@luma.gl/engine 9.0.0-alpha.9 → 9.0.0-beta.10

package/src/scenegraph/group-node.ts

@@ -0,0 +1,107 @@
+import {Matrix4, Vector3} from '@math.gl/core';
+import {log} from '@luma.gl/core';
+import {ScenegraphNode, ScenegraphNodeProps} from './scenegraph-node';
+
+export type GroupNodeProps = ScenegraphNodeProps & {
+  children?: ScenegraphNode[];
+};
+
+export class GroupNode extends ScenegraphNode {
+  children: ScenegraphNode[];
+
+  constructor(children: ScenegraphNode[]);
+  constructor(props?: GroupNodeProps);
+
+  constructor(props: ScenegraphNode[] | GroupNodeProps = {}) {
+    props = Array.isArray(props) ? {children: props} : props;
+    const {children = []} = props;
+    log.assert(
+      children.every(child => child instanceof ScenegraphNode),
+      'every child must an instance of ScenegraphNode'
+    );
+    super(props);
+    this.children = children;
+  }
+
+  override getBounds(): [number[], number[]] | null {
+    const result: [number[], number[]] = [
+      [Infinity, Infinity, Infinity],
+      [-Infinity, -Infinity, -Infinity]
+    ];
+
+    this.traverse((node, {worldMatrix}) => {
+      const bounds = node.getBounds();
+      if (!bounds) {
+        return;
+      }
+      const [min, max] = bounds;
+      const center = new Vector3(min).add(max).divide([2, 2, 2]);
+      worldMatrix.transformAsPoint(center, center);
+      const halfSize = new Vector3(max).subtract(min).divide([2, 2, 2]);
+      worldMatrix.transformAsVector(halfSize, halfSize);
+
+      for (let v = 0; v < 8; v++) {
+        // Test all 8 corners of the box
+        const position = new Vector3(v & 0b001 ? -1 : 1, v & 0b010 ? -1 : 1, v & 0b100 ? -1 : 1)
+          .multiply(halfSize)
+          .add(center);
+
+        for (let i = 0; i < 3; i++) {
+          result[0][i] = Math.min(result[0][i], position[i]);
+          result[1][i] = Math.max(result[1][i], position[i]);
+        }
+      }
+    });
+    if (!Number.isFinite(result[0][0])) {
+      return null;
+    }
+    return result;
+  }
+
+  override destroy(): void {
+    this.children.forEach(child => child.destroy());
+    this.removeAll();
+    super.destroy();
+  }
+
+  // Unpacks arrays and nested arrays of children
+  add(...children: (ScenegraphNode | ScenegraphNode[])[]): this {
+    for (const child of children) {
+      if (Array.isArray(child)) {
+        this.add(...child);
+      } else {
+        this.children.push(child);
+      }
+    }
+    return this;
+  }
+
+  remove(child: ScenegraphNode): this {
+    const children = this.children;
+    const indexOf = children.indexOf(child);
+    if (indexOf > -1) {
+      children.splice(indexOf, 1);
+    }
+    return this;
+  }
+
+  removeAll(): this {
+    this.children = [];
+    return this;
+  }
+
+  traverse(
+    visitor: (node: ScenegraphNode, context: {worldMatrix: Matrix4}) => void,
+    {worldMatrix = new Matrix4()} = {}
+  ) {
+    const modelMatrix = new Matrix4(worldMatrix).multiplyRight(this.matrix);
+
+    for (const child of this.children) {
+      if (child instanceof GroupNode) {
+        child.traverse(visitor, {worldMatrix: modelMatrix});
+      } else {
+        visitor(child, {worldMatrix: modelMatrix});
+      }
+    }
+  }
+}

package/src/scenegraph/model-node.ts

