@luma.gl/engine 8.6.0-alpha.5 → 9.0.0-alpha.3

package/src/lib/animation-loop.ts

@@ -1,142 +1,62 @@
-import {luma, Device} from '@luma.gl/api';
-import {
-  lumaStats,
-  // TODO - remove dependency on framebuffer (bundle size impact)
-  log,
-  assert
-} from '@luma.gl/api';
-import type {WebGLDeviceProps} from '@luma.gl/webgl'
-import {WebGLDevice} from '@luma.gl/webgl';
-import {
-  isWebGL,
-  // createGLContext,
-  // instrumentGLContext,
-  // resizeGLContext,
-  resetParameters
-} from '@luma.gl/webgl';
-
-
-import {
-  requestAnimationFrame,
-  cancelAnimationFrame,
-  Query,
-  // TODO - remove dependency on framebuffer (bundle size impact)
-  Framebuffer
-} from '@luma.gl/webgl';
-
-import { Stats, Stat } from '@probe.gl/stats'
+import {luma, Device, DeviceProps} from '@luma.gl/api';
+import {requestAnimationFrame, cancelAnimationFrame} from '@luma.gl/api';
+import {Timeline} from '../animation/timeline';
+import {AnimationProps} from '../lib/animation-props';
+import {Stats, Stat} from '@probe.gl/stats';
 import {isBrowser} from '@probe.gl/env';
 
-import { Timeline } from '../animation/timeline'
-
-
-type DeviceProps = WebGLDeviceProps;
-type ContextProps = WebGLDeviceProps;
-
 const isPage = isBrowser() && typeof document !== 'undefined';
 
 let statIdCounter = 0;
 
+type ContextProps = DeviceProps;
+
 /** AnimationLoop properties */
 export type AnimationLoopProps = {
-  onCreateDevice?: (props: DeviceProps) => Device;
-  onCreateContext?: (props: ContextProps) => WebGLRenderingContext; // TODO: signature from createGLContext
+  onCreateDevice?: (props: DeviceProps) => Promise<Device>;
   onAddHTML?: (div: HTMLDivElement) => string; // innerHTML
-  onInitialize?: (animationProps: AnimationProps) => {} | void;
+  onInitialize?: (animationProps: AnimationProps) => void;
   onRender?: (animationProps: AnimationProps) => void;
   onFinalize?: (animationProps: AnimationProps) => void;
-  onError?: (reason: any) => void;
-
-  stats?: Stats;
+  onError?: (reason: Error) => void;
 
   device?: Device;
-  glOptions?: ContextProps; // createGLContext options
-  debug?: boolean;
+  deviceProps?: DeviceProps;
+  stats?: Stats;
 
   // view parameters
+  debug?: boolean;
   autoResizeViewport?: boolean;
   autoResizeDrawingBuffer?: boolean;
   useDevicePixels?: number | boolean;
-
-  /** @deprecated Use .device */
-  gl?: WebGLRenderingContext
-  /** @deprecated Will be removed */
-  createFramebuffer?: boolean;
 };
 
