@vgpu/render 0.0.6 → 0.0.7

package/README.md

@@ -1,6 +1,6 @@
 # @vgpu/render
 
-> 0.0.6 — early preview
+> 0.0.7 — early preview
 
 `@vgpu/render` is the small rendering layer on top of `@vgpu/core`. It focuses on explicit WebGPU-style control: create pipelines, encode standalone render passes, or build one frame command encoder with multiple user-ordered passes.
 

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export { beginFrame, Frame } from "./frame.ts";
 export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.ts";
-export { createRenderPipeline, createRenderPipelineAsync } from "./pipeline.ts";
+export { createRenderPipeline, createRenderPipelineAsync, createRenderPipelineFromDescriptor, createRenderPipelineFromDescriptorAsync } from "./pipeline.ts";
 export { RenderPass } from "./render-pass.ts";
 export { RapidRenderer } from "./rapid-renderer.ts";
+export { StorageBuffer } from "./storage-buffer.ts";
+export { Uniform } from "./uniform.ts";
 export { UniformPool } from "./uniform-pool.ts";
 export type { FrameOptions, FrameRenderPassCallback } from "./frame.ts";
 export type { RenderBundleOptions } from "./render-bundle.ts";
 export type { RenderPipelineAsyncFallback, RenderPipelineFragmentOptions, RenderPipelineOptions, RenderPipelineShaderInput, RenderPipelineStageOptions, RenderPipelineVertexOptions, } from "./pipeline.ts";
 export type { DrawSpec } from "./rapid-renderer.ts";
+export type { StorageBufferOptions } from "./storage-buffer.ts";
+export type { UniformOptions } from "./uniform.ts";
 export type { UniformLayout, UniformPoolOptions, UniformSlot } from "./uniform-pool-types.ts";
 export type { ColorAttachment, DepthStencilAttachment, RenderPassDrawOptions, RenderPassDynamicOffsets, RenderPassOptions, } from "./render-pass.ts";
 export { box, capsule, cone, cylinder, degToRad, disk, dodecahedron, fullscreenQuad, getMaterialDeclarations, icosahedron, icosphere, material, Mesh, octahedron, orthographicCamera, perspectiveCamera, plane, ring, sampler, sphere, srgb, tetrahedron, torus, wgslDeclarations } from "./domain/index.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7S,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kCAAkC,EAAE,uCAAuC,EAAE,MAAM,eAAe,CAAC;AAC7J,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC7S,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,8 +1,10 @@
 export { beginFrame, Frame } from "./frame.js";
 export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.js";
-export { createRenderPipeline, createRenderPipelineAsync } from "./pipeline.js";
+export { createRenderPipeline, createRenderPipelineAsync, createRenderPipelineFromDescriptor, createRenderPipelineFromDescriptorAsync } from "./pipeline.js";
 export { RenderPass } from "./render-pass.js";
 export { RapidRenderer } from "./rapid-renderer.js";
+export { StorageBuffer } from "./storage-buffer.js";
+export { Uniform } from "./uniform.js";
 export { UniformPool } from "./uniform-pool.js";
 export { box, capsule, cone, cylinder, degToRad, disk, dodecahedron, fullscreenQuad, getMaterialDeclarations, icosahedron, icosphere, material, Mesh, octahedron, orthographicCamera, perspectiveCamera, plane, ring, sampler, sphere, srgb, tetrahedron, torus, wgslDeclarations } from "./domain/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoBhD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kCAAkC,EAAE,uCAAuC,EAAE,MAAM,eAAe,CAAC;AAC7J,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsBhD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/perf/frame-time-measure.d.ts

