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

package/src/adapter/webgl-device.ts

@@ -1,26 +1,38 @@
 // luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
 import type {
   DeviceProps,
   DeviceInfo,
   DeviceLimits,
   DeviceFeature,
   CanvasContextProps,
-  TextureFormat
-} from '@luma.gl/api';
-import {Device, CanvasContext, log, assert} from '@luma.gl/api';
+  TextureFormat,
+  VertexArray,
+  VertexArrayProps,
+  Framebuffer,
+  Buffer,
+  Texture,
+  TypedArray
+} from '@luma.gl/core';
+import {Device, CanvasContext, log, uid, assert} from '@luma.gl/core';
 import {isBrowser} from '@probe.gl/env';
 import {polyfillContext} from '../context/polyfill/polyfill-context';
-import {trackContextState} from '../context/state-tracker/track-context-state';
-import {ContextState} from '../context/context/context-state';
+import {
+  popContextState,
+  pushContextState,
+  trackContextState
+} from '../context/state-tracker/track-context-state';
 import {createBrowserContext} from '../context/context/create-browser-context';
 import {
   createHeadlessContext,
   isHeadlessGLRegistered
 } from '../context/context/create-headless-context';
+
 import {getDeviceInfo} from './device-helpers/get-device-info';
 import {getDeviceFeatures} from './device-helpers/device-features';
 import {getDeviceLimits, getWebGLLimits, WebGLLimits} from './device-helpers/device-limits';