-export type AnimationProps = {
-  device: Device;
-
-  stop: () => AnimationLoop
-  canvas: HTMLCanvasElement | OffscreenCanvas
-  // Initial values
-  useDevicePixels: number | boolean
-  needsRedraw?: string
-  // Animation props
-  startTime: number
-  engineTime: number
-  tick: number
-  tock: number
-
-  // Timeline time for back compatibility
-  time: number
-
-  width: number
-  height: number
-  aspect: number
-
-  timeline: Timeline
-  animationLoop: AnimationLoop
-
-  // Experimental
-  _mousePosition?: [number, number] // [offsetX, offsetY],
-
-  /** @deprecated Will be removed, create your own Framebuffer */
-  framebuffer: Framebuffer
-  /** @deprecated Use .device */
-  gl: WebGLRenderingContext
-
-  /** @deprecated Use .timeline */
-  _timeline: Timeline
-  /** @deprecated Use .animationLoop */
-  _loop: AnimationLoop
-  /** @deprecated Use .animationLoop */
-  _animationLoop: AnimationLoop
-}
-
 const DEFAULT_ANIMATION_LOOP_PROPS: Required<AnimationLoopProps> = {
-  onCreateDevice: (props: DeviceProps) => luma.createDevice(props),
-  onCreateContext: null,
-  onAddHTML: null,
+  onCreateDevice: (props: DeviceProps): Promise<Device> => luma.createDevice(props),
+  onAddHTML: undefined,
   onInitialize: () => ({}),
   onRender: () => {},
   onFinalize: () => {},
   onError: (error) => console.error(error), // eslint-disable-line no-console
 
-  device: null,
+  device: undefined,
+  deviceProps: {},
   debug: false,
+  stats: luma.stats.get(`animation-loop-${statIdCounter++}`),
 
   // view parameters
   useDevicePixels: true,
   autoResizeViewport: true,
   autoResizeDrawingBuffer: true,
-  stats: lumaStats.get(`animation-loop-${statIdCounter++}`),
-
-  // deprecated
-  // onCreateContext: (opts) => createGLContext(opts),
-  gl: null,
-  glOptions: {},
-  createFramebuffer: false
 };
 
 /** Convenient animation loop */
 export default class AnimationLoop {
   device: Device;
-  canvas: HTMLCanvasElement | OffscreenCanvas;
+  canvas: HTMLCanvasElement; // | OffscreenCanvas;
 
   props: Required<AnimationLoopProps>;
   animationProps: AnimationProps;
-  framebuffer: Framebuffer = null;
   timeline: Timeline = null;
   stats: Stats;
   cpuTime: Stat;
@@ -150,15 +70,11 @@ export default class AnimationLoop {
   _initialized: boolean = false;
   _running: boolean = false;
   _animationFrameId = null;
-  _pageLoadPromise: Promise<{}> | null = null;
   _nextFramePromise: Promise<AnimationLoop> | null = null;
   _resolveNextFrame: ((AnimationLoop) => void) | null = null;
   _cpuStartTime: number = 0;
 
-  _gpuTimeQuery: Query | null = null;
-
-  /** @deprecated */
-  gl: WebGLRenderingContext;
+  // _gpuTimeQuery: Query | null = null;
 
   /*
    * @param {HTMLCanvasElement} canvas - if provided, width and height will be passed to context
@@ -169,12 +85,6 @@ export default class AnimationLoop {
 
     let {useDevicePixels = true} = this.props;
 
-    if ('useDevicePixelRatio' in props) {
-      log.deprecated('useDevicePixelRatio', 'useDevicePixels')();
-      // @ts-expect-error
-      useDevicePixels = props.useDevicePixelRatio;
-    }
-
     // state
     this.device = props.device;
     // @ts-expect-error
@@ -214,6 +124,7 @@ export default class AnimationLoop {
     return this;
   }
 
+  // TODO - move to CanvasContext
   setProps(props: AnimationLoopProps): this {
     if ('autoResizeViewport' in props) {
       this.props.autoResizeViewport = props.autoResizeViewport;
@@ -227,25 +138,14 @@ export default class AnimationLoop {
     return this;
   }
 
-  start(opts = {}) {
-    this._start(opts);
-    return this;
-  }
-
-  /** Starts a render loop if not already running
-   * @param {Object} context - contains frame specific info (E.g. tick, width, height, etc)
-   */
-  async _start(opts) {
+  /** Starts a render loop if not already running */
+  async start() {
     if (this._running) {
       return this;
     }
     this._running = true;
 
-    // console.debug(`Starting ${this.constructor.name}`);
-    // Wait for start promise before rendering frame
     try {
-      await this._getPageLoadPromise();
-
       // check that we haven't been stopped
       if (!this._running) {
         return null;
@@ -254,11 +154,12 @@ export default class AnimationLoop {
       let appContext;
       if (!this._initialized) {
         this._initialized = true;
-        this._initialize(opts);
+        // Create the WebGL context
+        await this._createDevice();
+        this._initialize();
 
-        // Note: onIntialize can return a promise (in case app needs to load resources)
-        appContext = await this.onInitialize(this.animationProps);
-        this._addCallbackData(appContext || {});
+        // Note: onIntialize can return a promise (e.g. in case app needs to load resources)
+        await this.onInitialize(this.animationProps);
       }
 
       // check that we haven't been stopped
@@ -274,16 +175,17 @@ export default class AnimationLoop {
       }
 
       return this;
-    } catch (error) {
+    } catch (err: unknown) {
+      const error = err instanceof Error ? err : new Error('Unknown error')
       this.props.onError(error);
       // this._running = false; // TODO
-      return null;
+      throw error;
     }
   }
 
   /** Explicitly draw a frame */
   redraw(): this {
-    if (this.isContextLost()) {
+    if (this.device.isLost) {
       return this;
     }
 
@@ -312,7 +214,9 @@ export default class AnimationLoop {
   stop() {
     // console.debug(`Stopping ${this.constructor.name}`);
     if (this._running) {
-      this._finalizeCallbackData();
+      // call callback
+      this.onFinalize(this.animationProps);
+
       this._cancelAnimationFrame();
       this._nextFramePromise = null;
       this._resolveNextFrame = null;
@@ -343,17 +247,11 @@ export default class AnimationLoop {
 
   async toDataURL() {
     this.setNeedsRedraw('toDataURL');
-
     await this.waitForRender();
-
-    return this.gl.canvas.toDataURL();
-  }
-
-  isContextLost(): boolean {
-    return this.gl.isContextLost();
+    return this.canvas.toDataURL();
   }
 
-  onCreateDevice(deviceProps: DeviceProps) {
+  onCreateDevice(deviceProps: DeviceProps): Promise<Device> {
     return this.props.onCreateDevice(deviceProps);
   }
 
@@ -369,26 +267,9 @@ export default class AnimationLoop {
     return this.props.onFinalize(animationProps);
   }
 
-  // DEPRECATED/REMOVED METHODS
-
-  /** @deprecated Use .onCreateDevice() */
-  onCreateContext(props: ContextProps) {
-    return this.props.onCreateContext(props);
-  }
-
-  /** @deprecated */
-  getHTMLControlValue(id, defaultValue = 1) {
-    const element = document.getElementById(id);
-    // @ts-expect-error Not all html elements have value
-    return element ? Number(element.value) : defaultValue;
-  }
-
   // PRIVATE METHODS
 
-  _initialize(props: AnimationLoopProps) {
-    // Create the WebGL context
-    this._createDevice(props);
-    this._createFramebuffer();
+  _initialize() {
     this._startEventHandling();
 
     // Initialize the callback data
@@ -399,24 +280,7 @@ export default class AnimationLoop {
     this._resizeCanvasDrawingBuffer();
     this._resizeViewport();
 
-    this._gpuTimeQuery = Query.isSupported(this.gl, ['timers']) ? new Query(this.gl) : null;
-  }
-
-  _getPageLoadPromise() {
-    if (!this._pageLoadPromise) {
-      this._pageLoadPromise = isPage
-        ? new Promise((resolve, reject) => {
-            if (isPage && document.readyState === 'complete') {
-              resolve(document);
-              return;
-            }
-            window.addEventListener('load', () => {
-              resolve(document);
-            });
-          })
-        : Promise.resolve({});
-    }
-    return this._pageLoadPromise;
+    // this._gpuTimeQuery = Query.isSupported(this.gl, ['timers']) ? new Query(this.gl) : null;
   }
 
   _setDisplay(display) {
@@ -458,7 +322,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;
   }
 
@@ -491,43 +355,34 @@ export default class AnimationLoop {
   _setupFrame() {
     this._resizeCanvasDrawingBuffer();
     this._resizeViewport();
-    this._resizeFramebuffer();
   }
 
   // Initialize the  object that will be passed to app callbacks
   _initializeCallbackData() {
-    // @ts-expect-error
     this.animationProps = {
+      animationLoop: this,
       device: this.device,
-      gl: this.gl,
-
-      stop: this.stop,
-      canvas: this.gl.canvas,
+      canvas: this.device.canvasContext.canvas,
+      timeline: this.timeline,
 
       // Initial values
       useDevicePixels: this.props.useDevicePixels,
       needsRedraw: null,
 
+      // Placeholders
+      width: 1,
+      height: 1,
+      aspect: 1,
+
       // Animation props
+      time: 0,
       startTime: Date.now(),
       engineTime: 0,
       tick: 0,
       tock: 0,
 
-      timeline: this.timeline,
-      animationLoop: this,
-
-      // Timeline time for back compatibility
-      time: 0,
-
       // Experimental
-      _mousePosition: null, // Event props
-
-      // Deprecated
-      framebuffer: this.framebuffer,
-      _timeline: this.timeline,
-      _loop: this,
-      _animationLoop: this
+      _mousePosition: null // Event props
     };
   }
 
@@ -563,43 +418,17 @@ export default class AnimationLoop {
       : this.animationProps.engineTime;
   }
 
-  _finalizeCallbackData() {
-    // call callback
-    this.onFinalize(this.animationProps);
-    // end callback
-  }
-
-  /** Add application's data to the app context object */
-  _addCallbackData(appContext) {
-    if (typeof appContext === 'object' && appContext !== null) {
-      this.animationProps = Object.assign({}, this.animationProps, appContext);
-    }
-  }
-
   /** Either uses supplied or existing context, or calls provided callback to create one */
-  _createDevice(props: DeviceProps) {
-    const deviceProps = {...this.props, ...props, ...this.props.glOptions};
-
-    // TODO - support this.onCreateContext
-    // Create the WebGL context if necessary
-    // this.gl = this.props.gl ? instrumentGLContext(this.props.gl, deviceProps) : this.onCreateContext(deviceProps);
-
-    this.device = this.onCreateDevice(deviceProps);
+  async _createDevice() {
+    const deviceProps = {...this.props, ...this.props.deviceProps};
+    this.device = await this.onCreateDevice(deviceProps);
     // @ts-expect-error
-    this.gl = this.device.gl;
-
-    if (!isWebGL(this.gl)) {
-      throw new Error('AnimationLoop.onCreateContext - illegal context returned');
-    }
-
-    // Reset the WebGL context.
-    resetParameters(this.gl);
-
+    this.canvas = this.device.canvasContext.canvas;
     this._createInfoDiv();
   }
 
   _createInfoDiv() {
-    if (this.gl.canvas && this.props.onAddHTML) {
+    if (this.canvas && this.props.onAddHTML) {
       const wrapperDiv = document.createElement('div');
       document.body.appendChild(wrapperDiv);
       wrapperDiv.style.position = 'relative';
@@ -609,7 +438,7 @@ export default class AnimationLoop {
       div.style.bottom = '10px';
       div.style.width = '300px';
       div.style.background = 'white';
-      wrapperDiv.appendChild(this.gl.canvas);
+      wrapperDiv.appendChild(this.canvas);
       wrapperDiv.appendChild(div);
       const html = this.props.onAddHTML(div);
       if (html) {
@@ -620,14 +449,15 @@ export default class AnimationLoop {
 
   _getSizeAndAspect() {
     // https://webglfundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
-    const width = this.gl.drawingBufferWidth;
-    const height = this.gl.drawingBufferHeight;
+    const [width, height] = this.device.canvasContext.getPixelSize();
 
     // https://webglfundamentals.org/webgl/lessons/webgl-anti-patterns.html
     let aspect = 1;
-    const {canvas} = this.gl;
+    const canvas = this.device.canvasContext.canvas;
 
+    // @ts-expect-error
     if (canvas && canvas.clientHeight) {
+      // @ts-expect-error
       aspect = canvas.clientWidth / canvas.clientHeight;
     } else if (width > 0 && height > 0) {
       aspect = width / height;
@@ -638,18 +468,20 @@ export default class AnimationLoop {
 
   /** Default viewport setup */
   _resizeViewport() {
-    if (this.props.autoResizeViewport) {
-      this.gl.viewport(0, 0, this.gl.drawingBufferWidth, this.gl.drawingBufferHeight);
+    // @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);
     }
   }
 
-  /** 
+  /**
    * Resize the render buffer of the canvas to match canvas client size
    * Optionally multiplying with devicePixel ratio
    */
   _resizeCanvasDrawingBuffer() {
     if (this.props.autoResizeDrawingBuffer) {
-      (this.device as WebGLDevice).resize({useDevicePixels: this.props.useDevicePixels});
+      this.device.canvasContext.resize({useDevicePixels: this.props.useDevicePixels});
     }
   }
 
@@ -660,38 +492,37 @@ export default class AnimationLoop {
     // Check if timer for last frame has completed.
     // GPU timer results are never available in the same
     // frame they are captured.
-    if (
-      this._gpuTimeQuery &&
-      this._gpuTimeQuery.isResultAvailable() &&
-      !this._gpuTimeQuery.isTimerDisjoint()
-    ) {
-      this.stats.get('GPU Time').addTime(this._gpuTimeQuery.getTimerMilliseconds());
-    }
+    // if (
+    //   this._gpuTimeQuery &&
+    //   this._gpuTimeQuery.isResultAvailable() &&
+    //   !this._gpuTimeQuery.isTimerDisjoint()
+    // ) {
+    //   this.stats.get('GPU Time').addTime(this._gpuTimeQuery.getTimerMilliseconds());
+    // }
 
-    if (this._gpuTimeQuery) {
-      // GPU time query start
-      this._gpuTimeQuery.beginTimeElapsedQuery();
-    }
+    // if (this._gpuTimeQuery) {
+    //   // GPU time query start
+    //   this._gpuTimeQuery.beginTimeElapsedQuery();
+    // }
 
-    this.cpuTime.timeStart();
+    // this.cpuTime.timeStart();
   }
 
   _endTimers() {
     this.cpuTime.timeEnd();
 
-    if (this._gpuTimeQuery) {
-      // GPU time query end. Results will be available on next frame.
-      this._gpuTimeQuery.end();
-    }
+    // if (this._gpuTimeQuery) {
+    //   // GPU time query end. Results will be available on next frame.
+    //   this._gpuTimeQuery.end();
+    // }
   }
 
   // Event handling
 
   _startEventHandling() {
-    const {canvas} = this.gl;
-    if (canvas) {
-      canvas.addEventListener('mousemove', this._onMousemove);
-      canvas.addEventListener('mouseleave', this._onMouseleave);
+    if (this.canvas) {
+      this.canvas.addEventListener('mousemove', this._onMousemove);
+      this.canvas.addEventListener('mouseleave', this._onMouseleave);
     }
   }
 
@@ -701,24 +532,4 @@ export default class AnimationLoop {
   _onMouseleave(e) {
     this.animationProps._mousePosition = null;
   }
-
-  // Deprecated
-
-  /** @deprecated */
-  _createFramebuffer() {
-    // Setup default framebuffer
-    if (this.props.createFramebuffer) {
-      this.framebuffer = new Framebuffer(this.gl);
-    }
-  }
-
-  /** @deprecated */
-  _resizeFramebuffer() {
-    if (this.framebuffer) {
-      this.framebuffer.resize({
-        width: this.gl.drawingBufferWidth,
-        height: this.gl.drawingBufferHeight
-      });
-    }
-  }  
 }

package/src/lib/animation-props.ts

@@ -0,0 +1,31 @@
+import {Device} from '@luma.gl/api';
+import {Timeline} from '../animation/timeline'
+import type AnimationLoop from './animation-loop';
+
+/** Properties passed to every render frame  */
+export type AnimationProps = {
+  device: Device;
+  animationLoop: AnimationLoop;
+
+  /** @todo Should be canvasContext */
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  useDevicePixels: number | boolean;
+  width: number;
+  height: number;
+  aspect: number;
+
+  // Animation props
+  time: number;
+  startTime: number;
+  engineTime: number;
+  tick: number;
+  tock: number;
+
+  // Initial values
+  needsRedraw?: string;
+
+  timeline: Timeline;
+
+  // Experimental
+  _mousePosition?: [number, number]; // [offsetX, offsetY],
+};

package/src/{utils → lib}/clip-space.ts

@@ -1,6 +1,8 @@
+
 // ClipSpace
+/*
 import GL from '@luma.gl/constants';
-import Model, {ModelProps} from '../lib/model';
+import Model, {ModelProps} from './model';
 import Geometry from '../geometry/geometry';
 
 const CLIPSPACE_VERTEX_SHADER = `\
@@ -20,7 +22,7 @@ void main(void) {
 }
 `;
 
-/* eslint-disable indent, no-multi-spaces */
+/* eslint-disable indent, no-multi-spaces *
 const POSITIONS = [-1, -1, 1, -1, -1, 1, 1, 1];
 
 
@@ -46,3 +48,4 @@ export default class ClipSpace extends Model {
     this.setVertexCount(4);
   }
 }
+*/