@luma.gl/webgl 8.6.0-alpha.5 → 9.0.0-alpha.4

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

@@ -0,0 +1,162 @@
+// luma.gl, MIT license
+import {log, loadScript} from '@luma.gl/api/';
+import GL from '@luma.gl/constants';
+
+const WEBGL_DEBUG_CDN_URL = 'https://unpkg.com/webgl-debug@2.0.1/index.js';
+
+type DebugContextProps = {
+  debug?: boolean;
+  throwOnError?: boolean;
+  break?: string[];
+  webgl2?: boolean;
+};
+
+const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
+  debug: true,
+  throwOnError: false,
+  break: undefined,
+  webgl2: false,
+}
+
+// Helper to get shared context data
+function getContextData(gl: any) {
+  gl.luma = gl.luma || {};
+  return gl.luma;
+}
+
+declare global {
+  var WebGLDebugUtils: any;
+}
+
+/**
+ * Loads Khronos WebGLDeveloperTools from CDN if not already installed 
+ * const WebGLDebugUtils = require('webgl-debug');
+ * @see https://github.com/KhronosGroup/WebGLDeveloperTools
+ * @see https://github.com/vorg/webgl-debug
+ */
+export async function loadWebGLDeveloperTools(): Promise<void> {
+  if (!globalThis.WebGLDebugUtils) {
+    // @ts-expect-error Developer tools expects global to be set
+    globalThis.global = globalThis.global || globalThis;
+    // @ts-expect-error Developer tools expects global to be set
+    globalThis.global.module = {};
+    await loadScript(WEBGL_DEBUG_CDN_URL);
+  }
+}
+
+// Returns (a potentially new) context with debug instrumentation turned off or on.
+// Note that this actually returns a new context
+export function makeDebugContext(gl: WebGLRenderingContext, props: DebugContextProps = {}): WebGLRenderingContext {
+  // Return null to ensure we don't try to create a context in this case (TODO what case is that?)
+  if (!gl) {
+    return null;
+  }
+
+  return props.debug ? getDebugContext(gl, props) : getRealContext(gl);
+}
+
+// Returns the real context from either of the real/debug contexts
+function getRealContext(gl: WebGLRenderingContext): WebGLRenderingContext {
+  const data = getContextData(gl);
+  // If the context has a realContext member, it is a debug context so return the realContext
+  return data.realContext ? data.realContext : gl;
+}
+
+// Returns the debug context from either of the real/debug contexts
+function getDebugContext(gl: WebGLRenderingContext, props: DebugContextProps): WebGLRenderingContext {
+  if (!globalThis.WebGLDebugUtils) {
+    log.warn('webgl-debug not loaded')();
+    return gl;
+  }
+
+  const data = getContextData(gl);
+
+  // If this already has a debug context, return it.
+  if (data.debugContext) {
+    return data.debugContext;
+  }
+
+  // Create a new debug context
+  globalThis.WebGLDebugUtils.init({...GL, ...gl});
+  const glDebug = globalThis.WebGLDebugUtils.makeDebugContext(
+    gl,
+    onGLError.bind(null, props),
+    onValidateGLFunc.bind(null, props)
+  );
+
+  // Make sure we have all WebGL2 and extension constants (todo dynamic import to circumvent minification?)
+  for (const key in GL) {
+    if (!(key in glDebug) && typeof GL[key] === 'number') {
+      glDebug[key] = GL[key];
+    }
+  }
+  
+  // Ensure we have a clean prototype on the instrumented object
+  // Note: setPrototypeOf does come with perf warnings, but we already take a bigger perf reduction
+  // by synchronizing the WebGL errors after each WebGL call.
+  class WebGLDebugContext {}
+  Object.setPrototypeOf(glDebug, Object.getPrototypeOf(gl));
+  Object.setPrototypeOf(WebGLDebugContext, glDebug);
+  const debugContext = Object.create(WebGLDebugContext);
+  // Store the debug context
+  data.realContext = gl;
+  data.debugContext = debugContext;
+  debugContext.debug = true;
+
+  // Return it
+  return debugContext;
+}
+
+// DEBUG TRACING
+
+function getFunctionString(functionName: string, functionArgs): string {
+  // Cover bug in webgl-debug-tools
+  functionArgs = Array.from(functionArgs).map(arg => arg === undefined ? 'undefined' : arg);
+  let args = globalThis.WebGLDebugUtils.glFunctionArgsToString(functionName, functionArgs);
+  args = `${args.slice(0, 100)}${args.length > 100 ? '...' : ''}`;
+  return `gl.${functionName}(${args})`;
+}
+
+function onGLError(props: DebugContextProps, err, functionName: string, args: any[]): void {
+  // Cover bug in webgl-debug-tools
+  args = Array.from(args).map(arg => arg === undefined ? 'undefined' : arg);
+  const errorMessage = globalThis.WebGLDebugUtils.glEnumToString(err);
+  const functionArgs = globalThis.WebGLDebugUtils.glFunctionArgsToString(functionName, args);
+  const glName = props.webgl2 ? 'gl2' : 'gl1';
+  const message = `${errorMessage} in ${glName}.${functionName}(${functionArgs})`;
+  log.error(message)();
+  debugger; // eslint-disable-line
+  if (props.throwOnError) {
+    throw new Error(message);
+  }
+}
+
+// Don't generate function string until it is needed
+function onValidateGLFunc(props: DebugContextProps, functionName: string, functionArgs: any[]): void {
+  let functionString: string;
+  if (log.level >= 1) {
+    functionString = getFunctionString(functionName, functionArgs);
+    log.log(1, functionString)();
+  }
+
+  if (props.break) {
+    functionString = functionString || getFunctionString(functionName, functionArgs);
+    const isBreakpoint =
+      props.break && props.break.every((breakOn: string) => functionString.indexOf(breakOn) !== -1);
+    if (isBreakpoint) {
+      debugger; // eslint-disable-line
+    }
+  }
+
+  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
+      }
+    }
+  }
+}

