feat: Add QuerySet resource

.eslintrc.cjs

@@ -38,6 +38,9 @@ module.exports = getESLintConfig({
       {
         files: ['**/*.ts', '**/*.tsx', '**/*.d.ts'],
         rules: {
+          'quotes': 0, // handled by prettier
+          'indent': 0, // handled by prettier
+
           // typescript-eslint 6.0
           '@typescript-eslint/no-unsafe-argument': 0,
           '@typescript-eslint/no-redundant-type-constituents': 0,
@@ -163,7 +166,8 @@ module.exports = getESLintConfig({
           "GPUTextureFormat": true,
           "GPUBufferUsage": true,
           "GPUVertexFormat": true,
-          "GPURenderPassDescriptor": true
+          "GPURenderPassDescriptor": true,
+          "GPUComputePassTimestampWrites": true
         }
       }
     ],

docs/api-reference/core/resources/query-set.md

@@ -0,0 +1,81 @@
+# QuerySet
+
+:::caution
+This page is incomplete.
+:::
+
+A `QuerySet` object provides an API for using asynchronous GPU queries of the following types
+- timer queries.
+- 'Occlusion' 
+- 'Transform Feedback'
+
+A `QuerySet` holds a number of 64 bit values. 
+
+Timer queries are available if the `timestamp-query` extension is available. (On WebGL 2 this is equivalent to the 
+[`EXT_disjoint_timer_query_webgl2`](https://www.khronos.org/registry/webgl/extensions/EXT_disjoint_timer_query_webgl2/)
+being supported on the current browser.
+
+Note that 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, for example if the GPU is throttled mid-frame. 
+
+## Usage
+
+Create a timestamp query set:
+
+```typescript
+import {QuerySet} from '@luma.gl/core';
+...
+const timestampQuery = device.createQuerySet({type: 'timestamp'}});
+```
+
+## Types
+
+### `QueryProps`
+
+- `type`: `occlusion` | `timestamp` - type of timer
+- `count`: `number` - number of query results held by this `QuerySet`
+
+| Query Type                               | Usage                                        | Description                                                                |
+| ---------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
+| `timestamp` (`RenderPass begin/end`)     | `beginRenderPass({timestampQuery: ...})`     | Time taken by GPU to execute RenderPass commands                           |
+| `timestamp`  (`ComputePass begin/end`)   | `beginComputePass({timestampQuery: ...})`    | Time taken by GPU to execute ComputePass commands                          |
+| `occlusion`                              | `beginOcclusionQuery({conservative: false})` | Occlusion query how many fragment samples pass tests (depth, stencil, ...) |
+| `occlusion`                              | `beginOcclusionQuery({conservative: true})`  | Same as above above, but less accurate and faster                          | 
+| `transform-feedback` (Not yet supported) | `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.
+
+## DeviceFeatures
+
+`timestamp-query`: Whether `QuerySet` can be created with type `timestamp`.
+
+## Methods
+
+
+
+### `constructor(device: Device, props: Object)`
+
+`new Query(gl, {})`
+- options.timers=false Object - If true, checks if 'TIME_ELAPSED_EXT' queries are supported
+
+### `destroy()`
+
+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 WebGL 1 and 2)
+
+## RenderPass
+
+
+### `RenderPass.beginOcclusionQuery({conservative = false})`
+
+Shortcut for occlusion query (dependent on WebGL 2)
+
+### `RenderPass.beginTransformFeedbackQuery()`
+
+WebGL 2 only. not yet implemented.
+

docs/developer-guide/profiling.md

@@ -1,7 +1,7 @@
 # Profiling
 
 GPU programming is all about performance, so having tools to systematically
-measure the performance impact of code changes are critical. luma.gl offers
+measure the performance impact of code changes is critical. luma.gl offers
 several built-in facilities.
 
 ## probe.gl Stats
@@ -31,4 +31,12 @@ however tracking allocations can help spot resource leaks or unnecessary work be
 
 ## Performance Profiling
 
-Queries are supported if available.
+`device.createQuerySet()` can be used to create GPU queries that 
+
+- Occlusion Queries always supported.
+- Timestamp Queries are supported if the `timestamp-query` feature is available, check with `device.features.has('timestamp-query')`.
+
+`QuerySet` instances can be supplied when creating `RenderPass` and `ComputePass` instances.
+
+Results are available through
+`commandEncoder.resolveQuerySet()`

docs/sidebar.json

@@ -94,7 +94,8 @@
           "api-reference/core/resources/shader",
           "api-reference/core/shader-logs",
           "api-reference/core/resources/texture",
-          "api-reference/core/resources/vertex-array"
+          "api-reference/core/resources/vertex-array",
+          "api-reference/core/resources/query-set"
         ]
       },
       {

modules/core-tests/test/adapter/helpers/parse-shader-compiler-log.spec.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+/* eslint-disable quotes */
+
 import test from 'tape-promise/tape';
 import {parseShaderCompilerLog} from '@luma.gl/webgl/adapter/helpers/parse-shader-compiler-log';
 

modules/core-tests/test/adapter/resources/framebuffer.spec.ts

@@ -1,3 +1,7 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 /* eslint-disable max-len */
 import test from 'tape-promise/tape';
 import {Framebuffer} from '@luma.gl/core';

wip/modules-wip/webgl-legacy/test/classic/query.spec.ts → modules/core-tests/test/adapter/resources/query-set.spec.ts

@@ -1,18 +1,23 @@
-/* eslint-disable max-len, max-statements */
-import test from 'tape-promise/tape';
-import {Query} from '@luma.gl/webgl-legacy';
-// import util from 'util';
-import {GL} from '@luma.gl/constants';
-import {fixture} from 'test/setup';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 
-function pollQuery(query, t) {
-  return query
-    .createPoll(10)
-    .then((result) => t.pass(`Timer query: ${result}ms`))
-    .catch((error) => t.fail(`Timer query: ${error}`));
-}
+import test from 'tape-promise/tape';
+import {getTestDevices} from '@luma.gl/test-utils';
+import {QuerySet} from '@luma.gl/core';
+
+test('QuerySet construct/delete', async t => {
+  for (const device of await getTestDevices()) {
+    const querySet = device.createQuerySet({type: 'occlusion', count: 1});
+    t.ok(querySet instanceof QuerySet, 'QuerySet construction successful');
+    querySet.destroy();
+    t.pass('QuerySet delete successful');
+  }
+  t.end();
+});
 
-function testQueryConstructDelete(gl, t) {
+/*
+test('Query construct/delete', (t) => {
   const ext = gl.getExtension('EXT_disjoint_timer_query');
   t.comment(`EXT_disjoint_timer_query is ${Boolean(ext)} ${ext}`, ext);
   // util.inspect(ext, {showHidden: true});
@@ -24,8 +29,6 @@ function testQueryConstructDelete(gl, t) {
     t.comment('Query is not supported, testing graceful fallback');
   }
 
-  // @ts-expect-error
-  t.throws(() => new Query(), /.*WebGLRenderingContext.*/, 'Query throws on missing gl context');
 
   const timerQuery = new Query(gl);
   t.ok(timerQuery, 'Query construction successful');
@@ -39,23 +42,10 @@ function testQueryConstructDelete(gl, t) {
   t.end();
 }
 
-test('WebGL#Query construct/delete', (t) => {
-  const {gl} = fixture;
-
-  testQueryConstructDelete(gl, t);
-});
-
-test('WebGL2#Query construct/delete', (t) => {
-  const {gl2} = fixture;
-  if (!gl2) {
-    t.comment('WebGL2 not available, skipping tests');
-    t.end();
-    return;
-  }
-  testQueryConstructDelete(gl2, t);
-});
-
 function testQueryCompleteFail(gl, t) {
+}
+
+test('Query completed/failed queries', (t) => {
   if (!Query.isSupported(gl, ['timers'])) {
     t.comment('Query Timer API not supported, skipping tests');
     return null;
@@ -66,26 +56,17 @@ function testQueryCompleteFail(gl, t) {
   timerQuery.beginTimeElapsedQuery().end();
 
   return pollQuery(timerQuery, t);
-}
-
-test('WebGL#Query completed/failed queries', (t) => {
-  const {gl} = fixture;
-  testQueryCompleteFail(gl, t);
   t.end();
 });
 
-test('WebGL2#Query completed/failed queries', (t) => {
+test('TimeElapsedQuery', (t) => {
   const {gl2} = fixture;
   if (!gl2) {
     t.comment('WebGL2 not available, skipping tests');
     t.end();
     return;
   }
-  testQueryCompleteFail(gl2, t);
-  t.end();
-});
-
-function testQuery(gl, opts, target, t) {
+  const opts = ['timers'];
   if (!Query.isSupported(gl, opts)) {
     t.comment('Query API not supported, skipping tests');
     return null;
@@ -94,35 +75,10 @@ function testQuery(gl, opts, target, t) {
   query.begin(target).end();
 
   return pollQuery(query, t);
-}
-
-test('WebGL#TimeElapsedQuery', (t) => {
-  const {gl} = fixture;
-  const opts = ['timers'];
-  testQuery(gl, opts, GL.TIME_ELAPSED_EXT, t);
   t.end();
 });
 
-test('WebGL2#TimeElapsedQuery', (t) => {
-  const {gl2} = fixture;
-  if (!gl2) {
-    t.comment('WebGL2 not available, skipping tests');
-    t.end();
-    return;
-  }
-  const opts = ['timers'];
-  testQuery(gl2, opts, GL.TIME_ELAPSED_EXT, t);
-  t.end();
-});
-
-test('WebGL#OcclusionQuery', (t) => {
-  const {gl} = fixture;
-  const opts = ['queries'];
-  testQuery(gl, opts, GL.ANY_SAMPLES_PASSED_CONSERVATIVE, t);
-  t.end();
-});
-
-test('WebGL2#OcclusionQuery', (t) => {
+test('OcclusionQuery', (t) => {
   const {gl2} = fixture;
   if (!gl2) {
     t.comment('WebGL2 not available, skipping tests');
@@ -141,7 +97,7 @@ test('WebGL#TransformFeedbackQuery', (t) => {
   t.end();
 });
 
-test('WebGL2#TransformFeedbackQuery', (t) => {
+test('TransformFeedbackQuery', (t) => {
   const {gl2} = fixture;
   if (!gl2) {
     t.comment('WebGL2 not available, skipping tests');
@@ -152,3 +108,11 @@ test('WebGL2#TransformFeedbackQuery', (t) => {
   testQuery(gl2, opts, GL.TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, t);
   t.end();
 });
+
+function pollQuery(query, t) {
+  return query
+    .createPoll(10)
+    .then((result) => t.pass(`Timer query: ${result}ms`))
+    .catch((error) => t.fail(`Timer query: ${error}`));
+}
+*/

modules/core-tests/test/index.ts

@@ -2,12 +2,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// Note that we do two test runs on luma.gl, with and without headless-gl
-// This file imports tests that should run *with* headless-gl included
-
-// import './adapter/helpers/parse-shader-compiler-log.spec';
-// import './adapter/helpers/get-shader-layout.spec';
-
 // ADAPTER
 
 // WebGLDevice, features & limits
@@ -16,8 +10,11 @@ import './adapter/device-helpers/device-features.spec';
 import './adapter/device-helpers/device-limits.spec';
 import './adapter/device-helpers/set-device-parameters.spec';
 
-// import './adapter/webgl-device.spec';
-// import './adapter/webgl-canvas-context.spec';
+import './adapter/helpers/parse-shader-compiler-log.spec';
+// import './adapter/helpers/get-shader-layout.spec';
+
+import './adapter/device.spec';
+import './adapter/canvas-context.spec';
 
 // Resources
 import './adapter/texture-formats.spec';
@@ -30,4 +27,5 @@ import './adapter/resources/render-pipeline.spec';
 import './adapter/resources/shader.spec';
 import './adapter/resources/sampler.spec';
 import './adapter/resources/texture.spec';
-// import './adapter/resources/vertex-array.spec';
+import './adapter/resources/vertex-array.spec';
+import './adapter/resources/query-set.spec';

modules/core/src/adapter/device.ts

@@ -22,6 +22,7 @@ import type {ComputePass, ComputePassProps} from './resources/compute-pass';
 import type {CommandEncoder, CommandEncoderProps} from './resources/command-encoder';
 import type {VertexArray, VertexArrayProps} from './resources/vertex-array';
 import type {TransformFeedback, TransformFeedbackProps} from './resources/transform-feedback';
+import type {QuerySet, QuerySetProps} from './resources/query-set';
 
 import {isTextureFormatCompressed} from './type-utils/decode-texture-format';
 
@@ -395,6 +396,8 @@ export abstract class Device {
   /** Create a transform feedback (immutable set of output buffer bindings). WebGL only. */
   abstract createTransformFeedback(props: TransformFeedbackProps): TransformFeedback;
 
+  abstract createQuerySet(props: QuerySetProps): QuerySet;
+
   createCommandEncoder(props: CommandEncoderProps = {}): CommandEncoder {
     throw new Error('not implemented');
   }