chore(core) new device props api

docs/api-reference/core/device.md

@@ -54,18 +54,44 @@ console.error(message);
 
 | Parameter                       | Default            | Description                                                                                                               |
 | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `type`                          | `'best-available'` | `'webgpu'`, `'webgl'`, `'best-available'`                                                                                 |
-| `canvas`                        | N/A                | A _string_ `id` of an existing HTML element or a _DOMElement_. If not provided, a new canvas will be created.             |
-| priority.                       |
-| `debug?: boolean`               | `false`            | WebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions.                       |
-| `break?: string[]`              | `[]`               | Insert a break point (`debugger`) if one of the listed gl functions is called.                                            |
+| `id?: string`                   | `null`             |                                                                                                                           |
+| `canvas?: HTMLCanvasElement | OffscreenCanvas | string` | N/A           | A _string_ `id` or object of an existing canvas element. If not provided, a new canvas will be created.|
+| `container?: HTMLElement | string` | N/A             | If new canvas is created, it will be created in the specified container, otherwise appended to body.                      |
+| `width?: number`                | `800`              | Sets the canvas width. Only used when creating a new canvas internally.                                                   |
+| `height?: number`               | `600`              | Sets the canvas height. Only used when creating a new canvas internally.                                                  |
+| `onError?: (error: Error) => unknown` | `log.error`  | Error handling.                                                                                                           |
+| `initalizeFeatures?: boolean`   | `true`             | Initialize all features on startup.                                                                                       |
+| `disabledFeatures?: Partial<Record<DeviceFeature, boolean>>` | `{ 'compilation-status-async-webgl': true }` | Disable specific features.                                         |
+| `_factoryDestroyPolicy?: 'unused' | 'never'` | `true` | Never destroy cached shaders and pipelines.                                                                              |
+
+### WebGLDeviceProps
+
+Extends `DeviceProps`.
+
+| WebGL Parameter                 | Default            | Description                                                                                                               |
+| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
 | `alpha?: boolean`               | `true`             | Default render target has an alpha buffer.                                                                                |
 | `depth?: boolean`               | `true`             | Default render target has a depth buffer of at least `16` bits.                                                           |
-| `stencil?`                      | `false`            | Default render target has a stencil buffer of at least `8` bits.                                                          |
+| `stencil?: boolean`             | `false`            | Default render target has a stencil buffer of at least `8` bits.                                                          |
+| `desynchronized?: boolean`      | `false`            | Hints the user agent to reduce the latency by desynchronizing the canvas paint cycle from the event loop.                 |
 | `antialias?`                    | `true`             | Boolean that indicates whether or not to perform anti-aliasing.                                                           |
+| `failIfMajorPerformanceCaveat?` | `false`            | Do not create if the system performance is low.                                                                           |
+| `powerPreference`               | `'high-performance'`| `'default'`, `'high-performance'`, `'low-power'`                                                                         |
 | `premultipliedAlpha?`           | `true`             | Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha. |
 | `preserveDrawingBuffer?`        | `false`            | Default render target buffers will preserve their values until cleared or overwritten. Useful for screen capture.         |
-| `failIfMajorPerformanceCaveat?` | `false`            | Do not create if the system performance is low.                                                                           |
+| `onContextLost`                 | `(event: Event) => void` | `webglcontextlost` event.                                                                                           |
+| `onContextRestored`             | `(event: Event) => void` | `webglcontextrestored` event.                                                                                       |
+| `debug?: boolean`               | `false`            | WebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions.                       |
+| `break?: string[]`              | `[]`               | Insert a break point (`debugger`) if one of the listed gl functions is called.                                            |
+| `manageState?: boolean`         | `true`             | Set to false to disable WebGL state management instrumentation.                                                           |
+
+### WebGPUDeviceProps
+
+Extends `DeviceProps`.
+
+| WebGPU Parameter                | Default            | Description                                                                                                               |
+| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `requestMaxLimits`              | `true`             | Request a Device with the highest limits supported by platform. WebGPU: devices can be created with minimal limits.       |
 
 ## Fields
 

docs/api-reference/core/luma.md

@@ -90,7 +90,7 @@ const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...});
 
 ### `CreateDeviceProps`
 
