luma.gl/docs/api-reference/webgl/query.md

Query

A Query object provides single unified API for using WebGL asynchronus queries, which include query objects ('Occlusion' and 'Transform Feedback') and timer queries. Query objects expose a promise member that tracks the state of the query and poll is used to update queries.

See also:

• WebGL1 timer extension: EXT_disjoint_timer_query
• WebGL2 timer extension: EXT_disjoint_timer_query_webgl2

Usage

Use a query to time GPU calls

import {pollContext, Query, GL} from 'luma.gl';
...
const timerQuery = new Query({
  onComplete: timestamp => console.log(timestamp)
  onError: error => console.warn(error)
});

// Option #1
timerQuery.beginTimeElapsedQuery();
// Option #2
// timerQuery.begin(GL.TIME_ELAPSED_EXT)

// Issue GPU calls

timerQuery.end();

// Poll for resolved queries
requestAnimationFrame(() => pollContext(gl))

Query Types

A query can be started by passing following query type to to begin() or by using corresponding begin* method.

Query Type	begin method	Description
GL_TIME_ELAPSED_EXT	beginTimeElapsedQuery()	Time taken by GPU to fully complete a set of GL commands
GL.ANY_SAMPLES_PASSED	beginOcclusionQuery({conservative: false})	Occlusion query: these queries detect whether an object is visible (whether the scoped drawing commands pass the depth test and if so, how many samples pass).
GL.ANY_SAMPLES_PASSED_CONSERVATIVE	beginOcclusionQuery({conservative: true})	Same as above above, but less accurate and faster version.
GL.TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN	beginTransformFeedbackQuery()	Number of primitives that are written to transform feedback buffers.

In addition to above queries, Query object also provides getTimeStamp which returns GPU time stamp at the time this query is executed by GPU. Two sets of these methods can be used to calculate time taken by GPU for a set of GL commands.

Methods

static Query.isSupported(gl, opts)

Returns true if Query is supported by the WebGL implementation (depends on the EXT_disjoint_timer_query extension)/ Can also check whether timestamp queries are available.

• gl {WebGLRenderingContext} - gl context
• opts= {Object} - options
• opts.queries=false {Object} - If true, checks if Query objects (occlusion/transform feedback) are supported
• opts.timers=false {Object} - If true, checks if 'TIME_ELAPSED_EXT' queries are supported
• opts.timestamps=false {Object} - If true, checks if 'TIMESTAMP_EXT' queries are supported
• return {Boolean} - Query API is supported with specified configuration

Options

• queries = false,
• timers = false,
• timestamps = false

constructor

new Query(gl, opts)

• gl {WebGLRenderingContext | WebGL2RenderingContext} - gl context
• opts {Object} opts - options
• opts.onComplete {Function} - called with a timestamp. Specifying this parameter causes a timestamp query to be initiated
• opts.onError {Function} opts.onComplete - called with a timestamp. Specifying this parameter causes a timestamp query to be initiated

delete

Destroys the WebGL object. Rejects any pending query.

• return {Query} - returns itself, to enable chaining of calls.

beginTimeElapsedQuery

Shortcut for timer query (dependent on extension in both WebGL1 and 2)

Query.beginOcclusionQuery({conservative = false})

Shortcut for occlusion query (dependent on WebGL2)

beginTransformFeedbackQuery

Shortcut for transform feedback query (dependent on WebGL2)

Query.begin(target)

Measures GPU time delta between this call and a matching end call in the GPU instruction stream.

Remarks:

• Due to OpenGL API limitations, after calling begin() on one Query instance, end() must be called on that same instance before calling begin() on another query. While there can be multiple outstanding queries representing disjoint begin()/end() intervals. It is not possible to interleave or overlap begin and end calls.

• Triggering a new query when a Query is already tracking an unresolved query causes that query to be cancelled.

• target {GLenum} - target to query

• return {Query} - returns itself, to enable chaining of calls.

end

Inserts a query end marker into the GPU instruction stream. Note: Can be called multiple times.

return {Query} - returns itself, to enable chaining of calls.

getTimestamp

Generates a GPU time stamp when the GPU instruction stream reaches this instruction. To measure time deltas, two timestamp queries are needed.

return {Query} - returns itself, to enable chaining of calls.

Remarks:

• timestamp() queries may not be available even when the timer query extension is. See Query.isSupported() flags.
• Triggering a new query when a Query is already tracking an unresolved query causes that query to be cancelled.

cancel

Cancels a pending query Note - Cancel's the promise and calls end on the current query if needed.

return {Query} - returns itself, to enable chaining of calls.

isResultAvailable

return {Boolean} - true if query result is available

getResult

Returns the query result, converted to milliseconds to match JavaScript conventions.

return {Number} - measured time or timestamp, in milliseconds

Remarks

• On Chrome, go to chrome:flags and enable "WebGL Draft Extensions"
• For full functionality, Query depends on a pollContext() function being called regularly. When this is done, completed queries will be automatically detected and any callbacks are called.
• Query instance creation will always succeed, even when the required extension is not supported. Instead any issued queries will fail immediately. This allows applications to unconditionally use TimerQueries without adding logic to check whether they are supported; the difference being that the onComplete callback never gets called, (the onError callback, if supplied, will be called instead).
• Even when supported, timer queries can fail whenever a change in the GPU occurs that will make the values returned by this extension unusable for performance metrics. Power conservation might cause the GPU to go to sleep at the lower levers. Query will detect this condition and fail any outstanding queries (which calls the onError function, if supplied).
• Note that from a JavaScript perspective, where callback driven APIs are the norm, the functionality of the WebGL Query class seems limited. Many operations that require expensive roundtrips to the GPU (such as readPixels) that would obviously benefit from asynchronous queries, are not covered by the Query class.