@@ -0,0 +1,22 @@
+import type { Device } from "@vgpu/core";
+import { type Frame } from "../frame.ts";
+export type GpuFrameEncoder = (frame: Frame, index: number) => void;
+/**
+ * Wall-clock fallback: record one sample per frame while batching only the
+ * queue flush cadence. This keeps `samples` aligned with requested frames,
+ * matching the timestamp-query path and public docs.
+ */
+export declare function measureWallClock(device: Device, encode: GpuFrameEncoder, frames: number, batch: number, label: string): Promise<number[]>;
+/**
+ * GPU-only timing via timestamp queries. Writes a begin/end timestamp around
+ * each frame's passes, then resolves all pairs in one read at the end. Throws
+ * if timestamp writes are unavailable so the caller can fall back to wall-clock.
+ */
+export declare function measureTimestamp(device: Device, encode: GpuFrameEncoder, frames: number, label: string): Promise<number[]>;
+export declare function summarize(ms: number[]): {
+    medianMs: number;
+    meanMs: number;
+    minMs: number;
+    p95Ms: number;
+};
+//# sourceMappingURL=frame-time-measure.d.ts.map

package/dist/perf/frame-time-measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-time-measure.d.ts","sourceRoot":"","sources":["../../src/perf/frame-time-measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAKrD,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpE;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAenB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAgDnB;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CAaA"}

package/dist/perf/frame-time-measure.js

@@ -0,0 +1,91 @@
+import { beginFrame } from "../frame.js";
+const MS_PER_NS = 1 / 1_000_000;
+const MAP_READ = 1; // GPUMapMode.READ
+/**
+ * Wall-clock fallback: record one sample per frame while batching only the
+ * queue flush cadence. This keeps `samples` aligned with requested frames,
+ * matching the timestamp-query path and public docs.
+ */
+export async function measureWallClock(device, encode, frames, batch, label) {
+    const samples = [];
+    for (let i = 0; i < frames;) {
+        const n = Math.min(batch, frames - i);
+        for (let k = 0; k < n; k++) {
+            const start = performance.now();
+            const frame = beginFrame(device, { label });
+            encode(frame, i + k);
+            frame.submit();
+            samples.push(performance.now() - start);
+        }
+        await device.queue.flush();
+        i += n;
+    }
+    return samples;
+}
+/**
+ * GPU-only timing via timestamp queries. Writes a begin/end timestamp around
+ * each frame's passes, then resolves all pairs in one read at the end. Throws
+ * if timestamp writes are unavailable so the caller can fall back to wall-clock.
+ */
+export async function measureTimestamp(device, encode, frames, label) {
+    const gpu = device.gpu;
+    const querySet = gpu.createQuerySet({ type: "timestamp", count: frames * 2 });
+    const resolve = device.createBuffer({
+        size: frames * 2 * 8,
+        usage: ["query_resolve", "copy_src"],
+        label: `${label}-ts-resolve`,
+    });
+    const read = device.createBuffer({
+        size: frames * 2 * 8,
+        usage: ["map_read", "copy_dst"],
+        label: `${label}-ts-read`,
+    });
+    try {
+        for (let i = 0; i < frames; i++) {
+            const frame = beginFrame(device, { label });
+            const enc = frame.gpu;
+            if (typeof enc.writeTimestamp !== "function") {
+                throw new Error("GPUCommandEncoder.writeTimestamp unavailable");
+            }
+            enc.writeTimestamp(querySet, i * 2);
+            encode(frame, i);
+            enc.writeTimestamp(querySet, i * 2 + 1);
+            frame.submit();
+        }
+        const enc = gpu.createCommandEncoder({ label: `${label}-ts-resolve` });
+        enc.resolveQuerySet(querySet, 0, frames * 2, resolve.gpu, 0);
+        enc.copyBufferToBuffer(resolve.gpu, 0, read.gpu, 0, frames * 2 * 8);
+        gpu.queue.submit([enc.finish()]);
+        await read.gpu.mapAsync(MAP_READ);
+        const ticks = new BigUint64Array(read.gpu.getMappedRange().slice(0));
+        read.gpu.unmap();
+        const samples = [];
+        for (let i = 0; i < frames; i++) {
+            const dt = Number(ticks[i * 2 + 1] - ticks[i * 2]) * MS_PER_NS;
+            if (Number.isFinite(dt) && dt > 0)
+                samples.push(dt);
+        }
+        if (samples.length === 0)
+            throw new Error("no valid timestamp samples");
+        return samples;
+    }
+    finally {
+        querySet.destroy();
+        resolve.dispose();
+        read.dispose();
+    }
+}
+export function summarize(ms) {
+    if (ms.length === 0) {
+        return { medianMs: 0, meanMs: 0, minMs: 0, p95Ms: 0 };
+    }
+    const sorted = [...ms].sort((a, b) => a - b);
+    const at = (q) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.floor(q * sorted.length)))];
+    return {
+        medianMs: at(0.5),
+        meanMs: sorted.reduce((s, v) => s + v, 0) / sorted.length,
+        minMs: sorted[0],
+        p95Ms: at(0.95),
+    };
+}
+//# sourceMappingURL=frame-time-measure.js.map

