@vgpu/render 0.0.6 → 0.0.8

package/src/storage-buffer.docs.md

@@ -0,0 +1,102 @@
+# StorageBuffer
+
+`StorageBuffer` is one stable storage buffer for a single render (or compute)
+pass, rewritten as needed and change-gated by the caller. It is the
+storage-buffer counterpart to `Uniform`: it creates a `storage | copy_dst`
+buffer, a bind group layout with a single storage 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 `StorageBuffer` vs `Uniform` vs `UniformPool`
+
+Use `StorageBuffer` when the data is too large or too dynamic for a uniform:
+arrays, runtime-sized data, particle/instance state, lookup tables. Storage
+buffers can be much larger than uniforms — up to the adapter's
+`maxStorageBufferBindingSize` (typically 128 MiB) versus a uniform's 64 KiB —
+and the shader can write them with `access: "read-write"`.
+
+Use `Uniform` for the common "globals/camera per pass" case: a small, fixed,
+read-only buffer (`var<uniform>`).
+
+Use `UniformPool` only when you have **many** small 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.
+
+## `access`: read vs read-write
+
+`access` controls the bind group layout entry type. Both modes default to
+`FRAGMENT | COMPUTE` visibility:
+
+- `"read"` (default) → WGSL `var<storage, read>`, layout type
+  `"read-only-storage"`.
+- `"read-write"` → WGSL `var<storage, read_write>`, layout type `"storage"`.
+
+> Neither default includes `VERTEX`. Read-write storage is forbidden in the
+> vertex stage outright. Read-only storage is _allowed_ in the vertex stage, but
+> `maxStorageBuffersInVertexStage` is **0** on many adapters (software/CI Vulkan,
+> some mobile GPUs) — a `VERTEX`-visible default silently invalidates the layout
+> there and the draw no-ops. For vertex-stage read-only storage, pass
+> `visibility: VERTEX | …` explicitly **and** raise `maxStorageBuffersInVertexStage`
+> via `requiredLimits` when requesting the device.
+
+## Constructor
+
+```ts
+new StorageBuffer(device, {
+  size,            // byte size of the storage buffer (required)
+  label,           // optional debug label for buffer, layout, and bind group
+  access,          // "read" (default) | "read-write"
+  visibility,      // GPUShaderStageFlags; defaults by access (see above)
+  bindGroupLayout, // optional pipeline-owned layout to reuse instead of creating one
+});
+```
+
+- `size`: byte size of the storage buffer. May be far larger than a uniform.
+- `label`: optional debug label; suffixed `.bgl` / `.bg` for the layout and bind
+  group.
+- `access`: `"read"` (default, read-only storage) or `"read-write"` (writable
+  storage). Selects the layout entry type and the default visibility.
+- `visibility`: shader stages that access binding 0. Defaults to
+  `FRAGMENT | COMPUTE` for both access modes (no `VERTEX` — see the note above).
+  Ignored when `bindGroupLayout` is provided.
+- `bindGroupLayout`: reuse a pipeline-owned bind group layout instead of creating
+  one. Its binding 0 must be a storage buffer compatible with `size` and
+  `access`.
+
+## Members
+
+- `storageBuffer.gpu`: the underlying storage `GPUBuffer`.
+- `storageBuffer.buffer`: the VGPU `Buffer` wrapper around `gpu`.
+- `storageBuffer.bindGroup`: the `GPUBindGroup` to bind for the pass.
+- `storageBuffer.bindGroupLayout`: the `GPUBindGroupLayout` (created or reused).
+- `storageBuffer.size`: the buffer byte size.
+- `storageBuffer.access`: the resolved access mode (`"read"` or `"read-write"`).
+- `storageBuffer.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 contents actually change.
+- `storageBuffer.destroy()` / `storageBuffer.dispose()`: releases the backing
+  buffer once; idempotent.
+
+## Example
+
+```ts
+// A read-only array the fragment shader samples:
+//   @group(0) @binding(0) var<storage, read> values: array<f32>;
+const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+storage.write(new Float32Array(values));
+
+const pipeline = createRenderPipelineFromDescriptor(device, {
+  layout: device.gpu.createPipelineLayout({ bindGroupLayouts: [storage.bindGroupLayout] }),
+  vertex: { module, entryPoint: "vs_main" },
+  fragment: { module, entryPoint: "fs_main", targets: [{ format }] },
+});
+
+pass.setPipeline(pipeline);
+pass.setBindGroup(0, storage.bindGroup);
+pass.draw(3);
+
+// A compute-written scratch buffer:
+//   @group(0) @binding(0) var<storage, read_write> out: array<u32>;
+const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+```

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