@luma.gl/engine 9.0.0-alpha.3 → 9.0.0-alpha.30

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@luma.gl/engine",
-  "version": "9.0.0-alpha.3",
+  "version": "9.0.0-alpha.30",
   "description": "WebGL2 Components for High Performance Rendering and Computation",
+  "type": "module",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -16,27 +17,36 @@
     "animation",
     "3d"
   ],
-  "types": "src/index.ts",
-  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.cjs",
   "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "files": [
     "src",
     "dist",
+    "dist.min.js",
     "README.md"
   ],
   "sideEffects": false,
   "scripts": {
-    "pre-build": "npm run build-bundle",
-    "build-bundle": "webpack --display=minimal --config ../../scripts/bundle.config.js"
+    "build-bundle": "ocular-bundle ./src/index.ts",
+    "pre-build": "npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
     "@babel/runtime": "^7.0.0",
-    "@luma.gl/constants": "9.0.0-alpha.3",
-    "@luma.gl/shadertools": "9.0.0-alpha.3",
-    "@luma.gl/webgl": "9.0.0-alpha.3",
-    "@math.gl/core": "^3.5.0",
-    "@probe.gl/log": "^3.5.0",
-    "@probe.gl/stats": "^3.5.0"
+    "@luma.gl/constants": "9.0.0-alpha.30",
+    "@luma.gl/core": "9.0.0-alpha.30",
+    "@luma.gl/shadertools": "9.0.0-alpha.30",
+    "@luma.gl/webgl": "9.0.0-alpha.30",
+    "@math.gl/core": "4.0.0-alpha.4",
+    "@probe.gl/log": "^4.0.2",
+    "@probe.gl/stats": "^4.0.2"
   },
-  "gitHead": "3f259d0de774c6b98dd5ded61e64a0bd9f58b61e"
+  "gitHead": "7fb163f20d3400d59b59a17d36b4f3c466c559ba"
 }

package/src/animation/timeline.ts

@@ -7,7 +7,7 @@
  * @param rate = 1
  * @param repeat = 1
  */
