@luma.gl/core 9.0.0-beta.4 → 9.0.0-beta.6

package/src/adapter/canvas-context.ts

@@ -1,4 +1,7 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {isBrowser} from '@probe.gl/env';
 import type {Device} from './device';
 import type {Framebuffer} from './resources/framebuffer';
@@ -120,7 +123,7 @@ export abstract class CanvasContext {
 
     // React to size changes
     if (this.canvas instanceof HTMLCanvasElement && props.autoResize) {
-      this.resizeObserver = new ResizeObserver((entries) => {
+      this.resizeObserver = new ResizeObserver(entries => {
         for (const entry of entries) {
           if (entry.target === this.canvas) {
             this.update();
@@ -145,7 +148,7 @@ export abstract class CanvasContext {
 
     useDevicePixels = useDevicePixels === undefined ? this.props.useDevicePixels : useDevicePixels;
 
-    if (!useDevicePixels || useDevicePixels as number <= 0) {
+    if (!useDevicePixels || (useDevicePixels as number) <= 0) {
       return 1;
     }
 
@@ -320,7 +323,7 @@ function getPageLoadPromise(): Promise<void> {
   if (isPageLoaded() || typeof window === 'undefined') {
     return Promise.resolve();
   }
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     window.addEventListener('load', () => resolve());
   });
 }
@@ -387,7 +390,7 @@ function scalePixels(
   height: number;
 } {
   const point = pixel as [number, number];
-  
+
   const x = scaleX(point[0], ratio, width);
   let y = scaleY(point[1], ratio, height, yInvert);
 

package/src/adapter/device.ts

@@ -1,4 +1,7 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {VERSION} from '../init';
 import {StatsManager, lumaStats} from '../utils/stats-manager';
 import {log} from '../utils/log';
@@ -19,40 +22,9 @@ 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';
 
-/** Device properties */
-export type DeviceProps = {
-  id?: string;
-
-  type?: 'webgl' | 'webgl1' | 'webgl2' | 'webgpu' | 'best-available';
-
-  // Common parameters
-  canvas?: HTMLCanvasElement | OffscreenCanvas | string | null; // A canvas element or a canvas string id
-  container?: HTMLElement | string | null;
-  width?: number /** width is only used when creating a new canvas */;
-  height?: number /** height is only used when creating a new canvas */;
-
-  // WebGLDevice parameters
-  webgl2?: boolean; // Set to false to not create a WebGL2 context (force webgl1)
-  webgl1?: boolean; // set to false to not create a WebGL1 context (fails if webgl2 not available)
-
-  // WebGLContext PARAMETERS - Can only be set on context creation...
-  // alpha?: boolean; // Default render target has an alpha buffer.
-  // depth?: boolean; // Default render target has a depth buffer of at least 16 bits.
-  // stencil?: boolean; // Default render target has a stencil buffer of at least 8 bits.
-  // antialias?: boolean; // Boolean that indicates whether or not to perform anti-aliasing.
-  // premultipliedAlpha?: boolean; // Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
-  // preserveDrawingBuffer?: boolean; // Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
-  // failIfMajorPerformanceCaveat?: boolean; // Do not create if the system performance is low.
-
-  // Unclear if these are still supported
-  debug?: boolean; // Instrument context (at the expense of performance)
-  manageState?: boolean; // Set to false to disable WebGL state management instrumentation
-  break?: string[]; // TODO: types
-
-  // @deprecated Attach to existing context
-  gl?: WebGLRenderingContext | WebGL2RenderingContext | null;
-};
+import {isTextureFormatCompressed} from './type-utils/decode-texture-format';
 
 /**
  * Identifies the GPU vendor and driver.
@@ -62,7 +34,7 @@ export type DeviceProps = {
  */
 export type DeviceInfo = {
   /** Type of device */
-  type: 'webgl' | 'webgl2' | 'webgpu';
+  type: 'webgl' | 'webgpu';
   /** Vendor (name of GPU vendor, Apple, nVidia etc */
   vendor: string;
   /** Renderer (usually driver name) */
@@ -81,132 +53,198 @@ export type DeviceInfo = {
   fallback?: boolean;
   /** Shader language supported by device.createShader() */
   shadingLanguage: 'wgsl' | 'glsl';
-  /** Highest supported shader language version (GLSL 3.00 = 300, GLSL 1.00 = 100) */
+  /** Highest supported shader language version: GLSL 3.00 = 300, WGSL 1.00 = 100 */
   shadingLanguageVersion: number;
 };
 
-/** Limits for a device */
-export type DeviceLimits = {
-  readonly maxTextureDimension1D?: number;
-  readonly maxTextureDimension2D?: number;
-  readonly maxTextureDimension3D?: number;
-  readonly maxTextureArrayLayers?: number;
-  readonly maxBindGroups: number;
-  readonly maxDynamicUniformBuffersPerPipelineLayout: number;
-  readonly maxDynamicStorageBuffersPerPipelineLayout: number;
-  readonly maxSampledTexturesPerShaderStage: number;
-  readonly maxSamplersPerShaderStage: number;
-  readonly maxStorageBuffersPerShaderStage: number;
-  readonly maxStorageTexturesPerShaderStage: number;
-  readonly maxUniformBuffersPerShaderStage: number;
-  readonly maxUniformBufferBindingSize: number;
-  readonly maxStorageBufferBindingSize?: number;
-  readonly minUniformBufferOffsetAlignment?: number;
-  readonly minStorageBufferOffsetAlignment?: number;
-  readonly maxVertexBuffers?: number;
-  readonly maxVertexAttributes: number;
-  readonly maxVertexBufferArrayStride?: number;
-  readonly maxInterStageShaderComponents?: number;
-  readonly maxComputeWorkgroupStorageSize?: number;
-  readonly maxComputeInvocationsPerWorkgroup?: number;
-  readonly maxComputeWorkgroupSizeX?: number;
-  readonly maxComputeWorkgroupSizeY?: number;
-  readonly maxComputeWorkgroupSizeZ?: number;
-  readonly maxComputeWorkgroupsPerDimension?: number;
-};
+/** Limits for a device (max supported sizes of resources, max number of bindings etc) */
+export abstract class DeviceLimits {
+  /** max number of TextureDimension1D */
+  abstract maxTextureDimension1D: number;
+  /** max number of TextureDimension2D */
+  abstract maxTextureDimension2D: number;
+  /** max number of TextureDimension3D */
+  abstract maxTextureDimension3D: number;
+  /** max number of TextureArrayLayers */
+  abstract maxTextureArrayLayers: number;
+  /** max number of BindGroups */
+  abstract maxBindGroups: number;
+  /** max number of DynamicUniformBuffers per PipelineLayout */
+  abstract maxDynamicUniformBuffersPerPipelineLayout: number;
+  /** max number of DynamicStorageBuffers per PipelineLayout */
+  abstract maxDynamicStorageBuffersPerPipelineLayout: number;
+  /** max number of SampledTextures per ShaderStage */
+  abstract maxSampledTexturesPerShaderStage: number;
+  /** max number of Samplers per ShaderStage */
+  abstract maxSamplersPerShaderStage: number;
+  /** max number of StorageBuffers per ShaderStage */
+  abstract maxStorageBuffersPerShaderStage: number;
+  /** max number of StorageTextures per ShaderStage */
+  abstract maxStorageTexturesPerShaderStage: number;
+  /** max number of UniformBuffers per ShaderStage */
+  abstract maxUniformBuffersPerShaderStage: number;
+  /** max number of UniformBufferBindingSize */
+  abstract maxUniformBufferBindingSize: number;
+  /** max number of StorageBufferBindingSize */
+  abstract maxStorageBufferBindingSize: number;
+  /** min UniformBufferOffsetAlignment */
+  abstract minUniformBufferOffsetAlignment: number;
+  /** min StorageBufferOffsetAlignment */
+  abstract minStorageBufferOffsetAlignment: number;
+  /** max number of VertexBuffers */
+  abstract maxVertexBuffers: number;
+  /** max number of VertexAttributes */
+  abstract maxVertexAttributes: number;
+  /** max number of VertexBufferArrayStride */
+  abstract maxVertexBufferArrayStride: number;
+  /** max number of InterStageShaderComponents */
+  abstract maxInterStageShaderComponents: number;
+  /** max number of ComputeWorkgroupStorageSize */
+  abstract maxComputeWorkgroupStorageSize: number;
+  /** max number of ComputeInvocations per Workgroup */
+  abstract maxComputeInvocationsPerWorkgroup: number;
+  /** max ComputeWorkgroupSizeX */
+  abstract maxComputeWorkgroupSizeX: number;
+  /** max ComputeWorkgroupSizeY */
+  abstract maxComputeWorkgroupSizeY: number;
+  /** max ComputeWorkgroupSizeZ */
+  abstract maxComputeWorkgroupSizeZ: number;
+  /** max ComputeWorkgroupsPerDimension */
+  abstract maxComputeWorkgroupsPerDimension: number;
+}
+
+/** Set-like class for features (lets apps check for WebGL / WebGPU extensions) */
+export class DeviceFeatures {
+  protected features: Set<DeviceFeature>;
+
+  constructor(features: DeviceFeature[] = []) {
+    this.features = new Set<DeviceFeature>(features);
+  }
+
+  *[Symbol.iterator](): IterableIterator<DeviceFeature> {
+    yield* this.features;
+  }
+
+  has(feature: DeviceFeature): boolean {
+    return this.features.has(feature);
+  }
+}
+
+/** Device feature names */
+export type DeviceFeature =
+  | WebGPUDeviceFeature
+  | WebGLDeviceFeature
+  | WebGLCompressedTextureFeatures;
 
 export type WebGPUDeviceFeature =
   | 'depth-clip-control'
+  | 'indirect-first-instance'
+  | 'timestamp-query'
+  | 'shader-f16'
   | 'depth24unorm-stencil8'
   | 'depth32float-stencil8'
-  | 'timestamp-query'
-  | 'indirect-first-instance'
+  | 'rg11b10ufloat-renderable' // Is the rg11b10ufloat texture format renderable?
+  | 'float32-filterable' // Is the float32 format filterable?
+  | 'bgra8unorm-storage' // Can the bgra8unorm texture format be used in storage buffers?
   | 'texture-compression-bc'
   | 'texture-compression-etc2'
   | 'texture-compression-astc';
-
-// obsolete...
-// 'depth-clamping' |
-// 'depth24unorm-stencil8' |
-// 'depth32float-stencil8' |
-// 'pipeline-statistics-query' |
-// 'timestamp-query' |
-// 'texture-compression-bc'
+// | 'depth-clamping' // removed from the WebGPU spec...
+// | 'pipeline-statistics-query' // removed from the WebGPU spec...
 
 export type WebGLDeviceFeature =
-  | 'webgpu'
-  | 'webgl2'
-  | 'webgl'
+  // webgl extension features
+  | 'timer-query-webgl' // unify with WebGPU timestamp-query?
+  | 'compilation-status-async-webgl' // Non-blocking shader compile/link status query available
+  | 'provoking-vertex-webgl' // parameters.provokingVertex
+  | 'polygon-mode-webgl' // parameters.polygonMode and parameters.polygonOffsetLine
 
-  // api support (unify with WebGPU timestamp-query?)
-  | 'timer-query-webgl'
-  | 'uniform-buffers-webgl'
-  | 'uniforms-webgl'
+  // GLSL extension features
+  | 'shader-noperspective-interpolation-webgl' // Vertex outputs & fragment inputs can have a `noperspective` interpolation qualifier.
+  | 'shader-conservative-depth-webgl' // GLSL `gl_FragDepth` qualifiers `depth_unchanged` etc can enable early depth test
+  | 'shader-clip-cull-distance-webgl' // Makes gl_ClipDistance and gl_CullDistance available in shaders
+
+  // texture rendering
+  | 'float32-renderable-webgl'
+  | 'float16-renderable-webgl'
+  | 'rgb9e5ufloat_renderable-webgl'
+  | 'snorm8-renderable-webgl'
+  | 'norm16-renderable-webgl'
+  | 'snorm16-renderable-webgl'
 
   // texture filtering
-  | 'texture-filter-linear-float32-webgl'
-  | 'texture-filter-linear-float16-webgl'
-  | 'texture-filter-anisotropic-webgl'
+  | 'float16-filterable-webgl'
+  | 'texture-filterable-anisotropic-webgl'
 
-  // texture rendering
-  | 'texture-renderable-float32-webgl'
-  | 'texture-renderable-float16-webgl'
-  | 'texture-renderable-rgba32float-webgl' // TODO - remove
+  // texture storage bindings
+  | 'bgra8unorm-storage'
 
   // texture blending
-  | 'texture-blend-float-webgl1'
-
-  // texture format support
-  | 'texture-formats-norm16-webgl'
-  | 'texture-formats-srgb-webgl1'
-  | 'texture-formats-depth-webgl1'
-  | 'texture-formats-float32-webgl1'
-  | 'texture-formats-float16-webgl1'
-
-  // api support
-  | 'vertex-array-object-webgl1'
-  | 'instanced-rendering-webgl1'
-  | 'multiple-render-targets-webgl1'
-  | 'index-uint32-webgl1'
-  | 'blend-minmax-webgl1'
-  | 'transform-feedback-webgl2'
-
-  // glsl extensions
-  | 'glsl-frag-data'
-  | 'glsl-frag-depth'
-  | 'glsl-derivatives'
-  | 'glsl-texture-lod';
+  | 'texture-blend-float-webgl';
 
 type WebGLCompressedTextureFeatures =
   | 'texture-compression-bc5-webgl'
+  | 'texture-compression-bc7-webgl'
   | 'texture-compression-etc1-webgl'
   | 'texture-compression-pvrtc-webgl'
   | 'texture-compression-atc-webgl';
 
-/** Valid feature strings */
-export type DeviceFeature =
-  | WebGPUDeviceFeature
-  | WebGLDeviceFeature
-  | WebGLCompressedTextureFeatures;
+/** Device properties */
+export type DeviceProps = {
+  id?: string;
+
+  type?: 'webgl' | 'webgpu' | 'best-available';
+
+  // Common parameters
+  canvas?: HTMLCanvasElement | OffscreenCanvas | string | null; // A canvas element or a canvas string id
+  container?: HTMLElement | string | null;
+  width?: number /** width is only used when creating a new canvas */;
+  height?: number /** height is only used when creating a new canvas */;
+
+  /** Request a Device with the highest limits supported by platform. */
+  requestMaximalLimits?: boolean;
+
+  // WebGLContext PARAMETERS - Can only be set on context creation...
+  // alpha?: boolean; // Default render target has an alpha buffer.
+  // depth?: boolean; // Default render target has a depth buffer of at least 16 bits.
+  // stencil?: boolean; // Default render target has a stencil buffer of at least 8 bits.
+  // antialias?: boolean; // Boolean that indicates whether or not to perform anti-aliasing.
+  // premultipliedAlpha?: boolean; // Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
+  // preserveDrawingBuffer?: boolean; // Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
+  // failIfMajorPerformanceCaveat?: boolean; // Do not create if the system performance is low.
+
+  onError?: (error: Error) => unknown;
+  /** Instrument context (at the expense of performance) */
+  debug?: boolean;
+  /** Initialize the SpectorJS WebGL debugger */
+  spector?: boolean;
+
+  // Unclear if these are still supported
+  manageState?: boolean; // Set to false to disable WebGL state management instrumentation
+  break?: string[]; // TODO: types
+
+  // @deprecated Attach to existing context
+  gl?: WebGL2RenderingContext | null;
+};
 
 /**
  * WebGPU Device/WebGL context abstraction
  */
 export abstract class Device {
-
   static defaultProps: Required<DeviceProps> = {
     id: null!,
     type: 'best-available',
     canvas: null,
     container: null,
-    webgl2: true, // Attempt to create a WebGL2 context
-    webgl1: true, // Attempt to create a WebGL1 context (false to fail if webgl2 not available)
     manageState: true,
     width: 800, // width are height are only used by headless gl
     height: 600,
+
+    requestMaximalLimits: true,
     debug: Boolean(log.get('debug')), // Instrument context (at the expense of performance)
+    spector: Boolean(log.get('spector')), // Initialize the SpectorJS WebGL debugger
     break: [],
-  
+
     // alpha: undefined,
     // depth: undefined,
     // stencil: undefined,
@@ -214,10 +252,12 @@ export abstract class Device {
     // premultipliedAlpha: undefined,
     // preserveDrawingBuffer: undefined,
     // failIfMajorPerformanceCaveat: undefined
-  
-    gl: null
+
+    gl: null,
+
+    // Callbacks
+    onError: (error: Error) => log.error(error.message)
   };
-  
 
   get [Symbol.toStringTag](): string {
     return 'Device';
@@ -249,7 +289,7 @@ export abstract class Device {
   abstract info: DeviceInfo;
 
   /** Optional capability discovery */
-  abstract get features(): Set<DeviceFeature>;
+  abstract features: DeviceFeatures;
 
   /** WebGPU style device limits */
   abstract get limits(): DeviceLimits;
@@ -263,6 +303,11 @@ export abstract class Device {
   /** Check if device supports rendering to a specific texture format */
   abstract isTextureFormatRenderable(format: TextureFormat): boolean;
 
+  /** Check if a specific texture format is GPU compressed */
+  isTextureFormatCompressed(format: TextureFormat): boolean {
+    return isTextureFormatCompressed(format);
+  }
+
   // Device loss
 
   /** `true` if device is already lost */
@@ -348,9 +393,11 @@ export abstract class Device {
   /** Get a renderpass that is set up to render to the primary CanvasContext */
   abstract getDefaultRenderPass(): RenderPass;
 
-  /** Create a transform feedback (immutable set of output buffer bindings). WebGL 2 only. */
+  /** 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');
   }
@@ -375,7 +422,7 @@ export abstract class Device {
   ): Uint8Array | Uint16Array | Float32Array {
     throw new Error('not implemented');
   }
-  
+
   /** @deprecated - will be removed - should use command encoder */
   readPixelsToBufferWebGL(
     source: Framebuffer | Texture,
@@ -414,7 +461,14 @@ export abstract class Device {
     throw new Error('not implemented');
   }
 
-  // Implementation
+  // IMPLEMENTATION
+
+  // Error Handling
+
+  /** Report unhandled device errors */
+  onError(error: Error) {
+    this.props.onError(error);
+  }
 
   protected _getBufferProps(props: BufferProps | ArrayBuffer | ArrayBufferView): BufferProps {
     if (props instanceof ArrayBuffer || ArrayBuffer.isView(props)) {

package/src/adapter/resources/buffer.ts

@@ -1,4 +1,6 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 
 import type {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
@@ -19,7 +21,7 @@ export type BufferProps = ResourceProps & {
 
   // TBD
   mappedAtCreation?: boolean;
-}
+};
 
 /** Abstract GPU buffer */
 export abstract class Buffer extends Resource<BufferProps> {
@@ -49,7 +51,9 @@ export abstract class Buffer extends Resource<BufferProps> {
   static INDIRECT = 0x0100;
   static QUERY_RESOLVE = 0x0200;
 
-  override get [Symbol.toStringTag](): string { return 'Buffer'; }
+  override get [Symbol.toStringTag](): string {
+    return 'Buffer';
+  }
 
   /** The usage with which this buffer was created */
   readonly usage: number;
@@ -82,7 +86,9 @@ export abstract class Buffer extends Resource<BufferProps> {
   abstract readAsync(byteOffset?: number, byteLength?: number): Promise<Uint8Array>;
 
   /** Read data synchronously. @note WebGL2 only */
-  readSyncWebGL2(byteOffset?: number, byteLength?: number): Uint8Array  { throw new Error('not implemented'); }
+  readSyncWebGL(byteOffset?: number, byteLength?: number): Uint8Array {
+    throw new Error('not implemented');
+  }
 
   // PROTECTED METHODS (INTENDED FOR USE BY OTHER FRAMEWORK CODE ONLY)
 
@@ -92,9 +98,16 @@ export abstract class Buffer extends Resource<BufferProps> {
   debugData: ArrayBuffer = new ArrayBuffer(0);
 
   /** This doesn't handle partial non-zero offset updates correctly */
-  protected _setDebugData(data: ArrayBufferView | ArrayBuffer | null, byteOffset: number, byteLength: number): void {
+  protected _setDebugData(
+    data: ArrayBufferView | ArrayBuffer | null,
+    byteOffset: number,
+    byteLength: number
+  ): void {
     const buffer: ArrayBuffer | null = ArrayBuffer.isView(data) ? data.buffer : data;
-    const debugDataLength = Math.min(data ? data.byteLength : byteLength, Buffer.DEBUG_DATA_MAX_LENGTH);
+    const debugDataLength = Math.min(
+      data ? data.byteLength : byteLength,
+      Buffer.DEBUG_DATA_MAX_LENGTH
+    );
     if (data === null) {
       this.debugData = new ArrayBuffer(debugDataLength);
     } else if (byteOffset === 0 && byteLength === data.byteLength) {

package/src/adapter/resources/command-buffer.ts

@@ -1,5 +1,8 @@
-// luma.gl, MIT license
-import { Device } from '../device';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
 
 // interface Queue {
@@ -17,8 +20,7 @@ import {Resource, ResourceProps} from './resource';
 //   // ): void;
 // }
 
-export type CommandBufferProps = ResourceProps & {
-};
+export type CommandBufferProps = ResourceProps & {};
 
 /**
  * Encodes commands to queue that can be executed later
@@ -27,7 +29,7 @@ export abstract class CommandBuffer extends Resource<CommandBufferProps> {
   static override defaultProps: Required<CommandBufferProps> = {
     ...Resource.defaultProps
   };
-  
+
   override get [Symbol.toStringTag](): string {
     return 'CommandBuffer';
   }

package/src/adapter/resources/command-encoder.ts

@@ -1,15 +1,19 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
 import {Buffer} from './buffer';
 import {Texture} from './texture';
+import {QuerySet} from './query-set';
 
 export type WriteBufferOptions = {
-  buffer: Buffer,
-  bufferOffset?: number,
-  data: BufferSource,
-  dataOffset?: number,
-  size?: number
+  buffer: Buffer;
+  bufferOffset?: number;
+  data: BufferSource;
+  dataOffset?: number;
+  size?: number;
 };
 
 export type WriteTextureOptions = {
@@ -23,7 +27,7 @@ export type WriteTextureOptions = {
   bytesPerRow: number;
   rowsPerImage: number;
   size: [number, number, number] | number[];
-}
+};
 
 export type CopyBufferToBufferOptions = {
   source: Buffer;
@@ -37,7 +41,7 @@ export type CopyBufferToTextureOptions = {
   source: Buffer;
   byteOffset?: number;
   destination: Texture;
-  mipLevel?: number //  = 0;
+  mipLevel?: number; //  = 0;
   origin?: [number, number, number] | number[];
   aspect?: 'all' | 'stencil-only' | 'depth-only';
   bytesPerRow: number;
@@ -131,7 +135,7 @@ export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
     ...Resource.defaultProps,
     measureExecutionTime: undefined
   };
-  
+
   override get [Symbol.toStringTag](): string {
     return 'CommandEncoder';
   }
@@ -139,34 +143,41 @@ export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
   constructor(device: Device, props: CommandEncoderProps) {
     super(device, props, CommandEncoder.defaultProps);
   }
-  
-  abstract finish(): void; // TODO - return the CommandBuffer?
 
-  // beginRenderPass(GPURenderPassDescriptor descriptor): GPURenderPassEncoder;
-  // beginComputePass(optional GPUComputePassDescriptor descriptor = {}): GPUComputePassEncoder;
-  // finish(options?: {id?: string}): GPUCommandBuffer;
+  /** Completes recording of the commands sequence */
+  abstract finish(): void; // TODO - return the CommandBuffer?
 
+  /** Add a command that that copies data from a sub-region of a Buffer to a sub-region of another Buffer. */
   abstract copyBufferToBuffer(options: CopyBufferToBufferOptions): void;
 
+  /** Add a command that copies data from a sub-region of a GPUBuffer to a sub-region of one or multiple continuous texture subresources. */
   abstract copyBufferToTexture(options: CopyBufferToTextureOptions): void;
 
+  /** Add a command that copies data from a sub-region of one or multiple continuous texture subresources to a sub-region of a Buffer. */
   abstract copyTextureToBuffer(options: CopyTextureToBufferOptions): void;
 
+  /** Add a command that copies data from a sub-region of one or multiple contiguous texture subresources to another sub-region of one or multiple continuous texture subresources. */
   abstract copyTextureToTexture(options: CopyTextureToTextureOptions): void;
 
-  pushDebugGroup(groupLabel: string): void {}
-
-  popDebugGroup() {}
-
-  insertDebugMarker(markerLabel: string): void {}
-
-  // writeTimestamp(querySet: Query, queryIndex: number): void;
-
-  // resolveQuerySet(options: {
-  //   querySet: GPUQuerySet,
-  //   firstQuery: number,
-  //   queryCount: number,
-  //   destination: Buffer,
-  //   destinationOffset?: number;
-  // }): void;
+  /** Reads results from a query set into a GPU buffer. Values are 64 bits so byteLength must be querySet.props.count * 8 */
+  abstract resolveQuerySet(
+    querySet: QuerySet,
+    destination: Buffer,
+    options?: {
+      firstQuery?: number;
+      queryCount?: number;
+      destinationOffset?: number;
+    }
+  ): void;
+
+  /** Begins a labeled debug group containing subsequent commands */
+  abstract pushDebugGroup(groupLabel: string): void;
+  /** Ends the labeled debug group most recently started by pushDebugGroup() */
+  abstract popDebugGroup(): void;
+  /** Marks a point in a stream of commands with a label */
+  abstract insertDebugMarker(markerLabel: string): void;
+
+  // TODO - luma.gl has these on the device, should we align with WebGPU API?
+  // beginRenderPass(GPURenderPassDescriptor descriptor): GPURenderPassEncoder;
+  // beginComputePass(optional GPUComputePassDescriptor descriptor = {}): GPUComputePassEncoder;
 }