package/src/context/parameters/unified-parameter-api.ts

@@ -1,8 +1,8 @@
 // Provides a unified API for getting and setting any WebGL parameter
 // Also knows default values of all parameters, enabling fast cache initialization
 // Provides base functionality for the state caching.
-import {assert} from '@luma.gl/api';
-import type {GLParameters} from './webgl-parameters';
+import {Device} from '@luma.gl/api';
+import type {GLParameters} from '../../types/webgl';
 import {
   GL_PARAMETER_DEFAULTS,
   GL_PARAMETER_SETTERS,
@@ -11,6 +11,7 @@ import {
 } from './webgl-parameter-tables';
 
 import {isWebGL} from '../context/webgl-checks';
+import WebGLDevice from '../../adapter/webgl-device';
 
 export type {GLParameters};
 
@@ -20,8 +21,9 @@ export type {GLParameters};
  * @note requires a `cache` object to be set on the context (gl.state.cache)
  * This object is used to fill in any missing values for composite setter functions
  */
-export function setParameters(gl: WebGLRenderingContext, parameters: GLParameters): void {
-  assert(isWebGL(gl), 'setParameters requires a WebGL context');
+export function setParameters(device: Device | WebGLRenderingContext, parameters: GLParameters): void {
+  const webglDevice = WebGLDevice.attach(device);
+  const gl = webglDevice.gl;
 
   if (isObjectEmpty(parameters)) {
     return;

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

@@ -1,7 +1,7 @@
 // Tables describing WebGL parameters
 import GL from '@luma.gl/constants';
 import {isWebGL2} from '../context/webgl-checks';
-import {GLParameters} from './webgl-parameters';
+import type {GLParameters} from '../../types/webgl';
 // DEFAULT SETTINGS - FOR FAST CACHE INITIALIZATION AND CONTEXT RESETS
 
 /* eslint-disable no-shadow */
@@ -346,42 +346,44 @@ export const GL_COMPOSITE_PARAMETER_SETTERS = {
     )
 };
 
+type UpdateFunc = (params: Record<string, any>) => void;
+
 // Setter functions intercepted for cache updates
 export const GL_HOOKED_SETTERS = {
   // GENERIC SETTERS
 
-  enable: (update, capability) =>
+  enable: (update: UpdateFunc, capability) =>
     update({
       [capability]: true
     }),
-  disable: (update, capability) =>
+  disable: (update: UpdateFunc, capability) =>
     update({
       [capability]: false
     }),
-  pixelStorei: (update, pname, value) =>
+  pixelStorei: (update: UpdateFunc, pname, value) =>
     update({
       [pname]: value
     }),
-  hint: (update, pname, hint) =>
+  hint: (update: UpdateFunc, pname, hint) =>
     update({
       [pname]: hint
     }),
 
   // SPECIFIC SETTERS
-  useProgram: (update, value) => update({
+  useProgram: (update: UpdateFunc, value) => update({
     [GL.CURRENT_PROGRAM]: value,
   }),
-  bindRenderbuffer: (update, target, value) => update({
+  bindRenderbuffer: (update: UpdateFunc, target, value) => update({
     [GL.RENDERBUFFER_BINDING]: value
   }),
-  bindTransformFeedback: (update, target, value) => update({
+  bindTransformFeedback: (update: UpdateFunc, target, value) => update({
     [GL.TRANSFORM_FEEDBACK_BINDING]: value
   }),
-  bindVertexArray: (update, value) => update({
+  bindVertexArray: (update: UpdateFunc, value) => update({
     [GL.VERTEX_ARRAY_BINDING]: value
   }),
 
-  bindFramebuffer: (update, target, framebuffer) => {
+  bindFramebuffer: (update: UpdateFunc, target, framebuffer) => {
     switch (target) {
       case GL.FRAMEBUFFER:
         return update({
@@ -396,7 +398,7 @@ export const GL_HOOKED_SETTERS = {
         return null;
     }
   },
-  bindBuffer: (update, target, buffer) => {
+  bindBuffer: (update: UpdateFunc, target, buffer) => {
     const pname = ({
       [GL.ARRAY_BUFFER]: [GL.ARRAY_BUFFER_BINDING],
       [GL.COPY_READ_BUFFER]: [GL.COPY_READ_BUFFER_BINDING],
@@ -412,24 +414,24 @@ export const GL_HOOKED_SETTERS = {
     return {valueChanged: true};
   },
 
-  blendColor: (update, r, g, b, a) =>
+  blendColor: (update: UpdateFunc, r: number, g: number, b: number, a: number) =>
     update({
       [GL.BLEND_COLOR]: new Float32Array([r, g, b, a])
     }),
 
-  blendEquation: (update, mode) =>
+  blendEquation: (update: UpdateFunc, mode) =>
     update({
       [GL.BLEND_EQUATION_RGB]: mode,
       [GL.BLEND_EQUATION_ALPHA]: mode
     }),
 
-  blendEquationSeparate: (update, modeRGB, modeAlpha) =>
+  blendEquationSeparate: (update: UpdateFunc, modeRGB, modeAlpha) =>
     update({
       [GL.BLEND_EQUATION_RGB]: modeRGB,
       [GL.BLEND_EQUATION_ALPHA]: modeAlpha
     }),
 
-  blendFunc: (update, src, dst) =>
+  blendFunc: (update: UpdateFunc, src, dst) =>
     update({
       [GL.BLEND_SRC_RGB]: src,
       [GL.BLEND_DST_RGB]: dst,
@@ -437,7 +439,7 @@ export const GL_HOOKED_SETTERS = {
       [GL.BLEND_DST_ALPHA]: dst
     }),
 
-  blendFuncSeparate: (update, srcRGB, dstRGB, srcAlpha, dstAlpha) =>
+  blendFuncSeparate: (update: UpdateFunc, srcRGB, dstRGB, srcAlpha, dstAlpha) =>
     update({
       [GL.BLEND_SRC_RGB]: srcRGB,
       [GL.BLEND_DST_RGB]: dstRGB,
@@ -445,85 +447,85 @@ export const GL_HOOKED_SETTERS = {
       [GL.BLEND_DST_ALPHA]: dstAlpha
     }),
 
-  clearColor: (update, r, g, b, a) =>
+  clearColor: (update: UpdateFunc, r: number, g: number, b: number, a: number) =>
     update({
       [GL.COLOR_CLEAR_VALUE]: new Float32Array([r, g, b, a])
     }),
 
-  clearDepth: (update, depth) =>
+  clearDepth: (update: UpdateFunc, depth: number) =>
     update({
       [GL.DEPTH_CLEAR_VALUE]: depth
     }),
 
-  clearStencil: (update, s) =>
+  clearStencil: (update: UpdateFunc, s: number) =>
     update({
       [GL.STENCIL_CLEAR_VALUE]: s
     }),
 
-  colorMask: (update, r, g, b, a) =>
+  colorMask: (update: UpdateFunc, r: number, g: number, b: number, a: number) =>
     update({
       [GL.COLOR_WRITEMASK]: [r, g, b, a]
     }),
 
-  cullFace: (update, mode) =>
+  cullFace: (update: UpdateFunc, mode) =>
     update({
       [GL.CULL_FACE_MODE]: mode
     }),
 
-  depthFunc: (update, func) =>
+  depthFunc: (update: UpdateFunc, func) =>
     update({
       [GL.DEPTH_FUNC]: func
     }),
 
-  depthRange: (update, zNear, zFar) =>
+  depthRange: (update: UpdateFunc, zNear: number, zFar: number) =>
     update({
       [GL.DEPTH_RANGE]: new Float32Array([zNear, zFar])
     }),
 
-  depthMask: (update, mask) =>
+  depthMask: (update: UpdateFunc, mask: number) =>
     update({
       [GL.DEPTH_WRITEMASK]: mask
     }),
 
-  frontFace: (update, face) =>
+  frontFace: (update: UpdateFunc, face) =>
     update({
       [GL.FRONT_FACE]: face
     }),
 
-  lineWidth: (update, width) =>
+  lineWidth: (update: UpdateFunc, width) =>
     update({
       [GL.LINE_WIDTH]: width
     }),
 
-  polygonOffset: (update, factor, units) =>
+  polygonOffset: (update: UpdateFunc, factor, units) =>
     update({
       [GL.POLYGON_OFFSET_FACTOR]: factor,
       [GL.POLYGON_OFFSET_UNITS]: units
     }),
 
-  sampleCoverage: (update, value, invert) =>
+  sampleCoverage: (update: UpdateFunc, value, invert) =>
     update({
       [GL.SAMPLE_COVERAGE_VALUE]: value,
       [GL.SAMPLE_COVERAGE_INVERT]: invert
     }),
 
-  scissor: (update, x, y, width, height) =>
+  scissor: (update: UpdateFunc, x, y, width, height) =>
     update({
       [GL.SCISSOR_BOX]: new Int32Array([x, y, width, height])
     }),
 
-  stencilMask: (update, mask) =>
+  stencilMask: (update: UpdateFunc, mask) =>
     update({
       [GL.STENCIL_WRITEMASK]: mask,
       [GL.STENCIL_BACK_WRITEMASK]: mask
     }),
 
-  stencilMaskSeparate: (update, face, mask) =>
+  stencilMaskSeparate: (update: UpdateFunc, face, mask) =>
     update({
       [face === GL.FRONT ? GL.STENCIL_WRITEMASK : GL.STENCIL_BACK_WRITEMASK]: mask
     }),
 
-  stencilFunc: (update, func, ref, mask) =>
+  stencilFunc: (update: UpdateFunc, func, ref, mask) =>
     update({
       [GL.STENCIL_FUNC]: func,
       [GL.STENCIL_REF]: ref,
@@ -533,14 +535,14 @@ export const GL_HOOKED_SETTERS = {
       [GL.STENCIL_BACK_VALUE_MASK]: mask
     }),
 
-  stencilFuncSeparate: (update, face, func, ref, mask) =>
+  stencilFuncSeparate: (update: UpdateFunc, face, func, ref, mask) =>
     update({
       [face === GL.FRONT ? GL.STENCIL_FUNC : GL.STENCIL_BACK_FUNC]: func,
       [face === GL.FRONT ? GL.STENCIL_REF : GL.STENCIL_BACK_REF]: ref,
       [face === GL.FRONT ? GL.STENCIL_VALUE_MASK : GL.STENCIL_BACK_VALUE_MASK]: mask
     }),
 
-  stencilOp: (update, fail, zfail, zpass) =>
+  stencilOp: (update: UpdateFunc, fail, zfail, zpass) =>
     update({
       [GL.STENCIL_FAIL]: fail,
       [GL.STENCIL_PASS_DEPTH_FAIL]: zfail,
@@ -550,14 +552,14 @@ export const GL_HOOKED_SETTERS = {
       [GL.STENCIL_BACK_PASS_DEPTH_PASS]: zpass
     }),
 
-  stencilOpSeparate: (update, face, fail, zfail, zpass) =>
+  stencilOpSeparate: (update: UpdateFunc, face, fail, zfail, zpass) =>
     update({
       [face === GL.FRONT ? GL.STENCIL_FAIL : GL.STENCIL_BACK_FAIL]: fail,
       [face === GL.FRONT ? GL.STENCIL_PASS_DEPTH_FAIL : GL.STENCIL_BACK_PASS_DEPTH_FAIL]: zfail,
       [face === GL.FRONT ? GL.STENCIL_PASS_DEPTH_PASS : GL.STENCIL_BACK_PASS_DEPTH_PASS]: zpass
     }),
 
-  viewport: (update, x, y, width, height) =>
+  viewport: (update: UpdateFunc, x, y, width, height) =>
     update({
       [GL.VIEWPORT]: [x, y, width, height]
     })

package/src/context/polyfill/get-parameter-polyfill.ts

@@ -51,7 +51,7 @@ const WEBGL_PARAMETERS = {
 
   // Extension LIMITS
   [GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT]: (gl, getParameter) => {
-    const ext = gl.luma?.extensions?.[EXT_texture_filter_anisotropic] || 
+    const ext = gl.luma?.extensions?.[EXT_texture_filter_anisotropic] ||
       gl.getExtension('EXT_texture_filter_anisotropic');
     return ext ? getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT) : 1.0;
   },

package/src/context/polyfill/polyfill-context.ts

@@ -35,10 +35,11 @@ function initializeExtensions(gl: WebGLRenderingContext): void {
   const contextState = getContextState(gl);
   // `getSupportedExtensions` can return null when context is lost.
   const EXTENSIONS = gl.getSupportedExtensions() || [];
-  for (const extension of EXTENSIONS) {
-    contextState._extensions[extension] = gl.getExtension(extension);
+  for (const extensionName of EXTENSIONS) {
+    const extension = gl.getExtension(extensionName);
+    contextState._extensions[extensionName] = extension;
     // TODO - this looks like a mistake?
-    contextState[extension] = gl.getExtension(extension);
+    contextState[extensionName] = extension;
   }
 }
 

package/src/context/state-tracker/deep-array-equal.ts

@@ -1,6 +1,6 @@
 
 /** deeply compare two arrays */
-export function deepArrayEqual(x, y): boolean {
+export function deepArrayEqual(x: any, y: any): boolean {
   if (x === y) {
     return true;
   }

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

@@ -81,6 +81,11 @@ class GLState {
   }
 }
 
+function getContextState(gl: WebGLRenderingContext): GLState {
+  // @ts-expect-error
+  return gl.state as GLState;
+}
+
 // PUBLIC API
 
 /**
@@ -127,8 +132,8 @@ class GLState {
     installGetterOverride(gl, 'isEnabled');
   }
 
-  // @ts-expect-error
-  gl.state.enable = enable;
+  const glState = getContextState(gl);
+  glState.enable = enable;
 
   return gl;
 }
@@ -137,12 +142,12 @@ class GLState {
  * Saves current WebGL context state onto an internal per-context stack
  */
  export function pushContextState(gl: WebGLRenderingContext): void {
-  // @ts-expect-error
-  if (!gl.state) {
+  let glState = getContextState(gl);
+  if (!glState) {
     trackContextState(gl, {copyState: false});
+    glState = getContextState(gl);
   }
-  // @ts-expect-error
-  gl.state.push();
+  glState.push();
 }
 
 
@@ -150,10 +155,9 @@ class GLState {
  * Restores previously saved WebGL context state
  */
 export function popContextState(gl: WebGLRenderingContext): void {
-  // @ts-expect-error
-  assert(gl.state);
-  // @ts-expect-error
-  gl.state.pop();
+  const glState = getContextState(gl);
+  assert(glState);
+  glState.pop();
 }
 
 // HELPER FUNCTIONS - INSTALL GET/SET INTERCEPTORS (SPYS) ON THE CONTEXT
@@ -164,7 +168,7 @@ export function popContextState(gl: WebGLRenderingContext): void {
  * @param gl
  * @param functionName
  */
-function installGetterOverride(gl, functionName) {
+function installGetterOverride(gl: WebGLRenderingContext, functionName: string) {
   // Get the original function from the WebGLRenderingContext
   const originalGetterFunc = gl[functionName].bind(gl);
 
@@ -175,15 +179,16 @@ function installGetterOverride(gl, functionName) {
       return originalGetterFunc(pname);
     }
 
-    if (!(pname in gl.state.cache)) {
+    const glState = getContextState(gl);
+    if (!(pname in glState.cache)) {
       // WebGL limits are not prepopulated in the cache, call the original getter when first queried.
-      gl.state.cache[pname] = originalGetterFunc(pname);
+      glState.cache[pname] = originalGetterFunc(pname);
     }
 
     // Optionally call the original function to do a "hard" query from the WebGLRenderingContext
-    return gl.state.enable
+    return glState.enable
       ? // Call the getter the params so that it can e.g. serve from a cache
-        gl.state.cache[pname]
+        glState.cache[pname]
       : // Optionally call the original function to do a "hard" query from the WebGLRenderingContext
         originalGetterFunc(pname);
   };
@@ -204,7 +209,7 @@ function installGetterOverride(gl, functionName) {
  * @param setter
  * @returns
  */
-function installSetterSpy(gl, functionName, setter) {
+function installSetterSpy(gl: WebGLRenderingContext, functionName, setter) {
   // Get the original function from the WebGLRenderingContext
   if (!gl[functionName]) {
     // This could happen if we try to intercept WebGL2 method on a WebGL1 context
@@ -216,7 +221,8 @@ function installSetterSpy(gl, functionName, setter) {
   gl[functionName] = function set(...params) {
     // Update the value
     // Call the setter with the state cache and the params so that it can store the parameters
-    const {valueChanged, oldValue} = setter(gl.state._updateCache, ...params);
+    const glState = getContextState(gl);
+    const {valueChanged, oldValue} = setter(glState._updateCache, ...params);
 
     // Call the original WebGLRenderingContext func to make sure the context actually gets updated
     if (valueChanged) {
@@ -238,13 +244,14 @@ function installSetterSpy(gl, functionName, setter) {
   });
 }
 
-function installProgramSpy(gl) {
+function installProgramSpy(gl: WebGLRenderingContext): void {
   const originalUseProgram = gl.useProgram.bind(gl);
 
   gl.useProgram = function useProgramLuma(handle) {
-    if (gl.state.program !== handle) {
+    const glState = getContextState(gl);
+    if (glState.program !== handle) {
       originalUseProgram(handle);
-      gl.state.program = handle;
+      glState.program = handle;
     }
   };
 }