@luma.gl/core 9.2.5 → 9.3.0-alpha.10

package/src/adapter/device.ts

@@ -5,12 +5,18 @@
 import {StatsManager, lumaStats} from '../utils/stats-manager';
 import {log} from '../utils/log';
 import {uid} from '../utils/uid';
-import type {VertexFormat, VertexFormatInfo} from '../shadertypes/vertex-arrays/vertex-formats';
-import type {TextureFormat, TextureFormatInfo} from '../shadertypes/textures/texture-formats';
+import type {VertexFormat, VertexFormatInfo} from '../shadertypes/vertex-types/vertex-formats';
+import type {
+  TextureFormat,
+  TextureFormatInfo,
+  CompressedTextureFormat
+} from '../shadertypes/texture-types/texture-formats';
 import type {CanvasContext, CanvasContextProps} from './canvas-context';
+import type {PresentationContext, PresentationContextProps} from './presentation-context';
 import type {BufferProps} from './resources/buffer';
 import {Buffer} from './resources/buffer';
 import type {RenderPipeline, RenderPipelineProps} from './resources/render-pipeline';
+import type {SharedRenderPipeline} from './resources/shared-render-pipeline';
 import type {ComputePipeline, ComputePipelineProps} from './resources/compute-pipeline';
 import type {Sampler, SamplerProps} from './resources/sampler';
 import type {Shader, ShaderProps} from './resources/shader';
@@ -24,11 +30,14 @@ import type {CommandBuffer} from './resources/command-buffer';
 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 type {Fence} from './resources/fence';
+import type {Bindings, ComputeShaderLayout, ShaderLayout} from './types/shader-layout';
 
