Typegpu

TypeGPU

A single schema (d.*) defines a GPU type, CPU buffer layout, and TypeScript type at once - no manual alignment, type mapping, or casting. The build plugin unplugin-typegpu transforms 'use gpu'-marked TypeScript for runtime WGSL transpilation, enabling type inference and polymorphism across the CPU/GPU boundary.

This skill targets TypeGPU 0.12. If the user's project is on an older release, verify API availability before relying on examples or recommended patterns here.

When to read reference files

Read before writing virtually any shader or GPU function — these two cover the rules that trip people up most:

• references/types.md — abstract type resolution, exactly when d.f32() is required vs redundant, vector constructor overloads, sampler/texture schemas for tgpu.fn signatures, CPU-side TgpuBuffer/TgpuTexture TypeScript types. If you skip this, you'll hit type errors.
• references/shaders.md — loops (std.range, tgpu.unroll), ternary/logical-operator semantics, tgpu.comptime, outer-scope capture rules, complete builtin reference for all three shader stages, console.log. Read this for any non-trivial shader logic.
• references/std.md — full std function listing (math, comparison/boolean vectors, matrix builders, texture, atomics, packing, subgroups, environment probes). Consult before hand-rolling any math/utility function.

Read when the task specifically involves:

• references/pipelines.md — vertex buffers/layouts, attribs wiring, MRT, fullscreen triangle, depth/stencil, blend modes, fragDepth output, loading 3D models (@loaders.gl), resolve API
• references/matrices.md — wgpu-matrix integration, column-major layout, camera uniforms, common.writeSoA, fast-path CPU writes. Read for any 3D work (view/projection matrices, animated transforms, model loading)
• references/textures.md — texture creation, views, samplers, storage textures, mipmaps, multisampling
• references/noise.md — @typegpu/noise (random, distributions, Perlin 2D/3D)
• references/sdf.md — @typegpu/sdf (2D/3D primitives, operators, ray marching, AA masking)
• references/encoders.md — typed command encoders, multi-pipeline render/compute passes, render bundles, batched submission, raw-WebGPU encoder interop (unstable API, stable behavior)
• references/timing.md — GPU timing via timestamp queries: withPerformanceCallback vs a shared query set, the available guard, why per-pass timings overlap
• references/react.md — @typegpu/react hooks (useRoot, useFrame, useUniform, ...), React Native worklet render loops
• references/setup.md — TypeGPU CLI, install, unplugin-typegpu build plugin, tsover operator overloading, troubleshooting
• references/advanced.md — buffer reinterpretation, indirect drawing/dispatch, ArrayBuffer IO, minification, warning silencing, root.unwrap

Setup

tsCopy code
import { tgpu, d, std, common } from 'typegpu';

const root = await tgpu.init();                 // request a GPU device
const root = tgpu.initFromDevice({ device });   // or wrap an existing GPUDevice

const context = root.configureContext({ canvas, alphaMode: 'premultiplied' });

Create one root at app startup. Resources from different roots cannot interact. Teardown: root.destroy() destroys all resources created through the root, plus the device itself if the root came from tgpu.init (not initFromDevice).

Data schemas (d.*)

A schema defines memory layout and infers TypeScript types; the same schema is used for buffers, shader signatures, and bind group entries.

Scalars

tsCopy code
d.f32    d.i32    d.u32    d.f16   // f16 needs the 'shader-f16' device feature (references/setup.md)
// d.bool is NOT host-shareable - use d.u32 in buffers

Vectors and matrices

tsCopy code
d.vec2f  d.vec3f  d.vec4f     // f32
d.vec2i  d.vec3i  d.vec4i     // i32
d.vec2u  d.vec3u  d.vec4u     // u32
d.vec2h  d.vec3h  d.vec4h     // f16
d.vec2b  d.vec3b  d.vec4b     // bool - shader-side only (not host-shareable)

d.mat2x2f   d.mat3x3f   d.mat4x4f

Instance types: d.vec3f() -> d.v3f, d.mat4x4f() -> d.m4x4f.

