@luma.gl/core 9.2.6 → 9.3.0-alpha.11

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

@@ -5,9 +5,9 @@
 // import type {TypedArray} from '@math.gl/types';
 import {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
+import {QuerySet} from './query-set';
 import {Buffer} from './buffer';
 import {Texture} from './texture';
-import {QuerySet} from './query-set';
 import type {RenderPass, RenderPassProps} from './render-pass';
 import type {ComputePass, ComputePassProps} from './compute-pass';
 import type {CommandBuffer, CommandBufferProps} from './command-buffer';
@@ -27,11 +27,11 @@ export type CopyBufferToTextureOptions = {
   byteOffset?: number;
   destinationTexture: Texture;
   mipLevel?: number; //  = 0;
-  origin?: [number, number, number] | number[];
+  origin?: [number, number, number];
   aspect?: 'all' | 'stencil-only' | 'depth-only';
   bytesPerRow: number;
   rowsPerImage: number;
-  size: [number, number, number] | number[];
+  size: [number, number, number];
 };
 
 export type CopyTextureToBufferOptions = {
@@ -49,7 +49,7 @@ export type CopyTextureToBufferOptions = {
   width?: number;
   height?: number;
   depthOrArrayLayers?: number;
-  origin?: number[];
+  origin?: [number, number, number];
 
   /** Destination buffer */
   destinationBuffer: Buffer;
@@ -74,7 +74,7 @@ export type CopyTextureToTextureOptions = {
   /**  Mip-map level of the texture to copy to/from. (Default 0) */
   mipLevel?: number;
   /** Defines the origin of the copy - the minimum corner of the texture sub-region to copy from. */
-  origin?: number[];
+  origin?: [number, number, number];
   /** Defines which aspects of the {@link GPUImageCopyTexture#texture} to copy to/from. */
   aspect?: 'all' | 'stencil-only' | 'depth-only';
 
@@ -83,7 +83,7 @@ export type CopyTextureToTextureOptions = {
   /**  Mip-map level of the texture to copy to/from. (Default 0) */
   destinationMipLevel?: number;
   /** Defines the origin of the copy - the minimum corner of the texture sub-region to copy to. */
-  destinationOrigin?: number[];
+  destinationOrigin?: [number, number, number];
   /** Defines which aspects of the {@link GPUImageCopyTexture#texture} to copy to/from. */
   destinationAspect?: 'all' | 'stencil-only' | 'depth-only';
 
@@ -113,7 +113,7 @@ export type ClearTextureOptions = {
 //   size?: number;
 // };
 
-// export type WriteTextureOptions = {
+// export type TextureWriteOptions = {
 //   destination: Texture;
 //   mipLevel?: number; //  = 0;
 //   origin?: [number, number, number] | number[];
@@ -128,18 +128,34 @@ export type ClearTextureOptions = {
 
 export type CommandEncoderProps = ResourceProps & {
   measureExecutionTime?: boolean;
+  timeProfilingQuerySet?: QuerySet | null;
+};
+
+type PassWithTimestamps = {
+  timestampQuerySet?: QuerySet;
+  beginTimestampIndex?: number;
+  endTimestampIndex?: number;
 };
 
 /**
- * Encodes commands to queue that can be executed later
+ * Records commands onto a single backend command encoder and can finish them into one command
+ * buffer. Resource helpers invoked through a CommandEncoder must record onto that encoder rather
+ * than allocating hidden encoders or submitting work eagerly.
  */
 export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
   override get [Symbol.toStringTag](): string {
     return 'CommandEncoder';
   }
 
+  protected _timeProfilingQuerySet: QuerySet | null = null;
+  protected _timeProfilingSlotCount: number = 0;
+  _gpuTimeMs?: number;
+
   constructor(device: Device, props: CommandEncoderProps) {
     super(device, props, CommandEncoder.defaultProps);
+    this._timeProfilingQuerySet = props.timeProfilingQuerySet ?? null;
+    this._timeProfilingSlotCount = 0;
+    this._gpuTimeMs = undefined;
   }
 
   /** Completes recording of the commands sequence */
@@ -166,7 +182,7 @@ export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
   /** Add a command that clears a texture mip level. */
   // abstract clearTexture(options: ClearTextureOptions): void;
 
-  // abstract readTexture(options: ReadTextureOptions): Promise<TypedArray>;
+  // abstract readTexture(options: TextureReadOptions): Promise<TypedArray>;
 
   /** Reads results from a query set into a GPU buffer. Values are 64 bits so byteLength must be querySet.props.count * 8 */
   abstract resolveQuerySet(
@@ -179,6 +195,80 @@ export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
     }
   ): void;
 
+  /**
+   * Reads all resolved timestamp pairs on the current profiler query set and caches the sum
+   * as milliseconds on this encoder.
+   */
+  async resolveTimeProfilingQuerySet(): Promise<void> {
+    this._gpuTimeMs = undefined;
+
+    if (!this._timeProfilingQuerySet) {
+      return;
+    }
+
+    const pairCount = Math.floor(this._timeProfilingSlotCount / 2);
+    if (pairCount <= 0) {
+      return;
+    }
+
+    const queryCount = pairCount * 2;
+    const results = await this._timeProfilingQuerySet.readResults({
+      firstQuery: 0,
+      queryCount
+    });
+
+    let totalDurationNanoseconds = 0n;
+    for (let queryIndex = 0; queryIndex < queryCount; queryIndex += 2) {
+      totalDurationNanoseconds += results[queryIndex + 1] - results[queryIndex];
+    }
+
+    this._gpuTimeMs = Number(totalDurationNanoseconds) / 1e6;
+  }
+
+  /** Returns the number of query slots consumed by automatic pass profiling on this encoder. */
+  getTimeProfilingSlotCount(): number {
+    return this._timeProfilingSlotCount;
+  }
+
+  getTimeProfilingQuerySet(): QuerySet | null {
+    return this._timeProfilingQuerySet;
+  }
+
+  /** Internal helper for auto-assigning timestamp slots to render/compute passes on this encoder. */
+  protected _applyTimeProfilingToPassProps<P extends PassWithTimestamps>(props?: P): P {
+    const passProps = (props || {}) as P;
+
+    if (!this._supportsTimestampQueries() || !this._timeProfilingQuerySet) {
+      return passProps;
+    }
+
+    if (
+      passProps.timestampQuerySet !== undefined ||
+      passProps.beginTimestampIndex !== undefined ||
+      passProps.endTimestampIndex !== undefined
+    ) {
+      return passProps;
+    }
+
+    const beginTimestampIndex = this._timeProfilingSlotCount;
+    if (beginTimestampIndex + 1 >= this._timeProfilingQuerySet.props.count) {
+      return passProps;
+    }
+
+    this._timeProfilingSlotCount += 2;
+
+    return {
+      ...passProps,
+      timestampQuerySet: this._timeProfilingQuerySet,
+      beginTimestampIndex,
+      endTimestampIndex: beginTimestampIndex + 1
+    };
+  }
+
+  protected _supportsTimestampQueries(): boolean {
+    return this.device.features.has('timestamp-query');
+  }
+
   /** Begins a labeled debug group containing subsequent commands */
   abstract pushDebugGroup(groupLabel: string): void;
   /** Ends the labeled debug group most recently started by pushDebugGroup() */
@@ -192,6 +282,7 @@ export abstract class CommandEncoder extends Resource<CommandEncoderProps> {
 
   static override defaultProps: Required<CommandEncoderProps> = {
     ...Resource.defaultProps,
-    measureExecutionTime: undefined!
+    measureExecutionTime: undefined!,
+    timeProfilingQuerySet: undefined!
   };
 }

package/src/adapter/resources/compute-pipeline.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {Resource, ResourceProps} from './resource';
-import type {ComputeShaderLayout, Binding} from '../types/shader-layout';
+import type {ComputeShaderLayout, Bindings, BindingsByGroup} from '../types/shader-layout';
 import type {Device} from '../device';
 import type {Shader} from './shader';
 
@@ -43,7 +43,7 @@ export abstract class ComputePipeline extends Resource<ComputePipelineProps> {
    * @todo Use renderpass.setBindings() ?
    * @todo Do we want to expose BindGroups in the API and remove this?
    */
-  abstract setBindings(bindings: Record<string, Binding>): void;
+  abstract setBindings(bindings: Bindings | BindingsByGroup): void;
 
   static override defaultProps: Required<ComputePipelineProps> = {
     ...Resource.defaultProps,

package/src/adapter/resources/fence.ts

@@ -0,0 +1,32 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device} from '../device';
+import {Resource, type ResourceProps} from './resource';
+
+export type FenceProps = ResourceProps;
+
+/** Synchronization primitive that resolves when GPU work is completed */
+export abstract class Fence extends Resource<FenceProps> {
+  static override defaultProps: Required<FenceProps> = {
+    ...Resource.defaultProps
+  };
+
+  override get [Symbol.toStringTag](): string {
+    return 'Fence';
+  }
+
+  /** Promise that resolves when the fence is signaled */
+  abstract readonly signaled: Promise<void>;
+
+  constructor(device: Device, props: FenceProps = {}) {
+    super(device, props, Fence.defaultProps);
+  }
+
+  /** Destroy the fence and release any resources */
+  abstract override destroy(): void;
+
+  /** Check if the fence has been signaled */
+  abstract isSignaled(): boolean;
+}

package/src/adapter/resources/framebuffer.ts

@@ -6,7 +6,7 @@ import type {
   TextureFormatColor,
   TextureFormatDepthStencil,
   TextureFormat
-} from '../../shadertypes/textures/texture-formats';
+} from '../../shadertypes/texture-types/texture-formats';
 import type {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
 import {Texture} from './texture';
@@ -56,7 +56,12 @@ export abstract class Framebuffer extends Resource<FramebufferProps> {
     const depthStencilAttachment =
       this.depthStencilAttachment && this.depthStencilAttachment.texture.clone(size);
 
-    return this.device.createFramebuffer({...this.props, colorAttachments, depthStencilAttachment});
+    return this.device.createFramebuffer({
+      ...this.props,
+      ...size,
+      colorAttachments,
+      depthStencilAttachment
+    });
   }
 
   /**
@@ -146,17 +151,15 @@ export abstract class Framebuffer extends Resource<FramebufferProps> {
    * and destroys existing textures if owned
    */
   protected resizeAttachments(width: number, height: number): void {
-    for (let i = 0; i < this.colorAttachments.length; ++i) {
-      if (this.colorAttachments[i]) {
-        const resizedTexture = this.colorAttachments[i].texture.clone({
-          width,
-          height
-        });
-        this.destroyAttachedResource(this.colorAttachments[i]);
-        this.colorAttachments[i] = resizedTexture.view;
-        this.attachResource(resizedTexture.view);
-      }
-    }
+    this.colorAttachments.forEach((colorAttachment, i) => {
+      const resizedTexture = colorAttachment.texture.clone({
+        width,
+        height
+      });
+      this.destroyAttachedResource(colorAttachment);
+      this.colorAttachments[i] = resizedTexture.view;
+      this.attachResource(resizedTexture.view);
+    });
 
     if (this.depthStencilAttachment) {
       const resizedTexture = this.depthStencilAttachment.texture.clone({

package/src/adapter/resources/query-set.ts

@@ -16,7 +16,8 @@ export type QuerySetProps = ResourceProps & {
   /**
    * The type of query set
    * occlusion - query the number of fragment samples that pass all the per-fragment tests for a set of drawing commands, including scissor, sample mask, alpha to coverage, stencil, and depth tests
-   * timestamp - query the GPU timestamp counter at the start and end of render passes
+   * timestamp - query the GPU timestamp counter. Timestamp queries are available if the
+   * `timestamp-query` feature is present.
    */
   type: 'occlusion' | 'timestamp';
   /** The number of queries managed by the query set */
@@ -38,4 +39,19 @@ export abstract class QuerySet extends Resource<QuerySetProps> {
     type: undefined!,
     count: undefined!
   };
+
+  /**
+   * Returns true if the requested result has been captured and can be read without blocking.
+   * Backends may implement this conservatively.
+   */
+  abstract isResultAvailable(queryIndex?: number): boolean;
+
+  /** Reads query results as 64-bit values. */
+  abstract readResults(options?: {firstQuery?: number; queryCount?: number}): Promise<bigint[]>;
+
+  /**
+   * Reads a timestamp duration in milliseconds between a begin and end query index.
+   * Portable duration profiling requires adjacent indices that identify one logical pair.
+   */
+  abstract readTimestampDuration(beginIndex: number, endIndex: number): Promise<number>;
 }

package/src/adapter/resources/render-pipeline.ts

@@ -3,15 +3,15 @@
 // Copyright (c) vis.gl contributors
 
 import type {Device} from '../device';
-import type {UniformValue} from '../types/uniforms';
 import type {PrimitiveTopology, RenderPipelineParameters} from '../types/parameters';
-import type {ShaderLayout, Binding} from '../types/shader-layout';
+import type {ShaderLayout, Bindings, BindingsByGroup} from '../types/shader-layout';
 import type {BufferLayout} from '../types/buffer-layout';
 import type {
   TextureFormatColor,
   TextureFormatDepthStencil
-} from '@luma.gl/core/shadertypes/textures/texture-formats';
+} from '@luma.gl/core/shadertypes/texture-types/texture-formats';
 import type {Shader} from './shader';
+import type {SharedRenderPipeline} from './shared-render-pipeline';
 import type {RenderPass} from './render-pass';
 import {Resource, ResourceProps} from './resource';
 import {VertexArray} from './vertex-array';
@@ -51,12 +51,22 @@ export type RenderPipelineProps = ResourceProps & {
   /** Parameters that are controlled by pipeline */
   parameters?: RenderPipelineParameters;
 
-  // Dynamic bindings (TODO - pipelines should be immutable, move to RenderPass)
+  /** Transform feedback varyings captured when linking a WebGL render pipeline. WebGL only. */
+  varyings?: string[];
+  /** Transform feedback buffer mode used when linking a WebGL render pipeline. WebGL only. */
+  bufferMode?: number;
+
+  /** Some applications intentionally supply unused attributes and bindings, and want to disable warnings */
+  disableWarnings?: boolean;
+
+  /** Internal hook for backend-specific shared pipeline implementations. */
+  _sharedRenderPipeline?: SharedRenderPipeline;
 
+  // Dynamic bindings (TODO - pipelines should be immutable, move to RenderPass)
   /** Buffers, Textures, Samplers for the shader bindings */
-  bindings?: Record<string, Binding>;
-  /** @deprecated uniforms (WebGL only) */
-  uniforms?: Record<string, UniformValue>;
+  bindings?: Bindings;
+  /** Bindings grouped by bind-group index */
+  bindGroups?: BindingsByGroup;
 };
 
 /**
@@ -78,19 +88,34 @@ export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
   linkStatus: 'pending' | 'success' | 'error' = 'pending';
   /** The hash of the pipeline */
   hash: string = '';
+  /** Optional shared backend implementation */
+  sharedRenderPipeline: SharedRenderPipeline | null = null;
+
+  /** Whether shader or pipeline compilation/linking is still in progress */
+  get isPending(): boolean {
+    return (
+      this.linkStatus === 'pending' ||
+      this.vs.compilationStatus === 'pending' ||
+      this.fs?.compilationStatus === 'pending'
+    );
+  }
+
+  /** Whether shader or pipeline compilation/linking has failed */
+  get isErrored(): boolean {
+    return (
+      this.linkStatus === 'error' ||
+      this.vs.compilationStatus === 'error' ||
+      this.fs?.compilationStatus === 'error'
+    );
+  }
 
   constructor(device: Device, props: RenderPipelineProps) {
     super(device, props, RenderPipeline.defaultProps);
     this.shaderLayout = this.props.shaderLayout!;
     this.bufferLayout = this.props.bufferLayout || [];
+    this.sharedRenderPipeline = this.props._sharedRenderPipeline || null;
   }
 
-  /** Set bindings (stored on pipeline and set before each call) */
-  abstract setBindings(
-    bindings: Record<string, Binding>,
-    options?: {disableWarnings?: boolean}
-  ): void;
-
   /** Draw call. Returns false if the draw call was aborted (due to resources still initializing) */
   abstract draw(options: {
     /** Render pass to draw into (targeting screen or framebuffer) */
@@ -118,6 +143,14 @@ export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
     baseVertex?: number;
     /** Transform feedback. WebGL only. */
     transformFeedback?: TransformFeedback;
+    /** Bindings applied for this draw (textures, samplers, uniform buffers) */
+    bindings?: Bindings;
+    /** Bindings grouped by bind-group index */
+    bindGroups?: BindingsByGroup;
+    /** Optional stable cache keys for backend bind-group reuse */
+    _bindGroupCacheKeys?: Partial<Record<number, object>>;
+    /** WebGL-only uniforms */
+    uniforms?: Record<string, unknown>;
   }): boolean;
 
   static override defaultProps: Required<RenderPipelineProps> = {
@@ -139,8 +172,11 @@ export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
     depthStencilAttachmentFormat: undefined!,
 
     parameters: {},
-
-    bindings: {},
-    uniforms: {}
+    varyings: undefined!,
+    bufferMode: undefined!,
+    disableWarnings: false,
+    _sharedRenderPipeline: undefined!,
+    bindings: undefined!,
+    bindGroups: undefined!
   };
 }