@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/render/passes/csm.js

@@ -0,0 +1,338 @@
+import { mat4x4f, vec4f, wgsl } from "@downdraft/engine/shader-graph";
+import { mat4, vec3 } from "wgpu-matrix";
+import { PassType } from "../frame-graph.js";
+import { RenderPass } from "../render-pass.js";
+import { destroyMapValues } from "../resource-tracker.js";
+import { createValidatedShaderModule } from "../shader-validator.js";
+import { TrackedRenderPass } from "../tracked-render-pass.js";
+export const DEFAULT_CSM_SETTINGS = {
+    cascadeCount: 4,
+    shadowMapSize: 2048,
+    lambda: 0.5,
+    bias: 0.001,
+    normalBias: 0.02,
+    blendDistance: 0.15,
+};
+const MAX_CASCADES = 4;
+const CascadeUniforms = wgsl.struct("CascadeUniforms", {
+    viewProj: mat4x4f,
+    texelSize: vec4f,
+});
+// CSMUniforms contains a nested struct array (array<CascadeUniforms, N>).
+// The wgsl.struct emitter cannot produce valid WGSL for nested struct arrays
+// (it would inline the struct declaration inside array<...>), so the WGSL
+// declaration below is hand-written. The WgslStruct descriptor is still used
+// for the typed view layout (single source of truth for buffer offsets).
+const CSMUniforms = wgsl.struct("CSMUniforms", {
+    cascades: wgsl.array(CascadeUniforms, MAX_CASCADES),
+    cascadeSplits: vec4f,
+    lightDir: vec4f,
+    cascadeCount: vec4f,
+});
+const CSM_SHADER = /* wgsl */ `
+${CascadeUniforms.wgsl}
+
+struct CSMUniforms {
+  cascades: array<CascadeUniforms, ${MAX_CASCADES}>,
+  cascadeSplits: vec4<f32>,
+  lightDir: vec4<f32>,
+  cascadeCount: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> csm: CSMUniforms;
+@group(0) @binding(1) var modelUniform: mat4x4<f32>;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) viewDepth: f32,
+  @location(1) worldNormal: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = modelUniform * vec4<f32>(input.position, 1.0);
+  output.clipPosition = csm.cascades[0].viewProj * worldPos;
+  output.viewDepth = output.clipPosition.z / output.clipPosition.w;
+  output.worldNormal = normalize((modelUniform * vec4<f32>(input.normal, 0.0)).xyz);
+  return output;
+}
+`;
+export class CSMPass extends RenderPass {
+    name = "csm";
+    passType = PassType.Custom;
+    shadowHandle = null;
+    device;
+    settings;
+    shaderModule = null;
+    shadowTexture = null;
+    shadowView = null;
+    // Per-cascade views for rendering to individual layers of the 2d-array texture.
+    cascadeViews = [];
+    shadowSampler = null;
+    uniformBuffer = null;
+    modelBuffer = null;
+    _uniformView = null;
+    _uniformBuf = null;
+    pipelines = new Map();
+    bindGroups = new Map();
+    vertexBuffers = new Map();
+    indexBuffers = new Map();
+    cascadeViewProjs = [];
+    cascadeSplits = [];
+    constructor(device, settings = {}) {
+        super();
+        this.device = device;
+        this.settings = { ...DEFAULT_CSM_SETTINGS, ...settings };
+        for (let i = 0; i < MAX_CASCADES; i++) {
+            this.cascadeViewProjs.push(mat4.identity());
+            this.cascadeSplits.push(0);
+        }
+    }
+    get cascadeCount() {
+        return this.settings.cascadeCount;
+    }
+    get shadowMapSize() {
+        return this.settings.shadowMapSize;
+    }
+    prepare(_device) {
+        if (!this.shaderModule) {
+            this.shaderModule = createValidatedShaderModule(this.device, { code: CSM_SHADER, label: "CSMPass" });
+        }
+        // Destroy old shadow resources before creating new ones.
+        this.shadowTexture?.destroy();
+        this.shadowView = null;
+        // GPUTextureView does not have .destroy() — just drop the references.
+        this.cascadeViews = [];
+        this.shadowTexture = this.device.createTexture({
+            size: [this.settings.shadowMapSize, this.settings.shadowMapSize, this.settings.cascadeCount],
+            format: "depth32float",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.shadowView = this.shadowTexture.createView({
+            dimension: "2d-array",
+            arrayLayerCount: this.settings.cascadeCount,
+        });
+        // Create per-cascade views for rendering to individual layers
+        this.cascadeViews = [];
+        for (let i = 0; i < this.settings.cascadeCount; i++) {
+            this.cascadeViews.push(this.shadowTexture.createView({
+                dimension: "2d",
+                baseArrayLayer: i,
+                arrayLayerCount: 1,
+            }));
+        }
+        this.shadowSampler = this.device.createSampler({
+            compare: "less",
+            magFilter: "linear",
+            minFilter: "linear",
+        });
+        const uniformSize = CSMUniforms.size;
+        this.uniformBuffer = this.device.createBuffer({
+            size: uniformSize,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this._uniformBuf = new Float32Array(CSMUniforms.floatCount);
+        this._uniformView = CSMUniforms.view(this._uniformBuf);
+        this.modelBuffer = this.device.createBuffer({
+            size: 64,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    computeCascadeSplits(near, far) {
+        const splits = [];
+        const count = this.settings.cascadeCount;
+        const lambda = this.settings.lambda;
+        for (let i = 0; i < count; i++) {
+            const p = (i + 1) / count;
+            const logSplit = near * Math.pow(far / near, p);
+            const linearSplit = near + (far - near) * p;
+            splits.push(near + (logSplit - near) * lambda + (linearSplit - near) * (1 - lambda));
+        }
+        this.cascadeSplits = splits;
+        return splits;
+    }
+    computeCascadeViewProjs(lightDir, cameraPos, cameraDir, cameraUp, near, far, aspect, fov) {
+        const splits = this.computeCascadeSplits(near, far);
+        const tanHalfFov = Math.tan(fov * 0.5);
+        for (let i = 0; i < this.settings.cascadeCount; i++) {
+            const cascadeNear = i === 0 ? near : splits[i - 1];
+            const cascadeFar = splits[i];
+            const cascadeMid = (cascadeNear + cascadeFar) * 0.5;
+            const cascadeExtent = (cascadeFar - cascadeNear) * 0.5;
+            const frustumHeight = tanHalfFov * cascadeMid * 2;
+            const frustumWidth = frustumHeight * aspect;
+            const maxRadius = Math.sqrt(frustumWidth * frustumWidth + frustumHeight * frustumHeight + 4 * cascadeExtent * cascadeExtent) * 0.55;
+            const eye = vec3.create(cameraPos[0] - lightDir[0] * maxRadius, cameraPos[1] - lightDir[1] * maxRadius, cameraPos[2] - lightDir[2] * maxRadius);
+            const view = mat4.lookAt(eye, vec3.create(cameraPos[0], cameraPos[1], cameraPos[2]), vec3.create(0, 1, 0));
+            const proj = mat4.ortho(-maxRadius, maxRadius, -maxRadius, maxRadius, 0.1, maxRadius * 4);
+            this.cascadeViewProjs[i] = mat4.multiply(proj, view);
+        }
+        this.uploadUniforms();
+    }
+    uploadUniforms() {
+        const buf = this._uniformBuf;
+        const view = this._uniformView;
+        buf.fill(0);
+        // Per-cascade viewProj + texelSize — written directly into the preallocated
+        // buffer (the typed view does not support indexed array-of-struct access).
+        const cascadeStride = CascadeUniforms.floatCount; // 20 floats per cascade
+        for (let i = 0; i < MAX_CASCADES; i++) {
+            const off = i * cascadeStride;
+            buf.set(this.cascadeViewProjs[i], off);
+            buf[off + 16] = 1.0 / this.settings.shadowMapSize;
+            buf[off + 17] = 1.0 / this.settings.shadowMapSize;
+            buf[off + 18] = 0;
+            buf[off + 19] = 0;
+        }
+        view.set("cascadeSplits", [
+            this.cascadeSplits[0] ?? 0,
+            this.cascadeSplits[1] ?? 0,
+            this.cascadeSplits[2] ?? 0,
+            this.cascadeSplits[3] ?? 0,
+        ]);
+        view.set("lightDir", [0, 0, 0, 0]);
+        view.set("cascadeCount", [
+            this.settings.cascadeCount,
+            this.settings.bias,
+            this.settings.normalBias,
+            this.settings.blendDistance,
+        ]);
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, buf);
+    }
+    getPipeline(stride) {
+        let pipeline = this.pipelines.get(stride);
+        if (!pipeline) {
+            pipeline = this.device.createRenderPipeline({
+                layout: "auto",
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: "vs_main",
+                    buffers: [{
+                            arrayStride: stride,
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: "float32x3" },
+                                { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            ],
+                        }],
+                },
+                primitive: { topology: "triangle-list", cullMode: "back" },
+                depthStencil: {
+                    format: "depth32float",
+                    depthWriteEnabled: true,
+                    depthCompare: "less",
+                },
+            });
+            this.pipelines.set(stride, pipeline);
+            this.bindGroups.set(stride, this.device.createBindGroup({
+                layout: pipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: { buffer: this.uniformBuffer } },
+                    { binding: 1, resource: { buffer: this.modelBuffer } },
+                ],
+            }));
+        }
+        return pipeline;
+    }
+    setModelMatrix(model) {
+        this.device.queue.writeBuffer(this.modelBuffer, 0, model);
+    }
+    getShadowView() {
+        return this.shadowView;
+    }
+    getShadowSampler() {
+        return this.shadowSampler;
+    }
+    getCascadeViewProjs() {
+        return this.cascadeViewProjs;
+    }
+    getCascadeSplits() {
+        return this.cascadeSplits;
+    }
+    getSettings() {
+        return this.settings;
+    }
+    setup(builder) {
+        if (this.shadowHandle) {
+            builder.write(this.shadowHandle);
+        }
+    }
+    renderCascade(encoder, cascadeIndex, meshes) {
+        if (!this.shadowView || !this.shaderModule)
+            return;
+        // Use the per-cascade view to render to the correct layer of the 2d-array texture
+        const cascadeView = this.cascadeViews[cascadeIndex] ?? this.shadowView;
+        const pass = encoder.beginRenderPass({
+            colorAttachments: [],
+            depthStencilAttachment: {
+                view: cascadeView,
+                depthClearValue: 1.0,
+                depthLoadOp: "clear",
+                depthStoreOp: "store",
+            },
+        });
+        const tracked = new TrackedRenderPass(pass);
+        meshes.forEach(({ mesh, model }) => {
+            this.setModelMatrix(model);
+            const pipeline = this.getPipeline(mesh.layout.stride);
+            const bindGroup = this.bindGroups.get(mesh.layout.stride);
+            tracked.setPipeline(pipeline);
+            tracked.setBindGroup(0, bindGroup);
+            tracked.setVertexBuffer(0, this.getVertexBuffer(mesh));
+            tracked.setIndexBuffer(this.getIndexBuffer(mesh), mesh.indices instanceof Uint16Array ? "uint16" : "uint32");
+            tracked.drawIndexed(mesh.indexCount);
+        });
+        tracked.end();
+    }
+    execute(ctx) {
+        if (!this.shaderModule || !ctx.shadowsEnabled)
+            return;
+    }
+    getVertexBuffer(mesh) {
+        let buf = this.vertexBuffers.get(mesh);
+        if (!buf) {
+            buf = this.device.createBuffer({
+                size: mesh.vertices.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            this.device.queue.writeBuffer(buf, 0, mesh.vertices.buffer);
+            this.vertexBuffers.set(mesh, buf);
+        }
+        return buf;
+    }
+    getIndexBuffer(mesh) {
+        let buf = this.indexBuffers.get(mesh);
+        if (!buf) {
+            buf = this.device.createBuffer({
+                size: mesh.indices.byteLength,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+            this.device.queue.writeBuffer(buf, 0, mesh.indices.buffer);
+            this.indexBuffers.set(mesh, buf);
+        }
+        return buf;
+    }
+    destroy() {
+        this.shadowTexture?.destroy();
+        this.shadowView = null;
+        // GPUSampler has no destroy() — it's GC'd automatically.
+        this.shadowSampler = null;
+        this.uniformBuffer?.destroy();
+        this.modelBuffer?.destroy();
+        this._uniformView = null;
+        this._uniformBuf = null;
+        for (const buf of this.vertexBuffers.values())
+            buf.destroy();
+        for (const buf of this.indexBuffers.values())
+            buf.destroy();
+        this.vertexBuffers.clear();
+        this.indexBuffers.clear();
+        destroyMapValues(this.pipelines);
+        destroyMapValues(this.bindGroups);
+    }
+}

package/dist/core/src/render/passes/cubemap-capture.js

@@ -0,0 +1,93 @@
+import { mat4 } from "wgpu-matrix";
+import { TrackedRenderPass } from "../tracked-render-pass.js";
+import { SkyDomePass } from "./sky-dome.js";
+const FACE_DIRS = [
+    { target: [1, 0, 0], up: [0, -1, 0] },
+    { target: [-1, 0, 0], up: [0, -1, 0] },
+    { target: [0, 1, 0], up: [0, 0, 1] },
+    { target: [0, -1, 0], up: [0, 0, -1] },
+    { target: [0, 0, 1], up: [0, -1, 0] },
+    { target: [0, 0, -1], up: [0, -1, 0] },
+];
+export class CubemapCapturePass {
+    device;
+    faceSize;
+    cubemapTexture = null;
+    depthTexture = null;
+    skyDomePass;
+    constructor(device, options = {}) {
+        this.device = device;
+        this.faceSize = options.faceSize ?? 256;
+        this.skyDomePass = new SkyDomePass(device, "rgba16float", 1);
+        this.skyDomePass.prepare(device);
+    }
+    getCubemapTexture() {
+        return this.cubemapTexture;
+    }
+    capture(uniforms) {
+        // Create a fresh cubemap texture each capture. The caller (IBLSystem) owns
+        // the returned texture's lifecycle and defers destruction of the previous
+        // cubemap until after the frame's command buffers have been submitted.
+        // Reusing a single texture here would conflict with that deferred-destroy
+        // contract — the next capture would render into a destroyed texture.
+        this.cubemapTexture = this.device.createTexture({
+            size: [this.faceSize, this.faceSize, 6],
+            format: "rgba16float",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        if (!this.depthTexture) {
+            this.depthTexture = this.device.createTexture({
+                size: [this.faceSize, this.faceSize],
+                format: "depth32float",
+                usage: GPUTextureUsage.RENDER_ATTACHMENT,
+            });
+        }
+        const proj = mat4.perspective(Math.PI / 2, 1.0, 0.1, 10000.0);
+        // DEVIATION: This pass creates its own command encoder and submits per face
+        // (6 submissions) instead of using the frame graph's shared encoder. This is
+        // intentional — cubemap capture is a one-shot offline render that happens
+        // outside the per-frame render loop, so it cannot share the frame encoder.
+        for (let face = 0; face < 6; face++) {
+            const faceView = this.cubemapTexture.createView({
+                dimension: "2d",
+                baseArrayLayer: face,
+                arrayLayerCount: 1,
+            });
+            const depthView = this.depthTexture.createView();
+            const encoder = this.device.createCommandEncoder();
+            const renderPass = encoder.beginRenderPass({
+                colorAttachments: [{
+                        view: faceView,
+                        loadOp: "clear",
+                        storeOp: "store",
+                        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+                    }],
+                depthStencilAttachment: {
+                    view: depthView,
+                    depthClearValue: 1.0,
+                    depthLoadOp: "clear",
+                    depthStoreOp: "store",
+                },
+            });
+            const view = mat4.lookAt([0, 0, 0], FACE_DIRS[face].target, FACE_DIRS[face].up);
+            const viewProj = mat4.multiply(proj, view);
+            this.skyDomePass.setUniforms({
+                ...uniforms,
+                viewProj: viewProj,
+                cameraPos: [0, 0, 0],
+            });
+            const tracked = new TrackedRenderPass(renderPass);
+            this.skyDomePass.execute({ device: this.device, pass: tracked });
+            tracked.end();
+            this.device.queue.submit([encoder.finish()]);
+        }
+        return this.cubemapTexture;
+    }
+    destroy() {
+        this.cubemapTexture?.destroy();
+        this.depthTexture?.destroy();
+        this.skyDomePass.destroy();
+        this.cubemapTexture = null;
+        this.depthTexture = null;
+    }
+}

package/dist/core/src/render/passes/debug-viz.js

@@ -0,0 +1,248 @@
+import { createValidatedShaderModule } from "../shader-validator.js";
+import { RenderPass } from "../render-pass.js";
+import { destroyMapValues } from "../resource-tracker.js";
+const AABB_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> @builtin(position) vec4<f32> {\n  return camera.viewProj * vec4<f32>(input.position, 1.0);\n}\n\n@fragment\nfn fs_main() -> @location(0) vec4<f32> {\n  return vec4<f32>(0.0, 1.0, 0.0, 1.0);\n}\n";
+const DEPTH_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPosition: vec4<f32>,\n  @location(0) depth: f32,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);\n  output.depth = output.clipPosition.z / output.clipPosition.w;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let d = input.depth;\n  return vec4<f32>(d, d, d, 1.0);\n}\n";
+const LOD_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\nstruct LodUniforms {\n  level: f32,\n  _pad: vec3<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(0) @binding(1) var<uniform> lod: LodUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPosition: vec4<f32>,\n  @location(0) vLevel: f32,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);\n  output.vLevel = lod.level;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let l = input.vLevel;\n  if (l < 0.5) { return vec4<f32>(0.0, 1.0, 0.0, 1.0); }\n  if (l < 1.5) { return vec4<f32>(1.0, 1.0, 0.0, 1.0); }\n  if (l < 2.5) { return vec4<f32>(1.0, 0.5, 0.0, 1.0); }\n  return vec4<f32>(1.0, 0.0, 0.0, 1.0);\n}\n";
+const NORMALS_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPosition: vec4<f32>,\n  @location(0) normal: vec3<f32>,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);\n  output.normal = input.normal;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let n = normalize(input.normal);\n  return vec4<f32>(abs(n), 1.0);\n}\n";
+const OVERDRAW_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> @builtin(position) vec4<f32> {\n  return camera.viewProj * vec4<f32>(input.position, 1.0);\n}\n\n@fragment\nfn fs_main() -> @location(0) vec4<f32> {\n  // Each overdraw adds more red — accumulates via additive blend\n  return vec4<f32>(0.1, 0.0, 0.0, 1.0);\n}\n";
+const TANGENTS_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) tangent: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPosition: vec4<f32>,\n  @location(0) vColor: vec3<f32>,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);\n  output.vColor = abs(normalize(input.tangent));\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  return vec4<f32>(input.vColor, 1.0);\n}\n";
+const WIREFRAME_SHADER = "struct CameraUniforms {\n  viewProj: mat4x4<f32>,\n  _pad0: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPosition: vec4<f32>,\n  @location(0) normal: vec3<f32>,\n  @location(1) depth: f32,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);\n  output.normal = input.normal;\n  output.depth = output.clipPosition.z / output.clipPosition.w;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let n = normalize(input.normal);\n  let color = (n * 0.5 + 0.5);\n  return vec4<f32>(color, 1.0);\n}\n";
+export const DEFAULT_DEBUG_VIZ_SETTINGS = {
+    mode: null,
+    wireframeColor: [0.5, 1.0, 0.8],
+    lodRanges: [10, 25, 50, 100],
+};
+export class DebugVizPass extends RenderPass {
+    name = "debug-viz";
+    surfaceHandle = null;
+    depthHandle = null;
+    device = null;
+    surfaceFormat;
+    pipelines = new Map();
+    cameraBuffer = null;
+    bindGroup = null;
+    settings = DEFAULT_DEBUG_VIZ_SETTINGS;
+    lodBuffer = null;
+    lodBindGroup = null;
+    aabbBuffer = null;
+    aabbPipeline = null;
+    aabbBindGroup = null;
+    constructor(surfaceFormat = "rgba16float") {
+        super();
+        this.surfaceFormat = surfaceFormat;
+    }
+    prepare(device) {
+        this.device = device;
+        this.cameraBuffer = device.createBuffer({
+            size: 80,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.lodBuffer = device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // AABB line buffer: 24 vertices (12 edges × 2 endpoints) × 3 floats
+        this.aabbBuffer = device.createBuffer({
+            size: 24 * 3 * 4,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        const meshShaders = [
+            ["wireframe", WIREFRAME_SHADER],
+            ["normals", NORMALS_SHADER],
+            ["overdraw", OVERDRAW_SHADER],
+            ["depth", DEPTH_SHADER],
+            ["tangents", TANGENTS_SHADER],
+            ["lod", LOD_SHADER],
+        ];
+        meshShaders.forEach(([mode, code]) => {
+            const module = createValidatedShaderModule(device, { code, label: "DebugViz" });
+            const primitive = mode === "wireframe"
+                ? { topology: "line-list" }
+                : { topology: "triangle-list" };
+            const blend = mode === "overdraw"
+                ? {
+                    color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+                    alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
+                }
+                : undefined;
+            const targets = [{
+                    format: this.surfaceFormat,
+                    ...(blend ? { blend } : {}),
+                }];
+            const pipeline = device.createRenderPipeline({
+                layout: "auto",
+                vertex: {
+                    module,
+                    entryPoint: "vs_main",
+                    buffers: [{
+                            arrayStride: 24,
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: "float32x3" },
+                                { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            ],
+                        }],
+                },
+                fragment: { module, entryPoint: "fs_main", targets },
+                primitive,
+            });
+            this.pipelines.set(mode, pipeline);
+        });
+        // LOD bind group (needs lod uniform in addition to camera)
+        const lodPipeline = this.pipelines.get("lod");
+        if (lodPipeline) {
+            this.lodBindGroup = device.createBindGroup({
+                layout: lodPipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: { buffer: this.cameraBuffer } },
+                    { binding: 1, resource: { buffer: this.lodBuffer } },
+                ],
+            });
+        }
+        // AABB pipeline (line-list, position-only vertices)
+        const aabbModule = createValidatedShaderModule(device, { code: AABB_SHADER, label: "DebugViz.aabb" });
+        this.aabbPipeline = device.createRenderPipeline({
+            layout: "auto",
+            vertex: {
+                module: aabbModule,
+                entryPoint: "vs_main",
+                buffers: [{
+                        arrayStride: 12,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                        ],
+                    }],
+            },
+            fragment: { module: aabbModule, entryPoint: "fs_main", targets: [{ format: this.surfaceFormat }] },
+            primitive: { topology: "line-list" },
+        });
+        this.aabbBindGroup = device.createBindGroup({
+            layout: this.aabbPipeline.getBindGroupLayout(0),
+            entries: [{ binding: 0, resource: { buffer: this.cameraBuffer } }],
+        });
+        // Use first pipeline's layout for bind group
+        const firstPipeline = this.pipelines.values().next().value;
+        if (firstPipeline) {
+            this.bindGroup = device.createBindGroup({
+                layout: firstPipeline.getBindGroupLayout(0),
+                entries: [{ binding: 0, resource: { buffer: this.cameraBuffer } }],
+            });
+        }
+    }
+    setCamera(viewProj) {
+        if (!this.device || !this.cameraBuffer)
+            return;
+        const data = new Float32Array(20);
+        data.set(viewProj, 0);
+        this.device.queue.writeBuffer(this.cameraBuffer, 0, data);
+    }
+    setSettings(settings) {
+        this.settings = { ...this.settings, ...settings };
+    }
+    getMode() {
+        return this.settings.mode;
+    }
+    setMode(mode) {
+        this.settings = { ...this.settings, mode };
+    }
+    renderMesh(ctx, vertexBuffer, indexBuffer, indexCount) {
+        if (!this.settings.mode || !this.bindGroup || !ctx.pass)
+            return;
+        if (this.settings.mode === "lod") {
+            const pipeline = this.pipelines.get("lod");
+            if (!pipeline || !this.lodBindGroup)
+                return;
+            const pass = ctx.pass;
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, this.lodBindGroup);
+            pass.setVertexBuffer(0, vertexBuffer);
+            if (indexBuffer) {
+                pass.setIndexBuffer(indexBuffer, "uint16");
+                pass.drawIndexed(indexCount);
+            }
+            else {
+                pass.draw(indexCount);
+            }
+            return;
+        }
+        const pipeline = this.pipelines.get(this.settings.mode);
+        if (!pipeline)
+            return;
+        const pass = ctx.pass;
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, this.bindGroup);
+        pass.setVertexBuffer(0, vertexBuffer);
+        if (indexBuffer) {
+            pass.setIndexBuffer(indexBuffer, "uint16");
+            pass.drawIndexed(indexCount);
+        }
+        else {
+            pass.draw(indexCount);
+        }
+    }
+    renderAABB(ctx, min, max) {
+        if (!this.device || !this.aabbPipeline || !this.aabbBindGroup || !this.aabbBuffer)
+            return;
+        const [minX, minY, minZ] = min;
+        const [maxX, maxY, maxZ] = max;
+        const vertices = new Float32Array([
+            minX, minY, minZ, maxX, minY, minZ,
+            maxX, minY, minZ, maxX, maxY, minZ,
+            maxX, maxY, minZ, minX, maxY, minZ,
+            minX, maxY, minZ, minX, minY, minZ,
+            minX, minY, maxZ, maxX, minY, maxZ,
+            maxX, minY, maxZ, maxX, maxY, maxZ,
+            maxX, maxY, maxZ, minX, maxY, maxZ,
+            minX, maxY, maxZ, minX, minY, maxZ,
+            minX, minY, minZ, minX, minY, maxZ,
+            maxX, minY, minZ, maxX, minY, maxZ,
+            maxX, maxY, minZ, maxX, maxY, maxZ,
+            minX, maxY, minZ, minX, maxY, maxZ,
+        ]);
+        this.device.queue.writeBuffer(this.aabbBuffer, 0, vertices);
+        const pass = ctx.pass;
+        if (!pass)
+            return;
+        pass.setPipeline(this.aabbPipeline);
+        pass.setBindGroup(0, this.aabbBindGroup);
+        pass.setVertexBuffer(0, this.aabbBuffer);
+        pass.draw(24);
+    }
+    setLodLevel(level) {
+        if (!this.device || !this.lodBuffer)
+            return;
+        const data = new Float32Array(4);
+        data[0] = level;
+        this.device.queue.writeBuffer(this.lodBuffer, 0, data);
+    }
+    setup(builder) {
+        if (this.depthHandle)
+            builder.depthAttachment({ handle: this.depthHandle, depthLoadOp: "load", depthStoreOp: "store", depthReadOnly: true });
+        if (this.surfaceHandle)
+            builder.colorAttachment({ handle: this.surfaceHandle, loadOp: "load", storeOp: "store" });
+    }
+    execute(ctx) {
+        if (!ctx.pass)
+            return;
+        this.setCamera(ctx.viewProj);
+        if (!this.settings.mode)
+            return;
+        const vb = ctx.opaqueVertexBuffer;
+        const ib = ctx.opaqueIndexBuffer;
+        const indexCount = ctx.opaqueIndexCount;
+        if (vb && ib && indexCount > 0) {
+            this.renderMesh(ctx, vb, ib, indexCount);
+        }
+    }
+    destroy() {
+        this.cameraBuffer?.destroy();
+        this.cameraBuffer = null;
+        this.lodBuffer?.destroy();
+        this.lodBuffer = null;
+        this.aabbBuffer?.destroy();
+        this.aabbBuffer = null;
+        destroyMapValues(this.pipelines);
+        this.aabbPipeline?.destroy();
+        this.aabbPipeline = null;
+    }
+}