@latkit/gpu¶

Core WebGPU device and canvas presentation primitives for Latkit.

@latkit/gpu handles the environmental part of requesting a device and then returns the platform GPUDevice directly. It also provides the shared presentation implementation used by Latkit renderers. All exports come from the single @latkit/gpu entrypoint.

Install¶

npm install @latkit/gpu

Request a device¶

import { requestDevice } from '@latkit/gpu';

const device = await requestDevice();

try {
  console.log(device.limits);

  void device.lost.then((info) => {
    console.error('GPU device lost:', info.reason, info.message);
  });
} finally {
  device.destroy();
}

requestDevice() requests Core WebGPU and leaves the adapter power preference to the browser. Pass powerPreference only when the application has a specific reason to override that choice:

const device = await requestDevice({
  powerPreference: 'high-performance',
});

Handle availability¶

import { GpuUnavailableError, requestDevice } from '@latkit/gpu';

try {
  const device = await requestDevice();

  try {
    // Create renderers that borrow device.
  } finally {
    device.destroy();
  }
} catch (error) {
  if (error instanceof GpuUnavailableError) {
    console.error(`WebGPU unavailable at ${error.stage}:`, error.message);
  } else {
    throw error;
  }
}

Only API absence, a null adapter, and device-request rejection use GpuUnavailableError. Other platform and programming failures retain their original identity.

Configure presentation¶

Renderer implementations can configure either an HTMLCanvasElement or an OffscreenCanvas through the same primitive:

import { createPresentation } from '@latkit/gpu';

const presentation = createPresentation(device, canvas);
presentation.resize(800, 450);

try {
  const texture = presentation.context.getCurrentTexture();
  // Encode rendering commands for texture.
} finally {
  presentation.destroy();
}

Presentation owns its context configuration and backing-size changes. It preserves aspect ratio when fitting oversized requests to the device limit, restores the original canvas size when destroyed, and never destroys its borrowed device. observeCanvas() provides device-pixel sizes and pixel ratio for an HTML canvas while leaving scheduling and resize policy to the renderer.

Classes¶

Class	Description
GpuUnavailableError	Expected environmental failure while requesting a WebGPU device.

Interfaces¶

Interface	Description
Options	Options used when selecting a WebGPU adapter.
Presentation	A configured WebGPU canvas binding.

Type Aliases¶

PresentationCanvas¶

PresentationCanvas = GPUCanvasContext["canvas"]

Canvas types accepted by a WebGPU presentation context.

Functions¶

createPresentation()¶

createPresentation<TCanvas>(device, canvas, options?): Presentation<TCanvas>

Configures a canvas for presentation with a borrowed WebGPU device.

The returned presentation owns the context configuration and any backing-size changes made through Presentation.resize. It never owns the device.

Type Parameters¶

Type Parameter
`TCanvas` extends `HTMLCanvasElement` \| `OffscreenCanvas`

Parameters¶

Parameter	Type
`device`	`GPUDevice`
`canvas`	`TCanvas`
`options`	`Omit`<`GPUCanvasConfiguration`, `"device"` \| `"format"`> & `object`

Returns¶

Presentation<TCanvas>

observeCanvas()¶

observeCanvas(canvas, listener): () => void

Reports an HTML canvas’s current device-pixel size and pixel ratio, then observes subsequent changes.

The listener runs synchronously once, then directly from resize notifications. Scheduling and backing-size policy remain the listener’s responsibility.

Parameters¶

Parameter	Type
`canvas`	`HTMLCanvasElement`
`listener`	(`width`, `height`, `pixelRatio`) => `void`

Returns¶

An idempotent function that stops observation.

() => void

requestDevice()¶

requestDevice(options?): Promise<GPUDevice>

Requests a Core WebGPU device.

Parameters¶

Parameter	Type	Description
`options`	`Options`	Optional adapter-selection hints.

Returns¶

Promise<GPUDevice>

The native Core device owned by the caller.

Throws¶

GpuUnavailableError when the API, adapter, or device is unavailable.

Remarks¶

No power preference is requested by default. The caller must destroy the device after every renderer and resource that borrows it has been destroyed.