@@ -0,0 +1,50 @@
+import {RenderPass} from '@luma.gl/core';
+import {ScenegraphNode, ScenegraphNodeProps} from './scenegraph-node';
+import {Model} from '../model/model';
+
+export type ModelNodeProps = ScenegraphNodeProps & {
+  model: Model;
+  managedResources?: any[];
+  bounds?: [number[], number[]];
+};
+
+export class ModelNode extends ScenegraphNode {
+  readonly model: Model;
+  bounds: [number[], number[]] | null = null;
+  managedResources: any[];
+
+  // TODO - is this used? override callbacks to make sure we call them with this
+  // onBeforeRender = null;
+  // onAfterRender = null;
+  // AfterRender = null;
+
+  constructor(props: ModelNodeProps) {
+    super(props);
+
+    // Create new Model or used supplied Model
+    this.model = props.model;
+    this.managedResources = props.managedResources || [];
+    this.bounds = props.bounds || null;
+    this.setProps(props);
+  }
+
+  override getBounds(): [number[], number[]] | null {
+    return this.bounds;
+  }
+
+  override destroy(): void {
+    if (this.model) {
+      this.model.destroy();
+      // @ts-expect-error
+      this.model = null;
+    }
+    this.managedResources.forEach(resource => resource.destroy());
+    this.managedResources = [];
+  }
+
+  // Expose model methods
+  draw(renderPass?: RenderPass) {
+    // Return value indicates if something was actually drawn
+    return this.model.draw(renderPass);
+  }
+}

package/src/scenegraph/scenegraph-node.ts

@@ -0,0 +1,204 @@
+import {assert, uid, NumberArray} from '@luma.gl/core';
+import {Vector3, Matrix4} from '@math.gl/core';
+
+/** Properties for creating a new Scenegraph */
+export type ScenegraphNodeProps = {
+  id?: string;
+  /** whether to display the object at all */
+  display?: boolean;
+  matrix?: NumberArray;
+  position?: NumberArray;
+  rotation?: NumberArray;
+  scale?: NumberArray;
+  update?: boolean;
+};
+
+export class ScenegraphNode {
+  readonly id: string;
+  matrix: Matrix4 = new Matrix4();
+
+  display = true;
+  position = new Vector3();
+  rotation = new Vector3();
+  scale = new Vector3(1, 1, 1);
+  userData: Record<string, unknown> = {};
+
+  props: ScenegraphNodeProps = {};
+
+  constructor(props: ScenegraphNodeProps = {}) {
+    const {id} = props;
+
+    this.id = id || uid(this.constructor.name);
+
+    this._setScenegraphNodeProps(props);
+  }
+
+  getBounds(): [number[], number[]] | null {
+    return null;
+  }
+
+  destroy(): void {}
+
+  /** @deprecated use .destroy() */
+  delete(): void {
+    this.destroy();
+  }
+  setProps(props: ScenegraphNodeProps): this {
+    this._setScenegraphNodeProps(props);
+    return this;
+  }
+
+  toString(): string {
+    return `{type: ScenegraphNode, id: ${this.id})}`;
+  }
+
+  setPosition(position: any): this {
+    assert(position.length === 3, 'setPosition requires vector argument');
+    this.position = position;
+    return this;
+  }
+
+  setRotation(rotation: any): this {
+    assert(rotation.length === 3, 'setRotation requires vector argument');
+    this.rotation = rotation;
+    return this;
+  }
+
+  setScale(scale: any): this {
+    assert(scale.length === 3, 'setScale requires vector argument');
+    this.scale = scale;
+    return this;
+  }
+
+  setMatrix(matrix: any, copyMatrix: boolean = true): void {
+    if (copyMatrix) {
+      this.matrix.copy(matrix);
+    } else {
+      this.matrix = matrix;
+    }
+  }
+
+  setMatrixComponents(components: {
+    position?: any;
+    rotation?: any;
+    scale?: any;
+    update?: boolean;
+  }): this {
+    const {position, rotation, scale, update = true} = components;
+    if (position) {
+      this.setPosition(position);
+    }
+    if (rotation) {
+      this.setRotation(rotation);
+    }
+    if (scale) {
+      this.setScale(scale);
+    }
+    if (update) {
+      this.updateMatrix();
+    }
+    return this;
+  }
+
+  updateMatrix(): this {
+    const pos = this.position;
+    const rot = this.rotation;
+    const scale = this.scale;
+
+    this.matrix.identity();
+    this.matrix.translate(pos);
+    this.matrix.rotateXYZ(rot);
+    this.matrix.scale(scale);
+    return this;
+  }
+
+  update(options: {position?: any; rotation?: any; scale?: any} = {}): this {
+    const {position, rotation, scale} = options;
+    if (position) {
+      this.setPosition(position);
+    }
+    if (rotation) {
+      this.setRotation(rotation);
+    }
+    if (scale) {
+      this.setScale(scale);
+    }
+    this.updateMatrix();
+    return this;
+  }
+
+  getCoordinateUniforms(
+    viewMatrix: any,
+    modelMatrix?: any
+  ): {
+    viewMatrix: any;
+    modelMatrix: any;
+    objectMatrix: any;
+    worldMatrix: any;
+    worldInverseMatrix: any;
+    worldInverseTransposeMatrix: any;
+  } {
+    // TODO - solve multiple class problem
+    // assert(viewMatrix instanceof Matrix4);
+    assert(viewMatrix);
+    modelMatrix = modelMatrix || this.matrix;
+    const worldMatrix = new Matrix4(viewMatrix).multiplyRight(modelMatrix);
+    const worldInverse = worldMatrix.invert();
+    const worldInverseTranspose = worldInverse.transpose();
+
+    return {
+      viewMatrix,
+      modelMatrix,
+      objectMatrix: modelMatrix,
+      worldMatrix,
+      worldInverseMatrix: worldInverse,
+      worldInverseTransposeMatrix: worldInverseTranspose
+    };
+  }
+
+  // TODO - copied code, not yet vetted
+  /*
+  transform() {
+    if (!this.parent) {
+      this.endPosition.set(this.position);
+      this.endRotation.set(this.rotation);
+      this.endScale.set(this.scale);
+    } else {
+      const parent = this.parent;
+      this.endPosition.set(this.position.add(parent.endPosition));
+      this.endRotation.set(this.rotation.add(parent.endRotation));
+      this.endScale.set(this.scale.add(parent.endScale));
+    }
+
+    const ch = this.children;
+    for (let i = 0; i < ch.length; ++i) {
+      ch[i].transform();
+    }
+
+    return this;
+  }
+  */
+
+  _setScenegraphNodeProps(props: ScenegraphNodeProps): void {
+    if ('display' in props) {
+      this.display = props.display;
+    }
+
+    if ('position' in props) {
+      this.setPosition(props.position);
+    }
+    if ('rotation' in props) {
+      this.setRotation(props.rotation);
+    }
+    if ('scale' in props) {
+      this.setScale(props.scale);
+    }
+
+    // Matrix overwrites other props
+    if ('matrix' in props) {
+      this.setMatrix(props.matrix);
+    }
+
+    Object.assign(this.props, props);
+  }
+}

