@luma.gl/webgpu 9.3.0-alpha.2 → 9.3.0-alpha.6

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

@@ -2,13 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {QuerySet, QuerySetProps} from '@luma.gl/core';
+import {Buffer, QuerySet, QuerySetProps} from '@luma.gl/core';
 import {WebGPUDevice} from '../webgpu-device';
-
-export type QuerySetProps2 = {
-  type: 'occlusion' | 'timestamp';
-  count: number;
-};
+import {WebGPUBuffer} from './webgpu-buffer';
+import {
+  getCpuHotspotSubmitReason,
+  setCpuHotspotSubmitReason
+} from '../helpers/cpu-hotspot-profiler';
 
 /**
  * Immutable
@@ -17,6 +17,12 @@ export class WebGPUQuerySet extends QuerySet {
   readonly device: WebGPUDevice;
   readonly handle: GPUQuerySet;
 
+  protected _resolveBuffer: WebGPUBuffer | null = null;
+  protected _readBuffer: WebGPUBuffer | null = null;
+  protected _cachedResults: bigint[] | null = null;
+  protected _readResultsPromise: Promise<bigint[]> | null = null;
+  protected _resultsPendingResolution: boolean = false;
+
   constructor(device: WebGPUDevice, props: QuerySetProps) {
     super(device, props);
     this.device = device;
@@ -30,8 +36,178 @@ export class WebGPUQuerySet extends QuerySet {
   }
 
   override destroy(): void {
-    this.handle?.destroy();
-    // @ts-expect-error readonly
-    this.handle = null;
+    if (!this.destroyed) {
+      this.handle?.destroy();
+      this.destroyResource();
+      // @ts-expect-error readonly
+      this.handle = null;
+    }
+  }
+
+  isResultAvailable(queryIndex?: number): boolean {
+    if (!this._cachedResults) {
+      return false;
+    }
+
+    return queryIndex === undefined
+      ? true
+      : queryIndex >= 0 && queryIndex < this._cachedResults.length;
+  }
+
+  async readResults(options?: {firstQuery?: number; queryCount?: number}): Promise<bigint[]> {
+    const firstQuery = options?.firstQuery || 0;
+    const queryCount = options?.queryCount || this.props.count - firstQuery;
+
+    if (firstQuery < 0 || queryCount < 0 || firstQuery + queryCount > this.props.count) {
+      throw new Error('Query read range is out of bounds');
+    }
+
+    let needsFreshResults = true;
+    while (needsFreshResults) {
+      if (!this._readResultsPromise) {
+        this._readResultsPromise = this._readAllResults();
+      }
+
+      const readResultsPromise = this._readResultsPromise;
+      const results = await readResultsPromise;
+
+      // A later submit may have invalidated the query set while this read was in flight.
+      // Retry so each caller observes the freshest resolved results instead of stale data.
+      needsFreshResults = this._resultsPendingResolution;
+      if (!needsFreshResults) {
+        return results.slice(firstQuery, firstQuery + queryCount);
+      }
+    }
+
+    throw new Error('Query read unexpectedly failed to resolve');
+  }
+
+  async readTimestampDuration(beginIndex: number, endIndex: number): Promise<number> {
+    if (this.props.type !== 'timestamp') {
+      throw new Error('Timestamp durations require a timestamp QuerySet');
+    }
+    if (beginIndex < 0 || endIndex <= beginIndex || endIndex >= this.props.count) {
+      throw new Error('Timestamp duration range is out of bounds');
+    }
+
+    const results = await this.readResults({
+      firstQuery: beginIndex,
+      queryCount: endIndex - beginIndex + 1
+    });
+    return Number(results[results.length - 1] - results[0]) / 1e6;
+  }
+
+  /** Marks any cached query results as stale after new writes have been encoded. */
+  _invalidateResults(): void {
+    this._cachedResults = null;
+    this._resultsPendingResolution = true;
+  }
+
+  protected async _readAllResults(): Promise<bigint[]> {
+    this._ensureBuffers();
+
+    try {
+      // Use a dedicated encoder so async profiling reads cannot flush or replace the
+      // device's active frame encoder while application rendering is in flight.
+      if (this._resultsPendingResolution) {
+        const commandEncoder = this.device.createCommandEncoder({
+          id: `${this.id}-read-results`
+        });
+        commandEncoder.resolveQuerySet(this, this._resolveBuffer!);
+        commandEncoder.copyBufferToBuffer({
+          sourceBuffer: this._resolveBuffer!,
+          destinationBuffer: this._readBuffer!,
+          size: this._resolveBuffer!.byteLength
+        });
+        const commandBuffer = commandEncoder.finish({
+          id: `${this.id}-read-results-command-buffer`
+        });
+        const previousSubmitReason = getCpuHotspotSubmitReason(this.device) || undefined;
+        setCpuHotspotSubmitReason(this.device, 'query-readback');
+        try {
+          this.device.submit(commandBuffer);
+        } finally {
+          setCpuHotspotSubmitReason(this.device, previousSubmitReason);
+        }
+      }
+
+      const data = await this._readBuffer!.readAsync(0, this._readBuffer!.byteLength);
+      const resultView = new BigUint64Array(data.buffer, data.byteOffset, this.props.count);
+      this._cachedResults = Array.from(resultView, value => value);
+      this._resultsPendingResolution = false;
+      return this._cachedResults;
+    } finally {
+      this._readResultsPromise = null;
+    }
+  }
+
+  protected _ensureBuffers(): void {
+    if (this._resolveBuffer && this._readBuffer) {
+      return;
+    }
+
+    const byteLength = this.props.count * 8;
+    this._resolveBuffer = this.device.createBuffer({
+      id: `${this.id}-resolve-buffer`,
+      usage: Buffer.QUERY_RESOLVE | Buffer.COPY_SRC,
+      byteLength
+    });
+    this.attachResource(this._resolveBuffer);
+
+    this._readBuffer = this.device.createBuffer({
+      id: `${this.id}-read-buffer`,
+      usage: Buffer.COPY_DST | Buffer.MAP_READ,
+      byteLength
+    });
+    this.attachResource(this._readBuffer);
+  }
+
+  _encodeResolveToReadBuffer(
+    commandEncoder: {
+      resolveQuerySet: (
+        querySet: WebGPUQuerySet,
+        destination: WebGPUBuffer,
+        options?: {firstQuery?: number; queryCount?: number; destinationOffset?: number}
+      ) => void;
+      copyBufferToBuffer: (options: {
+        sourceBuffer: WebGPUBuffer;
+        destinationBuffer: WebGPUBuffer;
+        sourceOffset?: number;
+        destinationOffset?: number;
+        size?: number;
+      }) => void;
+    },
+    options?: {firstQuery?: number; queryCount?: number}
+  ): boolean {
+    if (!this._resultsPendingResolution) {
+      return false;
+    }
+
+    // If a readback is already mapping the shared read buffer, defer to the fallback read path.
+    // That path will submit resolve/copy commands once the current read has completed.
+    if (this._readResultsPromise) {
+      return false;
+    }
+
+    this._ensureBuffers();
+    const firstQuery = options?.firstQuery || 0;
+    const queryCount = options?.queryCount || this.props.count - firstQuery;
+    const byteLength = queryCount * BigUint64Array.BYTES_PER_ELEMENT;
+    const byteOffset = firstQuery * BigUint64Array.BYTES_PER_ELEMENT;
+
+    commandEncoder.resolveQuerySet(this, this._resolveBuffer!, {
+      firstQuery,
+      queryCount,
+      destinationOffset: byteOffset
+    });
+    commandEncoder.copyBufferToBuffer({
+      sourceBuffer: this._resolveBuffer!,
+      sourceOffset: byteOffset,
+      destinationBuffer: this._readBuffer!,
+      destinationOffset: byteOffset,
+      size: byteLength
+    });
+    this._resultsPendingResolution = false;
+    return true;
   }
 }

