编写或调试 TypeGPU 的 shader、buffer…

当任务涉及 TypeGPU（typegpu/tgpu、'use gpu'、d.*、std.*、@typegpu/react 等）而非原生 WebGPU/WGSL/Three.js/Babylon.js/WebGL 时，按本经验操作。

适用场景

解决思路

1. 使用 `import { tgpu, d, std, common } from 'typegpu';` 引入 TypeGPU。
2. 用 `await tgpu.init()` 请求 GPU device 并创建 root；或用 `tgpu.initFromDevice({ device })` 包装已有 GPUDevice。
3. 用 `root.configureContext({ canvas, alphaMode: 'premultiplied' })` 配置 canvas 上下文。
4. 应用启动时只创建一个 root；不同 root 创建的资源不能交互。
5. 清理时调用 `root.destroy()`，它会销毁通过该 root 创建的所有资源；如果 root 来自 `tgpu.init`（不是 `initFromDevice`），也销毁 device。
6. 写任何 shader 或 GPU function 前先读 `references/types.md`，掌握抽象类型解析、何时必须或冗余使用 `d.f32()`、向量构造重载、`tgpu.fn` 签名的 sampler/texture schema、CPU 侧 `TgpuBuffer`/`TgpuTexture` 类型。
7. 写任何非平凡 shader 逻辑前先读 `references/shaders.md`，掌握 `std.range`、`tgpu.unroll`、三元/逻辑运算符语义、`tgpu.comptime`、外层作用域捕获规则、三个阶段 builtin 参考、`console.log`、values-vs-references 处理。
8. 手写任何 math/utility 前先查 `references/std.md` 的完整 `std` 函数列表（math、comparison/boolean vectors、matrix builders、texture、atomics、packing、subgroups、environment probes）。
9. 涉及 vertex buffers/layouts、`attribs` wiring、MRT、fullscreen triangle、depth/stencil、blend modes、`fragDepth` 输出、加载 3D 模型（`@loaders.gl`）、resolve API 时读 `references/pipelines.md`。
10. 涉及 3D 工作（view/projection matrices、animated transforms、model loading）时读 `references/matrices.md`，掌握 `wgpu-matrix` 集成、column-major layout、camera uniforms、`common.writeSoA`、fast-path CPU writes。
11. 涉及 texture creation、views、samplers、storage textures、mipmaps、multisampling 时读 `references/textures.md`。
12. 使用 `@typegpu/noise`（random、distributions、Perlin 2D/3D）时读 `references/noise.md`。
13. 使用 `@typegpu/sdf`（2D/3D primitives、operators、ray marching、AA masking）时读 `references/sdf.md`。
14. 涉及 typed command encoders、multi-pipeline render/compute passes、render bundles、batched submission、raw-WebGPU encoder interop 时读 `references/encoders.md`。
15. 做 GPU timing via timestamp queries 时读 `references/timing.md`，区分 `withPerformanceCallback` 与 shared query set，使用 `available` guard，并理解 per-pass timings overlap。
16. 使用 `@typegpu/react` hooks（useRoot、useFrame、useUniform 等）或 React Native worklet render loops 时读 `references/react.md`。
17. 配置 TypeGPU CLI、安装、`unplugin-typegpu` build plugin、`tsover` operator overloading 或排障时读 `references/setup.md`。
18. 需要 buffer reinterpretation、indirect drawing/dispatch、ArrayBuffer IO、minification、warning silencing、`root.unwrap` 时读 `references/advanced.md`。
19. 用 `d.*` schema 同时定义 GPU 类型、CPU buffer layout 和 TypeScript 类型，避免手动 alignment、type mapping 或 casting。
20. 用构建插件 `unplugin-typegpu` 转换带 `'use gpu'` 标记的 TypeScript，实现运行时 WGSL 转译、类型推断和跨 CPU/GPU 边界多态。
21. 目标 TypeGPU `0.12`；旧版本先验证 API 可用性再使用本文示例和模式。
22. Scalars 使用 `d.f32`、`d.i32`、`d.u32`、`d.f16`；`f16` 需要 `'shader-f16'` device feature。
23. `d.bool` 不是 host-shareable，buffer 中用 `d.u32` 代替。
24. Vectors/matrices 使用 `d.vec2f` 到 `d.vec4f`（f32）、`d.vec2i` 到 `d.vec4i`（i32）、`d.vec2u` 到 `d.vec4u`（u32）、`d.vec2h` 到 `d.vec4h`（f16）、`d.vec2b` 到 `d.vec4b`（bool，shader-side only，不 host-shareable）、`d.mat2x2f`、`d.mat3x3f`、`d.mat4x4f`。
25. 实例类型用 `d.vec3f()` -> `d.v3f`、`d.mat4x4f()` -> `d.m4x4f`。
26. 优先使用向量构造重载，从 scalars、小向量和 swizzles 任意混合凑足分量，例如 `d.vec4f(rgb, 1)`、`d.vec3f(v.xy, newZ)`，避免手动拆分量。
27. 用 `d.struct({ ... })` 定义 compound struct，例如 Particle 含 position/velocity/color。
28. 用 `d.arrayOf(Particle, 1000)` 定义固定大小数组。
29. 用无 count 的 `d.arrayOf(Element)` 得到函数 `(n: number) => WgslArray<Element>`；将函数本身（unsized）传给 bind group layouts，用 count 调用（sized）创建 buffer。
30. 给普通数组 layout 时写 `data: { storage: d.arrayOf(d.f32), access: 'mutable' }`；创建 buffer 时写 `root.createBuffer(d.arrayOf(d.f32, 1024)).$usage('storage')`。
31. 给 runtime-sized struct 时用工厂函数 `RuntimeStruct = (n: number) => d.struct({ counter: d.atomic(d.u32), items: d.arrayOf(d.f32, n) })`，layout 传 `RuntimeStruct`，buffer 传 `RuntimeStruct(1024)`。
32. 不要将 unsized schema 直接传给 `createBuffer`，CPU 侧必须知道 size。
33. 用 `'use gpu'` 标记 TypeScript 函数，让 TypeGPU 编译成 WGSL。
34. 写 helper math 和 flexible utilities 时用 plain callback（无显式签名），如 `const rotate = (v: d.v2f, angle: number) => { 'use gpu'; ... }`。
35. 在 plain callback 中利用 `number` 参数和 `d.v2f | d.v3f` 等 union 的多态；TypeGPU 会为每个唯一调用点类型组合生成一个 WGSL overload。
36. 从外层作用域捕获的值会被内联为 WGSL 字面量；运行时会变化的值改用 buffers/uniforms。
37. 库代码或需要固定 WGSL 接口时用 `tgpu.fn([d.vec2f, d.f32], d.vec2f)((v, angle) => { 'use gpu'; ... })` 固定签名。
38. 写 compute entrypoint 用 `tgpu.computeFn({ workgroupSize: [64], in: { gid: d.builtin.globalInvocationId } })((input) => { 'use gpu'; ... })`，输入 `input.gid` 为 `d.v3u`。
39. 写 vertex entrypoint 用 `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 }; })`。
40. 写 fragment entrypoint 用 `tgpu.fragmentFn({ in: { fragUv: d.vec2f }, out: d.vec4f })((input) => { 'use gpu'; return d.vec4f(input.fragUv, 0, 1); })`。
41. Vertex `in` 可包含 builtins：`d.builtin.vertexIndex`、`d.builtin.instanceIndex`。
42. 创建仅带 schema 的 buffer：`root.createBuffer(d.arrayOf(Particle, 1000)).$usage('storage')`。
43. 创建带非零 typed initial value 的 buffer：`root.createBuffer(Config, { time: 1, scale: 2.0 }).$usage('uniform')`；所有 buffer 默认零初始化。
44. 创建带 initializer callback 的 buffer 并保持 mapped 以走最便宜 CPU 路径：`root.createBuffer(Schema, (mappedBuffer) => { mappedBuffer.write([10, 20], { startOffset: firstChunk.offset }); mappedBuffer.write([30, 40], { startOffset: secondChunk.offset }); })`。
45. 包装已有 GPUBuffer：`root.createBuffer(d.u32, existingGPUBuffer); buf.write(12);`，你拥有其生命周期和 flags。
46. 按 shader access 设置 usage flags：`'uniform'` -> `var<uniform>`；`'storage'` -> `var<storage, read>`（配合 `access: 'mutable'` 为 `read_write`）；`'vertex'` -> vertex input，配合 `tgpu.vertexLayout`；`'index'` -> index buffer，仅 `d.u16` 或 `d.u32` 数组；`'indirect'` -> indirect dispatch/draw。
47. 所有 buffer 自动获得 `COPY_SRC | COPY_DST`；用 `$addFlags(GPUBufferUsage.X)` 添加 `$usage` 未覆盖的 flag。
48. 用 `.write(value)` 写 buffer，它会处理 alignment；输入形式从慢到快：typed instance `d.vec3f(1, 2, 3)`、plain JS array/tuple `[1, 2, 3]`、TypedArray `new Float32Array([1, 2, 3])`（字节原样复制，必须包含 WGSL padding）、ArrayBuffer `rawBytes`（最大吞吐，字节原样复制）。
49. 在 setup 时缓存 plain arrays 或 `Float32Array` 并复用。
50. 遵循 padding rules：`vec3f` 元素占 16 bytes（12 + 4 padding），`mat3x3f` 有 per-column padding；详见 `references/matrices.md`。
51. 用 slice write 更新子区域：用 `d.memoryLayoutOf(schema, (a) => a[3])` 获取 byte offset，再 `buffer.write([4, 5, 6], { startOffset: layout.offset })`。
52. 用 `.patch(data)` 只更新特定 struct fields 或 array indices：`planetBuffer.patch({ mass: 123.1, colors: { 2: [1, 0, 0], 4: d.vec3f(0, 0, 1) } })`。
53. 用 `common.writeSoA(buffer, { field: Float32Array, ... })` 将分离的 packed per-field arrays 散射到 GPU 的 AoS layout 并补正确 padding，适合 particle systems、simulations、model loading。
54. 用 `destBuffer.copyFrom(srcBuffer)` 做 GPU 侧 copy，schema 必须匹配；用 `buffer.clear()` 清零；用 `buffer.destroy()` 清理；`copyFrom` 和 `clear` 可接受可选 command encoder。
55. 用 `const data = await buffer.read();` 读回匹配 schema 的 typed JS value。
56. 优先用 shorthand fixed resources 跳过手动 bind groups：`root.createMutable(d.arrayOf(Particle, 1000))` 对应 `var<storage, read_write>`，`root.createUniform(Config)` 对应 `var<uniform>`，`root.createReadonly(d.arrayOf(d.f32, N))` 对应 `var<storage, read>`。
57. 在 shader 中通过 `particles.$`、`config.$` 等访问 fixed resources。
58. 需要按帧交换资源、管理 `@group` indices 或跨 pipelines 共享 layouts 时，从 fixed resources 切换到 manual bind groups。
59. 用 `buffer.as('uniform' | 'readonly' | 'mutable')` 将手动创建的 buffer 转为同类 binding（需要匹配 `$usage`），以便在 shader 中用 `.$` 访问。
60. 用 `tgpu.bindGroupLayout({ config: { uniform: ConfigSchema }, particles: { storage: d.arrayOf(Particle), access: 'mutable' }, mySampler: { sampler: 'filtering' }, myTexture: { texture: d.texture2d(d.f32) } })` 创建 bind group layout；sampler 可为 `'filtering' | 'non-filtering' | 'comparison'`。
61. 在 shader 中通过 `layout.$.config`、`layout.$.particles` 等访问 manual bind group layout。
62. 用 `root.createBindGroup(layout, { config: configBuffer, particles: particleBuffer, mySampler: tgpuSampler, myTexture: textureOrView })` 创建 bind group。
63. 用 `pipeline.with(bindGroup).dispatchWorkgroups(N)` 绑定并执行 compute。
64. 来自 `createUniform`/`createMutable`/`createReadonly` 的 buffer bindings 可直接作为 bind group entries，无需 unwrap 到 buffer。
65. 仅在与 hardcode group indices 的原生 WGSL 集成时用 `layout.$idx(0)` 指定显式 `@group` index。
66. 标准 compute pipeline 用 `root.createComputePipeline({ compute: myComputeFn })`，自行控制 workgroup sizing 并调用 `pipeline.with(bindGroup).dispatchWorkgroups(Math.ceil(N / 64))`。
67. 用 guarded compute pipeline 让 TypeGPU 自动处理 workgroup sizing 和 bounds checking；callback 参数个数决定 0D 到 3D：`root.createGuardedComputePipeline(() => { 'use gpu'; })`、`(x: number)`、`(x: number, y: number)`、`(x: number, y: number, z: number)`。
68. 对 guarded pipeline 用 `dispatchThreads`，传 thread counts 而不是 workgroup counts，例如 `p2.with(bindGroup).dispatchThreads(width, height)`；TypeGPU 内部选择 workgroup sizes 并注入 bounds guard 使范围外 threads 为 no-ops。
69. 在 guarded pipeline 中不要使用 `globalInvocationId` 等 WGSL builtins，改用 callback 参数。
70. 遵循 WebGPU 坐标约定：NDC z 是 `[0, 1]` 而不是 `[-1, 1]`；不要直接复制 `gluPerspective`，用 `wgpu-matrix` 的 `mat4.perspective`（已针对 `[0, 1]`）或 `mat4.perspectiveReverseZ` 获得更好 depth precision。
71. Framebuffer `(0, 0)` 在 top-left，`+y` 向下，与 OpenGL 相反；fragment shader 中 `d.builtin.position.xy` 是 pixel-space 且采用该原点。
72. Texture UV `(0, 0)` 在 top-left；不要预翻转 `v`，`createImageBitmap` 已匹配。
73. Matrices 是 column-major：`d.mat4x4f(c0, c1, c2, c3)` 接受 columns；shader 内用 `mat.columns[c][r]`，拒绝 plain `mat[i]`；组合顺序为 `projection * view * model * position`。
74. 创建 render pipeline：`root.createRenderPipeline({ vertex: myVertex, fragment: myFragment, targets: { format: presentationFormat }, primitive?: GPUPrimitiveState, depthStencil?: GPUDepthStencilState, multisample?: GPUMultisampleState })`。
75. 录制 render：`pipeline.with(bindGroup).withColorAttachment({ view: context, ... }).withDepthStencilAttachment({ ... }).withIndexBuffer(indexBuffer).draw(vertexCount, instanceCount)`；`loadOp`/`storeOp`/`clearValue` 有默认值；`withIndexBuffer` 启用 `.drawIndexed()`。
76. 简单场景可用 shell-less inline vertex/fragment lambdas。
77. 多 render targets（MRT）时，fragment `out`、pipeline `targets`、`withColorAttachment` 都用 named record，让 TypeScript 强制 matching keys；keys 会原样成为 WGSL struct field names，不要加 `$` 前缀。
78. Builtins（如 `fragDepth`）放在 `out`，但不要出现在 `targets` 或 `withColorAttachment`。
79. 缓存 bind groups 和 views：`root.createBindGroup(...)` 和 `texture.createView(...)` 每次调用都会分配新 GPU 对象；原型可随意，生产应在 setup 时靠近资源创建一次，存入 `const` 并复用，以减少 GC 压力和 stutter；如果 view 或 bind group 每帧变化，缓存循环使用的小集合。
80. 做 vertex buffer layouts、`attribs` spread trick、`common.fullScreenTriangle` 时看 `references/pipelines.md`。
81. `draw()`/`dispatchWorkgroups()` 各自记录并提交自己的 single-pipeline pass；要在同一个 pass 运行多个 pipelines（共享 attachments）或将多个 passes 批处理为一次 submission，用 typed command encoder：`root['~unstable'].createCommandEncoder()` → `beginRenderPass`/`beginComputePass` → `pipeline.with(pass).draw(...)` → `pass.end()` → `encoder.submit()`。
82. 需要 render bundles 或 raw-WebGPU encoder interop 时看 `references/encoders.md`。
83. Pipelines 首次使用时懒初始化；用 `pipeline.initSync()` 或 `await pipeline.initAsync()` 把初始化成本移到 loading screen。
84. 用 `tgpu.workgroupVar(schema)` 定义 workgroup 内所有线程共享变量，仅 compute 可用；用 `tgpu.privateVar(schema)` 定义线程私有变量；用 `tgpu.const(schema, value)` 定义编译期常量并作为 WGSL literal 嵌入；都通过 `.$` 访问。
85. 用 `tgpu.slot<T>()` 定义 typed placeholder，在 root scope（pipeline 创建前）或 function scope 用 `.with(slot, value)` 填充；pipelines 的 `.with()` 不接受 slots；slot 可接受 GPU values、functions、callbacks，是构建可配置/可复用 shaders 的惯用方式。
86. 用 slot 注入函数示例：`const distFnSlot = tgpu.slot<(pos: d.v3f) => number>();`，shader 内调用 `distFnSlot.$(d.vec3f(gid))`，然后 `root.with(distFnSlot, (pos) => { 'use gpu'; return std.length(pos - d.vec3f(0, 0, -5)) - 1.0; }).createComputePipeline({ compute: rayMarcher })`。
87. 标量/向量 slot 可带默认值：`const colorSlot = tgpu.slot(d.vec4f(1, 0, 0, 1)); root.with(colorSlot, d.vec4f(0, 1, 0, 1)).createRenderPipeline({ ... });`。
88. 如果 accessors 能干净使用，优先用 accessors 而非 slots。
89. 用 `tgpu.accessor(schema, initial?)` 创建 schema-aware accessor；其值可以是 buffer binding、constant、literal 或返回这些的 `'use gpu'` function，shader 不关心来源。
90. 用 uniform buffer 填充 accessor：`root.with(colorAccess, colorUniform).createComputePipeline(...)`；用 literal 填充并内联：`root.with(colorAccess, d.vec3f(1, 0, 0)).createComputePipeline(...)`；用 GPU function 填充：`root.with(colorAccess, () => { 'use gpu'; return computeColor(); }).createComputePipeline(...)`。
91. 需要写访问时用 `tgpu.mutableAccessor(schema, initial?)`。
92. 用 `d.InferInput<typeof Schema>` 表示 `.write()` 接受的 CPU 侧类型；用 `d.InferGPU<typeof Schema>` 表示 `'use gpu'` 函数内的类型；用 `d.AnyData`（也可从 `'typegpu/data'` 导入）作为泛型的最宽 schema 约束。
93. 查完整 buffer/texture TypeScript 类型（`TgpuBuffer`、`TgpuUniform`、`TgpuTexture`、usage flags）看 `references/types.md`。
94. 避免 pitfall：numeric literals `1.0` 可能被剥离成 `abstractInt`，需要时用 `d.f32(1)`。
95. 避免 pitfall：外层作用域捕获是常量，不是 runtime-mutable；需要可变性用 `createUniform`/`createMutable`。
96. 避免 pitfall：TypedArray/ArrayBuffer 字节原样复制；`vec3f` 元素是 16 bytes（12 + 4 padding）；plain arrays 会处理 padding，typed arrays 必须自己包含 padding。
97. 避免 pitfall：primitives 上的 `a / b` 是 `f32`；需要整数语义用 `d.i32()`/`d.u32()`。
98. 避免 pitfall：`let x;` 无效；总是初始化以便推断类型，例如 `let x = d.f32(0)`。
99. 避免 pitfall：runtime ternaries 编译为 WGSL `select`，两个 branch 总会求值，因此 branch 必须无副作用且为 scalar/vector-valued（不能是 structs/arrays/matrices；这些用 `if`/`else`）；comptime-known 条件会完全剪除 dead branch。
100. 避免 pitfall：fragment output 总是 4-component（`d.vec4f`；整数格式用 `d.vec4i`/`d.vec4u`），即使目标格式通道更少；`targets: { format: 'r8unorm' }` 或 `'rg16float'` 仍要求 `out: d.vec4f` 并 `return d.vec4f(...)`；WebGPU 会丢弃未用通道。
101. 使用 `@typegpu/noise` 的 `randf`、distributions（uniform、normal、hemisphere 等）和 `perlin2d`/`perlin3d`，可选预计算 gradient caches（约 10x 加速）；优先用它而不是手写 hash。
102. 使用 `@typegpu/sdf` 的 2D/3D SDF primitives（`sdDisk`、`sdBox2d`、`sdRoundedBox2d`、`sdBezier`、`sdSphere`、`sdBox3d`、`sdCapsule`、`sdPlane` 等）和 operators（`opUnion`、`opSmoothUnion`、`opSmoothDifference`、`opExtrudeX/Y/Z`）；它们都是 pinned types 的 `tgpu.fn`，可直接从 `'use gpu'` 调用，适合 ray marching、UI masking、AA vector drawing。
103. 使用 `@typegpu/react` hooks（`useRoot`、`useFrame`、`useUniform` 等）支持 React 和 React Native，包括通过 `react-native-worklets` 在 UI thread 渲染循环。
104. 用 TypeGPU CLI：`npx typegpu@latest` 脚手架新项目；`--enhance` 将 TypeGPU 改造进现有项目。
105. 使用 `wgpu-matrix` 作为 TypeGPU 的规范数学库；可将 TypeGPU vectors/matrices 作为 `dst` 传给 `wgpu-matrix` 调用以避免分配。

适用边界 · 注意事项

• 不要用于原生 WebGPU（直接使用 GPUDevice/GPURenderPipeline 而没有 tgpu）、仅 WGSL 问题、Three.js、Babylon.js 或 WebGL。
• 不要用于未使用 TypeGPU schema API（d.*、tgpu.*、std.*）的 WebGPU 代码。
• TypeGPU 0.12 以外的旧版本可能缺少本文 API；先验证 API 可用性再依赖示例或推荐模式。