@vgpu/render 0.0.5 → 0.0.7

package/README.md

@@ -1,8 +1,8 @@
 # @vgpu/render
 
-> 0.0.1 — early preview
+> 0.0.7 — early preview
 
-`@vgpu/render` is the small rendering layer on top of `@vgpu/core`. It currently focuses on two public building blocks: creating a render pipeline from a vgpu shader wrapper, and issuing a render pass against a texture or texture view. The package is intentionally narrow in 0.0.1 and leaves higher-level scene helpers for later releases.
+`@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.
 
 ## Install
 
@@ -13,15 +13,23 @@ pnpm add @vgpu/render
 ## Exports
 
 ### Runtime
-- `createRenderPipeline`
+- `createRenderPipeline` / `createRenderPipelineAsync`
 - `RenderPass`
+- `beginFrame` / `Frame`
+- `createRenderBundle` / `RenderBundleRecorder`
+- `RapidRenderer`
 
 ### Types
 - `RenderPipelineOptions`
 - `ColorAttachment`
+- `DepthStencilAttachment`
 - `RenderPassOptions`
+- `RenderPassDrawOptions`
+- `RenderPassDynamicOffsets`
+- `FrameOptions`
+- `RenderBundleOptions`
 
-## Usage
+## Standalone pass
 
 ```ts
 import { App } from "@vgpu/core";
@@ -47,9 +55,90 @@ const pass = new RenderPass(device, {
 });
 pass.setPipeline(pipeline);
 pass.draw(3);