package/src/shader-inputs.ts

@@ -0,0 +1,157 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {UniformValue, Texture, Sampler} from '@luma.gl/core';
+import {log} from '@luma.gl/core';
+// import type {ShaderUniformType, UniformValue, UniformFormat, UniformInfoDevice, Texture, Sampler} from '@luma.gl/core';
+import {_resolveModules, ShaderModuleInstance} from '@luma.gl/shadertools';
+
+/** Minimal ShaderModule subset, we don't need shader code etc */
+export type ShaderModuleInputs<
+  PropsT extends Record<string, unknown> = Record<string, unknown>,
+  UniformsT extends Record<string, UniformValue> = Record<string, UniformValue>,
+  BindingsT extends Record<string, Texture | Sampler> = Record<string, Texture | Sampler>
+> = {
+  defaultUniforms?: UniformsT;
+  getUniforms?: (settings: Partial<PropsT>, prevUniforms?: UniformsT) => UniformsT;
+
+  /** Not used. Used to access props type */
+  props?: PropsT;
+
+  bindings?: Record<
+    keyof BindingsT,
+    {
+      location: number;
+      type: 'texture' | 'sampler' | 'uniforms';
+    }
+  >;
+
+  uniformTypes?: any;
+};
+
+/**
+ * ShaderInputs holds uniform and binding values for one or more shader modules,
+ * - It can generate binary data for any uniform buffer
+ * - It can manage a uniform buffer for each block
+ * - It can update managed uniform buffers with a single call
+ * - It performs some book keeping on what has changed to minimize unnecessary writes to uniform buffers.
+ */
+export class ShaderInputs<
+  ShaderPropsT extends Partial<Record<string, Record<string, unknown>>> = Partial<
+    Record<string, Record<string, unknown>>
+  >
+> {
+  /**
+   * The map of modules
+   * @todo should should this include the resolved dependencies?
+   */
+  modules: Readonly<{[P in keyof ShaderPropsT]: ShaderModuleInputs<ShaderPropsT[P]>}>;
+
+  /** Stores the uniform values for each module */
+  moduleUniforms: Record<keyof ShaderPropsT, Record<string, UniformValue>>;
+  /** Stores the uniform bindings for each module  */
+  moduleBindings: Record<keyof ShaderPropsT, Record<string, Texture | Sampler>>;
+  /** Tracks if uniforms have changed */
+  moduleUniformsChanged: Record<keyof ShaderPropsT, false | string>;
+
+  /**
+   * Create a new UniformStore instance
+   * @param modules
+   */
+  constructor(modules: {[P in keyof ShaderPropsT]: ShaderModuleInputs<ShaderPropsT[P]>}) {
+    // TODO - get all dependencies from modules
+    const allModules = _resolveModules(Object.values(modules));
+    log.log(
+      1,
+      'Creating ShaderInputs with modules',
+      allModules.map(m => m.name)
+    )();
+
+    // Store the module definitions and create storage for uniform values and binding values, per module
+    this.modules = modules;
+    this.moduleUniforms = {} as Record<keyof ShaderPropsT, Record<string, UniformValue>>;
+    this.moduleBindings = {} as Record<keyof ShaderPropsT, Record<string, Texture | Sampler>>;
+
+    // Initialize the modules
+    for (const [name, module] of Object.entries(modules)) {
+      const moduleName = name as keyof ShaderPropsT;
+
+      // Get default uniforms from module
+      this.moduleUniforms[moduleName] = module.defaultUniforms || {};
+      this.moduleBindings[moduleName] = {};
+    }
+  }
+
+  /** Destroy */
+  destroy(): void {}
+
+  /**
+   * Set module props
+   */
+  setProps(props: Partial<{[P in keyof ShaderPropsT]?: Partial<ShaderPropsT[P]>}>): void {
+    for (const name of Object.keys(props)) {
+      const moduleName = name as keyof ShaderPropsT;
+      const moduleProps = props[moduleName];
+      const module = this.modules[moduleName];
+      if (!module) {
+        // Ignore props for unregistered modules
+        log.warn(`Module ${name} not found`)();
+        continue; // eslint-disable-line no-continue
+      }
+
+      const oldUniforms = this.moduleUniforms[moduleName];
+      const uniforms =
+        module.getUniforms?.(moduleProps, this.moduleUniforms[moduleName]) || (moduleProps as any);
+      // console.error(uniforms)
+      this.moduleUniforms[moduleName] = {...oldUniforms, ...uniforms};
+      // this.moduleUniformsChanged ||= moduleName;
+
+      // console.log(`setProps(${String(moduleName)}`, moduleName, this.moduleUniforms[moduleName])
+
+      // TODO - Get Module bindings
+      // const bindings = module.getBindings?.(moduleProps);
+      // this.moduleUniforms[moduleName] = bindings;
+    }
+  }
+
+  /** Merges all bindings for the shader (from the various modules) */
+  // getUniformBlocks(): Record<string, Texture | Sampler> {
+  //   return this.moduleUniforms;
+  // }
+
+  /**
+   * Return the map of modules
+   * @todo should should this include the resolved dependencies?
+   */
+  getModules(): ShaderModuleInstance[] {
+    return Object.values(this.modules);
+  }
+
+  /** Get all uniform values for all modules */
+  getUniformValues(): Record<keyof ShaderPropsT, Record<string, UniformValue>> {
+    return this.moduleUniforms;
+  }
+
+  /** Merges all bindings for the shader (from the various modules) */
+  getBindings(): Record<string, Texture | Sampler> {
+    const bindings = {} as Record<string, Texture | Sampler>;
+    for (const moduleBindings of Object.values(this.moduleBindings)) {
+      Object.assign(bindings, moduleBindings);
+    }
+    return bindings;
+  }
+
+  getDebugTable(): Record<string, Record<string, unknown>> {
+    const table: Record<string, Record<string, unknown>> = {};
+    for (const [moduleName, module] of Object.entries(this.moduleUniforms)) {
+      for (const [key, value] of Object.entries(module)) {
+        table[`${moduleName}.${key}`] = {
+          type: this.modules[moduleName].uniformTypes?.[key],
+          value: String(value)
+        };
+      }
+    }
+    return table;
+  }
+}

