typegpu（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.11.2. 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, 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 — full std library listing, loops (std.range, tgpu.unroll), tgpu.comptime, outer-scope capture rules, complete builtin reference for all three shader stages, console.log. Read this for any non-trivial shader logic.

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/setup.md — install, unplugin-typegpu build plugin, tsover operator overloading
• references/advanced.md — buffer reinterpretation, indirect drawing/dispatch, custom encoders

Setup

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.

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

d.f32    d.i32    d.u32    d.f16
// d.bool is NOT host-shareable - use d.u32 in buffers

Vectors and matrices

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.mat2x2f   d.mat3x3f   d.mat4x4f

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

Vector constructors are richly overloaded - use them. They compose from any mix of scalars and smaller vectors that adds up to the right component count:

d.vec3f()              // zero-init: (0, 0, 0)
d.vec3f(1)             // broadcast:  (1, 1, 1)
d.vec3f(1, 2, 3)       // individual components
d.vec3f(someVec2, 1)   // vec2 + scalar
d.vec3f(1, someVec2)   // scalar + vec2

d.vec4f()              // zero-init: (0, 0, 0, 0)
d.vec4f(0.5)           // broadcast:  (0.5, 0.5, 0.5, 0.5)
d.vec4f(rgb, 1)        // vec3 + scalar (common: color + alpha)
d.vec4f(v2a, v2b)      // two vec2s
d.vec4f(1, uv, 0)      // scalar + vec2 + scalar

Swizzles (.xy, .zw, .rgb, .ba, etc.) return vector instances that work as constructor arguments: d.vec4f(pos.xy, vel.zw).

Prefer these overloads over manual component decomposition. Instead of d.vec3f(v.x, v.y, newZ), write d.vec3f(v.xy, newZ).

Compound types

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.

// 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.

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.

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

Shader entrypoints

// 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, and type inference: see references/shaders.md.

Values vs references — the most common source of ResolutionError. See references/shaders.md.

Idiomatic patterns (vector ops, struct constructors, register pressure): see references/shaders.md.

Buffers

Creating

// 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:

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:

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).

Reading

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:

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.

Bind group layouts (manual binding)

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);

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

Compute pipelines

// 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

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.

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 pipeline, root, or function scope. Any type fits: GPU values, functions, callbacks. Slots are the idiomatic way to build configurable/reusable shaders.

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:

const colorSlot = tgpu.slot(d.vec4f(1, 0, 0, 1));
pipeline.with(colorSlot, d.vec4f(0, 1, 0, 1)).draw(3);

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.

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. AnyData (from 'typegpu') — 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 aren't supported. Use std.select(falseVal, trueVal, condition).
7. Fragment output is always d.vec4f, 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.
• 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.