Core Concepts

Context

Start by creating a Volten context:

import { volten } from '@volten/core';
const v = await volten();

The context materializes logical nodes for its WebGPU device, runs GPU work, reads results, and reads debug output.

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() to define a callable operation containing the WGSL code that runs on the GPU.

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

const scale = kernel({
    shader: `
  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 an invocation has multiple possible input buffers, only raw buffers, or a shape that is not one thread per element, set threads on the kernel definition or invocation.

Operation Nodes

Calling a kernel connects it to data and returns a context-free node.

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

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

const result = await v.read(data);