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

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,30 +23,37 @@ 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 {ShaderAssembler, getShaderLayoutFromWGSL} 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 {AsyncTexture} from '../async-texture/async-texture';
+import {DynamicTexture} from '../dynamic-texture/dynamic-texture';
+import {Material} from '../material/material';
 
 const LOG_DRAW_PRIORITY = 2;
 const LOG_DRAW_TIMEOUT = 10000;
+const PIPELINE_INITIALIZATION_FAILED = 'render pipeline initialization failed';
 
 export type ModelProps = Omit<RenderPipelineProps, 'vs' | 'fs' | 'bindings'> & {
   source?: string;
@@ -62,8 +68,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 | AsyncTexture>;
+  bindings?: Record<string, Binding | DynamicTexture>;
+  /** WebGL-only uniforms */
+  uniforms?: Record<string, unknown>;
   /** Parameters that are built into the pipeline */
   parameters?: RenderPipelineParameters;
 
@@ -103,12 +113,19 @@ export type ModelProps = Omit<RenderPipelineProps, 'vs' | 'fs' | 'bindings'> & {
 };
 
 /**
- * v9 Model API
- * A model
- * - automatically reuses pipelines (programs) when possible
- * - automatically rebuilds pipelines if necessary to accommodate changed settings
- * shadertools integration
- * - accepts modules and performs shader transpilation
+ * High level draw API for luma.gl.
+ *
+ * A `Model` encapsulates shaders, geometry attributes, bindings and render
+ * pipeline state into a single object. It automatically reuses and rebuilds
+ * pipelines as render parameters change and exposes convenient hooks for
+ * updating uniforms and attributes.
+ *
+ * Features:
+ * - 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 `DynamicTexture`.
+ * - Provides detailed debug logging and optional shader source inspection.
  */
 export class Model {
   static defaultProps: Required<ModelProps> = {
@@ -125,6 +142,8 @@ export class Model {
     indexBuffer: null,
     attributes: {},
     constantAttributes: {},
+    bindings: {},
+    uniforms: {},
     varyings: [],
 
     isInstanced: undefined!,
@@ -132,6 +151,7 @@ export class Model {
     vertexCount: 0,
 
     shaderInputs: undefined!,
+    material: undefined!,
     pipelineFactory: undefined!,
     shaderFactory: undefined!,
     transformFeedback: undefined!,
@@ -141,16 +161,24 @@ export class Model {
     disableWarnings: undefined!
   };
 
+  /** Device that created this model */
   readonly device: Device;
+  /** Application provided identifier */
   readonly id: string;
+  /** WGSL shader source when using unified shader */
   // @ts-expect-error assigned in function called from constructor
   readonly source: string;
+  /** GLSL vertex shader source */
   // @ts-expect-error assigned in function called from constructor
   readonly vs: string;
+  /** GLSL fragment shader source */
   // @ts-expect-error assigned in function called from constructor
   readonly fs: string;
+  /** Factory used to create render pipelines */
   readonly pipelineFactory: PipelineFactory;
+  /** Factory used to create shaders */
   readonly shaderFactory: ShaderFactory;
+  /** User-supplied per-model data */
   userData: {[key: string]: any} = {};
 
   // Fixed properties (change can trigger pipeline rebuild)
@@ -179,7 +207,7 @@ export class Model {
   /** Constant-valued attributes */
   constantAttributes: Record<string, TypedArray> = {};
   /** Bindings (textures, samplers, uniform buffers) */
-  bindings: Record<string, Binding | AsyncTexture> = {};
+  bindings: Record<string, Binding | DynamicTexture> = {};
 
   /**
    * VertexArray
@@ -197,6 +225,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;
 
@@ -210,6 +239,7 @@ export class Model {
 
   /** "Time" of last draw. Monotonically increasing timestamp */
   _lastDrawTimestamp: number = -1;
+  private _bindingTable: ShaderBindingDebugRow[] = [];
 
   get [Symbol.toStringTag](): string {
     return 'Model';
@@ -227,6 +257,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]) || []
@@ -246,6 +278,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
@@ -253,7 +288,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
@@ -261,8 +296,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
-      this.props.shaderLayout ||= getShaderLayoutFromWGSL(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({
@@ -275,6 +318,7 @@ export class Model {
       this.fs = fs;
       // @ts-expect-error
       this._getModuleUniforms = getUniforms;
+      this._bindingTable = [];
     }
 
     this.vertexCount = this.props.vertexCount;
@@ -333,9 +377,6 @@ export class Model {
     if (props.transformFeedback) {
       this.transformFeedback = props.transformFeedback;
     }
-
-    // Catch any access to non-standard props
-    Object.seal(this);
   }
 
   destroy(): void {
@@ -344,7 +385,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();
@@ -372,6 +413,12 @@ 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
     this.updateShaderInputs();
@@ -379,6 +426,11 @@ export class Model {
     this.pipeline = this._updatePipeline();
   }
 
+  /**
+   * Issue one draw call.
+   * @param renderPass - render pass to draw into
+   * @returns `true` if the draw call was executed, `false` if resources were not ready.
+   */
   draw(renderPass: RenderPass): boolean {
     const loadingBinding = this._areBindingsLoading();
     if (loadingBinding) {
@@ -394,6 +446,7 @@ export class Model {
     }
 
     let drawSuccess: boolean;
+    let pipelineErrored = this.pipeline.isErrored;
     try {
       renderPass.pushDebugGroup(`${this}.draw(${renderPass})`);
       this._logDrawCallStart();
@@ -402,35 +455,45 @@ export class Model {
       // TODO - inside RenderPass is likely the worst place to do this from performance perspective.
       // Application can call Model.predraw() to avoid this.
       this.pipeline = this._updatePipeline();
+      pipelineErrored = this.pipeline.isErrored;
 
-      // 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 {indexBuffer} = this.vertexArray;
-      const indexCount = indexBuffer
-        ? indexBuffer.byteLength / (indexBuffer.indexType === 'uint32' ? 4 : 2)
-        : undefined;
-
-      drawSuccess = this.pipeline.draw({
-        renderPass,
-        vertexArray: this.vertexArray,
-        isInstanced: this.isInstanced,
-        vertexCount: this.vertexCount,
-        instanceCount: this.instanceCount,
-        indexCount,
-        transformFeedback: this.transformFeedback || undefined,
-        // 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)
-        parameters: this.parameters,
-        topology: this.topology
-      });
+      if (pipelineErrored) {
+        log.info(
+          LOG_DRAW_PRIORITY,
+          `>>> DRAWING ABORTED ${this.id}: ${PIPELINE_INITIALIZATION_FAILED}`
+        )();
+        drawSuccess = false;
+      } else {
+        const syncBindings = this._getBindings();
+        const syncBindGroups = this._getBindGroups();
+
+        const {indexBuffer} = this.vertexArray;
+        const indexCount = indexBuffer
+          ? indexBuffer.byteLength / (indexBuffer.indexType === 'uint32' ? 4 : 2)
+          : undefined;
+
+        drawSuccess = this.pipeline.draw({
+          renderPass,
+          vertexArray: this.vertexArray,
+          isInstanced: this.isInstanced,
+          vertexCount: this.vertexCount,
+          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)
+          parameters: this.parameters,
+          topology: this.topology
+        });
+      }
     } finally {
       renderPass.popDebugGroup();
       this._logDrawCallEnd();
@@ -441,6 +504,8 @@ export class Model {
     if (drawSuccess) {
       this._lastDrawTimestamp = this.device.timestamp;
       this._needsRedraw = false;
+    } else if (pipelineErrored) {
+      this._needsRedraw = PIPELINE_INITIALIZATION_FAILED;
     } else {
       this._needsRedraw = 'waiting for resource initialization';
     }
@@ -549,21 +614,26 @@ export class Model {
   /** Set the shader inputs */
   setShaderInputs(shaderInputs: ShaderInputs): void {
     this.shaderInputs = shaderInputs;
-    this._uniformStore = new UniformStore(this.shaderInputs.modules);
+    this._uniformStore = new UniformStore(this.device, 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)) {
-        const uniformBuffer = this._uniformStore.getManagedUniformBuffer(this.device, moduleName);
+      if (shaderModuleHasUniforms(module) && !this.material?.ownsModule(moduleName)) {
+        const uniformBuffer = this._uniformStore.getManagedUniformBuffer(moduleName);
         this.bindings[`${moduleName}Uniforms`] = uniformBuffer;
       }
     }
     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');
   }
@@ -571,7 +641,7 @@ export class Model {
   /**
    * Sets bindings (textures, samplers, uniform buffers)
    */
-  setBindings(bindings: Record<string, Binding | AsyncTexture>): void {
+  setBindings(bindings: Record<string, Binding | DynamicTexture>): void {
     Object.assign(this.bindings, bindings);
     this.setNeedsRedraw('bindings');
   }
@@ -678,7 +748,12 @@ export class Model {
   /** Check that bindings are loaded. Returns id of first binding that is still loading. */
   _areBindingsLoading(): string | false {
     for (const binding of Object.values(this.bindings)) {
-      if (binding instanceof AsyncTexture && !binding.isReady) {
+      if (binding instanceof DynamicTexture && !binding.isReady) {
+        return binding.id;
+      }
+    }
+    for (const binding of Object.values(this.material?.bindings || {})) {
+      if (binding instanceof DynamicTexture && !binding.isReady) {
         return binding.id;
       }
     }
@@ -690,7 +765,7 @@ export class Model {
     const validBindings: Record<string, Binding> = {};
 
     for (const [name, binding] of Object.entries(this.bindings)) {
-      if (binding instanceof AsyncTexture) {
+      if (binding instanceof DynamicTexture) {
         // Check that async textures are loaded
         if (binding.isReady) {
           validBindings[name] = binding.texture;
@@ -703,6 +778,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;
@@ -711,7 +812,7 @@ export class Model {
         timestamp = Math.max(timestamp, binding.texture.updateTimestamp);
       } else if (binding instanceof Buffer || binding instanceof Texture) {
         timestamp = Math.max(timestamp, binding.updateTimestamp);
-      } else if (binding instanceof AsyncTexture) {
+      } else if (binding instanceof DynamicTexture) {
         timestamp = binding.texture
           ? Math.max(timestamp, binding.texture.updateTimestamp)
           : // The texture will become available in the future
@@ -720,7 +821,7 @@ export class Model {
         timestamp = Math.max(timestamp, binding.buffer.updateTimestamp);
       }
     }
-    return timestamp;
+    return Math.max(timestamp, this.material?.getBindingsUpdateTimestamp() || 0);
   }
 
   /**
@@ -792,12 +893,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
       });
@@ -808,7 +908,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;
   }
@@ -859,12 +961,11 @@ export class Model {
       // } || (this._drawCount++ > 3 && this._drawCount % 60)) {
       return;
     }
-    // TODO - display framebuffer output in debug window
     const framebuffer = renderPass.props.framebuffer;
-    if (framebuffer) {
-      debugFramebuffer(framebuffer, {id: framebuffer.id, minimap: true});
-      // log.image({logLevel: LOG_DRAW_PRIORITY, message: `${framebuffer.id} %c sup?`, image})();
-    }
+    debugFramebuffer(renderPass, framebuffer, {
+      id: framebuffer?.id || `${this.id}-framebuffer`,
+      minimap: true
+    });
   }
 
   _getAttributeDebugTable(): Record<string, Record<string, unknown>> {
@@ -896,15 +997,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
@@ -920,13 +1033,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;
     }
   });