@luma.gl/engine 9.0.0-alpha.5 → 9.0.0-alpha.50

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@luma.gl/engine",
-  "version": "9.0.0-alpha.5",
+  "version": "9.0.0-alpha.50",
   "description": "WebGL2 Components for High Performance Rendering and Computation",
+  "type": "module",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -16,27 +17,35 @@
     "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.5",
-    "@luma.gl/shadertools": "9.0.0-alpha.5",
-    "@luma.gl/webgl": "9.0.0-alpha.5",
-    "@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.50",
+    "@luma.gl/core": "9.0.0-alpha.50",
+    "@luma.gl/shadertools": "9.0.0-alpha.50",
+    "@math.gl/core": "^4.0.0",
+    "@probe.gl/log": "^4.0.2",
+    "@probe.gl/stats": "^4.0.2"
   },
-  "gitHead": "729cfdd272836270d0f59793b8a36a2a3aea47ca"
+  "gitHead": "83899806fcfab67f97cc8b308f81e4844a05ca05"
 }

package/src/animation/timeline.ts

@@ -1,4 +1,5 @@
 // luma.gl, MIT license
+// Copyright (c) vis.gl contributors
 
 /**
  * Timeline channel properties
@@ -7,7 +8,7 @@
  * @param rate = 1
  * @param repeat = 1
  */
- export type ChannelOptions = {
+export type ChannelOptions = {
   delay?: number
   duration?: number
   rate?: number
@@ -27,7 +28,7 @@ export type AnimationOptions = {
 }
 
 type Animation = {
-  channel: number;
+  channel?: number;
   animation: {
     setTime: (time: number) => void
   }
@@ -49,7 +50,7 @@ export class Timeline {
   addChannel(props: ChannelOptions): number {
     const {delay = 0, duration = Number.POSITIVE_INFINITY, rate = 1, repeat = 1} = props;
 
-    const handle = channelHandles++;
+    const channelId = channelHandles++;
     const channel: Channel = {
       time: 0,
       delay,
@@ -58,23 +59,23 @@ export class Timeline {
       repeat
     };
     this._setChannelTime(channel, this.time);
-    this.channels.set(handle, channel);
+    this.channels.set(channelId, channel);
 
-    return handle;
+    return channelId;
   }
 
-  removeChannel(handle: number): void {
-    this.channels.delete(handle);
+  removeChannel(channelId: number): void {
+    this.channels.delete(channelId);
 
     for (const [animationHandle, animation] of this.animations) {
-      if (animation.channel === handle) {
+      if (animation.channel === channelId) {
         this.detachAnimation(animationHandle);
       }
     }
   }
 
-  isFinished(handle: number): boolean {
-    const channel = this.channels.get(handle);
+  isFinished(channelId: number): boolean {
+    const channel = this.channels.get(channelId);
     if (channel === undefined) {
       return false;
     }
@@ -82,12 +83,12 @@ export class Timeline {
     return this.time >= channel.delay + channel.duration * channel.repeat;
   }
 
-  getTime(handle?: number): number {
-    if (handle === undefined) {
+  getTime(channelId?: number): number {
+    if (channelId === undefined) {
       return this.time;
     }
 
-    const channel = this.channels.get(handle);
+    const channel = this.channels.get(channelId);
 
     if (channel === undefined) {
       return -1;
@@ -137,8 +138,8 @@ export class Timeline {
     return animationHandle;
   }
 
-  detachAnimation(handle: number): void {
-    this.animations.delete(handle);
+  detachAnimation(channelId: number): void {
+    this.animations.delete(channelId);
   }
 
   update(engineTime: number): void {

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

@@ -1,63 +1,65 @@
-import {luma, Device, DeviceProps} from '@luma.gl/api';
-import {requestAnimationFrame, cancelAnimationFrame} from '@luma.gl/api';
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+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 +67,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 +81,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 +127,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;
   }
@@ -146,20 +148,16 @@ export default class AnimationLoop {
     this._running = true;
 
     try {
-      // check that we haven't been stopped
-      if (!this._running) {
-        return null;
-      }
 
       let appContext;
       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 +183,16 @@ export default class AnimationLoop {
 
   /** Explicitly draw a frame */
   redraw(): this {
-    if (this.device.isLost) {
+    if (this.device?.isLost) {
       return this;
     }
 
-    this._beginTimers();
+    this._beginFrameTimers();
 
     this._setupFrame();
-    this._updateCallbackData();
+    this._updateAnimationProps();
 
-    this._renderFrame(this.animationProps);
+    this._renderFrame(this._getAnimationProps());
 
     // clear needsRedraw flag
     this._clearNeedsRedraw();
@@ -205,7 +203,7 @@ export default class AnimationLoop {
       this._resolveNextFrame = null;
     }
 
-    this._endTimers();
+    this._endFrameTimers();
 
     return this;
   }
@@ -215,7 +213,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 +246,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 +261,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 +271,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;
     }
 
@@ -312,7 +300,7 @@ export default class AnimationLoop {
   }
 
   _cancelAnimationFrame() {
-    if (this._animationFrameId !== null) {
+    if (this._animationFrameId === null) {
       return;
     }
 
@@ -322,7 +310,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 +324,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 +346,20 @@ 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,
       timeline: this.timeline,
 
       // Initial values
       useDevicePixels: this.props.useDevicePixels,
-      needsRedraw: null,
+      needsRedraw: false,
 
       // Placeholders
       width: 1,
@@ -386,8 +378,20 @@ 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;
+    }
+
+    // Can this be replaced with canvas context?
     const {width, height, aspect} = this._getSizeAndAspect();
     if (width !== this.animationProps.width || height !== this.animationProps.height) {
       this.setNeedsRedraw('drawing buffer resized');
@@ -418,13 +422,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 +443,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 +454,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,11 +491,11 @@ 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});
     }
   }
 
-  _beginTimers() {
+  _beginFrameTimers() {
     this.frameRate.timeEnd();
     this.frameRate.timeStart();
 
@@ -505,10 +515,10 @@ export default class AnimationLoop {
     //   this._gpuTimeQuery.beginTimeElapsedQuery();
     // }
 
-    // this.cpuTime.timeStart();
+    this.cpuTime.timeStart();
   }
 
-  _endTimers() {
+  _endFrameTimers() {
     this.cpuTime.timeEnd();
 
     // if (this._gpuTimeQuery) {
@@ -521,15 +531,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,6 +1,6 @@
-import {Device} from '@luma.gl/api';
+import {Device} 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 = {
@@ -22,10 +22,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;
+}