Skip to main content

QuerySet

A QuerySet stores asynchronous GPU query results.

For guidance on how this data is used for profiling in luma.gl, see Performance Profiling.

  • Use type: 'occlusion' to count samples that pass depth/stencil tests.
  • Use type: 'timestamp' to profile GPU work durations.

Timestamp queries are portable when device.features.has('timestamp-query') is true. On WebGL this is backed by EXT_disjoint_timer_query_webgl2.

Usage​

Create a timestamp query set:

const querySet = device.createQuerySet({type: 'timestamp', count: 2});

Record timestamps through the command stream:

device.commandEncoder.writeTimestamp(querySet, 0);
// encode GPU work here
device.commandEncoder.writeTimestamp(querySet, 1);
device.submit();

luma.gl can also apply timestamps automatically on render/compute passes when a pass does not already specify timestampQuerySet, beginTimestampIndex, or endTimestampIndex:

const querySet = device.createQuerySet({type: 'timestamp', count: 256});
const commandEncoder = device.createCommandEncoder({timeProfilingQuerySet: querySet});
commandEncoder.beginRenderPass({});
// ... encode passes ...
device.submit();

Read the duration asynchronously:

const milliseconds = await querySet.readTimestampDuration(0, 1);

You can also read all timestamps in one call:

const timestamps = await querySet.readResults();
  • RenderPass props: pass query sets through timestampQuerySet, beginTimestampIndex, endTimestampIndex, or occlusionQuerySet.
  • ComputePass props: pass timestampQuerySet, beginTimestampIndex, and endTimestampIndex.
  • Command encoding: use CommandEncoder.writeTimestamp() for manual timestamp capture.

Types​

QuerySetProps​

  • type: 'occlusion' | 'timestamp'
  • count: number

For timestamp duration profiling, use adjacent begin/end indices such as (0, 1) or (2, 3).

Methods​

isResultAvailable(queryIndex?: number): boolean​

Returns true when the requested result can be read without blocking. Backends may implement this conservatively.

readResults(options?: {firstQuery?: number; queryCount?: number}): Promise<bigint[]>​

Reads 64-bit query values asynchronously.

readTimestampDuration(beginIndex: number, endIndex: number): Promise<number>​

Reads a timestamp duration in milliseconds.

destroy()​

Destroys the underlying query resources.

Remarks​

  • QuerySet is a passive container. Record timestamps with CommandEncoder.writeTimestamp(), pass timestamp descriptors to render/compute passes, or let AnimationLoop inject pass-level profiling by constructing command encoders with timeProfilingQuerySet.
  • Query results are asynchronous and are typically not available in the same frame they are recorded.
  • On WebGL, timestamp results may be invalidated by disjoint timer events. Handle rejected reads when profiling long-running sessions.