@luma.gl/webgl 8.6.0-alpha.5 → 9.0.0-alpha.2

package/{dist/esm/classes/accessor.ts.disabled → src/classic/accessor.ts}

@@ -1,23 +1,19 @@
+import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import {getTypedArrayFromGLType} from '../webgl-utils';
-import {checkProps, assert} from '../utils/index';
-import {Buffer} from '@luma.gl/core/';
+import {getTypedArrayFromGLType} from './typed-array-utils';
 
-export interface AccessorObject {
-  buffer?: Buffer;
-  offset?: number;
-  stride?: number;
-  type?: number;
-  size?: number;
-  divisor?: number;
-  normalized?: boolean;
-  integer?: boolean;
-  index?: number;
-  /** @deprecated Use .divisor */
-  instanced?: boolean;
-  /** @deprecated Use .divisor */
-  isInstanced?: boolean;
-}
+// export interface AccessorObject {
+//   offset?: number;
+//   stride?: number;
+//   type?: number;
+//   size?: number;
+//   divisor?: number;
+//   normalized?: boolean;
+//   integer?: boolean;
+
+//   buffer?: Buffer;
+//   index?: number;
+// }
 
 const DEFAULT_ACCESSOR_VALUES = {
   offset: 0,
@@ -36,28 +32,26 @@ const PROP_CHECKS = {
   }
 };
 