Vector constructors are richly overloaded — they compose from any mix of scalars, smaller vectors, and swizzles that adds up to the right component count (d.vec4f(rgb, 1), d.vec3f(v.xy, newZ)). Prefer them over manual component decomposition; full overload listing in references/types.md.

Compound types

tsCopy code
const Particle = d.struct({
  position: d.vec2f,
  velocity: d.vec2f,
  color:    d.vec4f,
});

const ParticleArray = d.arrayOf(Particle, 1000); // fixed-size

Runtime-sized schemas. d.arrayOf(Element) without a count returns a function (n: number) => WgslArray<Element>. This dual nature is the key: pass the function itself (unsized) to bind group layouts, call it with a count (sized) for buffer creation.

tsCopy code
// Plain array - arrayOf without count is already a factory:
const layout = tgpu.bindGroupLayout({
  data: { storage: d.arrayOf(d.f32), access: 'mutable' },  // unsized for layout
});
const buf = root.createBuffer(d.arrayOf(d.f32, 1024)).$usage('storage'); // sized for buffer

// Struct with a runtime-sized last field - wrap in a factory function:
const RuntimeStruct = (n: number) =>
  d.struct({
    counter: d.atomic(d.u32),
    items:   d.arrayOf(d.f32, n),  // last field gets the runtime size
  });

const layout2 = tgpu.bindGroupLayout({
  runtimeData: { storage: RuntimeStruct, access: 'mutable' }, // unsized (the function)
});
const buf2 = root.createBuffer(RuntimeStruct(1024)).$usage('storage'); // sized (called)

You cannot pass an unsized schema directly to createBuffer - size must be known on the CPU.

GPU functions

TypeGPU compiles TypeScript marked with 'use gpu' into WGSL.

Plain callback (polymorphic)

No explicit signature; best for helper math and flexible utilities.

tsCopy code
const rotate = (v: d.v2f, angle: number) => {
  'use gpu';
  const c = std.cos(angle);
  const s = std.sin(angle);
  return d.vec2f(c * v.x - s * v.y, s * v.x + c * v.y);
};

number parameters and unions like d.v2f | d.v3f are polymorphic - TypeGPU generates one WGSL overload per unique call-site type combination. Values captured from outer scope are inlined as WGSL literals; use buffers/uniforms for anything that changes at runtime.

tgpu.fn (explicit types)

Pinned WGSL signature. Use for library code or when you need a fixed WGSL interface.

tsCopy code
const rotate = tgpu.fn([d.vec2f, d.f32], d.vec2f)((v, angle) => {
  'use gpu';
  // ...
});

Shader entrypoints

tsCopy code
// Compute
const myCompute = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})((input) => { 'use gpu'; /* input.gid: d.v3u */ });

// Vertex
const myVertex = tgpu.vertexFn({
  in:  { position: d.vec3f, uv: d.vec2f },
  out: { position: d.builtin.position, fragUv: d.vec2f },
})((input) => {
  'use gpu';
  return { position: d.vec4f(input.position, 1), fragUv: input.uv };
});

// Fragment
const myFragment = tgpu.fragmentFn({
  in: { fragUv: d.vec2f },
  out: d.vec4f,
})((input) => { 'use gpu'; return d.vec4f(input.fragUv, 0, 1); });

Vertex in may include builtins: d.builtin.vertexIndex, d.builtin.instanceIndex.

Full shader syntax, branch pruning, the std library, type inference, and idiomatic patterns (vector ops, struct constructors, register pressure): see references/shaders.md. Read it before any non-trivial shader — values-vs-references handling lives there and is the most common source of ResolutionError.

Buffers

Creating

tsCopy code
// Schema only:
const buf = root.createBuffer(d.arrayOf(Particle, 1000)).$usage('storage');

// With typed initial value (only when non-zero — all buffers are zero-initialized by default):
const uBuf = root.createBuffer(Config, { time: 1, scale: 2.0 }).$usage('uniform');

// With an initializer callback - buffer is still mapped (cheapest CPU path):
const buf = root.createBuffer(Schema, (mappedBuffer) => {
  mappedBuffer.write([10, 20], { startOffset: firstChunk.offset });
  mappedBuffer.write([30, 40], { startOffset: secondChunk.offset });
});

