@luma.gl/engine 8.6.0-alpha.1 → 8.6.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luma.gl/engine",
-  "version": "8.6.0-alpha.1",
+  "version": "8.6.0-alpha.2",
   "description": "WebGL2 Components for High Performance Rendering and Computation",
   "license": "MIT",
   "publishConfig": {
@@ -31,12 +31,12 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.0.0",
-    "@luma.gl/constants": "8.6.0-alpha.1",
-    "@luma.gl/gltools": "8.6.0-alpha.1",
-    "@luma.gl/shadertools": "8.6.0-alpha.1",
-    "@luma.gl/webgl": "8.6.0-alpha.1",
+    "@luma.gl/constants": "8.6.0-alpha.2",
+    "@luma.gl/shadertools": "8.6.0-alpha.2",
+    "@luma.gl/webgl": "8.6.0-alpha.2",
     "@math.gl/core": "^3.5.0",
-    "probe.gl": "^3.4.0"
+    "@probe.gl/log": "3.5.0-alpha.5",
+    "@probe.gl/stats": "3.5.0-alpha.5"
   },
-  "gitHead": "e3895ce8a6dd376394c6662bb8cf0e1ad1f233f3"
+  "gitHead": "bdcebda76c1b4e47b127cdbd3f426ea6cbae44f1"
 }

package/src/index.ts

@@ -1,5 +1,9 @@
 // CORE
+export type {AnimationLoopProps, AnimationProps} from './lib/animation-loop';
 export {default as AnimationLoop} from './lib/animation-loop';
+export {RenderLoop} from './lib/render-loop';
+
+export type {ModelProps} from './lib/model';
 export {default as Model} from './lib/model';
 export {default as ProgramManager} from './lib/program-manager';
 export {default as Transform} from './transform/transform';
@@ -8,19 +12,20 @@ export {default as Transform} from './transform/transform';
 export {default as Geometry} from './geometry/geometry';
 
 // Primitives
-export {ConeGeometry, ConeGeometryProps} from './geometries/cone-geometry';
-export {CubeGeometry, CubeGeometryProps} from './geometries/cube-geometry';
-export {CylinderGeometry, CylinderGeometryProps} from './geometries/cylinder-geometry';
-export {
-  IcoSphereGeometry,
-  IcoSphereGeometryProps
-} from './geometries/ico-sphere-geometry';
-export {PlaneGeometry, PlaneGeometryProps} from './geometries/plane-geometry';
-export {SphereGeometry, SphereGeometryProps} from './geometries/sphere-geometry';
-export {
-  TruncatedConeGeometry,
-  TruncatedConeGeometryProps
-} from './geometries/truncated-cone-geometry';
+export type {ConeGeometryProps} from './geometries/cone-geometry';
+export {ConeGeometry} from './geometries/cone-geometry';
+export type {CubeGeometryProps} from './geometries/cube-geometry';
+export {CubeGeometry} from './geometries/cube-geometry';
+export type {CylinderGeometryProps} from './geometries/cylinder-geometry';
+export {CylinderGeometry} from './geometries/cylinder-geometry';
+export type {IcoSphereGeometryProps} from './geometries/ico-sphere-geometry';
+export {IcoSphereGeometry} from './geometries/ico-sphere-geometry';
+export type {PlaneGeometryProps} from './geometries/plane-geometry';
+export {PlaneGeometry} from './geometries/plane-geometry';
+export type {SphereGeometryProps} from './geometries/sphere-geometry';
+export {SphereGeometry} from './geometries/sphere-geometry';
+export type {TruncatedConeGeometryProps} from './geometries/truncated-cone-geometry';
+export {TruncatedConeGeometry} from './geometries/truncated-cone-geometry';
 
 // Animation
 export {Timeline} from './animation/timeline';

package/src/lib/animation-loop.ts

@@ -1,29 +1,37 @@
+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,
+  // createGLContext,
+  // instrumentGLContext,
+  // resizeGLContext,
   resetParameters
-} from '@luma.gl/gltools';
+} from '@luma.gl/webgl';
+
 
 import {
   requestAnimationFrame,
   cancelAnimationFrame,
   Query,
-  lumaStats,
   // TODO - remove dependency on framebuffer (bundle size impact)
-  Framebuffer,
-  log,
-  assert
+  Framebuffer
 } from '@luma.gl/webgl';
 
