@luma.gl/webgl 9.0.0-beta.5 → 9.0.0-beta.7

package/src/adapter/webgl-device.ts

@@ -1,11 +1,10 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import type {
   DeviceProps,
   DeviceInfo,
-  DeviceLimits,
-  DeviceFeature,
   CanvasContextProps,
   TextureFormat,
   VertexArray,
@@ -16,16 +15,16 @@ import type {
   TypedArray
 } from '@luma.gl/core';
 import {Device, CanvasContext, log, uid, assert} from '@luma.gl/core';
-import {isBrowser} from '@probe.gl/env';
+import type {GLExtensions} from '@luma.gl/constants';
 import {
   popContextState,
   pushContextState,
   trackContextState
 } from '../context/state-tracker/track-context-state';
-import {createBrowserContext} from '../context/context/create-browser-context';
+import {createBrowserContext} from '../context/helpers/create-browser-context';
 import {getDeviceInfo} from './device-helpers/webgl-device-info';
-import {getDeviceFeatures} from './device-helpers/webgl-device-features';
-import {getDeviceLimits, getWebGLLimits, WebGLLimits} from './device-helpers/webgl-device-limits';
+import {WebGLDeviceFeatures} from './device-helpers/webgl-device-features';
+import {WebGLDeviceLimits} from './device-helpers/webgl-device-limits';
 import {WebGLCanvasContext} from './webgl-canvas-context';
 import {loadSpectorJS, initializeSpectorJS} from '../context/debug/spector';
 import {loadWebGLDeveloperTools, makeDebugContext} from '../context/debug/webgl-developer-tools';
@@ -55,7 +54,8 @@ import type {
   ComputePassProps,
   // CommandEncoder,
   CommandEncoderProps,
-  TransformFeedbackProps
+  TransformFeedbackProps,
+  QuerySetProps
 } from '@luma.gl/core';
 
 import {WEBGLBuffer} from './resources/webgl-buffer';
@@ -68,11 +68,13 @@ 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 {WEBGLQuerySet} from './resources/webgl-query-set';
 
 import {readPixelsToArray, readPixelsToBuffer} from '../classic/copy-and-blit';
 import {setGLParameters, getGLParameters} from '../context/parameters/unified-parameter-api';
 import {withGLParameters} from '../context/state-tracker/with-parameters';
 import {clear} from '../classic/clear';
+import {getWebGLExtension} from '../context/helpers/webgl-extensions';
 
 const LOG_LEVEL = 1;
 
@@ -82,37 +84,33 @@ export class WebGLDevice extends Device {
   // Public `Device` API
   //
 
-  static type: string = 'webgl';
+  /** type of this device */
+  static readonly type: string = 'webgl';
 
-  static isSupported(): boolean {
-    return typeof WebGL2RenderingContext !== 'undefined';
-  }
-
-  readonly info: DeviceInfo;
-  readonly canvasContext: WebGLCanvasContext;
+  /** type of this device */
+  readonly type = 'webgl';
 
+  /** The underlying WebGL context */
   readonly handle: WebGL2RenderingContext;
+  features: WebGLDeviceFeatures;
+  limits: WebGLDeviceLimits;
 
-  get features(): Set<DeviceFeature> {
-    this._features = this._features || getDeviceFeatures(this.gl);
-    return this._features;
-  }
-
-  get limits(): DeviceLimits {
-    this._limits = this._limits || getDeviceLimits(this.gl);
-    return this._limits;
-  }
+  readonly info: DeviceInfo;
+  readonly canvasContext: WebGLCanvasContext;
 
   readonly lost: Promise<{reason: 'destroyed'; message: string}>;
 
   private _resolveContextLost?: (value: {reason: 'destroyed'; message: string}) => void;
-  private _features?: Set<DeviceFeature>;
-  private _limits?: DeviceLimits;
 
   //
   // Static methods, expected to be present by `luma.createDevice()`
   //
 
+  /** Check if WebGL 2 is available */
+  static isSupported(): boolean {
+    return typeof WebGL2RenderingContext !== 'undefined';
+  }
+
   /**
    * Get a device instance from a GL context
    * Creates and instruments the device if not already created
@@ -137,27 +135,37 @@ export class WebGLDevice extends Device {
   static async create(props: DeviceProps = {}): Promise<WebGLDevice> {
     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
-    if (typeof props.canvas === 'string') {
-      await CanvasContext.pageLoaded;
-    }
+    const promises: Promise<unknown>[] = [];
 
     // Load webgl and spector debug scripts from CDN if requested
-    if (log.get('debug') || props.debug) {
-      await loadWebGLDeveloperTools();
+    if (props.debug) {
+      promises.push(loadWebGLDeveloperTools());
+    }
+
+    if (props.spector) {
+      promises.push(loadSpectorJS());
+    }
+
+    // Wait for page to load: if canvas is a string we need to query the DOM for the canvas element.
+    // We only wait when props.canvas is string to avoids setting the global page onload callback unless necessary.
+    if (typeof props.canvas === 'string') {
+      promises.push(CanvasContext.pageLoaded);
     }
 
-    // @ts-expect-error spector not on props
-    const {spector} = props;
-    if (log.get('spector') || spector) {
-      await loadSpectorJS();
+    // Wait for all the loads to settle before creating the context.
+    // The Device.create() functions are async, so in contrast to the constructor, we can `await` here.
+    const results = await Promise.allSettled(promises);
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        log.error(`Failed to initialize debug libraries ${result.reason}`)();
+      }
     }
 
     log.probe(LOG_LEVEL + 1, 'DOM is loaded')();
 
     // @ts-expect-error
-    if (props.gl && props.gl.device) {
+    if (props.gl?.device) {
+      log.warn('reattaching existing device')();
       return WebGLDevice.attach(props.gl);
     }
 
@@ -165,7 +173,7 @@ export class WebGLDevice extends Device {
 
     // Log some debug info about the newly created context
     const message = `\
-Created ${device.info.type}${device.debug ? ' debug' : ''} context: \
+Created ${device.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)();
@@ -190,41 +198,42 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
     }
 
     // Create and instrument context
-    const canvas = props.canvas || props.gl?.canvas;
+    const canvas = props.gl?.canvas || props.canvas;
     this.canvasContext = new WebGLCanvasContext(this, {...props, canvas});
 
     this.lost = new Promise<{reason: 'destroyed'; message: string}>(resolve => {
       this._resolveContextLost = resolve;
     });
 
-    const onContextLost = (event: Event) =>
-      this._resolveContextLost?.({
-        reason: 'destroyed',
-        message: 'Computer entered sleep mode, or too many apps or browser tabs are using the GPU.'
-      });
-
     let gl: WebGL2RenderingContext | null = props.gl || null;
-    gl =
-      gl ||
-      (isBrowser()
-        ? createBrowserContext(this.canvasContext.canvas, {...props, onContextLost})
-        : null);
-    
+    gl ||= createBrowserContext(this.canvasContext.canvas, {
+      ...props,
+      onContextLost: (event: Event) =>
+        this._resolveContextLost?.({
+          reason: 'destroyed',
+          message: 'Entered sleep mode, or too many apps or browser tabs are using the GPU.'
+        })
+    });
+
     if (!gl) {
       throw new Error('WebGL context creation failed');
     }
 
     this.handle = gl;
-    this.gl = this.handle;
-    this.canvasContext.resize();
+    this.gl = gl;
+
+    (this.gl as any).device = this; // Update GL context: Link webgl context back to device
+    (this.gl as any)._version = 2; // Update GL context: Store WebGL version field on gl context (HACK to identify debug contexts)
 
     // luma Device fields
-    this.info = getDeviceInfo(this.gl);
+    this.info = getDeviceInfo(this.gl, this._extensions);
+    this.limits = new WebGLDeviceLimits(this.gl);
+    this.features = new WebGLDeviceFeatures(this.gl, this._extensions, this.props.disabledFeatures);
+    if (this.props.initalizeFeatures) {
+      this.features.initializeFeatures();
+    }
 
-    // @ts-expect-error Link webgl context back to device
-    this.gl.device = this;
-    // @ts-expect-error Annotate webgl context to handle
-    this.gl._version = this.isWebGL2 ? 2 : 1;
+    this.canvasContext.resize();
 
     // Install context state tracking
     // @ts-expect-error - hidden parameters
@@ -236,26 +245,23 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
     });
 
     // DEBUG contexts: Add debug instrumentation to the context, force log level to at least 1
-    if (isBrowser() && props.debug) {
+    if (props.debug) {
       this.gl = makeDebugContext(this.gl, {...props, throwOnError: true});
       this.debug = true;
       log.level = Math.max(log.level, 1);
       log.warn('WebGL debug mode activated. Performance reduced.')();
     }
 
-    // @ts-expect-error spector not on props
-    if (isBrowser() && props.spector) {
-      const canvas = this.handle.canvas || (props.canvas as HTMLCanvasElement);
-      this.spector = initializeSpectorJS({...this.props, canvas});
+    if (props.spector) {
+      this.spectorJS = initializeSpectorJS({...this.props, canvas: this.handle.canvas});
     }
   }
 
   /**
    * Destroys the context
-   * @note Has no effect for browser contexts, there is no browser API for destroying contexts
+   * @note Has no effect for WebGL browser contexts, there is no browser API for destroying contexts
    */
-  destroy(): void {
-  }
+  destroy(): void {}
 
   get isLost(): boolean {
     return this.gl.isContextLost();
@@ -266,15 +272,15 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
   }
 
   isTextureFormatSupported(format: TextureFormat): boolean {
-    return isTextureFormatSupported(this.gl, format);
+    return isTextureFormatSupported(this.gl, format, this._extensions);
   }
 
   isTextureFormatFilterable(format: TextureFormat): boolean {
-    return isTextureFormatFilterable(this.gl, format);
+    return isTextureFormatFilterable(this.gl, format, this._extensions);
   }
 
   isTextureFormatRenderable(format: TextureFormat): boolean {
-    return isTextureFormatRenderable(this.gl, format);
+    return isTextureFormatRenderable(this.gl, format, this._extensions);
   }
 
   // IMPLEMENTATION OF ABSTRACT DEVICE
@@ -308,12 +314,20 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
     return new WEBGLFramebuffer(this, props);
   }
 
-  createRenderPipeline(props: RenderPipelineProps): WEBGLRenderPipeline {
-    return new WEBGLRenderPipeline(this, props);
+  createVertexArray(props: VertexArrayProps): VertexArray {
+    return new WEBGLVertexArray(this, props);
   }
 
-  override createVertexArray(props: VertexArrayProps): VertexArray {
-    return new WEBGLVertexArray(this, props);
+  createTransformFeedback(props: TransformFeedbackProps): WEBGLTransformFeedback {
+    return new WEBGLTransformFeedback(this, props);
+  }
+
+  createQuerySet(props: QuerySetProps): WEBGLQuerySet {
+    return new WEBGLQuerySet(this, props);
+  }
+
+  createRenderPipeline(props: RenderPipelineProps): WEBGLRenderPipeline {
+    return new WEBGLRenderPipeline(this, props);
   }
 
   beginRenderPass(props: RenderPassProps): WEBGLRenderPass {
@@ -328,21 +342,8 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
     throw new Error('ComputePass not supported in WebGL');
   }
 
-  createTransformFeedback(props: TransformFeedbackProps): WEBGLTransformFeedback {
-    return new WEBGLTransformFeedback(this, props);
-  }
-
   private renderPass: WEBGLRenderPass | null = null;
 
-  getDefaultRenderPass(): WEBGLRenderPass {
-    this.renderPass =
-      this.renderPass ||
-      this.beginRenderPass({
-        framebuffer: this.canvasContext.getCurrentFramebuffer()
-      });
-    return this.renderPass;
-  }
-
   override createCommandEncoder(props?: CommandEncoderProps): WEBGLCommandEncoder {
     return new WEBGLCommandEncoder(this, props);
   }
@@ -360,7 +361,7 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
 
   //
   // TEMPORARY HACKS - will be removed in v9.1
-  // 
+  //
 
   /** @deprecated - should use command encoder */
   override readPixelsToArrayWebGL(
@@ -399,21 +400,26 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
   }
 
   override setParametersWebGL(parameters: any): void {
-    setGLParameters(this, parameters);
+    setGLParameters(this.gl, parameters);
   }
 
   override getParametersWebGL(parameters: any): any {
-    return getGLParameters(this, parameters);
+    return getGLParameters(this.gl, parameters);
   }
 
   override withParametersWebGL(parameters: any, func: any): any {
-    withGLParameters(this, parameters, func);
+    withGLParameters(this.gl, parameters, func);
   }
 
-  override clearWebGL(options?: {framebuffer?: Framebuffer; color?: any; depth?: any; stencil?: any}): void {
+  override clearWebGL(options?: {
+    framebuffer?: Framebuffer;
+    color?: any;
+    depth?: any;
+    stencil?: any;
+  }): void {
     clear(this, options);
   }
-  
+
   //
   // WebGL-only API (not part of `Device` API)
   //
@@ -426,19 +432,11 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
   readonly _canvasSizeInfo = {clientWidth: 0, clientHeight: 0, devicePixelRatio: 1};
 
   /** State used by luma.gl classes - TODO - not used? */
-  readonly _extensions: Record<string, any> = {};
+  readonly _extensions: GLExtensions = {};
   _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;
-  }
+  spectorJS: unknown;
 
   /**
    * Triggers device (or WebGL context) loss.
@@ -446,7 +444,8 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
    */
   override loseDevice(): boolean {
     let deviceLossTriggered = false;
-    const ext = this.gl.getExtension('WEBGL_lose_context');
+    const extensions = this.getExtension('WEBGL_lose_context');
+    const ext = extensions.WEBGL_lose_context;
     if (ext) {
       deviceLossTriggered = true;
       ext.loseContext();
@@ -507,11 +506,15 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
    * 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);
+  setConstantAttributeWebGL(location: number, constant: TypedArray): void {
+    const maxVertexAttributes = this.limits.maxVertexAttributes;
+    this._constants = this._constants || new Array(maxVertexAttributes).fill(null);
     const currentConstant = this._constants[location];
     if (currentConstant && compareConstantArrayValues(currentConstant, constant)) {
-      log.info(1, `setConstantAttribute(${location}) could have been skipped, value unchanged`)();
+      log.info(
+        1,
+        `setConstantAttributeWebGL(${location}) could have been skipped, value unchanged`
+      )();
     }
     this._constants[location] = constant;
 
@@ -529,6 +532,12 @@ ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContex
         assert(false);
     }
   }
+
+  /** Ensure extensions are only requested once */
+  getExtension(name: keyof GLExtensions): GLExtensions {
+    getWebGLExtension(this.gl, name, this._extensions);
+    return this._extensions;
+  }
 }
 
 /** Check if supplied parameter is a WebGL2RenderingContext */

package/src/classic/accessor.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/core';
@@ -58,7 +59,7 @@ export class Accessor implements AccessorObject {
   }
 
   constructor(...accessors: AccessorObject[]) {
-    accessors.forEach((accessor) => this._assign(accessor)); // Merge in sequence
+    accessors.forEach(accessor => this._assign(accessor)); // Merge in sequence
     Object.freeze(this);
   }
 
@@ -151,10 +152,10 @@ export class Accessor implements AccessorObject {
     if (this.divisor === undefined) delete this.divisor;
     if (this.normalized === undefined) delete this.normalized;
     if (this.integer === undefined) delete this.integer;
-  
+
     if (this.buffer === undefined) delete this.buffer;
     if (this.index === undefined) delete this.index;
-  
+
     return this;
   }
 }

package/src/classic/clear.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {Device, Framebuffer, assert} from '@luma.gl/core';
@@ -18,8 +19,8 @@ const GL_DEPTH_STENCIL = 0x84f9;
 // Should disappear if asserts are removed
 const ERR_ARGUMENTS = 'clear: bad arguments';
 
-/** 
- * Optionally clears depth, color and stencil buffers 
+/**
+ * Optionally clears depth, color and stencil buffers
  * @deprecated Set clear color when creating a RenderPass.
  */
 export function clear(
@@ -59,21 +60,26 @@ export function clear(
   assert(clearFlags !== 0, ERR_ARGUMENTS);
 
   // Temporarily set any clear "colors" and call clear
-  withGLParameters(device, parameters, () => {
-    const gl = (device as WebGLDevice).gl;
+  const gl = (device as WebGLDevice).gl;
+  withGLParameters(gl, parameters, () => {
     gl.clear(clearFlags);
   });
 }
 
-/** 
- * WebGL2 - clear a specific drawing buffer 
+/**
+ * WebGL2 - clear a specific drawing buffer
  * @deprecated Set clear color when creating a RenderPass
  */
 export function clearBuffer(
   device: Device,
   options?: {framebuffer?: Framebuffer; buffer?: any; drawBuffer?: any; value?: any}
 ) {
-  const {framebuffer = null, buffer = GL_COLOR, drawBuffer = 0, value = [0, 0, 0, 0]} = options || {};
+  const {
+    framebuffer = null,
+    buffer = GL_COLOR,
+    drawBuffer = 0,
+    value = [0, 0, 0, 0]
+  } = options || {};
   const gl = (device as WebGLDevice).gl;
   withGLParameters(gl, {framebuffer}, () => {
     // Method selection per OpenGL ES 3 docs

package/src/classic/copy-and-blit.ts

@@ -1,10 +1,11 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {assert, Buffer, Texture, Framebuffer, FramebufferProps} from '@luma.gl/core';
 import {GL} from '@luma.gl/constants';
 
-import {WEBGLTexture} from '../adapter/resources/webgl-texture';
+import {WEBGLTextureView} from '../adapter/resources/webgl-texture-view';
 import {WEBGLFramebuffer} from '../adapter/resources/webgl-framebuffer';
 import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from './typed-array-utils';
 import {glFormatToComponents, glTypeToBytes} from './format-utils';
@@ -66,7 +67,7 @@ export function readPixelsToArray(
   // Deduce the type from color attachment if not provided.
   sourceType =
     sourceType ||
-    (framebuffer.colorAttachments[attachment] as WEBGLTexture)?.type ||
+    (framebuffer.colorAttachments[attachment] as WEBGLTextureView)?.texture?.type ||
     GL.UNSIGNED_BYTE;
 
   // Deduce type and allocated pixelArray if needed
@@ -106,7 +107,13 @@ export function readPixelsToBuffer(
     sourceType?: number;
   }
 ): WEBGLBuffer {
-  const {target, sourceX = 0, sourceY = 0, sourceFormat = GL.RGBA, targetByteOffset = 0} = options || {};
+  const {
+    target,
+    sourceX = 0,
+    sourceY = 0,
+    sourceFormat = GL.RGBA,
+    targetByteOffset = 0
+  } = options || {};
   // following parameters are auto deduced if not provided
   let {sourceWidth, sourceHeight, sourceType} = options || {};
   const {framebuffer, deleteFramebuffer} = getFramebuffer(source);

package/src/classic/format-utils.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {assert} from '@luma.gl/core';

package/src/classic/typed-array-utils.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {TypedArray, TypedArrayConstructor} from '@luma.gl/core';
@@ -108,12 +109,7 @@ export function flipRows(options: {
   }
 }
 
-
-export function scalePixels(options: {
-  data: TypedArray;
-  width: number;
-  height: number;
-}): {
+export function scalePixels(options: {data: TypedArray; width: number; height: number}): {
   data: Uint8Array;
   width: number;
   height: number;

package/src/context/debug/spector.ts

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {log, loadScript} from '@luma.gl/core';
@@ -34,8 +35,8 @@ export async function loadSpectorJS(props?: SpectorProps) {
   if (!globalThis.SPECTOR) {
     try {
       await loadScript(SPECTOR_CDN_URL);
-    } catch(error) {
-      log.warn(String(error))
+    } catch (error) {
+      log.warn(String(error));
     }
   }
 }
@@ -64,14 +65,16 @@ export function initializeSpectorJS(props?: SpectorProps) {
     // enables recording some extra information merged in the capture like texture memory sizes and formats
     spector.spyCanvases();
     // A callback when results are ready
-    spector?.onCaptureStarted.add((capture: unknown) => log.info('Spector capture started:', capture)());
+    spector?.onCaptureStarted.add((capture: unknown) =>
+      log.info('Spector capture started:', capture)()
+    );
     spector?.onCapture.add((capture: unknown) => {
       log.info('Spector capture complete:', capture)();
       // Use undocumented Spector API to open the UI with our capture
       // See https://github.com/BabylonJS/Spector.js/blob/767ad1195a25b85a85c381f400eb50a979239eca/src/spector.ts#L124
-      spector?.getResultUI()
+      spector?.getResultUI();
       spector?.resultView.display();
-      spector?.resultView.addCapture(capture)
+      spector?.resultView.addCapture(capture);
     });
   }