@luma.gl/webgl 9.0.0-alpha.5 → 9.0.0-alpha.51

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

@@ -0,0 +1,51 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+const ERR_HEADLESSGL_FAILED =
+  'Failed to create WebGL context in Node.js, headless gl returned null';
+
+const ERR_HEADLESSGL_LOAD = '\
+  luma.gl: loaded under Node.js without headless gl installed, meaning that WebGL \
+  contexts can not be created. This may not be an error. For example, this is a \
+  typical configuration for isorender applications running on the server.';
+
+const CONTEXT_DEFAULTS = {
+  width: 1,
+  height: 1,
+  debug: true,
+  throwOnError: false
+};
+
+/** Duck typing for the main headless gl export, a function to create contexts */
+export type HeadlessGL = (width: number, height: number, options: Record<string, unknown>) => WebGLRenderingContext;
+
+let headlessGL: HeadlessGL | null = null; 
+
+/** By importing `gl` and registering it with this function, contexts can be created under Node.js */
+export function registerHeadlessGL(headlessgl: HeadlessGL) {
+  headlessGL = headlessgl;
+}
+
+/** @returns true if headless gl is registered */
+export function isHeadlessGLRegistered(): boolean {
+  return headlessGL !== null;
+}
+
+/** Create headless gl context (for running under Node.js) */
+export function createHeadlessContext(options?: Record<string, any>): WebGLRenderingContext {
+  options = {...CONTEXT_DEFAULTS, ...options};
+
+  const {width, height, webgl1, webgl2} = options;
+
+  if (webgl2 && !webgl1) {
+    throw new Error('headless-gl does not support WebGL2');
+  }
+  if (!headlessGL) {
+    throw new Error(ERR_HEADLESSGL_LOAD);
+  }
+  const gl = headlessGL(width, height, options);
+  if (!gl) {
+    throw new Error(ERR_HEADLESSGL_FAILED);
+  }
+  return gl;
+}

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

@@ -1,5 +1,7 @@
 // luma.gl, MIT license
-import {assert} from '@luma.gl/api';
+// Copyright (c) vis.gl contributors
+
+import {assert} from '@luma.gl/core';
 
 const ERR_CONTEXT = 'Invalid WebGLRenderingContext';
 export const ERR_WEBGL = ERR_CONTEXT;

package/src/context/debug/spector.ts

@@ -1,5 +1,7 @@
 // luma.gl, MIT license
-import {log, loadScript} from '@luma.gl/api';
+// Copyright (c) vis.gl contributors
+
+import {log, loadScript} from '@luma.gl/core';
 
 /** Spector debug initialization options */
 type SpectorProps = {
@@ -23,6 +25,7 @@ let spector: any = null;
 let initialized: boolean = false;
 
 declare global {
+  // eslint-disable-next-line no-var
   var SPECTOR: any;
 }
 
@@ -32,7 +35,7 @@ export async function loadSpectorJS(props?: SpectorProps) {
     try {
       await loadScript(SPECTOR_CDN_URL);
     } catch(error) {
-      log.warn(error)
+      log.warn(String(error))
     }
   }
 }
