@luma.gl/webgl 9.1.0-alpha.2 → 9.1.0-beta.1

package/src/context/debug/spector.ts

@@ -5,54 +5,61 @@
 import {log} from '@luma.gl/core';
 import {loadScript} from '../../utils/load-script';
 
+import type {Spector} from './spector-types';
+
 /** Spector debug initialization options */
 type SpectorProps = {
+  /** Whether spector.js is enabled */
+  debugSpectorJS?: boolean;
+  /** URL to load spector script from. Typically a CDN URL */
+  debugSpectorJSUrl?: string;
   /** Canvas to monitor */
-  canvas?: HTMLCanvasElement | OffscreenCanvas;
-  /** Whether debug is enabled. Auto-detected if ommitted */
-  debug?: boolean;
-  /** Whether spector is disabled */
-  spector?: boolean | string | object;
-};
-
-const DEFAULT_SPECTOR_PROPS: SpectorProps = {
-  spector: log.get('spector') || log.get('inspect')
+  gl?: WebGL2RenderingContext;
 };
 
-// https://github.com/BabylonJS/Spector.js#basic-usage
-const SPECTOR_CDN_URL = 'https://spectorcdn.babylonjs.com/spector.bundle.js';
 const LOG_LEVEL = 1;
 
-let spector: any = null;
+let spector: Spector = null;
 let initialized: boolean = false;
 
 declare global {
+  // @ts-ignore
   // eslint-disable-next-line no-var
-  var SPECTOR: any;
+  var SPECTOR: Spector;
 }
 
