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

package/src/dynamic-texture/texture-data.ts

@@ -0,0 +1,301 @@
+import type {TypedArray, TextureFormat, ExternalImage} from '@luma.gl/core';
+import {isExternalImage, getExternalImageSize} from '@luma.gl/core';
+
+export type TextureImageSource = ExternalImage;
+
+/**
+ * One mip level
+ * Basic data structure is similar to `ImageData`
+ * additional optional fields can describe compressed texture data.
+ */
+export type TextureImageData = {
+  /** WebGPU style format string. Defaults to 'rgba8unorm' */
+  format?: TextureFormat;
+  /** Typed Array with the bytes of the image. @note beware row byte alignment requirements */
+  data: TypedArray;
+  /** Width of the image, in pixels, @note beware row byte alignment requirements */
+  width: number;
+  /** Height of the image, in rows */
+  height: number;
+};
+
+/**
+ * A single mip-level can be initialized by data or an ImageBitmap etc
+ * @note in the WebGPU spec a mip-level is called a subresource
+ */
+export type TextureMipLevelData = TextureImageData | TextureImageSource;
+
+/**
+ * Texture data for one image "slice" (which can consist of multiple miplevels)
+ * Thus data for one slice be a single mip level or an array of miplevels
+ * @note in the WebGPU spec each cross-section image in a 3D texture is called a "slice",
+ * in a array texture each image in the array is called an array "layer"
+ * luma.gl calls one image in a GPU texture a "slice" regardless of context.
+ */
+export type TextureSliceData = TextureMipLevelData | TextureMipLevelData[];
+
+/** Names of cube texture faces */
+export type TextureCubeFace = '+X' | '-X' | '+Y' | '-Y' | '+Z' | '-Z';
+
+/** Array of cube texture faces. @note: index in array is the face index */
+// prettier-ignore
+export const TEXTURE_CUBE_FACES = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'] as const satisfies readonly TextureCubeFace[];
+
+/** Map of cube texture face names to face indexes */
+// prettier-ignore
+export const TEXTURE_CUBE_FACE_MAP = {'+X': 0, '-X': 1, '+Y': 2, '-Y': 3, '+Z': 4, '-Z': 5} as const satisfies Record<TextureCubeFace, number>;
+
+/** @todo - Define what data type is supported for 1D textures. TextureImageData with height = 1 */
+export type Texture1DData = TextureSliceData;
+
+/** Texture data can be one or more mip levels */
+export type Texture2DData = TextureSliceData;
+
+/** 6 face textures */
+export type TextureCubeData = Record<TextureCubeFace, TextureSliceData>;
+
+/** Array of textures */
+export type Texture3DData = TextureSliceData[];
+
+/** Array of textures */
+export type TextureArrayData = TextureSliceData[];
+
+/** Array of 6 face textures */
+export type TextureCubeArrayData = Record<TextureCubeFace, TextureSliceData>[];
+
+type TextureData =
+  | Texture1DData
+  | Texture3DData
+  | TextureArrayData
+  | TextureCubeArrayData
+  | TextureCubeData;
+
+/** Sync data props */
+export type TextureDataProps =
+  | {dimension: '1d'; data: Texture1DData | null}
+  | {dimension?: '2d'; data: Texture2DData | null}
+  | {dimension: '3d'; data: Texture3DData | null}
+  | {dimension: '2d-array'; data: TextureArrayData | null}
+  | {dimension: 'cube'; data: TextureCubeData | null}
+  | {dimension: 'cube-array'; data: TextureCubeArrayData | null};
+
+/** Async data props */
+export type TextureDataAsyncProps =
+  | {dimension: '1d'; data?: Promise<Texture1DData> | Texture1DData | null}
+  | {dimension?: '2d'; data?: Promise<Texture2DData> | Texture2DData | null}
+  | {dimension: '3d'; data?: Promise<Texture3DData> | Texture3DData | null}
+  | {dimension: '2d-array'; data?: Promise<TextureArrayData> | TextureArrayData | null}
+  | {dimension: 'cube'; data?: Promise<TextureCubeData> | TextureCubeData | null}
+  | {dimension: 'cube-array'; data?: Promise<TextureCubeArrayData> | TextureCubeArrayData | null};
+
+/** Describes data for one sub resource (one mip level of one slice (depth or array layer)) */
+export type TextureSubresource = {
+  /** slice (depth or array layer)) */
+  z: number;
+  /** mip level (0 - max mip levels) */
+  mipLevel: number;
+} & (
+  | {
+      type: 'external-image';
+      image: ExternalImage;
+      /** @deprecated is this an appropriate place for this flag? */
+      flipY?: boolean;
+    }
+  | {
+      type: 'texture-data';
+      data: TextureImageData;
+    }
+);
+
+/** Check if texture data is a typed array */
+export function isTextureSliceData(data: TextureData): data is TextureImageData {
+  const typedArray = (data as TextureImageData)?.data;
+  return ArrayBuffer.isView(typedArray);
+}
+
+export function getFirstMipLevel(layer: TextureSliceData | null): TextureMipLevelData | null {
+  if (!layer) return null;
+  return Array.isArray(layer) ? (layer[0] ?? null) : layer;
+}
+
+export function getTextureSizeFromData(
+  props: TextureDataProps
+): {width: number; height: number} | null {
+  const {dimension, data} = props;
+  if (!data) {
+    return null;
+  }
+
+  switch (dimension) {
+    case '1d': {
+      const mipLevel = getFirstMipLevel(data);
+      if (!mipLevel) return null;
+      const {width} = getTextureMipLevelSize(mipLevel);
+      return {width, height: 1};
+    }
+    case '2d': {
+      const mipLevel = getFirstMipLevel(data);
+      return mipLevel ? getTextureMipLevelSize(mipLevel) : null;
+    }
+    case '3d':
+    case '2d-array': {
+      if (!Array.isArray(data) || data.length === 0) return null;
+      const mipLevel = getFirstMipLevel(data[0]);
+      return mipLevel ? getTextureMipLevelSize(mipLevel) : null;
+    }
+    case 'cube': {
+      const face = (Object.keys(data)[0] as TextureCubeFace) ?? null;
+      if (!face) return null;
+      const faceData = (data as Record<TextureCubeFace, TextureSliceData>)[face];
+      const mipLevel = getFirstMipLevel(faceData);
+      return mipLevel ? getTextureMipLevelSize(mipLevel) : null;
+    }
+    case 'cube-array': {
+      if (!Array.isArray(data) || data.length === 0) return null;
+      const firstCube = data[0];
+      const face = (Object.keys(firstCube)[0] as TextureCubeFace) ?? null;
+      if (!face) return null;
+      const mipLevel = getFirstMipLevel(firstCube[face]);
+      return mipLevel ? getTextureMipLevelSize(mipLevel) : null;
+    }
+    default:
+      return null;
+  }
+}
+
+function getTextureMipLevelSize(data: TextureMipLevelData): {width: number; height: number} {
+  if (isExternalImage(data)) {
+    return getExternalImageSize(data);
+  }
+  if (typeof data === 'object' && 'width' in data && 'height' in data) {
+    return {width: data.width, height: data.height};
+  }
+  throw new Error('Unsupported mip-level data');
+}
+
+/** Type guard: is a mip-level `TextureImageData` (vs ExternalImage) */
+function isTextureImageData(data: TextureMipLevelData): data is TextureImageData {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'data' in data &&
+    'width' in data &&
+    'height' in data
+  );
+}
+
+/** Resolve size for a single mip-level datum */
+// function getTextureMipLevelSizeFromData(data: TextureMipLevelData): {
+//   width: number;
+//   height: number;
+// } {
+//   if (this.device.isExternalImage(data)) {
+//     return this.device.getExternalImageSize(data);
+//   }
+//   if (this.isTextureImageData(data)) {
+//     return {width: data.width, height: data.height};
+//   }
+//   // Fallback (should not happen with current types)
+//   throw new Error('Unsupported mip-level data');
+// }
+
+/** Convert cube face label to depth index */
+export function getCubeFaceIndex(face: TextureCubeFace): number {
+  const idx = TEXTURE_CUBE_FACE_MAP[face];
+  if (idx === undefined) throw new Error(`Invalid cube face: ${face}`);
+  return idx;
+}
+
+/** Convert cube face label to texture slice index. Index can be used with `setTexture2DData()`. */
+export function getCubeArrayFaceIndex(cubeIndex: number, face: TextureCubeFace): number {
+  return 6 * cubeIndex + getCubeFaceIndex(face);
+}
+
+// ------------------ Upload helpers ------------------
+
+/** Experimental: Set multiple mip levels (1D) */
+export function getTexture1DSubresources(data: Texture1DData): TextureSubresource[] {
+  // Not supported in WebGL; left explicit
+  throw new Error('setTexture1DData not supported in WebGL.');
+  // const subresources: TextureSubresource[] = [];
+  // return subresources;
+}
+
+/** Normalize 2D layer payload into an array of mip-level items */
+function _normalizeTexture2DData(data: Texture2DData): (TextureImageData | ExternalImage)[] {
+  return Array.isArray(data) ? data : [data];
+}
+
+/** Experimental: Set multiple mip levels (2D), optionally at `z` (depth/array index) */
+export function getTexture2DSubresources(
+  slice: number,
+  lodData: Texture2DData
+): TextureSubresource[] {
+  const lodArray = _normalizeTexture2DData(lodData);
+  const z = slice;
+
+  const subresources: TextureSubresource[] = [];
+
+  for (let mipLevel = 0; mipLevel < lodArray.length; mipLevel++) {
+    const imageData = lodArray[mipLevel];
+    if (isExternalImage(imageData)) {
+      subresources.push({
+        type: 'external-image',
+        image: imageData,
+        z,
+        mipLevel
+      });
+    } else if (isTextureImageData(imageData)) {
+      subresources.push({
+        type: 'texture-data',
+        data: imageData,
+        z,
+        mipLevel
+      });
+    } else {
+      throw new Error('Unsupported 2D mip-level payload');
+    }
+  }
+
+  return subresources;
+}
+
+/** 3D: multiple depth slices, each may carry multiple mip levels */
+export function getTexture3DSubresources(data: Texture3DData): TextureSubresource[] {
+  const subresources: TextureSubresource[] = [];
+  for (let depth = 0; depth < data.length; depth++) {
+    subresources.push(...getTexture2DSubresources(depth, data[depth]));
+  }
+  return subresources;
+}
+
+/** 2D array: multiple layers, each may carry multiple mip levels */
+export function getTextureArraySubresources(data: TextureArrayData): TextureSubresource[] {
+  const subresources: TextureSubresource[] = [];
+  for (let layer = 0; layer < data.length; layer++) {
+    subresources.push(...getTexture2DSubresources(layer, data[layer]));
+  }
+  return subresources;
+}
+
+/** Cube: 6 faces, each may carry multiple mip levels */
+export function getTextureCubeSubresources(data: TextureCubeData): TextureSubresource[] {
+  const subresources: TextureSubresource[] = [];
+  for (const [face, faceData] of Object.entries(data) as [TextureCubeFace, TextureSliceData][]) {
+    const faceDepth = getCubeFaceIndex(face);
+    subresources.push(...getTexture2DSubresources(faceDepth, faceData));
+  }
+  return subresources;
+}
+
+/** Cube array: multiple cubes (faces×layers), each face may carry multiple mips */
+export function getTextureCubeArraySubresources(data: TextureCubeArrayData): TextureSubresource[] {
+  const subresources: TextureSubresource[] = [];
+  data.forEach((cubeData, cubeIndex) => {
+    for (const [face, faceData] of Object.entries(cubeData)) {
+      const faceDepth = getCubeArrayFaceIndex(cubeIndex, face as TextureCubeFace);
+      subresources.push(...getTexture2DSubresources(faceDepth, faceData));
+    }
+  });
+  return subresources;
+}