@@ -44,7 +47,7 @@ export function initializeSpectorJS(props?: SpectorProps) {
   }
 
   if (!spector && globalThis.SPECTOR) {
-    log.probe(LOG_LEVEL, "SPECTOR found and initialized")();
+    log.probe(LOG_LEVEL, 'SPECTOR found and initialized')();
     spector = new globalThis.SPECTOR.Spector();
     if (globalThis.luma) {
       globalThis.luma.spector = spector;
@@ -61,9 +64,9 @@ export function initializeSpectorJS(props?: SpectorProps) {
     // enables recording some extra information merged in the capture like texture memory sizes and formats
     spector.spyCanvases();
     // A callback when results are ready
-    spector?.onCaptureStarted.add((capture: unknown) => log.info(`Spector capture started:`, capture)());
+    spector?.onCaptureStarted.add((capture: unknown) => log.info('Spector capture started:', capture)());
     spector?.onCapture.add((capture: unknown) => {
-      log.info(`Spector capture complete:`, capture)();
+      log.info('Spector capture complete:', capture)();
       // Use undocumented Spector API to open the UI with our capture
       // See https://github.com/BabylonJS/Spector.js/blob/767ad1195a25b85a85c381f400eb50a979239eca/src/spector.ts#L124
       spector?.getResultUI()
@@ -82,7 +85,7 @@ export function initializeSpectorJS(props?: SpectorProps) {
     // spector?.captureCanvas(props?.canvas);
     spector?.startCapture(props?.canvas, 500); // 500 commands
     new Promise(resolve => setTimeout(resolve, 2000)).then(_ => {
-      log.info(`Spector capture stopped after 2 seconds`)();
+      log.info('Spector capture stopped after 2 seconds')();
       spector?.stopCapture();
       // spector?.displayUI();
     });

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

@@ -1,6 +1,9 @@
 // luma.gl, MIT license
-import {log, loadScript} from '@luma.gl/api/';
-import GL from '@luma.gl/constants';
+// Copyright (c) vis.gl contributors
+
+import {log, loadScript} from '@luma.gl/core';
+import {GL} 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';
 
@@ -11,20 +14,26 @@ type DebugContextProps = {
   webgl2?: boolean;
 };
 
-const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
-  debug: true,
-  throwOnError: false,
-  break: undefined,
-  webgl2: false,
+// const DEFAULT_DEBUG_CONTEXT_PROPS: Required<DebugContextProps> = {
+//   debug: true,
+//   throwOnError: false,
+//   break: [],
+//   webgl2: false,
+// }
+
+type ContextData = {
+  realContext?: WebGLRenderingContext;
+  debugContext?: WebGLRenderingContext;
 }
 
 // Helper to get shared context data
-function getContextData(gl: any) {
+function getContextData(gl: any): ContextData {
   gl.luma = gl.luma || {};
   return gl.luma;
 }
 
 declare global {
+  // eslint-disable-next-line no-var
   var WebGLDebugUtils: any;
 }
 
@@ -35,8 +44,7 @@ declare global {
  * @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 +54,7 @@ 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 {
+export function makeDebugContext(gl: WebGLRenderingContext, props: DebugContextProps = {}): WebGLRenderingContext | 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;
@@ -133,16 +141,16 @@ 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 {
-  let functionString: string;
+  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 GL 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/parameters/unified-parameter-api.ts

@@ -1,8 +1,11 @@
+// luma.gl, MIT license
+// 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 {Device} from '@luma.gl/core';
+import type {GLParameters} from '@luma.gl/constants';
 import {
   GL_PARAMETER_DEFAULTS,
   GL_PARAMETER_SETTERS,
@@ -10,8 +13,7 @@ import {
   GL_PARAMETER_GETTERS
 } from './webgl-parameter-tables';
 
-import {isWebGL} from '../context/webgl-checks';
-import WebGLDevice from '../../adapter/webgl-device';
+import {WebGLDevice} from '../../adapter/webgl-device';
 
 export type {GLParameters};
 
@@ -21,7 +23,10 @@ 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 {
+export function setGLParameters(
+  device: Device | WebGLRenderingContext,
+  parameters: GLParameters
+): void {
   const webglDevice = WebGLDevice.attach(device);
   const gl = webglDevice.gl;
 
@@ -74,7 +79,10 @@ export function setParameters(device: Device | WebGLRenderingContext, parameters
 
 /**
  * Reads the entire WebGL state from a context
- * @returns - a newly created map, with values keyed by GL parameters
+
+  // default to querying all parameters
+
+  * @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
@@ -83,13 +91,13 @@ export function setParameters(device: Device | WebGLRenderingContext, parameters
  * 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?: (keyof GLParameters)[]): GLParameters;
-export function getParameters(gl: WebGLRenderingContext, parameters: keyof GLParameters): GLParameters;
+export function getGLParameters(
+  device: Device | WebGLRenderingContext,
+  parameters: keyof GLParameters | (keyof GLParameters)[] | GLParameters = GL_PARAMETER_DEFAULTS
+): GLParameters {
+  const webglDevice = WebGLDevice.attach(device);
+  const gl = webglDevice.gl;
 
-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') {
@@ -115,14 +123,15 @@ export function getParameters(gl, parameters) {
  * 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(device: Device | WebGLRenderingContext): void {
+  setGLParameters(device, 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;
   }