Skip to content

Commit

Permalink
New DeviceProps API
Browse files Browse the repository at this point in the history 
Signed-off-by: Chris Gervang <chris@gervang.com>
  • Loading branch information
@chrisgervang
chrisgervang committed Jun 20, 2024
1 parent 688f87f commit c88dc08
Show file tree
Hide file tree
Showing 7 changed files with 98 additions and 38 deletions.
20 changes: 18 additions & 2 deletions docs/api-reference/core/canvas-context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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

Expand Down
84 changes: 63 additions & 21 deletions docs/api-reference/core/device.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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<Record<DeviceFeature, boolean>>` | `{ '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<Record<DeviceFeature, boolean>>` | `{ '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

Expand Down
14 changes: 8 additions & 6 deletions docs/api-reference/core/luma.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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()`.

Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference/webgl/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(...);
Expand Down
4 changes: 2 additions & 2 deletions docs/api-reference/webgpu/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(...);
Expand Down
2 changes: 1 addition & 1 deletion docs/developer-guide/debugging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading

0 comments on commit c88dc08

Please sign in to comment.