package/dist/perf/frame-time-measure.js.map

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

package/dist/perf/gpu-frame-time.d.ts

@@ -0,0 +1,49 @@
+import type { Device } from "@vgpu/core";
+import { type Frame } from "../frame.ts";
+/**
+ * Options for {@link gpuFrameTime}. All have sensible defaults; the common call passes only the
+ * device and an encode callback.
+ */
+export interface GpuFrameTimeOptions {
+    /** Measured frames (after warmup). Default 120. */
+    readonly frames?: number;
+    /** Warmup frames discarded before measuring (shader compile + lazy allocs settle). Default 30. */
+    readonly warmup?: number;
+    /** Frames per wall-clock batch (amortizes submit/drain latency). Ignored for timestamp-query. Default 8. */
+    readonly batch?: number;
+    /** Force the wall-clock path even when timestamp-query is available. Default false. */
+    readonly forceWallClock?: boolean;
+    readonly label?: string;
+}
+export interface GpuFrameTimeResult {
+    /** Median per-frame time in milliseconds — the headline number for before/after comparisons. */
+    readonly medianMs: number;
+    readonly meanMs: number;
+    readonly minMs: number;
+    readonly p95Ms: number;
+    /** Per-frame samples behind the stats. */
+    readonly samples: number;
+    /**
+     * How the time was obtained. `timestamp-query` is GPU-only (excludes submit/drain) and needs the
+     * device feature; `wall-clock` (queue.flush) is the robust fallback and works everywhere.
+     */
+    readonly method: "timestamp-query" | "wall-clock";
+}
+/**
+ * Measures GPU time per frame for a render routine, for before/after optimization comparisons.
+ *
+ * The `encode` callback records the frame's passes onto a vgpu {@link Frame} — the SAME body you
+ * run in production. The harness owns warmup, the loop, submit, and timing, so you don't hand-roll
+ * a bench. It prefers GPU timestamp queries when the device supports them (`timestamp-query`) and
+ * otherwise falls back to wall-clock timing via `device.queue.flush()`.
+ *
+ * Tooling only — never call this on a live animation-frame path.
+ *
+ * @example
+ * const { medianMs, method } = await gpuFrameTime(device, (frame, i) => {
+ *   frame.renderPass(scenePass, (pass) => drawScene(pass, i));
+ *   frame.renderPass(floorPass, (pass) => drawFloor(pass, i));
+ * });
+ */
+export declare function gpuFrameTime(device: Device, encode: (frame: Frame, index: number) => void, options?: GpuFrameTimeOptions): Promise<GpuFrameTimeResult>;
+//# sourceMappingURL=gpu-frame-time.d.ts.map

package/dist/perf/gpu-frame-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-frame-time.d.ts","sourceRoot":"","sources":["../../src/perf/gpu-frame-time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAGrD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4GAA4G;IAC5G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAAC;CACnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAC7C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}

package/dist/perf/gpu-frame-time.js

