@luma.gl/engine 9.0.0-beta.1 → 9.0.0-beta.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luma.gl/engine",
-  "version": "9.0.0-beta.1",
-  "description": "WebGL2 Components for High Performance Rendering and Computation",
+  "version": "9.0.0-beta.10",
+  "description": "3D Engine Components for luma.gl",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -35,17 +35,18 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build-bundle": "ocular-bundle ./src/index.ts",
-    "pre-build": "npm run build-bundle && npm run build-bundle -- --env=dev"
+    "build-minified-bundle": "ocular-bundle ./bundle.ts --output=dist/dist.min.js",
+    "build-dev-bundle": "ocular-bundle ./bundle.ts --output=dist/dist.dev.js --env=dev",
+    "prepublishOnly": "npm run build-minified-bundle && npm run build-dev-bundle"
+  },
+  "peerDependencies": {
+    "@luma.gl/core": "^9.0.0-beta"
   },
   "dependencies": {
-    "@babel/runtime": "^7.0.0",
-    "@luma.gl/constants": "9.0.0-beta.1",
-    "@luma.gl/core": "9.0.0-beta.1",
-    "@luma.gl/shadertools": "9.0.0-beta.1",
+    "@luma.gl/shadertools": "9.0.0-beta.10",
     "@math.gl/core": "^4.0.0",
     "@probe.gl/log": "^4.0.2",
     "@probe.gl/stats": "^4.0.2"
   },
-  "gitHead": "5fb42f651e80825336a372ca5a66de7d55611ddf"
+  "gitHead": "1b36500a878e1b365425826750320dde7d6929bb"
 }

package/src/animation/timeline.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 /**
@@ -9,30 +10,30 @@
  * @param repeat = 1
  */
 export type ChannelOptions = {
-  delay?: number
-  duration?: number
-  rate?: number
-  repeat?: number
-}
+  delay?: number;
+  duration?: number;
+  rate?: number;
+  repeat?: number;
+};
 
 export type AnimationOptions = {
-  setTime: (time: number) => void
-}
+  setTime: (time: number) => void;
+};
 
- type Channel = {
-  time: number
-  delay: number
-  duration: number
-  rate: number
-  repeat: number
-}
+type Channel = {
+  time: number;
+  delay: number;
+  duration: number;
+  rate: number;
+  repeat: number;
+};
 
 type Animation = {
   channel?: number;
   animation: {
-    setTime: (time: number) => void
-  }
-}
+    setTime: (time: number) => void;
+  };
+};
 
 let channelHandles = 1;
 let animationHandles = 1;
