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

package/src/adapter/helpers/get-bind-group.ts

@@ -3,10 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 import type {ComputeShaderLayout, BindingDeclaration, Binding} from '@luma.gl/core';
-import {Buffer, Sampler, Texture, log} from '@luma.gl/core';
+import {Buffer, Sampler, Texture, TextureView, log} from '@luma.gl/core';
+import type {WebGPUDevice} from '../webgpu-device';
 import type {WebGPUBuffer} from '../resources/webgpu-buffer';
 import type {WebGPUSampler} from '../resources/webgpu-sampler';
 import type {WebGPUTexture} from '../resources/webgpu-texture';
+import type {WebGPUTextureView} from '../resources/webgpu-texture-view';
 
 /**
  * Create a WebGPU "bind group layout" from an array of luma.gl bindings
@@ -28,21 +30,19 @@ export function makeBindGroupLayout(
  * Create a WebGPU "bind group" from an array of luma.gl bindings
  */
 export function getBindGroup(
-  device: GPUDevice,
+  device: WebGPUDevice,
   bindGroupLayout: GPUBindGroupLayout,
   shaderLayout: ComputeShaderLayout,
   bindings: Record<string, Binding>
 ): GPUBindGroup {
   const entries = getBindGroupEntries(bindings, shaderLayout);
   device.pushErrorScope('validation');
-  const bindGroup = device.createBindGroup({
+  const bindGroup = device.handle.createBindGroup({
     layout: bindGroupLayout,
     entries
   });
-  device.popErrorScope().then((error: GPUError | null) => {
-    if (error) {
-      log.error(`bindGroup creation: ${error.message}`, bindGroup)();
-    }
+  device.popErrorScope((error: GPUError) => {
+    log.error(`bindGroup creation: ${error.message}`, bindGroup)();
   });
   return bindGroup;
 }
@@ -74,23 +74,31 @@ function getBindGroupEntries(
   const entries: GPUBindGroupEntry[] = [];
 
   for (const [bindingName, value] of Object.entries(bindings)) {
-    let bindingLayout = getShaderLayoutBinding(shaderLayout, bindingName);
-    if (bindingLayout) {
-      const entry = getBindGroupEntry(value, bindingLayout.location);
+    const exactBindingLayout = shaderLayout.bindings.find(binding => binding.name === bindingName);
+    const bindingLayout = exactBindingLayout || getShaderLayoutBinding(shaderLayout, bindingName);
+    const isShadowedAlias =
+      !exactBindingLayout && bindingLayout ? bindingLayout.name in bindings : false;
+
+    // Mirror the WebGL path: when both `foo` and `fooUniforms` exist in the bindings map,
+    // prefer the exact shader binding name and ignore the alias entry.
+    if (!isShadowedAlias) {
+      const entry = bindingLayout
+        ? getBindGroupEntry(value, bindingLayout.location, undefined, bindingName)
+        : null;
       if (entry) {
         entries.push(entry);
       }
-    }
 
-    // TODO - hack to automatically bind samplers to supplied texture default samplers
-    if (value instanceof Texture) {
-      bindingLayout = getShaderLayoutBinding(shaderLayout, `${bindingName}Sampler`, {
-        ignoreWarnings: true
-      });
-      if (bindingLayout) {
-        const entry = getBindGroupEntry(value, bindingLayout.location, {sampler: true});
-        if (entry) {
-          entries.push(entry);
+      // TODO - hack to automatically bind samplers to supplied texture default samplers
+      if (value instanceof Texture) {
+        const samplerBindingLayout = getShaderLayoutBinding(shaderLayout, `${bindingName}Sampler`, {
+          ignoreWarnings: true
+        });
+        const samplerEntry = samplerBindingLayout
+          ? getBindGroupEntry(value, samplerBindingLayout.location, {sampler: true}, bindingName)
+          : null;
+        if (samplerEntry) {
+          entries.push(samplerEntry);
         }
       }
     }
@@ -102,7 +110,8 @@ function getBindGroupEntries(
 function getBindGroupEntry(
   binding: Binding,
   index: number,
-  options?: {sampler?: boolean}
+  options?: {sampler?: boolean},
+  bindingName: string = 'unknown'
 ): GPUBindGroupEntry | null {
   if (binding instanceof Buffer) {
     return {
@@ -118,6 +127,12 @@ function getBindGroupEntry(
       resource: (binding as WebGPUSampler).handle
     };
   }
+  if (binding instanceof TextureView) {
+    return {
+      binding: index,
+      resource: (binding as WebGPUTextureView).handle
+    };
+  }
   if (binding instanceof Texture) {
     if (options?.sampler) {
       return {
@@ -130,6 +145,6 @@ function getBindGroupEntry(
       resource: (binding as WebGPUTexture).view.handle
     };
   }
-  log.warn(`invalid binding ${name}`, binding);
+  log.warn(`invalid binding ${bindingName}`, binding);
   return null;
 }

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

@@ -5,20 +5,28 @@
 import {log, Buffer, type BufferProps, type BufferMapCallback} from '@luma.gl/core';
 import {type WebGPUDevice} from '../webgpu-device';
 
+/**
+ * WebGPU implementation of Buffer
+ * For byte alignment requirements see:
+ * @see https://www.w3.org/TR/webgpu/#dom-gpubuffer-mapasync
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/mapAsync
+ */
 export class WebGPUBuffer extends Buffer {
   readonly device: WebGPUDevice;
   readonly handle: GPUBuffer;
   readonly byteLength: number;
+  readonly paddedByteLength: number;
 
   constructor(device: WebGPUDevice, props: BufferProps) {
     super(device, props);
     this.device = device;
 
     this.byteLength = props.byteLength || props.data?.byteLength || 0;
+    this.paddedByteLength = Math.ceil(this.byteLength / 4) * 4;
     const mappedAtCreation = Boolean(this.props.onMapped || props.data);
 
     // WebGPU buffers must be aligned to 4 bytes
-    const size = Math.ceil(this.byteLength / 4) * 4;
+    const size = this.paddedByteLength;
 
     this.device.pushErrorScope('out-of-memory');
     this.device.pushErrorScope('validation');
@@ -59,12 +67,27 @@ export class WebGPUBuffer extends Buffer {
       this.device.reportError(new Error(`${this} creation failed ${error.message}`), this)();
       this.device.debug();
     });
+
+    if (!this.props.handle) {
+      this.trackAllocatedMemory(size);
+    } else {
+      this.trackReferencedMemory(size, 'Buffer');
+    }
   }
 
   override destroy(): void {
-    this.handle?.destroy();
-    // @ts-expect-error readonly
-    this.handle = null;
+    if (!this.destroyed && this.handle) {
+      this.removeStats();
+      if (!this.props.handle) {
+        this.trackDeallocatedMemory();
+        this.handle.destroy();
+      } else {
+        this.trackDeallocatedReferencedMemory('Buffer');
+      }
+      this.destroyed = true;
+      // @ts-expect-error readonly
+      this.handle = null;
+    }
   }
 
   write(data: ArrayBufferLike | ArrayBufferView | SharedArrayBuffer, byteOffset = 0) {
@@ -92,10 +115,11 @@ export class WebGPUBuffer extends Buffer {
     byteOffset: number = 0,
     byteLength: number = this.byteLength - byteOffset
   ): Promise<void> {
+    const alignedByteLength = Math.ceil(byteLength / 4) * 4;
     // Unless the application created and supplied a mappable buffer, a staging buffer is needed
     const isMappable = (this.usage & Buffer.MAP_WRITE) !== 0;
     const mappableBuffer: WebGPUBuffer | null = !isMappable
-      ? this._getMappableBuffer(Buffer.MAP_WRITE | Buffer.COPY_SRC, 0, this.byteLength)
+      ? this._getMappableBuffer(Buffer.MAP_WRITE | Buffer.COPY_SRC, 0, this.paddedByteLength)
       : null;
 
     const writeBuffer = mappableBuffer || this;
@@ -105,13 +129,15 @@ export class WebGPUBuffer extends Buffer {
     this.device.pushErrorScope('validation');
     try {
       await this.device.handle.queue.onSubmittedWorkDone();
-      await writeBuffer.handle.mapAsync(GPUMapMode.WRITE, byteOffset, byteLength);
-      const arrayBuffer = writeBuffer.handle.getMappedRange(byteOffset, byteLength);
+      await writeBuffer.handle.mapAsync(GPUMapMode.WRITE, byteOffset, alignedByteLength);
+      const mappedRange = writeBuffer.handle.getMappedRange(byteOffset, alignedByteLength);
+      const arrayBuffer = mappedRange.slice(0, byteLength);
       // eslint-disable-next-line @typescript-eslint/await-thenable
       await callback(arrayBuffer, 'mapped');
+      new Uint8Array(mappedRange).set(new Uint8Array(arrayBuffer), 0);
       writeBuffer.handle.unmap();
       if (mappableBuffer) {
-        this._copyBuffer(mappableBuffer, byteOffset, byteLength);
+        this._copyBuffer(mappableBuffer, byteOffset, alignedByteLength);
       }
     } finally {
       this.device.popErrorScope((error: GPUError) => {
@@ -138,17 +164,33 @@ export class WebGPUBuffer extends Buffer {
     byteOffset = 0,
     byteLength = this.byteLength - byteOffset
   ): Promise<T> {
+    const requestedEnd = byteOffset + byteLength;
+    if (requestedEnd > this.byteLength) {
+      throw new Error('Mapping range exceeds buffer size');
+    }
+
+    let mappedByteOffset = byteOffset;
+    let mappedByteLength = byteLength;
+    let sliceByteOffset = 0;
+    let lifetime: 'mapped' | 'copied' = 'mapped';
+
+    // WebGPU mapAsync requires 8-byte offsets and 4-byte lengths.
     if (byteOffset % 8 !== 0 || byteLength % 4 !== 0) {
-      throw new Error('byteOffset must be multiple of 8 and byteLength multiple of 4');
+      mappedByteOffset = Math.floor(byteOffset / 8) * 8;
+      const alignedEnd = Math.ceil(requestedEnd / 4) * 4;
+      mappedByteLength = alignedEnd - mappedByteOffset;
+      sliceByteOffset = byteOffset - mappedByteOffset;
+      lifetime = 'copied';
     }
-    if (byteOffset + byteLength > this.handle.size) {
+
+    if (mappedByteOffset + mappedByteLength > this.paddedByteLength) {
       throw new Error('Mapping range exceeds buffer size');
     }
 
     // Unless the application created and supplied a mappable buffer, a staging buffer is needed
     const isMappable = (this.usage & Buffer.MAP_READ) !== 0;
     const mappableBuffer: WebGPUBuffer | null = !isMappable
-      ? this._getMappableBuffer(Buffer.MAP_READ | Buffer.COPY_DST, 0, this.byteLength)
+      ? this._getMappableBuffer(Buffer.MAP_READ | Buffer.COPY_DST, 0, this.paddedByteLength)
       : null;
 
     const readBuffer = mappableBuffer || this;
@@ -158,12 +200,16 @@ export class WebGPUBuffer extends Buffer {
     try {
       await this.device.handle.queue.onSubmittedWorkDone();
       if (mappableBuffer) {
-        mappableBuffer._copyBuffer(this);
+        mappableBuffer._copyBuffer(this, mappedByteOffset, mappedByteLength);
       }
-      await readBuffer.handle.mapAsync(GPUMapMode.READ, byteOffset, byteLength);
-      const arrayBuffer = readBuffer.handle.getMappedRange(byteOffset, byteLength);
+      await readBuffer.handle.mapAsync(GPUMapMode.READ, mappedByteOffset, mappedByteLength);
+      const arrayBuffer = readBuffer.handle.getMappedRange(mappedByteOffset, mappedByteLength);
+      const mappedRange =
+        lifetime === 'mapped'
+          ? arrayBuffer
+          : arrayBuffer.slice(sliceByteOffset, sliceByteOffset + byteLength);
       // eslint-disable-next-line @typescript-eslint/await-thenable
-      const result = await callback(arrayBuffer, 'mapped');
+      const result = await callback(mappedRange, lifetime);
       readBuffer.handle.unmap();
       return result;
     } finally {

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

@@ -13,7 +13,7 @@ export class WebGPUCommandBuffer extends CommandBuffer {
   readonly handle: GPUCommandBuffer;
 
   constructor(commandEncoder: WebGPUCommandEncoder, props: CommandBufferProps) {
-    super(commandEncoder.device, {});
+    super(commandEncoder.device, props);
     this.device = commandEncoder.device;
     this.handle =
       this.props.handle ||

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

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {
+  CommandBufferProps,
   RenderPassProps,
   ComputePassProps,
   CopyTextureToTextureOptions,
@@ -34,9 +35,11 @@ export class WebGPUCommandEncoder extends CommandEncoder {
     this.handle.label = this.props.id;
   }
 
-  override destroy(): void {}
+  override destroy(): void {
+    this.destroyResource();
+  }
 
-  finish(props?: CommandEncoderProps): WebGPUCommandBuffer {
+  finish(props?: CommandBufferProps): WebGPUCommandBuffer {
     this.device.pushErrorScope('validation');
     const commandBuffer = new WebGPUCommandBuffer(this, {
       id: props?.id || 'unnamed-command-buffer'
@@ -46,6 +49,7 @@ export class WebGPUCommandEncoder extends CommandEncoder {
       this.device.reportError(new Error(message), this)();
       this.device.debug();
     });
+    this.destroy();
     return commandBuffer;
   }
 
@@ -53,12 +57,12 @@ export class WebGPUCommandEncoder extends CommandEncoder {
    * Allows a render pass to begin against a canvas context
    * @todo need to support a "Framebuffer" equivalent (aka preconfigured RenderPassDescriptors?).
    */
-  beginRenderPass(props: RenderPassProps): WebGPURenderPass {
-    return new WebGPURenderPass(this.device, props);
+  beginRenderPass(props: RenderPassProps = {}): WebGPURenderPass {
+    return new WebGPURenderPass(this.device, this._applyTimeProfilingToPassProps(props));
   }
 
-  beginComputePass(props: ComputePassProps): WebGPUComputePass {
-    return new WebGPUComputePass(this.device, props);
+  beginComputePass(props: ComputePassProps = {}): WebGPUComputePass {
+    return new WebGPUComputePass(this.device, this._applyTimeProfilingToPassProps(props));
   }
 
   // beginRenderPass(GPURenderPassDescriptor descriptor): GPURenderPassEncoder;
@@ -174,6 +178,28 @@ export class WebGPUCommandEncoder extends CommandEncoder {
       options?.destinationOffset || 0
     );
   }
+
+  writeTimestamp(querySet: WebGPUQuerySet, queryIndex: number): void {
+    querySet._invalidateResults();
+    const writeTimestamp = (
+      this.handle as GPUCommandEncoder & {
+        writeTimestamp?: (querySet: GPUQuerySet, queryIndex: number) => void;
+      }
+    ).writeTimestamp;
+
+    if (writeTimestamp) {
+      writeTimestamp.call(this.handle, querySet.handle, queryIndex);
+      return;
+    }
+
+    const computePass = this.handle.beginComputePass({
+      timestampWrites: {
+        querySet: querySet.handle,
+        beginningOfPassWriteIndex: queryIndex
+      }
+    });
+    computePass.end();
+  }
 }
 
 /*

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

@@ -14,19 +14,21 @@ export class WebGPUComputePass extends ComputePass {
 
   _webgpuPipeline: WebGPUComputePipeline | null = null;
 
-  constructor(device: WebGPUDevice, props: ComputePassProps) {
+  constructor(device: WebGPUDevice, props: ComputePassProps = {}) {
     super(device, props);
     this.device = device;
+    const {props: computePassProps} = this;
 
     // Set up queries
     let timestampWrites: GPUComputePassTimestampWrites | undefined;
-    if (device.features.has('timestamp-query')) {
-      const webgpuQuerySet = props.timestampQuerySet as WebGPUQuerySet;
+    if (computePassProps.timestampQuerySet) {
+      const webgpuQuerySet = computePassProps.timestampQuerySet as WebGPUQuerySet;
       if (webgpuQuerySet) {
+        webgpuQuerySet._invalidateResults();
         timestampWrites = {
           querySet: webgpuQuerySet.handle,
-          beginningOfPassWriteIndex: props.beginTimestampIndex,
-          endOfPassWriteIndex: props.endTimestampIndex
+          beginningOfPassWriteIndex: computePassProps.beginTimestampIndex,
+          endOfPassWriteIndex: computePassProps.endTimestampIndex
         };
       }
     }
@@ -40,10 +42,16 @@ export class WebGPUComputePass extends ComputePass {
   }
 
   /** @note no WebGPU destroy method, just gc */
-  override destroy(): void {}
+  override destroy(): void {
+    this.destroyResource();
+  }
 
   end(): void {
+    if (this.destroyed) {
+      return;
+    }
     this.handle.end();
+    this.destroy();
   }
 
   setPipeline(pipeline: ComputePipeline): void {

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

@@ -7,6 +7,8 @@ import {getBindGroup} from '../helpers/get-bind-group';
 import {WebGPUDevice} from '../webgpu-device';
 import {WebGPUShader} from './webgpu-shader';
 
+const EMPTY_BINDINGS: Record<string, Binding> = {};
+
 // COMPUTE PIPELINE
 
 /** Creates a new compute pipeline when parameters change */
@@ -18,7 +20,7 @@ export class WebGPUComputePipeline extends ComputePipeline {
   private _bindGroupLayout: GPUBindGroupLayout | null = null;
   private _bindGroup: GPUBindGroup | null = null;
   /** For internal use to create BindGroups */
-  private _bindings: Record<string, Binding> = {};
+  private _bindings: Record<string, Binding>;
 
   constructor(device: WebGPUDevice, props: ComputePipelineProps) {
     super(device, props);
@@ -37,6 +39,8 @@ export class WebGPUComputePipeline extends ComputePipeline {
         },
         layout: 'auto'
       });
+
+    this._bindings = EMPTY_BINDINGS;
   }
 
   /**
@@ -44,7 +48,21 @@ export class WebGPUComputePipeline extends ComputePipeline {
    * @todo Do we want to expose BindGroups in the API and remove this?
    */
   setBindings(bindings: Record<string, Binding>): void {
-    Object.assign(this._bindings, bindings);
+    let bindingsChanged = false;
+    for (const [name, binding] of Object.entries(bindings)) {
+      if (this._bindings[name] !== binding) {
+        if (!bindingsChanged) {
+          if (this._bindings === EMPTY_BINDINGS) {
+            this._bindings = {};
+          }
+          bindingsChanged = true;
+        }
+        this._bindings[name] = binding;
+      }
+    }
+    if (bindingsChanged) {
+      this._bindGroup = null;
+    }
   }
 
   /** Return a bind group created by setBindings */
@@ -55,7 +73,7 @@ export class WebGPUComputePipeline extends ComputePipeline {
     // Set up the 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-framebuffer.ts

@@ -29,4 +29,25 @@ export class WebGPUFramebuffer extends Framebuffer {
   protected updateAttachments(): void {
     // WebGPU framebuffers are JS only objects, nothing to update
   }
+
+  /**
+   * Internal-only hook for the cached CanvasContext/PresentationContext swapchain path.
+   * Rebinds the long-lived default framebuffer wrapper to the current per-frame color view
+   * and optional depth attachment without allocating a new luma.gl Framebuffer object.
+   */
+  _reinitialize(
+    colorAttachment: WebGPUTextureView,
+    depthStencilAttachment: WebGPUTextureView | null
+  ): void {
+    this.colorAttachments[0] = colorAttachment;
+    // @ts-expect-error Internal-only canvas wrapper reuse mutates this otherwise-readonly attachment.
+    this.depthStencilAttachment = depthStencilAttachment;
+    this.width = colorAttachment.texture.width;
+    this.height = colorAttachment.texture.height;
+
+    this.props.width = this.width;
+    this.props.height = this.height;
+    this.props.colorAttachments = [colorAttachment.texture];
+    this.props.depthStencilAttachment = depthStencilAttachment?.texture || null;
+  }
 }

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

@@ -47,8 +47,7 @@ export class WebGPUPipelineLayout extends PipelineLayout {
     // TODO (kaapp): This only supports the first group, but so does the rest of the code
     const bindGroupEntries: GPUBindGroupLayoutEntry[] = [];
 
-    for (let i = 0; i < this.props.shaderLayout.bindings.length; i++) {
-      const binding = this.props.shaderLayout.bindings[i];
+    for (const binding of this.props.shaderLayout.bindings) {
       const bindingTypeInfo: Omit<GPUBindGroupLayoutEntry, 'binding' | 'visibility'> = {};
 
       switch (binding.type) {