@@ -0,0 +1,50 @@
+import { beginFrame } from "../frame.js";
+import { measureTimestamp, measureWallClock, summarize } from "./frame-time-measure.js";
+/**
+ * Measures GPU time per frame for a render routine, for before/after optimization comparisons.
+ *
+ * The `encode` callback records the frame's passes onto a vgpu {@link Frame} — the SAME body you
+ * run in production. The harness owns warmup, the loop, submit, and timing, so you don't hand-roll
+ * a bench. It prefers GPU timestamp queries when the device supports them (`timestamp-query`) and
+ * otherwise falls back to wall-clock timing via `device.queue.flush()`.
+ *
+ * Tooling only — never call this on a live animation-frame path.
+ *
+ * @example
+ * const { medianMs, method } = await gpuFrameTime(device, (frame, i) => {
+ *   frame.renderPass(scenePass, (pass) => drawScene(pass, i));
+ *   frame.renderPass(floorPass, (pass) => drawFloor(pass, i));
+ * });
+ */
+export async function gpuFrameTime(device, encode, options = {}) {
+    const frames = Math.max(1, Math.floor(options.frames ?? 120));
+    const warmup = Math.max(0, Math.floor(options.warmup ?? 30));
+    const batch = Math.max(1, Math.floor(options.batch ?? 8));
+    const label = options.label ?? "vgpu-gpuFrameTime";
+    await warmupFrames(device, encode, warmup, label);
+    let perFrameMs = null;
+    let method = "wall-clock";
+    if (!options.forceWallClock && device.features.has("timestamp-query")) {
+        try {
+            perFrameMs = await measureTimestamp(device, encode, frames, label);
+            method = "timestamp-query";
+        }
+        catch {
+            perFrameMs = null; // any timestamp hiccup → fall back to the robust path
+        }
+    }
+    if (!perFrameMs || perFrameMs.length === 0) {
+        perFrameMs = await measureWallClock(device, encode, frames, batch, label);
+        method = "wall-clock";
+    }
+    return { ...summarize(perFrameMs), samples: perFrameMs.length, method };
+}
+async function warmupFrames(device, encode, warmup, label) {
+    for (let i = 0; i < warmup; i++) {
+        const frame = beginFrame(device, { label });
+        encode(frame, i);
+        frame.submit();
+    }
+    await device.queue.flush();
+}
+//# sourceMappingURL=gpu-frame-time.js.map

package/dist/perf/gpu-frame-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-frame-time.js","sourceRoot":"","sources":["../../src/perf/gpu-frame-time.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAiCxF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,MAA6C,EAC7C,UAA+B,EAAE;IAEjC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IAEnD,MAAM,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAElD,IAAI,UAAU,GAAoB,IAAI,CAAC;IACvC,IAAI,MAAM,GAAiC,YAAY,CAAC;IACxD,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACtE,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YACnE,MAAM,GAAG,iBAAiB,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,GAAG,IAAI,CAAC,CAAC,sDAAsD;QAC3E,CAAC;IACH,CAAC;IACD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,UAAU,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC1E,MAAM,GAAG,YAAY,CAAC;IACxB,CAAC;IAED,OAAO,EAAE,GAAG,SAAS,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;AAC1E,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,MAAc,EACd,MAA6C,EAC7C,MAAc,EACd,KAAa;IAEb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjB,KAAK,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;AAC7B,CAAC"}

package/dist/perf/index.d.ts

@@ -0,0 +1,5 @@
+export { gpuFrameTime } from "./gpu-frame-time.ts";
+export type { GpuFrameTimeOptions, GpuFrameTimeResult } from "./gpu-frame-time.ts";
+export { pixelDiff } from "./pixel-diff.ts";
+export type { PixelDiffResult } from "./pixel-diff.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/perf/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/perf/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/perf/index.js

@@ -0,0 +1,3 @@
+export { gpuFrameTime } from "./gpu-frame-time.js";
+export { pixelDiff } from "./pixel-diff.js";
+//# sourceMappingURL=index.js.map

package/dist/perf/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/perf/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/perf/pixel-diff.d.ts