- export type ChannelOptions = {
+export type ChannelOptions = {
   delay?: number
   duration?: number
   rate?: number
@@ -27,7 +27,7 @@ export type AnimationOptions = {
 }
 
 type Animation = {
-  channel: number;
+  channel?: number;
   animation: {
     setTime: (time: number) => void
   }

package/src/{lib → animation-loop}/animation-loop.ts

@@ -1,63 +1,64 @@
-import {luma, Device, DeviceProps} from '@luma.gl/api';
-import {requestAnimationFrame, cancelAnimationFrame} from '@luma.gl/api';
+// luma.gl, MIT license
+
+import {luma, Device} from '@luma.gl/core';
+import {requestAnimationFrame, cancelAnimationFrame} from '@luma.gl/core';
 import {Timeline} from '../animation/timeline';
-import {AnimationProps} from '../lib/animation-props';
+import {AnimationProps} from './animation-props';
 import {Stats, Stat} from '@probe.gl/stats';
-import {isBrowser} from '@probe.gl/env';
-
-const isPage = isBrowser() && typeof document !== 'undefined';
 
 let statIdCounter = 0;
 
-type ContextProps = DeviceProps;
-
 /** AnimationLoop properties */
 export type AnimationLoopProps = {
-  onCreateDevice?: (props: DeviceProps) => Promise<Device>;
+  device: Device | Promise<Device>;
+
   onAddHTML?: (div: HTMLDivElement) => string; // innerHTML
-  onInitialize?: (animationProps: AnimationProps) => void;
-  onRender?: (animationProps: AnimationProps) => void;
+  onInitialize?: (animationProps: AnimationProps) => Promise<unknown>;
+  onRender?: (animationProps: AnimationProps) => unknown;
   onFinalize?: (animationProps: AnimationProps) => void;
   onError?: (reason: Error) => void;
 
-  device?: Device;
-  deviceProps?: DeviceProps;
   stats?: Stats;
 
-  // view parameters
-  debug?: boolean;
+  // view parameters - TODO move to CanvasContext?
   autoResizeViewport?: boolean;
   autoResizeDrawingBuffer?: boolean;
   useDevicePixels?: number | boolean;
 };
 
+export type MutableAnimationLoopProps = {
+  // view parameters
+  autoResizeViewport?: boolean;
+  autoResizeDrawingBuffer?: boolean;
+  useDevicePixels?: number | boolean;
+}
+
+
 const DEFAULT_ANIMATION_LOOP_PROPS: Required<AnimationLoopProps> = {
-  onCreateDevice: (props: DeviceProps): Promise<Device> => luma.createDevice(props),
-  onAddHTML: undefined,
-  onInitialize: () => ({}),
+  device: null!,
+
+  onAddHTML: () => '',
+  onInitialize: async () => { return null; },
   onRender: () => {},
   onFinalize: () => {},
   onError: (error) => console.error(error), // eslint-disable-line no-console
 
-  device: undefined,
-  deviceProps: {},
-  debug: false,
   stats: luma.stats.get(`animation-loop-${statIdCounter++}`),
 
   // view parameters
   useDevicePixels: true,
-  autoResizeViewport: true,
-  autoResizeDrawingBuffer: true,
+  autoResizeViewport: false,
+  autoResizeDrawingBuffer: false,
 };
 
 /** Convenient animation loop */
-export default class AnimationLoop {
-  device: Device;
-  canvas: HTMLCanvasElement; // | OffscreenCanvas;
+export class AnimationLoop {
+  device: Device | null = null;
+  canvas: HTMLCanvasElement | OffscreenCanvas | null = null;
 
   props: Required<AnimationLoopProps>;
-  animationProps: AnimationProps;
-  timeline: Timeline = null;
+  animationProps: AnimationProps | null = null;
+  timeline: Timeline | null = null;
   stats: Stats;
   cpuTime: Stat;
   gpuTime: Stat;
@@ -65,13 +66,13 @@ export default class AnimationLoop {
 
   display: any;
 
-  needsRedraw: string | null = 'initialized';
+  needsRedraw: string | false = 'initialized';
 
   _initialized: boolean = false;
   _running: boolean = false;
-  _animationFrameId = null;
+  _animationFrameId: any = null;
   _nextFramePromise: Promise<AnimationLoop> | null = null;
-  _resolveNextFrame: ((AnimationLoop) => void) | null = null;
+  _resolveNextFrame: ((animationLoop: AnimationLoop) => void) | null = null;
   _cpuStartTime: number = 0;
 
   // _gpuTimeQuery: Query | null = null;
@@ -79,18 +80,18 @@ export default class AnimationLoop {
   /*
    * @param {HTMLCanvasElement} canvas - if provided, width and height will be passed to context
    */
-  constructor(props: AnimationLoopProps = {}) {
+  constructor(props: AnimationLoopProps) {
     this.props = {...DEFAULT_ANIMATION_LOOP_PROPS, ...props};
     props = this.props;
 
-    let {useDevicePixels = true} = this.props;
+    if (!props.device) {
+      throw new Error('No device provided');
+    }
 
-    // state
-    this.device = props.device;
-    // @ts-expect-error
-    this.gl = (this.device && this.device.gl) || props.gl;
+    const {useDevicePixels = true} = this.props;
 
-    this.stats = props.stats;
+    // state
+    this.stats = props.stats || new Stats({id: 'animation-loop-stats'});
     this.cpuTime = this.stats.get('CPU Time');
     this.gpuTime = this.stats.get('GPU Time');
     this.frameRate = this.stats.get('Frame Rate');
@@ -125,15 +126,15 @@ export default class AnimationLoop {
   }
 
   // TODO - move to CanvasContext
-  setProps(props: AnimationLoopProps): this {
+  setProps(props: MutableAnimationLoopProps): this {
     if ('autoResizeViewport' in props) {
-      this.props.autoResizeViewport = props.autoResizeViewport;
+      this.props.autoResizeViewport = props.autoResizeViewport || false;
     }
     if ('autoResizeDrawingBuffer' in props) {
-      this.props.autoResizeDrawingBuffer = props.autoResizeDrawingBuffer;
+      this.props.autoResizeDrawingBuffer = props.autoResizeDrawingBuffer || false;
     }
     if ('useDevicePixels' in props) {
-      this.props.useDevicePixels = props.useDevicePixels;
+      this.props.useDevicePixels = props.useDevicePixels || false;
     }
     return this;
   }
@@ -155,11 +156,11 @@ export default class AnimationLoop {
       if (!this._initialized) {
         this._initialized = true;
         // Create the WebGL context
-        await this._createDevice();
+        await this._initDevice();
         this._initialize();
 
         // Note: onIntialize can return a promise (e.g. in case app needs to load resources)
-        await this.onInitialize(this.animationProps);
+        await this.props.onInitialize(this._getAnimationProps());
       }
 
       // check that we haven't been stopped
@@ -185,16 +186,16 @@ export default class AnimationLoop {
 
   /** Explicitly draw a frame */
   redraw(): this {
-    if (this.device.isLost) {
+    if (this.device?.isLost) {
       return this;
     }
 
     this._beginTimers();
 
     this._setupFrame();
-    this._updateCallbackData();
+    this._updateAnimationProps();
 
-    this._renderFrame(this.animationProps);
+    this._renderFrame(this._getAnimationProps());
 
     // clear needsRedraw flag
     this._clearNeedsRedraw();
@@ -215,7 +216,10 @@ export default class AnimationLoop {
     // console.debug(`Stopping ${this.constructor.name}`);
     if (this._running) {
       // call callback
-      this.onFinalize(this.animationProps);
+      // If stop is called immediately, we can end up in a state where props haven't been initialized...
+      if (this.animationProps) {
+        this.props.onFinalize(this.animationProps);
+      }
 
       this._cancelAnimationFrame();
       this._nextFramePromise = null;
@@ -245,26 +249,13 @@ export default class AnimationLoop {
     return this._nextFramePromise;
   }
 
-  async toDataURL() {
+  async toDataURL(): Promise<string> {
     this.setNeedsRedraw('toDataURL');
     await this.waitForRender();
-    return this.canvas.toDataURL();
-  }
-
-  onCreateDevice(deviceProps: DeviceProps): Promise<Device> {
-    return this.props.onCreateDevice(deviceProps);
-  }
-
-  onInitialize(animationProps: AnimationProps): {} | void {
-    return this.props.onInitialize(animationProps);
-  }
-
-  onRender(animationProps: AnimationProps) {
-    return this.props.onRender(animationProps);
-  }
-
-  onFinalize(animationProps: AnimationProps) {
-    return this.props.onFinalize(animationProps);
+    if (this.canvas instanceof HTMLCanvasElement) {
+      return this.canvas.toDataURL();
+    }
+    throw new Error('OffscreenCanvas');
   }
 
   // PRIVATE METHODS
@@ -273,8 +264,8 @@ export default class AnimationLoop {
     this._startEventHandling();
 
     // Initialize the callback data
-    this._initializeCallbackData();
-    this._updateCallbackData();
+    this._initializeAnimationProps();
+    this._updateAnimationProps();
 
     // Default viewport setup, in case onInitialize wants to render
     this._resizeCanvasDrawingBuffer();
@@ -283,9 +274,9 @@ export default class AnimationLoop {
     // this._gpuTimeQuery = Query.isSupported(this.gl, ['timers']) ? new Query(this.gl) : null;
   }
 
-  _setDisplay(display) {
+  _setDisplay(display: any) {
     if (this.display) {
-      this.display.delete();
+      this.display.destroy();
       this.display.animationLoop = null;
     }
 
@@ -322,7 +313,7 @@ export default class AnimationLoop {
     // if (this.display && this.display.cancelAnimationFrame) {
     //   this.display.cancelAnimationFrame(this._animationFrameId);
     // }
-  cancelAnimationFrame(this._animationFrameId);
+    cancelAnimationFrame(this._animationFrameId);
     this._animationFrameId = null;
   }
 
@@ -336,20 +327,20 @@ export default class AnimationLoop {
 
   // Called on each frame, can be overridden to call onRender multiple times
   // to support e.g. stereoscopic rendering
-  _renderFrame(props: AnimationProps) {
+  _renderFrame(animationProps: AnimationProps) {
     // Allow e.g. VR display to render multiple frames.
     if (this.display) {
-      this.display._renderFrame(props);
+      this.display._renderFrame(animationProps);
       return;
     }
 
     // call callback
-    this.onRender(props);
+    this.props.onRender(this._getAnimationProps());
     // end callback
   }
 
   _clearNeedsRedraw() {
-    this.needsRedraw = null;
+    this.needsRedraw = false;
   }
 
   _setupFrame() {
@@ -358,16 +349,21 @@ export default class AnimationLoop {
   }
 
   // Initialize the  object that will be passed to app callbacks
-  _initializeCallbackData() {
+  _initializeAnimationProps() {
+    if (!this.device) {
+      throw new Error('loop');
+    }
     this.animationProps = {
       animationLoop: this,
+
       device: this.device,
-      canvas: this.device.canvasContext.canvas,
+      canvas: this.device?.canvasContext?.canvas,
+      renderPass: this.device.getDefaultRenderPass(),
       timeline: this.timeline,
 
       // Initial values
       useDevicePixels: this.props.useDevicePixels,
-      needsRedraw: null,
+      needsRedraw: false,
 
       // Placeholders
       width: 1,
@@ -386,8 +382,21 @@ export default class AnimationLoop {
     };
   }
 
+  _getAnimationProps(): AnimationProps {
+    if (!this.animationProps) {
+      throw new Error('animationProps');
+    }
+    return this.animationProps;
+  }
+
   // Update the context object that will be passed to app callbacks
-  _updateCallbackData() {
+  _updateAnimationProps(): void {
+    if (!this.animationProps) {
+      return;
+    }
+
+    this.animationProps.renderPass = this.device.getDefaultRenderPass();
+
     const {width, height, aspect} = this._getSizeAndAspect();
     if (width !== this.animationProps.width || height !== this.animationProps.height) {
       this.setNeedsRedraw('drawing buffer resized');
@@ -418,13 +427,14 @@ export default class AnimationLoop {
       : this.animationProps.engineTime;
   }
 
-  /** Either uses supplied or existing context, or calls provided callback to create one */
-  async _createDevice() {
-    const deviceProps = {...this.props, ...this.props.deviceProps};
-    this.device = await this.onCreateDevice(deviceProps);
-    // @ts-expect-error
-    this.canvas = this.device.canvasContext.canvas;
-    this._createInfoDiv();
+  /** Wait for supplied device */
+  async _initDevice() {
+    this.device = await this.props.device;
+    if (!this.device) {
+      throw new Error('No device provided');
+    }
+    this.canvas = this.device.canvasContext?.canvas || null;
+    // this._createInfoDiv();
   }
 
   _createInfoDiv() {
@@ -438,7 +448,9 @@ export default class AnimationLoop {
       div.style.bottom = '10px';
       div.style.width = '300px';
       div.style.background = 'white';
-      wrapperDiv.appendChild(this.canvas);
+      if (this.canvas instanceof HTMLCanvasElement) {
+        wrapperDiv.appendChild(this.canvas);
+      }
       wrapperDiv.appendChild(div);
       const html = this.props.onAddHTML(div);
       if (html) {
@@ -447,13 +459,16 @@ export default class AnimationLoop {
     }
   }
 
-  _getSizeAndAspect() {
+  _getSizeAndAspect(): {width: number; height: number; aspect: number}  {
+    if (!this.device) {
+      return {width: 1, height: 1, aspect: 1};
+    }
     // https://webglfundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
-    const [width, height] = this.device.canvasContext.getPixelSize();
+    const [width, height] = this.device?.canvasContext?.getPixelSize() || [1, 1];
 
     // https://webglfundamentals.org/webgl/lessons/webgl-anti-patterns.html
     let aspect = 1;
-    const canvas = this.device.canvasContext.canvas;
+    const canvas = this.device?.canvasContext?.canvas;
 
     // @ts-expect-error
     if (canvas && canvas.clientHeight) {
@@ -481,7 +496,7 @@ export default class AnimationLoop {
    */
   _resizeCanvasDrawingBuffer() {
     if (this.props.autoResizeDrawingBuffer) {
-      this.device.canvasContext.resize({useDevicePixels: this.props.useDevicePixels});
+      this.device?.canvasContext?.resize({useDevicePixels: this.props.useDevicePixels});
     }
   }
 
@@ -521,15 +536,18 @@ export default class AnimationLoop {
 
   _startEventHandling() {
     if (this.canvas) {
-      this.canvas.addEventListener('mousemove', this._onMousemove);
-      this.canvas.addEventListener('mouseleave', this._onMouseleave);
+      this.canvas.addEventListener('mousemove', this._onMousemove.bind(this));
+      this.canvas.addEventListener('mouseleave', this._onMouseleave.bind(this));
     }
   }
 
-  _onMousemove(e) {
-    this.animationProps._mousePosition = [e.offsetX, e.offsetY];
+  _onMousemove(event: Event) {
+    if (event instanceof MouseEvent) {
+      this._getAnimationProps()._mousePosition = [event.offsetX, event.offsetY];
+    }
   }
-  _onMouseleave(e) {
-    this.animationProps._mousePosition = null;
+
+  _onMouseleave(event: Event) {
+    this._getAnimationProps()._mousePosition = null;
   }
 }

package/src/{lib → animation-loop}/animation-props.ts

@@ -1,10 +1,11 @@
-import {Device} from '@luma.gl/api';
+import {Device, RenderPass} from '@luma.gl/core';
 import {Timeline} from '../animation/timeline'
-import type AnimationLoop from './animation-loop';
+import type {AnimationLoop} from './animation-loop';
 
 /** Properties passed to every render frame  */
 export type AnimationProps = {
   device: Device;
+  renderPass: RenderPass;
   animationLoop: AnimationLoop;
 
   /** @todo Should be canvasContext */
@@ -22,10 +23,10 @@ export type AnimationProps = {
   tock: number;
 
   // Initial values
-  needsRedraw?: string;
+  needsRedraw?: string | false;
 
-  timeline: Timeline;
+  timeline: Timeline | null;
 
   // Experimental
-  _mousePosition?: [number, number]; // [offsetX, offsetY],
+  _mousePosition?: [number, number] | null; // [offsetX, offsetY],
 };

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

@@ -0,0 +1,44 @@
+// luma.gl, MIT license
+import {luma} from '@luma.gl/core';
+import {AnimationLoopTemplate} from './render-loop'
+import {AnimationLoop, AnimationLoopProps} from './animation-loop'
+import type {AnimationProps} from './animation-props';
+
+export type MakeAnimationLoopProps = Omit<AnimationLoopProps, 'onCreateDevice' | 'onInitialize' | 'onRedraw' | 'onFinalize'>;
+
+/** Instantiates and runs the render loop */
+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,
+
+    device,
+
+    async onInitialize(animationProps: AnimationProps): Promise<unknown> {
+      // @ts-expect-error abstract to prevent instantiation
+      renderLoop = new AnimationLoopTemplateCtor(animationProps);
+      // Any async loading can be handled here
+      return await renderLoop?.onInitialize(animationProps);
+    },
+
+    onRender: (animationProps: AnimationProps) => renderLoop?.onRender(animationProps),
+    
+    onFinalize: (animationProps: AnimationProps) => renderLoop?.onFinalize(animationProps)
+  });
+
+  // @ts-expect-error Hack: adds info for the website to find
+  animationLoop.getInfo = () => {
+    // @ts-ignore
+    // eslint-disable-next-line no-invalid-this
+    return this.AnimationLoopTemplateCtor.info;
+  }
+
+  // Start the loop automatically
+  // animationLoop.start();
+
+  return animationLoop;
+}

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

@@ -0,0 +1,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 
+ * since they are allocated in the constructor rather than in onInitialized
+ * 
+ * @note Introduced in luma.gl v9
+ * 
+ * @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 
+ * as an argument to create an AnimationLoop.
+ */
+export abstract class AnimationLoopTemplate {
+  constructor(animationProps?: AnimationProps) {}
+  async onInitialize(animationProps: AnimationProps): Promise<unknown> { return null; }
+  abstract onRender(animationProps: AnimationProps): unknown;
+  abstract onFinalize(animationProps: AnimationProps): void;
+}

package/src/geometries/cone-geometry.ts

@@ -1,4 +1,4 @@
-import {uid} from '@luma.gl/api';
+import {uid} from '@luma.gl/core';
 import {TruncatedConeGeometry} from './truncated-cone-geometry';
 
 export type ConeGeometryProps = {

package/src/geometries/cube-geometry.ts

@@ -1,11 +1,11 @@
-import {uid} from '@luma.gl/api';
-import Geometry from '../geometry/geometry';
+import {uid} from '@luma.gl/core';
+import {Geometry} from '../geometry/geometry';
 // import type {GeometryType} from '../geometry/geometry-type';
 
 export type CubeGeometryProps = {
   id?: string;
   indices?: boolean;
-  attributes?;
+  attributes?: any;
 };
 
 export class CubeGeometry extends Geometry {
@@ -14,11 +14,14 @@ export class CubeGeometry extends Geometry {
     super(indices ? {
       ...props,
       id,
+      topology: 'triangle-list',
       indices: {size: 1, value: CUBE_INDICES},
       attributes: {...ATTRIBUTES, ...props.attributes}
     } : {
       ...props,
       id,
+      topology: 'triangle-list',
+      indices: undefined,
       attributes: {...NON_INDEXED_ATTRIBUTES, ...props.attributes}
     });
   }

package/src/geometries/cylinder-geometry.ts

@@ -1,10 +1,10 @@
-import {uid} from '@luma.gl/api';
+import {uid} from '@luma.gl/core';
 import {TruncatedConeGeometry} from './truncated-cone-geometry';
 
 export type CylinderGeometryProps = {
   id?: string;
   radius?: number;
-  attributes?
+  attributes?: any;
 };
 
 export class CylinderGeometry extends TruncatedConeGeometry {