@vgpu/render 0.0.5 → 0.0.7

package/src/uniform.docs.md

@@ -0,0 +1,70 @@
+# Uniform
+
+`Uniform` is one stable uniform buffer for a single render pass, rewritten per
+frame and change-gated by the caller. It creates a `uniform | copy_dst` buffer,
+a bind group layout with a single uniform binding at binding 0, and a bind group
+wired to that buffer. `write()` uploads bytes with `queue.writeBuffer` at a fixed
+offset — there is no dynamic offset and the bind group never changes.
+
+## When to use `Uniform` vs `UniformPool`
+
+Use `Uniform` for the common "globals/camera per pass" case: a single buffer you
+overwrite each frame, where you decide when the contents actually changed.
+
+Use `UniformPool` only when you have **many** per-draw uniforms. It is a
+dynamic-offset ring allocator: every slot binding is marked
+`hasDynamicOffset: true` and the whole CPU mirror is re-uploaded each frame. For
+one stable buffer that is the wrong shape — it forces a dynamic-offset layout and
+defeats change-gating.
+
+## Constructor
+
+```ts
+new Uniform(device, {
+  size,            // byte size of the uniform buffer (required)
+  label,           // optional debug label for buffer, layout, and bind group
+  visibility,      // GPUShaderStageFlags; defaults to VERTEX | FRAGMENT
+  bindGroupLayout, // optional pipeline-owned layout to reuse instead of creating one
+});
+```
+
+- `size`: byte size of the uniform buffer.
+- `label`: optional debug label; suffixed `.bgl` / `.bg` for the layout and bind
+  group.
+- `visibility`: shader stages that read binding 0. Defaults to
+  `GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT`. Ignored when
+  `bindGroupLayout` is provided.
+- `bindGroupLayout`: reuse a pipeline-owned bind group layout instead of creating
+  one. Its binding 0 must be a uniform buffer compatible with `size`.
+
+## Members
+
+- `uniform.gpu`: the underlying uniform `GPUBuffer`.
+- `uniform.buffer`: the VGPU `Buffer` wrapper around `gpu`.
+- `uniform.bindGroup`: the `GPUBindGroup` to bind for the pass.
+- `uniform.bindGroupLayout`: the `GPUBindGroupLayout` (created or reused).
+- `uniform.size`: the buffer byte size.
+- `uniform.write(data, offset = 0)`: uploads `data` via
+  `device.queue.writeBuffer(gpu, offset, data)`. No dynamic offset; the bind group
+  is unchanged. Call only when the uniform contents actually change.
+- `uniform.destroy()` / `uniform.dispose()`: releases the backing buffer once;
+  idempotent.
+
+## Example
+
+```ts
+const uniform = new Uniform(device, { size: 64, label: "globals" });
+
+// Per frame, only when inputs changed:
+if (dirty) uniform.write(globalsBytes);
+
+const pipeline = createRenderPipelineFromDescriptor(device, {
+  layout: device.gpu.createPipelineLayout({ bindGroupLayouts: [uniform.bindGroupLayout] }),
+  vertex: { module, entryPoint: "vs_main" },
+  fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+});
+
+pass.setPipeline(pipeline);
+pass.setBindGroup(0, uniform.bindGroup);
+pass.draw(3);
+```