@@ -0,0 +1,27 @@
+import type { Texture } from "@vgpu/core";
+export interface PixelDiffResult {
+    /** Largest absolute per-byte difference (0–255). The headline: ≤1–2 is driver-rounding noise. */
+    readonly maxByte: number;
+    /** Mean absolute per-byte difference. */
+    readonly meanByte: number;
+    /** Bytes that differ at all. */
+    readonly changedBytes: number;
+    readonly totalBytes: number;
+    /** changedBytes / totalBytes. A tiny fraction with maxByte ≤ ~2 means "imperceptible". */
+    readonly changedFraction: number;
+}
+/**
+ * Compares two renders byte-for-byte — the verify half of measure-before-keeping. Pass two
+ * `Texture`s (read back via {@link Texture.read}) or two already-read `Uint8Array`s. Use it to
+ * confirm an optimization is bit-exact (maxByte 0) or imperceptible (maxByte ≤ ~2 on a small
+ * fraction) before keeping it.
+ *
+ * @example
+ * const before = await renderInto(target);      // baseline texture
+ * applyOptimization();
+ * const after = await renderInto(target);
+ * const { maxByte } = await pixelDiff(before, after);
+ * expect(maxByte).toBeLessThanOrEqual(2);
+ */
+export declare function pixelDiff(a: Texture | Uint8Array, b: Texture | Uint8Array): Promise<PixelDiffResult>;
+//# sourceMappingURL=pixel-diff.d.ts.map

package/dist/perf/pixel-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-diff.d.ts","sourceRoot":"","sources":["../../src/perf/pixel-diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAC7B,CAAC,EAAE,OAAO,GAAG,UAAU,EACvB,CAAC,EAAE,OAAO,GAAG,UAAU,GACtB,OAAO,CAAC,eAAe,CAAC,CAwB1B"}

package/dist/perf/pixel-diff.js

@@ -0,0 +1,40 @@
+/**
+ * Compares two renders byte-for-byte — the verify half of measure-before-keeping. Pass two
+ * `Texture`s (read back via {@link Texture.read}) or two already-read `Uint8Array`s. Use it to
+ * confirm an optimization is bit-exact (maxByte 0) or imperceptible (maxByte ≤ ~2 on a small
+ * fraction) before keeping it.
+ *
+ * @example
+ * const before = await renderInto(target);      // baseline texture
+ * applyOptimization();
+ * const after = await renderInto(target);
+ * const { maxByte } = await pixelDiff(before, after);
+ * expect(maxByte).toBeLessThanOrEqual(2);
+ */
+export async function pixelDiff(a, b) {
+    const da = a instanceof Uint8Array ? a : await a.read();
+    const db = b instanceof Uint8Array ? b : await b.read();
+    const total = Math.min(da.length, db.length);
+    let maxByte = 0;
+    let sum = 0;
+    let changed = 0;
+    for (let i = 0; i < total; i++) {
+        const d = Math.abs((da[i] ?? 0) - (db[i] ?? 0));
+        if (d > 0)
+            changed++;
+        if (d > maxByte)
+            maxByte = d;
+        sum += d;
+    }
+    // A length mismatch is itself a difference; surface it rather than silently comparing a prefix.
+    if (da.length !== db.length)
+        maxByte = Math.max(maxByte, 255);
+    return {
+        maxByte,
+        meanByte: total === 0 ? 0 : sum / total,
+        changedBytes: changed,
+        totalBytes: total,
+        changedFraction: total === 0 ? 0 : changed / total,
+    };
+}
+//# sourceMappingURL=pixel-diff.js.map

package/dist/perf/pixel-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-diff.js","sourceRoot":"","sources":["../../src/perf/pixel-diff.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,CAAuB,EACvB,CAAuB;IAEvB,MAAM,EAAE,GAAG,CAAC,YAAY,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,MAAM,EAAE,GAAG,CAAC,YAAY,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAExD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC,GAAG,OAAO;YAAE,OAAO,GAAG,CAAC,CAAC;QAC7B,GAAG,IAAI,CAAC,CAAC;IACX,CAAC;IACD,gGAAgG;IAChG,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAE9D,OAAO;QACL,OAAO;QACP,QAAQ,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK;QACvC,YAAY,EAAE,OAAO;QACrB,UAAU,EAAE,KAAK;QACjB,eAAe,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK;KACnD,CAAC;AACJ,CAAC"}

