@luma.gl/webgl 8.6.0-alpha.1 → 8.6.0-alpha.2

package/src/classes/webgl-resource.ts

@@ -1,9 +1,10 @@
 // luma.gl, MIT license
-import {isWebGL2, assertWebGLContext} from '@luma.gl/gltools';
-import {Resource} from '@luma.gl/api';
+import {Resource, assert, uid, stubRemovedMethods} from '@luma.gl/api';
+import type {Device} from '@luma.gl/api';
 export type {ResourceProps} from '@luma.gl/api';
-import {getKey, getKeyValue} from '../webgl-utils';
-import {uid, assert, stubRemovedMethods} from '../utils';
+import {isWebGL2, assertWebGLContext} from '../context/context/webgl-checks';
+import {getKey, getKeyValue} from '../webgl-utils/constants-to-keys';
+import WebGLDevice from '../device/webgl-device';
 
 const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual methods';
 
@@ -12,17 +13,21 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
  */
  export default class WebGLResource<Props> extends Resource<Props> {
   id: string;
+  userData: any;
+  readonly device: WebGLDevice;
   readonly gl: WebGLRenderingContext;
   readonly gl2: WebGL2RenderingContext;
-  userData: any;
   private _handle: any;
 
   private _bound = false;
   // Only meaningful for resources that allocate GPU memory
   byteLength = 0;
 
-  constructor(gl: WebGLRenderingContext, props: Props, defaultProps: Required<Props>) {
-    super(gl as any, props, defaultProps);
+  constructor(device: Device, props: Props, defaultProps: Required<Props>) {
+    super(device, props, defaultProps);
+
+    this.device = WebGLDevice.attach(device);
+    const gl = this.device.gl;
 
     assertWebGLContext(gl);
 
@@ -30,9 +35,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     // @ts-expect-error
     const {id, userData = {}} = props || {};
     this.gl = gl;
-    // @ts-ignore
-    this.gl2 = gl;
-    // this.ext = polyfillContext(gl);
+    this.gl2 = gl as WebGL2RenderingContext;
     this.id = id || uid(this.constructor.name);
     this.userData = userData;
 
@@ -71,7 +74,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
 
   delete({deleteChildren = false} = {}) {
     // Delete this object, and get refs to any children
-    // @ts-ignore
+    // @ts-expect-error
     const children = this._handle && this._deleteHandle(this._handle);
     if (this._handle) {
       this.removeStats();
@@ -79,9 +82,9 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     this._handle = null;
 
     // Optionally, recursively delete the children
-    // @ts-ignore
+    // @ts-expect-error
     if (children && deleteChildren) {
-      // @ts-ignore
+      // @ts-expect-error
       children.filter(Boolean).forEach((child) => child.delete());
     }
 
@@ -125,7 +128,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     pname = getKeyValue(this.gl, pname);
     assert(pname);
 
-    // @ts-ignore
+    // @ts-expect-error
     const parameters = this.constructor.PARAMETERS || {};
 
     // Use parameter definitions to handle unsupported parameters
@@ -158,7 +161,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     const {parameters, keys} = options;
 
     // Get parameter definitions for this Resource
-    // @ts-ignore
+    // @ts-expect-error
     const PARAMETERS = this.constructor.PARAMETERS || {};
 
     const isWebgl2 = isWebGL2(this.gl);
@@ -203,7 +206,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     pname = getKeyValue(this.gl, pname);
     assert(pname);
 
-    // @ts-ignore
+    // @ts-expect-error
     const parameters = this.constructor.PARAMETERS || {};
 
     const parameter = parameters[pname];
@@ -268,8 +271,7 @@ const ERR_RESOURCE_METHOD_UNDEFINED = 'Resource subclass must define virtual met
     throw new Error(ERR_RESOURCE_METHOD_UNDEFINED);
   }
 
-  /** @returns {number} */
-  _getParameter(pname, props) {
+  _getParameter(pname, props): number {
     throw new Error(ERR_RESOURCE_METHOD_UNDEFINED);
   }
 

package/src/classes/webgl-shader.ts

@@ -1,10 +1,10 @@
 // luma.gl, MIT license
+import {log, assert, uid, Shader as ShaderAPI, ShaderProps} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import {assertWebGLContext, log} from '@luma.gl/gltools';
 import {getShaderInfo, CompilerMessage, formatCompilerLog} from '@luma.gl/shadertools';
-import {Shader as ShaderAPI, ShaderProps} from '@luma.gl/api';
+import {assertWebGLContext} from '../context/context/webgl-checks';
 import {parseShaderCompilerLog} from '../webgl-utils/parse-shader-compiler-log';
-import {uid, assert} from '../utils';
+import WebGLDevice from '../device/webgl-device';
 
 const ERR_SOURCE = 'Shader: GLSL source code must be a JavaScript string';
 
@@ -12,13 +12,15 @@ const ERR_SOURCE = 'Shader: GLSL source code must be a JavaScript string';
 export type {ShaderProps};
 
 export class WEBGLShader extends ShaderAPI {
+  readonly device: WebGLDevice;
   readonly gl: WebGLRenderingContext;
   readonly handle: WebGLShader;
 
   readonly stage: 'vertex' | 'fragment';
 
   constructor(gl: WebGLRenderingContext, props: ShaderProps) {
-    super(gl as any, {id: getShaderIdFromProps(props), ...props});
+    super(WebGLDevice.attach(gl), {id: getShaderIdFromProps(props), ...props});
+    this.device = WebGLDevice.attach(gl);
     this.gl = gl;
     switch (this.props.stage) {
       case 'vertex':

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

@@ -0,0 +1,39 @@
+/**
+ * Stores luma.gl specific state associated with a context
+ */
+export interface ContextState {
+  _canvasSizeInfo: {
+    clientWidth: number;
+    clientHeight: number;
+    devicePixelRatio: number;
+  };
+  _polyfilled: boolean;
+  _extensions: Record<string, any>;
+}
+
+/**
+ * Gets luma.gl specific state from a context
+ * @returns context state
+ */
+export function getContextState(gl: WebGLRenderingContext): ContextState {
+  // @ts-expect-error
+  const {device, luma} = gl;
+  if (device) {
+    return device as ContextState;
+  }
+  if (!luma) {
+    const contextState: ContextState = {
+      _canvasSizeInfo: {
+        clientWidth: 0,
+        clientHeight: 0,
+        devicePixelRatio: 1,
+      },
+      _polyfilled: false,
+      _extensions: {}
+    };
+    // @ts-expect-error
+    gl.luma = contextState;
+  }
+  // @ts-expect-error
+  return gl.luma;
+}

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

@@ -0,0 +1,83 @@
+// luma.gl, MIT license
+
+/**
+ * ContextProps
+* @param webgl2 Set to false to not create a WebGL2 context (force webgl1)
+* @param webgl1 set to false to not create a WebGL1 context (fail if webgl2 not available)
+* @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 = {
+  webgl1?: boolean;
+  webgl2?: boolean;
+  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 = {
+  webgl2: true, // Attempt to create a WebGL2 context
+  webgl1: true, // Attempt to create a WebGL1 context (false to fail if webgl2 not available)
+  powerPreference: 'high-performance', // After all, most apps are using WebGL for performance reasons
+  onContextLost: () => console.error('WebGL context lost'),
+  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: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): WebGLRenderingContext {
+   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;
+
+  // Prefer webgl2 over webgl1 if both are acceptable
+  if (props.webgl2) {
+    gl = gl || canvas.getContext('webgl2', props);
+  }
+  if (props.webgl1) {
+    gl = 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 ${props.webgl2 && !props.webgl1 ? 'WebGL2' : 'WebGL'} context: ${
+        errorMessage || 'Unknown error'
+      }`
+    );
+  }
+
+  canvas.addEventListener('webglcontextlost', props.onContextLost, false);
+  canvas.addEventListener('webglcontextrestored', props.onContextRestored, false);
+
+  return gl;
+}

package/src/context/context/device-pixels.ts

@@ -0,0 +1,147 @@
+import {log} from '@luma.gl/api';
+import {getContextState} from './context-state';
+
+/**
+ * Returns multiplier need to convert CSS size to Device size
+ */
+export function cssToDeviceRatio(gl: WebGLRenderingContext): number {
+  const state = getContextState(gl);
+
+  if (gl.canvas && state) {
+    // For headless gl we might have used custom width and height
+    // hence use cached clientWidth
+    const {clientWidth} = state._canvasSizeInfo;
+    return clientWidth ? gl.drawingBufferWidth / clientWidth : 1;
+  }
+  // use default device pixel ratio
+  return 1;
+}
+
+/**
+ * Maps CSS pixel position to device pixel position
+ */
+ export function cssToDevicePixels(
+  gl: WebGLRenderingContext,
+  cssPixel: number[],
+  yInvert: boolean = true
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
+  const ratio = cssToDeviceRatio(gl);
+  const width = gl.drawingBufferWidth;
+  const height = gl.drawingBufferHeight;
+  return scalePixels(cssPixel, ratio, width, height, yInvert);
+}
+
+/**
+ * Calulates device pixel ratio, used during context creation
+ *
+ * @param useDevicePixels - boolean or a number
+ * @return - device pixel ratio
+ */
+ export function getDevicePixelRatio(useDevicePixels: boolean | number): number {
+  const windowRatio = typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1;
+  if (Number.isFinite(useDevicePixels)) {
+    // @ts-expect-error Can no longer be boolean after previous line
+    return useDevicePixels <= 0 ? 1 : useDevicePixels;
+  }
+  return useDevicePixels ? windowRatio : 1;
+}
+
+// use devicePixelRatio to set canvas width and height
+export function setDevicePixelRatio(gl, devicePixelRatio, options: {width?: number, height?: number} = {}) {
+  // NOTE: if options.width and options.height not used remove in v8
+  let clientWidth = 'width' in options ? options.width : gl.canvas.clientWidth;
+  let clientHeight = 'height' in options ? options.height : gl.canvas.clientHeight;
+
+  if (!clientWidth || !clientHeight) {
+    log.log(1, 'Canvas clientWidth/clientHeight is 0')();
+    // by forcing devicePixel ratio to 1, we do not scale gl.canvas.width and height in each frame.
+    devicePixelRatio = 1;
+    clientWidth = gl.canvas.width || 1;
+    clientHeight = gl.canvas.height || 1;
+  }
+
+  const contextState = getContextState(gl);
+  const cachedSize = contextState._canvasSizeInfo;
+  // Check if canvas needs to be resized
+  if (
+    cachedSize.clientWidth !== clientWidth ||
+    cachedSize.clientHeight !== clientHeight ||
+    cachedSize.devicePixelRatio !== devicePixelRatio
+  ) {
+    let clampedPixelRatio = devicePixelRatio;
+
+    const canvasWidth = Math.floor(clientWidth * clampedPixelRatio);
+    const canvasHeight = Math.floor(clientHeight * clampedPixelRatio);
+    gl.canvas.width = canvasWidth;
+    gl.canvas.height = canvasHeight;
+
+    // Note: when devicePixelRatio is too high, it is possible we might hit system limit for
+    // drawing buffer width and hight, in those cases they get clamped and resulting aspect ration may not be maintained
+    // for those cases, reduce devicePixelRatio.
+    if (gl.drawingBufferWidth !== canvasWidth || gl.drawingBufferHeight !== canvasHeight) {
+      log.warn(`Device pixel ratio clamped`)();
+      clampedPixelRatio = Math.min(
+        gl.drawingBufferWidth / clientWidth,
+        gl.drawingBufferHeight / clientHeight
+      );
+
+      gl.canvas.width = Math.floor(clientWidth * clampedPixelRatio);
+      gl.canvas.height = Math.floor(clientHeight * clampedPixelRatio);
+    }
+
+    Object.assign(contextState._canvasSizeInfo, {clientWidth, clientHeight, devicePixelRatio});
+  }
+}
+
+
+// PRIVATE
+
+function scalePixels(pixel, ratio, width, height, yInvert) {
+  const x = scaleX(pixel[0], ratio, width);
+  let y = scaleY(pixel[1], ratio, height, yInvert);
+
+  // Find boundaries of next pixel to provide valid range of device pixel locaitons
+
+  let t = scaleX(pixel[0] + 1, ratio, width);
+  // If next pixel's position is clamped to boundary, use it as is, otherwise subtract 1 for current pixel boundary
+  const xHigh = t === width - 1 ? t : t - 1;
+
+  t = scaleY(pixel[1] + 1, ratio, height, yInvert);
+  let yHigh;
+  if (yInvert) {
+    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
+    t = t === 0 ? t : t + 1;
+    // swap y and yHigh
+    yHigh = y;
+    y = t;
+  } else {
+    // If next pixel's position is clamped to boundary, use it as is, otherwise clamp it to valid range
+    yHigh = t === height - 1 ? t : t - 1;
+    // y remains same
+  }
+  return {
+    x,
+    y,
+    // when ratio < 1, current css pixel and next css pixel may point to same device pixel, set width/height to 1 in those cases.
+    width: Math.max(xHigh - x + 1, 1),
+    height: Math.max(yHigh - y + 1, 1)
+  };
+}
+
+function scaleX(x, ratio, width) {
+  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
+  const r = Math.min(Math.round(x * ratio), width - 1);
+  return r;
+}
+
+function scaleY(y, ratio, height, yInvert) {
+  // since we are rounding to nearest, when ratio > 1, edge pixels may point to out of bounds value, clamp to the limit
+  return yInvert
+    ? Math.max(0, height - 1 - Math.round(y * ratio))
+    : Math.min(Math.round(y * ratio), height - 1);
+}

package/src/context/context/get-canvas.ts

@@ -0,0 +1,37 @@
+// luma.gl, MIT license
+import {isBrowser} from 'probe.gl/env';
+const isPage = isBrowser() && typeof document !== 'undefined';
+
+/**
+ * Creates a new canvas or returns the HTML element for a canvas.
+ * @param width
+ * @param height
+ * @returns
+ */
+export function getCanvas(options: {
+  canvas?: string | HTMLCanvasElement | OffscreenCanvas,
+  width: number,
+  height: number
+}): HTMLCanvasElement | OffscreenCanvas {
+  const {canvas, width = 800, height = 600} = options;
+
+  if (!canvas) {
+    const targetCanvas = document.createElement('canvas');
+    targetCanvas.id = 'lumagl-canvas';
+    targetCanvas.style.width = Number.isFinite(width) ? `${width}px` : '100%';
+    targetCanvas.style.height = Number.isFinite(height) ? `${height}px` : '100%';
+    document.body.insertBefore(targetCanvas, document.body.firstChild);
+    return targetCanvas;
+  }
+
+  if (typeof canvas === 'string') {
+    const isPageLoaded = isPage && document.readyState === 'complete';
+    if (!isPageLoaded) {
+      throw new Error(`createGLContext called on canvas '${canvas}' before page was loaded`);
+    }
+    // TODO - check type?
+    return document.getElementById(canvas) as HTMLCanvasElement;
+  }
+
+  return canvas;
+}

package/src/context/context/resize-context.ts

@@ -0,0 +1,37 @@
+// luma.gl, MIT license
+import { getDevicePixelRatio, setDevicePixelRatio } from "./device-pixels";
+/**
+ * Resize the canvas' drawing buffer.
+ *
+ * Can match the canvas CSS size, and optionally also consider devicePixelRatio
+ * Can be called every frame
+ *
+ * Regardless of size, the drawing buffer will always be scaled to the viewport, but
+ * for best visual results, usually set to either:
+ *  canvas CSS width x canvas CSS height
+ *  canvas CSS width * devicePixelRatio x canvas CSS height * devicePixelRatio
+ * See http://webgl2fundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
+ *
+ * resizeGLContext(gl, {width, height, useDevicePixels})
+ */
+ export function resizeGLContext(
+  gl: WebGLRenderingContext,
+  options?: {
+    width?: number;
+    height?: number;
+    useDevicePixels?: boolean | number;
+  }
+) {
+  // Resize browser context .
+  if (gl.canvas) {
+    const devicePixelRatio = getDevicePixelRatio(options?.useDevicePixels);
+    setDevicePixelRatio(gl, devicePixelRatio, options);
+    return;
+  }
+
+  // Resize headless gl context
+  const ext = gl.getExtension('STACKGL_resize_drawingbuffer');
+  if (ext && options && `width` in options && `height` in options) {
+    ext.resize(options.width, options.height);
+  }
+}

package/src/context/context/webgl-checks.ts

@@ -0,0 +1,49 @@
+// luma.gl, MIT license
+import {assert} from '@luma.gl/api';
+
+const ERR_CONTEXT = 'Invalid WebGLRenderingContext';
+export const ERR_WEBGL = ERR_CONTEXT;
+export const ERR_WEBGL2 = 'Requires WebGL2';
+
+
+/** Check if supplied parameter is a WebGLRenderingContext */
+export function isWebGL(gl: any): boolean {
+  if (typeof WebGLRenderingContext !== 'undefined' && gl instanceof WebGLRenderingContext) {
+    return true;
+  }
+  if (typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext) {
+    return true;
+  }
+  // Look for debug contexts, headless gl etc
+  return Boolean(gl && Number.isFinite(gl._version));
+}
+
+
+/** Check if supplied parameter is a WebGL2RenderingContext */
+export function isWebGL2(gl: any): boolean {
+  if (typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext) {
+    return true;
+  }
+  // Look for debug contexts, headless gl etc
+  return Boolean(gl && gl._version === 2);
+}
+
+
+/** Returns a properly typed WebGL2RenderingContext from a WebGL1 context, or null */
+export function getWebGL2Context(gl: WebGLRenderingContext): WebGL2RenderingContext | null {
+  // @ts-expect-error
+  return isWebGL2(gl) ? gl : null;
+}
+
+
+/** Throw if supplied parameter is not a WebGLRenderingContext, otherwise return properly typed value */
+export function assertWebGLContext(gl: any): WebGLRenderingContext {
+  assert(isWebGL(gl), ERR_CONTEXT);
+  return gl;
+}
+
+/** Throw if supplied parameter is not a WebGL2RenderingContext, otherwise return properly typed value */
+export function assertWebGL2Context(gl: any): WebGL2RenderingContext {
+  assert(isWebGL2(gl), ERR_WEBGL2);
+  return gl;
+}

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

@@ -0,0 +1,127 @@
+// 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 {
+  GL_PARAMETER_DEFAULTS,
+  GL_PARAMETER_SETTERS,
+  GL_COMPOSITE_PARAMETER_SETTERS,
+  GL_PARAMETER_GETTERS
+} from './webgl-parameter-tables';
+
+import {isWebGL} from '../context/webgl-checks';
+
+export type {GLParameters};
+
+/**
+ * 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 setParameters(gl: WebGLRenderingContext, parameters: GLParameters): void {
+  assert(isWebGL(gl), 'setParameters requires a WebGL context');
+
+  if (isObjectEmpty(parameters)) {
+    return;
+  }
+
+  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?
+}
+
+/**
+ * Reads the entire WebGL state from a context
+ * @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 getParameters(gl: WebGLRenderingContext, parameters?: Record<keyof GLParameters, any>): GLParameters;
+ export function getParameters(gl: WebGLRenderingContext, parameters: number): any;
+
+export function getParameters(gl, parameters) {
+  // default to querying all parameters
+  parameters = 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;
+}
+
+/**
+ * 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 resetParameters(gl: WebGLRenderingContext): void {
+  setParameters(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;
+}