package/src/transform/buffer-transform.ts

@@ -0,0 +1,102 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  Device,
+  Buffer,
+  BufferRange,
+  TransformFeedback,
+  assert,
+  RenderPassProps
+} from '@luma.gl/core';
+import {getPassthroughFS} from '@luma.gl/shadertools';
+import {Model} from '../model/model';
+import type {ModelProps} from '..';
+
+/**
+ * Properties for creating a {@link BufferTransform}
+ * @deprecated
+ */
+export type BufferTransformProps = Omit<ModelProps, 'fs'> & {
+  fs?: ModelProps['fs']; // override as optional
+  feedbackBuffers?: Record<string, Buffer | BufferRange>;
+};
+
+/**
+ * Creates a pipeline for buffer→buffer transforms.
+ * @deprecated
+ */
+export class BufferTransform {
+  readonly device: Device;
+  readonly model: Model;
+  readonly transformFeedback: TransformFeedback;
+
+  /** @deprecated Use device feature test. */
+  static isSupported(device: Device): boolean {
+    return device?.info?.type === 'webgl';
+  }
+
+  constructor(device: Device, props: BufferTransformProps = Model.defaultProps) {
+    assert(BufferTransform.isSupported(device), 'BufferTransform not yet implemented on WebGPU');
+
+    this.device = device;
+
+    this.model = new Model(this.device, {
+      id: props.id || 'buffer-transform-model',
+      fs: props.fs || getPassthroughFS(),
+      topology: props.topology || 'point-list',
+      ...props
+    });
+
+    this.transformFeedback = this.device.createTransformFeedback({
+      layout: this.model.pipeline.shaderLayout,
+      buffers: props.feedbackBuffers
+    });
+
+    this.model.setTransformFeedback(this.transformFeedback);
+
+    Object.seal(this);
+  }
+
+  /** Destroy owned resources. */
+  destroy(): void {
+    if (this.model) {
+      this.model.destroy();
+    }
+  }
+
+  /** @deprecated Use {@link destroy}. */
+  delete(): void {
+    this.destroy();
+  }
+
+  /** Run one transform loop. */
+  run(options?: RenderPassProps): void {
+    const renderPass = this.device.beginRenderPass(options);
+    this.model.draw(renderPass);
+    renderPass.end();
+  }
+
+  /** @deprecated */
+  update(...args: any[]): void {
+    // TODO(v9): Method should likely be removed for v9. Keeping a method stub
+    // to assist with migrating DeckGL usage.
+    // eslint-disable-next-line no-console
+    console.warn('TextureTransform#update() not implemented');
+  }
+
+  /** Returns the {@link Buffer} or {@link BufferRange} for given varying name. */
+  getBuffer(varyingName: string): Buffer | BufferRange | null {
+    return this.transformFeedback.getBuffer(varyingName);
+  }
+
+  readAsync(varyingName: string): Promise<Uint8Array> {
+    const result = this.getBuffer(varyingName);
+    if (result instanceof Buffer) {
+      return result.readAsync();
+    }
+    const {buffer, byteOffset = 0, byteLength = buffer.byteLength} = result;
+    return buffer.readAsync(byteOffset, byteLength);
+  }
+}