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

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

@@ -2,11 +2,26 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {ComputeShaderLayout, BindingDeclaration, Binding} from '@luma.gl/core';
-import {Buffer, Sampler, Texture, log} from '@luma.gl/core';
+import type {
+  Binding,
+  BindingDeclaration,
+  Bindings,
+  ComputeShaderLayout,
+  ShaderLayout
+} from '@luma.gl/core';
+import {Buffer, Sampler, Texture, TextureView, getShaderLayoutBinding, 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';
+
+type AnyShaderLayout = ShaderLayout | ComputeShaderLayout;
+type BindGroupBindingSummary = {
+  name: string;
+  location: number;
+  type: string;
+};
 
 /**
  * Create a WebGPU "bind group layout" from an array of luma.gl bindings
@@ -15,7 +30,7 @@ import type {WebGPUTexture} from '../resources/webgpu-texture';
 export function makeBindGroupLayout(
   device: GPUDevice,
   layout: GPUBindGroupLayout,
-  bindings: Binding[]
+  bindings: Bindings
 ): GPUBindGroupLayout {
   throw new Error('not implemented');
   // return device.createBindGroupLayout({
@@ -28,39 +43,82 @@ 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);
+  shaderLayout: ShaderLayout | ComputeShaderLayout,
+  bindings: Bindings,
+  group: number,
+  label?: string
+): GPUBindGroup | null {
+  const entries = getBindGroupEntries(bindings, shaderLayout, group);
+  if (entries.length === 0) {
+    return null;
+  }
   device.pushErrorScope('validation');
-  const bindGroup = device.createBindGroup({
+  const bindGroup = device.handle.createBindGroup({
+    label,
     layout: bindGroupLayout,
     entries
   });
-  device.popErrorScope().then((error: GPUError | null) => {
-    if (error) {
-      log.error(`bindGroup creation: ${error.message}`, bindGroup)();
-    }
+  device.popErrorScope((error: GPUError) => {
+    const summary = formatBindGroupCreationErrorSummary(shaderLayout, bindings, entries, group);
+    log.error(`bindGroup creation: ${summary}\nRaw WebGPU error: ${error.message}`, bindGroup)();
   });
   return bindGroup;
 }
 
-export function getShaderLayoutBinding(
-  shaderLayout: ComputeShaderLayout,
-  bindingName: string,
-  options?: {ignoreWarnings?: boolean}
-): BindingDeclaration | null {
-  const bindingLayout = shaderLayout.bindings.find(
-    binding =>
-      binding.name === bindingName ||
-      `${binding.name.toLocaleLowerCase()}uniforms` === bindingName.toLocaleLowerCase()
+export function formatBindGroupCreationErrorSummary(
+  shaderLayout: AnyShaderLayout,
+  bindings: Bindings,
+  entries: GPUBindGroupEntry[],
+  group: number
+): string {
+  const expectedBindings = getExpectedBindingsForGroup(shaderLayout, group);
+  const expectedByLocation = new Map(
+    expectedBindings.map(bindingSummary => [bindingSummary.location, bindingSummary])
   );
-  if (!bindingLayout && !options?.ignoreWarnings) {
-    log.warn(`Binding ${bindingName} not set: Not found in shader layout.`)();
+  const providedBindings = entries
+    .map(entry => expectedByLocation.get(entry.binding) || getUnexpectedEntrySummary(entry))
+    .sort(compareBindingSummaries);
+  const missingBindings = expectedBindings.filter(
+    bindingSummary =>
+      !providedBindings.some(provided => provided.location === bindingSummary.location)
+  );
+  const unexpectedBindings = providedBindings.filter(
+    bindingSummary => !expectedByLocation.has(bindingSummary.location)
+  );
+  const unmatchedLogicalBindings = Object.keys(bindings)
+    .filter(bindingName => !resolveGroupBinding(bindingName, bindings, shaderLayout, group))
+    .sort();
+
+  const lines = [
+    `bindGroup creation failed for group ${group}: expected ${expectedBindings.length}, provided ${providedBindings.length}`,
+    `expected: ${formatBindingSummaryList(expectedBindings)}`,
+    `provided: ${formatBindingSummaryList(providedBindings)}`
+  ];
+
+  if (missingBindings.length > 0) {
+    lines.push(`missing: ${formatBindingSummaryList(missingBindings)}`);
+  }
+  if (unexpectedBindings.length > 0) {
+    lines.push(`unexpected entries: ${formatBindingSummaryList(unexpectedBindings)}`);
   }
-  return bindingLayout || null;
+  if (unmatchedLogicalBindings.length > 0) {
+    lines.push(`unmatched logical bindings: ${unmatchedLogicalBindings.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function getBindGroupLabel(
+  pipelineId: string,
+  shaderLayout: AnyShaderLayout,
+  group: number
+): string {
+  const expectedBindings = getExpectedBindingsForGroup(shaderLayout, group);
+  const bindingSuffix =
+    expectedBindings.length > 0 ? expectedBindings.map(binding => binding.name).join(',') : 'empty';
+  return `${pipelineId}/group${group}[${bindingSuffix}]`;
 }
 
 /**
@@ -68,29 +126,42 @@ export function getShaderLayoutBinding(
  * @returns
  */
 function getBindGroupEntries(
-  bindings: Record<string, Binding>,
-  shaderLayout: ComputeShaderLayout
+  bindings: Bindings,
+  shaderLayout: AnyShaderLayout,
+  group: number
 ): GPUBindGroupEntry[] {
   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 {bindingLayout, isShadowedAlias} = resolveGroupBinding(
+      bindingName,
+      bindings,
+      shaderLayout,
+      group
+    ) || {bindingLayout: null, isShadowedAlias: 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 && bindingLayout) {
+      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
+          ? samplerBindingLayout.group === group
+            ? getBindGroupEntry(value, samplerBindingLayout.location, {sampler: true}, bindingName)
+            : null
+          : null;
+        if (samplerEntry) {
+          entries.push(samplerEntry);
         }
       }
     }
@@ -102,7 +173,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 +190,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 +208,68 @@ function getBindGroupEntry(
       resource: (binding as WebGPUTexture).view.handle
     };
   }
