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

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

@@ -1,53 +1,57 @@
-import {luma, Device, DeviceProps} from '@luma.gl/api';
-import {requestAnimationFrame, cancelAnimationFrame} from '@luma.gl/api';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// 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 - TODO move to CanvasContext?
+  autoResizeViewport?: boolean;
+  autoResizeDrawingBuffer?: boolean;
+  useDevicePixels?: number | boolean;
+};
+
+export type MutableAnimationLoopProps = {
   // view parameters
-  debug?: boolean;
   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
+  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 +75,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 +83,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 +123,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 +151,11 @@ 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)
@@ -176,20 +176,38 @@ 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;
     }
   }
 
+  /** 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,49 +223,35 @@ 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');
 
     if (!this._nextFramePromise) {
-      this._nextFramePromise = new Promise((resolve) => {
+      this._nextFramePromise = new Promise(resolve => {
         this._resolveNextFrame = resolve;
       });
     }
     return this._nextFramePromise;
   }
 
+  /** TODO - should use device.deviceContext */
   async toDataURL(): Promise<string> {
     this.setNeedsRedraw('toDataURL');
     await this.waitForRender();
@@ -259,7 +263,7 @@ export class AnimationLoop {
 
   // PRIVATE METHODS
 
-  _initialize() {
+  _initialize(): void {
     this._startEventHandling();
 
     // Initialize the callback data
@@ -273,9 +277,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 +291,7 @@ export class AnimationLoop {
     this.display = display;
   }
 
-  _requestAnimationFrame() {
+  _requestAnimationFrame(): void {
     if (!this._running) {
       return;
     }
@@ -301,8 +305,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 +316,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 +330,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 +400,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 +431,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);
@@ -452,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};
     }
@@ -475,11 +486,19 @@ export class AnimationLoop {
   }
 
   /** Default viewport setup */
-  _resizeViewport() {
+  _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
+      );
     }
   }
 
@@ -487,13 +506,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 +532,10 @@ export class AnimationLoop {
     //   this._gpuTimeQuery.beginTimeElapsedQuery();
     // }
 
-    // this.cpuTime.timeStart();
+    this.cpuTime.timeStart();
   }
 
-  _endTimers() {
+  _endFrameTimers() {
     this.cpuTime.timeEnd();
 
     // if (this._gpuTimeQuery) {
@@ -529,16 +548,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,5 +1,5 @@
-import {Device} from '@luma.gl/api';
-import {Timeline} from '../animation/timeline'
+import {Device} from '@luma.gl/core';
+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

@@ -0,0 +1,53 @@
+// 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 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;
+}