@luma.gl/core 9.3.0-alpha.6 → 9.3.0-alpha.8

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

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

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

@@ -138,7 +138,9 @@ type PassWithTimestamps = {
 };
 
 /**
- * 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 {

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/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';

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

@@ -4,12 +4,12 @@
 
 import type {Device} from '../device';
 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';
@@ -64,7 +64,9 @@ export type RenderPipelineProps = ResourceProps & {
 
   // Dynamic bindings (TODO - pipelines should be immutable, move to RenderPass)
   /** Buffers, Textures, Samplers for the shader bindings */
-  bindings?: Record<string, Binding>;
+  bindings?: Bindings;
+  /** Bindings grouped by bind-group index */
+  bindGroups?: BindingsByGroup;
 };
 
 /**
@@ -142,7 +144,11 @@ export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
     /** Transform feedback. WebGL only. */
     transformFeedback?: TransformFeedback;
     /** Bindings applied for this draw (textures, samplers, uniform buffers) */
-    bindings?: Record<string, Binding>;
+    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;
@@ -170,6 +176,7 @@ export abstract class RenderPipeline extends Resource<RenderPipelineProps> {
     bufferMode: undefined!,
     disableWarnings: false,
     _sharedRenderPipeline: undefined!,
-    bindings: undefined!
+    bindings: undefined!,
+    bindGroups: undefined!
   };
 }

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

@@ -4,7 +4,7 @@
 
 import type {Device} from '../device';
 import type {Texture} from './texture';
-import type {TextureFormat} from '../../shadertypes/textures/texture-formats';
+import type {TextureFormat} from '../../shadertypes/texture-types/texture-formats';
 import {Resource, ResourceProps} from './resource';
 
 /** Properties for initializing a texture view */

package/src/adapter/resources/texture.ts

@@ -8,14 +8,14 @@ import {
   type TextureFormat,
   type TextureMemoryLayout,
   type TextureFormatInfo
-} from '../../shadertypes/textures/texture-formats';
-import {type ExternalImage} from '../../image-utils/image-types';
+} from '../../shadertypes/texture-types/texture-formats';
+import {type ExternalImage} from '../../shadertypes/image-types/image-types';
 import {type TextureView, type TextureViewProps} from './texture-view';
 import {Resource, type ResourceProps} from './resource';
 import {Sampler, type SamplerProps} from './sampler';
 import {Buffer} from './buffer';
 import {log} from '../../utils/log';