-import WebGLCanvasContext from './webgl-canvas-context';
+import {WebGLCanvasContext} from './webgl-canvas-context';
 import {loadSpectorJS, initializeSpectorJS} from '../context/debug/spector';
 import {loadWebGLDeveloperTools, makeDebugContext} from '../context/debug/webgl-developer-tools';
 import {
@@ -33,37 +45,45 @@ import {
 import type {
   BufferProps,
   ShaderProps,
-  Sampler,
+  // Sampler,
   SamplerProps,
   TextureProps,
   ExternalTexture,
   ExternalTextureProps,
   FramebufferProps,
-  RenderPipeline,
+  // RenderPipeline,
   RenderPipelineProps,
   ComputePipeline,
   ComputePipelineProps,
-  RenderPass,
+  // RenderPass,
   RenderPassProps,
   ComputePass,
-  ComputePassProps
-} from '@luma.gl/api';
-
-import ClassicBuffer from '../classic/buffer';
-import WEBGLBuffer from './resources/webgl-buffer';
-import WEBGLShader from './resources/webgl-shader';
-import WEBGLSampler from './resources/webgl-sampler';
-import WEBGLTexture from './resources/webgl-texture';
-import WEBGLFramebuffer from './resources/webgl-framebuffer';
-import WEBGLRenderPass from './resources/webgl-render-pass';
-import WEBGLRenderPipeline from './resources/webgl-render-pipeline';
+  ComputePassProps,
+  // CommandEncoder,
+  CommandEncoderProps,
+  TransformFeedbackProps
+} from '@luma.gl/core';
+
+import {WEBGLBuffer} from './resources/webgl-buffer';
+import {WEBGLShader} from './resources/webgl-shader';
+import {WEBGLSampler} from './resources/webgl-sampler';
+import {WEBGLTexture} from './resources/webgl-texture';
+import {WEBGLFramebuffer} from './resources/webgl-framebuffer';
+import {WEBGLRenderPass} from './resources/webgl-render-pass';
+import {WEBGLRenderPipeline} from './resources/webgl-render-pipeline';
+import {WEBGLCommandEncoder} from './resources/webgl-command-encoder';
+import {WEBGLVertexArray} from './resources/webgl-vertex-array';
+import {WEBGLTransformFeedback} from './resources/webgl-transform-feedback';
+
+import {readPixelsToArray, readPixelsToBuffer} from '../classic/copy-and-blit';
+import {setGLParameters} from '../context/parameters/unified-parameter-api';
+import {withGLParameters} from '../context/state-tracker/with-parameters';
+import {clear} from '../classic/clear';
 
 const LOG_LEVEL = 1;
 
-let counter = 0;
-
 /** WebGPU style Device API for a WebGL context */
-export default class WebGLDevice extends Device implements ContextState {
+export class WebGLDevice extends Device {
   //
   // Public `Device` API
   //
@@ -95,37 +115,6 @@ export default class WebGLDevice extends Device implements ContextState {
   private _features?: Set<DeviceFeature>;
   private _limits?: DeviceLimits;
 
-  //
-  // WebGL-only API (not part of `Device` API)
-  //
-
-  /** WebGL1 typed context. Can always be used. */
-  readonly gl: WebGLRenderingContext;
-  /** WebGL2 typed context. Need to check isWebGL2 or isWebGL1 before using. */
-  readonly gl2: WebGL2RenderingContext | null = null;
-  readonly debug: boolean = false;
-
-  /** `true` if this is a WebGL1 context. @note `false` if WebGL2 */
-  readonly isWebGL1: boolean;
-  /** `true` if this is a WebGL2 context. @note `false` if WebGL1 */
-  readonly isWebGL2: boolean;
-
-  get webglLimits(): WebGLLimits {
-    this._webglLimits = this._webglLimits || getWebGLLimits(this.gl);
-    return this._webglLimits;
-  }
-
-  private _webglLimits?: WebGLLimits;
-
-  /** State used by luma.gl classes: TODO - move to canvasContext*/
-  readonly _canvasSizeInfo = {clientWidth: 0, clientHeight: 0, devicePixelRatio: 1};
-  /** State used by luma.gl classes */
-  readonly _extensions: Record<string, any> = {};
-  _polyfilled: boolean = false;
-
-  /** Instance of Spector.js (if initialized) */
-  spector;
-
   //
   // Static methods, expected to be present by `luma.createDevice()`
   //
@@ -152,7 +141,7 @@ export default class WebGLDevice extends Device implements ContextState {
   }
 
   static async create(props: DeviceProps = {}): Promise<WebGLDevice> {
-    log.groupCollapsed(LOG_LEVEL, 'WebGLDevice created');
+    log.groupCollapsed(LOG_LEVEL, 'WebGLDevice created')();
 
     // Wait for page to load. Only wait when props. canvas is string
     // to avoid setting page onload callback unless necessary
@@ -161,11 +150,13 @@ export default class WebGLDevice extends Device implements ContextState {
     }
 
     // Load webgl and spector debug scripts from CDN if requested
-    if (props.debug) {
+    if (log.get('debug') || props.debug) {
       await loadWebGLDeveloperTools();
     }
+
     // @ts-expect-error spector not on props
-    if (props.spector) {
+    const {spector} = props;
+    if (log.get('spector') || spector) {
       await loadSpectorJS();
     }
 
@@ -176,7 +167,18 @@ export default class WebGLDevice extends Device implements ContextState {
       return WebGLDevice.attach(props.gl);
     }
 
-    return new WebGLDevice(props);
+    const device = new WebGLDevice(props);
+
+    // Log some debug info about the newly created context
+    const message = `\
+Created ${device.info.type}${device.debug ? ' debug' : ''} context: \
+${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContext.id}`;
+    log.probe(LOG_LEVEL, message)();
+    log.table(LOG_LEVEL, device.info)();
+
+    log.groupEnd(LOG_LEVEL)();
+
+    return device;
   }
 
   //
@@ -184,7 +186,7 @@ export default class WebGLDevice extends Device implements ContextState {
   //
 
   constructor(props: DeviceProps) {
-    super(props);
+    super({...props, id: props.id || uid('webgl-device')});
 
     // If attaching to an already attached context, return the attached device
     // @ts-expect-error device is attached to context
@@ -194,9 +196,10 @@ export default class WebGLDevice extends Device implements ContextState {
     }
 
     // Create and instrument context
-    this.canvasContext = new WebGLCanvasContext(this, props);
+    const canvas = props.canvas || props.gl?.canvas;
+    this.canvasContext = new WebGLCanvasContext(this, {...props, canvas});
 
-    this.lost = new Promise<{reason: 'destroyed'; message: string}>((resolve) => {
+    this.lost = new Promise<{reason: 'destroyed'; message: string}>(resolve => {
       this._resolveContextLost = resolve;
     });
 
@@ -206,10 +209,12 @@ export default class WebGLDevice extends Device implements ContextState {
         message: 'Computer entered sleep mode, or too many apps or browser tabs are using the GPU.'
       });
 
-    let gl: WebGLRenderingContext | WebGL2RenderingContext | null = props.gl;
+    let gl: WebGLRenderingContext | WebGL2RenderingContext | null = props.gl || null;
     gl =
       gl ||
-      (isBrowser() ? createBrowserContext(this.canvasContext.canvas, {...props, onContextLost}) : null);
+      (isBrowser()
+        ? createBrowserContext(this.canvasContext.canvas, {...props, onContextLost})
+        : null);
     gl = gl || (!isBrowser() ? createHeadlessContext({...props, onContextLost}) : null);
 
     if (!gl) {
@@ -221,6 +226,7 @@ export default class WebGLDevice extends Device implements ContextState {
     this.gl2 = this.gl as WebGL2RenderingContext;
     this.isWebGL2 = isWebGL2(this.gl);
     this.isWebGL1 = !this.isWebGL2;
+    this.canvasContext.resize();
 
     // luma Device fields
     this.info = getDeviceInfo(this.gl);
@@ -256,43 +262,19 @@ export default class WebGLDevice extends Device implements ContextState {
       const canvas = this.handle.canvas || (props.canvas as HTMLCanvasElement);
       this.spector = initializeSpectorJS({...this.props, canvas});
     }
-
-    // Log some debug info about the newly created context
-    const message = `\
-Created ${this.info.type}${this.debug ? ' debug' : ''} context: \
-${this.info.vendor}, ${this.info.renderer} for canvas: ${this.canvasContext.id}`;
-    log.probe(LOG_LEVEL, message)();
-
-    log.groupEnd(LOG_LEVEL)();
   }
 
   /**
    * Destroys the context
    * @note Has no effect for browser contexts, there is no browser API for destroying contexts
    */
-  destroy() {
+  destroy(): void {
     const ext = this.gl.getExtension('STACKGL_destroy_context');
     if (ext) {
       ext.destroy();
     }
   }
 
-  /**
-   * Loses the context
-   * @note Triggers context loss, mainly for testing
-   */
-  loseDevice() {
-    const ext = this.gl.getExtension('WEBGL_lose_context');
-    if (ext) {
-      ext.loseContext();
-    }
-    // loseContext should trigger context loss callback but 
-    this._resolveContextLost?.({
-      reason: 'destroyed',
-      message: 'Application triggered context loss'
-    });
-  }
-
   get isLost(): boolean {
     return this.gl.isContextLost();
   }
@@ -329,8 +311,9 @@ ${this.info.vendor}, ${this.info.renderer} for canvas: ${this.canvasContext.id}`
     throw new Error('WebGL only supports a single canvas');
   }
 
-  _createBuffer(props: BufferProps): WEBGLBuffer {
-    return new ClassicBuffer(this, props);
+  createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): WEBGLBuffer {
+    const newProps = this._getBufferProps(props);
+    return new WEBGLBuffer(this, newProps);
   }
 
   _createTexture(props: TextureProps): WEBGLTexture {
@@ -357,6 +340,10 @@ ${this.info.vendor}, ${this.info.renderer} for canvas: ${this.canvasContext.id}`
     return new WEBGLRenderPipeline(this, props);
   }
 
+  override createVertexArray(props: VertexArrayProps): VertexArray {
+    return new WEBGLVertexArray(this, props);
+  }
+
   beginRenderPass(props: RenderPassProps): WEBGLRenderPass {
     return new WEBGLRenderPass(this, props);
   }
@@ -366,7 +353,11 @@ ${this.info.vendor}, ${this.info.renderer} for canvas: ${this.canvasContext.id}`
   }
 
   beginComputePass(props: ComputePassProps): ComputePass {
-    throw new Error('compute shaders not supported in WebGL');
+    throw new Error('ComputePass not supported in WebGL');
+  }
+
+  createTransformFeedback(props: TransformFeedbackProps): WEBGLTransformFeedback {
+    return new WEBGLTransformFeedback(this, props);
   }
 
   private renderPass: WEBGLRenderPass | null = null;
@@ -380,16 +371,195 @@ ${this.info.vendor}, ${this.info.renderer} for canvas: ${this.canvasContext.id}`
     return this.renderPass;
   }
 
+  override createCommandEncoder(props?: CommandEncoderProps): WEBGLCommandEncoder {
+    return new WEBGLCommandEncoder(this, props);
+  }
+
   /**
    * 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
    */
   submit(): void {
-    this.renderPass?.endPass();
+    this.renderPass?.end();
     this.renderPass = null;
     // this.canvasContext.commit();
   }
+
+  //
+  // TEMPORARY HACKS - will be removed in v9.1
+  // 
+
+  /** @deprecated - should use command encoder */
+  override readPixelsToArrayWebGL(
+    source: Framebuffer | Texture,
+    options?: {
+      sourceX?: number;
+      sourceY?: number;
+      sourceFormat?: number;
+      sourceAttachment?: number;
+      target?: Uint8Array | Uint16Array | Float32Array;
+      // following parameters are auto deduced if not provided
+      sourceWidth?: number;
+      sourceHeight?: number;
+      sourceType?: number;
+    }
+  ): Uint8Array | Uint16Array | Float32Array {
+    return readPixelsToArray(source, options);
+  }
+
+  /** @deprecated - should use command encoder */
+  override readPixelsToBufferWebGL2(
+    source: Framebuffer | Texture,
+    options?: {
+      sourceX?: number;
+      sourceY?: number;
+      sourceFormat?: number;
+      target?: Buffer; // A new Buffer object is created when not provided.
+      targetByteOffset?: number; // byte offset in buffer object
+      // following parameters are auto deduced if not provided
+      sourceWidth?: number;
+      sourceHeight?: number;
+      sourceType?: number;
+    }
+  ): Buffer {
+    return readPixelsToBuffer(source, options);
+  }
+
+  override setParametersWebGL(parameters: any): void {
+    setGLParameters(this, parameters);
+  }
+
+  override withParametersWebGL(parameters: any, func: any): any {
+    withGLParameters(this, parameters, func);
+  }
+
+  override clearWebGL(options?: {framebuffer?: Framebuffer; color?: any; depth?: any; stencil?: any}): void {
+    clear(this, options);
+  }
+  
+  //
+  // WebGL-only API (not part of `Device` API)
+  //
+
+  /** WebGL1 typed context. Can always be used. */
+  readonly gl: WebGLRenderingContext;
+  /** WebGL2 typed context. Need to check isWebGL2 or isWebGL1 before using. */
+  readonly gl2: WebGL2RenderingContext | null = null;
+  readonly debug: boolean = false;
+
+  /** `true` if this is a WebGL1 context. @note `false` if WebGL2 */
+  readonly isWebGL1: boolean;
+  /** `true` if this is a WebGL2 context. @note `false` if WebGL1 */
+  readonly isWebGL2: boolean;
+
+  /** State used by luma.gl classes: TODO - move to canvasContext*/
+  readonly _canvasSizeInfo = {clientWidth: 0, clientHeight: 0, devicePixelRatio: 1};
+
+  /** State used by luma.gl classes - TODO - not used? */
+  readonly _extensions: Record<string, any> = {};
+  _polyfilled: boolean = false;
+
+  /** Instance of Spector.js (if initialized) */
+  spector;
+
+  private _webglLimits?: WebGLLimits;
+
+  /** Return WebGL specific limits */
+  get webglLimits(): WebGLLimits {
+    this._webglLimits = this._webglLimits || getWebGLLimits(this.gl);
+    return this._webglLimits;
+  }
+
+  /**
+   * Triggers device (or WebGL context) loss.
+   * @note primarily intended for testing how application reacts to device loss
+   */
+  override loseDevice(): boolean {
+    let deviceLossTriggered = false;
+    const ext = this.gl.getExtension('WEBGL_lose_context');
+    if (ext) {
+      deviceLossTriggered = true;
+      ext.loseContext();
+      // ext.loseContext should trigger context loss callback but the platform may not do this, so do it explicitly
+    }
+    this._resolveContextLost?.({
+      reason: 'destroyed',
+      message: 'Application triggered context loss'
+    });
+    return deviceLossTriggered;
+  }
+
+  /** Save current WebGL context state onto an internal stack */
+  pushState(): void {
+    pushContextState(this.gl);
+  }
+
+  /** Restores previously saved context state */
+  popState(): void {
+    popContextState(this.gl);
+  }
+
+  /**
+   * Storing data on a special field on WebGLObjects makes that data visible in SPECTOR chrome debug extension
+   * luma.gl ids and props can be inspected
+   */
+  setSpectorMetadata(handle: unknown, props: Record<string, unknown>) {
+    // @ts-expect-error
+    // eslint-disable-next-line camelcase
+    handle.__SPECTOR_Metadata = props;
+  }
+
+  /**
+   * Returns the GL.<KEY> constant that corresponds to a numeric value of a GL constant
+   * Be aware that there are some duplicates especially for constants that are 0,
+   * so this isn't guaranteed to return the right key in all cases.
+   */
+  getGLKey(value: unknown, gl?: WebGLRenderingContext): string {
+    // @ts-ignore expect-error depends on settings
+    gl = gl || this.gl2 || this.gl;
+    const number = Number(value);
+    for (const key in gl) {
+      // @ts-ignore expect-error depends on settings
+      if (gl[key] === number) {
+        return `GL.${key}`;
+      }
+    }
+    // No constant found. Stringify the value and return it.
+    return String(value);
+  }
+
+  /** Store constants */
+  _constants: (TypedArray | null)[];
+
+  /**
+   * Set a constant value for a location. Disabled attributes at that location will read from this value
+   * @note WebGL constants are stored globally on the WebGL context, not the VertexArray
+   * so they need to be updated before every render
+   * @todo - remember/cache values to avoid setting them unnecessarily?
+   */
+  setConstantAttribute(location: number, constant: TypedArray): void {
+    this._constants = this._constants || new Array(this.limits.maxVertexAttributes).fill(null);
+    const currentConstant = this._constants[location];
+    if (currentConstant && compareConstantArrayValues(currentConstant, constant)) {
+      log.info(1, `setConstantAttribute(${location}) could have been skipped, value unchanged`)();
+    }
+    this._constants[location] = constant;
+
+    switch (constant.constructor) {
+      case Float32Array:
+        setConstantFloatArray(this, location, constant as Float32Array);
+        break;
+      case Int32Array:
+        setConstantIntArray(this, location, constant as Int32Array);
+        break;
+      case Uint32Array:
+        setConstantUintArray(this, location, constant as Uint32Array);
+        break;
+      default:
+        assert(false);
+    }
+  }
 }
 
 /** Check if supplied parameter is a WebGLRenderingContext */
@@ -412,3 +582,84 @@ function isWebGL2(gl: any): boolean {
   // Look for debug contexts, headless gl etc
   return Boolean(gl && gl._version === 2);
 }
+
+/** Set constant float array attribute */
+function setConstantFloatArray(device: WebGLDevice, location: number, array: Float32Array): void {
+  switch (array.length) {
+    case 1:
+      device.gl.vertexAttrib1fv(location, array);
+      break;
+    case 2:
+      device.gl.vertexAttrib2fv(location, array);
+      break;
+    case 3:
+      device.gl.vertexAttrib3fv(location, array);
+      break;
+    case 4:
+      device.gl.vertexAttrib4fv(location, array);
+      break;
+    default:
+      assert(false);
+  }
+}
+
+/** Set constant signed int array attribute */
+function setConstantIntArray(device: WebGLDevice, location: number, array: Int32Array): void {
+  device.assertWebGL2();
+  device.gl2?.vertexAttribI4iv(location, array);
+  // TODO - not clear if we need to use the special forms, more testing needed
+  // switch (array.length) {
+  //   case 1:
+  //     gl.vertexAttribI1iv(location, array);
+  //     break;
+  //   case 2:
+  //     gl.vertexAttribI2iv(location, array);
+  //     break;
+  //   case 3:
+  //     gl.vertexAttribI3iv(location, array);
+  //     break;
+  //   case 4:
+  //     break;
+  //   default:
+  //     assert(false);
+  // }
+}
+
+/** Set constant unsigned int array attribute */
+function setConstantUintArray(device: WebGLDevice, location: number, array: Uint32Array) {
+  device.assertWebGL2();
+  device.gl2?.vertexAttribI4uiv(location, array);
+  // TODO - not clear if we need to use the special forms, more testing needed
+  // switch (array.length) {
+  //   case 1:
+  //     gl.vertexAttribI1uiv(location, array);
+  //     break;
+  //   case 2:
+  //     gl.vertexAttribI2uiv(location, array);
+  //     break;
+  //   case 3:
+  //     gl.vertexAttribI3uiv(location, array);
+  //     break;
+  //   case 4:
+  //     gl.vertexAttribI4uiv(location, array);
+  //     break;
+  //   default:
+  //     assert(false);
+  // }
+}
+
+/**
+ * Compares contents of two typed arrays
+ * @todo max length?
+ */
+function compareConstantArrayValues(v1: TypedArray, v2: TypedArray): boolean {
+  if (!v1 || !v2 || v1.length !== v2.length || v1.constructor !== v2.constructor) {
+    return false;
+  }
+  for (let i = 0; i < v1.length; ++i) {
+    if (v1[i] !== v2[i]) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/classic/accessor.ts

@@ -1,5 +1,8 @@
-import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/api';
-import GL from '@luma.gl/constants';
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
 import {getTypedArrayFromGLType} from './typed-array-utils';
 
 const DEFAULT_ACCESSOR_VALUES = {
@@ -19,7 +22,7 @@ const PROP_CHECKS = {
   }
 };
 
-export default class Accessor implements AccessorObject {
+export class Accessor implements AccessorObject {
   offset?: number;
   stride?: number;
   type?: number;
@@ -84,8 +87,8 @@ export default class Accessor implements AccessorObject {
       this.type = props.type;
 
       // Auto-deduce integer type?
-      if (props.type === GL.INT || props.type === GL.UNSIGNED_INT) {
-      this.integer = true;
+      if ((props.type as GL) === GL.INT || (props.type as GL) === GL.UNSIGNED_INT) {
+        this.integer = true;
       }
     }
     if (props.size !== undefined) {