package/dist/pipeline-descriptor.d.ts

@@ -0,0 +1,35 @@
+import { Shader } from "@vgpu/core";
+export type RenderPipelineShaderInput = Shader | GPUShaderModule;
+export interface RenderPipelineStageOptions {
+    /** VGPU Shader or raw GPUShaderModule for this stage. Defaults to RenderPipelineOptions.shader. */
+    readonly shader?: RenderPipelineShaderInput;
+    /** Descriptor-like alias for shader. */
+    readonly module?: RenderPipelineShaderInput;
+    /** Entry-point name. Kept for backwards compatibility with the first render helper API. */
+    readonly entry?: string;
+    /** Descriptor-like entry-point name. */
+    readonly entryPoint?: string;
+    readonly constants?: Record<string, GPUPipelineConstantValue>;
+}
+export interface RenderPipelineVertexOptions extends RenderPipelineStageOptions {
+    readonly buffers?: readonly (GPUVertexBufferLayout | null)[];
+}
+export interface RenderPipelineFragmentOptions extends RenderPipelineStageOptions {
+    readonly targets: readonly (GPUColorTargetState | null)[];
+}
+export interface RenderPipelineOptions {
+    /** Optional shared shader module used by vertex/fragment stages that do not provide their own module. */
+    readonly shader?: RenderPipelineShaderInput;
+    readonly vertex: RenderPipelineVertexOptions;
+    readonly fragment?: RenderPipelineFragmentOptions;
+    readonly primitive?: GPUPrimitiveState;
+    readonly depthStencil?: GPUDepthStencilState;
+    readonly multisample?: GPUMultisampleState;
+    readonly layout?: GPUPipelineLayout | "auto";
+    readonly label?: string;
+    /** createRenderPipelineAsync fallback when GPUDevice.createRenderPipelineAsync is unavailable. Defaults to "sync". */
+    readonly fallback?: RenderPipelineAsyncFallback;
+}
+export type RenderPipelineAsyncFallback = "sync" | "throw";
+export declare function toRenderPipelineDescriptor(opts: RenderPipelineOptions): GPURenderPipelineDescriptor;
+//# sourceMappingURL=pipeline-descriptor.d.ts.map

package/dist/pipeline-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-descriptor.d.ts","sourceRoot":"","sources":["../src/pipeline-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,eAAe,CAAC;AAEjE,MAAM,WAAW,0BAA0B;IACzC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9D;AAED,MAAM,WAAW,6BAA8B,SAAQ,0BAA0B;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,mBAAmB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sHAAsH;IACtH,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACjD;AAED,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,qBAAqB,GAAG,2BAA2B,CAyBnG"}

package/dist/pipeline-descriptor.js

@@ -0,0 +1,44 @@
+import { Shader, VGPUError } from "@vgpu/core";
+export 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;
+}
+//# sourceMappingURL=pipeline-descriptor.js.map

package/dist/pipeline-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-descriptor.js","sourceRoot":"","sources":["../src/pipeline-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAwC/C,MAAM,UAAU,0BAA0B,CAAC,IAA2B;IACpE,MAAM,UAAU,GAAgC;QAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM;QAC7B,MAAM,EAAE;YACN,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC;YACvD,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC;YACxC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;SACpE;QACD,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,CAAC;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,UAAU,CAAC,QAAQ,GAAG;YACpB,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC;YAC3D,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC;YAC1C,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS;YAClC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;SACpC,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,WAAW,CAClB,KAAiC,EACjC,QAA+C,EAC/C,SAAgC;IAEhC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC;IACxD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,SAAS,CAAC;YAClB,IAAI,EAAE,qCAAqC;YAC3C,OAAO,EAAE,6BAA6B,SAAS,SAAS;YACxD,GAAG,EAAE,mFAAmF;YACxF,KAAK,EAAE,wBAAwB,SAAS,EAAE;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AAChD,CAAC;AAED,SAAS,eAAe,CAAC,KAAiC;IACxD,OAAO,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,KAAK,CAAC;AACzC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAgC;IAChD,OAAO,KAAK,YAAY,MAAM,CAAC;AACjC,CAAC"}