+export default class Accessor implements AccessorObject {
+  offset?: number;
+  stride?: number;
+  type?: number;
+  size?: number;
+  divisor?: number;
+  normalized?: boolean;
+  integer?: boolean;
 
-// @ts-nocheck members are added dynamically
-export default class Accessor {
-  // buffer: Buffer | undefined = undefined;
-  // index: number;
-
-  // offset: number;
-  // stride: number;
-  // type: number;
-  // size: number;
-  // divisor: number;
-  // normalized: boolean;
-  // integer: boolean;
+  buffer?: Buffer;
+  index?: number;
 
-  static getBytesPerElement(accessor): number {
+  static getBytesPerElement(accessor: Accessor | AccessorObject): number {
     // TODO: using `FLOAT` when type is not specified,
     // ensure this assumption is valid or force API to specify type.
     const ArrayType = getTypedArrayFromGLType(accessor.type || GL.FLOAT);
     return ArrayType.BYTES_PER_ELEMENT;
   }
 
-  static getBytesPerVertex(accessor): number {
+  static getBytesPerVertex(accessor: AccessorObject): number {
     assert(accessor.size);
     // TODO: using `FLOAT` when type is not specified,
     // ensure this assumption is valid or force API to specify type.
@@ -69,11 +63,11 @@ export default class Accessor {
   // Usually [programAccessor, bufferAccessor, appAccessor]
   // All props will be set in the returned object.
   // TODO check for conflicts between values in the supplied accessors
-  static resolve(...accessors): Accessor {
+  static resolve(...accessors: AccessorObject[]): Accessor {
     return new Accessor(...[DEFAULT_ACCESSOR_VALUES, ...accessors]); // Default values
   }
 
-  constructor(...accessors: any[]) {
+  constructor(...accessors: AccessorObject[]) {
     accessors.forEach((accessor) => this._assign(accessor)); // Merge in sequence
     Object.freeze(this);
   }
@@ -96,7 +90,7 @@ export default class Accessor {
   // PRIVATE
 
   // eslint-disable-next-line complexity, max-statements
-  _assign(props: AccessorObject = {}) {
+  _assign(props: AccessorObject = {}): this {
     props = checkProps('Accessor', props, PROP_CHECKS);
 
     if (props.type !== undefined) {
@@ -104,7 +98,7 @@ export default class Accessor {
 
       // Auto-deduce integer type?
       if (props.type === GL.INT || props.type === GL.UNSIGNED_INT) {
-        this.integer = true;
+      this.integer = true;
       }
     }
     if (props.size !== undefined) {
@@ -116,6 +110,11 @@ export default class Accessor {
     if (props.stride !== undefined) {
       this.stride = props.stride;
     }
+    // @ts-expect-error
+    if (props.normalize !== undefined) {
+      // @ts-expect-error
+      this.normalized = props.normalize;
+    }
     if (props.normalized !== undefined) {
       this.normalized = props.normalized;
     }
@@ -144,13 +143,28 @@ export default class Accessor {
     }
 
     // DEPRECATED
+    // @ts-expect-error
     if (props.instanced !== undefined) {
+      // @ts-expect-error
       this.divisor = props.instanced ? 1 : 0;
     }
+    // @ts-expect-error
     if (props.isInstanced !== undefined) {
+      // @ts-expect-error
       this.divisor = props.isInstanced ? 1 : 0;
     }
 
+    if (this.offset === undefined) delete this.offset;
+    if (this.stride === undefined) delete this.stride;
+    if (this.type === undefined) delete this.type;
+    if (this.size === undefined) delete this.size;
+    if (this.divisor === undefined) delete this.divisor;
+    if (this.normalized === undefined) delete this.normalized;
+    if (this.integer === undefined) delete this.integer;
+  
+    if (this.buffer === undefined) delete this.buffer;
+    if (this.index === undefined) delete this.index;
+  
     return this;
   }
 }

package/src/{classes/webgl-buffer.ts → classic/buffer.ts}

@@ -1,11 +1,13 @@
-import {log, assert, checkProps} from '@luma.gl/api';
-import {Buffer, BufferProps} from '@luma.gl/api';
+import type {Device, BufferProps, TypedArray} from '@luma.gl/api';
+import {Buffer, log, assert, checkProps} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import {getWebGL2Context, assertWebGL2Context} from '../context/context/webgl-checks';
+import {assertWebGL2Context} from '../context/context/webgl-checks';
 import {AccessorObject} from '../types';
 import Accessor from './accessor';
-import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from '../webgl-utils/typed-array-utils';
+import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from './typed-array-utils';
+
 import WebGLDevice from '../adapter/webgl-device';
+import WEBGLBuffer from '../adapter/resources/webgl-buffer';
 
 const DEBUG_DATA_LENGTH = 10;
 
@@ -38,13 +40,32 @@ const PROP_CHECKS_SET_PROPS = {
   removedProps: DEPRECATED_PROPS
 };
 
+function getWEBGLBufferProps(props: ClassicBufferProps | ArrayBufferView | number): BufferProps {
+  // Signature `new Buffer(gl, new Float32Array(...)`
+  if (ArrayBuffer.isView(props)) {
+    return {data: props};
+  }
+
+  // Signature: `new Buffer(gl, 100)`
+  else if (typeof props === 'number') {
+    return {byteLength: props as number};
+  }
+
+  props = checkProps('Buffer', props, PROP_CHECKS_INITIALIZE);
+  const bufferProps = {...props as ClassicBufferProps};
+  if (bufferProps.offset) {
+    bufferProps.byteOffset = bufferProps.offset;
+  }
+  return bufferProps;
+}
+
 /** WebGL Buffer interface */
-export type WebGLBufferProps = BufferProps & {
+export type ClassicBufferProps = BufferProps & {
   handle?: WebGLBuffer;
-  data?: any; // ArrayBufferView;
-  byteLength?: number;
+
   target?: number;
-  usage?: number;
+  webglUsage?: number;
+
   accessor?: AccessorObject;
 
   /** @deprecated */
@@ -58,41 +79,29 @@ export type WebGLBufferProps = BufferProps & {
 }
 
 /** WebGL Buffer interface */
-export default class WEBGLBuffer extends Buffer {
-  readonly device: WebGLDevice;
-  readonly gl: WebGLRenderingContext;
-  readonly gl2: WebGL2RenderingContext | null;
-  readonly handle: WebGLBuffer;
-
-  target: number;
+export default class ClassicBuffer extends WEBGLBuffer {
   usage: number;
-
-  byteLength: number;
-  bytesUsed: number;
-
   accessor: Accessor;
 
-  debugData;
+  constructor(device: Device | WebGLRenderingContext, props?: ClassicBufferProps);
+  constructor(device: Device | WebGLRenderingContext, data: ArrayBufferView | number[]);
+  constructor(device: Device | WebGLRenderingContext, byteLength: number);
 
-  constructor(gl: WebGLRenderingContext, props?: BufferProps);
-  constructor(gl: WebGLRenderingContext, data: ArrayBufferView | number[]);
-  constructor(gl: WebGLRenderingContext, byteLength: number);
+  constructor(device: Device | WebGLRenderingContext, props = {}) {
+    super(WebGLDevice.attach(device), getWEBGLBufferProps(props));
 
-  constructor(gl: WebGLRenderingContext, props = {}) {
-    super(WebGLDevice.attach(gl), props);
+    // Base class initializes
+    // this.initialize(props);
 
-    this.gl = gl;
-    this.gl2 = getWebGL2Context(gl);
-    const handle = typeof props === 'object' ? (props as BufferProps).handle : undefined;
-    this.handle = handle || this.gl.createBuffer();
-
-    // In WebGL1, need to make sure we use GL.ELEMENT_ARRAY_BUFFER when initializing element buffers
-    // otherwise buffer type will lock to generic (non-element) buffer
-    // In WebGL2, we can use GL.COPY_READ_BUFFER which avoids locking the type here
-    // @ts-expect-error
-    this.target = props.target || (this.gl.webgl2 ? GL.COPY_READ_BUFFER : GL.ARRAY_BUFFER);
+    // Deprecated: Merge main props and accessor
+    this.setAccessor(Object.assign({}, props, (props as ClassicBufferProps).accessor));
 
-    this.initialize(props);
+    // infer GL type from supplied typed array
+    if (this.props.data) {
+      const type = getGLTypeFromTypedArray(this.props.data as TypedArray);
+      assert(type);
+      this.setAccessor(new Accessor(this.accessor, {type}));
+    }
 
     Object.seal(this);
   }
@@ -107,13 +116,16 @@ export default class WEBGLBuffer extends Buffer {
     }
   }
 
+  write(data: TypedArray, byteOffset?: number): void {
+    this.subData({data, offset: byteOffset});
+  }
   // returns number of elements in the buffer (assuming that the full buffer is used)
-  getElementCount(accessor = this.accessor): number {
+  getElementCount(accessor: AccessorObject = this.accessor): number {
     return Math.round(this.byteLength / Accessor.getBytesPerElement(accessor));
   }
 
   // returns number of vertices in the buffer (assuming that the full buffer is used)
-  getVertexCount(accessor = this.accessor): number {
+  getVertexCount(accessor: AccessorObject = this.accessor): number {
     return Math.round(this.byteLength / Accessor.getBytesPerVertex(accessor));
   }
 
@@ -121,7 +133,7 @@ export default class WEBGLBuffer extends Buffer {
   // Signature: `new Buffer(gl, {data: new Float32Array(...)})`
   // Signature: `new Buffer(gl, new Float32Array(...))`
   // Signature: `new Buffer(gl, 100)`
-  initialize(props: BufferProps = {}): this {
+  initialize(props: ClassicBufferProps = {}): this {
     // Signature `new Buffer(gl, new Float32Array(...)`
     if (ArrayBuffer.isView(props)) {
       props = {data: props};
@@ -136,7 +148,7 @@ export default class WEBGLBuffer extends Buffer {
     props = checkProps('Buffer', props, PROP_CHECKS_INITIALIZE);
 
     // Initialize member fields
-    this.usage = props.usage || GL.STATIC_DRAW;
+    this.webglUsage = props.webglUsage || GL.STATIC_DRAW;
     this.debugData = null;
 
     // Deprecated: Merge main props and accessor
@@ -152,7 +164,7 @@ export default class WEBGLBuffer extends Buffer {
     return this;
   }
 
-  setProps(props: BufferProps): this {
+  setProps(props: ClassicBufferProps): this {
     props = checkProps('Buffer', props, PROP_CHECKS_SET_PROPS);
 
     if ('accessor' in props) {
@@ -164,11 +176,12 @@ export default class WEBGLBuffer extends Buffer {
 
   // Optionally stores an accessor with the buffer, makes it easier to use it as an attribute later
   // {type, size = 1, offset = 0, stride = 0, normalized = false, integer = false, divisor = 0}
-  setAccessor(accessor): this {
+  setAccessor(accessor: AccessorObject | Accessor): this {
     // NOTE: From luma.gl v7.0, Accessors have an optional `buffer `field
     // (mainly to support "interleaving")
     // To avoid confusion, ensure `buffer.accessor` does not have a `buffer.accessor.buffer` field:
     accessor = Object.assign({}, accessor);
+    // @ts-expect-error
     delete accessor.buffer;
 
     // This new statement ensures that an "accessor object" is re-packaged as an Accessor instance
@@ -181,7 +194,7 @@ export default class WEBGLBuffer extends Buffer {
   // Returns:
   //  `true`: buffer was reallocated, data was cleared
   //  `false`: buffer was big enough, data is intact
-  reallocate(byteLength) {
+  reallocate(byteLength: number): boolean {
     if (byteLength > this.byteLength) {
       this._setByteLength(byteLength);
       return true;
@@ -191,7 +204,7 @@ export default class WEBGLBuffer extends Buffer {
   }
 
   // Update with new data. Reinitializes the buffer
-  setData(props) {
+  setData(props: ClassicBufferProps) {
     return this.initialize(props);
   }
 
@@ -200,14 +213,14 @@ export default class WEBGLBuffer extends Buffer {
   // Offset into buffer
   // WebGL2 only: Offset into srcData
   // WebGL2 only: Number of bytes to be copied
-  subData(props) {
+  subData(options: TypedArray | {data: TypedArray, offset?: number; srcOffset?: number; byteLength?: number, length?: number}) {
     // Signature: buffer.subData(new Float32Array([...]))
-    if (ArrayBuffer.isView(props)) {
-      props = {data: props};
+    if (ArrayBuffer.isView(options)) {
+      options = {data: options};
     }
 
-    const {data, offset = 0, srcOffset = 0} = props;
-    const byteLength = props.byteLength || props.length;
+    const {data, offset = 0, srcOffset = 0} = options;
+    const byteLength = options.byteLength || options.length;
 
     assert(data);
 
@@ -235,7 +248,7 @@ export default class WEBGLBuffer extends Buffer {
   }
 
   /**
-   * Copies part of the data of another buffer into this buffer 
+   * Copies part of the data of another buffer into this buffer
    * @note WEBGL2 ONLY
    */
   copyData(options: {
@@ -318,7 +331,6 @@ export default class WEBGLBuffer extends Buffer {
   bind(options?: {target?: number; index?: any; offset?: number; size: any}): this {
     const {
       target = this.target, // target for the bind operation
-      // @ts-expect-error
       index = this.accessor && this.accessor.index, // index = index of target (indexed bind point)
       offset = 0,
       size
@@ -341,7 +353,6 @@ export default class WEBGLBuffer extends Buffer {
   }
 
   unbind(options?: {target?: any; index?: any}): this {
-    // @ts-expect-error
     const {target = this.target, index = this.accessor && this.accessor.index} = options || {};
     const isIndexedBuffer = target === GL.UNIFORM_BUFFER || target === GL.TRANSFORM_FEEDBACK_BUFFER;
     if (isIndexedBuffer) {
@@ -380,7 +391,7 @@ export default class WEBGLBuffer extends Buffer {
 
     const target = this._getTarget();
     this.gl.bindBuffer(target, this.handle);
-    this.gl.bufferData(target, byteLength, this.usage);
+    this.gl.bufferData(target, byteLength, this.webglUsage);
     this.gl.bufferSubData(target, offset, data);
     this.gl.bindBuffer(target, null);
 
@@ -397,7 +408,7 @@ export default class WEBGLBuffer extends Buffer {
   }
 
   // Allocate a GPU buffer of specified size.
-  _setByteLength(byteLength: number, usage = this.usage): this {
+  _setByteLength(byteLength: number, webglUsage = this.webglUsage): this {
     assert(byteLength >= 0);
 
     this.trackDeallocatedMemory();
@@ -412,10 +423,10 @@ export default class WEBGLBuffer extends Buffer {
 
     const target = this._getTarget();
     this.gl.bindBuffer(target, this.handle);
-    this.gl.bufferData(target, data, usage);
+    this.gl.bufferData(target, data, webglUsage);
     this.gl.bindBuffer(target, null);
 
-    this.usage = usage;
+    this.webglUsage = webglUsage;
     this.debugData = null;
     this.bytesUsed = byteLength;
     this.byteLength = byteLength;
@@ -432,7 +443,7 @@ export default class WEBGLBuffer extends Buffer {
     return this.gl.webgl2 ? GL.COPY_WRITE_BUFFER : this.target;
   }
 
-  _getAvailableElementCount(srcByteOffset) {
+  _getAvailableElementCount(srcByteOffset: number) {
     const ArrayType = getTypedArrayFromGLType(this.accessor.type || GL.FLOAT, {clamped: false});
     const sourceElementOffset = srcByteOffset / ArrayType.BYTES_PER_ELEMENT;
     return this.getElementCount() - sourceElementOffset;
@@ -448,7 +459,7 @@ export default class WEBGLBuffer extends Buffer {
 
   // RESOURCE METHODS
 
-  getParameter(pname) {
+  getParameter(pname: GL): any {
     this.gl.bindBuffer(this.target, this.handle);
     const value = this.gl.getBufferParameter(this.target, pname);
     this.gl.bindBuffer(this.target, null);
@@ -460,23 +471,4 @@ export default class WEBGLBuffer extends Buffer {
   get type() {
     return this.accessor.type;
   }
-
-  get bytes() {
-    log.deprecated('Buffer.bytes', 'Buffer.byteLength')();
-    return this.byteLength;
-  }
-
-  // DEPRECATIONS - v6.0
-  // Deprecated in v6.x, but not warnings not properly implemented
-  setByteLength(byteLength) {
-    log.deprecated('setByteLength', 'reallocate')();
-    return this.reallocate(byteLength);
-  }
-
-  // Deprecated in v6.x, but not warnings not properly implemented
-  updateAccessor(opts) {
-    log.deprecated('updateAccessor(...)', 'setAccessor(new Accessor(buffer.accessor, ...)')();
-    this.accessor = new Accessor(this.accessor, opts);
-    return this;
-  }
 }

package/src/{webgl-utils → classic}/typed-array-utils.ts

@@ -1,4 +1,6 @@
+import {TypedArray} from '@luma.gl/api/types';
 import GL from '@luma.gl/constants';
+import {GLType} from '../types/webgl'
 
 const ERR_TYPE_DEDUCTION = 'Failed to deduce GL constant from typed array';
 
@@ -18,7 +20,7 @@ type TypedArrayConstructor =
  * @param {*} arrayOrType
  * @returns
  */
-export function getGLTypeFromTypedArray(arrayOrType) {
+export function getGLTypeFromTypedArray(arrayOrType: TypedArray): GLType {
   // If typed array, look up constructor
   const type = ArrayBuffer.isView(arrayOrType) ? arrayOrType.constructor : arrayOrType;
   switch (type) {

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

@@ -34,6 +34,8 @@ export function getContextState(gl: WebGLRenderingContext): ContextState {
     // @ts-expect-error
     gl.luma = contextState;
   }
-  // @ts-expect-error
-  return gl.luma;
+  throw new Error('context state without device');
+
+  // // @ts-expect-error
+  // return gl.luma;
 }

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

@@ -17,8 +17,8 @@
 * @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 = {
+  type?: 'webgl' | 'webgl1' | 'webgl2' | string;
   webgl1?: boolean;
   webgl2?: boolean;
   onContextLost?: (event: Event) => void;
@@ -57,6 +57,13 @@ const DEFAULT_CONTEXT_PROPS: ContextProps = {
   // Create the desired context
   let gl = null;
 
+  if (props.type === 'webgl2') {
+    props = {...props, webgl1: false};
+  }
+  if (props.type === 'webgl1') {
+    props = {...props, webgl2: false};
+  }
+
   // Prefer webgl2 over webgl1 if both are acceptable
   if (props.webgl2) {
     gl = gl || canvas.getContext('webgl2', props);
@@ -81,3 +88,23 @@ const DEFAULT_CONTEXT_PROPS: ContextProps = {
 
   return gl;
 }
+
+/* TODO - can we call this asynchronously to catch the error events?
+export async function createBrowserContextAsync(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): Promise<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);
+
+ 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/context/device-pixels.ts

@@ -52,7 +52,7 @@ export function cssToDeviceRatio(gl: WebGLRenderingContext): number {
 }
 
 // use devicePixelRatio to set canvas width and height
-export function setDevicePixelRatio(gl, devicePixelRatio, options: {width?: number, height?: number} = {}) {
+export function setDevicePixelRatio(gl: WebGLRenderingContext, devicePixelRatio: number, 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;
@@ -101,7 +101,12 @@ export function setDevicePixelRatio(gl, devicePixelRatio, options: {width?: numb
 
 // PRIVATE
 
-function scalePixels(pixel, ratio, width, height, yInvert) {
+function scalePixels(pixel: number[], ratio: number, width: number, height: number, yInvert: boolean): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+} {
   const x = scaleX(pixel[0], ratio, width);
   let y = scaleY(pixel[1], ratio, height, yInvert);
 
@@ -133,13 +138,13 @@ function scalePixels(pixel, ratio, width, height, yInvert) {
   };
 }
 
-function scaleX(x, ratio, width) {
+function scaleX(x: number, ratio: number, width: number): number {
   // 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) {
+function scaleY(y: number, ratio: number, height: number, yInvert: boolean): number {
   // 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))

package/src/context/debug/spector.ts

@@ -0,0 +1,92 @@
+// luma.gl, MIT license
+import {log, loadScript} from '@luma.gl/api';
+
+/** Spector debug initialization options */
+type SpectorProps = {
+  /** Canvas to monitor */
+  canvas?: HTMLCanvasElement | OffscreenCanvas;
+  /** Whether debug is enabled. Auto-detected if ommitted */
+  debug?: boolean;
+  /** Whether spector is disabled */
+  spector?: boolean | string | object;
+};
+
+const DEFAULT_SPECTOR_PROPS: SpectorProps = {
+  spector: log.get('spector') || log.get('inspect')
+};
+
+// https://github.com/BabylonJS/Spector.js#basic-usage
+const SPECTOR_CDN_URL = 'https://spectorcdn.babylonjs.com/spector.bundle.js';
+const LOG_LEVEL = 1;
+
+let spector: any = null;
+let initialized: boolean = false;
+
+declare global {
+  var SPECTOR: any;
+}
+
+/** Loads spector from CDN if not already installed */
+export async function loadSpectorJS(props?: SpectorProps) {
+  if (!globalThis.SPECTOR) {
+    try {
+      await loadScript(SPECTOR_CDN_URL);
+    } catch(error) {
+      log.warn(error)
+    }
+  }
+}
+
+export function initializeSpectorJS(props?: SpectorProps) {
+  props = {...DEFAULT_SPECTOR_PROPS, ...props};
+  if (!props?.spector) {
+    return null;
+  }
+
+  if (!spector && globalThis.SPECTOR) {
+    log.probe(LOG_LEVEL, "SPECTOR found and initialized")();
+    spector = new globalThis.SPECTOR.Spector();
+    if (globalThis.luma) {
+      globalThis.luma.spector = spector;
+    }
+  }
+
+  if (!spector) {
+    return null;
+  }
+
+  if (!initialized) {
+    initialized = true;
+
+    // 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?.onCapture.add((capture: unknown) => {
+      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()
+      spector?.resultView.display();
+      spector?.resultView.addCapture(capture)
+    });
+  }
+
+  if (props?.canvas) {
+    // @ts-expect-error If spector is specified as a canvas id, only monitor that canvas
+    if (typeof props.spector === 'string' && props.spector !== props.canvas.id) {
+      return spector;
+    }
+
+    // capture startup
+    // 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`)();
+      spector?.stopCapture();
+      // spector?.displayUI();
+    });
+  }
+
+  return spector;
+}