@luma.gl/webgl 9.1.0-alpha.15 → 9.1.0-alpha.17

package/src/adapter/webgl-device.ts

@@ -12,28 +12,7 @@ import type {
   Texture,
   Framebuffer,
   VertexArray,
-  VertexArrayProps
-} from '@luma.gl/core';
-import {Device, CanvasContext, log} from '@luma.gl/core';
-import type {GLExtensions} from '@luma.gl/constants';
-import {WebGLStateTracker} from '../context/state-tracker/webgl-state-tracker';
-import {createBrowserContext} from '../context/helpers/create-browser-context';
-import {getDeviceInfo} from './device-helpers/webgl-device-info';
-import {WebGLDeviceFeatures} from './device-helpers/webgl-device-features';
-import {WebGLDeviceLimits} from './device-helpers/webgl-device-limits';
-import {WebGLCanvasContext} from './webgl-canvas-context';
-import type {Spector} from '../context/debug/spector-types';
-import {initializeSpectorJS} from '../context/debug/spector';
-import {makeDebugContext} from '../context/debug/webgl-developer-tools';
-import {
-  isTextureFormatSupported,
-  isTextureFormatRenderable,
-  isTextureFormatFilterable
-} from './converters/texture-formats';
-import {uid} from '../utils/uid';
-
-// WebGL classes
-import type {
+  VertexArrayProps,
   BufferProps,
   ShaderProps,
   // Sampler,
@@ -55,6 +34,23 @@ import type {
   TransformFeedbackProps,
   QuerySetProps
 } from '@luma.gl/core';
+import {Device, CanvasContext, log} from '@luma.gl/core';
+import type {GLExtensions} from '@luma.gl/constants';
+import {WebGLStateTracker} from '../context/state-tracker/webgl-state-tracker';
+import {createBrowserContext} from '../context/helpers/create-browser-context';
+import {getDeviceInfo} from './device-helpers/webgl-device-info';
+import {WebGLDeviceFeatures} from './device-helpers/webgl-device-features';
+import {WebGLDeviceLimits} from './device-helpers/webgl-device-limits';
+import {WebGLCanvasContext} from './webgl-canvas-context';
+import type {Spector} from '../context/debug/spector-types';
+import {initializeSpectorJS} from '../context/debug/spector';
+import {makeDebugContext} from '../context/debug/webgl-developer-tools';
+import {
+  isTextureFormatSupported,
+  isTextureFormatRenderable,
+  isTextureFormatFilterable
+} from './converters/texture-formats';
+import {uid} from '../utils/uid';
 
 import {WEBGLBuffer} from './resources/webgl-buffer';
 import {WEBGLShader} from './resources/webgl-shader';
@@ -120,35 +116,62 @@ export class WebGLDevice extends Device {
   constructor(props: DeviceProps) {
     super({...props, id: props.id || uid('webgl-device')});
 
+    // WebGL requires a canvas to be created before creating the context
+    if (!props.createCanvasContext) {
+      throw new Error('WebGLDevice requires props.createCanvasContext to be set');
+    }
+    const canvasContextProps = props.createCanvasContext === true ? {} : props.createCanvasContext;
+
     // If attaching to an already attached context, return the attached device
     // @ts-expect-error device is attached to context
-    const device: WebGLDevice | undefined = props.gl?.device;
+    let device: WebGLDevice | undefined = canvasContextProps.canvas?.gl?.device;
     if (device) {
       throw new Error(`WebGL context already attached to device ${device.id}`);
     }
 
     // Create and instrument context
-    const canvas = props.gl?.canvas || props.canvas;
-    this.canvasContext = new WebGLCanvasContext(this, {...props, canvas});
+    this.canvasContext = new WebGLCanvasContext(this, canvasContextProps);
 
     this.lost = new Promise<{reason: 'destroyed'; message: string}>(resolve => {
       this._resolveContextLost = resolve;
     });
 
-    this.handle = 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.'
-        })
-    });
-    this.gl = this.handle;
+    const webglContextAttributes: WebGLContextAttributes = {...props.webgl};
+    // Copy props from CanvasContextProps
+    if (canvasContextProps.alphaMode === 'premultiplied') {
+      webglContextAttributes.premultipliedAlpha = true;
+    }
+    if (props.powerPreference !== undefined) {
+      webglContextAttributes.powerPreference = props.powerPreference;
+    }
 