-pass.end();
+pass.end(); // finishes and submits this one-shot pass
 ```
 
+## Rapid renderer
+
+`RapidRenderer` is available for examples and simple one-draw submissions:
+
+```ts
+import { RapidRenderer } from "@vgpu/render";
+
+const renderer = new RapidRenderer(device);
+material.writeUniforms({ viewProjection, model, cameraPosition, light });
+await renderer.draw({ material, mesh, target, depthTarget });
+```
+
+For homepage-grade hot paths, do not resolve shaders or rebuild pipelines inside
+the animation-frame path. If shader source truly changes dynamically, resolve and
+create the replacement pipeline outside the frame loop, then stage or
+double-buffer the swap so a completed pipeline is installed at a frame boundary.
+
+## Explicit multipass frame
+
+Render bundles are setup-time reusable draw packets, not hidden passes or a render graph:
+
+```ts
+import { beginFrame, createRenderBundle } from "@vgpu/render";
+
+const bundle = createRenderBundle(device, {
+  label: "hero.light-sources.bundle",
+  colorFormats: ["rgba8unorm"],
+  depthStencilFormat: "depth24plus",
+  sampleCount: 1,
+  record(bundle) {
+    bundle.setPipeline(lightPipeline);
+    bundle.setBindGroup(0, lightBindGroup);
+    bundle.draw(lightVertexCount);
+  },
+});
+```
+
+Native WebGPU multipass code uses one command encoder, explicit pass begin/end calls, then one finish/submit:
+
+```ts
+const encoder = device.gpu.createCommandEncoder({ label: "hero.frame" });
+
+const lightPass = encoder.beginRenderPass(lightPassDescriptor);
+lightPass.executeBundles([bundle]);
+lightPass.end();
+
+encoder.writeTimestamp(querySet, 0);
+encoder.copyBufferToBuffer(srcBuffer, 0, dstBuffer, 0, byteLength);
+
+const compositePass = encoder.beginRenderPass(compositePassDescriptor);
+compositePass.setPipeline(compositePipeline);
+compositePass.setBindGroup(0, compositeBindGroup);
+compositePass.draw(3);
+compositePass.end();
+
+device.queue.gpu.submit([encoder.finish()]);
+```
+
+With VGPU `Frame`, the lifecycle is the same but pass end and final submission are harder to get wrong:
+
+```ts
+const frame = beginFrame(device, { label: "hero.frame" });
+frame.renderPass(lightPassDescriptor, (pass) => {
+  pass.executeBundles([bundle]);
+});
+frame.gpu.writeTimestamp(querySet, 0);
+frame.copyBufferToBuffer(srcBuffer, dstBuffer, byteLength);
+frame.renderPass(compositePassDescriptor, (pass) => {
+  pass.setPipeline(compositePipeline);
+  pass.setBindGroup(0, compositeBindGroup);
+  pass.draw(3);
+});
+frame.submit(); // finishes once and submits once
+```
+
+`Frame` preserves authored ordering and exposes its raw `GPUCommandEncoder` as `frame.gpu` for advanced commands. Direct raw encoder calls follow WebGPU behavior; VGPU helper methods guard use after `submit()` with `VGPU-FRAME-SUBMITTED`.
+
+For homepage-grade hot paths, create pipelines (sync or async), buffers, bind groups, and render bundles during setup/warmup or resize, then keep per-frame code to command encoding and one queue submit. `createRenderPipelineAsync()` defaults to `fallback: "sync"` with a once-only diagnostic when native async creation is unavailable; use `fallback: "throw"` if warmup must fail rather than block. Avoid runtime `resolveShader()`/shader creation in frame loops; dynamically changing shader source should be resolved and pipelined off the frame path, with staged or double-buffered swaps at frame boundaries.
+
+Raw `.gpu` properties such as `device.gpu`, `queue.gpu`, `buffer.gpu`, `texture.gpu`, `shader.gpu`, `frame.gpu`, and `RenderBundleRecorder.gpu` are intentional advanced escape hatches to native WebGPU objects and are treated as semver-protected public API. Native WebGPU validation and lifecycle rules still apply when using them directly.
+
 ## License
 
 MIT.

package/dist/frame.d.ts

@@ -0,0 +1,19 @@
+import { Buffer, type Device } from "@vgpu/core";
+import { type RenderPass, type RenderPassOptions } from "./render-pass.ts";
+export interface FrameOptions {
+    readonly label?: string;
+}
+export type FrameRenderPassCallback = (pass: RenderPass) => void;
+export declare class Frame {
+    private readonly device;
+    readonly gpu: GPUCommandEncoder;
+    private submitted;
+    constructor(device: Device, opts?: FrameOptions);
+    renderPass(opts: RenderPassOptions, record: FrameRenderPassCallback): void;
+    copyBufferToBuffer(source: Buffer | GPUBuffer, destination: Buffer | GPUBuffer, size: GPUSize64, sourceOffset?: number, destinationOffset?: number): void;
+    submit(): void;
+    dispose(): void;
+    private assertOpen;
+}
+export declare function beginFrame(device: Device, opts?: FrameOptions): Frame;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAA6B,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjE,qBAAa,KAAK;IAIJ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,OAAO,CAAC,SAAS,CAAS;gBAEG,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB;IAIpE,UAAU,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAU1E,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,SAAI,EAAE,iBAAiB,SAAI,GAAG,IAAI;IAK/I,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,UAAU;CAQnB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,KAAK,CAEzE"}

package/dist/frame.js

@@ -0,0 +1,50 @@
+import { Buffer, VGPUError } from "@vgpu/core";
+import { createRenderPassOnEncoder } from "./render-pass.js";
+export class Frame {
+    device;
+    gpu;
+    submitted = false;
+    constructor(device, opts = {}) {
+        this.device = device;
+        this.gpu = device.gpu.createCommandEncoder({ label: opts.label });
+    }
+    renderPass(opts, record) {
+        this.assertOpen("Frame.renderPass");
+        const pass = createRenderPassOnEncoder(this.device, opts, this.gpu);
+        try {
+            record(pass);
+        }
+        finally {
+            pass.end();
+        }
+    }
+    copyBufferToBuffer(source, destination, size, sourceOffset = 0, destinationOffset = 0) {
+        this.assertOpen("Frame.copyBufferToBuffer");
+        this.gpu.copyBufferToBuffer(gpuBuffer(source), sourceOffset, gpuBuffer(destination), destinationOffset, size);
+    }
+    submit() {
+        this.assertOpen("Frame.submit");
+        this.submitted = true;
+        this.device.queue.gpu.submit([this.gpu.finish()]);
+    }
+    dispose() {
+        if (!this.submitted)
+            this.submit();
+    }
+    assertOpen(where) {
+        if (!this.submitted)
+            return;
+        throw new VGPUError({
+            code: "VGPU-FRAME-SUBMITTED",
+            message: "Frame cannot encode or submit after submit().",
+            where,
+        });
+    }
+}
+export function beginFrame(device, opts = {}) {
+    return new Frame(device, opts);
+}
+function gpuBuffer(buffer) {
+    return buffer instanceof Buffer ? buffer.gpu : buffer;
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAA2C,MAAM,kBAAkB,CAAC;AAQtG,MAAM,OAAO,KAAK;IAIa;IAHpB,GAAG,CAAoB;IACxB,SAAS,GAAG,KAAK,CAAC;IAE1B,YAA6B,MAAc,EAAE,OAAqB,EAAE;QAAvC,WAAM,GAAN,MAAM,CAAQ;QACzC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,UAAU,CAAC,IAAuB,EAAE,MAA+B;QACjE,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IAED,kBAAkB,CAAC,MAA0B,EAAE,WAA+B,EAAE,IAAe,EAAE,YAAY,GAAG,CAAC,EAAE,iBAAiB,GAAG,CAAC;QACtI,IAAI,CAAC,UAAU,CAAC,0BAA0B,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAChH,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACrC,CAAC;IAEO,UAAU,CAAC,KAAa;QAC9B,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,MAAM,IAAI,SAAS,CAAC;YAClB,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,+CAA+C;YACxD,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAqB,EAAE;IAChE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,SAAS,CAAC,MAA0B;IAC3C,OAAO,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,19 @@
-export { createRenderPipeline } from "./pipeline.ts";
+export { beginFrame, Frame } from "./frame.ts";
+export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.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 { RenderPipelineOptions } from "./pipeline.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, RenderPassDrawOptions, RenderPassDynamicOffsets, RenderPassOptions, } from "./render-pass.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";
 export type { BoxSpec, Camera, CapsuleSpec, ConeSpec, CylinderSpec, DiskSpec, FullscreenQuadSpec, IcosphereSpec, Material, MaterialSamplerSpec, MaterialSpec, MaterialTextureSpec, MaterialUniformValue, Mat4, MeshGpu, MeshPrimitive, PlaneSpec, PolyhedronSpec, RingSpec, Sampler, SamplerSpec, SphereSpec, TextureKind, TextureSpec, TextureValue, TorusSpec, Vec3, VertexAttributes, VertexLayoutKind, WgslUniformType, WriteTextureValues } from "./domain/index.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,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,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EACV,eAAe,EACf,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,6 +1,10 @@
-export { createRenderPipeline } from "./pipeline.js";
+export { beginFrame, Frame } from "./frame.js";
+export { createRenderBundle, RenderBundleRecorder } from "./render-bundle.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,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAUhD,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