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

package/src/material/material.ts

@@ -0,0 +1,254 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Binding, BindingsByGroup, Device} from '@luma.gl/core';
+import {Buffer, Sampler, Texture, TextureView, UniformStore} from '@luma.gl/core';
+import type {ShaderModule} from '@luma.gl/shadertools';
+import {DynamicTexture} from '../dynamic-texture/dynamic-texture';
+import {ShaderInputs} from '../shader-inputs';
+import {shaderModuleHasUniforms} from '../utils/shader-module-utils';
+import {uid} from '../utils/uid';
+import {
+  getModuleNameFromUniformBinding,
+  MATERIAL_BIND_GROUP,
+  MaterialFactory
+} from './material-factory';
+
+type MaterialModuleProps = Partial<Record<string, Record<string, unknown>>>;
+type MaterialBindings = Record<string, Binding | DynamicTexture>;
+type MaterialPropsUpdate<TModuleProps extends MaterialModuleProps> = Partial<{
+  [P in keyof TModuleProps]?: Partial<TModuleProps[P]>;
+}>;
+
+/** Construction props for one typed {@link Material}. */
+export type MaterialProps<
+  TModuleProps extends MaterialModuleProps = MaterialModuleProps,
+  TBindings extends MaterialBindings = MaterialBindings
+> = {
+  /** Optional application-provided identifier. */
+  id?: string;
+  /** Factory that owns the material schema. */
+  factory?: MaterialFactory<TModuleProps, TBindings>;
+  /** Optional pre-created shader inputs for the material modules. */
+  shaderInputs?: ShaderInputs<TModuleProps>;
+  /** Shader modules used when a factory is not supplied. */
+  modules?: ShaderModule[];
+  /** Initial material-owned resource bindings. */
+  bindings?: Partial<TBindings>;
+};
+
+/** Structural overrides applied when cloning a {@link Material}. */
+export type MaterialCloneProps<
+  TModuleProps extends MaterialModuleProps = MaterialModuleProps,
+  TBindings extends MaterialBindings = MaterialBindings
+> = {
+  /** Optional identifier for the cloned material. */
+  id?: string;
+  /** Replacement material-owned resource bindings. */
+  bindings?: Partial<TBindings>;
+  /** Additional uniform/module props applied to the clone. */
+  moduleProps?: MaterialPropsUpdate<TModuleProps>;
+  /** Optional full replacement shader-input store. */
+  shaderInputs?: ShaderInputs<TModuleProps>;
+};
+
+/**
+ * Material owns bind group `3` resources and uniforms for one material instance.
+ *
+ * `setProps()` mutates uniform values in place. Structural resource changes are
+ * expressed through `clone({...})`, which creates a new material identity.
+ */
+export class Material<
+  TModuleProps extends MaterialModuleProps = MaterialModuleProps,
+  TBindings extends MaterialBindings = MaterialBindings
+> {
+  /** Application-provided identifier. */
+  readonly id: string;
+  /** Device that owns the material resources. */
+  readonly device: Device;
+  /** Factory that defines the material schema. */
+  readonly factory: MaterialFactory<TModuleProps, TBindings>;
+  /** Shader inputs for the material-owned modules. */
+  readonly shaderInputs: ShaderInputs<TModuleProps>;
+  /** Internal binding store including uniform buffers and resource bindings. */
+  readonly bindings: Record<string, Binding | DynamicTexture> = {};
+
+  private _uniformStore: UniformStore;
+  private _bindGroupCacheToken: object = {};
+
+  constructor(device: Device, props: MaterialProps<TModuleProps, TBindings> = {}) {
+    this.id = props.id || uid('material');
+    this.device = device;
+
+    this.factory =
+      props.factory ||
+      new MaterialFactory<TModuleProps, TBindings>(device, {
+        modules: props.modules || props.shaderInputs?.getModules() || []
+      });
+
+    const moduleMap = Object.fromEntries(
+      (props.shaderInputs?.getModules() || this.factory.modules).map(module => [
+        module.name,
+        module
+      ])
+    ) as {[P in keyof TModuleProps]?: ShaderModule[] extends never ? never : any};
+    this.shaderInputs = props.shaderInputs || new ShaderInputs<TModuleProps>(moduleMap);
+    this._uniformStore = new UniformStore(this.device, this.shaderInputs.modules);
+
+    for (const [moduleName, module] of Object.entries(this.shaderInputs.modules)) {
+      if (this.ownsModule(moduleName) && shaderModuleHasUniforms(module)) {
+        const uniformBuffer = this._uniformStore.getManagedUniformBuffer(moduleName);
+        this.bindings[`${moduleName}Uniforms`] = uniformBuffer;
+      }
+    }
+
+    this.updateShaderInputs();
+    if (props.bindings) {
+      this._replaceOwnedBindings(props.bindings);
+    }
+  }
+
+  /** Destroys managed uniform-buffer resources owned by this material. */
+  destroy(): void {
+    this._uniformStore.destroy();
+  }
+
+  /** Creates a new material variant with optional structural and uniform overrides. */
+  clone(
+    props: MaterialCloneProps<TModuleProps, TBindings> = {}
+  ): Material<TModuleProps, TBindings> {
+    const material = this.factory.createMaterial({
+      id: props.id,
+      shaderInputs: props.shaderInputs,
+      bindings: {
+        ...this.getResourceBindings(),
+        ...props.bindings
+      }
+    });
+
+    if (!props.shaderInputs) {
+      material.setProps(this.shaderInputs.getUniformValues() as MaterialPropsUpdate<TModuleProps>);
+    }
+    if (props.moduleProps) {
+      material.setProps(props.moduleProps);
+    }
+    return material;
+  }
+
+  /** Returns `true` if this material owns the supplied binding name. */
+  ownsBinding(bindingName: string): boolean {
+    return this.factory.ownsBinding(bindingName);
+  }
+
+  /** Returns `true` if this material owns the supplied shader module. */
+  ownsModule(moduleName: string): boolean {
+    return this.factory.ownsModule(moduleName);
+  }
+
+  /** Updates material uniform/module props in place without changing material identity. */
+  setProps(props: MaterialPropsUpdate<TModuleProps>): void {
+    this.shaderInputs.setProps(props);
+    this.updateShaderInputs();
+  }
+
+  /** Updates managed uniform buffers and shader-input-owned bindings. */
+  updateShaderInputs(): void {
+    this._uniformStore.setUniforms(this.shaderInputs.getUniformValues());
+    const didChange = this._setOwnedBindings(this.shaderInputs.getBindingValues());
+    if (didChange) {
+      this._bindGroupCacheToken = {};
+    }
+  }
+
+  /** Returns the material-owned resource bindings without internal uniform buffers. */
+  getResourceBindings(): Partial<TBindings> {
+    const resourceBindings = {} as Partial<TBindings>;
+
+    for (const [name, binding] of Object.entries(this.bindings)) {
+      if (!getModuleNameFromUniformBinding(name)) {
+        (resourceBindings as Record<string, Binding | DynamicTexture>)[name] = binding;
+      }
+    }
+
+    return resourceBindings;
+  }
+
+  /** Returns the resolved bindings, including internal uniform buffers and ready textures. */
+  getBindings(): Partial<{[K in keyof TBindings]: Binding}> & Record<string, Binding> {
+    const validBindings = {} as Partial<{[K in keyof TBindings]: Binding}> &
+      Record<string, Binding>;
+    const validBindingsMap = validBindings as Record<string, Binding>;
+
+    for (const [name, binding] of Object.entries(this.bindings)) {
+      if (binding instanceof DynamicTexture) {
+        if (binding.isReady) {
+          validBindingsMap[name] = binding.texture;
+        }
+      } else {
+        validBindingsMap[name] = binding;
+      }
+    }
+
+    return validBindings;
+  }
+
+  /** Packages resolved material bindings into logical bind group `3`. */
+  getBindingsByGroup(): BindingsByGroup {
+    return this.factory.getBindingsByGroup(this.getBindings());
+  }
+
+  /** Returns the stable bind-group cache token for the requested bind group. */
+  getBindGroupCacheKey(group: number): object | null {
+    return group === MATERIAL_BIND_GROUP ? this._bindGroupCacheToken : null;
+  }
+
+  /** Returns the latest update timestamp across material-owned resources. */
+  getBindingsUpdateTimestamp(): number {
+    let timestamp = 0;
+    for (const binding of Object.values(this.bindings)) {
+      if (binding instanceof TextureView) {
+        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 DynamicTexture) {
+        timestamp = binding.texture
+          ? Math.max(timestamp, binding.texture.updateTimestamp)
+          : Infinity;
+      } else if (!(binding instanceof Sampler)) {
+        timestamp = Math.max(timestamp, binding.buffer.updateTimestamp);
+      }
+    }
+    return timestamp;
+  }
+
+  /** Replaces owned resource bindings and invalidates the material cache identity when needed. */
+  private _replaceOwnedBindings(bindings: Partial<TBindings>): void {
+    const didChange = this._setOwnedBindings(bindings);
+    if (didChange) {
+      this._bindGroupCacheToken = {};
+    }
+  }
+
+  private _setOwnedBindings(
+    bindings: Partial<TBindings> | Record<string, Binding | DynamicTexture>
+  ): boolean {
+    let didChange = false;
+
+    for (const [name, binding] of Object.entries(bindings)) {
+      if (binding === undefined) {
+        continue;
+      }
+      if (!this.ownsBinding(name)) {
+        continue;
+      }
+
+      if (this.bindings[name] !== binding) {
+        this.bindings[name] = binding;
+        didChange = true;
+      }
+    }
+
+    return didChange;
+  }
+}