-    if (!this.handle) {
+    const gl = createBrowserContext(
+      this.canvasContext.canvas,
+      {
+        onContextLost: (event: Event) =>
+          this._resolveContextLost?.({
+            reason: 'destroyed',
+            message: 'Entered sleep mode, or too many apps or browser tabs are using the GPU.'
+          }),
+        // eslint-disable-next-line no-console
+        onContextRestored: (event: Event) => console.log('WebGL context restored')
+      },
+      webglContextAttributes
+    );
+
+    if (!gl) {
       throw new Error('WebGL context creation failed');
     }
 
+    // @ts-expect-error device is attached to context
+    device = gl.device;
+    if (device) {
+      throw new Error(`WebGL context already attached to device ${device.id}`);
+    }
+
+    this.handle = gl;
+    this.gl = gl;
+
     // Add spector debug instrumentation to context
     // We need to trust spector integration to decide if spector should be initialized
     // We also run spector instrumentation first, otherwise spector can clobber luma instrumentation.
@@ -161,8 +184,12 @@ export class WebGLDevice extends Device {
     // initialize luma Device fields
     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 = new WebGLDeviceFeatures(
+      this.gl,
+      this._extensions,
+      this.props._disabledFeatures
+    );
+    if (this.props._initializeFeatures) {
       this.features.initializeFeatures();
     }
 
@@ -175,11 +202,14 @@ export class WebGLDevice extends Device {
     glState.trackState(this.gl, {copyState: false});
 
     // DEBUG contexts: Add luma debug instrumentation to the context, force log level to at least 1
-    if (props.debug) {
-      this.gl = makeDebugContext(this.gl, {...props, throwOnError: true});
-      this.debug = true;
-      log.level = Math.max(log.level, 1);
+    const debugWebGL = props.debugWebGL || props.debug;
+    const traceWebGL = props.debugWebGL;
+    if (debugWebGL) {
+      this.gl = makeDebugContext(this.gl, {debugWebGL, traceWebGL});
       log.warn('WebGL debug mode activated. Performance reduced.')();
+      if (props.debugWebGL) {
+        log.level = Math.max(log.level, 1);
+      }
     }
   }
 
@@ -212,7 +242,7 @@ export class WebGLDevice extends Device {
   }
 
   createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): WEBGLBuffer {
-    const newProps = this._getBufferProps(props);
+    const newProps = this._normalizeBufferProps(props);
     return new WEBGLBuffer(this, newProps);
   }
 
@@ -398,18 +428,28 @@ export class WebGLDevice extends Device {
    * 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?: WebGL2RenderingContext): string {
-    // @ts-ignore expect-error depends on settings
-    gl = gl || this.gl2 || this.gl;
+  getGLKey(value: unknown, options?: {emptyIfUnknown?: boolean}): string {
     const number = Number(value);
-    for (const key in gl) {
+    for (const key in this.gl) {
       // @ts-ignore expect-error depends on settings
-      if (gl[key] === number) {
+      if (this.gl[key] === number) {
         return `GL.${key}`;
       }
     }
     // No constant found. Stringify the value and return it.
-    return String(value);
+    return options?.emptyIfUnknown ? '' : String(value);
+  }
+
+  /**
+   * Returns a map with any GL.<KEY> constants mapped to strings, both for keys and values
+   */
+  getGLKeys(glParameters: Record<number, unknown>): Record<string, string> {
+    const opts = {emptyIfUnknown: true};
+    return Object.entries(glParameters).reduce<Record<string, string>>((keys, [key, value]) => {
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      keys[`${key}:${this.getGLKey(key, opts)}`] = `${value}:${this.getGLKey(value, opts)}`;
+      return keys;
+    }, {});
   }
 
   /** Store constants */

package/src/context/debug/spector-types.ts

@@ -1,5 +1,5 @@
 // Forked from https://github.com/BabylonJS/Spector.js/blob/master/dist/spector.d.ts
-/* eslint-disable camelcase */
+/* eslint-disable camelcase, no-shadow */
 
 interface IEvent<T> {
   add(callback: (element: T) => void, context?: any): number;

package/src/context/debug/spector.ts

@@ -5,14 +5,14 @@
 import {log} from '@luma.gl/core';
 import {loadScript} from '../../utils/load-script';
 
-import {Spector} from './spector-types';
+import type {Spector} from './spector-types';
 
 /** Spector debug initialization options */
 type SpectorProps = {
-  /** Whether spector is enabled */
-  debugWithSpectorJS?: boolean;
+  /** Whether spector.js is enabled */
+  debugSpectorJS?: boolean;
   /** URL to load spector script from. Typically a CDN URL */
-  spectorUrl?: string;
+  debugSpectorJSUrl?: string;
   /** Canvas to monitor */
   gl?: WebGL2RenderingContext;
 };
@@ -29,19 +29,19 @@ declare global {
 }
 
 export const DEFAULT_SPECTOR_PROPS: Required<SpectorProps> = {
-  debugWithSpectorJS: log.get('spector') || log.get('spectorjs'),
+  debugSpectorJS: log.get('debug-spectorjs'),
   // https://github.com/BabylonJS/Spector.js#basic-usage
   // https://forum.babylonjs.com/t/spectorcdn-is-temporarily-off/48241
   // spectorUrl: 'https://spectorcdn.babylonjs.com/spector.bundle.js';
-  spectorUrl: 'https://cdn.jsdelivr.net/npm/spectorjs@0.9.30/dist/spector.bundle.js',
+  debugSpectorJSUrl: 'https://cdn.jsdelivr.net/npm/spectorjs@0.9.30/dist/spector.bundle.js',
   gl: undefined!
 };
 
 /** Loads spector from CDN if not already installed */
-export async function loadSpectorJS(props: {spectorUrl?: string}): Promise<void> {
+export async function loadSpectorJS(props: {debugSpectorJSUrl?: string}): Promise<void> {
   if (!globalThis.SPECTOR) {
     try {
-      await loadScript(props.spectorUrl || DEFAULT_SPECTOR_PROPS.spectorUrl);
+      await loadScript(props.debugSpectorJSUrl || DEFAULT_SPECTOR_PROPS.debugSpectorJSUrl);
     } catch (error) {
       log.warn(String(error));
     }
@@ -50,14 +50,14 @@ export async function loadSpectorJS(props: {spectorUrl?: string}): Promise<void>
 
 export function initializeSpectorJS(props: SpectorProps): Spector | null {
   props = {...DEFAULT_SPECTOR_PROPS, ...props};
-  if (!props.debugWithSpectorJS) {
+  if (!props.debugSpectorJS) {
     return null;
   }
 
   if (!spector && globalThis.SPECTOR && !globalThis.luma?.spector) {
     log.probe(LOG_LEVEL, 'SPECTOR found and initialized. Start with `luma.spector.displayUI()`')();
-    const {Spector} = globalThis.SPECTOR as any;
-    spector = new Spector();
+    const {Spector: SpectorJS} = globalThis.SPECTOR as any;
+    spector = new SpectorJS();
     if (globalThis.luma) {
       (globalThis.luma as any).spector = spector;
     }

package/src/context/debug/webgl-developer-tools.ts

@@ -11,18 +11,10 @@ import {loadScript} from '../../utils/load-script';
 const WEBGL_DEBUG_CDN_URL = 'https://unpkg.com/webgl-debug@2.0.1/index.js';
 
 type DebugContextProps = {
-  debug?: boolean;
-  throwOnError?: boolean;
-  break?: string[];
+  debugWebGL?: boolean;
+  traceWebGL?: boolean;
 };
 
-// const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
-//   debug: true,
-//   throwOnError: false,
-//   break: [],
-//   webgl2: false,
-// }
-
 type ContextData = {
   realContext?: WebGL2RenderingContext;
   debugContext?: WebGL2RenderingContext;
@@ -60,7 +52,7 @@ export function makeDebugContext(
   gl: WebGL2RenderingContext,
   props: DebugContextProps = {}
 ): WebGL2RenderingContext {
-  return props.debug ? getDebugContext(gl, props) : getRealContext(gl);
+  return props.debugWebGL || props.traceWebGL ? getDebugContext(gl, props) : getRealContext(gl);
 }
 
 // Returns the real context from either of the real/debug contexts
@@ -136,9 +128,7 @@ function onGLError(props: DebugContextProps, err, functionName: string, args: an
   const message = `${errorMessage} in gl.${functionName}(${functionArgs})`;
   log.error(message)();
   debugger; // eslint-disable-line
-  if (props.throwOnError) {
-    throw new Error(message);
-  }
+  // throw new Error(message);
 }
 
 // Don't generate function string until it is needed
@@ -150,29 +140,16 @@ function onValidateGLFunc(
   let functionString: string = '';
   if (log.level >= 1) {
     functionString = getFunctionString(functionName, functionArgs);
-    log.log(1, functionString)();
-  }
-
-  // If array of breakpoint strings supplied, check if any of them is contained in current GLEnum function
-  if (props.break && props.break.length > 0) {
-    functionString = functionString || getFunctionString(functionName, functionArgs);
-    const isBreakpoint = props.break.every(
-      (breakOn: string) => functionString.indexOf(breakOn) !== -1
-    );
-    if (isBreakpoint) {
-      debugger; // eslint-disable-line
+    if (props.traceWebGL) {
+      log.log(1, functionString)();
     }
   }
 
   for (const arg of functionArgs) {
     if (arg === undefined) {
       functionString = functionString || getFunctionString(functionName, functionArgs);
-      if (props.throwOnError) {
-        throw new Error(`Undefined argument: ${functionString}`);
-      } else {
-        log.error(`Undefined argument: ${functionString}`)();
-        debugger; // eslint-disable-line
-      }
+      debugger; // eslint-disable-line
+      // throw new Error(`Undefined argument: ${functionString}`);
     }
   }
 }

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

@@ -5,37 +5,13 @@
 /**
  * ContextProps
  * @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.
+ * @param onContextRestored *
  */
 type ContextProps = {
-  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 = {
-  powerPreference: 'high-performance', // After all, most apps are using WebGL for performance reasons
-  // eslint-disable-next-line no-console
-  onContextLost: () => console.error('WebGL context lost'),
-  // eslint-disable-next-line no-console
-  onContextRestored: () => console.info('WebGL context restored')
+  /** Called when a context is lost */
+  onContextLost: (event: Event) => void;
+  /** Called when a context is restored */
+  onContextRestored: (event: Event) => void;
 };
 
 /**
@@ -45,53 +21,67 @@ const DEFAULT_CONTEXT_PROPS: ContextProps = {
  */
 export function createBrowserContext(
   canvas: HTMLCanvasElement | OffscreenCanvas,
-  props: ContextProps
+  props: ContextProps,
+  webglContextAttributes: WebGLContextAttributes
 ): WebGL2RenderingContext {
-  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: WebGL2RenderingContext | null = null;
+  let errorMessage = '';
+  // const onCreateError = error => (errorMessage = error.statusMessage || errorMessage);
 
-  // props.failIfMajorPerformanceCaveat = true;
+  // Avoid multiple listeners?
+  // canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+  // canvas.addEventListener('webglcontextcreationerror', onCreateError, false);
 
-  // We require webgl2 context
-  gl ||= canvas.getContext('webgl2', props) as WebGL2RenderingContext;
+  const webglProps: WebGLContextAttributes = {
+    preserveDrawingBuffer: true,
+    // failIfMajorPerformanceCaveat: true,
+    ...webglContextAttributes
+  };
 
-  // Software GPU
-
-  // props.failIfMajorPerformanceCaveat = false;
+  // Create the desired context
+  let gl: WebGL2RenderingContext | null = null;
 
-  // if (!gl && props.webgl1) {
-  //   gl = canvas.getContext('webgl', props);
-  // }
+  // Create a webgl2 context
+  gl ||= canvas.getContext('webgl2', webglProps);
+  if (webglProps.failIfMajorPerformanceCaveat) {
+    errorMessage ||=
+      'Only software GPU is available. Set `failIfMajorPerformanceCaveat: false` to allow.';
+  }
 
-  // TODO are we removing this listener before giving it a chance to fire?
-  canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+  // Creation failed with failIfMajorPerformanceCaveat - Try a Software GPU
+  if (!gl && !webglContextAttributes.failIfMajorPerformanceCaveat) {
+    webglProps.failIfMajorPerformanceCaveat = false;
+    gl = canvas.getContext('webgl2', webglProps);
+    // @ts-expect-error
+    gl.luma ||= {};
+    // @ts-expect-error
+    gl.luma.softwareRenderer = true;
+  }
 
   if (!gl) {
-    throw new Error(`Failed to create WebGL context: ${errorMessage || 'Unknown error'}`);
+    gl = canvas.getContext('webgl', {}) as WebGL2RenderingContext;
+    if (gl) {
+      gl = null;
+      errorMessage ||= 'Your browser only supports WebGL1';
+    }
   }
 
-  if (props.onContextLost) {
-    // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
-    const {onContextLost} = props;
-    canvas.addEventListener('webglcontextlost', (event: Event) => onContextLost(event), false);
-  }
-  if (props.onContextRestored) {
-    // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
-    const {onContextRestored} = props;
-    canvas.addEventListener(
-      'webglcontextrestored',
-      (event: Event) => onContextRestored(event),
-      false
-    );
+  if (!gl) {
+    errorMessage ||= 'Your browser does not support WebGL';
+    throw new Error(`Failed to create WebGL context: ${errorMessage}`);
   }
 
+  // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
+  const {onContextLost, onContextRestored} = props;
+  canvas.addEventListener('webglcontextlost', (event: Event) => onContextLost(event), false);
+  canvas.addEventListener(
+    'webglcontextrestored',
+    (event: Event) => onContextRestored(event),
+    false
+  );
+
+  // @ts-expect-error
+  gl.luma ||= {};
   return gl;
 }