-import {getVertexFormatInfo} from '../shadertypes/vertex-arrays/decode-vertex-format';
-import {textureFormatDecoder} from '../shadertypes/textures/texture-format-decoder';
-import type {ExternalImage} from '../image-utils/image-types';
-import {isExternalImage, getExternalImageSize} from '../image-utils/image-types';
+import {vertexFormatDecoder} from '../shadertypes/vertex-types/vertex-format-decoder';
+import {textureFormatDecoder} from '../shadertypes/texture-types/texture-format-decoder';
+import type {ExternalImage} from '../shadertypes/image-types/image-types';
+import {isExternalImage, getExternalImageSize} from '../shadertypes/image-types/image-types';
+import {getTextureFormatTable} from '../shadertypes/texture-types/texture-format-table';
 
 /**
  * Identifies the GPU vendor and driver.
@@ -117,6 +126,84 @@ export abstract class DeviceLimits {
   abstract maxComputeWorkgroupsPerDimension: number;
 }
 
+function formatErrorLogArguments(context: unknown, args: unknown[]): unknown[] {
+  const formattedContext = formatErrorLogValue(context);
+  const formattedArgs = args.map(formatErrorLogValue).filter(arg => arg !== undefined);
+  return [formattedContext, ...formattedArgs].filter(arg => arg !== undefined);
+}
+
+function formatErrorLogValue(value: unknown): unknown {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (value instanceof Error) {
+    return value.message;
+  }
+  if (Array.isArray(value)) {
+    return value.map(formatErrorLogValue);
+  }
+  if (typeof value === 'object') {
+    if (hasCustomToString(value)) {
+      const stringValue = String(value);
+      if (stringValue !== '[object Object]') {
+        return stringValue;
+      }
+    }
+
+    if (looksLikeGPUCompilationMessage(value)) {
+      return formatGPUCompilationMessage(value);
+    }
+
+    return value.constructor?.name || 'Object';
+  }
+
+  return String(value);
+}
+
+function hasCustomToString(value: object): boolean {
+  return (
+    'toString' in value &&
+    typeof value.toString === 'function' &&
+    value.toString !== Object.prototype.toString
+  );
+}
+
+function looksLikeGPUCompilationMessage(value: object): value is {
+  message?: unknown;
+  type?: unknown;
+  lineNum?: unknown;
+  linePos?: unknown;
+} {
+  return 'message' in value && 'type' in value;
+}
+
+function formatGPUCompilationMessage(value: {
+  message?: unknown;
+  type?: unknown;
+  lineNum?: unknown;
+  linePos?: unknown;
+}): string {
+  const type = typeof value.type === 'string' ? value.type : 'message';
+  const message = typeof value.message === 'string' ? value.message : '';
+  const lineNum = typeof value.lineNum === 'number' ? value.lineNum : null;
+  const linePos = typeof value.linePos === 'number' ? value.linePos : null;
+  const location =
+    lineNum !== null && linePos !== null
+      ? ` @ ${lineNum}:${linePos}`
+      : lineNum !== null
+        ? ` @ ${lineNum}`
+        : '';
+  return `${type}${location}: ${message}`.trim();
+}
+
 /** Set-like class for features (lets apps check for WebGL / WebGPU extensions) */
 export class DeviceFeatures {
   protected features: Set<DeviceFeature>;
@@ -172,7 +259,6 @@ export type WebGPUDeviceFeature =
 
 export type WebGLDeviceFeature =
   // 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
@@ -187,6 +273,7 @@ export type WebGLDeviceFeature =
   | 'float16-renderable-webgl'
   | 'rgb9e5ufloat-renderable-webgl'
   | 'snorm8-renderable-webgl'
+  | 'norm16-webgl'
   | 'norm16-renderable-webgl'
   | 'snorm16-renderable-webgl'
 
@@ -241,18 +328,29 @@ export type DeviceProps = {
   /** Error handler. If it returns a probe logger style function, it will be called at the site of the error to optimize console error links. */
   onError?: (error: Error, context?: unknown) => unknown;
   /** Called when the size of a CanvasContext's canvas changes */
-  onResize?: (ctx: CanvasContext, info: {oldPixelSize: [number, number]}) => unknown;
+  onResize?: (
+    ctx: CanvasContext | PresentationContext,
+    info: {oldPixelSize: [number, number]}
+  ) => unknown;
   /** Called when the absolute position of a CanvasContext's canvas changes. Must set `CanvasContextProps.trackPosition: true` */
-  onPositionChange?: (ctx: CanvasContext, info: {oldPosition: [number, number]}) => unknown;
+  onPositionChange?: (
+    ctx: CanvasContext | PresentationContext,
+    info: {oldPosition: [number, number]}
+  ) => unknown;
   /** Called when the visibility of a CanvasContext's canvas changes */
-  onVisibilityChange?: (ctx: CanvasContext) => unknown;
+  onVisibilityChange?: (ctx: CanvasContext | PresentationContext) => unknown;
   /** Called when the device pixel ratio of a CanvasContext's canvas changes */
-  onDevicePixelRatioChange?: (ctx: CanvasContext, info: {oldRatio: number}) => unknown;
+  onDevicePixelRatioChange?: (
+    ctx: CanvasContext | PresentationContext,
+    info: {oldRatio: number}
+  ) => unknown;
 
   // DEBUG SETTINGS
 
   /** Turn on implementation defined checks that slow down execution but help break where errors occur */
   debug?: boolean;
+  /** Enable GPU timestamp collection without enabling all debug validation paths. */
+  debugGPUTime?: boolean;
   /** Show shader source in browser? The default is `'error'`, meaning that logs are shown when shader compilation has errors */
   debugShaders?: 'never' | 'errors' | 'warnings' | 'always';
   /** Renders a small version of updated Framebuffers into the primary canvas context. Can be set in console luma.log.set('debug-framebuffers', true) */
@@ -278,15 +376,31 @@ export type DeviceProps = {
   _initializeFeatures?: boolean;
   /** Enable shader caching (via ShaderFactory) */
   _cacheShaders?: boolean;
-  /** Enable shader caching (via PipelineFactory) */
+  /**
+   * Destroy cached shaders when they become unused.
+   * Defaults to `false` so repeated create/destroy cycles can still reuse cached shaders.
+   * Enable this if the application creates very large numbers of distinct shaders and needs cache eviction.
+   */
+  _destroyShaders?: boolean;
+  /** Enable pipeline caching (via PipelineFactory) */
   _cachePipelines?: boolean;
-  /** Never destroy cached shaders and pipelines */
-  _cacheDestroyPolicy?: 'unused' | 'never';
+  /** Enable sharing of backend render-pipeline implementations when caching is enabled. Currently used by WebGL. */
+  _sharePipelines?: boolean;
+  /**
+   * Destroy cached pipelines when they become unused.
+   * Defaults to `false` so repeated create/destroy cycles can still reuse cached pipelines.
+   * Enable this if the application creates very large numbers of distinct pipelines and needs cache eviction.
+   */
+  _destroyPipelines?: boolean;
 
   /** @deprecated Internal, Do not use directly! Use `luma.attachDevice()` to attach to pre-created contexts/devices. */
   _handle?: unknown; // WebGL2RenderingContext | GPUDevice | null;
 };
 
+type DeviceFactories = {
+  bindGroupFactory?: unknown;
+};
+
 /** WebGL independent copy of WebGLContextAttributes */
 type WebGLContextProps = {
   /** indicates if the canvas contains an alpha buffer. */
@@ -349,7 +463,8 @@ export abstract class Device {
       log.log(1, `${context} DPR changed ${info.oldRatio} => ${context.devicePixelRatio}`)(),
 
     // Debug flags
-    debug: log.get('debug') || undefined!,
+    debug: getDefaultDebugValue(),
+    debugGPUTime: false,
     debugShaders: log.get('debug-shaders') || undefined!,
     debugFramebuffers: Boolean(log.get('debug-framebuffers')),
     debugFactories: Boolean(log.get('debug-factories')),
@@ -360,9 +475,11 @@ export abstract class Device {
     // Experimental
     _reuseDevices: false,
     _requestMaxLimits: true,
-    _cacheShaders: false,
-    _cachePipelines: false,
-    _cacheDestroyPolicy: 'unused',
+    _cacheShaders: true,
+    _destroyShaders: false,
+    _cachePipelines: true,
+    _sharePipelines: true,
+    _destroyPipelines: false,
     // TODO - Change these after confirming things work as expected
     _initializeFeatures: true,
     _disabledFeatures: {
@@ -394,13 +511,15 @@ export abstract class Device {
   userData: {[key: string]: unknown} = {};
   /** stats */
   readonly statsManager: StatsManager = lumaStats;
+  /** Internal per-device factory storage */
+  _factories: DeviceFactories = {};
   /** An abstract timestamp used for change tracking */
   timestamp: number = 0;
 
   /** True if this device has been reused during device creation (app has multiple references) */
   _reused: boolean = false;
   /** Used by other luma.gl modules to store data on the device */
-  _lumaData: {[key: string]: unknown} = {};
+  private _moduleData: Record<string, Record<string, unknown>> = {};
 
   // Capabilities
 
@@ -419,6 +538,8 @@ export abstract class Device {
   abstract preferredDepthFormat: 'depth16' | 'depth24plus' | 'depth32float';
 
   protected _textureCaps: Partial<Record<TextureFormat, DeviceTextureFormatCapabilities>> = {};
+  /** Internal timestamp query set used when GPU timing collection is enabled for this device. */
+  protected _debugGPUTimeQuery: QuerySet | null = null;
 
   constructor(props: DeviceProps) {
     this.props = {...Device.defaultProps, ...props};
@@ -427,8 +548,10 @@ export abstract class Device {
 
   abstract destroy(): void;
 
+  // TODO - just expose the shadertypes decoders?
+
   getVertexFormatInfo(format: VertexFormat): VertexFormatInfo {
-    return getVertexFormatInfo(format);
+    return vertexFormatDecoder.getVertexFormatInfo(format);
   }
 
   isVertexFormatSupported(format: VertexFormat): boolean {
@@ -451,9 +574,6 @@ export abstract class Device {
     return textureCaps;
   }
 
-  /** Return the implementation specific alignment for a texture format. 1 on WebGL, 256 on WebGPU */
-  abstract getTextureByteAlignment(): number;
-
   /** Calculates the number of mip levels for a texture of width, height and in case of 3d textures only, depth */
   getMipLevelCount(width: number, height: number, depth3d: number = 1): number {
     const maxSize = Math.max(width, height, depth3d);
@@ -490,6 +610,19 @@ export abstract class Device {
     return textureFormatDecoder.isCompressed(format);
   }
 
+  /** Returns the compressed texture formats that can be created and sampled on this device */
+  getSupportedCompressedTextureFormats(): CompressedTextureFormat[] {
+    const supportedFormats: CompressedTextureFormat[] = [];
+
+    for (const format of Object.keys(getTextureFormatTable()) as TextureFormat[]) {
+      if (this.isTextureFormatCompressed(format) && this.isTextureFormatSupported(format)) {
+        supportedFormats.push(format as CompressedTextureFormat);
+      }
+    }
+
+    return supportedFormats;
+  }
+
   // DEBUG METHODS
 
   pushDebugGroup(groupLabel: string): void {
@@ -547,8 +680,14 @@ export abstract class Device {
     // Call the error handler
     const isHandled = this.props.onError(error, context);
     if (!isHandled) {
+      const logArguments = formatErrorLogArguments(context, args);
       // Note: Returns a function that must be called: `device.reportError(...)()`
-      return log.error(error.message, context, ...args);
+      return log.error(
+        this.type === 'webgl' ? '%cWebGL' : '%cWebGPU',
+        'color: white; background: red; padding: 2px 6px; border-radius: 3px;',
+        error.message,
+        ...logArguments
+      );
     }
     return () => {};
   }
@@ -583,6 +722,9 @@ or create a device with the 'debug: true' prop.`;
   /** Creates a new CanvasContext (WebGPU only) */
   abstract createCanvasContext(props?: CanvasContextProps): CanvasContext;
 
+  /** Creates a presentation context for a destination canvas. WebGL requires the default canvas context to use an OffscreenCanvas. */
+  abstract createPresentationContext(props?: PresentationContextProps): PresentationContext;
+
   /** Call after rendering a frame (necessary e.g. on WebGL OffscreenCanvas) */
   abstract submit(commandBuffer?: CommandBuffer): void;
 
@@ -622,6 +764,11 @@ or create a device with the 'debug: true' prop.`;
 
   abstract createQuerySet(props: QuerySetProps): QuerySet;
 
+  /** Create a fence sync object */
+  createFence(): Fence {
+    throw new Error('createFence() not implemented');
+  }
+
   /** Create a RenderPass using the default CommandEncoder */
   beginRenderPass(props?: RenderPassProps): RenderPass {
     return this.commandEncoder.beginRenderPass(props);
@@ -632,6 +779,101 @@ or create a device with the 'debug: true' prop.`;
     return this.commandEncoder.beginComputePass(props);
   }
 
+  /**
+   * Generate mipmaps for a WebGPU texture.
+   * WebGPU textures must be created up front with the required mip count, usage flags, and a format that supports the chosen generation path.
+   * WebGL uses `Texture.generateMipmapsWebGL()` directly because the backend manages mip generation on the texture object itself.
+   */
+  generateMipmapsWebGPU(_texture: Texture): void {
+    throw new Error('not implemented');
+  }
+
+  /** Internal helper for creating a shareable WebGL render-pipeline implementation. */
+  _createSharedRenderPipelineWebGL(_props: RenderPipelineProps): SharedRenderPipeline {
+    throw new Error('_createSharedRenderPipelineWebGL() not implemented');
+  }
+
+  /** Internal WebGPU-only helper for retrieving the native bind-group layout for a pipeline group. */
+  _createBindGroupLayoutWebGPU(
+    _pipeline: RenderPipeline | ComputePipeline,
+    _group: number
+  ): unknown {
+    throw new Error('_createBindGroupLayoutWebGPU() not implemented');
+  }
+
+  /** Internal WebGPU-only helper for creating a native bind group. */
+  _createBindGroupWebGPU(
+    _bindGroupLayout: unknown,
+    _shaderLayout: ShaderLayout | ComputeShaderLayout,
+    _bindings: Bindings,
+    _group: number
+  ): unknown {
+    throw new Error('_createBindGroupWebGPU() not implemented');
+  }
+
+  /**
+   * Internal helper that returns `true` when timestamp-query GPU timing should be
+   * collected for this device.
+   */
+  _supportsDebugGPUTime(): boolean {
+    return (
+      this.features.has('timestamp-query') && Boolean(this.props.debug || this.props.debugGPUTime)
+    );
+  }
+
+  /**
+   * Internal helper that enables device-managed GPU timing collection on the
+   * default command encoder. Reuses the existing query set if timing is already enabled.
+   *
+   * @param queryCount - Number of timestamp slots reserved for profiled passes.
+   * @returns The device-managed timestamp QuerySet, or `null` when timing is not supported or could not be enabled.
+   */
+  _enableDebugGPUTime(queryCount: number = 256): QuerySet | null {
+    if (!this._supportsDebugGPUTime()) {
+      return null;
+    }
+
+    if (this._debugGPUTimeQuery) {
+      return this._debugGPUTimeQuery;
+    }
+
+    try {
+      this._debugGPUTimeQuery = this.createQuerySet({type: 'timestamp', count: queryCount});
+      this.commandEncoder = this.createCommandEncoder({
+        id: this.commandEncoder.props.id,
+        timeProfilingQuerySet: this._debugGPUTimeQuery
+      });
+    } catch {
+      this._debugGPUTimeQuery = null;
+    }
+
+    return this._debugGPUTimeQuery;
+  }
+
+  /**
+   * Internal helper that disables device-managed GPU timing collection and restores
+   * the default command encoder to an unprofiled state.
+   */
+  _disableDebugGPUTime(): void {
+    if (!this._debugGPUTimeQuery) {
+      return;
+    }
+
+    if (this.commandEncoder.getTimeProfilingQuerySet() === this._debugGPUTimeQuery) {
+      this.commandEncoder = this.createCommandEncoder({
+        id: this.commandEncoder.props.id
+      });
+    }
+
+    this._debugGPUTimeQuery.destroy();
+    this._debugGPUTimeQuery = null;
+  }
+
+  /** Internal helper that returns `true` when device-managed GPU timing is currently active. */
+  _isDebugGPUTimeEnabled(): boolean {
+    return this._debugGPUTimeQuery !== null;
+  }
+
   /**
    * Determines what operations are supported on a texture format, checking against supported device features
    * Subclasses override to apply additional checks
@@ -711,6 +953,15 @@ or create a device with the 'debug: true' prop.`;
     throw new Error('not implemented');
   }
 
+  // INTERNAL LUMA.GL METHODS
+
+  getModuleData<ModuleDataT extends Record<string, unknown>>(moduleName: string): ModuleDataT {
+    this._moduleData[moduleName] ||= {};
+    return this._moduleData[moduleName] as ModuleDataT;
+  }
+
+  // INTERNAL HELPERS
+
   // IMPLEMENTATION
 
   /** Helper to get the canvas context props */
@@ -756,6 +1007,10 @@ or create a device with the 'debug: true' prop.`;
           newProps.indexType = 'uint32';
         } else if (props.data instanceof Uint16Array) {
           newProps.indexType = 'uint16';
+        } else if (props.data instanceof Uint8Array) {
+          // Convert uint8 to uint16 for WebGPU compatibility (WebGPU doesn't support uint8 indices)
+          newProps.data = new Uint16Array(props.data);
+          newProps.indexType = 'uint16';
         }
       }
       if (!newProps.indexType) {
@@ -766,3 +1021,36 @@ or create a device with the 'debug: true' prop.`;
     return newProps;
   }
 }
+
+/**
+ * Internal helper for resolving the default `debug` prop.
+ * Precedence is: explicit log debug value first, then `NODE_ENV`, then `false`.
+ */
+export function _getDefaultDebugValue(logDebugValue: unknown, nodeEnv?: string): boolean {
+  if (logDebugValue !== undefined && logDebugValue !== null) {
+    return Boolean(logDebugValue);
+  }
+
+  if (nodeEnv !== undefined) {
+    return nodeEnv !== 'production';
+  }
+
+  return false;
+}
+
+function getDefaultDebugValue(): boolean {
+  return _getDefaultDebugValue(log.get('debug'), getNodeEnv());
+}
+
+function getNodeEnv(): string | undefined {
+  const processObject = (
+    globalThis as typeof globalThis & {
+      process?: {env?: Record<string, string | undefined>};
+    }
+  ).process;
+  if (!processObject?.env) {
+    return undefined;
+  }
+
+  return processObject.env['NODE_ENV'];
+}

package/src/adapter/presentation-context.ts

@@ -0,0 +1,16 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CanvasSurface} from './canvas-surface';
+
+export type {CanvasContextProps as PresentationContextProps} from './canvas-surface';
+
+/**
+ * Tracks a destination canvas for presentation.
+ * Backend implementations either borrow the default GPU-backed canvas (WebGL)
+ * or render directly into the destination canvas (WebGPU).
+ */
+export abstract class PresentationContext extends CanvasSurface {
+  abstract present(): void;
+}

package/src/adapter/resources/buffer.ts

@@ -17,8 +17,8 @@ export type BufferProps = ResourceProps & {
   byteLength?: number;
   /** Byte offset into the newly created Buffer to store data at */
   byteOffset?: number;
-  /** If props.usage includes Buffer.INDEX */
-  indexType?: 'uint16' | 'uint32';
+  /** If props.usage includes Buffer.INDEX. Note: uint8 indices are automatically converted to uint16 for WebGPU compatibility */
+  indexType?: 'uint8' | 'uint16' | 'uint32';
   /** Data to initialize the buffer with. */
   data?: ArrayBuffer | ArrayBufferView | null;
   /** Callback to initialize data without copy */
@@ -50,8 +50,8 @@ export abstract class Buffer extends Resource<BufferProps> {
 
   /** The usage with which this buffer was created */
   readonly usage: number;
-  /** For index buffers, whether indices are 16 or 32 bit */
-  readonly indexType?: 'uint16' | 'uint32';
+  /** For index buffers, whether indices are 8, 16 or 32 bit. Note: uint8 indices are automatically converted to uint16 for WebGPU compatibility */
+  readonly indexType?: 'uint8' | 'uint16' | 'uint32';
   /** Length of buffer in bytes */
   abstract byteLength: number;
   /** "Time" of last update, can be used to check if redraw is needed */
@@ -66,6 +66,8 @@ export abstract class Buffer extends Resource<BufferProps> {
         deducedProps.indexType = 'uint32';
       } else if (props.data instanceof Uint16Array) {
         deducedProps.indexType = 'uint16';
+      } else if (props.data instanceof Uint8Array) {
+        deducedProps.indexType = 'uint8';
       }
     }
 
@@ -125,20 +127,28 @@ export abstract class Buffer extends Resource<BufferProps> {
   /** This doesn't handle partial non-zero offset updates correctly */
   protected _setDebugData(
     data: ArrayBufferView | ArrayBufferLike | null,
-    byteOffset: number,
+    _byteOffset: number,
     byteLength: number
   ): void {
-    const arrayBuffer: ArrayBufferLike | null = ArrayBuffer.isView(data) ? data.buffer : data;
+    let arrayBufferView: ArrayBufferView | null = null;
+    let arrayBuffer: ArrayBufferLike | null;
+    if (ArrayBuffer.isView(data)) {
+      arrayBufferView = data;
+      arrayBuffer = data.buffer;
+    } else {
+      arrayBuffer = data;
+    }
     const debugDataLength = Math.min(
       data ? data.byteLength : byteLength,
       Buffer.DEBUG_DATA_MAX_LENGTH
     );
     if (arrayBuffer === null) {
       this.debugData = new ArrayBuffer(debugDataLength);
-    } else if (byteOffset === 0 && byteLength === arrayBuffer.byteLength) {
-      this.debugData = arrayBuffer.slice(0, debugDataLength);
     } else {
-      this.debugData = arrayBuffer.slice(byteOffset, byteOffset + debugDataLength);
+      const sourceByteOffset = Math.min(arrayBufferView?.byteOffset || 0, arrayBuffer.byteLength);
+      const availableByteLength = Math.max(0, arrayBuffer.byteLength - sourceByteOffset);
+      const copyByteLength = Math.min(debugDataLength, availableByteLength);
+      this.debugData = new Uint8Array(arrayBuffer, sourceByteOffset, copyByteLength).slice().buffer;
     }
   }
 

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

@@ -11,7 +11,7 @@ import {Resource, ResourceProps} from './resource';
 //   // onSubmittedWorkDone(): Promise<undefined>;
 
 //   writeBuffer(options: WriteBufferOptions): void;
-//   writeTexture(options: WriteTextureOptions): void;
+//   writeTexture(options: TextureWriteOptions): void;
 
 //   // copyExternalImageToTexture(
 //   //   GPUImageCopyExternalImage source,
@@ -23,7 +23,9 @@ import {Resource, ResourceProps} from './resource';
 export type CommandBufferProps = ResourceProps & {};
 
 /**
- * Encodes commands to queue that can be executed later
+ * Represents the finished contents of exactly one CommandEncoder. Backends may store native
+ * command buffers or replayable command lists internally, but submission must preserve the same
+ * recorded command ordering.
  */
 export abstract class CommandBuffer extends Resource<CommandBufferProps> {
   override get [Symbol.toStringTag](): string {