package/src/adapter/resources/webgpu-render-pass.ts

@@ -11,59 +11,107 @@ import {WebGPUBuffer} from './webgpu-buffer';
 import {WebGPURenderPipeline} from './webgpu-render-pipeline';
 import {WebGPUQuerySet} from './webgpu-query-set';
 import {WebGPUFramebuffer} from './webgpu-framebuffer';
+import {getCpuHotspotProfiler, getTimestamp} from '../helpers/cpu-hotspot-profiler';
 
 export class WebGPURenderPass extends RenderPass {
   readonly device: WebGPUDevice;
   readonly handle: GPURenderPassEncoder;
+  readonly framebuffer: WebGPUFramebuffer;
 
   /** Active pipeline */
   pipeline: WebGPURenderPipeline | null = null;
 
+  /** Latest bindings applied to this pass */
+  bindings: Record<string, Binding> = {};
+
   constructor(device: WebGPUDevice, props: RenderPassProps = {}) {
     super(device, props);
     this.device = device;
-    const framebuffer =
-      (props.framebuffer as WebGPUFramebuffer) || device.getCanvasContext().getCurrentFramebuffer();
-
-    const renderPassDescriptor = this.getRenderPassDescriptor(framebuffer);
+    const {props: renderPassProps} = this;
+    this.framebuffer =
+      (renderPassProps.framebuffer as WebGPUFramebuffer) ||
+      device.getCanvasContext().getCurrentFramebuffer();
 
-    const webgpuQuerySet = props.timestampQuerySet as WebGPUQuerySet;
-    if (webgpuQuerySet) {
-      renderPassDescriptor.occlusionQuerySet = webgpuQuerySet.handle;
+    const profiler = getCpuHotspotProfiler(this.device);
+    if (profiler) {
+      const counterName:
+        | 'explicitFramebufferRenderPassCount'
+        | 'defaultFramebufferRenderPassCount' = renderPassProps.framebuffer
+        ? 'explicitFramebufferRenderPassCount'
+        : 'defaultFramebufferRenderPassCount';
+      profiler[counterName] = (profiler[counterName] || 0) + 1;
     }
 
-    if (device.features.has('timestamp-query')) {
-      const webgpuTSQuerySet = props.timestampQuerySet as WebGPUQuerySet;
-      renderPassDescriptor.timestampWrites = webgpuTSQuerySet
-        ? ({
-            querySet: webgpuTSQuerySet.handle,
-            beginningOfPassWriteIndex: props.beginTimestampIndex,
-            endOfPassWriteIndex: props.endTimestampIndex
-          } as GPUComputePassTimestampWrites)
-        : undefined;
-    }
+    const startTime = profiler ? getTimestamp() : 0;
+    try {
+      const descriptorAssemblyStartTime = profiler ? getTimestamp() : 0;
+      const renderPassDescriptor = this.getRenderPassDescriptor(this.framebuffer);
 
-    if (!device.commandEncoder) {
-      throw new Error('commandEncoder not available');
-    }
+      if (renderPassProps.occlusionQuerySet) {
+        renderPassDescriptor.occlusionQuerySet = (
+          renderPassProps.occlusionQuerySet as WebGPUQuerySet
+        ).handle;
+      }
 
-    this.device.pushErrorScope('validation');
-    this.handle =
-      this.props.handle || device.commandEncoder.handle.beginRenderPass(renderPassDescriptor);
-    this.device.popErrorScope((error: GPUError) => {
-      this.device.reportError(new Error(`${this} creation failed:\n"${error.message}"`), this)();
-      this.device.debug();
-    });
-    this.handle.label = this.props.id;
-    log.groupCollapsed(3, `new WebGPURenderPass(${this.id})`)();
-    log.probe(3, JSON.stringify(renderPassDescriptor, null, 2))();
-    log.groupEnd(3)();
+      if (renderPassProps.timestampQuerySet) {
+        const webgpuTSQuerySet = renderPassProps.timestampQuerySet as WebGPUQuerySet;
+        webgpuTSQuerySet?._invalidateResults();
+        renderPassDescriptor.timestampWrites = webgpuTSQuerySet
+          ? ({
+              querySet: webgpuTSQuerySet.handle,
+              beginningOfPassWriteIndex: renderPassProps.beginTimestampIndex,
+              endOfPassWriteIndex: renderPassProps.endTimestampIndex
+            } as GPURenderPassTimestampWrites)
+          : undefined;
+      }
+      if (profiler) {
+        profiler.renderPassDescriptorAssemblyCount =
+          (profiler.renderPassDescriptorAssemblyCount || 0) + 1;
+        profiler.renderPassDescriptorAssemblyTimeMs =
+          (profiler.renderPassDescriptorAssemblyTimeMs || 0) +
+          (getTimestamp() - descriptorAssemblyStartTime);
+      }
+
+      if (!device.commandEncoder) {
+        throw new Error('commandEncoder not available');
+      }
+
+      this.device.pushErrorScope('validation');
+      const beginRenderPassStartTime = profiler ? getTimestamp() : 0;
+      this.handle =
+        this.props.handle || device.commandEncoder.handle.beginRenderPass(renderPassDescriptor);
+      if (profiler) {
+        profiler.renderPassBeginCount = (profiler.renderPassBeginCount || 0) + 1;
+        profiler.renderPassBeginTimeMs =
+          (profiler.renderPassBeginTimeMs || 0) + (getTimestamp() - beginRenderPassStartTime);
+      }
+      this.device.popErrorScope((error: GPUError) => {
+        this.device.reportError(new Error(`${this} creation failed:\n"${error.message}"`), this)();
+        this.device.debug();
+      });
+      this.handle.label = this.props.id;
+      log.groupCollapsed(3, `new WebGPURenderPass(${this.id})`)();
+      log.probe(3, JSON.stringify(renderPassDescriptor, null, 2))();
+      log.groupEnd(3)();
+    } finally {
+      if (profiler) {
+        profiler.renderPassSetupCount = (profiler.renderPassSetupCount || 0) + 1;
+        profiler.renderPassSetupTimeMs =
+          (profiler.renderPassSetupTimeMs || 0) + (getTimestamp() - startTime);
+      }
+    }
   }
 
-  override destroy(): void {}
+  override destroy(): void {
+    this.destroyResource();
+  }
 
   end(): void {
+    if (this.destroyed) {
+      return;
+    }
     this.handle.end();
+    this.destroy();
   }
 
   setPipeline(pipeline: RenderPipeline): void {
@@ -78,8 +126,8 @@ export class WebGPURenderPass extends RenderPass {
 
   /** Sets an array of bindings (uniform buffers, samplers, textures, ...) */
   setBindings(bindings: Record<string, Binding>): void {
-    this.pipeline?.setBindings(bindings);
-    const bindGroup = this.pipeline?._getBindGroup();
+    this.bindings = bindings;
+    const bindGroup = this.pipeline?._getBindGroup(bindings);
     if (bindGroup) {
       this.handle.setBindGroup(0, bindGroup);
     }

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

@@ -15,6 +15,8 @@ import type {WebGPUDevice} from '../webgpu-device';
 import type {WebGPUShader} from './webgpu-shader';
 import type {WebGPURenderPass} from './webgpu-render-pass';
 
+const EMPTY_BINDINGS: Record<string, Binding> = {};
+
 // RENDER PIPELINE
 
 /** Creates a new render pipeline when parameters change */
@@ -25,8 +27,9 @@ export class WebGPURenderPipeline extends RenderPipeline {
   readonly vs: WebGPUShader;
   readonly fs: WebGPUShader | null = null;
 
-  /** For internal use to create BindGroups */
+  /** Compatibility path for direct pipeline.setBindings() usage */
   private _bindings: Record<string, Binding>;
+  /** For internal use to create BindGroups */
   private _bindGroupLayout: GPUBindGroupLayout | null = null;
   private _bindGroup: GPUBindGroup | null = null;
 
@@ -56,8 +59,7 @@ export class WebGPURenderPipeline extends RenderPipeline {
     // Note: Often the same shader in WebGPU
     this.vs = props.vs as WebGPUShader;
     this.fs = props.fs as WebGPUShader;
-
-    this._bindings = {...this.props.bindings};
+    this._bindings = props.bindings || EMPTY_BINDINGS;
   }
 
   override destroy(): void {
@@ -67,17 +69,25 @@ export class WebGPURenderPipeline extends RenderPipeline {
   }
 
   /**
-   * @todo Use renderpass.setBindings() ?
-   * @todo Do we want to expose BindGroups in the API and remove this?
+   * Compatibility shim for code paths that still set bindings on the pipeline.
+   * The shared-model path passes bindings per draw and does not rely on this state.
    */
   setBindings(bindings: Record<string, Binding>): void {
-    // Invalidate the cached bind group if any value has changed
+    let bindingsChanged = false;
     for (const [name, binding] of Object.entries(bindings)) {
       if (this._bindings[name] !== binding) {
-        this._bindGroup = null;
+        if (!bindingsChanged) {
+          if (this._bindings === this.props.bindings || this._bindings === EMPTY_BINDINGS) {
+            this._bindings = {...this._bindings};
+          }
+          bindingsChanged = true;
+        }
+        this._bindings[name] = binding;
       }
     }
-    Object.assign(this._bindings, bindings);
+    if (bindingsChanged) {
+      this._bindGroup = null;
+    }
   }
 
   /** @todo - should this be moved to renderpass? */
@@ -91,8 +101,12 @@ export class WebGPURenderPipeline extends RenderPipeline {
     firstIndex?: number;
     firstInstance?: number;
     baseVertex?: number;
+    bindings?: Record<string, Binding>;
+    uniforms?: Record<string, unknown>;
   }): boolean {
     const webgpuRenderPass = options.renderPass as WebGPURenderPass;
+    const instanceCount =
+      options.instanceCount && options.instanceCount > 0 ? options.instanceCount : 1;
 
     // Set pipeline
     this.device.pushErrorScope('validation');
@@ -103,7 +117,7 @@ export class WebGPURenderPipeline extends RenderPipeline {
     });
 
     // Set bindings (uniform buffers, textures etc)
-    const bindGroup = this._getBindGroup();
+    const bindGroup = this._getBindGroup(options.bindings);
     if (bindGroup) {
       webgpuRenderPass.handle.setBindGroup(0, bindGroup);
     }
@@ -116,16 +130,17 @@ export class WebGPURenderPipeline extends RenderPipeline {
     if (options.indexCount) {
       webgpuRenderPass.handle.drawIndexed(
         options.indexCount,
-        options.instanceCount,
-        options.firstIndex,
-        options.baseVertex,
-        options.firstInstance
+        instanceCount,
+        options.firstIndex || 0,
+        options.baseVertex || 0,
+        options.firstInstance || 0
       );
     } else {
       webgpuRenderPass.handle.draw(
         options.vertexCount || 0,
-        options.instanceCount || 1, // If 0, nothing will be drawn
-        options.firstInstance
+        instanceCount,
+        options.firstVertex || 0,
+        options.firstInstance || 0
       );
     }
 
@@ -136,7 +151,7 @@ export class WebGPURenderPipeline extends RenderPipeline {
   }
 
   /** Return a bind group created by setBindings */
-  _getBindGroup() {
+  _getBindGroup(bindings?: Record<string, Binding>) {
     if (this.shaderLayout.bindings.length === 0) {
       return null;
     }
@@ -144,11 +159,13 @@ export class WebGPURenderPipeline extends RenderPipeline {
     // Get hold of the bind group layout. We don't want to do this unless we know there is at least one bind group
     this._bindGroupLayout = this._bindGroupLayout || this.handle.getBindGroupLayout(0);
 
-    // Set up the bindings
-    // TODO what if bindings change? We need to rebuild the bind group!
+    if (bindings) {
+      return getBindGroup(this.device, this._bindGroupLayout, this.shaderLayout, bindings);
+    }
+
     this._bindGroup =
       this._bindGroup ||
-      getBindGroup(this.device.handle, this._bindGroupLayout, this.shaderLayout, this._bindings);
+      getBindGroup(this.device, this._bindGroupLayout, this.shaderLayout, this._bindings);
 
     return this._bindGroup;
   }

package/src/adapter/resources/webgpu-sampler.ts

@@ -40,6 +40,11 @@ export class WebGPUSampler extends Sampler {
   }
 
   override destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.destroyResource();
     // GPUSampler does not have a destroy method
     // this.handle.destroy();
     // @ts-expect-error readonly

package/src/adapter/resources/webgpu-texture-view.ts

@@ -5,6 +5,7 @@
 import {TextureView, TextureViewProps} from '@luma.gl/core';
 import type {WebGPUDevice} from '../webgpu-device';
 import type {WebGPUTexture} from './webgpu-texture';
+import {getCpuHotspotProfiler, getTimestamp} from '../helpers/cpu-hotspot-profiler';
 
 /*
   // type = sampler
@@ -39,17 +40,15 @@ export class WebGPUTextureView extends TextureView {
     this.texture = props.texture;
 
     this.device.pushErrorScope('validation');
-    this.handle =
-      // props.handle ||
-      this.texture.handle.createView({
-        format: (this.props.format || this.texture.format) as GPUTextureFormat,
-        dimension: this.props.dimension || this.texture.dimension,
-        aspect: this.props.aspect,
-        baseMipLevel: this.props.baseMipLevel,
-        mipLevelCount: this.props.mipLevelCount,
-        baseArrayLayer: this.props.baseArrayLayer,
-        arrayLayerCount: this.props.arrayLayerCount
-      });
+    this.handle = this.texture.handle.createView({
+      format: (this.props.format || this.texture.format) as GPUTextureFormat,
+      dimension: this.props.dimension || this.texture.dimension,
+      aspect: this.props.aspect,
+      baseMipLevel: this.props.baseMipLevel,
+      mipLevelCount: this.props.mipLevelCount,
+      baseArrayLayer: this.props.baseArrayLayer,
+      arrayLayerCount: this.props.arrayLayerCount
+    });
     this.device.popErrorScope((error: GPUError) => {
       this.device.reportError(new Error(`TextureView constructor: ${error.message}`), this)();
       this.device.debug();
@@ -59,9 +58,50 @@ export class WebGPUTextureView extends TextureView {
   }
 
   override destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.destroyResource();
     // GPUTextureView does not have a destroy method
     // this.handle.destroy();
     // @ts-expect-error readonly
     this.handle = null;
   }
+
+  /**
+   * Internal-only hook for the cached CanvasContext/PresentationContext swapchain path.
+   * Rebuilds the default view when the per-frame canvas texture handle changes, without
+   * replacing the long-lived luma.gl wrapper object.
+   */
+  _reinitialize(texture: WebGPUTexture): void {
+    // @ts-expect-error readonly
+    this.texture = texture;
+
+    const profiler = getCpuHotspotProfiler(this.device);
+    this.device.pushErrorScope('validation');
+    const createViewStartTime = profiler ? getTimestamp() : 0;
+    const handle = this.texture.handle.createView({
+      format: (this.props.format || this.texture.format) as GPUTextureFormat,
+      dimension: this.props.dimension || this.texture.dimension,
+      aspect: this.props.aspect,
+      baseMipLevel: this.props.baseMipLevel,
+      mipLevelCount: this.props.mipLevelCount,
+      baseArrayLayer: this.props.baseArrayLayer,
+      arrayLayerCount: this.props.arrayLayerCount
+    });
+    if (profiler) {
+      profiler.textureViewReinitializeCount = (profiler.textureViewReinitializeCount || 0) + 1;
+      profiler.textureViewReinitializeTimeMs =
+        (profiler.textureViewReinitializeTimeMs || 0) + (getTimestamp() - createViewStartTime);
+    }
+    this.device.popErrorScope((error: GPUError) => {
+      this.device.reportError(new Error(`TextureView constructor: ${error.message}`), this)();
+      this.device.debug();
+    });
+
+    handle.label = this.props.id;
+    // @ts-expect-error readonly
+    this.handle = handle;
+  }
 }