package/src/factories/pipeline-factory.ts

@@ -4,6 +4,7 @@
 
 import type {RenderPipelineProps, ComputePipelineProps} from '@luma.gl/core';
 import {Device, RenderPipeline, ComputePipeline, log} from '@luma.gl/core';
+import type {EngineModuleState} from '../types';
 import {uid} from '../utils/uid';
 
 export type PipelineFactoryProps = RenderPipelineProps;
@@ -19,9 +20,9 @@ export class PipelineFactory {
 
   /** Get the singleton default pipeline factory for the specified device */
   static getDefaultPipelineFactory(device: Device): PipelineFactory {
-    device._lumaData['defaultPipelineFactory'] =
-      device._lumaData['defaultPipelineFactory'] || new PipelineFactory(device);
-    return device._lumaData['defaultPipelineFactory'] as PipelineFactory;
+    const moduleData = device.getModuleData<EngineModuleState>('@luma.gl/engine');
+    moduleData.defaultPipelineFactory ||= new PipelineFactory(device);
+    return moduleData.defaultPipelineFactory;
   }
 
   readonly device: Device;

package/src/factories/shader-factory.ts

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {Device, Shader, ShaderProps, log} from '@luma.gl/core';
+import type {EngineModuleState} from '../types';
 
 /** Manages a cached pool of Shaders for reuse. */
 export class ShaderFactory {
@@ -10,8 +11,9 @@ export class ShaderFactory {
 
   /** Returns the default ShaderFactory for the given {@link Device}, creating one if necessary. */
   static getDefaultShaderFactory(device: Device): ShaderFactory {
-    device._lumaData['defaultShaderFactory'] ||= new ShaderFactory(device);
-    return device._lumaData['defaultShaderFactory'] as ShaderFactory;
+    const moduleData = device.getModuleData<EngineModuleState>('@luma.gl/engine');
+    moduleData.defaultShaderFactory ||= new ShaderFactory(device);
+    return moduleData.defaultShaderFactory;
   }
 
   public readonly device: Device;

package/src/index.ts

@@ -83,17 +83,16 @@ export {Computation} from './compute/computation';
 export type {
   TextureCubeFace,
   TextureImageData,
-  TextureData,
   Texture1DData,
   Texture2DData,
   Texture3DData,
   TextureCubeData,
   TextureArrayData,
   TextureCubeArrayData
-} from './async-texture/async-texture';
+} from './dynamic-texture/texture-data';
 
-export type {AsyncTextureProps} from './async-texture/async-texture';
-export {AsyncTexture} from './async-texture/async-texture';
+export type {DynamicTextureProps} from './dynamic-texture/dynamic-texture';
+export {DynamicTexture} from './dynamic-texture/dynamic-texture';
 
 export {PickingManager} from './modules/picking/picking-manager';
 export {picking as indexPicking} from './modules/picking/index-picking';
@@ -107,3 +106,9 @@ export {
 // DEPRECATED
 
 export {LegacyPickingManager} from './modules/picking/legacy-picking-manager';
+
+import {DynamicTexture, type DynamicTextureProps} from './dynamic-texture/dynamic-texture';
+/** @deprecated use DynamicTexture */
+export const AsyncTexture = DynamicTexture;
+/** @deprecated use DynamicTextureProps */
+export type AsyncTextureProps = DynamicTextureProps;

package/src/model/model.ts

@@ -31,7 +31,7 @@ import {
 } from '@luma.gl/core';
 
 import type {ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
-import {ShaderAssembler, getShaderLayoutFromWGSL} from '@luma.gl/shadertools';
+import {ShaderAssembler} from '@luma.gl/shadertools';
 
 import type {Geometry} from '../geometry/geometry';
 import {GPUGeometry, makeGPUGeometry} from '../geometry/gpu-geometry';
@@ -44,7 +44,7 @@ import {BufferLayoutHelper} from '../utils/buffer-layout-helper';
 import {sortedBufferLayoutByShaderSourceLocations} from '../utils/buffer-layout-order';
 import {uid} from '../utils/uid';
 import {ShaderInputs} from '../shader-inputs';
-import {AsyncTexture} from '../async-texture/async-texture';
+import {DynamicTexture} from '../dynamic-texture/dynamic-texture';
 
 const LOG_DRAW_PRIORITY = 2;
 const LOG_DRAW_TIMEOUT = 10000;
@@ -63,7 +63,7 @@ export type ModelProps = Omit<RenderPipelineProps, 'vs' | 'fs' | 'bindings'> & {
   /** Shader inputs, used to generated uniform buffers and bindings */
   shaderInputs?: ShaderInputs;
   /** Bindings */
-  bindings?: Record<string, Binding | AsyncTexture>;
+  bindings?: Record<string, Binding | DynamicTexture>;
   /** Parameters that are built into the pipeline */
   parameters?: RenderPipelineParameters;
 
@@ -103,12 +103,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 `AsyncTexture`.
+ * - Provides detailed debug logging and optional shader source inspection.
  */
 export class Model {
   static defaultProps: Required<ModelProps> = {
@@ -141,16 +148,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 +194,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
@@ -262,7 +277,8 @@ export class Model {
       // @ts-expect-error
       this._getModuleUniforms = getUniforms;
       // Extract shader layout after modules have been added to WGSL source, to include any bindings added by modules
-      this.props.shaderLayout ||= getShaderLayoutFromWGSL(this.source);
+      // @ts-expect-error Method on WebGPUDevice
+      this.props.shaderLayout ||= device.getShaderLayout(this.source);
     } else {
       // GLSL
       const {vs, fs, getUniforms} = this.props.shaderAssembler.assembleGLSLShaderPair({
@@ -333,9 +349,6 @@ export class Model {
     if (props.transformFeedback) {
       this.transformFeedback = props.transformFeedback;
     }
-
-    // Catch any access to non-standard props
-    Object.seal(this);
   }
 
   destroy(): void {
@@ -372,6 +385,7 @@ export class Model {
     this._needsRedraw ||= reason;
   }
 
+  /** Update uniforms and pipeline state prior to drawing. */
   predraw(): void {
     // Update uniform buffers if needed
     this.updateShaderInputs();
@@ -379,6 +393,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) {
@@ -571,7 +590,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 +697,7 @@ 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;
       }
     }
@@ -690,7 +709,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;
@@ -711,7 +730,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