// Wrap an existing GPUBuffer (you own its lifecycle and flags):
const buf = root.createBuffer(d.u32, existingGPUBuffer);
buf.write(12);

Usage flags

All buffers get COPY_SRC | COPY_DST automatically. $addFlags(GPUBufferUsage.X) adds any flag not covered by $usage.

Writing

.write(value) handles alignment. Four input forms (slowest → fastest):

Cache plain arrays or Float32Array at setup and reuse. For the padding rules (vec3f = 16 bytes, mat3x3f per-column padding) and full fast-path guidance, see references/matrices.md.

Slice write - update a sub-region using d.memoryLayoutOf to get byte offsets:

tsCopy code
const layout = d.memoryLayoutOf(schema, (a) => a[3]);
buffer.write([4, 5, 6], { startOffset: layout.offset });

.patch(data) - update specific struct fields or array indices without touching the rest:

tsCopy code
planetBuffer.patch({
  mass: 123.1,
  colors: { 2: [1, 0, 0], 4: d.vec3f(0, 0, 1) },
});

common.writeSoA(buffer, { field: Float32Array, ... }) - scatter separate packed per-field arrays into the GPU's AoS layout with correct padding. The idiomatic path for particle systems, simulations, and model loading where CPU data is already field-separated. See references/matrices.md for examples and references/pipelines.md for the model-loading pattern.

GPU-side copy: destBuffer.copyFrom(srcBuffer) (schemas must match). Zeroing: buffer.clear(). Cleanup: buffer.destroy(). Both copyFrom and clear take an optional command encoder — see references/encoders.md.

Reading

tsCopy code
const data = await buffer.read(); // returns a typed JS value matching the schema

Shorthand "fixed" resources

Skip manual bind groups - the buffer is always bound when referenced in any shader:

tsCopy code
const particlesMutable = root.createMutable(d.arrayOf(Particle, 1000));  // var<storage, read_write>
const configUniform    = root.createUniform(Config);                     // var<uniform>
const bufReadonly      = root.createReadonly(d.arrayOf(d.f32, N));       // var<storage, read>

Access inside shaders via particles.$, config.$. Prefer fixed resources by default; switch to manual bind groups when you need to swap resources per frame, manage @group indices, or share layouts across pipelines.

A manually created buffer converts to the same kind of binding with buffer.as('uniform' | 'readonly' | 'mutable') (requires the matching $usage) — use it when you hold a TgpuBuffer but need .$ access in a shader.

Bind group layouts (manual binding)

tsCopy code
const layout = tgpu.bindGroupLayout({
  config:    { uniform: ConfigSchema },
  particles: { storage: d.arrayOf(Particle), access: 'mutable' },
  mySampler: { sampler: 'filtering' },   // 'filtering' | 'non-filtering' | 'comparison'
  myTexture: { texture: d.texture2d(d.f32) },
});

// Inside shaders: layout.$.config, layout.$.particles, ...

const bindGroup = root.createBindGroup(layout, {
  config:    configBuffer,
  particles: particleBuffer,
  mySampler: tgpuSampler,
  myTexture: textureOrView,
});

pipeline.with(bindGroup).dispatchWorkgroups(N);

Buffer bindings from createUniform/createMutable/createReadonly are accepted directly as entries (no need to unwrap to a buffer).

Explicit @group index (only needed when integrating with raw WGSL that hardcodes group indices): layout.$idx(0).

Compute pipelines

tsCopy code
// Standard - you control workgroup sizing
const pipeline = root.createComputePipeline({ compute: myComputeFn });
pipeline.with(bindGroup).dispatchWorkgroups(Math.ceil(N / 64));

// Guarded - TypeGPU handles workgroup sizing and bounds checking automatically.
// The callback's parameter count sets the dimensionality (0D to 3D):
const p0 = root.createGuardedComputePipeline(() => { 'use gpu'; /* runs once */ });
const p1 = root.createGuardedComputePipeline((x: number) => { 'use gpu'; });
const p2 = root.createGuardedComputePipeline((x: number, y: number) => { 'use gpu'; });
const p3 = root.createGuardedComputePipeline((x: number, y: number, z: number) => { 'use gpu'; });

