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

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@luma.gl/engine",
-  "version": "9.0.0-alpha.9",
+  "version": "9.0.0-beta.2",
   "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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "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.9",
-    "@luma.gl/shadertools": "9.0.0-alpha.9",
-    "@luma.gl/webgl": "9.0.0-alpha.9",
-    "@math.gl/core": "^3.5.0",
-    "@probe.gl/log": "^3.5.0",
-    "@probe.gl/stats": "^3.5.0"
+    "@luma.gl/constants": "9.0.0-beta.2",
+    "@luma.gl/core": "9.0.0-beta.2",
+    "@luma.gl/shadertools": "9.0.0-beta.2",
+    "@math.gl/core": "^4.0.0",
+    "@probe.gl/log": "^4.0.2",
+    "@probe.gl/stats": "^4.0.2"
   },
-  "gitHead": "b84aae16edcdee2be84d2861c81cc6584e336b28"
+  "gitHead": "d90ddd6231c3d405d88dfb9e8c232c4dfefcc056"
 }

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
@@ -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/animation-loop/animation-loop-template.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/{lib → animation-loop}/animation-loop.ts

@@ -1,53 +1,54 @@
-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 | null;
-  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),
+  device: null!,
+
   onAddHTML: () => '',
-  onInitialize: () => ({}),
+  onInitialize: async () => { return null; },
   onRender: () => {},
   onFinalize: () => {},
   onError: (error) => console.error(error), // eslint-disable-line no-console
 