-  log.warn(`invalid binding ${name}`, binding);
+  log.warn(`invalid binding ${bindingName}`, binding);
   return null;
 }
+
+function getExpectedBindingsForGroup(
+  shaderLayout: AnyShaderLayout,
+  group: number
+): BindGroupBindingSummary[] {
+  return shaderLayout.bindings
+    .filter(bindingLayout => bindingLayout.group === group)
+    .map(bindingLayout => toBindingSummary(bindingLayout))
+    .sort(compareBindingSummaries);
+}
+
+function resolveGroupBinding(
+  bindingName: string,
+  bindings: Bindings,
+  shaderLayout: AnyShaderLayout,
+  group: number
+): {bindingLayout: BindingDeclaration; isShadowedAlias: boolean} | null {
+  const exactBindingLayout = shaderLayout.bindings.find(binding => binding.name === bindingName);
+  const bindingLayout =
+    exactBindingLayout || getShaderLayoutBinding(shaderLayout, bindingName, {ignoreWarnings: true});
+  const isShadowedAlias =
+    !exactBindingLayout && bindingLayout ? bindingLayout.name in bindings : false;
+
+  if (isShadowedAlias || !bindingLayout || bindingLayout.group !== group) {
+    return null;
+  }
+
+  return {bindingLayout, isShadowedAlias};
+}
+
+function toBindingSummary(bindingLayout: BindingDeclaration): BindGroupBindingSummary {
+  return {
+    name: bindingLayout.name,
+    location: bindingLayout.location,
+    type: bindingLayout.type
+  };
+}
+
+function getUnexpectedEntrySummary(entry: GPUBindGroupEntry): BindGroupBindingSummary {
+  return {
+    name: '?',
+    location: entry.binding,
+    type: 'unknown'
+  };
+}
+
+function compareBindingSummaries(
+  left: BindGroupBindingSummary,
+  right: BindGroupBindingSummary
+): number {
+  if (left.location !== right.location) {
+    return left.location - right.location;
+  }
+  return left.name.localeCompare(right.name);
+}
+
+function formatBindingSummaryList(bindings: BindGroupBindingSummary[]): string {
+  if (bindings.length === 0) {
+    return 'none';
+  }
+  return bindings.map(binding => `${binding.name}@${binding.location}`).join(', ');
+}

package/src/adapter/helpers/get-vertex-buffer-layout.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {ShaderLayout, BufferLayout, AttributeDeclaration, VertexFormat} from '@luma.gl/core';
-import {log, getVertexFormatInfo} from '@luma.gl/core';
+import {log, vertexFormatDecoder} from '@luma.gl/core';
 // import {getAttributeInfosFromLayouts} from '@luma.gl/core';
 
 /** Throw error on any WebGL-only vertex formats */