-Properties for creating a new device
+Properties for creating a new device.
 
 ```ts
 type CreateDeviceProps = DeviceProps & {
@@ -137,7 +137,7 @@ Note: A specific device type is available and supported if both of the following
 ### `luma.attachDevice()`
 
 ```ts
-luma.attachDevice({handle: WebGL2RenderingContext | GPUDevice, adapters, ...}: AttachDeviceProps);
+luma.attachDevice({handle: WebGL2RenderingContext | GPUDevice, adapters, ...deviceProps}: AttachDeviceProps);
 ```
 
 A luma.gl Device can be attached to an externally created `WebGL2RenderingContext` or `GPUDevice`.

docs/api-reference/webgl/README.md

@@ -5,7 +5,7 @@
 This module contains the WebGL adapter for the "abstract" luma.gl API (`@luma.gl/core`).
 
 Simply importing `@luma.gl/webgl` installs the adapter and enables WebGL devices to
-be created using `luma.createDevice(...)`:
+be created using `luma.createDevice(props)`. See [`WebGLDeviceProps`](../core/device#webgldeviceprops) for prop options.
 
 ```typescript
 import {luma} from '@luma.gl/core';
@@ -18,20 +18,20 @@ const buffer = device.createBuffer(...);
 ```
 
 To use a luma.gl WebGL `Device` with raw WebGL calls, the application needs to access
-the `WebGLRenderingContext`. The context is available on the `WebGLDevice` subclass:
+the `WebGL2RenderingContext`. The context is available on the `WebGLDevice` subclass:
 
 ```typescript
 // @ts-expect-error
 const gl = device.gl;
 ```
 
-With a bit more work, typescript users can retrieve the `WebGLRenderingContext`
+With a bit more work, typescript users can retrieve the `WebGL2RenderingContext`
 without ignoring type errors:
 
 ```typescript
 import {cast} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl'; // Installs the WebGLDevice adapter
 
-const webglDevice = cast<WebGPUDevice>(device);
+const webglDevice = cast<WebGLDevice>(device);
 const gl = webglDevice.gl;
 ```

docs/api-reference/webgpu/README.md

@@ -5,7 +5,7 @@
 This module contains the WebGPU adapter for the "abstract" luma.gl API (`@luma.gl/core`).
 
 Simply importing `@luma.gl/webgpu` installs the adapter and enables WebGPU devices to
-be created using `luma.createDevice(...)`:
+be created using `luma.createDevice(props)`: See [`WebGPUDeviceProps`](../core/device#webgpudeviceprops) for prop options.
 
 ```typescript
 import {luma} from '@luma.gl/core';

modules/core/src/adapter/device.ts

@@ -194,7 +194,7 @@ type WebGLCompressedTextureFeatures =
   | 'texture-compression-atc-webgl';
 
 /** Device properties */