-  device: null,
-  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 */
@@ -71,7 +72,7 @@ export class AnimationLoop {
   _running: boolean = false;
   _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,17 +80,17 @@ export 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 || null;
-    // @ts-expect-error
-    this.gl = (this.device && this.device.gl) || props.gl;
+    const {useDevicePixels = true} = this.props;
 
+    // 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');
@@ -119,13 +120,14 @@ export class AnimationLoop {
     this.destroy();
   }
 
+  /** Flags this animation loop as needing redraw */
   setNeedsRedraw(reason: string): this {
     this.needsRedraw = this.needsRedraw || reason;
     return this;
   }
 
-  // TODO - move to CanvasContext
-  setProps(props: AnimationLoopProps): this {
+  /** TODO - move these props to CanvasContext? */
+  setProps(props: MutableAnimationLoopProps): this {
     if ('autoResizeViewport' in props) {
       this.props.autoResizeViewport = props.autoResizeViewport || false;
     }
@@ -146,16 +148,12 @@ export 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)
@@ -183,13 +181,31 @@ export class AnimationLoop {
     }
   }
 
+  /** Stops a render loop if already running, finalizing */
+  stop() {
+    // console.debug(`Stopping ${this.constructor.name}`);
+    if (this._running) {
+      // call callback
+      // 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;
+      this._resolveNextFrame = null;
+      this._running = false;
+    }
+    return this;
+  }
+
   /** Explicitly draw a frame */
   redraw(): this {
     if (this.device?.isLost) {
       return this;
     }
 
-    this._beginTimers();
+    this._beginFrameTimers();
 
     this._setupFrame();
     this._updateAnimationProps();
@@ -205,38 +221,23 @@ export class AnimationLoop {
       this._resolveNextFrame = null;
     }
 
-    this._endTimers();
+    this._endFrameTimers();
 
     return this;
   }
 
-  // Stops a render loop if already running, finalizing
-  stop() {
-    // console.debug(`Stopping ${this.constructor.name}`);
-    if (this._running) {
-      // call callback
-      // 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;
-      this._resolveNextFrame = null;
-      this._running = false;
-    }
-    return this;
-  }
-
+  /** Add a timeline, it will be automatically updated by the animation loop. */
   attachTimeline(timeline: Timeline): Timeline {
     this.timeline = timeline;
     return this.timeline;
   }
 
+  /** Remove a timeline */
   detachTimeline(): void {
     this.timeline = null;
   }
 
+  /** Wait until a render completes */
   waitForRender(): Promise<AnimationLoop> {
     this.setNeedsRedraw('waitForRender');
 
@@ -248,6 +249,7 @@ export class AnimationLoop {
     return this._nextFramePromise;
   }
 
+  /** TODO - should use device.deviceContext */
   async toDataURL(): Promise<string> {
     this.setNeedsRedraw('toDataURL');
     await this.waitForRender();
@@ -259,7 +261,7 @@ export class AnimationLoop {
 
   // PRIVATE METHODS
 
-  _initialize() {
+  _initialize(): void {
     this._startEventHandling();
 
     // Initialize the callback data
@@ -273,9 +275,9 @@ export class AnimationLoop {
     // this._gpuTimeQuery = Query.isSupported(this.gl, ['timers']) ? new Query(this.gl) : null;
   }
 
-  _setDisplay(display) {
+  _setDisplay(display: any): void {
     if (this.display) {
-      this.display.delete();
+      this.display.destroy();
       this.display.animationLoop = null;
     }
 
@@ -287,7 +289,7 @@ export class AnimationLoop {
     this.display = display;
   }
 
-  _requestAnimationFrame() {
+  _requestAnimationFrame(): void {
     if (!this._running) {
       return;
     }
@@ -301,8 +303,8 @@ export class AnimationLoop {
     this._animationFrameId = requestAnimationFrame(this._animationFrame.bind(this));
   }
 
-  _cancelAnimationFrame() {
-    if (this._animationFrameId !== null) {
+  _cancelAnimationFrame(): void {
+    if (this._animationFrameId === null) {
       return;
     }
 
@@ -312,11 +314,11 @@ export class AnimationLoop {
     // if (this.display && this.display.cancelAnimationFrame) {
     //   this.display.cancelAnimationFrame(this._animationFrameId);
     // }
-  cancelAnimationFrame(this._animationFrameId);
+    cancelAnimationFrame(this._animationFrameId);
     this._animationFrameId = null;
   }
 
-  _animationFrame() {
+  _animationFrame(): void {
     if (!this._running) {
       return;
     }
@@ -326,36 +328,40 @@ export 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): void {
     // Allow e.g. VR display to render multiple frames.
     if (this.display) {
-      this.display._renderFrame(props);
+      this.display._renderFrame(animationProps);
       return;
     }
 
     // call callback
-    this.props.onRender(props);
+    this.props.onRender(this._getAnimationProps());
     // end callback
+
+    // Submit commands (necessary on WebGPU)
+    this.device.submit();
   }
 
-  _clearNeedsRedraw() {
+  _clearNeedsRedraw(): void {
     this.needsRedraw = false;
   }
 
-  _setupFrame() {
+  _setupFrame(): void {
     this._resizeCanvasDrawingBuffer();
     this._resizeViewport();
   }
 
   // Initialize the  object that will be passed to app callbacks
-  _initializeAnimationProps() {
+  _initializeAnimationProps(): void {
     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
@@ -392,6 +398,7 @@ export class AnimationLoop {
       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');
@@ -422,15 +429,17 @@ export 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.props.onCreateDevice(deviceProps);
-    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() {
+  _createInfoDiv(): void {
     if (this.canvas && this.props.onAddHTML) {
       const wrapperDiv = document.createElement('div');
       document.body.appendChild(wrapperDiv);
@@ -475,7 +484,7 @@ export class AnimationLoop {
   }
 
   /** Default viewport setup */
-  _resizeViewport() {
+  _resizeViewport(): void {
     // @ts-expect-error Expose on canvasContext
     if (this.props.autoResizeViewport && this.device.gl) {
       // @ts-expect-error Expose canvasContext
@@ -487,13 +496,13 @@ export class AnimationLoop {
    * Resize the render buffer of the canvas to match canvas client size
    * Optionally multiplying with devicePixel ratio
    */
-  _resizeCanvasDrawingBuffer() {
+  _resizeCanvasDrawingBuffer(): void {
     if (this.props.autoResizeDrawingBuffer) {
       this.device?.canvasContext?.resize({useDevicePixels: this.props.useDevicePixels});
     }
   }
 
-  _beginTimers() {
+  _beginFrameTimers() {
     this.frameRate.timeEnd();
     this.frameRate.timeStart();
 
@@ -513,10 +522,10 @@ export class AnimationLoop {
     //   this._gpuTimeQuery.beginTimeElapsedQuery();
     // }
 
-    // this.cpuTime.timeStart();
+    this.cpuTime.timeStart();
   }
 
-  _endTimers() {
+  _endFrameTimers() {
     this.cpuTime.timeEnd();
 
     // if (this._gpuTimeQuery) {
@@ -529,16 +538,18 @@ export 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._getAnimationProps()._mousePosition = [e.offsetX, e.offsetY];
+  _onMousemove(event: Event) {
+    if (event instanceof MouseEvent) {
+      this._getAnimationProps()._mousePosition = [event.offsetX, event.offsetY];
+    }
   }
 
-  _onMouseleave(e) {
+  _onMouseleave(event: Event) {
     this._getAnimationProps()._mousePosition = null;
   }
 }

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

@@ -1,4 +1,4 @@
-import {Device} from '@luma.gl/api';
+import {Device} from '@luma.gl/core';
 import {Timeline} from '../animation/timeline'
 import type {AnimationLoop} from './animation-loop';
 

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 './animation-loop-template'
+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;
+}