@@ -23,10 +23,12 @@ function getWebGPUVertexFormat(format: VertexFormat): GPUVertexFormat {
  */
 export function getVertexBufferLayout(
   shaderLayout: ShaderLayout,
-  bufferLayout: BufferLayout[]
+  bufferLayout: BufferLayout[],
+  options?: {pipelineId?: string}
 ): GPUVertexBufferLayout[] {
   const vertexBufferLayouts: GPUVertexBufferLayout[] = [];
   const usedAttributes = new Set<string>();
+  const shaderAttributes = shaderLayout.attributes || [];
 
   // First handle any buffers mentioned in `bufferLayout`
   for (const mapping of bufferLayout) {
@@ -44,7 +46,12 @@ export function getVertexBufferLayout(
       // const arrayStride = mapping.byteStride; TODO
       for (const attributeMapping of mapping.attributes) {
         const attributeName = attributeMapping.attribute;
-        const attributeLayout = findAttributeLayout(shaderLayout, attributeName, usedAttributes);
+        const attributeLayout = findAttributeLayout(
+          shaderLayout,
+          attributeName,
+          usedAttributes,
+          options
+        );
 
         // @ts-ignore
         const location: number = attributeLayout?.location;
@@ -59,15 +66,20 @@ export function getVertexBufferLayout(
           shaderLocation: location
         });
 
-        byteStride += getVertexFormatInfo(format).byteLength;
+        byteStride += vertexFormatDecoder.getVertexFormatInfo(format).byteLength;
       }
       // non-interleaved mapping (just set offset and stride)
     } else {
-      const attributeLayout = findAttributeLayout(shaderLayout, mapping.name, usedAttributes);
+      const attributeLayout = findAttributeLayout(
+        shaderLayout,
+        mapping.name,
+        usedAttributes,
+        options
+      );
       if (!attributeLayout) {
         continue; // eslint-disable-line no-continue
       }
-      byteStride = getVertexFormatInfo(format).byteLength;
+      byteStride = vertexFormatDecoder.getVertexFormatInfo(format).byteLength;
 
       stepMode =
         attributeLayout.stepMode ||
@@ -89,10 +101,10 @@ export function getVertexBufferLayout(
   }
 
   // Add any non-mapped attributes - TODO - avoid hardcoded types
-  for (const attribute of shaderLayout.attributes) {
+  for (const attribute of shaderAttributes) {
     if (!usedAttributes.has(attribute.name)) {
       vertexBufferLayouts.push({
-        arrayStride: getVertexFormatInfo('float32x3').byteLength,
+        arrayStride: vertexFormatDecoder.getVertexFormatInfo('float32x3').byteLength,
         stepMode:
           attribute.stepMode || (attribute.name.startsWith('instance') ? 'instance' : 'vertex'),
         attributes: [
@@ -124,6 +136,7 @@ export function getBufferSlots(
   bufferLayout: BufferLayout[]
 ): Record<string, number> {
   const usedAttributes = new Set<string>();
+  const shaderAttributes = shaderLayout.attributes || [];
   let bufferSlot = 0;
   const bufferSlots: Record<string, number> = {};
 
@@ -142,7 +155,7 @@ export function getBufferSlots(
   }
 
   // Add any non-mapped attributes
-  for (const attribute of shaderLayout.attributes) {
+  for (const attribute of shaderAttributes) {
     if (!usedAttributes.has(attribute.name)) {
       bufferSlots[attribute.name] = bufferSlot++;
     }
@@ -159,11 +172,17 @@ export function getBufferSlots(
 function findAttributeLayout(
   shaderLayout: ShaderLayout,
   name: string,
-  attributeNames?: Set<string>
+  attributeNames?: Set<string>,
+  options?: {pipelineId?: string}
 ): AttributeDeclaration | null {
-  const attribute = shaderLayout.attributes.find(attribute_ => attribute_.name === name);
+  const attribute = shaderLayout.attributes?.find(attribute_ => attribute_.name === name);
   if (!attribute) {
-    log.warn(`Supplied attribute not present in shader layout: ${name}`)();
+    const pipelineContext = options?.pipelineId
+      ? `RenderPipeline(${options.pipelineId})`
+      : 'RenderPipeline';
+    log.warn(
+      `${pipelineContext}: Ignoring "${name}" attribute, since it is not present in shader layout.`
+    )();
     return null;
   }
   if (attributeNames) {

package/src/adapter/helpers/webgpu-parameters.ts

@@ -65,6 +65,8 @@ export const PARAMETER_TABLE: Record<keyof Parameters, Function> = {
     depthStencil.format = value;
   },
 
+  clearDepth: notSupported,
+
   depthBias: (_: keyof Parameters, value: any, descriptor: GPURenderPipelineDescriptor) => {
     const depthStencil = addDepthStencil(descriptor);
     depthStencil.depthBias = value;

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 ||