@luma.gl/engine 9.3.0-alpha.4 → 9.3.0-alpha.8

package/src/model/model.ts

@@ -3,19 +3,18 @@
 // Copyright (c) vis.gl contributors
 
 // A lot of imports, but then Model is where it all comes together...
-import type {TypedArray} from '@math.gl/types';
-import type {
-  RenderPipelineProps,
-  RenderPipelineParameters,
-  BufferLayout,
-  Shader,
-  VertexArray,
-  TransformFeedback,
-  AttributeInfo,
-  Binding,
-  PrimitiveTopology
-} from '@luma.gl/core';
+import {type TypedArray} from '@math.gl/types';
 import {
+  type RenderPipelineProps,
+  type RenderPipelineParameters,
+  type BufferLayout,
+  type Shader,
+  type VertexArray,
+  type TransformFeedback,
+  type AttributeInfo,
+  type Binding,
+  type BindingsByGroup,
+  type PrimitiveTopology,
   Device,
   DeviceFeature,
   Buffer,
@@ -24,27 +23,33 @@ import {
   Sampler,
   RenderPipeline,
   RenderPass,
+  PipelineFactory,
+  ShaderFactory,
   UniformStore,
   log,
-  getTypedArrayConstructor,
-  getAttributeInfosFromLayouts
+  dataTypeDecoder,
+  getAttributeInfosFromLayouts,
+  normalizeBindingsByGroup
 } from '@luma.gl/core';
 
-import type {ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
+import type {ShaderBindingDebugRow, ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
 import {ShaderAssembler} from '@luma.gl/shadertools';
 
 import type {Geometry} from '../geometry/geometry';
 import {GPUGeometry, makeGPUGeometry} from '../geometry/gpu-geometry';
-import {PipelineFactory} from '../factories/pipeline-factory';
-import {ShaderFactory} from '../factories/shader-factory';
 import {getDebugTableForShaderLayout} from '../debug/debug-shader-layout';
 import {debugFramebuffer} from '../debug/debug-framebuffer';
 import {deepEqual} from '../utils/deep-equal';
 import {BufferLayoutHelper} from '../utils/buffer-layout-helper';
 import {sortedBufferLayoutByShaderSourceLocations} from '../utils/buffer-layout-order';
+import {
+  mergeShaderModuleBindingsIntoLayout,
+  shaderModuleHasUniforms
+} from '../utils/shader-module-utils';
 import {uid} from '../utils/uid';
 import {ShaderInputs} from '../shader-inputs';
 import {DynamicTexture} from '../dynamic-texture/dynamic-texture';
+import {Material} from '../material/material';
 
 const LOG_DRAW_PRIORITY = 2;
 const LOG_DRAW_TIMEOUT = 10000;
@@ -62,8 +67,12 @@ export type ModelProps = Omit<RenderPipelineProps, 'vs' | 'fs' | 'bindings'> & {
 
   /** Shader inputs, used to generated uniform buffers and bindings */
   shaderInputs?: ShaderInputs;
+  /** Material-owned group-3 bindings */
+  material?: Material;
   /** Bindings */
   bindings?: Record<string, Binding | DynamicTexture>;
+  /** WebGL-only uniforms */
+  uniforms?: Record<string, unknown>;
   /** Parameters that are built into the pipeline */
   parameters?: RenderPipelineParameters;
 
@@ -114,7 +123,7 @@ export type ModelProps = Omit<RenderPipelineProps, 'vs' | 'fs' | 'bindings'> & {
  * - Reuses and lazily recompiles {@link RenderPipeline | pipelines} as needed.
  * - Integrates with `@luma.gl/shadertools` to assemble GLSL or WGSL from shader modules.
  * - Manages geometry attributes and buffer bindings.
- * - Accepts textures, samplers and uniform buffers as bindings, including `AsyncTexture`.
+ * - Accepts textures, samplers and uniform buffers as bindings, including `DynamicTexture`.
  * - Provides detailed debug logging and optional shader source inspection.
  */
 export class Model {
@@ -132,6 +141,8 @@ export class Model {
     indexBuffer: null,
     attributes: {},
     constantAttributes: {},
+    bindings: {},
+    uniforms: {},
     varyings: [],
 
     isInstanced: undefined!,
@@ -139,6 +150,7 @@ export class Model {
     vertexCount: 0,
 
     shaderInputs: undefined!,
+    material: undefined!,
     pipelineFactory: undefined!,
     shaderFactory: undefined!,
     transformFeedback: undefined!,
@@ -212,6 +224,7 @@ export class Model {
   /** ShaderInputs instance */
   // @ts-expect-error Assigned in function called by constructor
   shaderInputs: ShaderInputs;
+  material: Material | null = null;
   // @ts-expect-error Assigned in function called by constructor
   _uniformStore: UniformStore;
 
@@ -225,6 +238,7 @@ export class Model {
 
   /** "Time" of last draw. Monotonically increasing timestamp */
   _lastDrawTimestamp: number = -1;
+  private _bindingTable: ShaderBindingDebugRow[] = [];
 
   get [Symbol.toStringTag](): string {
     return 'Model';
@@ -242,6 +256,8 @@ export class Model {
 
     Object.assign(this.userData, props.userData);
 
+    this.material = props.material || null;
+
     // Setup shader module inputs
     const moduleMap = Object.fromEntries(
       this.props.modules?.map(module => [module.name, module]) || []
@@ -261,6 +277,9 @@ export class Model {
       // @ts-ignore shaderInputs is assigned in setShaderInputs above.
       (this.props.modules?.length > 0 ? this.props.modules : this.shaderInputs?.getModules()) || [];
 
+    this.props.shaderLayout =
+      mergeShaderModuleBindingsIntoLayout(this.props.shaderLayout, modules) || null;
+
     const isWebGPU = this.device.type === 'webgpu';
 
     // WebGPU
@@ -268,7 +287,7 @@ export class Model {
     // TODO - this is wrong, compile a single shader
     if (isWebGPU && this.props.source) {
       // WGSL
-      const {source, getUniforms} = this.props.shaderAssembler.assembleWGSLShader({
+      const {source, getUniforms, bindingTable} = this.props.shaderAssembler.assembleWGSLShader({
         platformInfo,
         ...this.props,
         modules
@@ -276,9 +295,16 @@ export class Model {
       this.source = source;
       // @ts-expect-error
       this._getModuleUniforms = getUniforms;
+      this._bindingTable = bindingTable;
       // Extract shader layout after modules have been added to WGSL source, to include any bindings added by modules
-      // @ts-expect-error Method on WebGPUDevice
-      this.props.shaderLayout ||= device.getShaderLayout(this.source);
+      const inferredShaderLayout = (
+        device as Device & {getShaderLayout?: (source: string) => any}
+      ).getShaderLayout?.(this.source);
+      this.props.shaderLayout =
+        mergeShaderModuleBindingsIntoLayout(
+          this.props.shaderLayout || inferredShaderLayout || null,
+          modules
+        ) || null;
     } else {
       // GLSL
       const {vs, fs, getUniforms} = this.props.shaderAssembler.assembleGLSLShaderPair({
@@ -291,6 +317,7 @@ export class Model {
       this.fs = fs;
       // @ts-expect-error
       this._getModuleUniforms = getUniforms;
+      this._bindingTable = [];
     }
 
     this.vertexCount = this.props.vertexCount;
@@ -357,7 +384,7 @@ export class Model {
       this.pipelineFactory.release(this.pipeline);
       // Release the shaders
       this.shaderFactory.release(this.pipeline.vs);
-      if (this.pipeline.fs) {
+      if (this.pipeline.fs && this.pipeline.fs !== this.pipeline.vs) {
         this.shaderFactory.release(this.pipeline.fs);
       }
       this._uniformStore.destroy();
@@ -385,6 +412,11 @@ export class Model {
     this._needsRedraw ||= reason;
   }
 
+  /** Returns WGSL binding debug rows for the assembled shader. Returns an empty array for GLSL models. */
+  getBindingDebugTable(): readonly ShaderBindingDebugRow[] {
+    return this._bindingTable;
+  }
+
   /** Update uniforms and pipeline state prior to drawing. */
   predraw(): void {
     // Update uniform buffers if needed
@@ -422,14 +454,8 @@ export class Model {
       // Application can call Model.predraw() to avoid this.
       this.pipeline = this._updatePipeline();
 
-      // Set pipeline state, we may be sharing a pipeline so we need to set all state on every draw
-      // Any caching needs to be done inside the pipeline functions
-      // TODO this is a busy initialized check for all bindings every frame
-
       const syncBindings = this._getBindings();
-      this.pipeline.setBindings(syncBindings, {
-        disableWarnings: this.props.disableWarnings
-      });
+      const syncBindGroups = this._getBindGroups();
 
       const {indexBuffer} = this.vertexArray;
       const indexCount = indexBuffer
@@ -444,6 +470,13 @@ export class Model {
         instanceCount: this.instanceCount,
         indexCount,
         transformFeedback: this.transformFeedback || undefined,
+        // Pipelines may be shared across models when caching is enabled, so bindings
+        // and WebGL uniforms must be supplied on every draw instead of being stored
+        // on the pipeline instance.
+        bindings: syncBindings,
+        bindGroups: syncBindGroups,
+        _bindGroupCacheKeys: this._getBindGroupCacheKeys(),
+        uniforms: this.props.uniforms,
         // WebGL shares underlying cached pipelines even for models that have different parameters and topology,
         // so we must provide our unique parameters to each draw
         // (In WebGPU most parameters are encoded in the pipeline and cannot be changed per draw call)
@@ -571,7 +604,7 @@ export class Model {
     this._uniformStore = new UniformStore(this.shaderInputs.modules);
     // Create uniform buffer bindings for all modules that actually have uniforms
     for (const [moduleName, module] of Object.entries(this.shaderInputs.modules)) {
-      if (shaderModuleHasUniforms(module)) {
+      if (shaderModuleHasUniforms(module) && !this.material?.ownsModule(moduleName)) {
         const uniformBuffer = this._uniformStore.getManagedUniformBuffer(this.device, moduleName);
         this.bindings[`${moduleName}Uniforms`] = uniformBuffer;
       }
@@ -579,10 +612,15 @@ export class Model {
     this.setNeedsRedraw('shaderInputs');
   }
 
+  setMaterial(material: Material | null): void {
+    this.material = material;
+    this.setNeedsRedraw('material');
+  }
+
   /** Update uniform buffers from the model's shader inputs */
   updateShaderInputs(): void {
     this._uniformStore.setUniforms(this.shaderInputs.getUniformValues());
-    this.setBindings(this.shaderInputs.getBindingValues());
+    this.setBindings(this._getNonMaterialBindings(this.shaderInputs.getBindingValues()));
     // TODO - this is already tracked through buffer/texture update times?
     this.setNeedsRedraw('shaderInputs');
   }
@@ -701,6 +739,11 @@ export class Model {
         return binding.id;
       }
     }
+    for (const binding of Object.values(this.material?.bindings || {})) {
+      if (binding instanceof DynamicTexture && !binding.isReady) {
+        return binding.id;
+      }
+    }
     return false;
   }
 
@@ -722,6 +765,32 @@ export class Model {
     return validBindings;
   }
 
+  _getBindGroups(): BindingsByGroup {
+    const shaderLayout = this.pipeline?.shaderLayout || this.props.shaderLayout || {bindings: []};
+    const bindGroups = shaderLayout.bindings.length
+      ? normalizeBindingsByGroup(shaderLayout, this._getBindings())
+      : {0: this._getBindings()};
+
+    if (!this.material) {
+      return bindGroups;
+    }
+
+    for (const [groupKey, groupBindings] of Object.entries(this.material.getBindingsByGroup())) {
+      const group = Number(groupKey);
+      bindGroups[group] = {
+        ...(bindGroups[group] || {}),
+        ...groupBindings
+      };
+    }
+
+    return bindGroups;
+  }
+
+  _getBindGroupCacheKeys(): Partial<Record<number, object>> {
+    const bindGroupCacheKey = this.material?.getBindGroupCacheKey(3);
+    return bindGroupCacheKey ? {3: bindGroupCacheKey} : {};
+  }
+
   /** Get the timestamp of the latest updated bound GPU memory resource (buffer/texture). */
   _getBindingsUpdateTimestamp(): number {
     let timestamp = 0;
@@ -739,7 +808,7 @@ export class Model {
         timestamp = Math.max(timestamp, binding.buffer.updateTimestamp);
       }
     }
-    return timestamp;
+    return Math.max(timestamp, this.material?.getBindingsUpdateTimestamp() || 0);
   }
 
   /**
@@ -811,12 +880,11 @@ export class Model {
 
       this.pipeline = this.pipelineFactory.createRenderPipeline({
         ...this.props,
+        bindings: undefined,
         bufferLayout: this.bufferLayout,
         topology: this.topology,
         parameters: this.parameters,
-        // TODO - why set bindings here when we reset them every frame?
-        // Should we expose a BindGroup abstraction?
-        bindings: this._getBindings(),
+        bindGroups: this._getBindGroups(),
         vs,
         fs
       });
@@ -827,7 +895,9 @@ export class Model {
       );
 
       if (prevShaderVs) this.shaderFactory.release(prevShaderVs);
-      if (prevShaderFs) this.shaderFactory.release(prevShaderFs);
+      if (prevShaderFs && prevShaderFs !== prevShaderVs) {
+        this.shaderFactory.release(prevShaderFs);
+      }
     }
     return this.pipeline;
   }
@@ -915,15 +985,27 @@ export class Model {
 
   // TODO - fix typing of luma data types
   _getBufferOrConstantValues(attribute: Buffer | TypedArray, dataType: any): string {
-    const TypedArrayConstructor = getTypedArrayConstructor(dataType);
+    const TypedArrayConstructor = dataTypeDecoder.getTypedArrayConstructor(dataType);
     const typedArray =
       attribute instanceof Buffer ? new TypedArrayConstructor(attribute.debugData) : attribute;
     return typedArray.toString();
   }
-}
 
-function shaderModuleHasUniforms(module: ShaderModule): boolean {
-  return Boolean(module.uniformTypes && !isObjectEmpty(module.uniformTypes));
+  private _getNonMaterialBindings(
+    bindings: Record<string, Binding | DynamicTexture>
+  ): Record<string, Binding | DynamicTexture> {
+    if (!this.material) {
+      return bindings;
+    }
+
+    const filteredBindings: Record<string, Binding | DynamicTexture> = {};
+    for (const [name, binding] of Object.entries(bindings)) {
+      if (!this.material.ownsBinding(name)) {
+        filteredBindings[name] = binding;
+      }
+    }
+    return filteredBindings;
+  }
 }
 
 // HELPERS
@@ -939,13 +1021,3 @@ export function getPlatformInfo(device: Device): PlatformInfo {
     features: device.features as unknown as Set<DeviceFeature>
   };
 }
-
-/** Returns true if given object is empty, false otherwise. */
-function isObjectEmpty(obj: object): boolean {
-  // @ts-ignore key is unused
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  for (const key in obj) {
-    return false;
-  }
-  return true;
-}

package/src/model/split-uniforms-and-bindings.ts

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {UniformValue, Binding} from '@luma.gl/core';
+import type {Binding, CompositeShaderType, UniformValue} from '@luma.gl/core';
+import type {ShaderModuleUniformValue} from '@luma.gl/shadertools';
 import {isNumericArray} from '@math.gl/types';
 
 export function isUniformValue(value: unknown): value is UniformValue {
@@ -11,19 +12,20 @@ export function isUniformValue(value: unknown): value is UniformValue {
 
 type UniformsAndBindings = {
   bindings: Record<string, Binding>;
-  uniforms: Record<string, UniformValue>;
+  uniforms: Record<string, ShaderModuleUniformValue>;
 };
 
 export function splitUniformsAndBindings(
-  uniforms: Record<string, Binding | UniformValue>
+  uniforms: Record<string, Binding | ShaderModuleUniformValue>,
+  uniformTypes: Readonly<Record<string, CompositeShaderType>> = {}
 ): UniformsAndBindings {
   const result: UniformsAndBindings = {bindings: {}, uniforms: {}};
   Object.keys(uniforms).forEach(name => {
     const uniform = uniforms[name];
-    if (isUniformValue(uniform)) {
-      result.uniforms[name] = uniform;
+    if (Object.prototype.hasOwnProperty.call(uniformTypes, name) || isUniformValue(uniform)) {
+      result.uniforms[name] = uniform as ShaderModuleUniformValue;
     } else {
-      result.bindings[name] = uniform;
+      result.bindings[name] = uniform as Binding;
     }
   });
 

package/src/models/billboard-texture-model.ts

@@ -22,15 +22,15 @@ struct backgroundUniforms {
 };
 @group(0) @binding(2) var<uniform> background: backgroundUniforms;
 
-fn billboardTexture_getTextureUV(coordinates: vec2<f32>) -> vec2<f32> {
+fn billboardTexture_getTextureUV(uv: vec2<f32>) -> vec2<f32> {
         let scale: vec2<f32> = background.scale;
-        var position: vec2<f32> = (coordinates - vec2<f32>(0.5, 0.5)) / scale + vec2<f32>(0.5, 0.5);
+        var position: vec2<f32> = (uv - vec2<f32>(0.5, 0.5)) / scale + vec2<f32>(0.5, 0.5);
         return position;
 }
 
 @fragment
 fn fragmentMain(inputs: FragmentInputs) -> @location(0) vec4<f32> {
-        let position: vec2<f32> = billboardTexture_getTextureUV(inputs.coordinate);
+        let position: vec2<f32> = billboardTexture_getTextureUV(inputs.uv);
         return textureSample(backgroundTexture, backgroundTextureSampler, position);
 }
 `;
@@ -79,21 +79,23 @@ export class BackgroundTextureModel extends ClipSpace {
 
   constructor(device: Device, props: BackgroundTextureModelProps) {
     super(device, {
+      ...props,
       id: props.id || 'background-texture-model',
       source: BACKGROUND_FS_WGSL,
       fs: BACKGROUND_FS,
-      modules: [backgroundModule],
+      modules: [...(props.modules || []), backgroundModule],
       parameters: {
         depthWriteEnabled: false,
+        ...(props.parameters || {}),
         ...(props.blend
           ? {
               blend: true,
               blendColorOperation: 'add',
               blendAlphaOperation: 'add',
-              blendColorSrcFactor: 'one',
-              blendColorDstFactor: 'one-minus-src',
-              blendAlphaSrcFactor: 'one',
-              blendAlphaDstFactor: 'one-minus-src-alpha'
+              blendColorSrcFactor: 'one-minus-dst-alpha',
+              blendColorDstFactor: 'one',
+              blendAlphaSrcFactor: 'one-minus-dst-alpha',
+              blendAlphaDstFactor: 'one'
             }
           : {})
       }

package/src/models/clip-space.ts

@@ -10,9 +10,9 @@ import {uid} from '../utils/uid';
 
 const CLIPSPACE_VERTEX_SHADER_WGSL = /* wgsl */ `\
 struct VertexInputs {
-  @location(0) clipSpacePosition: vec2<f32>,
-  @location(1) texCoord: vec2<f32>,
-  @location(2) coordinate: vec2<f32>  
+  @location(0) clipSpacePositions: vec2<f32>,
+  @location(1) texCoords: vec2<f32>,
+  @location(2) coordinates: vec2<f32>
 }
 
 struct FragmentInputs {
@@ -25,10 +25,10 @@ struct FragmentInputs {
 @vertex
 fn vertexMain(inputs: VertexInputs) -> FragmentInputs {
   var outputs: FragmentInputs;
-  outputs.Position = vec4(inputs.clipSpacePosition, 0., 1.);
-  outputs.position = inputs.clipSpacePosition;
-  outputs.coordinate = inputs.coordinate;
-  outputs.uv = inputs.texCoord;
+  outputs.Position = vec4(inputs.clipSpacePositions, 0., 1.);
+  outputs.position = inputs.clipSpacePositions;
+  outputs.coordinate = inputs.coordinates;
+  outputs.uv = inputs.texCoords;
   return outputs;
 }
 `;

package/src/models/directional-light-model.ts

@@ -0,0 +1,32 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Device} from '@luma.gl/core';
+import {ConeGeometry} from '../geometries/cone-geometry';
+import {
+  BaseLightModel,
+  buildDirectionalLightInstanceData,
+  type DirectionalLightModelProps
+} from './light-model-utils';
+
+const DIRECTIONAL_LIGHT_GEOMETRY = new ConeGeometry({
+  cap: true,
+  nradial: 12,
+  nvertical: 1,
+  radius: 1
+});
+
+export type {DirectionalLightModelProps} from './light-model-utils';
+
+export class DirectionalLightModel extends BaseLightModel<DirectionalLightModelProps> {
+  constructor(device: Device, props: DirectionalLightModelProps) {
+    super(device, props, {
+      anchorMode: 'apex',
+      buildInstanceData: buildDirectionalLightInstanceData,
+      geometry: DIRECTIONAL_LIGHT_GEOMETRY,
+      idPrefix: 'directional-light-model',
+      sizePropNames: ['directionalLightLength']
+    });
+  }
+}