diff --git a/docs/api-reference/core/canvas-context.md b/docs/api-reference/core/canvas-context.md index 3a92372cd1..454ffb78d5 100644 --- a/docs/api-reference/core/canvas-context.md +++ b/docs/api-reference/core/canvas-context.md @@ -37,6 +37,17 @@ const renderPass = device.beginRenderPass({ ### `CanvasContextProps` +```ts +{ + // common options + webgpu: { + // webgpu specific options + } +} +``` + +### Common Props + | Property | Type | | | ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | | `canvas?` | `HTMLCanvasElement` \| `OffscreenCanvas` \| `string` | A new canvas will be created if not supplied. | @@ -46,8 +57,13 @@ const renderPass = device.beginRenderPass({ | `useDevicePixels?` | `boolean` \| `number` | Device pixels scale factor (`true` uses browser DPI) | | `autoResize?` | `boolean` | Whether to track resizes | | `visible?` | `boolean` | Visibility (only used if new canvas is created). | -| `colorSpace?` | `'srgb'` | WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration | -| `compositingAlphaMode?` | `'opaque'` \| `'premultiplied'` | WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration | + +#### WebGPU Specific Props + +| Property | Type | | +| ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | +| `alphaMode?: string` | `'opaque'` | `'opaque' \| 'premultiplied'`. See [alphaMode](https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#alphamode). | +| `colorSpace?: 'string` | `'srgb'` | `'srgb' \| 'display-p3'`. See [colorSpace](https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#colorspace). | ## Static Fields diff --git a/docs/api-reference/core/device.md b/docs/api-reference/core/device.md index c27c5c819c..de03e58a3e 100644 --- a/docs/api-reference/core/device.md +++ b/docs/api-reference/core/device.md @@ -18,20 +18,20 @@ with changes to enable a WebGL2 implementation. ## Usage -Create a new Device, auto creating a canvas and a new WebGL 2 context +Create a new `Device`, auto creating a canvas and a new WebGL 2 context. See [`luma.createDevice()`](./luma.md#lumacreatedevice). ```typescript import {Device} from '@luma.gl/core'; -const device = new luma.createDevice({type: 'webgl2'}); +const device = new luma.createDevice({type: 'webgl2', ...}); ``` -Attaching a Device to an externally created `WebGL2RenderingContext`. +Attaching a `Device` to an externally created `WebGL2RenderingContext`. ```typescript import {Device} from '@luma.gl/core'; import {Model} from '@luma.gl/engine'; -const gl = canvas.createContext('webgl2'); +const gl = canvas.getContext('webgl2', ...); const device = Device.attach(gl); const model = new Model(device, options); @@ -52,44 +52,86 @@ console.error(message); ### `DeviceProps` +```ts +{ + // common options + webgl: { + // webgl specific options + }, + webgpu: { + // webgpu specific options + } +} +``` +:::tip +This object can also include all [`CanvasContextProps`](./canvas-context.md#canvascontextprops) properties to configure how a new canvas is created. If a canvas is provided, these are ignored. +::: + +#### Common Options + +Specify common props to use when luma creates the device. + | Parameter | Default | Description | | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `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. | +| `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.| | `onError?: (error: Error) => unknown` | `log.error` | Error handling. | -| `initalizeFeatures?: boolean` | `true` | Initialize all features on startup. | -| `disabledFeatures?: Partial>` | `{ 'compilation-status-async-webgl': true }` | Disable specific features. | -| `_factoryDestroyPolicy?: 'unused' | 'never'` | `true` | Never destroy cached shaders and pipelines. | +| `initalizeFeatures?: boolean` | `true` | Initialize all features on startup. 🧪 | +| `disabledFeatures?: Partial>` | `{ 'compilation-status-async-webgl': true }` | Disable specific features. 🧪 | +| `_factoryDestroyPolicy?: string`| `'unused'` | `'unused' \| 'never'` Never destroy cached shaders and pipelines. 🧪 | +| `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` | If new canvas is created, sets the canvas width. | +| `height?: number` | `600` | If new canvas is created, sets the canvas height. | +| `useDevicePixels?: boolean \| number` | `true` | If new canvas is created, sets device pixels scale factor (`true` uses browser DPI). | +| `autoResize?: boolean` | `true` | If new canvas is created, sets whether to track resizes. | +| `visible?: boolean` | `true` | If new canvas is created, sets visibility. | -### WebGLDeviceProps +:::caution +🧪 denotes experimental feature. Expect API to change. +::: -Extends `DeviceProps`. +#### WebGL Specific Options -| WebGL Parameter | Default | Description | +Specify WebGL context attributes to use if luma creates the WebGL context. + +| WebGL Context Attributes | Default | Description | | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `gl?: WebGL2RenderingContext` | N/A | An existing WebGL context. If not provided, a new context will be created with the attributes provided below. | | `alpha?: boolean` | `true` | Default render target has an alpha buffer. | +| `antialias?` | `true` | Boolean that indicates whether or not to perform anti-aliasing. | | `depth?: boolean` | `true` | Default render target has a depth buffer of at least `16` 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'` | +| `manageState?: boolean` | `true` | Set to false to disable WebGL state management instrumentation. *_Experimental._ | +| `powerPreference?: string` | `'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. | -| `debug?: boolean` | `false` | WebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions. | +| `stencil?: boolean` | `false` | Default render target has a stencil buffer of at least `8` bits. | + +:::tip +See [MDN WebGL context attributes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext#contextattributes) guide for more information. +::: + +Specify WebGL debugging options to use when luma creates the WebGL context. + +| WebGL Debugging | Default | Description | +| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `debug?: boolean` | `false` | Initialize Khronos WebGLDeveloperTools. 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. | +| `debugWithSpectorJS?: boolean` | `false` | Initialize the SpectorJS WebGL debugger. | +| `spectorUrl?: string` | N/A | SpectorJS URL. Override if CDN is down or different SpectorJS version is desired. | -### WebGPUDeviceProps +:::tip +Learn more about WebGL debugging in our [Debugging](../../developer-guide/debugging.md) guide. +::: -Extends `DeviceProps`. +#### WebGPU Specific Options | WebGPU Parameter | Default | Description | | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `requestMaxLimits` | `true` | Request a Device with the highest limits supported by platform. WebGPU: devices can be created with minimal limits. | +| `alphaMode?: string` | `'opaque'` | `'opaque' \| 'premultiplied'`. Sets the initial [alphaMode](https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#alphamode) on the internal context. | +| `colorSpace?: 'string` | `'srgb'` | `'srgb' \| 'display-p3'`. Sets the initial [colorSpace](https://developer.mozilla.org/en-US/docs/Web/API/GPUCanvasContext/configure#colorspace) on the internal context. | ## Fields diff --git a/docs/api-reference/core/luma.md b/docs/api-reference/core/luma.md index b2dde2be87..6bc2e7106c 100644 --- a/docs/api-reference/core/luma.md +++ b/docs/api-reference/core/luma.md @@ -90,28 +90,28 @@ const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...}); ### `CreateDeviceProps` -Properties for creating a new device. +Properties for creating a new device. See [`DeviceProps`](./device.md#deviceprops) for device specific options. ```ts -type CreateDeviceProps = DeviceProps & { +type CreateDeviceProps = { /** Selects the type of device. `best-available` uses webgpu if available, then webgl. */ type?: 'webgl' | 'webgpu' | 'unknown' | 'best-available'; /** List of device types. Will also search any pre-registered device backends */ adapters?: Adapter[]; -} +} & DeviceProps ``` ### `AttachDeviceProps` -Properties for attaching an existing WebGL context or WebGPU device to a new luma Device. +Properties for attaching an existing WebGL context or WebGPU device to a new luma Device. See [`DeviceProps`](./device.md#deviceprops) for device specific options. ```ts -export type AttachDeviceProps = DeviceProps & { +export type AttachDeviceProps = { /** Externally created WebGL context or WebGPU device */ handle: WebGL2RenderingContext | GPUDevice | null; /** List of device types. Will also search any pre-registered device backends */ adapters?: Adapter[]; -}; +} & DeviceProps; ``` ## Methods @@ -126,6 +126,7 @@ To create a Device instance, the application calls `luma.createDevice()`. - `type`: `'webgl' \| 'webgpu' \| 'best-available'` - `adapters`: list of `Adapter` instances providing support for different GPU backends. Can be omitted if `luma.registerAdapters()` has been called. +- `...deviceProps`: See [`DeviceProps`](./device.md#deviceprops) for device specific options. Unless a device `type` is specified a `Device` will be created using the `'best-available'` adapter. luma.gl favors WebGPU over WebGL adapters, whenever WebGPU is available. @@ -145,6 +146,7 @@ This allows applications to use the luma.gl API to "interleave" rendering with o - `handle` - The externally created `WebGL2RenderingContext` or `GPUDevice` that should be attached to a luma `Device`. - `adapters` - list of `Device` backend classes. Can be omitted if `luma.registerAdapters()` has been called. +- `...deviceProps`: See [`DeviceProps`](./device.md#deviceprops) for device specific options. Note that while you cannot directly attach a luma.gl `Device` to a WebGL 1 `WebGLRenderingContext`, you may be able to work around it using `luma.enforceWebGL2()`. diff --git a/docs/api-reference/webgl/README.md b/docs/api-reference/webgl/README.md index 66d25aad91..c2291125b1 100644 --- a/docs/api-reference/webgl/README.md +++ b/docs/api-reference/webgl/README.md @@ -5,13 +5,13 @@ 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(props)`. See [`WebGLDeviceProps`](../core/device#webgldeviceprops) for prop options. +be created using `luma.createDevice(props)`. See [`DeviceProps`](../core/device#deviceprops) for WebGL prop options. ```typescript import {luma} from '@luma.gl/core'; import '@luma.gl/webgl'; // Installs the WebGLDevice adapter -const device = await luma.createDevice({type: 'webgl', canvas: ...}); +const device = await luma.createDevice({type: 'webgl', canvas: ..., webgl: {...}}); // Resources can now be created const buffer = device.createBuffer(...); diff --git a/docs/api-reference/webgpu/README.md b/docs/api-reference/webgpu/README.md index 8b4672e616..38e73598f9 100644 --- a/docs/api-reference/webgpu/README.md +++ b/docs/api-reference/webgpu/README.md @@ -5,13 +5,13 @@ 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(props)`: See [`WebGPUDeviceProps`](../core/device#webgpudeviceprops) for prop options. +be created using `luma.createDevice(props)`: See [`DeviceProps`](../core/device#deviceprops) for WebGPU prop options. ```typescript import {luma} from '@luma.gl/core'; import '@luma.gl/webgpu'; // Installs the WebGPUDevice adapter -const device = await luma.createDevice({type: 'webgpu', canvas: ...}); +const device = await luma.createDevice({type: 'webgpu', canvas: ..., webgpu: {...}}); // Resources can now be created const buffer = device.createBuffer(...); diff --git a/docs/developer-guide/debugging.md b/docs/developer-guide/debugging.md index 90f51716f5..33850c2a56 100644 --- a/docs/developer-guide/debugging.md +++ b/docs/developer-guide/debugging.md @@ -105,7 +105,7 @@ While usually not recommended, it is also possible to activate the developer too ```ts import {luma} from '@luma.gl/core'; -const device = luma.createDevice({type: 'webgl', debug: true}); +const device = luma.createDevice({type: 'webgl', {webgl: {debug: true}}); ``` > Warning: WebGL debug contexts impose a significant performance penalty (luma waits for the GPU after each WebGL call to check error codes) and should not be activated in production code. diff --git a/docs/legacy/porting-guide.md b/docs/legacy/porting-guide.md index 6312f38e90..55c835714c 100644 --- a/docs/legacy/porting-guide.md +++ b/docs/legacy/porting-guide.md @@ -185,9 +185,9 @@ The debug module has been removed. Debug functionality is now built-in (and dyna | ------------------------------- | ---------------------------------- | ------------------------------------------------ | | Properties | | `props.gl` | `props.device` | Now accepts a `Promise`. | -| `props.glOptions` | `luma.createDevice()` | +| `props.glOptions` | `luma.createDevice()` | See [CreateDeviceProps](../api-reference/core/luma.md#createdeviceprops) | | `props.createFramebuffer` | N/A | You will need to create framebuffers explicitly. | -| `props.debug` | `luma.createDevice({debug: true})` | Device debug functionality is improved. | +| `props.debug` | `luma.createDevice({webgl: {debug: true}, type: 'webgl'})` | Device debug functionality is improved. | | Methods | | `animationLoop.isContextLost()` | `device.lost`, `device.isLost()` | | @@ -246,8 +246,8 @@ The v8 luma.gl API was designed to allow apps to work directly with the `WebGLRe | v8 Prop or Method | v9 Replacement | Comment | | -------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `makeDebugContext()` | `luma.createDevice({debug: true, type: 'webgl'})` | [Khronos WebGL developer tools][khronos_dev_tools] are dynamically loaded when needed. | -| Spector.js | `luma.createDevice({spector: true, type: 'webgl'})` | [Spector.js][spector] is pre-integrated. Te Spector.js library will be dynamically loaded when needed and the canvas is "captured". | +| `makeDebugContext()` | `luma.createDevice({webgl: {debug: true}, type: 'webgl'})` | [Khronos WebGL developer tools][khronos_dev_tools] are dynamically loaded when needed. | +| Spector.js | `luma.createDevice({webgl: {debugWithSpectorJS: true}, type: 'webgl'})` | [Spector.js][spector] is pre-integrated. The Spector.js library will be dynamically loaded when needed and the canvas is "captured". | [khronos_dev_tools]: https://github.com/KhronosGroup/WebGLDeveloperTools [spector]: https://spector.babylonjs.com/