@@ -44,8 +45,7 @@ export class Timeline {
   playing: boolean = false;
   lastEngineTime: number = -1;
 
-  constructor() {
-  }
+  constructor() {}
 
   addChannel(props: ChannelOptions): number {
     const {delay = 0, duration = Number.POSITIVE_INFINITY, rate = 1, repeat = 1} = props;

package/src/animation-loop/animation-loop-template.ts

@@ -3,21 +3,23 @@ import type {AnimationProps} from './animation-props';
 /**
  * Minimal class that represents a "componentized" rendering life cycle
  * (resource construction, repeated rendering, resource destruction)
- * 
- * @note A motivation for this class compared to the raw animation loop is 
- * that it simplifies TypeScript code by allowing resources to be typed unconditionally 
+ *
+ * @note A motivation for this class compared to the raw animation loop is
+ * that it simplifies TypeScript code by allowing resources to be typed unconditionally
  * since they are allocated in the constructor rather than in onInitialized
- * 
+ *
  * @note Introduced in luma.gl v9
- * 
- * @example AnimationLoopTemplate is intended to be subclassed, 
+ *
+ * @example AnimationLoopTemplate is intended to be subclassed,
  * but the subclass should not be instantiated directly. Instead the subclass
- * (i.e. the constructor of the subclass) should be used 
+ * (i.e. the constructor of the subclass) should be used
  * as an argument to create an AnimationLoop.
  */
 export abstract class AnimationLoopTemplate {
   constructor(animationProps?: AnimationProps) {}
-  async onInitialize(animationProps: AnimationProps): Promise<unknown> { return null; }
+  async onInitialize(animationProps: AnimationProps): Promise<unknown> {
+    return null;
+  }
   abstract onRender(animationProps: AnimationProps): unknown;
   abstract onFinalize(animationProps: AnimationProps): void;
 }

package/src/animation-loop/animation-loop.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {luma, Device} from '@luma.gl/core';
@@ -32,23 +33,25 @@ export type MutableAnimationLoopProps = {
   autoResizeViewport?: boolean;
   autoResizeDrawingBuffer?: boolean;
   useDevicePixels?: number | boolean;
-}
+};
 
 const DEFAULT_ANIMATION_LOOP_PROPS: Required<AnimationLoopProps> = {
   device: null!,
 
   onAddHTML: () => '',
-  onInitialize: async () => { return null; },
+  onInitialize: async () => {
+    return null;
+  },
   onRender: () => {},
   onFinalize: () => {},
-  onError: (error) => console.error(error), // eslint-disable-line no-console
+  onError: error => console.error(error), // eslint-disable-line no-console
 
   stats: luma.stats.get(`animation-loop-${statIdCounter++}`),
 
   // view parameters
   useDevicePixels: true,
   autoResizeViewport: false,
-  autoResizeDrawingBuffer: false,
+  autoResizeDrawingBuffer: false
 };
 
 /** Convenient animation loop */
@@ -148,7 +151,6 @@ export class AnimationLoop {
     this._running = true;
 
     try {
-
       let appContext;
       if (!this._initialized) {
         this._initialized = true;
@@ -174,7 +176,7 @@ export class AnimationLoop {
 
       return this;
     } catch (err: unknown) {
-      const error = err instanceof Error ? err : new Error('Unknown error')
+      const error = err instanceof Error ? err : new Error('Unknown error');
       this.props.onError(error);
       // this._running = false; // TODO
       throw error;
@@ -242,7 +244,7 @@ export class AnimationLoop {
     this.setNeedsRedraw('waitForRender');
 
     if (!this._nextFramePromise) {
-      this._nextFramePromise = new Promise((resolve) => {
+      this._nextFramePromise = new Promise(resolve => {
         this._resolveNextFrame = resolve;
       });
     }
@@ -461,7 +463,7 @@ export class AnimationLoop {
     }
   }
 
-  _getSizeAndAspect(): {width: number; height: number; aspect: number}  {
+  _getSizeAndAspect(): {width: number; height: number; aspect: number} {
     if (!this.device) {
       return {width: 1, height: 1, aspect: 1};
     }
@@ -485,10 +487,18 @@ export class AnimationLoop {
 
   /** Default viewport setup */
   _resizeViewport(): void {
+    // TODO can we use canvas context to code this in a portable way?
     // @ts-expect-error Expose on canvasContext
     if (this.props.autoResizeViewport && this.device.gl) {
       // @ts-expect-error Expose canvasContext
-      this.device.gl.viewport(0, 0, this.device.gl.drawingBufferWidth, this.device.gl.drawingBufferHeight);
+      this.device.gl.viewport(
+        0,
+        0,
+        // @ts-expect-error Expose canvasContext
+        this.device.gl.drawingBufferWidth,
+        // @ts-expect-error Expose canvasContext
+        this.device.gl.drawingBufferHeight
+      );
     }
   }
 

package/src/animation-loop/animation-props.ts

@@ -1,5 +1,5 @@
 import {Device} from '@luma.gl/core';
-import {Timeline} from '../animation/timeline'
+import {Timeline} from '../animation/timeline';
 import type {AnimationLoop} from './animation-loop';
 
 /** Properties passed to every render frame  */

package/src/animation-loop/make-animation-loop.ts

@@ -1,20 +1,29 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {luma} from '@luma.gl/core';
-import {AnimationLoopTemplate} from './animation-loop-template'
-import {AnimationLoop, AnimationLoopProps} from './animation-loop'
+import {AnimationLoopTemplate} from './animation-loop-template';
+import {AnimationLoop, AnimationLoopProps} from './animation-loop';
 import type {AnimationProps} from './animation-props';
 
-export type MakeAnimationLoopProps = Omit<AnimationLoopProps, 'onCreateDevice' | 'onInitialize' | 'onRedraw' | 'onFinalize'>;
+export type MakeAnimationLoopProps = Omit<
+  AnimationLoopProps,
+  'onCreateDevice' | 'onInitialize' | 'onRedraw' | 'onFinalize'
+>;
 
 /** Instantiates and runs the render loop */
-export function makeAnimationLoop(AnimationLoopTemplateCtor: typeof AnimationLoopTemplate, props?: MakeAnimationLoopProps): AnimationLoop {
+export function makeAnimationLoop(
+  AnimationLoopTemplateCtor: typeof AnimationLoopTemplate,
+  props?: MakeAnimationLoopProps
+): AnimationLoop {
   let renderLoop: AnimationLoopTemplate | null = null;
 
   const device = props?.device || luma.createDevice();
 
   // Create an animation loop;
   const animationLoop = new AnimationLoop({
-    ... props,
+    ...props,
 
     device,
 
@@ -26,7 +35,7 @@ export function makeAnimationLoop(AnimationLoopTemplateCtor: typeof AnimationLoo
     },
 
     onRender: (animationProps: AnimationProps) => renderLoop?.onRender(animationProps),
-    
+
     onFinalize: (animationProps: AnimationProps) => renderLoop?.onFinalize(animationProps)
   });
 
@@ -35,7 +44,7 @@ export function makeAnimationLoop(AnimationLoopTemplateCtor: typeof AnimationLoo
     // @ts-ignore
     // eslint-disable-next-line no-invalid-this
     return this.AnimationLoopTemplateCtor.info;
-  }
+  };
 
   // Start the loop automatically
   // animationLoop.start();

package/src/computation.ts

@@ -0,0 +1,346 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TypedArray} from '@luma.gl/core';
+import type {DeviceFeature, ComputePipelineProps, Shader, Binding} from '@luma.gl/core';
+import {Device, Buffer, ComputePipeline, ComputePass, UniformStore} from '@luma.gl/core';
+import {log, uid, isNumberArray} from '@luma.gl/core';
+import {getTypedArrayFromDataType} from '@luma.gl/core';
+import type {ShaderModule, PlatformInfo} from '@luma.gl/shadertools';
+import {ShaderAssembler, getShaderLayoutFromWGSL} from '@luma.gl/shadertools';
+import {ShaderInputs} from './shader-inputs';
+import {PipelineFactory} from './lib/pipeline-factory';
+import {ShaderFactory} from './lib/shader-factory';
+// import {getDebugTableForShaderLayout} from '../debug/debug-shader-layout';
+
+const LOG_DRAW_PRIORITY = 2;
+const LOG_DRAW_TIMEOUT = 10000;
+
+export type ComputationProps = Omit<ComputePipelineProps, 'shader'> & {
+  source?: string;
+
+  /** shadertool shader modules (added to shader code) */
+  modules?: ShaderModule[];
+  /** Shadertool module defines (configures shader code)*/
+  defines?: Record<string, string | number | boolean>;
+  // TODO - injections, hooks etc?
+
+  /** Shader inputs, used to generated uniform buffers and bindings */
+  shaderInputs?: ShaderInputs;
+
+  /** Bindings */
+  bindings?: Record<string, Binding>;
+
+  /** Show shader source in browser? */
+  debugShaders?: 'never' | 'errors' | 'warnings' | 'always';
+
+  /** Factory used to create a {@link ComputePipeline}. Defaults to {@link Device} default factory. */
+  pipelineFactory?: PipelineFactory;
+  /** Factory used to create a {@link Shader}. Defaults to {@link Device} default factory. */
+  shaderFactory?: ShaderFactory;
+  /** Shader assembler. Defaults to the ShaderAssembler.getShaderAssembler() */
+  shaderAssembler?: ShaderAssembler;
+};
+
+/**
+ * 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
+ */
+export class Computation {
+  static defaultProps: Required<ComputationProps> = {
+    ...ComputePipeline.defaultProps,
+    id: 'unnamed',
+    handle: undefined,
+    userData: {},
+
+    source: '',
+    modules: [],
+    defines: {},
+
+    bindings: undefined!,
+    shaderInputs: undefined!,
+
+    pipelineFactory: undefined!,
+    shaderFactory: undefined!,
+    shaderAssembler: ShaderAssembler.getDefaultShaderAssembler(),
+
+    debugShaders: undefined
+  };
+
+  readonly device: Device;
+  readonly id: string;
+
+  readonly pipelineFactory: PipelineFactory;
+  readonly shaderFactory: ShaderFactory;
+
+  userData: {[key: string]: any} = {};
+
+  /** Bindings (textures, samplers, uniform buffers) */
+  bindings: Record<string, Binding> = {};
+
+  /** The underlying GPU "program". @note May be recreated if parameters change */
+  pipeline: ComputePipeline;
+  /** the underlying compiled compute shader */
+  shader: Shader;
+  source: string;
+
+  /** ShaderInputs instance */
+  shaderInputs: ShaderInputs;
+
+  _uniformStore: UniformStore;
+
+  _pipelineNeedsUpdate: string | false = 'newly created';
+
+  private _getModuleUniforms: (props?: Record<string, Record<string, any>>) => Record<string, any>;
+  private props: Required<ComputationProps>;
+
+  private _destroyed = false;
+
+  constructor(device: Device, props: ComputationProps) {
+    if (device.type !== 'webgpu') {
+      throw new Error('Computation is only supported in WebGPU');
+    }
+
+    this.props = {...Computation.defaultProps, ...props};
+    props = this.props;
+    this.id = props.id || uid('model');
+    this.device = device;
+
+    Object.assign(this.userData, props.userData);
+
+    // Setup shader module inputs
+    const moduleMap = Object.fromEntries(
+      this.props.modules?.map(module => [module.name, module]) || []
+    );
+    this.setShaderInputs(props.shaderInputs || new ShaderInputs(moduleMap));
+
+    // Support WGSL shader layout introspection
+    // TODO - Don't modify props!!
+    this.props.shaderLayout ||= getShaderLayoutFromWGSL(this.props.source);
+
+    // Setup shader assembler
+    const platformInfo = getPlatformInfo(device);
+
+    // Extract modules from shader inputs if not supplied
+    const modules =
+      (this.props.modules?.length > 0 ? this.props.modules : this.shaderInputs?.getModules()) || [];
+
+    this.pipelineFactory =
+      props.pipelineFactory || PipelineFactory.getDefaultPipelineFactory(this.device);
+    this.shaderFactory = props.shaderFactory || ShaderFactory.getDefaultShaderFactory(this.device);
+
+    const {source, getUniforms} = this.props.shaderAssembler.assembleShader({
+      platformInfo,
+      ...this.props,
+      modules
+    });
+
+    this.source = source;
+
+    this._getModuleUniforms = getUniforms;
+
+    // Create the pipeline
+    // @note order is important
+    this.pipeline = this._updatePipeline();
+
+    // Apply any dynamic settings that will not trigger pipeline change
+    if (props.bindings) {
+      this.setBindings(props.bindings);
+    }
+
+    // Catch any access to non-standard props
+    Object.seal(this);
+  }
+
+  destroy(): void {
+    if (this._destroyed) return;
+    this.pipelineFactory.release(this.pipeline);
+    this.shaderFactory.release(this.shader);
+    this._uniformStore.destroy();
+    this._destroyed = true;
+  }
+
+  // Draw call
+
+  predraw() {
+    // Update uniform buffers if needed
+    this.updateShaderInputs();
+  }
+
+  dispatch(computePass: ComputePass, x: number, y?: number, z?: number): void {
+    try {
+      this._logDrawCallStart();
+
+      // Check if the pipeline is invalidated
+      // TODO - this is likely the worst place to do this from performance perspective. Perhaps add a predraw()?
+      this.pipeline = this._updatePipeline();
+
+      // 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
+      this.pipeline.setBindings(this.bindings);
+      computePass.setPipeline(this.pipeline);
+      // @ts-expect-error
+      computePass.setBindings([]);
+
+      computePass.dispatch(x, y, z);
+    } finally {
+      this._logDrawCallEnd();
+    }
+  }
+
+  // Update fixed fields (can trigger pipeline rebuild)
+
+  // Update dynamic fields
+
+  /**
+   * Updates the vertex count (used in draw calls)
+   * @note Any attributes with stepMode=vertex need to be at least this big
+   */
+  setVertexCount(vertexCount: number): void {
+    // this.vertexCount = vertexCount;
+  }
+
+  /**
+   * Updates the instance count (used in draw calls)
+   * @note Any attributes with stepMode=instance need to be at least this big
+   */
+  setInstanceCount(instanceCount: number): void {
+    // this.instanceCount = instanceCount;
+  }
+
+  setShaderInputs(shaderInputs: ShaderInputs): void {
+    this.shaderInputs = shaderInputs;
+    this._uniformStore = new UniformStore(this.shaderInputs.modules);
+    // Create uniform buffer bindings for all modules
+    for (const moduleName of Object.keys(this.shaderInputs.modules)) {
+      const uniformBuffer = this._uniformStore.getManagedUniformBuffer(this.device, moduleName);
+      this.bindings[`${moduleName}Uniforms`] = uniformBuffer;
+    }
+  }
+
+  /**
+   * Updates shader module settings (which results in uniforms being set)
+   */
+  setShaderModuleProps(props: Record<string, any>): void {
+    const uniforms = this._getModuleUniforms(props);
+
+    // Extract textures & framebuffers set by the modules
+    // TODO better way to extract bindings
+    const keys = Object.keys(uniforms).filter(k => {
+      const uniform = uniforms[k];
+      return !isNumberArray(uniform) && typeof uniform !== 'number' && typeof uniform !== 'boolean';
+    });
+    const bindings: Record<string, Binding> = {};
+    for (const k of keys) {
+      bindings[k] = uniforms[k];
+      delete uniforms[k];
+    }
+  }
+
+  updateShaderInputs(): void {
+    this._uniformStore.setUniforms(this.shaderInputs.getUniformValues());
+  }
+
+  /**
+   * Sets bindings (textures, samplers, uniform buffers)
+   */
+  setBindings(bindings: Record<string, Binding>): void {
+    Object.assign(this.bindings, bindings);
+  }
+
+  _setPipelineNeedsUpdate(reason: string): void {
+    this._pipelineNeedsUpdate = this._pipelineNeedsUpdate || reason;
+  }
+
+  _updatePipeline(): ComputePipeline {
+    if (this._pipelineNeedsUpdate) {
+      let prevShader: Shader | null = null;
+      if (this.pipeline) {
+        log.log(
+          1,
+          `Model ${this.id}: Recreating pipeline because "${this._pipelineNeedsUpdate}".`
+        )();
+        prevShader = this.shader;
+      }
+
+      this._pipelineNeedsUpdate = false;
+
+      this.shader = this.shaderFactory.createShader({
+        id: `${this.id}-fragment`,
+        stage: 'compute',
+        source: this.source,
+        debug: this.props.debugShaders
+      });
+
+      this.pipeline = this.pipelineFactory.createComputePipeline({
+        ...this.props,
+        shader: this.shader
+      });
+
+      if (prevShader) {
+        this.shaderFactory.release(prevShader);
+      }
+    }
+    return this.pipeline;
+  }
+
+  /** Throttle draw call logging */
+  _lastLogTime = 0;
+  _logOpen = false;
+
+  _logDrawCallStart(): void {
+    // IF level is 4 or higher, log every frame.
+    const logDrawTimeout = log.level > 3 ? 0 : LOG_DRAW_TIMEOUT;
+    if (log.level < 2 || Date.now() - this._lastLogTime < logDrawTimeout) {
+      return;
+    }
+
+    this._lastLogTime = Date.now();
+    this._logOpen = true;
+
+    log.group(LOG_DRAW_PRIORITY, `>>> DRAWING MODEL ${this.id}`, {collapsed: log.level <= 2})();
+  }
+
+  _logDrawCallEnd(): void {
+    if (this._logOpen) {
+      // const shaderLayoutTable = getDebugTableForShaderLayout(this.pipeline.props.shaderLayout, this.id);
+
+      // log.table(logLevel, attributeTable)();
+      // log.table(logLevel, uniformTable)();
+      // log.table(LOG_DRAW_PRIORITY, shaderLayoutTable)();
+
+      const uniformTable = this.shaderInputs.getDebugTable();
+      log.table(LOG_DRAW_PRIORITY, uniformTable)();
+
+      log.groupEnd(LOG_DRAW_PRIORITY)();
+      this._logOpen = false;
+    }
+  }
+
+  protected _drawCount = 0;
+
+  // TODO - fix typing of luma data types
+  _getBufferOrConstantValues(attribute: Buffer | TypedArray, dataType: any): string {
+    const TypedArrayConstructor = getTypedArrayFromDataType(dataType);
+    const typedArray =
+      attribute instanceof Buffer ? new TypedArrayConstructor(attribute.debugData) : attribute;
+    return typedArray.toString();
+  }
+}
+
+/** Create a shadertools platform info from the Device */
+export function getPlatformInfo(device: Device): PlatformInfo {
+  return {
+    type: device.type,
+    shaderLanguage: device.info.shadingLanguage,
+    shaderLanguageVersion: device.info.shadingLanguageVersion as 100 | 300,
+    gpu: device.info.gpu,
+    // HACK - we pretend that the DeviceFeatures is a Set, it has a similar API
+    features: device.features as unknown as Set<DeviceFeature>
+  };
+}

package/src/debug/copy-texture-to-image.ts

@@ -1,6 +1,8 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 import {Texture, Framebuffer} from '@luma.gl/core';
-import {GL} from '@luma.gl/constants';
 import {flipRows, scalePixels} from './pixel-data-utils';
 
 /**
@@ -8,7 +10,7 @@ import {flipRows, scalePixels} from './pixel-data-utils';
  * @todo - support gl.readBuffer
  */
 export type CopyTextureToImageOptions = {
-  sourceAttachment?: number; 
+  sourceAttachment?: number;
   targetMaxHeight?: number;
   targetImage?: HTMLImageElement;
 };
@@ -16,15 +18,14 @@ export type CopyTextureToImageOptions = {
 /**
  * Reads pixels from a Framebuffer or Texture object into an HTML Image
  * @todo - can we move this to @luma.gl/core?
- * @param source 
+ * @param source
  * @param options options passed to copyToDataUrl
- * @returns 
+ * @returns
  */
 export function copyTextureToImage(
   source: Texture | Framebuffer,
   options?: CopyTextureToImageOptions
 ): HTMLImageElement {
-
   const dataUrl = copyTextureToDataUrl(source, options);
   const targetImage: HTMLImageElement = options?.targetImage || new Image();
   targetImage.src = dataUrl;
@@ -36,16 +37,13 @@ export function copyTextureToImage(
  * Reads pixels from a Framebuffer or Texture object to a dataUrl
  * @todo - can we move this to @luma.gl/core?
  * @param source texture or framebuffer to read from
- * @param options 
+ * @param options
  */
 export function copyTextureToDataUrl(
   source: Texture | Framebuffer,
   options: CopyTextureToImageOptions = {}
 ): string {
-  const {
-    sourceAttachment = GL.COLOR_ATTACHMENT0, // TODO - support gl.readBuffer
-    targetMaxHeight = Number.MAX_SAFE_INTEGER
-  } = options;
+  const {sourceAttachment, targetMaxHeight = Number.MAX_SAFE_INTEGER} = options;
 
   let data = source.device.readPixelsToArrayWebGL(source, {sourceAttachment});