+export const DEFAULT_SPECTOR_PROPS: Required<SpectorProps> = {
+  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';
+  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?: SpectorProps) {
+export async function loadSpectorJS(props: {debugSpectorJSUrl?: string}): Promise<void> {
   if (!globalThis.SPECTOR) {
     try {
-      await loadScript(SPECTOR_CDN_URL);
+      await loadScript(props.debugSpectorJSUrl || DEFAULT_SPECTOR_PROPS.debugSpectorJSUrl);
     } catch (error) {
       log.warn(String(error));
     }
   }
 }
 
-export function initializeSpectorJS(props?: SpectorProps) {
+export function initializeSpectorJS(props: SpectorProps): Spector | null {
   props = {...DEFAULT_SPECTOR_PROPS, ...props};
-  if (!props?.spector) {
+  if (!props.debugSpectorJS) {
     return null;
   }
 
-  if (!spector && globalThis.SPECTOR) {
-    log.probe(LOG_LEVEL, 'SPECTOR found and initialized')();
-    spector = new globalThis.SPECTOR.Spector();
+  if (!spector && globalThis.SPECTOR && !globalThis.luma?.spector) {
+    log.probe(LOG_LEVEL, 'SPECTOR found and initialized. Start with `luma.spector.displayUI()`')();
+    const {Spector: SpectorJS} = globalThis.SPECTOR as any;
+    spector = new SpectorJS();
     if (globalThis.luma) {
-      globalThis.luma.spector = spector;
+      (globalThis.luma as any).spector = spector;
     }
   }
 
@@ -74,20 +81,22 @@ export function initializeSpectorJS(props?: SpectorProps) {
       // 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();
+      // @ts-expect-error private
       spector?.resultView.display();
+      // @ts-expect-error private
       spector?.resultView.addCapture(capture);
     });
   }
 
-  if (props?.canvas) {
-    // @ts-expect-error If spector is specified as a canvas id, only monitor that canvas
-    if (typeof props.spector === 'string' && props.spector !== props.canvas.id) {
-      return spector;
-    }
-
+  if (props.gl) {
     // capture startup
-    // spector?.captureCanvas(props?.canvas);
-    spector?.startCapture(props?.canvas, 500); // 500 commands
+    const gl = props.gl;
+    // @ts-expect-error
+    const device = gl.device;
+    spector?.startCapture(props.gl, 500); // 500 commands
+    // @ts-expect-error
+    gl.device = device;
+
     new Promise(resolve => setTimeout(resolve, 2000)).then(_ => {
       log.info('Spector capture stopped after 2 seconds')();
       spector?.stopCapture();

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;
 }
 

package/src/context/parameters/webgl-parameter-tables.ts

@@ -412,9 +412,9 @@ export const GL_HOOKED_SETTERS = {
     update({
       [pname]: value
     }),
-  hint: (update: UpdateFunc, pname: GL, hint: GL) =>
+  hint: (update: UpdateFunc, pname: GL, value: GL) =>
     update({
-      [pname]: hint
+      [pname]: value
     }),
 
   // SPECIFIC SETTERS

package/src/context/polyfills/polyfill-webgl1-extensions.ts

@@ -0,0 +1,202 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Goal is to make WebGL2 contexts look like WebGL1
+// @note Partly inspired by with some older code from the `regl` library
+
+/* eslint-disable camelcase */
+
+import {GL} from '@luma.gl/constants';
+
+// webgl1 extensions natively supported by webgl2
+const WEBGL1_STATIC_EXTENSIONS = {
+  WEBGL_depth_texture: {
+    UNSIGNED_INT_24_8_WEBGL: GL.UNSIGNED_INT_24_8
+  } as const satisfies WEBGL_depth_texture,
+  OES_element_index_uint: {} as const satisfies OES_element_index_uint,
+  OES_texture_float: {} as const satisfies OES_texture_float,
+  OES_texture_half_float: {
+    // @ts-expect-error different numbers?
+    HALF_FLOAT_OES: GL.HALF_FLOAT
+  } as const satisfies OES_texture_half_float,
+  EXT_color_buffer_float: {} as const satisfies EXT_color_buffer_float,
+  OES_standard_derivatives: {
+    FRAGMENT_SHADER_DERIVATIVE_HINT_OES: GL.FRAGMENT_SHADER_DERIVATIVE_HINT
+  } as const satisfies OES_standard_derivatives,
+  EXT_frag_depth: {} as const satisfies EXT_frag_depth,
+  EXT_blend_minmax: {
+    MIN_EXT: GL.MIN,
+    MAX_EXT: GL.MAX
+  } as const satisfies EXT_blend_minmax,
+  EXT_shader_texture_lod: {} as const satisfies EXT_shader_texture_lod
+};
+
+const getWEBGL_draw_buffers = (gl: WebGL2RenderingContext) =>
+  ({
+    drawBuffersWEBGL(buffers: number[]) {
+      return gl.drawBuffers(buffers);
+    },
+    COLOR_ATTACHMENT0_WEBGL: GL.COLOR_ATTACHMENT0,
+    COLOR_ATTACHMENT1_WEBGL: GL.COLOR_ATTACHMENT1,
+    COLOR_ATTACHMENT2_WEBGL: GL.COLOR_ATTACHMENT2,
+    COLOR_ATTACHMENT3_WEBGL: GL.COLOR_ATTACHMENT3
+  }) as const satisfies Partial<WEBGL_draw_buffers>; // - too many fields
+
+const getOES_vertex_array_object = (gl: WebGL2RenderingContext) =>
+  ({
+    VERTEX_ARRAY_BINDING_OES: GL.VERTEX_ARRAY_BINDING,
+    createVertexArrayOES() {
+      return gl.createVertexArray();
+    },
+    deleteVertexArrayOES(vertexArray: WebGLVertexArrayObject): void {
+      return gl.deleteVertexArray(vertexArray);
+    },
+    isVertexArrayOES(vertexArray: WebGLVertexArrayObject): boolean {
+      return gl.isVertexArray(vertexArray);
+    },
+    bindVertexArrayOES(vertexArray: WebGLVertexArrayObject): void {
+      return gl.bindVertexArray(vertexArray);
+    }
+  }) as const satisfies OES_vertex_array_object;
+
+const getANGLE_instanced_arrays = (gl: WebGL2RenderingContext) =>
+  ({
+    VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE: 0x88fe,
+    drawArraysInstancedANGLE(...args) {
+      return gl.drawArraysInstanced(...args);
+    },
+    drawElementsInstancedANGLE(...args) {
+      return gl.drawElementsInstanced(...args);
+    },
+    vertexAttribDivisorANGLE(...args) {
+      return gl.vertexAttribDivisor(...args);
+    }
+  }) as const satisfies ANGLE_instanced_arrays;
+
+/**
+ * Make browser return WebGL2 contexts even if WebGL1 contexts are requested
+ * @param enforce
+ * @returns
+ */
+export function enforceWebGL2(enforce: boolean = true): void {
+  const prototype = HTMLCanvasElement.prototype as any;
+  if (!enforce && prototype.originalGetContext) {
+    // Reset the original getContext function
+    prototype.getContext = prototype.originalGetContext;
+    prototype.originalGetContext = undefined;
+    return;
+  }
+
+  // Store the original getContext function
+  prototype.originalGetContext = prototype.getContext;
+
+  // Override the getContext function
+  prototype.getContext = function (contextId: string, options?: WebGLContextAttributes) {
+    // Attempt to force WebGL2 for all WebGL1 contexts
+    if (contextId === 'webgl' || contextId === 'experimental-webgl') {
+      const context = this.originalGetContext('webgl2', options) as WebGL2RenderingContext;
+      // Work around test mocking
+      if (context instanceof HTMLElement) {
+        polyfillWebGL1Extensions(context);
+      }
+      return context;
+    }
+    // For any other type, return the original context
+    return this.originalGetContext(contextId, options);
+  };
+}
+
+/** Install WebGL1-only extensions on WebGL2 contexts */
+export function polyfillWebGL1Extensions(gl: WebGL2RenderingContext): void {
+  // Enable, to support float and half-float textures
+  gl.getExtension('EXT_color_buffer_float');
+
+  // WebGL1 extensions implemented using WebGL2 APIs
+  const boundExtensions = {
+    ...WEBGL1_STATIC_EXTENSIONS,
+    WEBGL_disjoint_timer_query: gl.getExtension('EXT_disjoint_timer_query_webgl2'),
+    WEBGL_draw_buffers: getWEBGL_draw_buffers(gl),
+    OES_vertex_array_object: getOES_vertex_array_object(gl),
+    ANGLE_instanced_arrays: getANGLE_instanced_arrays(gl)
+  };
+
+  // Override gl.getExtension
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const originalGetExtension = gl.getExtension;
+  gl.getExtension = function (extensionName: string) {
+    const ext = originalGetExtension.call(gl, extensionName);
+    if (ext) {
+      return ext;
+    }
+
+    // Injected extensions
+    if (extensionName in boundExtensions) {
+      return boundExtensions[extensionName];
+    }
+
+    return null;
+  };
+
+  // Override gl.getSupportedExtensions
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const originalGetSupportedExtensions = gl.getSupportedExtensions;
+  gl.getSupportedExtensions = function (): string[] | null {
+    const extensions = originalGetSupportedExtensions.apply(gl) || [];
+    return extensions?.concat(Object.keys(boundExtensions));
+  };
+}
+
+// Update unsized WebGL1 formats to sized WebGL2 formats
+// todo move to texture format file
+// export function getInternalFormat(gl: WebGL2RenderingContext, format: GL, type: GL): GL {
+//   // webgl2 texture formats
+//   // https://webgl2fundamentals.org/webgl/lessons/webgl-data-textures.html
+//   switch (format) {
+//     case GL.DEPTH_COMPONENT:
+//       return GL.DEPTH_COMPONENT24;
+//     case GL.DEPTH_STENCIL:
+//       return GL.DEPTH24_STENCIL8;
+//     case GL.RGBA:
+//       return type === GL.HALF_FLOAT ? GL.RGBA16F : GL.RGBA32F;
+//     case GL.RGB:
+//       return type === GL.HALF_FLOAT ? GL.RGB16F : GL.RGB32F;
+//     default:
+//       return format;
+//   }
+// }
+
+/*
+// texture type to update on the fly
+export function getTextureType(gl: WebGL2RenderingContext, type: GL): GL {
+  if (type === HALF_FLOAT_OES) {
+    return GL.HALF_FLOAT;
+  }
+  return type;
+}
+
+  // And texImage2D to convert the internalFormat to webgl2.
+  const webgl2 = this;
+  const origTexImage = gl.texImage2D;
+  gl.texImage2D = function (target, miplevel, iformat, a, typeFor6, c, d, typeFor9, f) {
+    if (arguments.length == 6) {
+      var ifmt = webgl2.getInternalFormat(gl, iformat, typeFor6);
+      origTexImage.apply(gl, [target, miplevel, ifmt, a, webgl.getTextureType(gl, typeFor6), c]);
+    } else {
+      // arguments.length == 9
+      var ifmt = webgl2.getInternalFormat(gl, iformat, typeFor9);
+      origTexImage.apply(gl, [
+        target,
+        miplevel,
+        ifmt,
+        a,
+        typeFor6,
+        c,
+        d,
+        webgl2.getTextureType(gl, typeFor9),
+        f
+      ]);
+    }
+  };
+};
+*/