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

package/dist/context/debug/webgl-developer-tools.js

@@ -1,121 +1,125 @@
-import { log, loadScript } from '@luma.gl/api/';
-import GL from '@luma.gl/constants';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { log, loadScript } from '@luma.gl/core';
+// Rename constant to prevent inlining. We need the full set of constants for generating debug strings.
+import { GL as GLEnum } from '@luma.gl/constants';
+import { isBrowser } from '@probe.gl/env';
 const WEBGL_DEBUG_CDN_URL = 'https://unpkg.com/webgl-debug@2.0.1/index.js';
-const DEFAULT_DEBUG_CONTEXT_PROPS = {
-  debug: true,
-  throwOnError: false,
-  break: [],
-  webgl2: false
-};
-
-function getContextData(gl) {
-  gl.luma = gl.luma || {};
-  return gl.luma;
+// Helper to get shared context data
+function getWebGLContextData(gl) {
+    gl.luma = gl.luma || {};
+    return gl.luma;
 }
-
+/**
+ * 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() {
-  if (!globalThis.WebGLDebugUtils) {
-    globalThis.global = globalThis.global || globalThis;
-    globalThis.global.module = {};
-    await loadScript(WEBGL_DEBUG_CDN_URL);
-  }
+    if (isBrowser() && !globalThis.WebGLDebugUtils) {
+        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, props = {}) {
-  if (!gl) {
-    return null;
-  }
-
-  return props.debug ? getDebugContext(gl, props) : getRealContext(gl);
+    // 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) {
-  const data = getContextData(gl);
-  return data.realContext ? data.realContext : gl;
+    const data = getWebGLContextData(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, props) {
-  if (!globalThis.WebGLDebugUtils) {
-    log.warn('webgl-debug not loaded')();
-    return gl;
-  }
-
-  const data = getContextData(gl);
-
-  if (data.debugContext) {
-    return data.debugContext;
-  }
-
-  globalThis.WebGLDebugUtils.init({ ...GL,
-    ...gl
-  });
-  const glDebug = globalThis.WebGLDebugUtils.makeDebugContext(gl, onGLError.bind(null, props), onValidateGLFunc.bind(null, props));
-
-  for (const key in GL) {
-    if (!(key in glDebug) && typeof GL[key] === 'number') {
-      glDebug[key] = GL[key];
+    if (!globalThis.WebGLDebugUtils) {
+        log.warn('webgl-debug not loaded')();
+        return gl;
+    }
+    const data = getWebGLContextData(gl);
+    // If this already has a debug context, return it.
+    if (data.debugContext) {
+        return data.debugContext;
+    }
+    // Create a new debug context
+    globalThis.WebGLDebugUtils.init({ ...GLEnum, ...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 GLEnum) {
+        if (!(key in glDebug) && typeof GLEnum[key] === 'number') {
+            glDebug[key] = GLEnum[key];
+        }
     }
-  }
-
-  class WebGLDebugContext {}
-
-  Object.setPrototypeOf(glDebug, Object.getPrototypeOf(gl));
-  Object.setPrototypeOf(WebGLDebugContext, glDebug);
-  const debugContext = Object.create(WebGLDebugContext);
-  data.realContext = gl;
-  data.debugContext = debugContext;
-  debugContext.debug = true;
-  return debugContext;
+    // 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, functionArgs) {
-  functionArgs = Array.from(functionArgs).map(arg => arg === undefined ? 'undefined' : arg);
-  let args = globalThis.WebGLDebugUtils.glFunctionArgsToString(functionName, functionArgs);
-  args = "".concat(args.slice(0, 100)).concat(args.length > 100 ? '...' : '');
-  return "gl.".concat(functionName, "(").concat(args, ")");
+    // 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, err, functionName, args) {
-  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 = "".concat(errorMessage, " in ").concat(glName, ".").concat(functionName, "(").concat(functionArgs, ")");
-  log.error(message)();
-  debugger;
-
-  if (props.throwOnError) {
-    throw new Error(message);
-  }
+    // 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 message = `${errorMessage} in gl.${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, functionName, functionArgs) {
-  let functionString = '';
-
-  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 => functionString.indexOf(breakOn) !== -1);
-
-    if (isBreakpoint) {
-      debugger;
+    let functionString = '';
+    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) => 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: ".concat(functionString));
-      } else {
-        log.error("Undefined argument: ".concat(functionString))();
-        debugger;
-      }
+    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
+            }
+        }
     }
-  }
 }
-//# sourceMappingURL=webgl-developer-tools.js.map

package/dist/context/helpers/create-browser-context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+type ContextProps = {
+    onContextLost?: (event: Event) => void;
+    onContextRestored?: (event: Event) => void;
+    alpha?: boolean;
+    desynchronized?: boolean;
+    antialias?: boolean;
+    depth?: boolean;
+    failIfMajorPerformanceCaveat?: boolean;
+    powerPreference?: 'default' | 'high-performance' | 'low-power';
+    premultipliedAlpha?: boolean;
+    preserveDrawingBuffer?: boolean;
+};
+/**
+ * Create a WebGL context for a canvas
+ * Note calling this multiple time on the same canvas does return the same context
+ * @param canvas A canvas element or offscreen canvas
+ */
+export declare function createBrowserContext(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): WebGL2RenderingContext;
+export {};
+//# sourceMappingURL=create-browser-context.d.ts.map

package/dist/context/helpers/create-browser-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-browser-context.d.ts","sourceRoot":"","sources":["../../../src/context/helpers/create-browser-context.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,KAAK,YAAY,GAAG;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACvC,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC3C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,eAAe,CAAC,EAAE,SAAS,GAAG,kBAAkB,GAAG,WAAW,CAAC;IAC/D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAUF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,GAAG,eAAe,EAC3C,KAAK,EAAE,YAAY,GAClB,sBAAsB,CA+CxB"}

package/dist/context/helpers/create-browser-context.js

@@ -0,0 +1,67 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+const DEFAULT_CONTEXT_PROPS = {
+    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')
+};
+/**
+ * Create a WebGL context for a canvas
+ * Note calling this multiple time on the same canvas does return the same context
+ * @param canvas A canvas element or offscreen canvas
+ */
+export function createBrowserContext(canvas, props) {
+    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 = null;
+    // props.failIfMajorPerformanceCaveat = true;
+    // We require webgl2 context
+    gl ||= canvas.getContext('webgl2', props);
+    // Software GPU
+    // props.failIfMajorPerformanceCaveat = false;
+    // if (!gl && props.webgl1) {
+    //   gl = canvas.getContext('webgl', props);
+    // }
+    // TODO are we removing this listener before giving it a chance to fire?
+    canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+    if (!gl) {
+        throw new Error(`Failed to create WebGL context: ${errorMessage || 'Unknown error'}`);
+    }
+    if (props.onContextLost) {
+        // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
+        const { onContextLost } = props;
+        canvas.addEventListener('webglcontextlost', (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) => onContextRestored(event), false);
+    }
+    return gl;
+}
+/* TODO - can we call this asynchronously to catch the error events?
+export async function createBrowserContextAsync(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): Promise<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);
+
+ const gl = createBrowserContext(canvas, props);
+
+ // Give the listener a chance to fire
+ await new Promise(resolve => setTimeout(resolve, 0));
+
+ canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+
+ return gl;
+}
+*/

package/dist/context/helpers/webgl-context-data.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stores luma.gl specific state associated with a context
+ */
+export interface WebGLContextData {
+    _polyfilled: boolean;
+    _extensions: Record<string, any>;
+}
+/**
+ * Gets luma.gl specific state from a context
+ * @returns context state
+ */
+export declare function getWebGLContextData(gl: WebGL2RenderingContext): WebGLContextData;
+//# sourceMappingURL=webgl-context-data.d.ts.map

package/dist/context/helpers/webgl-context-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-context-data.d.ts","sourceRoot":"","sources":["../../../src/context/helpers/webgl-context-data.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,sBAAsB,GAAG,gBAAgB,CAchF"}

package/dist/context/helpers/webgl-context-data.js

@@ -0,0 +1,21 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/**
+ * Gets luma.gl specific state from a context
+ * @returns context state
+ */
+export function getWebGLContextData(gl) {
+    // @ts-expect-error
+    const luma = gl.luma;
+    if (!luma) {
+        const contextState = {
+            _polyfilled: false,
+            _extensions: {}
+        };
+        // @ts-expect-error
+        gl.luma = contextState;
+    }
+    // @ts-expect-error
+    return gl.luma;
+}

package/dist/context/helpers/webgl-extensions.d.ts

@@ -0,0 +1,4 @@
+import { GLExtensions } from '@luma.gl/constants';
+/** Ensure extensions are only requested once */
+export declare function getWebGLExtension(gl: WebGL2RenderingContext, name: string, extensions: GLExtensions): unknown;
+//# sourceMappingURL=webgl-extensions.d.ts.map

package/dist/context/helpers/webgl-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-extensions.d.ts","sourceRoot":"","sources":["../../../src/context/helpers/webgl-extensions.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAEhD,gDAAgD;AAChD,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,sBAAsB,EAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,YAAY,GACvB,OAAO,CAKT"}

package/dist/context/helpers/webgl-extensions.js

@@ -0,0 +1,10 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/** Ensure extensions are only requested once */
+export function getWebGLExtension(gl, name, extensions) {
+    if (extensions[name] === undefined) {
+        extensions[name] = gl.getExtension(name) || null;
+    }
+    return extensions[name];
+}

package/dist/context/parameters/unified-parameter-api.d.ts

@@ -1,5 +1,4 @@
-import { Device } from '@luma.gl/api';
-import type { GLParameters } from '../../types/webgl';
+import type { GLParameters } from '@luma.gl/constants';
 export type { GLParameters };
 /**
  * Sets any GL parameter regardless of function (gl.blendMode, ...)
@@ -7,7 +6,7 @@ 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 declare function setParameters(device: Device | WebGLRenderingContext, parameters: GLParameters): void;
+export declare function setGLParameters(gl: WebGL2RenderingContext, parameters: GLParameters): void;
 /**
  * Reads the entire WebGL state from a context
 
@@ -22,12 +21,12 @@ export declare function setParameters(device: Device | WebGLRenderingContext, pa
  * considered a very slow operation, to be used only if/when a context already manipulated
  * by external code needs to be synchronized for the first time
  */
-export declare function getParameters(gl: WebGLRenderingContext, parameters?: keyof GLParameters | (keyof GLParameters)[] | GLParameters): GLParameters;
+export declare function getGLParameters(gl: WebGL2RenderingContext, parameters?: keyof GLParameters | (keyof GLParameters)[] | GLParameters): GLParameters;
 /**
  * Reset all parameters to a (almost) pure context state
  * @note viewport and scissor will be set to the values in GL_PARAMETER_DEFAULTS,
  * NOT the canvas size dimensions, so they will have to be properly set after
  * calling this function.
  */
-export declare function resetParameters(gl: WebGLRenderingContext): void;
+export declare function resetGLParameters(gl: WebGL2RenderingContext): void;
 //# sourceMappingURL=unified-parameter-api.d.ts.map

package/dist/context/parameters/unified-parameter-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unified-parameter-api.d.ts","sourceRoot":"","sources":["../../../src/context/parameters/unified-parameter-api.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,MAAM,EAAC,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAWpD,YAAY,EAAC,YAAY,EAAC,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAAG,qBAAqB,EACtC,UAAU,EAAE,YAAY,GACvB,IAAI,CAiDN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,qBAAqB,EACzB,UAAU,GAAE,MAAM,YAAY,GAAG,CAAC,MAAM,YAAY,CAAC,EAAE,GAAG,YAAoC,GAC7F,YAAY,CAkBd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI,CAE/D"}
+{"version":3,"file":"unified-parameter-api.d.ts","sourceRoot":"","sources":["../../../src/context/parameters/unified-parameter-api.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAQrD,YAAY,EAAC,YAAY,EAAC,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,sBAAsB,EAAE,UAAU,EAAE,YAAY,GAAG,IAAI,CA8C1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,sBAAsB,EAC1B,UAAU,GAAE,MAAM,YAAY,GAAG,CAAC,MAAM,YAAY,CAAC,EAAE,GAAG,YAAoC,GAC7F,YAAY,CAkBd;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI,CAElE"}

package/dist/context/parameters/unified-parameter-api.js

@@ -1,63 +1,100 @@
-import { GL_PARAMETER_DEFAULTS, GL_PARAMETER_SETTERS, GL_COMPOSITE_PARAMETER_SETTERS, GL_PARAMETER_GETTERS } from './webgl-parameter-tables';
-import WebGLDevice from '../../adapter/webgl-device';
-export function setParameters(device, parameters) {
-  const webglDevice = WebGLDevice.attach(device);
-  const gl = webglDevice.gl;
-
-  if (isObjectEmpty(parameters)) {
-    return;
-  }
-
-  const compositeSetters = {};
-
-  for (const key in parameters) {
-    const glConstant = Number(key);
-    const setter = GL_PARAMETER_SETTERS[key];
-
-    if (setter) {
-      if (typeof setter === 'string') {
-        compositeSetters[setter] = true;
-      } else {
-        setter(gl, parameters[key], glConstant);
-      }
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { GL_PARAMETER_DEFAULTS, GL_PARAMETER_SETTERS, GL_COMPOSITE_PARAMETER_SETTERS, GL_PARAMETER_GETTERS } from "./webgl-parameter-tables.js";
+/**
+ * Sets any GL parameter regardless of function (gl.blendMode, ...)
+ *
+ * @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 setGLParameters(gl, parameters) {
+    if (isObjectEmpty(parameters)) {
+        return;
     }
-  }
-
-  const cache = gl.state && gl.state.cache;
-
-  if (cache) {
-    for (const key in compositeSetters) {
-      const compositeSetter = GL_COMPOSITE_PARAMETER_SETTERS[key];
-      compositeSetter(gl, parameters, cache);
+    const compositeSetters = {};
+    // HANDLE PRIMITIVE SETTERS (and make note of any composite setters)
+    for (const key in parameters) {
+        const glConstant = Number(key);
+        const setter = GL_PARAMETER_SETTERS[key];
+        if (setter) {
+            // Composite setters should only be called once, so save them
+            if (typeof setter === 'string') {
+                compositeSetters[setter] = true;
+            }
+            else {
+                // if (gl[glConstant] !== undefined) {
+                // TODO - added above check since this is being called on WebGL2 parameters in WebGL1...
+                // TODO - deep equal on values? only call setter if value has changed?
+                // NOTE - the setter will automatically update this.state
+                setter(gl, parameters[key], glConstant);
+            }
+        }
+    }
+    // HANDLE COMPOSITE SETTERS
+    // NOTE: any non-provided values needed by composite setters are filled in from state cache
+    // The cache parameter is automatically retrieved from the context
+    // This depends on `trackContextState`, which is technically a "circular" dependency.
+    // But it is too inconvenient to always require a cache parameter here.
+    // This is the ONLY external dependency in this module/
+    // @ts-expect-error
+    const cache = gl.state && gl.state.cache;
+    if (cache) {
+        for (const key in compositeSetters) {
+            // TODO - avoid calling composite setters if values have not changed.
+            const compositeSetter = GL_COMPOSITE_PARAMETER_SETTERS[key];
+            // Note - if `trackContextState` has been called,
+            // the setter will automatically update this.state.cache
+            compositeSetter(gl, parameters, cache);
+        }
     }
-  }
+    // Add a log for the else case?
 }
-export function getParameters(gl, parameters = GL_PARAMETER_DEFAULTS) {
-  if (typeof parameters === 'number') {
-    const key = parameters;
-    const getter = GL_PARAMETER_GETTERS[key];
-    return getter ? getter(gl, key) : gl.getParameter(key);
-  }
+/**
+ * Reads the entire WebGL state from a context
 
-  const parameterKeys = Array.isArray(parameters) ? parameters : Object.keys(parameters);
-  const state = {};
+  // default to querying all parameters
 
-  for (const key of parameterKeys) {
-    const getter = GL_PARAMETER_GETTERS[key];
-    state[key] = getter ? getter(gl, Number(key)) : gl.getParameter(Number(key));
-  }
-
-  return state;
+  * @returns - a newly created map, with values keyed by GL parameters
+ *
+ * @note Copies the state from a context (gl.getParameter should not be overriden)
+ * Reads the entire WebGL state from a context
+ *
+ * @note This can generates a huge amount of synchronous driver roundtrips and should be
+ * considered a very slow operation, to be used only if/when a context already manipulated
+ * by external code needs to be synchronized for the first time
+ */
+export function getGLParameters(gl, parameters = GL_PARAMETER_DEFAULTS) {
+    // support both arrays of parameters and objects (keys represent parameters)
+    if (typeof parameters === 'number') {
+        // single GL enum
+        const key = parameters;
+        const getter = GL_PARAMETER_GETTERS[key];
+        return getter ? getter(gl, key) : gl.getParameter(key);
+    }
+    const parameterKeys = Array.isArray(parameters) ? parameters : Object.keys(parameters);
+    const state = {};
+    for (const key of parameterKeys) {
+        const getter = GL_PARAMETER_GETTERS[key];
+        state[key] = getter ? getter(gl, Number(key)) : gl.getParameter(Number(key));
+    }
+    return state;
 }
-export function resetParameters(gl) {
-  setParameters(gl, GL_PARAMETER_DEFAULTS);
+/**
+ * Reset all parameters to a (almost) pure context state
+ * @note viewport and scissor will be set to the values in GL_PARAMETER_DEFAULTS,
+ * NOT the canvas size dimensions, so they will have to be properly set after
+ * calling this function.
+ */
+export function resetGLParameters(gl) {
+    setGLParameters(gl, GL_PARAMETER_DEFAULTS);
 }
-
+// Helpers
+// Returns true if given object is empty, false otherwise.
 function isObjectEmpty(object) {
-  for (const key in object) {
-    return false;
-  }
-
-  return true;
+    // @ts-ignore dummy key variable
+    for (const key in object) {
+        return false;
+    }
+    return true;
 }
-//# sourceMappingURL=unified-parameter-api.js.map