@luma.gl/webgl 9.0.0-alpha.15 → 9.0.0-alpha.16

package/dist/context/state-tracker/track-context-state.js

@@ -1,182 +1,204 @@
-import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+// Support for listening to context state changes and intercepting state queries
+// NOTE: this system does not handle buffer bindings
 import { assert } from '@luma.gl/api';
-import { GL_PARAMETER_DEFAULTS, GL_HOOKED_SETTERS, NON_CACHE_PARAMETERS } from '../parameters/webgl-parameter-tables';
-import { setParameters, getParameters } from '../parameters/unified-parameter-api';
-import { deepArrayEqual } from './deep-array-equal';
-
+import { GL_PARAMETER_DEFAULTS, GL_HOOKED_SETTERS, NON_CACHE_PARAMETERS } from '../parameters/webgl-parameter-tables.js';
+import { setParameters, getParameters } from '../parameters/unified-parameter-api.js';
+import { deepArrayEqual } from './deep-array-equal.js';
+// HELPER CLASS - GLState
+/* eslint-disable no-shadow */
 class GLState {
-  constructor(gl, {
-    copyState = false,
-    log = () => {}
-  } = {}) {
-    _defineProperty(this, "gl", void 0);
-
-    _defineProperty(this, "program", null);
-
-    _defineProperty(this, "stateStack", []);
-
-    _defineProperty(this, "enable", true);
-
-    _defineProperty(this, "cache", void 0);
-
-    _defineProperty(this, "log", void 0);
-
-    this.gl = gl;
-    this.cache = copyState ? getParameters(gl) : Object.assign({}, GL_PARAMETER_DEFAULTS);
-    this.log = log;
-    this._updateCache = this._updateCache.bind(this);
-    Object.seal(this);
-  }
-
-  push(values = {}) {
-    this.stateStack.push({});
-  }
-
-  pop() {
-    assert(this.stateStack.length > 0);
-    const oldValues = this.stateStack[this.stateStack.length - 1];
-    setParameters(this.gl, oldValues);
-    this.stateStack.pop();
-  }
-
-  _updateCache(values) {
-    let valueChanged = false;
-    let oldValue;
-    const oldValues = this.stateStack.length > 0 ? this.stateStack[this.stateStack.length - 1] : null;
-
-    for (const key in values) {
-      assert(key !== undefined);
-      const value = values[key];
-      const cached = this.cache[key];
-
-      if (!deepArrayEqual(value, cached)) {
-        valueChanged = true;
-        oldValue = cached;
-
-        if (oldValues && !(key in oldValues)) {
-          oldValues[key] = cached;
+    constructor(gl, { copyState = false, // Copy cache from params (slow) or initialize from WebGL defaults (fast)
+    log = () => { } // Logging function, called when gl parameter change calls are actually issued
+     } = {}) {
+        this.program = null;
+        this.stateStack = [];
+        this.enable = true;
+        this.gl = gl;
+        this.cache = copyState ? getParameters(gl) : Object.assign({}, GL_PARAMETER_DEFAULTS);
+        this.log = log;
+        this._updateCache = this._updateCache.bind(this);
+        Object.seal(this);
+    }
+    push(values = {}) {
+        this.stateStack.push({});
+    }
+    pop() {
+        assert(this.stateStack.length > 0);
+        // Use the saved values in the state stack to restore parameters
+        const oldValues = this.stateStack[this.stateStack.length - 1];
+        setParameters(this.gl, oldValues);
+        // Don't pop until we have reset parameters (to make sure other "stack frames" are not affected)
+        this.stateStack.pop();
+    }
+    /**
+    // interceptor for context set functions - update our cache and our stack
+    // values (Object) - the key values for this setter
+     * @param values
+     * @returns
+     */
+    _updateCache(values) {
+        let valueChanged = false;
+        let oldValue; // = undefined
+        const oldValues = this.stateStack.length > 0 ? this.stateStack[this.stateStack.length - 1] : null;
+        for (const key in values) {
+            assert(key !== undefined);
+            const value = values[key];
+            const cached = this.cache[key];
+            // Check that value hasn't already been shadowed
+            if (!deepArrayEqual(value, cached)) {
+                valueChanged = true;
+                oldValue = cached;
+                // First, save current value being shadowed
+                // If a state stack frame is active, save the current parameter values for pop
+                // but first check that value hasn't already been shadowed and saved
+                if (oldValues && !(key in oldValues)) {
+                    oldValues[key] = cached;
+                }
+                // Save current value being shadowed
+                this.cache[key] = value;
+            }
         }
-
-        this.cache[key] = value;
-      }
+        return { valueChanged, oldValue };
     }
-
-    return {
-      valueChanged,
-      oldValue
-    };
-  }
-
 }
-
 function getContextState(gl) {
-  return gl.state;
+    // @ts-expect-error
+    return gl.state;
 }
-
+// PUBLIC API
+/**
+ * Initialize WebGL state caching on a context
+ * can be called multiple times to enable/disable
+ *
+ * @note After calling this function, context state will be cached
+ * gl.state.push() and gl.state.pop() will be available for saving,
+ * temporarily modifying, and then restoring state.
+ */
 export function trackContextState(gl, options) {
-  const {
-    enable = true,
-    copyState
-  } = options;
-  assert(copyState !== undefined);
-
-  if (!gl.state) {
-    gl.state = new GLState(gl, {
-      copyState
-    });
-    installProgramSpy(gl);
-
-    for (const key in GL_HOOKED_SETTERS) {
-      const setter = GL_HOOKED_SETTERS[key];
-      installSetterSpy(gl, key, setter);
+    const { enable = true, copyState } = options;
+    assert(copyState !== undefined);
+    // @ts-expect-error
+    if (!gl.state) {
+        // @ts-ignore
+        // const {polyfillContext} = global_;
+        // if (polyfillContext) {
+        //   polyfillContext(gl);
+        // }
+        // Create a state cache
+        // @ts-expect-error
+        gl.state = new GLState(gl, { copyState });
+        installProgramSpy(gl);
+        // intercept all setter functions in the table
+        for (const key in GL_HOOKED_SETTERS) {
+            const setter = GL_HOOKED_SETTERS[key];
+            installSetterSpy(gl, key, setter);
+        }
+        // intercept all getter functions in the table
+        installGetterOverride(gl, 'getParameter');
+        installGetterOverride(gl, 'isEnabled');
     }
-
-    installGetterOverride(gl, 'getParameter');
-    installGetterOverride(gl, 'isEnabled');
-  }
-
-  const glState = getContextState(gl);
-  glState.enable = enable;
-  return gl;
+    const glState = getContextState(gl);
+    glState.enable = enable;
+    return gl;
 }
+/**
+ * Saves current WebGL context state onto an internal per-context stack
+ */
 export function pushContextState(gl) {
-  let glState = getContextState(gl);
-
-  if (!glState) {
-    trackContextState(gl, {
-      copyState: false
-    });
-    glState = getContextState(gl);
-  }
-
-  glState.push();
+    let glState = getContextState(gl);
+    if (!glState) {
+        trackContextState(gl, { copyState: false });
+        glState = getContextState(gl);
+    }
+    glState.push();
 }
+/**
+ * Restores previously saved WebGL context state
+ */
 export function popContextState(gl) {
-  const glState = getContextState(gl);
-  assert(glState);
-  glState.pop();
+    const glState = getContextState(gl);
+    assert(glState);
+    glState.pop();
 }
-
+// HELPER FUNCTIONS - INSTALL GET/SET INTERCEPTORS (SPYS) ON THE CONTEXT
+/**
+// Overrides a WebGLRenderingContext state "getter" function
+// to return values directly from cache
+ * @param gl
+ * @param functionName
+ */
 function installGetterOverride(gl, functionName) {
-  const originalGetterFunc = gl[functionName].bind(gl);
-
-  gl[functionName] = function get(pname) {
-    if (pname === undefined || NON_CACHE_PARAMETERS.has(pname)) {
-      return originalGetterFunc(pname);
-    }
-
-    const glState = getContextState(gl);
-
-    if (!(pname in glState.cache)) {
-      glState.cache[pname] = originalGetterFunc(pname);
-    }
-
-    return glState.enable ? glState.cache[pname] : originalGetterFunc(pname);
-  };
-
-  Object.defineProperty(gl[functionName], 'name', {
-    value: "".concat(functionName, "-from-cache"),
-    configurable: false
-  });
+    // Get the original function from the WebGLRenderingContext
+    const originalGetterFunc = gl[functionName].bind(gl);
+    // Wrap it with a spy so that we can update our state cache when it gets called
+    gl[functionName] = function get(pname) {
+        if (pname === undefined || NON_CACHE_PARAMETERS.has(pname)) {
+            // Invalid or blacklisted parameter, do not cache
+            return originalGetterFunc(pname);
+        }
+        const glState = getContextState(gl);
+        if (!(pname in glState.cache)) {
+            // WebGL limits are not prepopulated in the cache, call the original getter when first queried.
+            glState.cache[pname] = originalGetterFunc(pname);
+        }
+        // Optionally call the original function to do a "hard" query from the WebGLRenderingContext
+        return glState.enable
+            ? // Call the getter the params so that it can e.g. serve from a cache
+                glState.cache[pname]
+            : // Optionally call the original function to do a "hard" query from the WebGLRenderingContext
+                originalGetterFunc(pname);
+    };
+    // Set the name of this anonymous function to help in debugging and profiling
+    Object.defineProperty(gl[functionName], 'name', {
+        value: `${functionName}-from-cache`,
+        configurable: false
+    });
 }
-
+/**
+// Overrides a WebGLRenderingContext state "setter" function
+// to call a setter spy before the actual setter. Allows us to keep a cache
+// updated with a copy of the WebGL context state.
+ * @param gl
+ * @param functionName
+ * @param setter
+ * @returns
+ */
 function installSetterSpy(gl, functionName, setter) {
-  if (!gl[functionName]) {
-    return;
-  }
-
-  const originalSetterFunc = gl[functionName].bind(gl);
-
-  gl[functionName] = function set(...params) {
-    const glState = getContextState(gl);
-    const {
-      valueChanged,
-      oldValue
-    } = setter(glState._updateCache, ...params);
-
-    if (valueChanged) {
-      originalSetterFunc(...params);
+    // Get the original function from the WebGLRenderingContext
+    if (!gl[functionName]) {
+        // This could happen if we try to intercept WebGL2 method on a WebGL1 context
+        return;
     }
-
-    return oldValue;
-  };
-
-  Object.defineProperty(gl[functionName], 'name', {
-    value: "".concat(functionName, "-to-cache"),
-    configurable: false
-  });
+    const originalSetterFunc = gl[functionName].bind(gl);
+    // Wrap it with a spy so that we can update our state cache when it gets called
+    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 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) {
+            originalSetterFunc(...params);
+        }
+        // Note: if the original function fails to set the value, our state cache will be bad
+        // No solution for this at the moment, but assuming that this is unlikely to be a real problem
+        // We could call the setter after the originalSetterFunc. Concern is that this would
+        // cause different behavior in debug mode, where originalSetterFunc can throw exceptions
+        return oldValue;
+    };
+    // Set the name of this anonymous function to help in debugging and profiling
+    Object.defineProperty(gl[functionName], 'name', {
+        value: `${functionName}-to-cache`,
+        configurable: false
+    });
 }
-
 function installProgramSpy(gl) {
-  const originalUseProgram = gl.useProgram.bind(gl);
-
-  gl.useProgram = function useProgramLuma(handle) {
-    const glState = getContextState(gl);
-
-    if (glState.program !== handle) {
-      originalUseProgram(handle);
-      glState.program = handle;
-    }
-  };
+    const originalUseProgram = gl.useProgram.bind(gl);
+    gl.useProgram = function useProgramLuma(handle) {
+        const glState = getContextState(gl);
+        if (glState.program !== handle) {
+            originalUseProgram(handle);
+            glState.program = handle;
+        }
+    };
 }
-//# sourceMappingURL=track-context-state.js.map

package/dist/context/state-tracker/with-parameters.js

@@ -1,40 +1,48 @@
-import { default as WebGLDevice } from '../../adapter/webgl-device';
-import { setParameters } from '../parameters/unified-parameter-api';
-import { pushContextState, popContextState } from './track-context-state';
+import { default as WebGLDevice } from '../../adapter/webgl-device.js';
+import { setParameters } from '../parameters/unified-parameter-api.js';
+import { pushContextState, popContextState } from './track-context-state.js';
+/**
+ * Execute a function with a set of temporary WebGL parameter overrides
+ * - Saves current "global" WebGL context settings
+ * - Sets the supplies WebGL context parameters,
+ * - Executes supplied function
+ * - Restores parameters
+ * - Returns the return value of the supplied function
+ */
 export function withParameters(device, parameters, func) {
-  const webglDevice = WebGLDevice.attach(device);
-  const gl = webglDevice.gl;
-
-  if (isObjectEmpty(parameters)) {
-    return func(device);
-  }
-
-  const {
-    nocatch = true
-  } = parameters;
-  pushContextState(gl);
-  setParameters(gl, parameters);
-  let value;
-
-  if (nocatch) {
-    value = func(gl);
-    popContextState(gl);
-  } else {
-    try {
-      value = func(gl);
-    } finally {
-      popContextState(gl);
+    const webglDevice = WebGLDevice.attach(device);
+    const gl = webglDevice.gl;
+    if (isObjectEmpty(parameters)) {
+        // Avoid setting state if no parameters provided. Just call and return
+        return func(device);
     }
-  }
-
-  return value;
+    const { nocatch = true } = parameters;
+    pushContextState(gl);
+    setParameters(gl, parameters);
+    // Setup is done, call the function
+    let value;
+    if (nocatch) {
+        // Avoid try catch to minimize stack size impact for safe execution paths
+        value = func(gl);
+        popContextState(gl);
+    }
+    else {
+        // Wrap in a try-catch to ensure that parameters are restored on exceptions
+        try {
+            value = func(gl);
+        }
+        finally {
+            popContextState(gl);
+        }
+    }
+    return value;
 }
-
+// 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=with-parameters.js.map