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

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

@@ -1,6 +1,11 @@
-// luma.gl, MIT license
-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';
 
@@ -8,35 +13,39 @@ type DebugContextProps = {
   debug?: boolean;
   throwOnError?: boolean;
   break?: string[];
-  webgl2?: boolean;
 };
 
-const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
-  debug: true,
-  throwOnError: false,
-  break: [],
-  webgl2: false,
-}
+// const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
+//   debug: true,
+//   throwOnError: false,
+//   break: [],
+//   webgl2: false,
+// }
+
+type ContextData = {
+  realContext?: WebGL2RenderingContext;
+  debugContext?: WebGL2RenderingContext;
+};
 
 // Helper to get shared context data
-function getContextData(gl: any) {
+function getWebGLContextData(gl: any): ContextData {
   gl.luma = gl.luma || {};
   return gl.luma;
 }
 
 declare global {
+  // eslint-disable-next-line no-var
   var WebGLDebugUtils: any;
 }
 
 /**
- * Loads Khronos WebGLDeveloperTools from CDN if not already installed 
+ * 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
+  if (isBrowser() && !globalThis.WebGLDebugUtils) {
     globalThis.global = globalThis.global || globalThis;
     // @ts-expect-error Developer tools expects global to be set
     globalThis.global.module = {};
@@ -46,7 +55,10 @@ export async function loadWebGLDeveloperTools(): Promise<void> {
 
 // 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 | null {
+export function makeDebugContext(
+  gl: WebGL2RenderingContext,
+  props: DebugContextProps = {}
+): WebGL2RenderingContext | null {
   // Return null to ensure we don't try to create a context in this case (TODO what case is that?)
   if (!gl) {
     return null;
@@ -56,20 +68,23 @@ export function makeDebugContext(gl: WebGLRenderingContext, props: DebugContextP
 }
 
 // Returns the real context from either of the real/debug contexts
-function getRealContext(gl: WebGLRenderingContext): WebGLRenderingContext {
-  const data = getContextData(gl);
+function getRealContext(gl: WebGL2RenderingContext): WebGL2RenderingContext {
+  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: WebGLRenderingContext, props: DebugContextProps): WebGLRenderingContext {
+function getDebugContext(
+  gl: WebGL2RenderingContext,
+  props: DebugContextProps
+): WebGL2RenderingContext {
   if (!globalThis.WebGLDebugUtils) {
     log.warn('webgl-debug not loaded')();
     return gl;
   }
 
-  const data = getContextData(gl);
+  const data = getWebGLContextData(gl);
 
   // If this already has a debug context, return it.
   if (data.debugContext) {
@@ -77,7 +92,7 @@ function getDebugContext(gl: WebGLRenderingContext, props: DebugContextProps): W
   }
 
   // Create a new debug context
-  globalThis.WebGLDebugUtils.init({...GL, ...gl});
+  globalThis.WebGLDebugUtils.init({...GLEnum, ...gl});
   const glDebug = globalThis.WebGLDebugUtils.makeDebugContext(
     gl,
     onGLError.bind(null, props),
@@ -85,12 +100,12 @@ function getDebugContext(gl: WebGLRenderingContext, props: DebugContextProps): W
   );
 
   // 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];
+  for (const key in GLEnum) {
+    if (!(key in glDebug) && typeof GLEnum[key] === 'number') {
+      glDebug[key] = GLEnum[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.
@@ -111,7 +126,7 @@ function getDebugContext(gl: WebGLRenderingContext, props: DebugContextProps): W
 
 function getFunctionString(functionName: string, functionArgs): string {
   // Cover bug in webgl-debug-tools
-  functionArgs = Array.from(functionArgs).map(arg => arg === undefined ? 'undefined' : arg);
+  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})`;
@@ -119,11 +134,10 @@ function getFunctionString(functionName: string, functionArgs): string {
 
 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);
+  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})`;
+  const message = `${errorMessage} in gl.${functionName}(${functionArgs})`;
   log.error(message)();
   debugger; // eslint-disable-line
   if (props.throwOnError) {
@@ -132,17 +146,23 @@ function onGLError(props: DebugContextProps, err, functionName: string, args: an
 }
 
 // Don't generate function string until it is needed
-function onValidateGLFunc(props: DebugContextProps, functionName: string, functionArgs: any[]): void {
+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) {
+  // 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 && props.break.every((breakOn: string) => functionString.indexOf(breakOn) !== -1);
+    const isBreakpoint = props.break.every(
+      (breakOn: string) => functionString.indexOf(breakOn) !== -1
+    );
     if (isBreakpoint) {
       debugger; // eslint-disable-line
     }

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

@@ -0,0 +1,116 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * 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; // 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')
+};
+
+/**
+ * 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
+): 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;
+
+  // props.failIfMajorPerformanceCaveat = true;
+
+  // We require webgl2 context
+  gl ||= canvas.getContext('webgl2', props) as WebGL2RenderingContext;
+
+  // 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: 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
+    );
+  }
+
+  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/src/context/helpers/webgl-context-data.ts

@@ -0,0 +1,31 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * 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 function getWebGLContextData(gl: WebGL2RenderingContext): WebGLContextData {
+  // @ts-expect-error
+  const luma = gl.luma as WebGLContextData | null;
+  if (!luma) {
+    const contextState: WebGLContextData = {
+      _polyfilled: false,
+      _extensions: {}
+    };
+    // @ts-expect-error
+    gl.luma = contextState;
+  }
+
+  // @ts-expect-error
+  return gl.luma;
+}

package/src/context/helpers/webgl-extensions.ts

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

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

@@ -1,8 +1,11 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
 // 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 {Device} from '@luma.gl/api';
-import type {GLParameters} from '../../types/webgl';
+import type {GLParameters} from '@luma.gl/constants';
 import {
   GL_PARAMETER_DEFAULTS,
   GL_PARAMETER_SETTERS,
@@ -10,9 +13,6 @@ import {
   GL_PARAMETER_GETTERS
 } from './webgl-parameter-tables';
 
-import {isWebGL} from '../context/webgl-checks';
-import WebGLDevice from '../../adapter/webgl-device';
-
 export type {GLParameters};
 
 /**
@@ -21,13 +21,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 function setParameters(
-  device: Device | WebGLRenderingContext,
-  parameters: GLParameters
-): void {
-  const webglDevice = WebGLDevice.attach(device);
-  const gl = webglDevice.gl;
-
+export function setGLParameters(gl: WebGL2RenderingContext, parameters: GLParameters): void {
   if (isObjectEmpty(parameters)) {
     return;
   }
@@ -89,8 +83,8 @@ export function setParameters(
  * 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,
+export function getGLParameters(
+  gl: WebGL2RenderingContext,
   parameters: keyof GLParameters | (keyof GLParameters)[] | GLParameters = GL_PARAMETER_DEFAULTS
 ): GLParameters {
   // support both arrays of parameters and objects (keys represent parameters)
@@ -118,14 +112,15 @@ export function getParameters(
  * 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);
+export function resetGLParameters(gl: WebGL2RenderingContext): void {
+  setGLParameters(gl, GL_PARAMETER_DEFAULTS);
 }
 
 // Helpers
 
 // Returns true if given object is empty, false otherwise.
 function isObjectEmpty(object) {
+  // @ts-ignore dummy key variable
   for (const key in object) {
     return false;
   }