com.io7m.jcanephora.core.api

## Interface JCGLTimersType

-     public interface JCGLTimersType

  Interface to OpenGL timer queries.

  A timer query allows for retrieving the current time as it was when the query was executed on the GPU.

  In more practical terms: Because (almost) all OpenGL commands are executed asynchronously, it's not possible for the CPU to determine when a particular command has finished executing on the GPU. Therefore, it's not possible for the CPU to determine how long it took the GPU to execute one or more commands. A timer query essentially records the current time on the GPU when requested. This makes it possible to, for example, determine how long a set of OpenGL commands took to execute by starting a timer query `Q`, enqueueing a set of OpenGL commands `S`, and then finishing the timer query `Q`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `JCGLTimerQueryType` | `timerQueryAllocate()`
    `void` | `timerQueryBegin(JCGLTimerQueryUsableType q)` Start the timer query running.
    `void` | `timerQueryDelete(JCGLTimerQueryType q)` Delete the given timer query.
    `void` | `timerQueryFinish(JCGLTimerQueryUsableType q)` Stop the timer query running.
    `JCGLQueryResultAvailability` | `timerQueryResultAvailability(JCGLTimerQueryUsableType q)` Ask the GPU if the timer query has executed and therefore has a result that can be fetched.
    `long` | `timerQueryResultGet(JCGLTimerQueryUsableType q)` Retrieve the result for the timer query.

- - ### Method Detail

    - #### timerQueryAllocate

          JCGLTimerQueryType timerQueryAllocate()
                                         throws JCGLException

      Returns:
        A new timer query
      Throws:
        `JCGLException` - On errors

    - #### timerQueryBegin

          void timerQueryBegin(JCGLTimerQueryUsableType q)
                        throws JCGLException

      Start the timer query running.
      Parameters:
        `q` - The query
      Throws:
        `JCGLException` - On errors

    - #### timerQueryFinish

          void timerQueryFinish(JCGLTimerQueryUsableType q)
                         throws JCGLException

      Stop the timer query running.
      Parameters:
        `q` - The query
      Throws:
        `JCGLException` - On errors

    - #### timerQueryResultAvailability

          JCGLQueryResultAvailability timerQueryResultAvailability(JCGLTimerQueryUsableType q)
                                                            throws JCGLException

      Ask the GPU if the timer query has executed and therefore has a result that can be fetched.

      Note that this function necessarily implies a GPU/CPU sync, and therefore (for performance reasons) should ideally be called only after all other rendering commands have been submitted for execution (perhaps at the end of a frame).

      A query that has not yet been started with `timerQueryBegin(JCGLTimerQueryUsableType)` will yield `JCGLQueryResultAvailability.QUERY_RESULT_NOT_YET_REQUESTED`.

      A query that has been started with `timerQueryBegin(JCGLTimerQueryUsableType)` but that has not been executed by the GPU will yield `JCGLQueryResultAvailability.QUERY_RESULT_NOT_YET_AVAILABLE`.

      A query that has been fully executed by the GPU will yield `JCGLQueryResultAvailability.QUERY_RESULT_AVAILABLE`.

      Parameters:
        `q` - The query
      Returns:
        The availability of the result of the timer query
      Throws:
        `JCGLException` - On errors
      See Also:
        `timerQueryResultGet(JCGLTimerQueryUsableType)`

    - #### timerQueryResultGet

          long timerQueryResultGet(JCGLTimerQueryUsableType q)
                            throws JCGLException

      Retrieve the result for the timer query.

      The result for the query is the time elapsed on the GPU between the execution of the `timerQueryBegin(JCGLTimerQueryUsableType)` and `timerQueryFinish(JCGLTimerQueryUsableType)` commands.

      Parameters:
        `q` - The query
      Returns:
        The result of the timer query in nanoseconds
      Throws:
        `JCGLException` - On errors

    - #### timerQueryDelete

          void timerQueryDelete(JCGLTimerQueryType q)
                         throws JCGLException

      Delete the given timer query.
      Parameters:
        `q` - The timer query
      Throws:
        `JCGLException` - On errors

Copyright © 2016 <code@io7m.com> http://io7m.com