Core Concepts

Context

Start by creating a Volten context:

import { volten } from '@volten/core';

const v = await volten();

The context is the object you use to create passes, run GPU work, read results, read debug output, and more.

If your app already owns a WebGPU device, pass it in:

const v = await volten({ device });

Buffers and Uniforms

Use Buffer for arrays of values. Use Uniform for small configuration values.

import { Buffer, Uniform } from '@volten/core';

const data = new Buffer([1, 2, 3, 4], 'f32', 'rw');
const scale = new Uniform(2, 'f32');

WebGPU mapping

Buffer maps to a storage buffer. Uniform maps to a WebGPU uniform buffer.

Kernels

Use Kernel for the WGSL code that runs on the GPU.

import { Kernel } from '@volten/core';

const kernel = new Kernel(`
  fn main(gid: vec3u) {
    data[gid.x] = data[gid.x] * scale;
  }
`);

Volten will internally handle pipeline creation, bindings and layouts, shader generation, buffer uploads, etc.

Volten also wraps your function with the compute entry point and workgroup size.

Thread count

Volten can often infer how many invocations to run from one clear input buffer. If a pass has multiple possible input buffers, only raw buffers, or a shape that is not one thread per element, set threads on the kernel or pass.

Passes

A pass connects a kernel to its data and returns a runnable node.

const node = v.pass(kernel, { data, scale });
v.run(node);

Read a concrete buffer when you need CPU-visible results:

const result = await v.read(data);