@luma.gl/engine 9.3.0-alpha.6 → 9.3.0-alpha.9

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,6 +67,8 @@ 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 */
@@ -143,6 +150,7 @@ export class Model {
     vertexCount: 0,
 
     shaderInputs: undefined!,
+    material: undefined!,
     pipelineFactory: undefined!,
     shaderFactory: undefined!,
     transformFeedback: undefined!,
@@ -216,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;
 
@@ -229,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';
@@ -246,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]) || []
@@ -265,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
@@ -272,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
@@ -280,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({
@@ -295,6 +317,7 @@ export class Model {
       this.fs = fs;
       // @ts-expect-error
       this._getModuleUniforms = getUniforms;
+      this._bindingTable = [];
     }
 
     this.vertexCount = this.props.vertexCount;
@@ -389,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
@@ -427,6 +455,7 @@ export class Model {
       this.pipeline = this._updatePipeline();
 
       const syncBindings = this._getBindings();
+      const syncBindGroups = this._getBindGroups();
 
       const {indexBuffer} = this.vertexArray;
       const indexCount = indexBuffer
@@ -445,6 +474,8 @@ export class Model {
         // 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
@@ -573,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;
       }
@@ -581,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');
   }
@@ -703,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;
   }
 
@@ -724,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;
@@ -741,7 +808,7 @@ export class Model {
         timestamp = Math.max(timestamp, binding.buffer.updateTimestamp);
       }
     }
-    return timestamp;
+    return Math.max(timestamp, this.material?.getBindingsUpdateTimestamp() || 0);
   }
 
   /**
@@ -813,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
       });
@@ -919,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
@@ -943,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/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']
+    });
+  }
+}