@luma.gl/webgl 8.5.9 → 8.6.0-alpha.3

package/src/classes/{resource.js → webgl-resource.ts}

@@ -1,29 +1,43 @@
-import {isWebGL2, assertWebGLContext} from '@luma.gl/gltools';
-import {lumaStats} from '../init';
+// luma.gl, MIT license
+import {Resource, assert, uid, stubRemovedMethods} from '@luma.gl/api';
+import type {Device} from '@luma.gl/api';
+export type {ResourceProps} from '@luma.gl/api';
+import {isWebGL2, assertWebGLContext} from '../context/context/webgl-checks';
 import {getKey, getKeyValue} from '../webgl-utils/constants-to-keys';
-import {assert} from '../utils/assert';
-import {uid} from '../utils/utils';
-import {stubRemovedMethods} from '../utils/stub-methods';
+import WebGLDevice from '../adapter/webgl-device';
 
 const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual methods';
 
-// TODO - Handle context loss
-// function glGetContextLossCount(gl) {
-//   return (gl.luma && gl.luma.glCount) || 0;
-// }
+/**
+ * Base class for WebGL object wrappers
+ */
+ export default class WebGLResource<Props> extends Resource<Props> {
+  id: string;
+  userData: any;
+  readonly device: WebGLDevice;
+  readonly gl: WebGLRenderingContext;
+  readonly gl2: WebGL2RenderingContext;
+  private _handle: any;
+
+  private _bound = false;
+  // Only meaningful for resources that allocate GPU memory
+  byteLength = 0;
+
+  constructor(device: Device, props: Props, defaultProps: Required<Props>) {
+    super(device, props, defaultProps);
+
+    this.device = WebGLDevice.attach(device);
+    const gl = this.device.gl;
 
-export default class Resource {
-  constructor(gl, opts = {}) {
     assertWebGLContext(gl);
 
-    const {id, userData = {}} = opts;
+    // extends 
+    // @ts-expect-error
+    const {id, userData = {}} = props || {};
     this.gl = gl;
-    // @ts-ignore
-    this.gl2 = gl;
-    // this.ext = polyfillContext(gl);
+    this.gl2 = gl as WebGL2RenderingContext;
     this.id = id || uid(this.constructor.name);
     this.userData = userData;
-    this._bound = false;
 
     // Set the handle
     // If handle was provided, use it, otherwise create a new handle
@@ -32,18 +46,16 @@ export default class Resource {
     // this.glCount = glGetContextLossCount(this.gl);
 
     // Default VertexArray needs to be created with null handle, so compare against undefined
-    this._handle = opts.handle;
+    // @ts-expect-error
+    this._handle = props?.handle;
     if (this._handle === undefined) {
       this._handle = this._createHandle();
     }
 
-    // Only meaningful for resources that allocate GPU memory
     this.byteLength = 0;
-
-    this._addStats();
   }
 
-  toString() {
+  toString(): string {
     return `${this.constructor.name}(${this.id})`;
   }
 
@@ -52,28 +64,28 @@ export default class Resource {
     // Will regenerate and reinitialize the handle if necessary
     // const glCount = glGetContextLossCount(this.gl);
     // if (this.glCount !== glCount) {
-    //   this._handle = this._createHandle(this.opts);
+    //   this._handle = this._createHandle(this.props);
     //   this._glCount = glCount;
     //   // Reinitialize object
-    //   this.initialize(this.opts);
+    //   this.initialize(this.props);
     // }
     return this._handle;
   }
 
   delete({deleteChildren = false} = {}) {
     // Delete this object, and get refs to any children
-    // @ts-ignore
+    // @ts-expect-error
     const children = this._handle && this._deleteHandle(this._handle);
     if (this._handle) {
-      this._removeStats();
+      this.removeStats();
     }
     this._handle = null;
 
     // Optionally, recursively delete the children
-    // @ts-ignore
+    // @ts-expect-error
     if (children && deleteChildren) {
-      // @ts-ignore
-      children.filter(Boolean).forEach(child => child.delete());
+      // @ts-expect-error
+      children.filter(Boolean).forEach((child) => child.delete());
     }
 
     return this;
@@ -109,14 +121,14 @@ export default class Resource {
   /**
    * Query a Resource parameter
    *
-   * @param {GLenum} pname
-   * @return {GLint|GLfloat|GLenum} param
+   * @param name
+   * @return param
    */
-  getParameter(pname, opts = {}) {
+  getParameter(pname: number, props = {}): any {
     pname = getKeyValue(this.gl, pname);
     assert(pname);
 
-    // @ts-ignore
+    // @ts-expect-error
     const parameters = this.constructor.PARAMETERS || {};
 
     // Use parameter definitions to handle unsupported parameters
@@ -139,17 +151,17 @@ export default class Resource {
 
     // If unknown parameter - Could be a valid parameter not covered by PARAMS
     // Attempt to query for it and let WebGL report errors
-    return this._getParameter(pname, opts);
+    return this._getParameter(pname, props);
   }
 
   // Many resources support a getParameter call -
   // getParameters will get all parameters - slow but useful for debugging
   // eslint-disable-next-line complexity
-  getParameters(options = {}) {
+  getParameters(options: {parameters?, keys?} = {}) {
     const {parameters, keys} = options;
 
     // Get parameter definitions for this Resource
-    // @ts-ignore
+    // @ts-expect-error
     const PARAMETERS = this.constructor.PARAMETERS || {};
 
     const isWebgl2 = isWebGL2(this.gl);
@@ -194,7 +206,7 @@ export default class Resource {
     pname = getKeyValue(this.gl, pname);
     assert(pname);
 
-    // @ts-ignore
+    // @ts-expect-error
     const parameters = this.constructor.PARAMETERS || {};
 
     const parameter = parameters[pname];
@@ -212,6 +224,7 @@ export default class Resource {
 
       // Handle string keys
       if (parameter.type === 'GLenum') {
+        // @ts-expect-error
         value = getKeyValue(value);
       }
     }
@@ -239,7 +252,7 @@ export default class Resource {
   }
 
   // PUBLIC VIRTUAL METHODS
-  initialize(opts) {}
+  initialize(props) {}
 
   // PROTECTED METHODS - These must be overridden by subclass
   _createHandle() {
@@ -258,8 +271,7 @@ export default class Resource {
     throw new Error(ERR_RESOURCE_METHOD_UNDEFINED);
   }
 
-  /** @returns {number} */
-  _getParameter(pname, opts) {
+  _getParameter(pname, props): number {
     throw new Error(ERR_RESOURCE_METHOD_UNDEFINED);
   }
 
@@ -269,11 +281,7 @@ export default class Resource {
 
   // PRIVATE METHODS
 
-  _context() {
-    this.gl.luma = this.gl.luma || {};
-    return this.gl.luma;
-  }
-
+  /*
   _addStats() {
     const name = this.constructor.name;
     const stats = lumaStats.get('Resource Counts');
@@ -290,7 +298,7 @@ export default class Resource {
     stats.get(`${name}s Active`).decrementCount();
   }
 
-  _trackAllocatedMemory(bytes, name = this.constructor.name) {
+  trackAllocatedMemory(bytes, name = this.constructor.name) {
     const stats = lumaStats.get('Memory Usage');
 
     stats.get('GPU Memory').addCount(bytes);
@@ -298,11 +306,12 @@ export default class Resource {
     this.byteLength = bytes;
   }
 
-  _trackDeallocatedMemory(name = this.constructor.name) {
+  trackDeallocatedMemory(name = this.constructor.name) {
     const stats = lumaStats.get('Memory Usage');
 
     stats.get('GPU Memory').subtractCount(this.byteLength);
     stats.get(`${name} Memory`).subtractCount(this.byteLength);
     this.byteLength = 0;
   }
+  */
 }

package/src/context/context/context-state.ts

@@ -0,0 +1,39 @@
+/**
+ * Stores luma.gl specific state associated with a context
+ */
+export interface ContextState {
+  _canvasSizeInfo: {
+    clientWidth: number;
+    clientHeight: number;
+    devicePixelRatio: number;
+  };
+  _polyfilled: boolean;
+  _extensions: Record<string, any>;
+}
+
+/**
+ * Gets luma.gl specific state from a context
+ * @returns context state
+ */
+export function getContextState(gl: WebGLRenderingContext): ContextState {
+  // @ts-expect-error
+  const {device, luma} = gl;
+  if (device) {
+    return device as ContextState;
+  }
+  if (!luma) {
+    const contextState: ContextState = {
+      _canvasSizeInfo: {
+        clientWidth: 0,
+        clientHeight: 0,
+        devicePixelRatio: 1,
+      },
+      _polyfilled: false,
+      _extensions: {}
+    };
+    // @ts-expect-error
+    gl.luma = contextState;
+  }
+  // @ts-expect-error
+  return gl.luma;
+}

package/src/context/context/create-context.ts

@@ -0,0 +1,83 @@
+// luma.gl, MIT license
+
+/**
+ * ContextProps
+* @param webgl2 Set to false to not create a WebGL2 context (force webgl1)
+* @param webgl1 set to false to not create a WebGL1 context (fail if webgl2 not available)
+* @param onContextLost
+* @param onContextRestored
+*
+* BROWSER CONTEXT PARAMETERS
+* @param debug Instrument context (at the expense of performance).
+* @param alpha Default render target has an alpha buffer.
+* @param depth Default render target has a depth buffer of at least 16 bits.
+* @param stencil Default render target has a stencil buffer of at least 8 bits.
+* @param antialias Boolean that indicates whether or not to perform anti-aliasing.
+* @param premultipliedAlpha Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
+* @param preserveDrawingBuffer Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
+* @param failIfMajorPerformanceCaveat Do not create if the system performance is low.
+*/
+
+type ContextProps = {
+  webgl1?: boolean;
+  webgl2?: boolean;
+  onContextLost?: (event: Event) => void;
+  onContextRestored?: (event: Event) => void;
+  alpha?: boolean; // indicates if the canvas contains an alpha buffer.
+  desynchronized?: boolean; // hints the user agent to reduce the latency by desynchronizing the canvas paint cycle from the event loop
+  antialias?: boolean; // indicates whether or not to perform anti-aliasing.
+  depth?: boolean; // indicates that the drawing buffer has a depth buffer of at least 16 bits.
+  failIfMajorPerformanceCaveat?: boolean, // indicates if a context will be created if the system performance is low or if no hardware GPU is available.
+  powerPreference?: 'default' |  'high-performance' | 'low-power',
+  premultipliedAlpha?: boolean, // page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
+  preserveDrawingBuffer?: boolean // buffers will not be cleared and will preserve their values until cleared or overwritten by the author.
+};
+
+const DEFAULT_CONTEXT_PROPS: ContextProps = {
+  webgl2: true, // Attempt to create a WebGL2 context
+  webgl1: true, // Attempt to create a WebGL1 context (false to fail if webgl2 not available)
+  powerPreference: 'high-performance', // After all, most apps are using WebGL for performance reasons
+  onContextLost: () => console.error('WebGL context lost'),
+  onContextRestored: () => console.info('WebGL context restored'),
+};
+
+/**
+ * Create a WebGL context for a canvas
+ * Note calling this multiple time on the same canvas does return the same context
+* @param canvas A canvas element or offscreen canvas
+ */
+ export function createBrowserContext(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): WebGLRenderingContext {
+   props = {...DEFAULT_CONTEXT_PROPS, ...props};
+
+  // Try to extract any extra information about why context creation failed
+  let errorMessage = null;
+  const onCreateError = (error) => (errorMessage = error.statusMessage || errorMessage);
+  canvas.addEventListener('webglcontextcreationerror', onCreateError, false);
+
+  // Create the desired context
+  let gl = null;
+
+  // Prefer webgl2 over webgl1 if both are acceptable
+  if (props.webgl2) {
+    gl = gl || canvas.getContext('webgl2', props);
+  }
+  if (props.webgl1) {
+    gl = gl || canvas.getContext('webgl', props);
+  }
+
+  // TODO are we removing this listener before giving it a chance to fire?
+  canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+
+  if (!gl) {
+    throw new Error(
+      `Failed to create ${props.webgl2 && !props.webgl1 ? 'WebGL2' : 'WebGL'} context: ${
+        errorMessage || 'Unknown error'
+      }`
+    );
+  }
+
+  canvas.addEventListener('webglcontextlost', props.onContextLost, false);
+  canvas.addEventListener('webglcontextrestored', props.onContextRestored, false);
+
+  return gl;
+}

package/src/context/context/device-pixels.ts

@@ -0,0 +1,147 @@
+import {log} from '@luma.gl/api';
+import {getContextState} from './context-state';
+
+/**
+ * Returns multiplier need to convert CSS size to Device size
+ */
+export function cssToDeviceRatio(gl: WebGLRenderingContext): number {
+  const state = getContextState(gl);
+
+  if (gl.canvas && state) {
+    // For headless gl we might have used custom width and height
+    // hence use cached clientWidth
+    const {clientWidth} = state._canvasSizeInfo;
+    return clientWidth ? gl.drawingBufferWidth / clientWidth : 1;
+  }
+  // use default device pixel ratio
+  return 1;
+}
+
+/**
+ * Maps CSS pixel position to device pixel position
+ */
+ export function cssToDevicePixels(
+  gl: WebGLRenderingContext,
+  cssPixel: number[],
+  yInvert: boolean = true
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
+  const ratio = cssToDeviceRatio(gl);
+  const width = gl.drawingBufferWidth;
+  const height = gl.drawingBufferHeight;
+  return scalePixels(cssPixel, ratio, width, height, yInvert);
+}
+
+/**
+ * Calulates device pixel ratio, used during context creation
+ *
+ * @param useDevicePixels - boolean or a number
+ * @return - device pixel ratio
+ */
+ export function getDevicePixelRatio(useDevicePixels: boolean | number): number {
+  const windowRatio = typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
+  if (Number.isFinite(useDevicePixels)) {
+    // @ts-expect-error Can no longer be boolean after previous line
+    return useDevicePixels <= 0 ? 1 : useDevicePixels;
+  }
+  return useDevicePixels ? windowRatio : 1;
+}
+
+// use devicePixelRatio to set canvas width and height
+export function setDevicePixelRatio(gl, devicePixelRatio, options: {width?: number, height?: number} = {}) {
+  // NOTE: if options.width and options.height not used remove in v8
+  let clientWidth = 'width' in options ? options.width : gl.canvas.clientWidth;
+  let clientHeight = 'height' in options ? options.height : gl.canvas.clientHeight;
+
+  if (!clientWidth || !clientHeight) {
+    log.log(1, 'Canvas clientWidth/clientHeight is 0')();
+    // by forcing devicePixel ratio to 1, we do not scale gl.canvas.width and height in each frame.
+    devicePixelRatio = 1;
+    clientWidth = gl.canvas.width || 1;
+    clientHeight = gl.canvas.height || 1;
+  }
+
+  const contextState = getContextState(gl);
+  const cachedSize = contextState._canvasSizeInfo;
+  // Check if canvas needs to be resized
+  if (
+    cachedSize.clientWidth !== clientWidth ||
+    cachedSize.clientHeight !== clientHeight ||
+    cachedSize.devicePixelRatio !== devicePixelRatio
+  ) {
+    let clampedPixelRatio = devicePixelRatio;
+
+    const canvasWidth = Math.floor(clientWidth * clampedPixelRatio);
+    const canvasHeight = Math.floor(clientHeight * clampedPixelRatio);
+    gl.canvas.width = canvasWidth;
+    gl.canvas.height = canvasHeight;
+
+    // Note: when devicePixelRatio is too high, it is possible we might hit system limit for
+    // drawing buffer width and hight, in those cases they get clamped and resulting aspect ration may not be maintained
+    // for those cases, reduce devicePixelRatio.
+    if (gl.drawingBufferWidth !== canvasWidth || gl.drawingBufferHeight !== canvasHeight) {
+      log.warn(`Device pixel ratio clamped`)();
+      clampedPixelRatio = Math.min(
+        gl.drawingBufferWidth / clientWidth,
+        gl.drawingBufferHeight / clientHeight
+      );
+
+      gl.canvas.width = Math.floor(clientWidth * clampedPixelRatio);
+      gl.canvas.height = Math.floor(clientHeight * clampedPixelRatio);
+    }
+
+    Object.assign(contextState._canvasSizeInfo, {clientWidth, clientHeight, devicePixelRatio});
+  }
+}
+
+
+// PRIVATE
+
+function scalePixels(pixel, ratio, width, height, yInvert) {
+  const x = scaleX(pixel[0], ratio, width);
+  let y = scaleY(pixel[1], ratio, height, yInvert);
+
+  // Find boundaries of next pixel to provide valid range of device pixel locaitons
+
+  let t = scaleX(pixel[0] + 1, ratio, width);
+  // If next pixel's position is clamped to boundary, use it as is, otherwise subtract 1 for current pixel boundary
+  const xHigh = t === width - 1 ? t : t - 1;
+
+  t = scaleY(pixel[1] + 1, ratio, height, yInvert);
+  let yHigh;
+  if (yInvert) {
+    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
+    t = t === 0 ? t : t + 1;
+    // swap y and yHigh
+    yHigh = y;
+    y = t;
+  } else {
+    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
+    yHigh = t === height - 1 ? t : t - 1;
+    // y remains same
+  }
+  return {
+    x,
+    y,
+    // when ratio < 1, current css pixel and next css pixel may point to same device pixel, set width/height to 1 in those cases.
+    width: Math.max(xHigh - x + 1, 1),
+    height: Math.max(yHigh - y + 1, 1)
+  };
+}
+
+function scaleX(x, ratio, width) {
+  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
+  const r = Math.min(Math.round(x * ratio), width - 1);
+  return r;
+}
+
+function scaleY(y, ratio, height, yInvert) {
+  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
+  return yInvert
+    ? Math.max(0, height - 1 - Math.round(y * ratio))
+    : Math.min(Math.round(y * ratio), height - 1);
+}

package/src/context/context/get-canvas.ts

@@ -0,0 +1,37 @@
+// luma.gl, MIT license
+import {isBrowser} from 'probe.gl/env';
+const isPage = isBrowser() && typeof document !== 'undefined';
+
+/**
+ * Creates a new canvas or returns the HTML element for a canvas.
+ * @param width
+ * @param height
+ * @returns
+ */
+export function getCanvas(options: {
+  canvas?: string | HTMLCanvasElement | OffscreenCanvas,
+  width: number,
+  height: number
+}): HTMLCanvasElement | OffscreenCanvas {
+  const {canvas, width = 800, height = 600} = options;
+
+  if (!canvas) {
+    const targetCanvas = document.createElement('canvas');
+    targetCanvas.id = 'lumagl-canvas';
+    targetCanvas.style.width = Number.isFinite(width) ? `${width}px` : '100%';
+    targetCanvas.style.height = Number.isFinite(height) ? `${height}px` : '100%';
+    document.body.insertBefore(targetCanvas, document.body.firstChild);
+    return targetCanvas;
+  }
+
+  if (typeof canvas === 'string') {
+    const isPageLoaded = isPage && document.readyState === 'complete';
+    if (!isPageLoaded) {
+      throw new Error(`createGLContext called on canvas '${canvas}' before page was loaded`);
+    }
+    // TODO - check type?
+    return document.getElementById(canvas) as HTMLCanvasElement;
+  }
+
+  return canvas;
+}

package/src/context/context/resize-context.ts

@@ -0,0 +1,37 @@
+// luma.gl, MIT license
+import { getDevicePixelRatio, setDevicePixelRatio } from "./device-pixels";
+/**
+ * Resize the canvas' drawing buffer.
+ *
+ * Can match the canvas CSS size, and optionally also consider devicePixelRatio
+ * Can be called every frame
+ *
+ * Regardless of size, the drawing buffer will always be scaled to the viewport, but
+ * for best visual results, usually set to either:
+ *  canvas CSS width x canvas CSS height
+ *  canvas CSS width * devicePixelRatio x canvas CSS height * devicePixelRatio
+ * See http://webgl2fundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
+ *
+ * resizeGLContext(gl, {width, height, useDevicePixels})
+ */
+ export function resizeGLContext(
+  gl: WebGLRenderingContext,
+  options?: {
+    width?: number;
+    height?: number;
+    useDevicePixels?: boolean | number;
+  }
+) {
+  // Resize browser context .
+  if (gl.canvas) {
+    const devicePixelRatio = getDevicePixelRatio(options?.useDevicePixels);
+    setDevicePixelRatio(gl, devicePixelRatio, options);
+    return;
+  }
+
+  // Resize headless gl context
+  const ext = gl.getExtension('STACKGL_resize_drawingbuffer');
+  if (ext && options && `width` in options && `height` in options) {
+    ext.resize(options.width, options.height);
+  }
+}

package/src/context/context/webgl-checks.ts

@@ -0,0 +1,49 @@
+// luma.gl, MIT license
+import {assert} from '@luma.gl/api';
+
+const ERR_CONTEXT = 'Invalid WebGLRenderingContext';
+export const ERR_WEBGL = ERR_CONTEXT;
+export const ERR_WEBGL2 = 'Requires WebGL2';
+
+
+/** Check if supplied parameter is a WebGLRenderingContext */
+export function isWebGL(gl: any): boolean {
+  if (typeof WebGLRenderingContext !== 'undefined' && gl instanceof WebGLRenderingContext) {
+    return true;
+  }
+  if (typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext) {
+    return true;
+  }
+  // Look for debug contexts, headless gl etc
+  return Boolean(gl && Number.isFinite(gl._version));
+}
+
+
+/** Check if supplied parameter is a WebGL2RenderingContext */
+export function isWebGL2(gl: any): boolean {
+  if (typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext) {
+    return true;
+  }
+  // Look for debug contexts, headless gl etc
+  return Boolean(gl && gl._version === 2);
+}
+
+
+/** Returns a properly typed WebGL2RenderingContext from a WebGL1 context, or null */
+export function getWebGL2Context(gl: WebGLRenderingContext): WebGL2RenderingContext | null {
+  // @ts-expect-error
+  return isWebGL2(gl) ? gl : null;
+}
+
+
+/** Throw if supplied parameter is not a WebGLRenderingContext, otherwise return properly typed value */
+export function assertWebGLContext(gl: any): WebGLRenderingContext {
+  assert(isWebGL(gl), ERR_CONTEXT);
+  return gl;
+}
+
+/** Throw if supplied parameter is not a WebGL2RenderingContext, otherwise return properly typed value */
+export function assertWebGL2Context(gl: any): WebGL2RenderingContext {
+  assert(isWebGL2(gl), ERR_WEBGL2);
+  return gl;
+}