// dispatchThreads matches the callback's arity - pass thread counts, not workgroup counts.
// TypeGPU picks workgroup sizes internally and injects a bounds guard so threads
// outside the requested range are no-ops.
p2.with(bindGroup).dispatchThreads(width, height);

// WGSL builtins like globalInvocationId are NOT available - use the callback parameters instead.

WebGPU coordinate conventions

WebGPU matches DirectX/Metal, not OpenGL/WebGL — porting tutorials verbatim causes subtle bugs:

• NDC z: [0, 1], not [-1, 1]. A copy-pasted gluPerspective clips the near plane. Use wgpu-matrix's mat4.perspective (already targets [0, 1]), or mat4.perspectiveReverseZ for better depth precision.
• Framebuffer (0, 0) is top-left, +y down — opposite of OpenGL. d.builtin.position.xy in a fragment shader is pixel-space with this origin.
• Texture UV (0, 0) is top-left. Do not pre-flip v — createImageBitmap already matches this.
• Matrices are column-major: d.mat4x4f(c0, c1, c2, c3) takes columns. Inside shaders use mat.columns[c][r]; plain mat[i] is rejected. Composition: projection * view * model * position. See references/matrices.md.

Render pipelines

tsCopy code
const pipeline = root.createRenderPipeline({
  vertex:   myVertex,
  fragment: myFragment,
  targets:  { format: presentationFormat }, // single target - shorthand
  primitive?:    GPUPrimitiveState,
  depthStencil?: GPUDepthStencilState,
  multisample?:  GPUMultisampleState,
});

pipeline
  .with(bindGroup)
  .withColorAttachment({
    view: context,
    // loadOp/storeOp/clearValue have defaults
  })
  .withDepthStencilAttachment({ /* ... */ })
  .withIndexBuffer(indexBuffer)  // enables .drawIndexed()
  .draw(vertexCount, instanceCount /* optional */);

Shell-less inline vertex/fragment lambdas are also valid for simple cases.

Multiple render targets (MRT)

Use a named record for fragment out, pipeline targets, and withColorAttachment — TypeScript enforces matching keys. Keys become WGSL struct field names verbatim; no $-prefixes. Builtins (fragDepth) go in out but do not appear in targets or withColorAttachment.

Full MRT example, per-target blend/writeMask config, and the fragDepth footgun: see references/pipelines.md.

Cache bind groups and views

root.createBindGroup(...) and texture.createView(...) allocate fresh GPU objects each call. Fine for prototypes; for anything you care about, create them once at setup (near the resource they wrap), store handles in consts, and reuse. Per-frame allocation isn't slow per se, but it raises GC pressure and introduces stutters. When a view or bind group legitimately varies each frame, cache the small set you cycle through.

For vertex buffer layouts, the attribs spread trick, and the common.fullScreenTriangle helper: references/pipelines.md.

Batching work

draw()/dispatchWorkgroups() each record and submit their own single-pipeline pass. To run several pipelines in one pass (shared attachments) or batch several passes into one submission, use the typed command encoder — root['~unstable'].createCommandEncoder() → beginRenderPass/beginComputePass → pipeline.with(pass).draw(...) → pass.end() → encoder.submit(). Render bundles and raw-WebGPU encoder interop too: see references/encoders.md.

Pipelines initialize lazily on first use; pipeline.initSync() / await pipeline.initAsync() move that cost to a loading screen (see references/pipelines.md).

GPU-scoped variables

tgpu.workgroupVar(schema) — shared across all threads in a workgroup (compute only). tgpu.privateVar(schema) — thread-private. tgpu.const(schema, value) — compile-time constant embedded as a WGSL literal. Access all via .$. Full examples in references/shaders.md.

Slots

tgpu.slot<T>() is a typed placeholder; fill with .with(slot, value) at root scope (before pipeline creation) or function scope — pipelines do not accept slots in .with(). Any type fits: GPU values, functions, callbacks. Slots are the idiomatic way to build configurable/reusable shaders.

tsCopy code
const distFnSlot = tgpu.slot<(pos: d.v3f) => number>();