-import { Stats } from 'probe.gl'
-import { Timeline } from '../animation/timeline'
+import { Stats, Stat } from '@probe.gl/stats'
+import {isBrowser} from '@probe.gl/env';
 
-import type {GLContextOptions} from '@luma.gl/gltools'
+import { Timeline } from '../animation/timeline'
 
-import {isBrowser} from 'probe.gl/env';
 
+type DeviceProps = WebGLDeviceProps;
+type ContextProps = WebGLDeviceProps;
 
 const isPage = isBrowser() && typeof document !== 'undefined';
 
@@ -31,17 +39,18 @@ let statIdCounter = 0;
 
 /** AnimationLoop properties */
 export type AnimationLoopProps = {
-  onCreateContext?: (opts: GLContextOptions) => WebGLRenderingContext; // TODO: signature from createGLContext
+  onCreateDevice?: (props: DeviceProps) => Device;
+  onCreateContext?: (props: ContextProps) => WebGLRenderingContext; // TODO: signature from createGLContext
   onAddHTML?: (div: HTMLDivElement) => string; // innerHTML
-  onInitialize?: ((animationProps: AnimationProps) => {}) | ((animationProps: AnimationProps) => {});
+  onInitialize?: (animationProps: AnimationProps) => {} | void;
   onRender?: (animationProps: AnimationProps) => void;
   onFinalize?: (animationProps: AnimationProps) => void;
   onError?: (reason: any) => void;
 
   stats?: Stats;
 
-  gl?: WebGLRenderingContext
-  glOptions?: GLContextOptions // createGLContext options
+  device?: Device;
+  glOptions?: ContextProps; // createGLContext options
   debug?: boolean;
 
   // view parameters
@@ -49,16 +58,17 @@ export type AnimationLoopProps = {
   autoResizeDrawingBuffer?: boolean;
   useDevicePixels?: number | boolean;
 
-  /** @deprecated */
+  /** @deprecated Use .device */
+  gl?: WebGLRenderingContext
+  /** @deprecated Will be removed */
   createFramebuffer?: boolean;
 };
 
 export type AnimationProps = {
-  gl: WebGLRenderingContext
+  device: Device;
 
   stop: () => AnimationLoop
   canvas: HTMLCanvasElement | OffscreenCanvas
-  framebuffer: Framebuffer
   // Initial values
   useDevicePixels: number | boolean
   needsRedraw?: string
@@ -75,63 +85,63 @@ export type AnimationProps = {
   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
-  _mousePosition?: [number, number] // [offsetX, offsetY]
-  _offScreen: boolean
-}
-
-/* instance of parameters after construction
-type AnimationLoopPropsInternal = {
-  onCreateContext: (opts: GLContextOptions) => WebGLRenderingContext // TODO: signature from createGLContext
-  onAddHTML?: (div: HTMLDivElement) => string // innerHTML
-  onInitialize: (animationProps: AnimationProps) => AnimationProps | Promise<AnimationProps>
-  onRender: (animationProps: AnimationProps) => void
-  onFinalize: (animationProps: AnimationProps) => void
-  onError: (reason: any) => PromiseLike<never>
-  gl?: WebGLRenderingContext
-  glOptions: GLContextOptions // createGLContext options
-  debug: boolean
-  createFramebuffer: boolean
 }
-*/
 
 const DEFAULT_ANIMATION_LOOP_PROPS: Required<AnimationLoopProps> = {
-  onCreateContext: (opts) => createGLContext(opts),
+  onCreateDevice: (props: DeviceProps) => luma.createDevice(props),
+  onCreateContext: null,
   onAddHTML: null,
   onInitialize: () => ({}),
   onRender: () => {},
   onFinalize: () => {},
-  // eslint-disable-next-line no-console
-  onError: (error) => console.error(error),
+  onError: (error) => console.error(error), // eslint-disable-line no-console
 
-  gl: null,
-  glOptions: {},
+  device: null,
   debug: false,
 
-  createFramebuffer: false,
-
   // view parameters
   useDevicePixels: true,
   autoResizeViewport: true,
   autoResizeDrawingBuffer: true,
-  stats: lumaStats.get(`animation-loop-${statIdCounter++}`)
+  stats: lumaStats.get(`animation-loop-${statIdCounter++}`),
+
+  // deprecated
+  // onCreateContext: (opts) => createGLContext(opts),
+  gl: null,
+  glOptions: {},
+  createFramebuffer: false
 };
 
+/** Convenient animation loop */
 export default class AnimationLoop {
-  animationProps: AnimationProps;
-  props: Required<AnimationLoopProps>;
-  gl: WebGLRenderingContext;
+  device: Device;
   canvas: HTMLCanvasElement | OffscreenCanvas;
+
+  props: Required<AnimationLoopProps>;
+  animationProps: AnimationProps;
   framebuffer: Framebuffer = null;
   timeline: Timeline = null;
   stats: Stats;
-  cpuTime: Stats;
-  gpuTime: Stats;
-  frameRate: Stats;
-  offScreen: boolean;
+  cpuTime: Stat;
+  gpuTime: Stat;
+  frameRate: Stat;
 
   display: any;
 
@@ -147,6 +157,9 @@ export default class AnimationLoop {
 
   _gpuTimeQuery: Query | null = null;
 
+  /** @deprecated */
+  gl: WebGLRenderingContext;
+
   /*
    * @param {HTMLCanvasElement} canvas - if provided, width and height will be passed to context
    */
@@ -158,12 +171,15 @@ export default class AnimationLoop {
 
     if ('useDevicePixelRatio' in props) {
       log.deprecated('useDevicePixelRatio', 'useDevicePixels')();
-      // @ts-ignore
+      // @ts-expect-error
       useDevicePixels = props.useDevicePixelRatio;
     }
 
     // state
-    this.gl = props.gl;
+    this.device = props.device;
+    // @ts-expect-error
+    this.gl = (this.device && this.device.gl) || props.gl;
+
     this.stats = props.stats;
     this.cpuTime = this.stats.get('CPU Time');
     this.gpuTime = this.stats.get('GPU Time');
@@ -179,16 +195,20 @@ export default class AnimationLoop {
     this.start = this.start.bind(this);
     this.stop = this.stop.bind(this);
 
-
     this._onMousemove = this._onMousemove.bind(this);
     this._onMouseleave = this._onMouseleave.bind(this);
   }
 
-  delete(): void {
+  destroy(): void {
     this.stop();
     this._setDisplay(null);
   }
 
+  /** @deprecated Use .destroy() */
+  delete(): void {
+    this.destroy();
+  }
+
   setNeedsRedraw(reason: string): this {
     this.needsRedraw = this.needsRedraw || reason;
     return this;
@@ -277,15 +297,6 @@ export default class AnimationLoop {
     // clear needsRedraw flag
     this._clearNeedsRedraw();
 
-    // Offscreen Canvas Support: Commit the frame
-    // https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/commit
-    // Chrome's offscreen canvas does not require gl.commit
-    // @ts-expect-error gl.commit is not officially part of WebGLRenderingContext
-    if (this.offScreen && this.gl.commit) {
-      // @ts-expect-error gl.commit is not officially part of WebGLRenderingContext
-      this.gl.commit();
-    }
-
     if (this._resolveNextFrame) {
       this._resolveNextFrame(this);
       this._nextFramePromise = null;
@@ -338,49 +349,45 @@ export default class AnimationLoop {
     return this.gl.canvas.toDataURL();
   }
 
-  isContextLost() {
+  isContextLost(): boolean {
     return this.gl.isContextLost();
   }
 
-  onCreateContext(...args) {
-    // @ts-expect-error
-    return this.props.onCreateContext(...args);
+  onCreateDevice(deviceProps: DeviceProps) {
+    return this.props.onCreateDevice(deviceProps);
   }
 
-  onInitialize(...args) {
-    // @ts-expect-error
-    return this.props.onInitialize(...args);
+  onInitialize(animationProps: AnimationProps): {} | void {
+    return this.props.onInitialize(animationProps);
   }
 
-  onRender(...args) {
-    // @ts-expect-error
-    return this.props.onRender(...args);
+  onRender(animationProps: AnimationProps) {
+    return this.props.onRender(animationProps);
   }
 
-  onFinalize(...args) {
-    // @ts-expect-error
-    return this.props.onFinalize(...args);
+  onFinalize(animationProps: AnimationProps) {
+    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-ignore Not all html elements have value
+    // @ts-expect-error Not all html elements have value
     return element ? Number(element.value) : defaultValue;
   }
 
-  // Update parameters
-  setViewParameters() {
-    log.removed('AnimationLoop.setViewParameters', 'AnimationLoop.setProps')();
-    return this;
-  }
-
   // PRIVATE METHODS
 
-  _initialize(opts) {
+  _initialize(props: AnimationLoopProps) {
     // Create the WebGL context
-    this._createWebGLContext(opts);
+    this._createDevice(props);
     this._createFramebuffer();
     this._startEventHandling();
 
@@ -465,15 +472,15 @@ export default class AnimationLoop {
 
   // Called on each frame, can be overridden to call onRender multiple times
   // to support e.g. stereoscopic rendering
-  _renderFrame(...args) {
+  _renderFrame(props: AnimationProps) {
     // Allow e.g. VR display to render multiple frames.
     if (this.display) {
-      this.display._renderFrame(...args);
+      this.display._renderFrame(props);
       return;
     }
 
     // call callback
-    this.onRender(...args);
+    this.onRender(props);
     // end callback
   }
 
@@ -491,11 +498,11 @@ export default class AnimationLoop {
   _initializeCallbackData() {
     // @ts-expect-error
     this.animationProps = {
+      device: this.device,
       gl: this.gl,
 
       stop: this.stop,
       canvas: this.gl.canvas,
-      framebuffer: this.framebuffer,
 
       // Initial values
       useDevicePixels: this.props.useDevicePixels,
@@ -507,14 +514,20 @@ export default class AnimationLoop {
       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
+      _animationLoop: this
     };
   }
 
@@ -548,9 +561,6 @@ export default class AnimationLoop {
     this.animationProps.time = this.timeline
       ? this.timeline.getTime()
       : this.animationProps.engineTime;
-
-    // experimental
-    this.animationProps._offScreen = this.offScreen;
   }
 
   _finalizeCallbackData() {
@@ -559,23 +569,24 @@ export default class AnimationLoop {
     // end callback
   }
 
-  // Add application's data to the app context object
+  /** 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
-  _createWebGLContext(opts) {
-    this.offScreen =
-      opts.canvas &&
-      typeof OffscreenCanvas !== 'undefined' &&
-      opts.canvas instanceof OffscreenCanvas;
+  /** 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
-    opts = Object.assign({}, opts, this.props.glOptions);
-    this.gl = this.props.gl ? instrumentGLContext(this.props.gl, opts) : this.onCreateContext(opts);
+    // this.gl = this.props.gl ? instrumentGLContext(this.props.gl, deviceProps) : this.onCreateContext(deviceProps);
+
+    this.device = this.onCreateDevice(deviceProps);
+    // @ts-expect-error
+    this.gl = this.device.gl;
 
     if (!isWebGL(this.gl)) {
       throw new Error('AnimationLoop.onCreateContext - illegal context returned');
@@ -625,35 +636,20 @@ export default class AnimationLoop {
     return {width, height, aspect};
   }
 
-  // Default viewport setup
+  /** Default viewport setup */
   _resizeViewport() {
     if (this.props.autoResizeViewport) {
       this.gl.viewport(0, 0, this.gl.drawingBufferWidth, this.gl.drawingBufferHeight);
     }
   }
 
-  // Resize the render buffer of the canvas to match canvas client size
-  // Optionally multiplying with devicePixel ratio
+  /** 
+   * Resize the render buffer of the canvas to match canvas client size
+   * Optionally multiplying with devicePixel ratio
+   */
   _resizeCanvasDrawingBuffer() {
     if (this.props.autoResizeDrawingBuffer) {
-      resizeGLContext(this.gl, {useDevicePixels: this.props.useDevicePixels});
-    }
-  }
-
-  // TBD - deprecated?
-  _createFramebuffer() {
-    // Setup default framebuffer
-    if (this.props.createFramebuffer) {
-      this.framebuffer = new Framebuffer(this.gl);
-    }
-  }
-
-  _resizeFramebuffer() {
-    if (this.framebuffer) {
-      this.framebuffer.resize({
-        width: this.gl.drawingBufferWidth,
-        height: this.gl.drawingBufferHeight
-      });
+      (this.device as WebGLDevice).resize({useDevicePixels: this.props.useDevicePixels});
     }
   }
 
@@ -705,4 +701,24 @@ 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/model.ts

@@ -1,9 +1,9 @@
 // luma.gl, MIT license
+import {Device} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import {isWebGL} from '@luma.gl/gltools';
-import {ProgramProps} from '@luma.gl/webgl';
+import type {ProgramProps} from '@luma.gl/webgl';
 import {
-  Shader,
+  WebGLDevice,
   Program,
   VertexArray,
   clear,
@@ -31,9 +31,22 @@ const NOOP = () => {};
 const DRAW_PARAMS = {};
 
 export type ModelProps = ProgramProps & {
-  id?: string
+  id?: string;
+
+  // program props
+  // vs,
+  // fs,
+  // varyings,
+  // bufferMode,
+
+  program?: Program;
+  modules?: any[];
+  defines?: Record<string, number | boolean>;
+  inject?: Record<string, any>;
+  transpileToGLSL100?: boolean;
+
   moduleSettings?: object; // UniformsOptions
-  attributes?: object,
+  attributes?: object;
   uniforms?: object; // Uniforms
   geometry?: object; // Geometry
   vertexCount?: number
@@ -50,8 +63,12 @@ export type ModelProps = ProgramProps & {
   indexType?;
   indexOffset?: number;
   vertexArrayInstanced?: boolean;
+
+  /** @deprecated Use isInstanced */
+  instanced?: boolean
 };
 
+
 export type ModelDrawOptions = {
   moduleSettings?;
   framebuffer?;
@@ -102,8 +119,10 @@ interface TransformOpts extends DrawOpts {
 */
 
 export default class Model {
-  readonly id: string;
+  readonly device: Device;
   readonly gl: WebGLRenderingContext;
+
+  readonly id: string;
   readonly animated: boolean = false;
   programManager: ProgramManager;
   vertexCount: number;
@@ -136,20 +155,24 @@ export default class Model {
   // TODO - just to unbreak deck.gl 7.0-beta, remove as soon as updated
   geometry = {};
 
-  constructor(gl, props: ModelProps = {}) {
+  constructor(device: Device, props?: ModelProps);
+  /* @deprecated */
+  constructor(gl: WebGLRenderingContext, props?: ModelProps);
+  constructor(device, props: ModelProps = {}) {
     // Deduce a helpful id
     const {id = uid('model')} = props;
-    assert(isWebGL(gl));
     this.id = id;
-    this.gl = gl;
+    const webglDevice = WebGLDevice.attach(device);
+    this.device = webglDevice;
+    this.gl = webglDevice.gl;
     this.id = props.id || uid('Model');
     this.initialize(props);
   }
 
-  initialize(props) {
+  initialize(props: ModelProps) {
     this.props = {};
 
-    this.programManager = props.programManager || ProgramManager.getDefaultProgramManager(this.gl);
+    this.programManager = props.programManager || ProgramManager.getDefaultProgramManager(this.device);
     this._programManagerState = -1;
     this._managedProgram = false;
 
@@ -226,7 +249,7 @@ export default class Model {
     this._setModelProps(props);
   }
 
-  delete() {
+  destroy(): void {
     // delete all attributes created by this model
     // TODO - should buffer deletes be handled by vertex array?
     for (const key in this._attributes) {
@@ -245,6 +268,11 @@ export default class Model {
     this._deleteGeometryBuffers();
   }
 
+  /** @deprecated Use .destroy() */
+  delete(): void {
+    this.destroy();
+  }
+
   // GETTERS
 
   getDrawMode() {
@@ -542,7 +570,6 @@ export default class Model {
     this.program = program;
 
     if (this.vertexArray) {
-      // @ts-ignore TODO
       this.vertexArray.setProps({program: this.program, attributes: this.vertexArray.attributes});
     } else {
       this.vertexArray = new VertexArray(this.gl, {program: this.program});
@@ -618,7 +645,7 @@ export default class Model {
     const attributeTable = getDebugTableForVertexArray({
       vertexArray,
       header: `${this.id} attributes`,
-      // @ts-ignore
+      // @ts-expect-error
       attributes: this._attributes
     });
 
@@ -661,6 +688,6 @@ export default class Model {
       framebuffer.log({logLevel: LOG_DRAW_PRIORITY, message: `Rendered to ${framebuffer.id}`});
     }
 
-    log.groupEnd(LOG_DRAW_PRIORITY, `>>> DRAWING MODEL ${this.id}`)();
+    log.groupEnd(LOG_DRAW_PRIORITY)();
   }
 }