Roots

Psst, WebGPU veterans…

You can think of roots as typed wrappers around WebGPU devices.

Roots are responsible for resource allocation and management. Whether you’d like to wrap an existing WebGPU buffer with a typed shell or create a brand new buffer, roots are the place to start.

You can create a root using the tgpu.init function. It requests a GPU device with default requirements. An optional parameter can be passed in with special requirements for the GPU device.

import tgpu from 'typegpu';

const root = await tgpu.init();

If you already have a device that you want to use, you can pass it into tgpu.initFromDevice instead.

import tgpu from 'typegpu';

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter?.requestDevice() as GPUDevice;

// using a preexisting device
const root = tgpu.initFromDevice({ device });

Note

To retrieve the device that is associated with a root, you can use the root.device property.

Configuring context

In order to draw on a canvas, you need to create and configure a context that will be later passed to a pipeline.

const context = canvas.getContext("webgpu") as GPUCanvasContext;
const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
context.configure({
  device: root.device,
  format: presentationFormat,
  alphaMode: 'premultiplied',
});

TypeGPU streamlines this process with root.configureContext method.

// format defaults to `navigator.gpu.getPreferredCanvasFormat()`
const context = root.configureContext({ canvas, alphaMode: 'premultiplied' });

Creating resources

Resources independent from the device, such as bind group layouts, functions, variables, TypeGPU slots etc., are created using dedicated tgpu.* methods.

Resources requiring a device, such as bind groups, buffers, samplers, pipelines, etc., are created using root.create* methods.

For more information, see corresponding chapters.

Note

There are times where a typed resource needs to be used by a vanilla WebGPU API. To retrieve the raw untyped value of a typed resource, use the root.unwrap function.

To unwrap a TgpuVertexLayout make sure to explicitly mark each of its attributes with the appropriate location using d.location(...).

Destroying resources

Calling root.destroy() will call device.destroy() to let the browser know that it can free up all the resources.

If the root was created via tgpu.initFromDevice(), this method does nothing.

root.destroy(); // <- frees up all the resources

Best practices

Treat roots as their own separate universes, meaning resources created from the same root can interact with each other, while resources created by seperate roots can have a hard time interacting. This usually means creating just one root at the start of the program is the safest bet, but there are exceptions.

If you do not own the GPU device

If you cannot control the lifetime of the GPU device you are to use for computing/rendering, but are instead given the device in a lifecycle hook (e.g., react-native-webgpu), you can create a new root each time, as long as you recreate every resource as well.

example.tsx

import React from 'react';

function SceneView() {
  const ref = useWebGPU(({ context, device, presentationFormat }) => {
    const root = tgpu.initFromDevice({ device });

    // create all resources...
  });

  // ...
}

If you pass the GPU device everywhere

It is common practice to pass a GPUDevice to classes or functions for them to allocate their required resources. At first glance, this poses a problem when trying to incorporate TypeGPU, since we would need to pass a root around instead of a device for all functionality that wants to move towards a typed API. We can create a global mapping between devices and roots to solve this.

Note

When designing an architecture from scratch with TypeGPU in mind, passing a root around instead of a device is the preferred pattern, since root.device can act as an escape hatch for vanilla WebGPU functionality.

You can copy and paste the utility below that implements a basic global cache for roots.

roots.ts

const deviceToRootMap = new WeakMap<GPUDevice, TgpuRoot>();

function getOrInitRoot(device: GPUDevice): TgpuRoot {
  let root = deviceToRootMap.get(device);

  if (!root) {
    root = tgpu.initFromDevice({ device });
    deviceToRootMap.set(device, root);
  }

  return root;
}

If you reuse the same getOrInitRoot function across code that has to create resources, the root will be shared across them.

class GameObject {
  constructor(device: GPUDevice) {
    const root = getOrInitRoot(device);

    // create all resources...
  }
}