const rayMarcher = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  const dist = distFnSlot.$(d.vec3f(gid)); // call the injected function
});

root
  .with(distFnSlot, (pos) => {
    'use gpu';
    return std.length(pos - d.vec3f(0, 0, -5)) - 1.0; // sphere SDF
  })
  .createComputePipeline({ compute: rayMarcher });

Scalar/vector slot with a default:

tsCopy code
const colorSlot = tgpu.slot(d.vec4f(1, 0, 0, 1));
root.with(colorSlot, d.vec4f(0, 1, 0, 1)).createRenderPipeline({ ... });

Accessors

tgpu.accessor(schema, initial?) is schema-aware - the value can be a buffer binding, a constant, a literal, or a 'use gpu' function returning one. The shader is agnostic about how the value is sourced. If they can be cleanly used, they should be preferred over slots.

tsCopy code
const colorAccess = tgpu.accessor(d.vec3f);

// Fill with a uniform buffer:
root.with(colorAccess, colorUniform).createComputePipeline(...)

// Fill with a literal (inlined):
root.with(colorAccess, d.vec3f(1, 0, 0)).createComputePipeline(...)

// Fill with a GPU function:
root.with(colorAccess, () => { 'use gpu'; return computeColor(); }).createComputePipeline(...)

Write access: tgpu.mutableAccessor(schema, initial?).

Type utilities

d.InferInput<typeof Schema> — CPU-side type accepted by .write(). d.InferGPU<typeof Schema> — type inside 'use gpu' functions. d.AnyData (also importable from 'typegpu/data') — broadest schema constraint for generics. Full buffer/texture TypeScript types (TgpuBuffer, TgpuUniform, TgpuTexture, usage flags): references/types.md.

Common pitfalls

1. Numeric literals: 1.0 may strip -> abstractInt. Use d.f32(1). See types.md.
2. Outer-scope captures are constants: not runtime-mutable. Use createUniform/createMutable. See shaders.md.
3. TypedArray/ArrayBuffer alignment: bytes copied verbatim. vec3f elements are 16 bytes (12 + 4 padding). Plain arrays handle padding; typed arrays must include it.
4. Integer division: a / b on primitives is f32. Use d.i32()/d.u32() for integer semantics. See types.md.
5. Uninitialised variables: let x; is invalid - always initialise so the type can be inferred: let x = d.f32(0).
6. Ternary operators: runtime ternaries compile to WGSL select — both branches always evaluate, so branches must be side-effect-free and scalar/vector-valued (no structs/arrays/matrices; use if/else for those). Comptime-known conditions prune the dead branch entirely. See shaders.md.
7. Fragment output is always 4-component (d.vec4f; d.vec4i/d.vec4u for integer formats), even for fewer-channel formats. A pipeline with targets: { format: 'r8unorm' } or 'rg16float' still requires out: d.vec4f and return d.vec4f(...). WebGPU drops the unused channels.

Companion packages

• @typegpu/noise - real PRNG (randf), distributions (uniform, normal, hemisphere, ...), and Perlin noise (perlin2d/perlin3d) with optional precomputed gradient caches (~10x speedups). Prefer over hand-rolled hashes. See references/noise.md.

• @typegpu/sdf - 2D/3D signed distance primitives (sdDisk, sdBox2d, sdRoundedBox2d, sdBezier, sdSphere, sdBox3d, sdCapsule, sdPlane, ...) and operators (opUnion, opSmoothUnion, opSmoothDifference, opExtrudeX/Y/Z). All tgpu.fn with pinned types, callable directly from 'use gpu'. For ray marching, UI masking, AA vector drawing. See references/sdf.md.

• @typegpu/react - hooks for TypeGPU in React and React Native (useRoot, useFrame, useUniform, ...), including UI-thread render loops via react-native-worklets. See references/react.md.

• TypeGPU CLI - npx typegpu@latest scaffolds a new project; --enhance retrofits TypeGPU into an existing one. See references/setup.md.

• wgpu-matrix - canonical math library for TypeGPU. TypeGPU vectors/matrices can be passed as dst to wgpu-matrix calls to avoid allocations. See references/matrices.md for full integration patterns.