@luma.gl/webgl 9.2.0-alpha.1 → 9.2.0-alpha.3

package/src/adapter/webgl-adapter.ts

@@ -45,7 +45,8 @@ export class WebGLAdapter extends Adapter {
 
   /**
    * Get a device instance from a GL context
-   * Creates and instruments the device if not already created
+   * Creates a WebGLCanvasContext against the contexts canvas
+   * @note autoResize will be disabled, assuming that whoever created the external context will be handling resizes.
    * @param gl
    * @returns
    */
@@ -62,51 +63,58 @@ export class WebGLAdapter extends Adapter {
     if (!isWebGL(gl)) {
       throw new Error('Invalid WebGL2RenderingContext');
     }
-    return new WebGLDevice({_handle: gl as WebGL2RenderingContext});
+
+    // We create a new device using the provided WebGL context and its canvas
+    // Assume that whoever created the external context will be handling resizes.
+    return new WebGLDevice({
+      _handle: gl,
+      createCanvasContext: {canvas: gl.canvas, autoResize: false}
+    });
   }
 
   async create(props: DeviceProps = {}): Promise<WebGLDevice> {
     const {WebGLDevice} = await import('./webgl-device');
 
     log.groupCollapsed(LOG_LEVEL, 'WebGLDevice created')();
+    try {
+      const promises: Promise<unknown>[] = [];
 
-    const promises: Promise<unknown>[] = [];
-
-    // Load webgl and spector debug scripts from CDN if requested
-    if (props.debugWebGL || props.debug) {
-      promises.push(loadWebGLDeveloperTools());
-    }
+      // Load webgl and spector debug scripts from CDN if requested
+      if (props.debugWebGL || props.debug) {
+        promises.push(loadWebGLDeveloperTools());
+      }
 
-    if (props.debugSpectorJS) {
-      promises.push(loadSpectorJS(props));
-    }
+      if (props.debugSpectorJS) {
+        promises.push(loadSpectorJS(props));
+      }
 
-    // Wait for all the loads to settle before creating the context.
-    // The Device.create() functions are async, so in contrast to the constructor, we can `await` here.
-    const results = await Promise.allSettled(promises);
-    for (const result of results) {
-      if (result.status === 'rejected') {
-        log.error(`Failed to initialize debug libraries ${result.reason}`)();
+      // Wait for all the loads to settle before creating the context.
+      // The Device.create() functions are async, so in contrast to the constructor, we can `await` here.
+      const results = await Promise.allSettled(promises);
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          log.error(`Failed to initialize debug libraries ${result.reason}`)();
+        }
       }
-    }
 
-    const device = new WebGLDevice(props);
+      const device = new WebGLDevice(props);
 
-    // Log some debug info about the newly created context
-    const message = `\
-Created ${device.type}${device.debug ? ' debug' : ''} context: \
+      // Log some debug info about the newly created context
+      const message = `\
+${device._reused ? 'Reusing' : 'Created'} device with WebGL2 ${device.props.debug ? 'debug ' : ''}context: \
 ${device.info.vendor}, ${device.info.renderer} for canvas: ${device.canvasContext.id}`;
-    log.probe(LOG_LEVEL, message)();
-    log.table(LOG_LEVEL, device.info)();
+      log.probe(LOG_LEVEL, message)();
+      log.table(LOG_LEVEL, device.info)();
 
-    log.groupEnd(LOG_LEVEL)();
-
-    return device;
+      return device;
+    } finally {
+      log.groupEnd(LOG_LEVEL)();
+    }
   }
 }
 
 /** Check if supplied parameter is a WebGL2RenderingContext */
-function isWebGL(gl: any): boolean {
+function isWebGL(gl: any): gl is WebGL2RenderingContext {
   if (typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext) {
     return true;
   }

package/src/adapter/webgl-device.ts

@@ -29,7 +29,8 @@ import type {
   CommandEncoderProps,
   TransformFeedbackProps,
   QuerySetProps,
-  Resource
+  Resource,
+  VertexFormat
 } from '@luma.gl/core';
 import {Device, CanvasContext, log} from '@luma.gl/core';
 import type {GLExtensions} from '@luma.gl/constants';
@@ -73,25 +74,25 @@ export class WebGLDevice extends Device {
   /** type of this device */
   readonly type = 'webgl';
 
+  // Use the ! assertion to handle the case where _reuseDevices causes the constructor to return early
   /** The underlying WebGL context */
-  readonly handle: WebGL2RenderingContext;
-  features: WebGLDeviceFeatures;
-  limits: WebGLDeviceLimits;
-  readonly info: DeviceInfo;
-  readonly canvasContext: WebGLCanvasContext;
+  readonly handle!: WebGL2RenderingContext;
+  features!: WebGLDeviceFeatures;
+  limits!: WebGLDeviceLimits;
+  readonly info!: DeviceInfo;
+  readonly canvasContext!: WebGLCanvasContext;
 
   readonly preferredColorFormat = 'rgba8unorm';
   readonly preferredDepthFormat = 'depth24plus';
 
-  commandEncoder: WEBGLCommandEncoder;
+  commandEncoder!: WEBGLCommandEncoder;
 
   readonly lost: Promise<{reason: 'destroyed'; message: string}>;
 
   private _resolveContextLost?: (value: {reason: 'destroyed'; message: string}) => void;
 
   /** WebGL2 context. */
-  readonly gl: WebGL2RenderingContext;
-  readonly debug: boolean = false;
+  readonly gl!: WebGL2RenderingContext;
 
   /** Store constants */
   // @ts-ignore TODO fix
@@ -102,26 +103,42 @@ export class WebGLDevice extends Device {
   _polyfilled: boolean = false;
 
   /** Instance of Spector.js (if initialized) */
-  spectorJS: Spector | null;
+  spectorJS!: Spector | null;
 
   //
   // Public API
   //
 
+  override get [Symbol.toStringTag](): string {
+    return 'WebGLDevice';
+  }
+
   override toString(): string {
     return `${this[Symbol.toStringTag]}(${this.id})`;
   }
 
+  override isVertexFormatSupported(format: VertexFormat): boolean {
+    switch (format) {
+      case 'unorm8x4-bgra':
+        return false;
+      default:
+        return true;
+    }
+  }
+
   constructor(props: DeviceProps) {
     super({...props, id: props.id || uid('webgl-device')});
 
+    const canvasContextProps = Device._getCanvasContextProps(props)!;
+
     // WebGL requires a canvas to be created before creating the context
-    if (!props.createCanvasContext) {
+    if (!canvasContextProps) {
       throw new Error('WebGLDevice requires props.createCanvasContext to be set');
     }
-    const canvasContextProps = props.createCanvasContext === true ? {} : props.createCanvasContext;
 
-    // If attaching to an already attached context, return the attached device
+    // Check if the WebGL context is already associated with a device
+    // Note that this can be avoided in webgl2adapter.create() if
+    // DeviceProps._reuseDevices is set.
     // @ts-expect-error device is attached to context
     let device: WebGLDevice | undefined = canvasContextProps.canvas?.gl?.device;
     if (device) {
@@ -144,27 +161,43 @@ export class WebGLDevice extends Device {
       webglContextAttributes.powerPreference = props.powerPreference;
     }
 
-    const gl = createBrowserContext(
-      this.canvasContext.canvas,
-      {
-        onContextLost: (event: Event) =>
-          this._resolveContextLost?.({
-            reason: 'destroyed',
-            message: 'Entered sleep mode, or too many apps or browser tabs are using the GPU.'
-          }),
-        // eslint-disable-next-line no-console
-        onContextRestored: (event: Event) => console.log('WebGL context restored')
-      },
-      webglContextAttributes
-    );
+    // Check if we should attach to an externally created context or create a new context
+    const externalGLContext = this.props._handle as WebGL2RenderingContext | null;
+
+    const gl =
+      externalGLContext ||
+      createBrowserContext(
+        this.canvasContext.canvas,
+        {
+          onContextLost: (event: Event) =>
+            this._resolveContextLost?.({
+              reason: 'destroyed',
+              message: 'Entered sleep mode, or too many apps or browser tabs are using the GPU.'
+            }),
+          // eslint-disable-next-line no-console
+          onContextRestored: (event: Event) => console.log('WebGL context restored')
+        },
+        webglContextAttributes
+      );
 
     if (!gl) {
       throw new Error('WebGL context creation failed');
     }
 
-    // @ts-expect-error device is attached to context
+    // Note that the browser will only create one WebGL context per canvas.
+    // This means that a newly created gl context may already have a device attached to it.
+    // @ts-expect-error luma.gl stores a device reference on the context.
     device = gl.device;
     if (device) {
+      if (props._reuseDevices) {
+        log.log(
+          1,
+          `Not creating a new Device, instead returning a reference to Device ${device.id} already attached to WebGL context`,
+          device
+        )();
+        device._reused = true;
+        return device;
+      }
       throw new Error(`WebGL context already attached to device ${device.id}`);
     }
 
@@ -178,6 +211,7 @@ export class WebGLDevice extends Device {
 
     // Instrument context
     (this.gl as any).device = this; // Update GL context: Link webgl context back to device
+    // TODO - remove, this is only used to detect debug contexts.
     (this.gl as any)._version = 2; // Update GL context: Store WebGL version field on gl context (HACK to identify debug contexts)
 
     // initialize luma Device fields
@@ -213,10 +247,26 @@ export class WebGLDevice extends Device {
   }
 
   /**
-   * Destroys the context
-   * @note Has no effect for WebGL browser contexts, there is no browser API for destroying contexts
+   * Destroys the device
+   *
+   * @note "Detaches" from the WebGL context unless _reuseDevices is true.
+   *
+   * @note The underlying WebGL context is not immediately destroyed,
+   * but may be destroyed later through normal JavaScript garbage collection.
+   * This is a fundamental limitation since WebGL does not offer any
+   * browser API for destroying WebGL contexts.
    */
-  destroy(): void {}
+  destroy(): void {
+    // Note that deck.gl (especially in React strict mode) depends on being able
+    // to asynchronously create a Device against the same canvas (i.e. WebGL context)
+    // multiple times and getting the same device back. Since deck.gl is not aware
+    // of this sharing, it might call destroy() multiple times on the same device.
+    // Therefore we must do nothing in destroy() if props._reuseDevices is true
+    if (!this.props._reuseDevices && !this._reused) {
+      // Delete the reference to the device that we store on the WebGL context
+      delete (this.gl as any).device;
+    }
+  }
 
   get isLost(): boolean {
     return this.gl.isContextLost();
@@ -224,6 +274,10 @@ export class WebGLDevice extends Device {
 
   // IMPLEMENTATION OF ABSTRACT DEVICE
 
+  getTextureByteAlignment(): number {
+    return 4;
+  }
+
   createCanvasContext(props?: CanvasContextProps): CanvasContext {
     throw new Error('WebGL only supports a single canvas');
   }
@@ -473,7 +527,7 @@ export class WebGLDevice extends Device {
     // @ts-expect-error
     handle.luma = resource;
 
-    const spectorMetadata = {props: options.spector, id: options.spector.id};
+    const spectorMetadata = {props: options.spector, id: options.spector['id']};
     // @ts-expect-error
     // eslint-disable-next-line camelcase
     handle.__SPECTOR_Metadata = spectorMetadata;

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

@@ -131,6 +131,7 @@ function onGLError(
   const errorMessage = globalThis.WebGLDebugUtils.glEnumToString(err);
   const functionArgs = globalThis.WebGLDebugUtils.glFunctionArgsToString(functionName, args);
   const message = `${errorMessage} in gl.${functionName}(${functionArgs})`;
+  // TODO - call device.reportError
   log.error(message)();
   debugger; // eslint-disable-line
   // throw new Error(message);