package/dist/pipeline.d.ts

@@ -1,37 +1,26 @@
-import { Shader, type Device } from "@vgpu/core";
-export type RenderPipelineShaderInput = Shader | GPUShaderModule;
-export type RenderPipelineAsyncFallback = "sync" | "throw";
-export interface RenderPipelineStageOptions {
-    /** VGPU Shader or raw GPUShaderModule for this stage. Defaults to RenderPipelineOptions.shader. */
-    readonly shader?: RenderPipelineShaderInput;
-    /** Descriptor-like alias for shader. */
-    readonly module?: RenderPipelineShaderInput;
-    /** Entry-point name. Kept for backwards compatibility with the first render helper API. */
-    readonly entry?: string;
-    /** Descriptor-like entry-point name. */
-    readonly entryPoint?: string;
-    readonly constants?: Record<string, GPUPipelineConstantValue>;
-}
-export interface RenderPipelineVertexOptions extends RenderPipelineStageOptions {
-    readonly buffers?: readonly (GPUVertexBufferLayout | null)[];
-}
-export interface RenderPipelineFragmentOptions extends RenderPipelineStageOptions {
-    readonly targets: readonly (GPUColorTargetState | null)[];
-}
-export interface RenderPipelineOptions {
-    /** Optional shared shader module used by vertex/fragment stages that do not provide their own module. */
-    readonly shader?: RenderPipelineShaderInput;
-    readonly vertex: RenderPipelineVertexOptions;
-    readonly fragment?: RenderPipelineFragmentOptions;
-    readonly primitive?: GPUPrimitiveState;
-    readonly depthStencil?: GPUDepthStencilState;
-    readonly multisample?: GPUMultisampleState;
-    readonly layout?: GPUPipelineLayout | "auto";
-    readonly label?: string;
-    /** createRenderPipelineAsync fallback when GPUDevice.createRenderPipelineAsync is unavailable. Defaults to "sync". */
-    readonly fallback?: RenderPipelineAsyncFallback;
-}
+import { type Device } from "@vgpu/core";
+import type { RenderPipelineAsyncFallback, RenderPipelineOptions } from "./pipeline-descriptor.ts";
+export type { RenderPipelineAsyncFallback, RenderPipelineFragmentOptions, RenderPipelineOptions, RenderPipelineShaderInput, RenderPipelineStageOptions, RenderPipelineVertexOptions, } from "./pipeline-descriptor.ts";
 export declare function createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline;
 export declare function createRenderPipelineAsync(device: Device, opts: RenderPipelineOptions): Promise<GPURenderPipeline>;
+/**
+ * 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 declare function createRenderPipelineFromDescriptor(device: Device, descriptor: GPURenderPipelineDescriptor): GPURenderPipeline;
+/**
+ * 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 declare function createRenderPipelineFromDescriptorAsync(device: Device, descriptor: GPURenderPipelineDescriptor, fallback?: RenderPipelineAsyncFallback): Promise<GPURenderPipeline>;
 export declare function __resetCreateRenderPipelineAsyncFallbackWarningForTests(): void;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,eAAe,CAAC;AACjE,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,0BAA0B;IACzC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9D;AAED,MAAM,WAAW,6BAA8B,SAAQ,0BAA0B;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,mBAAmB,GAAG,IAAI,CAAC,EAAE,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sHAAsH;IACtH,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACjD;AAOD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAEnG;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkBvH;AAkDD,wBAAgB,uDAAuD,IAAI,IAAI,CAE9E"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEnG,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AASlC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAEnG;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,2BAA2B,GACtC,iBAAiB,CAEnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,uCAAuC,CAC3D,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,2BAA2B,EACvC,QAAQ,CAAC,EAAE,2BAA2B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AA0BD,wBAAgB,uDAAuD,IAAI,IAAI,CAE9E"}