-import {textureFormatDecoder} from '../../shadertypes/textures/texture-format-decoder';
+import {textureFormatDecoder} from '../../shadertypes/texture-types/texture-format-decoder';
 
 /** Options for Texture.copyExternalImage */
 export type CopyExternalImageOptions = {
@@ -325,8 +325,8 @@ export abstract class Texture extends Resource<TextureProps> {
    *
    * @note The memory layout of the texture data is determined by the texture format and dimensions.
    * @note The application can call Texture.computeMemoryLayout() to compute the backend-aligned layout.
-   * @note The application can call Buffer.readAsync()
-   * @note If not supplied a buffer will be created and the application needs to call Buffer.destroy
+   * @note The application can call Buffer.readAsync() to read the returned buffer on the CPU.
+   * @note The destination buffer must be supplied by the caller and must be large enough for the requested region.
    * @note On WebGPU this corresponds to a texture-to-buffer copy and uses buffer-copy alignment rules.
    * @note On WebGL, luma.gl emulates the same logical readback behavior.
    */
@@ -340,6 +340,7 @@ export abstract class Texture extends Resource<TextureProps> {
    *
    * @note The memory layout of the texture data is determined by the texture format and dimensions.
    * @note The application can call Texture.computeMemoryLayout() to compute the layout.
+   * @deprecated Use Texture.readBuffer() with an explicit destination buffer, or DynamicTexture.readAsync() for convenience readback.
    */
   readDataAsync(options?: TextureReadOptions): Promise<ArrayBuffer> {
     throw new Error('readBuffer not implemented');

package/src/adapter/types/attachments.ts

@@ -6,7 +6,7 @@ import type {
   TextureFormatColor,
   TextureFormatDepthStencil,
   TextureFormat
-} from '../../shadertypes/textures/texture-formats';
+} from '../../shadertypes/texture-types/texture-formats';
 import type {Texture} from '../resources/texture'; // TextureView...
 import type {TextureView} from '../resources/texture-view'; // TextureView...
 

package/src/adapter/types/buffer-layout.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {VertexFormat} from '../../shadertypes/vertex-arrays/vertex-formats';
+import type {VertexFormat} from '../../shadertypes/vertex-types/vertex-formats';
 
 /**
  * Provides specific details about the memory layout of the actual buffers

package/src/adapter/types/parameters.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {NumberArray4, NumberArray6} from '@math.gl/types';
-import {TextureFormatDepthStencil} from '../../shadertypes/textures/texture-formats';
+import {TextureFormatDepthStencil} from '../../shadertypes/texture-types/texture-formats';
 
 export type CompareFunction =
   | 'never'
@@ -102,6 +102,8 @@ export type DepthStencilParameters = {
   depthCompare?: CompareFunction;
   /** The format of depthStencilAttachment this GPURenderPipeline will be compatible with. */
   depthFormat?: TextureFormatDepthStencil;
+  /** Depth value used when clearing depth buffers. */
+  clearDepth?: number;
 
   /** Bitmask controlling which depthStencilAttachment stencil value bits are read when performing stencil comparison tests. */
   stencilReadMask?: number;
@@ -217,6 +219,7 @@ export const DEFAULT_PARAMETERS: Required<Parameters> = {
   depthWriteEnabled: false,
   depthCompare: 'always',
   depthFormat: 'depth24plus',
+  clearDepth: 1,
 
   depthBias: 0,
   depthBiasSlopeScale: 0,

package/src/adapter/types/shader-layout.ts

@@ -2,15 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {TextureFormat} from '../../shadertypes/textures/texture-formats';
-import type {
-  VariableShaderType,
-  AttributeShaderType
-} from '../../shadertypes/data-types/shader-types';
-import type {Buffer} from '../resources/buffer';
-import type {Sampler} from '../resources/sampler';
-import type {Texture} from '../resources/texture';
-import type {TextureView} from '../resources/texture-view';
+import {type TextureFormat} from '../../shadertypes/texture-types/texture-formats';
+import {
+  type VariableShaderType,
+  type AttributeShaderType
+} from '../../shadertypes/shader-types/shader-types';
+import {type Buffer} from '../resources/buffer';
+import {type Sampler} from '../resources/sampler';
+import {type Texture} from '../resources/texture';
+import {type TextureView} from '../resources/texture-view';
 
 /**
  * Describes all shader binding points for a `RenderPipeline` or `ComputePipeline`
@@ -166,6 +166,12 @@ export type Binding =
   | Buffer
   | {buffer: Buffer; offset?: number; size?: number};
 
+/** Named binding map */
+export type Bindings = Record<string, Binding>;
+
+/** Bindings partitioned by bind-group index */
+export type BindingsByGroup = Partial<Record<number, Bindings>>;
+
 // SHADER LAYOUTS
 
 /**

package/src/adapter/types/uniforms.ts

@@ -8,3 +8,15 @@ import {NumericArray} from '@math.gl/types';
 
 /** Valid values for uniforms. @note boolean values get converted to 0 or 1 before setting */
 export type UniformValue = number | boolean | Readonly<NumericArray>; // Float32Array> | Readonly<Int32Array> | Readonly<Uint32Array> | Readonly<number[]>;
+
+/** Recursive uniform value tree used by uniform-buffer packing utilities. */
+export type CompositeUniformValue =
+  | UniformValue
+  | CompositeUniformValueStruct
+  | CompositeUniformValueArray;
+
+export type CompositeUniformValueStruct = {
+  [name: string]: CompositeUniformValue | undefined;
+};
+
+export type CompositeUniformValueArray = ReadonlyArray<CompositeUniformValue | undefined>;

package/src/adapter-utils/bind-groups.ts

@@ -0,0 +1,71 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  BindingDeclaration,
+  Bindings,
+  BindingsByGroup,
+  ComputeShaderLayout,
+  ShaderLayout
+} from '../adapter/types/shader-layout';
+import {log} from '../utils/log';
+
+type AnyShaderLayout = Pick<ShaderLayout | ComputeShaderLayout, 'bindings'>;
+
+export function getShaderLayoutBinding(
+  shaderLayout: AnyShaderLayout,
+  bindingName: string,
+  options?: {ignoreWarnings?: boolean}
+): BindingDeclaration | null {
+  const bindingLayout = shaderLayout.bindings.find(
+    binding =>
+      binding.name === bindingName ||
+      `${binding.name.toLocaleLowerCase()}uniforms` === bindingName.toLocaleLowerCase()
+  );
+
+  if (!bindingLayout && !options?.ignoreWarnings) {
+    log.warn(`Binding ${bindingName} not set: Not found in shader layout.`)();
+  }
+
+  return bindingLayout || null;
+}
+
+export function normalizeBindingsByGroup(
+  shaderLayout: AnyShaderLayout,
+  bindingsOrBindGroups?: Bindings | BindingsByGroup
+): BindingsByGroup {
+  if (!bindingsOrBindGroups) {
+    return {};
+  }
+
+  if (areBindingsGrouped(bindingsOrBindGroups)) {
+    const bindGroups = bindingsOrBindGroups as BindingsByGroup;
+    return Object.fromEntries(
+      Object.entries(bindGroups).map(([group, bindings]) => [Number(group), {...bindings}])
+    ) as BindingsByGroup;
+  }
+
+  const bindGroups: BindingsByGroup = {};
+  for (const [bindingName, binding] of Object.entries(bindingsOrBindGroups as Bindings)) {
+    const bindingLayout = getShaderLayoutBinding(shaderLayout, bindingName);
+    const group = bindingLayout?.group ?? 0;
+    bindGroups[group] ||= {};
+    bindGroups[group][bindingName] = binding;
+  }
+
+  return bindGroups;
+}
+
+export function flattenBindingsByGroup(bindGroups: BindingsByGroup): Bindings {
+  const bindings: Bindings = {};
+  for (const groupBindings of Object.values(bindGroups)) {
+    Object.assign(bindings, groupBindings);
+  }
+  return bindings;
+}
+
+function areBindingsGrouped(bindingsOrBindGroups: Bindings | BindingsByGroup): boolean {
+  const keys = Object.keys(bindingsOrBindGroups);
+  return keys.length > 0 && keys.every(key => /^\d+$/.test(key));
+}

package/src/adapter-utils/get-attribute-from-layouts.ts

@@ -4,13 +4,10 @@
 
 import {log} from '../utils/log';
 import type {PrimitiveDataType, NormalizedDataType} from '../shadertypes/data-types/data-types';
-import type {AttributeShaderType} from '../shadertypes/data-types/shader-types';
-import type {VertexFormat} from '../shadertypes/vertex-arrays/vertex-formats';
-import {getAttributeShaderTypeInfo} from '../shadertypes/data-types/decode-shader-types';
-import {
-  getVertexFormatInfo,
-  getCompatibleVertexFormat
-} from '../shadertypes/vertex-arrays/decode-vertex-format';
+import type {AttributeShaderType} from '../shadertypes/shader-types/shader-types';
+import type {VertexFormat} from '../shadertypes/vertex-types/vertex-formats';
+import {shaderTypeDecoder} from '../shadertypes/shader-types/shader-type-decoder';
+import {vertexFormatDecoder} from '../shadertypes/vertex-types/vertex-format-decoder';
 import type {ShaderLayout, AttributeDeclaration} from '../adapter/types/shader-layout';
 import type {BufferLayout} from '../adapter/types/buffer-layout';
 
@@ -112,10 +109,10 @@ function getAttributeInfoFromLayouts(
     return null;
   }
 
-  const attributeTypeInfo = getAttributeShaderTypeInfo(shaderDeclaration.type);
-  const defaultVertexFormat = getCompatibleVertexFormat(attributeTypeInfo);
+  const attributeTypeInfo = shaderTypeDecoder.getAttributeShaderTypeInfo(shaderDeclaration.type);
+  const defaultVertexFormat = vertexFormatDecoder.getCompatibleVertexFormat(attributeTypeInfo);
   const vertexFormat = bufferMapping?.vertexFormat || defaultVertexFormat;
-  const vertexFormatInfo = getVertexFormatInfo(vertexFormat);
+  const vertexFormatInfo = vertexFormatDecoder.getVertexFormatInfo(vertexFormat);
 
   return {
     attributeName: bufferMapping?.attributeName || shaderDeclaration.name,
@@ -217,7 +214,7 @@ function getAttributeFromAttributesList(
     // Calculate a default byte stride if not provided
     if (typeof bufferLayout.byteStride !== 'number') {
       for (const attributeMapping of bufferLayout.attributes || []) {
-        const info = getVertexFormatInfo(attributeMapping.format);
+        const info = vertexFormatDecoder.getVertexFormatInfo(attributeMapping.format);
         // @ts-ignore
         byteStride += info.byteLength;
       }

package/src/factories/bind-group-factory.ts

@@ -0,0 +1,139 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {
+  Bindings,
+  BindingsByGroup,
+  ComputeShaderLayout,
+  ShaderLayout
+} from '../adapter/types/shader-layout';
+import type {Device} from '../adapter/device';
+import type {ComputePipeline} from '../adapter/resources/compute-pipeline';
+import type {RenderPipeline} from '../adapter/resources/render-pipeline';
+import {normalizeBindingsByGroup} from '../adapter-utils/bind-groups';
+
+type AnyPipeline = RenderPipeline | ComputePipeline;
+type AnyShaderLayout = ShaderLayout | ComputeShaderLayout;
+type BindGroupCacheKeys = Partial<Record<number, object>>;
+type BindGroupMap = Partial<Record<number, unknown>>;
+type LayoutCache = Partial<Record<number, object>>;
+type LayoutBindGroupCache = {
+  bindGroupsBySource: WeakMap<object, unknown | null>;
+  emptyBindGroup?: unknown;
+};
+
+export class BindGroupFactory {
+  readonly device: Device;
+
+  private readonly _layoutCacheByPipeline: WeakMap<AnyPipeline, LayoutCache> = new WeakMap();
+  private readonly _bindGroupCacheByLayout: WeakMap<object, LayoutBindGroupCache> = new WeakMap();
+
+  constructor(device: Device) {
+    this.device = device;
+  }
+
+  getBindGroups(
+    pipeline: AnyPipeline,
+    bindings?: Bindings | BindingsByGroup,
+    bindGroupCacheKeys?: BindGroupCacheKeys
+  ): BindGroupMap {
+    if (this.device.type !== 'webgpu' || pipeline.shaderLayout.bindings.length === 0) {
+      return {};
+    }
+
+    const bindingsByGroup = normalizeBindingsByGroup(pipeline.shaderLayout, bindings);
+    const resolvedBindGroups: BindGroupMap = {};
+
+    for (const group of getBindGroupIndicesUpToMax(pipeline.shaderLayout.bindings)) {
+      const groupBindings = bindingsByGroup[group];
+      const bindGroupLayout = this._getBindGroupLayout(pipeline, group);
+
+      if (!groupBindings || Object.keys(groupBindings).length === 0) {
+        if (!hasBindingsInGroup(pipeline.shaderLayout.bindings, group)) {
+          resolvedBindGroups[group] = this._getEmptyBindGroup(
+            bindGroupLayout,
+            pipeline.shaderLayout,
+            group
+          );
+        }
+        continue;
+      }
+
+      const bindGroupCacheKey = bindGroupCacheKeys?.[group];
+      if (bindGroupCacheKey) {
+        const layoutCache = this._getLayoutBindGroupCache(bindGroupLayout);
+        if (layoutCache.bindGroupsBySource.has(bindGroupCacheKey)) {
+          resolvedBindGroups[group] = layoutCache.bindGroupsBySource.get(bindGroupCacheKey) || null;
+          continue;
+        }
+
+        const bindGroup = this.device._createBindGroupWebGPU(
+          bindGroupLayout,
+          pipeline.shaderLayout,
+          groupBindings,
+          group
+        );
+        layoutCache.bindGroupsBySource.set(bindGroupCacheKey, bindGroup);
+        resolvedBindGroups[group] = bindGroup;
+      } else {
+        resolvedBindGroups[group] = this.device._createBindGroupWebGPU(
+          bindGroupLayout,
+          pipeline.shaderLayout,
+          groupBindings,
+          group
+        );
+      }
+    }
+
+    return resolvedBindGroups;
+  }
+
+  private _getBindGroupLayout(pipeline: AnyPipeline, group: number): object {
+    let layoutCache = this._layoutCacheByPipeline.get(pipeline);
+    if (!layoutCache) {
+      layoutCache = {};
+      this._layoutCacheByPipeline.set(pipeline, layoutCache);
+    }
+
+    layoutCache[group] ||= this.device._createBindGroupLayoutWebGPU(pipeline, group) as object;
+    return layoutCache[group];
+  }
+
+  private _getEmptyBindGroup(
+    bindGroupLayout: object,
+    shaderLayout: AnyShaderLayout,
+    group: number
+  ): unknown {
+    const layoutCache = this._getLayoutBindGroupCache(bindGroupLayout);
+    layoutCache.emptyBindGroup ||=
+      this.device._createBindGroupWebGPU(bindGroupLayout, shaderLayout, {}, group) || null;
+    return layoutCache.emptyBindGroup;
+  }
+
+  private _getLayoutBindGroupCache(bindGroupLayout: object): LayoutBindGroupCache {
+    let layoutCache = this._bindGroupCacheByLayout.get(bindGroupLayout);
+    if (!layoutCache) {
+      layoutCache = {bindGroupsBySource: new WeakMap()};
+      this._bindGroupCacheByLayout.set(bindGroupLayout, layoutCache);
+    }
+    return layoutCache;
+  }
+}
+
+export function _getDefaultBindGroupFactory(device: Device): BindGroupFactory {
+  device._factories.bindGroupFactory ||= new BindGroupFactory(device);
+  return device._factories.bindGroupFactory as BindGroupFactory;
+}
+
+function getBindGroupIndicesUpToMax(bindings: AnyShaderLayout['bindings']): number[] {
+  const maxGroup = bindings.reduce(
+    (highestGroup, binding) => Math.max(highestGroup, binding.group),
+    -1
+  );
+  return Array.from({length: maxGroup + 1}, (_, group) => group);
+}
+
+function hasBindingsInGroup(bindings: AnyShaderLayout['bindings'], group: number): boolean {
+  return bindings.some(binding => binding.group === group);
+}

package/src/factories/core-module-state.ts

@@ -0,0 +1,11 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PipelineFactory} from './pipeline-factory';
+import type {ShaderFactory} from './shader-factory';
+
+export type CoreModuleState = {
+  defaultPipelineFactory?: PipelineFactory;
+  defaultShaderFactory?: ShaderFactory;
+};