@vgpu/render 0.0.6 → 0.0.8

package/dist/pipeline.js

@@ -1,4 +1,5 @@
-import { Shader, VGPUError } from "@vgpu/core";
+import { VGPUError } from "@vgpu/core";
+import { toRenderPipelineDescriptor } from "./pipeline-descriptor.js";
 // Warn once per JS process. This keeps compatibility fallback visible without spamming
 // apps that intentionally warm up multiple pipelines on implementations without
 // GPUDevice.createRenderPipelineAsync().
@@ -7,64 +8,47 @@ export function createRenderPipeline(device, opts) {
     return device.gpu.createRenderPipeline(toRenderPipelineDescriptor(opts));
 }
 export async function createRenderPipelineAsync(device, opts) {
-    const descriptor = toRenderPipelineDescriptor(opts);
+    return createPipelineAsync(device, toRenderPipelineDescriptor(opts), opts.fallback, "createRenderPipelineAsync");
+}
+/**
+ * Create a render pipeline from a raw, hand-built `GPURenderPipelineDescriptor`.
+ *
+ * @remarks
+ * Use this when you already own a native descriptor and only want VGPU's
+ * `Device` wrapper to forward it — no `RenderPipelineOptions` reshape. The
+ * descriptor is passed through unchanged.
+ */
+export function createRenderPipelineFromDescriptor(device, descriptor) {
+    return device.gpu.createRenderPipeline(descriptor);
+}
+/**
+ * Async variant of {@link createRenderPipelineFromDescriptor} with the same
+ * async→sync compatibility fallback as {@link createRenderPipelineAsync}.
+ *
+ * @remarks
+ * The descriptor is forwarded unchanged. When `GPUDevice.createRenderPipelineAsync`
+ * is unavailable, the default `fallback: "sync"` emits a once-only diagnostic and
+ * calls the synchronous path; pass `fallback: "throw"` for a structured `VGPUError`.
+ */
+export async function createRenderPipelineFromDescriptorAsync(device, descriptor, fallback) {
+    return createPipelineAsync(device, descriptor, fallback, "createRenderPipelineFromDescriptorAsync");
+}
+async function createPipelineAsync(device, descriptor, fallback, where) {
     const createAsync = device.gpu.createRenderPipelineAsync;
     if (typeof createAsync === "function") {
         return createAsync.call(device.gpu, descriptor);
     }
-    if ((opts.fallback ?? "sync") === "throw") {
+    if ((fallback ?? "sync") === "throw") {
         throw new VGPUError({
             code: "VGPU-RENDER-PIPELINE-ASYNC-UNAVAILABLE",
             message: "GPUDevice.createRenderPipelineAsync is unavailable on this WebGPU implementation.",
             fix: "Use fallback: 'sync' for compatibility or call createRenderPipeline() explicitly during setup/warmup.",
-            where: "createRenderPipelineAsync",
+            where,
         });
     }
     warnAsyncFallbackOnce();
     return device.gpu.createRenderPipeline(descriptor);
 }
-function toRenderPipelineDescriptor(opts) {
-    const descriptor = {
-        label: opts.label,
-        layout: opts.layout ?? "auto",
-        vertex: {
-            module: stageModule(opts.vertex, opts.shader, "vertex"),
-            entryPoint: stageEntryPoint(opts.vertex),
-            constants: opts.vertex.constants,
-            buffers: opts.vertex.buffers ? [...opts.vertex.buffers] : undefined,
-        },
-        primitive: opts.primitive,
-        depthStencil: opts.depthStencil,
-        multisample: opts.multisample,
-    };
-    if (opts.fragment) {
-        descriptor.fragment = {
-            module: stageModule(opts.fragment, opts.shader, "fragment"),
-            entryPoint: stageEntryPoint(opts.fragment),
-            constants: opts.fragment.constants,
-            targets: [...opts.fragment.targets],
-        };
-    }
-    return descriptor;
-}
-function stageModule(stage, fallback, stageName) {
-    const module = stage.module ?? stage.shader ?? fallback;
-    if (!module) {
-        throw new VGPUError({
-            code: "VGPU-RENDER-PIPELINE-MISSING-SHADER",
-            message: `Missing shader module for ${stageName} stage.`,
-            fix: "Pass options.shader for a shared module or pass vertex/fragment module or shader.",
-            where: `createRenderPipeline.${stageName}`,
-        });
-    }
-    return isShader(module) ? module.gpu : module;
-}
-function stageEntryPoint(stage) {
-    return stage.entryPoint ?? stage.entry;
-}
-function isShader(input) {
-    return input instanceof Shader;
-}
 export function __resetCreateRenderPipelineAsyncFallbackWarningForTests() {
     didWarnAboutAsyncFallback = false;
 }

package/dist/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAYtE,uFAAuF;AACvF,gFAAgF;AAChF,yCAAyC;AACzC,IAAI,yBAAyB,GAAG,KAAK,CAAC;AAItC,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,IAA2B;IAC9E,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAc,EACd,IAA2B;IAE3B,OAAO,mBAAmB,CACxB,MAAM,EACN,0BAA0B,CAAC,IAAI,CAAC,EAChC,IAAI,CAAC,QAAQ,EACb,2BAA2B,CAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kCAAkC,CAChD,MAAc,EACd,UAAuC;IAEvC,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,uCAAuC,CAC3D,MAAc,EACd,UAAuC,EACvC,QAAsC;IAEtC,OAAO,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,yCAAyC,CAAC,CAAC;AACtG,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,MAAc,EACd,UAAuC,EACvC,QAAiD,EACjD,KAAyB;IAEzB,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACzD,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;QACtC,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CAAC;YAClB,IAAI,EAAE,wCAAwC;YAC9C,OAAO,EAAE,mFAAmF;YAC5F,GAAG,EAAE,uGAAuG;YAC5G,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,qBAAqB,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,uDAAuD;IACrE,yBAAyB,GAAG,KAAK,CAAC;AACpC,CAAC;AAED,SAAS,qBAAqB;IAC5B,IAAI,yBAAyB;QAAE,OAAO;IACtC,yBAAyB,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,CACxB,yKAAyK,CAC1K,CAAC;AACJ,CAAC"}

package/dist/render-pass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-pass.d.ts","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,sBAAsB,EAAE,GAAG,WAAW,CAAC;AASvF,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,WAAW,CAA8B;gBAEpB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;IAQpE,IAAI,GAAG,IAAI,oBAAoB,CAS9B;IAED,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAIxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,IAAI;IAIxD,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAcrG,GAAG,IAAI,IAAI;IAQX,OAAO,IAAI,IAAI;CAGhB;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAGzH"}
+{"version":3,"file":"render-pass.d.ts","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,sBAAsB,EAAE,GAAG,WAAW,CAAC;AASvF,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,WAAW,CAA8B;gBAEpB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;IAQpE,IAAI,GAAG,IAAI,oBAAoB,CAS9B;IAED,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAQxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,IAAI;IAIxD,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAcrG,GAAG,IAAI,IAAI;IAQX,OAAO,IAAI,IAAI;CAGhB;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAGzH"}

package/dist/render-pass.js

@@ -28,6 +28,10 @@ export class RenderPass {
         this.gpu.setPipeline(pipeline);
     }
     setBindGroup(index, group, dynamicOffsets) {
+        if (dynamicOffsets === undefined) {
+            this.gpu.setBindGroup(index, group);
+            return;
+        }
         this.gpu.setBindGroup(index, group, dynamicOffsets);
     }
     setVertexBuffer(slot, buffer, offset = 0, size) {

package/dist/render-pass.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-pass.js","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-pass.js","sourceRoot":"","sources":["../src/render-pass.ts"],"names":[],"mappings":"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"}

package/dist/storage-buffer.d.ts

@@ -0,0 +1,81 @@
+import { Buffer, type Device } from "@vgpu/core";
+export interface StorageBufferOptions {
+    /** Byte size of the storage buffer. Must be a positive number. Storage buffers may be far larger than uniforms (up to the adapter's `maxStorageBufferBindingSize`, typically 128 MiB). */
+    readonly size: number;
+    /** Optional debug label forwarded to the buffer, bind group layout, and bind group. */
+    readonly label?: string;
+    /**
+     * Whether the shader only reads the buffer (`"read"`, the default → `var<storage, read>`)
+     * or also writes it (`"read-write"` → `var<storage, read_write>`). This selects the
+     * bind group layout entry type (`"read-only-storage"` vs `"storage"`) and changes the
+     * default {@link StorageBufferOptions.visibility}.
+     */
+    readonly access?: "read" | "read-write";
+    /**
+     * Shader stages that access binding 0. Defaults to `FRAGMENT | COMPUTE` for both access modes —
+     * no `VERTEX`. Read-write storage is forbidden in the vertex stage; read-only storage is allowed
+     * there but `maxStorageBuffersInVertexStage` is 0 on many adapters (software/CI Vulkan, some
+     * mobile GPUs), so vertex-stage storage is opt-in: pass `visibility` explicitly and raise that
+     * limit via `requiredLimits`. Ignored when {@link StorageBufferOptions.bindGroupLayout} is provided.
+     */
+    readonly visibility?: GPUShaderStageFlags;
+    /**
+     * Reuse a pipeline-owned bind group layout instead of creating one.
+     * The layout's binding 0 must be a storage buffer compatible with `size` and `access`.
+     */
+    readonly bindGroupLayout?: GPUBindGroupLayout;
+}
+/**
+ * A single stable storage buffer for one render (or compute) pass, rewritten as needed.
+ *
+ * @remarks
+ * `StorageBuffer` is the storage-buffer counterpart to {@link Uniform}. Reach for it when
+ * the data is too large or too dynamic for a uniform: arrays, runtime-sized data, particle
+ * state, lookup tables. Storage buffers can be much bigger than uniforms (up to the adapter's
+ * `maxStorageBufferBindingSize`, typically 128 MiB, versus a uniform's 64 KiB) and can be
+ * written by the shader when `access: "read-write"`.
+ *
+ * Like `Uniform`, it owns exactly one buffer at binding 0 with a fixed (non-dynamic) offset,
+ * and the caller decides when to {@link StorageBuffer.write}. Unlike {@link UniformPool} — a
+ * dynamic-offset ring allocator for many small per-draw uniforms — there is no dynamic offset
+ * and the bind group never moves.
+ *
+ * `access` controls the layout entry type; both modes default to `FRAGMENT | COMPUTE` visibility:
+ * - `"read"` (default) → `var<storage, read>`, layout type `"read-only-storage"`.
+ * - `"read-write"` → `var<storage, read_write>`, layout type `"storage"`.
+ * Neither default includes `VERTEX`: read-write storage is forbidden in the vertex stage, and
+ * read-only storage — though legal there — needs `maxStorageBuffersInVertexStage > 0`, which is 0
+ * on many adapters (software/CI Vulkan, some mobile GPUs). For vertex-stage read-only storage, pass
+ * `visibility: VERTEX | …` explicitly and raise the limit via `requiredLimits`; do not rely on the default.
+ *
+ * @example
+ * ```ts
+ * // A read-only array the fragment shader samples (var<storage, read> values: array<f32>):
+ * const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+ * storage.write(new Float32Array(values));
+ * pass.setBindGroup(0, storage.bindGroup);
+ *
+ * // A compute-written scratch buffer (var<storage, read_write> out: array<u32>):
+ * const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+ * ```
+ */
+export declare class StorageBuffer {
+    readonly device: Device;
+    readonly size: number;
+    readonly access: "read" | "read-write";
+    readonly buffer: Buffer;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    readonly bindGroup: GPUBindGroup;
+    private destroyed;
+    constructor(device: Device, opts: StorageBufferOptions);
+    /** The underlying storage `GPUBuffer`. */
+    get gpu(): GPUBuffer;
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the contents actually change.
+     */
+    write(data: BufferSource, offset?: number): void;
+    destroy(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=storage-buffer.d.ts.map

package/dist/storage-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-buffer.d.ts","sourceRoot":"","sources":["../src/storage-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAA0C,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,oBAAoB;IACnC,0LAA0L;IAC1L,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;CAC/C;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,aAAa;IAQZ,QAAQ,CAAC,MAAM,EAAE,MAAM;IAPnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,OAAO,CAAC,SAAS,CAAS;gBAEL,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB;IAmB/D,0CAA0C;IAC1C,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,IAAI;IAI3C,OAAO,IAAI,IAAI;IAMf,OAAO,IAAI,IAAI;CAGhB"}

package/dist/storage-buffer.js

@@ -0,0 +1,91 @@
+import { bind, createBindGroup, createBindGroupLayout } from "@vgpu/core";
+// Both access modes default to FRAGMENT | COMPUTE (no VERTEX):
+// - read-write storage is ILLEGAL in the vertex stage (WebGPU forbids it).
+// - read-only storage IS legal in vertex, but maxStorageBuffersInVertexStage is 0 on many adapters
+//   (software/CI Vulkan, some mobile GPUs), so a VERTEX-visible default would silently invalidate
+//   the layout there (the draw no-ops). Vertex-stage read-only storage is opt-in: pass `visibility`
+//   explicitly AND raise the limit via requiredLimits when requesting the device.
+const defaultVisibility = ((globalThis.GPUShaderStage?.FRAGMENT ?? 2) | (globalThis.GPUShaderStage?.COMPUTE ?? 4));
+/**
+ * A single stable storage buffer for one render (or compute) pass, rewritten as needed.
+ *
+ * @remarks
+ * `StorageBuffer` is the storage-buffer counterpart to {@link Uniform}. Reach for it when
+ * the data is too large or too dynamic for a uniform: arrays, runtime-sized data, particle
+ * state, lookup tables. Storage buffers can be much bigger than uniforms (up to the adapter's
+ * `maxStorageBufferBindingSize`, typically 128 MiB, versus a uniform's 64 KiB) and can be
+ * written by the shader when `access: "read-write"`.
+ *
+ * Like `Uniform`, it owns exactly one buffer at binding 0 with a fixed (non-dynamic) offset,
+ * and the caller decides when to {@link StorageBuffer.write}. Unlike {@link UniformPool} — a
+ * dynamic-offset ring allocator for many small per-draw uniforms — there is no dynamic offset
+ * and the bind group never moves.
+ *
+ * `access` controls the layout entry type; both modes default to `FRAGMENT | COMPUTE` visibility:
+ * - `"read"` (default) → `var<storage, read>`, layout type `"read-only-storage"`.
+ * - `"read-write"` → `var<storage, read_write>`, layout type `"storage"`.
+ * Neither default includes `VERTEX`: read-write storage is forbidden in the vertex stage, and
+ * read-only storage — though legal there — needs `maxStorageBuffersInVertexStage > 0`, which is 0
+ * on many adapters (software/CI Vulkan, some mobile GPUs). For vertex-stage read-only storage, pass
+ * `visibility: VERTEX | …` explicitly and raise the limit via `requiredLimits`; do not rely on the default.
+ *
+ * @example
+ * ```ts
+ * // A read-only array the fragment shader samples (var<storage, read> values: array<f32>):
+ * const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+ * storage.write(new Float32Array(values));
+ * pass.setBindGroup(0, storage.bindGroup);
+ *
+ * // A compute-written scratch buffer (var<storage, read_write> out: array<u32>):
+ * const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+ * ```
+ */
+export class StorageBuffer {
+    device;
+    size;
+    access;
+    buffer;
+    bindGroupLayout;
+    bindGroup;
+    destroyed = false;
+    constructor(device, opts) {
+        this.device = device;
+        this.size = opts.size;
+        this.access = opts.access ?? "read";
+        this.buffer = device.createBuffer({ size: opts.size, usage: ["storage", "copy_dst"], label: opts.label });
+        const visibility = opts.visibility ?? defaultVisibility;
+        const entry = this.access === "read-write"
+            ? bind.storage(0, visibility, { minBindingSize: opts.size })
+            : bind.readonlyStorage(0, visibility, { minBindingSize: opts.size });
+        this.bindGroupLayout = opts.bindGroupLayout ?? createBindGroupLayout(device, {
+            label: opts.label ? `${opts.label}.bgl` : undefined,
+            entries: [entry],
+        });
+        this.bindGroup = createBindGroup(device, {
+            label: opts.label ? `${opts.label}.bg` : undefined,
+            layout: this.bindGroupLayout,
+            entries: [bind.resource(0, this.buffer)],
+        });
+    }
+    /** The underlying storage `GPUBuffer`. */
+    get gpu() {
+        return this.buffer.gpu;
+    }
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the contents actually change.
+     */
+    write(data, offset = 0) {
+        this.buffer.write(data, offset);
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.buffer.destroy();
+    }
+    dispose() {
+        this.destroy();
+    }
+}
+//# sourceMappingURL=storage-buffer.js.map

package/dist/storage-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-buffer.js","sourceRoot":"","sources":["../src/storage-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,eAAe,EAAE,qBAAqB,EAAe,MAAM,YAAY,CAAC;AA6B/F,+DAA+D;AAC/D,2EAA2E;AAC3E,mGAAmG;AACnG,kGAAkG;AAClG,oGAAoG;AACpG,kFAAkF;AAClF,MAAM,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE,OAAO,IAAI,CAAC,CAAC,CAAwB,CAAC;AAE1I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,aAAa;IAQH;IAPZ,IAAI,CAAS;IACb,MAAM,CAAwB;IAC9B,MAAM,CAAS;IACf,eAAe,CAAqB;IACpC,SAAS,CAAe;IACzB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAqB,MAAc,EAAE,IAA0B;QAA1C,WAAM,GAAN,MAAM,CAAQ;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1G,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,YAAY;YACxC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5D,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,qBAAqB,CAAC,MAAM,EAAE;YAC3E,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS;YACnD,OAAO,EAAE,CAAC,KAAK,CAAC;SACjB,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE;YACvC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS;YAClD,MAAM,EAAE,IAAI,CAAC,eAAe;YAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAkB,EAAE,MAAM,GAAG,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/dist/uniform.d.ts

@@ -0,0 +1,55 @@
+import { Buffer, type Device } from "@vgpu/core";
+export interface UniformOptions {
+    /** Byte size of the uniform buffer. Must be a positive number. */
+    readonly size: number;
+    /** Optional debug label forwarded to the buffer, bind group layout, and bind group. */
+    readonly label?: string;
+    /**
+     * Shader stages that read binding 0. Defaults to `VERTEX | FRAGMENT`.
+     * Ignored when {@link UniformOptions.bindGroupLayout} is provided.
+     */
+    readonly visibility?: GPUShaderStageFlags;
+    /**
+     * Reuse a pipeline-owned bind group layout instead of creating one.
+     * The layout's binding 0 must be a uniform buffer compatible with `size`.
+     */
+    readonly bindGroupLayout?: GPUBindGroupLayout;
+}
+/**
+ * A single stable uniform buffer for one render pass, rewritten per frame.
+ *
+ * @remarks
+ * Unlike {@link UniformPool} (a dynamic-offset ring allocator built for many
+ * per-draw uniforms), `Uniform` owns exactly one uniform buffer at binding 0 with
+ * a fixed (non-dynamic) offset. The caller decides when to {@link Uniform.write}
+ * — typically gating on real changes — and the bind group never moves. This fits
+ * the "one camera/globals buffer per pass" case where a dynamic-offset binding
+ * would needlessly mark the layout `hasDynamicOffset` and re-upload every frame.
+ *
+ * @example
+ * ```ts
+ * const uniform = new Uniform(device, { size: 64, label: "globals" });
+ * // per frame, only when inputs changed:
+ * uniform.write(globalsBytes);
+ * pass.setBindGroup(0, uniform.bindGroup);
+ * ```
+ */
+export declare class Uniform {
+    readonly device: Device;
+    readonly size: number;
+    readonly buffer: Buffer;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    readonly bindGroup: GPUBindGroup;
+    private destroyed;
+    constructor(device: Device, opts: UniformOptions);
+    /** The underlying uniform `GPUBuffer`. */
+    get gpu(): GPUBuffer;
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the uniform contents actually change.
+     */
+    write(data: BufferSource, offset?: number): void;
+    destroy(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=uniform.d.ts.map

package/dist/uniform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform.d.ts","sourceRoot":"","sources":["../src/uniform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAA0C,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;CAC/C;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,OAAO;IAON,QAAQ,CAAC,MAAM,EAAE,MAAM;IANnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,OAAO,CAAC,SAAS,CAAS;gBAEL,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc;IAczD,0CAA0C;IAC1C,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,IAAI;IAI3C,OAAO,IAAI,IAAI;IAMf,OAAO,IAAI,IAAI;CAGhB"}

package/dist/uniform.js

@@ -0,0 +1,64 @@
+import { bind, createBindGroup, createBindGroupLayout } from "@vgpu/core";
+const defaultVisibility = ((globalThis.GPUShaderStage?.VERTEX ?? 1) | (globalThis.GPUShaderStage?.FRAGMENT ?? 2));
+/**
+ * A single stable uniform buffer for one render pass, rewritten per frame.
+ *
+ * @remarks
+ * Unlike {@link UniformPool} (a dynamic-offset ring allocator built for many
+ * per-draw uniforms), `Uniform` owns exactly one uniform buffer at binding 0 with
+ * a fixed (non-dynamic) offset. The caller decides when to {@link Uniform.write}
+ * — typically gating on real changes — and the bind group never moves. This fits
+ * the "one camera/globals buffer per pass" case where a dynamic-offset binding
+ * would needlessly mark the layout `hasDynamicOffset` and re-upload every frame.
+ *
+ * @example
+ * ```ts
+ * const uniform = new Uniform(device, { size: 64, label: "globals" });
+ * // per frame, only when inputs changed:
+ * uniform.write(globalsBytes);
+ * pass.setBindGroup(0, uniform.bindGroup);
+ * ```
+ */
+export class Uniform {
+    device;
+    size;
+    buffer;
+    bindGroupLayout;
+    bindGroup;
+    destroyed = false;
+    constructor(device, opts) {
+        this.device = device;
+        this.size = opts.size;
+        this.buffer = device.createBuffer({ size: opts.size, usage: ["uniform", "copy_dst"], label: opts.label });
+        this.bindGroupLayout = opts.bindGroupLayout ?? createBindGroupLayout(device, {
+            label: opts.label ? `${opts.label}.bgl` : undefined,
+            entries: [bind.uniform(0, opts.visibility ?? defaultVisibility, { minBindingSize: opts.size })],
+        });
+        this.bindGroup = createBindGroup(device, {
+            label: opts.label ? `${opts.label}.bg` : undefined,
+            layout: this.bindGroupLayout,
+            entries: [bind.resource(0, this.buffer)],
+        });
+    }
+    /** The underlying uniform `GPUBuffer`. */
+    get gpu() {
+        return this.buffer.gpu;
+    }
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the uniform contents actually change.
+     */
+    write(data, offset = 0) {
+        this.buffer.write(data, offset);
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.buffer.destroy();
+    }
+    dispose() {
+        this.destroy();
+    }
+}
+//# sourceMappingURL=uniform.js.map

package/dist/uniform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform.js","sourceRoot":"","sources":["../src/uniform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,eAAe,EAAE,qBAAqB,EAAe,MAAM,YAAY,CAAC;AAmB/F,MAAM,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAwB,CAAC;AAEzI;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,OAAO;IAOG;IANZ,IAAI,CAAS;IACb,MAAM,CAAS;IACf,eAAe,CAAqB;IACpC,SAAS,CAAe;IACzB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAqB,MAAc,EAAE,IAAoB;QAApC,WAAM,GAAN,MAAM,CAAQ;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1G,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,qBAAqB,CAAC,MAAM,EAAE;YAC3E,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS;YACnD,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,IAAI,iBAAiB,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;SAChG,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE;YACvC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS;YAClD,MAAM,EAAE,IAAI,CAAC,eAAe;YAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAkB,EAAE,MAAM,GAAG,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vgpu/render",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Render pipeline + render pass abstractions for vgpu.",
   "keywords": [
     "webgpu",
@@ -47,6 +47,10 @@
     "./passes": {
       "types": "./dist/passes/index.d.ts",
       "import": "./dist/passes/index.js"
+    },
+    "./perf": {
+      "types": "./dist/perf/index.d.ts",
+      "import": "./dist/perf/index.js"
     }
   },
   "files": [
@@ -58,14 +62,15 @@
   ],
   "dependencies": {
     "wgpu-matrix": "^3.4.2",
-    "@vgpu/core": "0.0.6"
+    "@vgpu/core": "0.0.8"
   },
   "vgpuExportBundleBudgetsGzipBytes": {
     ".": 49152,
     "./inspect": 4096,
     "./utils": 2048,
     "./edit": 25600,
-    "./passes": 3584
+    "./passes": 3584,
+    "./perf": 3072
   },
   "scripts": {
     "build": "tsc -b",

package/src/createRenderPipeline.docs.md

@@ -9,6 +9,8 @@ directly to native WebGPU, `RenderPass.setPipeline()`, or render-bundle recordin
 ```ts
 createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline
 createRenderPipelineAsync(device: Device, opts: RenderPipelineOptions): Promise<GPURenderPipeline>
+createRenderPipelineFromDescriptor(device: Device, descriptor: GPURenderPipelineDescriptor): GPURenderPipeline
+createRenderPipelineFromDescriptorAsync(device: Device, descriptor: GPURenderPipelineDescriptor, fallback?: RenderPipelineAsyncFallback): Promise<GPURenderPipeline>
 ```
 
 `createRenderPipelineAsync` calls `GPUDevice.createRenderPipelineAsync()` when it
@@ -18,6 +20,24 @@ calls `createRenderPipeline()` instead. Performance-critical warmup can pass
 `fallback: "throw"` to receive a structured `VGPUError` with code
 `VGPU-RENDER-PIPELINE-ASYNC-UNAVAILABLE` instead of accidentally blocking.
 
+## Raw descriptor entrypoints
+
+If you already have a hand-built `GPURenderPipelineDescriptor`, pass it straight
+through — do not reshape it into `RenderPipelineOptions` just to get the
+async→sync fallback:
+
+- `createRenderPipelineFromDescriptor(device, descriptor)` forwards the descriptor
+  to `GPUDevice.createRenderPipeline()` unchanged.
+- `createRenderPipelineFromDescriptorAsync(device, descriptor, fallback?)` forwards
+  it to `GPUDevice.createRenderPipelineAsync()` with the exact same compatibility
+  fallback as `createRenderPipelineAsync` (default `"sync"`, or `"throw"` for a
+  structured `VGPUError`).
+
+The descriptor is forwarded verbatim, so native WebGPU validation and lifecycle
+rules remain the caller's responsibility. These are explicit, separately named
+exports rather than an overload so a `RenderPipelineOptions` caller can never be
+misread as passing a raw descriptor.
+
 VGPU does not cache pipelines: one helper call equals one WebGPU device call.
 Keep pipeline caches explicit and owned by the caller.
 
@@ -86,6 +106,20 @@ const pipeline = createRenderPipeline(device, {
 });
 ```
 
+Existing raw `GPURenderPipelineDescriptor`, only wanting the async fallback:
+
+```ts
+const descriptor: GPURenderPipelineDescriptor = {
+  label: "hero.pipeline",
+  layout: pipelineLayout,
+  vertex: { module: shaderModule, entryPoint: "vs_main", buffers },
+  fragment: { module: shaderModule, entryPoint: "fs_main", targets: [{ format }] },
+  primitive: { topology: "triangle-list" },
+};
+
+const pipeline = await createRenderPipelineFromDescriptorAsync(device, descriptor, "throw");
+```
+
 ## Raw escape hatch
 
 `Shader.gpu` is an intentional advanced escape hatch to the underlying

package/src/perf/perf.docs.md

@@ -0,0 +1,45 @@
+# @vgpu/render/perf
+
+Measurement utilities for the optimize loop: confirm a shader change is still correct and actually
+faster. **Tooling only — never call these on a live animation-frame path.** See the `measuring`
+guide (`vgpu docs cat /guides/measuring.docs.md`) for the workflow.
+
+## gpuFrameTime
+
+`gpuFrameTime(device, encode, options?)` measures median GPU time per frame for a render routine.
+
+The `encode(frame, index)` callback records the frame's passes onto a vgpu `Frame` — the same body
+you run in production. The harness owns warmup, the loop, submit, and timing. It uses GPU timestamp
+queries when the device exposes `timestamp-query`, otherwise wall-clock timing via
+`device.queue.flush()`.
+
+```ts
+import { gpuFrameTime } from "@vgpu/render/perf";
+
+const { medianMs, method } = await gpuFrameTime(device, (frame, i) => {
+  frame.renderPass(scenePass, (pass) => drawScene(pass, i));
+  frame.renderPass(floorPass, (pass) => drawFloor(pass, i));
+});
+```
+
+- `options.frames` (default 120), `options.warmup` (default 30), `options.batch` (wall-clock batch
+  size, default 8), `options.forceWallClock`, `options.label`.
+- Returns `GpuFrameTimeResult`: `{ medianMs, meanMs, minMs, p95Ms, samples, method }` where `method`
+  is `"timestamp-query"` or `"wall-clock"`.
+- Compare medians before vs after. For absolute numbers use a real-GPU device (`@vgpu/adapter-node`
+  Dawn or a browser); software backends give relative signal only.
+
+## pixelDiff
+
+`pixelDiff(a, b)` compares two renders byte-for-byte. Pass two `Texture`s (read back via
+`Texture.read()`) or two `Uint8Array`s.
+
+```ts
+import { pixelDiff } from "@vgpu/render/perf";
+
+const { maxByte } = await pixelDiff(before, after); // before/after are Texture or Uint8Array
+```
+
+Returns `PixelDiffResult`: `{ maxByte, meanByte, changedBytes, totalBytes, changedFraction }`.
+Interpret `maxByte` (max per-channel delta, 0–255): `0` bit-exact, `1–2` imperceptible
+(driver-rounding floor), more is a real visual change. A length mismatch surfaces as `maxByte = 255`.