-export type DeviceProps = {
+type _DeviceProps = {
   id?: string;
 
   // Common parameters
@@ -203,21 +203,19 @@ export type DeviceProps = {
   width?: number /** width is only used when creating a new canvas */;
   height?: number /** height is only used when creating a new canvas */;
 
-  /** Request a Device with the highest limits supported by platform. WebGPU: devices can be created with minimal limits. */
-  requestMaxLimits?: boolean;
-
-  // WebGLContext PARAMETERS - Can only be set on context creation...
-  // alpha?: boolean; // Default render target has an alpha buffer.
-  // depth?: boolean; // Default render target has a depth buffer of at least 16 bits.
-  // stencil?: boolean; // Default render target has a stencil buffer of at least 8 bits.
-  // antialias?: boolean; // Boolean that indicates whether or not to perform anti-aliasing.
-  // premultipliedAlpha?: boolean; // Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
-  // preserveDrawingBuffer?: boolean; // Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
-  // failIfMajorPerformanceCaveat?: boolean; // Do not create if the system performance is low.
-
   /** Error handling */
   onError?: (error: Error) => unknown;
 
+  // EXPERIMENTAL SETTINGS
+  /** Initialize all features on startup */
+  initalizeFeatures?: boolean;
+  /** Disable specific features */
+  disabledFeatures?: Partial<Record<DeviceFeature, boolean>>;
+  /** Never destroy cached shaders and pipelines */
+  _factoryDestroyPolicy?: 'unused' | 'never';
+};
+
+export type WebGLDeviceProps = _DeviceProps & {
   // @deprecated Attach to existing context. Rename to handle? Use Device.attach?
   gl?: WebGL2RenderingContext | null;
 
@@ -232,17 +230,31 @@ export type DeviceProps = {
   /** SpectorJS URL. Override if CDN is down or different SpectorJS version is desired */
   spectorUrl?: string;
 
+  // ContextProps
+  onContextLost?: (event: Event) => void;
+  onContextRestored?: (event: Event) => void;
+  alpha?: boolean; // indicates if the canvas contains an alpha buffer.
+  depth?: boolean; // indicates that the drawing buffer has a depth buffer of at least 16 bits.
+  stencil?: boolean; // Default render target has a stencil buffer of at least `8` bits.
+  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.
+  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.
+
   // EXPERIMENTAL SETTINGS
   /** Set to false to disable WebGL state management instrumentation: TODO- Unclear if still supported / useful */
   manageState?: boolean;
-  /** Initialize all features on startup */
-  initalizeFeatures?: boolean;
-  /** Disable specific features */
-  disabledFeatures?: Partial<Record<DeviceFeature, boolean>>;
-  /** Never destroy cached shaders and pipelines */
-  _factoryDestroyPolicy?: 'unused' | 'never';
 };
 
+export type WebGPUDeviceProps = _DeviceProps & {
+  /** Request a Device with the highest limits supported by platform. WebGPU: devices can be created with minimal limits. */
+  requestMaxLimits?: boolean;
+};
+
+export type DeviceProps = WebGLDeviceProps & WebGPUDeviceProps;
+
 /**
  * Create and attach devices for a specific backend. Currently static methods on each device
  */
@@ -262,23 +274,38 @@ export abstract class Device {
     id: null!,
     canvas: null,
     container: null,
-    manageState: true,
     width: 800, // width are height are only used by headless gl
     height: 600,
-    requestMaxLimits: true,
 
     // Callbacks
     onError: (error: Error) => log.error(error.message),
 
+    // TODO - Change these after confirming things work as expected
+    initalizeFeatures: true,
+    disabledFeatures: {
+      'compilation-status-async-webgl': true
+    },
+    _factoryDestroyPolicy: 'unused',
+
+    /**
+     * WebGL
+     */
+
     gl: null,
 
-    // alpha: undefined,
-    // depth: undefined,
-    // stencil: undefined,
-    // antialias: undefined,
-    // premultipliedAlpha: undefined,
-    // preserveDrawingBuffer: undefined,
-    // failIfMajorPerformanceCaveat: undefined
+    // WebGL context aattributes
+    alpha: true,
+    depth: true,
+    stencil: false,
+    desynchronized: false,
+    antialias: true,
+    failIfMajorPerformanceCaveat: false,
+    powerPreference: 'high-performance',
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+
+    onContextLost: undefined!,
+    onContextRestored: undefined!,
 
     debug: Boolean(log.get('debug')), // Instrument context (at the expense of performance)
     break: (log.get('break') as string[]) || [],
@@ -287,12 +314,14 @@ export abstract class Device {
     debugWithSpectorJS: undefined!,
     spectorUrl: undefined!,
 
-    // TODO - Change these after confirming things work as expected
-    initalizeFeatures: true,
-    disabledFeatures: {
-      'compilation-status-async-webgl': true
-    },
-    _factoryDestroyPolicy: 'unused'
+    // Experimental WebGL
+    manageState: true,
+
+    /**
+     * WebGPU
+     */
+
+    requestMaxLimits: true
   };
 
   get [Symbol.toStringTag](): string {

modules/core/src/adapter/luma.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {Log} from '@probe.gl/log';
-import type {DeviceProps} from './device';
+import type {DeviceProps, WebGLDeviceProps, WebGPUDeviceProps} from './device';
 import {Device} from './device';
 import {Adapter} from './adapter';
 import {StatsManager} from '../utils/stats-manager';
@@ -21,19 +21,26 @@ const ERROR_MESSAGE =
   'No matching device found. Ensure `@luma.gl/webgl` and/or `@luma.gl/webgpu` modules are imported.';
 
 /** Properties for creating a new device */
-export type CreateDeviceProps = DeviceProps & {
-  /** Selects the type of device. `best-available` uses webgpu if available, then webgl. */
-  type?: 'webgl' | 'webgpu' | 'unknown' | 'best-available';
+export type CreateDeviceProps = {
+  /** List of adapters. Will also search any pre-registered adapterss */
   adapters?: Adapter[];
-};
+} /** Selects the type of device. `best-available` uses webgpu if available, then webgl. */ & (
+  | ({type: 'webgl'} & WebGLDeviceProps)
+  | ({type: 'webgpu'} & WebGPUDeviceProps)
+  | ({type?: 'unknown' | 'best-available'} & DeviceProps)
+);
 
 /** Properties for attaching an existing WebGL context or WebGPU device to a new luma Device */
-export type AttachDeviceProps = DeviceProps & {
+export type AttachDeviceProps = {
   /** Externally created WebGL context or WebGPU device */
   handle: unknown; // WebGL2RenderingContext | GPUDevice | null;
   /** List of adapters. Will also search any pre-registered adapterss */
   adapters?: Adapter[];
-};
+} & (
+  | ({type: 'webgl'} & WebGLDeviceProps)
+  | ({type: 'webgpu'} & WebGPUDeviceProps)
+  | ({type?: 'unknown' | 'best-available'} & DeviceProps)
+);
 
 /**
  * Entry point to the luma.gl GPU abstraction

modules/core/src/index.ts

@@ -3,12 +3,19 @@
 // Copyright (c) vis.gl contributors
 
 // MAIN API ACCESS POINT
+export type {CreateDeviceProps} from './adapter/luma';
 export {luma} from './adapter/luma';
 
 // ADAPTER (DEVICE AND GPU RESOURCE INTERFACES)
 export {Adapter} from './adapter/adapter';
 
-export type {DeviceProps, DeviceInfo, DeviceFeature} from './adapter/device';
+export type {
+  DeviceProps,
+  DeviceInfo,
+  DeviceFeature,
+  WebGLDeviceProps,
+  WebGPUDeviceProps
+} from './adapter/device';
 export {Device, DeviceFeatures, DeviceLimits} from './adapter/device';
 
 export type {CanvasContextProps} from './adapter/canvas-context';

modules/webgl/src/adapter/webgl-device.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {TypedArray} from '@math.gl/types';
-import type {DeviceProps, DeviceInfo, CanvasContextProps, TextureFormat} from '@luma.gl/core';
+import type {WebGLDeviceProps, DeviceInfo, CanvasContextProps, TextureFormat} from '@luma.gl/core';
 import type {Buffer, Texture, Framebuffer, VertexArray, VertexArrayProps} from '@luma.gl/core';
 import {Device, CanvasContext, log} from '@luma.gl/core';
 import type {GLExtensions} from '@luma.gl/constants';
@@ -108,7 +108,7 @@ export class WebGLDevice extends Device {
   // Public API
   //
 
-  constructor(props: DeviceProps) {
+  constructor(props: WebGLDeviceProps) {
     super({...props, id: props.id || uid('webgl-device')});
 
     // If attaching to an already attached context, return the attached device
@@ -128,11 +128,13 @@ export class WebGLDevice extends Device {
 
     this.handle = createBrowserContext(this.canvasContext.canvas, {
       ...props,
-      onContextLost: (event: Event) =>
+      onContextLost: (event: Event) => {
         this._resolveContextLost?.({
           reason: 'destroyed',
           message: 'Entered sleep mode, or too many apps or browser tabs are using the GPU.'
-        })
+        });
+        props.onContextLost?.(event);
+      }
     });
     this.gl = this.handle;
 

modules/webgpu/src/adapter/webgpu-device.ts

@@ -6,7 +6,6 @@
 // / <reference types="@webgpu/types" />
 
 import type {
-  DeviceProps,
   DeviceInfo,
   DeviceLimits,
   DeviceFeature,
@@ -28,7 +27,8 @@ import type {
   TransformFeedback,
   TransformFeedbackProps,
   QuerySet,
-  QuerySetProps
+  QuerySetProps,
+  WebGPUDeviceProps
 } from '@luma.gl/core';
 import {Device, DeviceFeatures} from '@luma.gl/core';
 import {WebGPUBuffer} from './resources/webgpu-buffer';
@@ -71,7 +71,7 @@ export class WebGPUDevice extends Device {
   renderPass: WebGPURenderPass | null = null;
 
   constructor(
-    props: DeviceProps,
+    props: WebGPUDeviceProps,
     device: GPUDevice,
     adapter: GPUAdapter,
     adapterInfo: GPUAdapterInfo