Skip to content

Commit

Permalink
Merge c88dc08 into a35c4dd
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisgervang
chrisgervang committed Jun 20, 2024
2 parents a35c4dd + c88dc08 commit 507ffce
Show file tree
Hide file tree
Showing 12 changed files with 202 additions and 80 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
90 changes: 78 additions & 12 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,20 +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 |
| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `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.|
| `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?: 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. |

:::caution
🧪 denotes experimental feature. Expect API to change.
:::

#### WebGL Specific Options

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. |
| `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. |
| `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. |
| `desynchronized?: boolean` | `false` | Hints the user agent to reduce the latency by desynchronizing the canvas paint cycle from the event loop. |
| `failIfMajorPerformanceCaveat?` | `false` | Do not create if the system performance is low. |
| `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. |
| `failIfMajorPerformanceCaveat?` | `false` | Do not create if the system performance is low. |
| `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. |
| `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. |

:::tip
Learn more about WebGL debugging in our [Debugging](../../developer-guide/debugging.md) guide.
:::

#### 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
16 changes: 9 additions & 7 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 @@ -137,14 +138,15 @@ 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`.
This allows applications to use the luma.gl API to "interleave" rendering with other GPU libraries.

- `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
10 changes: 5 additions & 5 deletions docs/api-reference/webgl/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,33 @@
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 [`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(...);
```

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;
```
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(...)`:
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 507ffce

Please sign in to comment.