@downdraft/engine 0.1.0 → 0.1.2-alpha.5

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

@@ -0,0 +1,966 @@
+import { getProfile, mat4x4f, wgsl } from "@downdraft/engine/shader-graph";
+import { mat4 } from "wgpu-matrix";
+import { compileVariant } from "../../material/graph-bridge.js";
+import { variantKey } from "../../material/variants.js";
+import { BindlessMaterialStruct } from "../bindless/index.js";
+import { createUniformBuffer } from "../gpu-utils.js";
+import { RenderPass } from "../render-pass.js";
+import { destroyMapValues } from "../resource-tracker.js";
+import { createValidatedShaderModule } from "../shader-validator.js";
+// ─── Camera uniform structs (single source of truth for layout) ────────────
+// Previously these were hand-written inline in each shader string and mirrored
+// by magic-offset data.set() calls in updateCamera/updatePBRCamera/updateGraphCamera.
+/** GBUFFER_SHADER camera: 4× mat4x4 = 256 bytes. */
+const CameraUniformsGbuffer = wgsl.struct("CameraUniforms", {
+    viewProj: mat4x4f,
+    prevViewProj: mat4x4f,
+    modelMatrix: mat4x4f,
+    prevModelMatrix: mat4x4f,
+});
+/** SIMPLE_SHADER camera: 2× mat4x4 = 128 bytes. */
+const CameraUniformsSimple = wgsl.struct("CameraUniforms", {
+    viewProj: mat4x4f,
+    modelMatrix: mat4x4f,
+});
+/** PBR_GBUFFER_SHADER camera: 2× mat4x4 = 128 bytes (model/prevModel are
+ *  separate @binding(1)/(2) uniforms, not in this struct). */
+const CameraUniformsPBR = wgsl.struct("CameraUniforms", {
+    viewProj: mat4x4f,
+    prevViewProj: mat4x4f,
+});
+const GBUFFER_SHADER = `
+${CameraUniformsGbuffer.wgsl}
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) color: vec4<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+  @location(1) worldNormal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) color: vec4<f32>,
+  @location(4) prevClipPosition: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = camera.modelMatrix * vec4<f32>(input.position, 1.0);
+  output.clipPosition = camera.viewProj * worldPos;
+  output.worldPos = worldPos.xyz;
+  output.worldNormal = normalize((camera.modelMatrix * vec4<f32>(input.normal, 0.0)).xyz);
+  output.uv = input.uv;
+  output.color = input.color;
+  let prevWorldPos = camera.prevModelMatrix * vec4<f32>(input.position, 1.0);
+  output.prevClipPosition = camera.prevViewProj * prevWorldPos;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32>,
+                                    @location(1) vec4<f32>,
+                                    @location(2) vec4<f32>,
+                                    @location(3) vec2<f32> {
+  // GBuffer0: albedo (RGB) + AO (A)
+  let albedo = input.color.rgb;
+  let ao = 1.0;
+  // GBuffer1: normal (RGB) + roughness (A)
+  let encodedNormal = normalize(input.worldNormal) * 0.5 + 0.5;
+  let roughness = 0.5;
+  // GBuffer2: metallic (R) + emissive (GBA)
+  let metallic = 0.0;
+  let emissive = vec3<f32>(0.0);
+  // Velocity: screen-space motion (curr - prev)
+  let currNDC = input.clipPosition.xy / input.clipPosition.w;
+  let prevNDC = input.prevClipPosition.xy / input.prevClipPosition.w;
+  let velocity = (currNDC - prevNDC) * 0.5;
+
+  return vec4<f32>(albedo, ao),
+         vec4<f32>(encodedNormal, roughness),
+         vec4<f32>(metallic, emissive),
+         velocity;
+}
+`;
+const PBR_GBUFFER_SHADER = `
+${CameraUniformsPBR.wgsl}
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var modelUniform: mat4x4<f32>;
+@group(0) @binding(2) var prevModelUniform: mat4x4<f32>;
+@group(0) @binding(3) var<uniform> materialIndex: u32;
+
+// Bindless material binding model (@group(3)) — struct emitted from
+// BindlessMaterialStruct (single source of truth, shared with material-manager).
+${BindlessMaterialStruct.wgsl}
+
+@group(3) @binding(0) var<storage, read> bindlessMaterials: array<BindlessMaterial>;
+@group(3) @binding(1) var albedoArray0: texture_2d_array<f32>;
+@group(3) @binding(2) var albedoArray1: texture_2d_array<f32>;
+@group(3) @binding(3) var albedoArray2: texture_2d_array<f32>;
+@group(3) @binding(4) var albedoArray3: texture_2d_array<f32>;
+@group(3) @binding(5) var albedoArray4: texture_2d_array<f32>;
+@group(3) @binding(6) var albedoArray5: texture_2d_array<f32>;
+@group(3) @binding(7) var albedoArray6: texture_2d_array<f32>;
+@group(3) @binding(8) var albedoArray7: texture_2d_array<f32>;
+@group(3) @binding(9) var bindlessSamplerRepeat: sampler;
+@group(3) @binding(10) var bindlessSamplerClamp: sampler;
+
+fn unpackArrayIndex(handle: u32) -> u32 { return (handle >> 16u) & 0xFFFFu; }
+fn unpackLayerIndex(handle: u32) -> u32 { return handle & 0xFFFFu; }
+
+fn sampleBindlessArray(arr: u32, uv: vec2<f32>, layer: u32) -> vec4<f32> {
+  switch (arr) {
+    case 0u: { return textureSample(albedoArray0, bindlessSamplerRepeat, uv, layer); }
+    case 1u: { return textureSample(albedoArray1, bindlessSamplerRepeat, uv, layer); }
+    case 2u: { return textureSample(albedoArray2, bindlessSamplerRepeat, uv, layer); }
+    case 3u: { return textureSample(albedoArray3, bindlessSamplerRepeat, uv, layer); }
+    case 4u: { return textureSample(albedoArray4, bindlessSamplerRepeat, uv, layer); }
+    case 5u: { return textureSample(albedoArray5, bindlessSamplerRepeat, uv, layer); }
+    case 6u: { return textureSample(albedoArray6, bindlessSamplerRepeat, uv, layer); }
+    case 7u: { return textureSample(albedoArray7, bindlessSamplerRepeat, uv, layer); }
+    default: { return vec4<f32>(1.0, 1.0, 1.0, 1.0); }
+  }
+}
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) tangent: vec4<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) worldPosition: vec3<f32>,
+  @location(1) uv: vec2<f32>,
+  @location(2) worldNormal: vec3<f32>,
+  @location(3) worldTangent: vec3<f32>,
+  @location(4) worldBitangent: vec3<f32>,
+  @location(5) prevClipPosition: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = modelUniform * vec4<f32>(input.position, 1.0);
+  output.clipPosition = camera.viewProj * worldPos;
+  output.worldPosition = worldPos.xyz;
+
+  // KHR_texture_transform: scale, rotate, translate UVs.
+  let m = bindlessMaterials[materialIndex];
+  if (m.hasTexTransform > 0.5) {
+    let cosR = cos(m.texRotation);
+    let sinR = sin(m.texRotation);
+    let scaled = input.uv * m.texScale;
+    output.uv = vec2<f32>(
+      cosR * scaled.x - sinR * scaled.y + m.texOffset.x,
+      sinR * scaled.x + cosR * scaled.y + m.texOffset.y,
+    );
+  } else {
+    output.uv = input.uv;
+  }
+
+  let normalMatrix = mat3x3<f32>(
+    modelUniform[0].xyz,
+    modelUniform[1].xyz,
+    modelUniform[2].xyz,
+  );
+  output.worldNormal = normalize(normalMatrix * input.normal);
+  output.worldTangent = normalize(normalMatrix * input.tangent.xyz);
+  output.worldBitangent = cross(output.worldNormal, output.worldTangent) * input.tangent.w;
+
+  let prevWorldPos = prevModelUniform * vec4<f32>(input.position, 1.0);
+  output.prevClipPosition = camera.prevViewProj * prevWorldPos;
+
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> (
+  @location(0) vec4<f32>,
+  @location(1) vec4<f32>,
+  @location(2) vec4<f32>,
+  @location(3) vec2<f32>,
+) {
+  let m = bindlessMaterials[materialIndex];
+  let albArr = unpackArrayIndex(m.albedoTex);
+  let albLayer = unpackLayerIndex(m.albedoTex);
+  let albedo = sampleBindlessArray(albArr, input.uv, albLayer) * m.baseColor;
+
+  let mrArr = unpackArrayIndex(m.metallicRoughnessTex);
+  let mrLayer = unpackLayerIndex(m.metallicRoughnessTex);
+  let mr = sampleBindlessArray(mrArr, input.uv, mrLayer);
+  let metallic = mr.b * m.metallic;
+  let roughness = mr.g * m.roughness;
+
+  let aoHandle = m.aoEmissiveTex & 0xFFFFu;
+  let aoArr = unpackArrayIndex(aoHandle);
+  let aoLayer = unpackLayerIndex(aoHandle);
+  let ao = sampleBindlessArray(aoArr, input.uv, aoLayer).r;
+
+  let emHandle = (m.aoEmissiveTex >> 16u) & 0xFFFFu;
+  let emArr = unpackArrayIndex(emHandle);
+  let emLayer = unpackLayerIndex(emHandle);
+  let emissive = sampleBindlessArray(emArr, input.uv, emLayer).rgb * m.emissiveIntensity;
+
+  let nArr = unpackArrayIndex(m.normalTex);
+  let nLayer = unpackLayerIndex(m.normalTex);
+  let tangentNormal = sampleBindlessArray(nArr, input.uv, nLayer).xyz * 2.0 - 1.0;
+  let TBN = mat3x3<f32>(
+    input.worldTangent,
+    input.worldBitangent,
+    input.worldNormal,
+  );
+  let worldNormal = normalize(TBN * tangentNormal);
+  let encodedNormal = (worldNormal * 0.5 + 0.5);
+
+  let currNDC = input.clipPosition.xy / input.clipPosition.w;
+  let prevNDC = input.prevClipPosition.xy / input.prevClipPosition.w;
+  let velocity = (currNDC - prevNDC) * 0.5;
+
+  return (
+    vec4<f32>(albedo.rgb, ao),
+    vec4<f32>(encodedNormal, roughness),
+    vec4<f32>(metallic, emissive.r, emissive.g, emissive.b),
+    velocity,
+  );
+}
+`;
+const SIMPLE_SHADER = `
+${CameraUniformsSimple.wgsl}
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) uv: vec2<f32>,
+  @location(3) color: vec4<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(1) normal: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = camera.modelMatrix * vec4<f32>(input.position, 1.0);
+  output.clipPosition = camera.viewProj * worldPos;
+  output.color = input.color;
+  output.normal = input.normal;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let lightDir = normalize(vec3<f32>(0.5, 0.8, 0.3));
+  let lambert = max(dot(normalize(input.normal), lightDir), 0.0);
+  let ambient = 0.3;
+  let intensity = ambient + lambert * 0.7;
+  return vec4<f32>(input.color.rgb * intensity, input.color.a);
+}
+`;
+export class OpaquePass extends RenderPass {
+    name = "opaque";
+    // Graph handles (set by RenderLoop before graph build)
+    gbufferAlbedoHandle = null;
+    gbufferNormalHandle = null;
+    gbufferMetallicEmissiveHandle = null;
+    gbufferVelocityHandle = null;
+    gbufferDepthHandle = null;
+    surfaceHandle = null; // for simple mode
+    depthHandle = null; // for simple mode depth
+    device;
+    pipeline = null;
+    vertexBuffer = null;
+    indexBuffer = null;
+    mesh = null;
+    depthTexture = null;
+    deferredDepthTextures = [];
+    shaderModule = null;
+    surfaceFormat;
+    mode;
+    cameraBuffer = null;
+    bindGroup = null;
+    modelMatrix = mat4.identity();
+    prevModelMatrix = mat4.identity();
+    prevViewProj = mat4.identity();
+    pbrPipeline = null;
+    pbrShaderModule = null;
+    pbrCameraBuffer = null;
+    pbrModelBuffer = null;
+    pbrPrevModelBuffer = null;
+    pbrMaterialIndexBuffer = null;
+    pbrCameraBindGroup = null;
+    pbrMaterial = null;
+    pbrMaterialIndex = 0;
+    pbrMaterialRegistered = false;
+    // Bindless deps (optional — when set, the PBR path uses @group(3))
+    bindlessRegistry = null;
+    bindlessMaterialManager = null;
+    bindlessBindGroup = null;
+    lastViewProj = mat4.identity();
+    graphMaterial = null;
+    graphPipeline = null;
+    // Per-variant pipeline cache (keyed by variantKey). Bounded — when exceeding
+    // MAX_VARIANT_PIPELINES, the oldest entry is evicted.
+    graphVariantPipelines = new Map();
+    graphVariantShaderModules = new Map();
+    static MAX_VARIANT_PIPELINES = 24;
+    graphShaderModule = null;
+    graphCameraBuffer = null;
+    graphBindGroup = null;
+    graphProfile = null;
+    graphExtraBindGroups = new Map();
+    graphInstanceBuffer = null;
+    graphInstanceCount = 0;
+    graphUniformData = null;
+    // Preallocated typed views for camera uniform writes (avoid per-frame alloc).
+    _gbufferCamView = null;
+    _gbufferCamBuf = null;
+    _simpleCamView = null;
+    _simpleCamBuf = null;
+    _pbrCamView = null;
+    _pbrCamBuf = null;
+    constructor(device, surfaceFormat, mode = "gbuffer") {
+        super();
+        this.device = device;
+        this.surfaceFormat = surfaceFormat ?? (navigator.gpu ? navigator.gpu.getPreferredCanvasFormat() : "bgra8unorm");
+        this.mode = mode;
+    }
+    setMesh(mesh) {
+        this.mesh = mesh;
+        this.vertexBuffer = this.device.createBuffer({
+            size: mesh.vertices.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.vertexBuffer, 0, mesh.vertices.buffer);
+        this.indexBuffer = this.device.createBuffer({
+            size: mesh.indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.indexBuffer, 0, mesh.indices.buffer);
+    }
+    setShaderSource(wgsl) {
+        this.shaderModule = createValidatedShaderModule(this.device, { code: wgsl, label: "OpaquePass.setShaderSource" });
+        this.pipeline = null;
+    }
+    setModelMatrix(model) {
+        this.prevModelMatrix = this.modelMatrix;
+        this.modelMatrix = model;
+    }
+    setPrevViewProj(prevViewProj) {
+        this.prevViewProj = prevViewProj;
+    }
+    /** Provide bindless deps. When set, the PBR path uses @group(3) for materials. */
+    setBindlessDeps(registry, materialManager, bindGroup) {
+        this.bindlessRegistry = registry;
+        this.bindlessMaterialManager = materialManager;
+        this.bindlessBindGroup = bindGroup;
+        this.pbrPipeline = null; // rebuild pipeline with bindless layout
+        this.pbrMaterialRegistered = false;
+    }
+    /** Update the bindless bind group for the frame (call before execute). */
+    setBindlessBindGroup(bg) {
+        this.bindlessBindGroup = bg;
+    }
+    setPBRMaterial(resources) {
+        this.pbrMaterial = resources;
+        this.pbrPipeline = null;
+        this.pbrMaterialRegistered = false;
+    }
+    setMaterial(material) {
+        if (!material.inlineShaderSource)
+            return;
+        this.graphMaterial = material;
+        this.graphPipeline = null;
+        this.graphBindGroup = null;
+        this.graphExtraBindGroups.clear();
+        this.graphVariantPipelines.clear();
+        this.graphVariantShaderModules.clear();
+        if (material.profile) {
+            this.graphProfile = getProfile(material.profile) ?? null;
+        }
+    }
+    /**
+     * Set the material with a specific variant flag override. The renderer
+     * compiles and caches a pipeline per variantKey. Used for shadow-caster,
+     * skinning, alpha-mode, and morph permutations.
+     */
+    setMaterialVariant(material, variantFlags) {
+        if (!material.inlineShaderSource && !material.graph)
+            return;
+        this.graphMaterial = material;
+        this.graphBindGroup = null;
+        this.graphExtraBindGroups.clear();
+        if (material.profile) {
+            this.graphProfile = getProfile(material.profile) ?? null;
+        }
+        // Compile the variant WGSL if not already cached.
+        const vkey = variantKey(variantFlags);
+        if (!this.graphVariantShaderModules.has(vkey)) {
+            const wgsl = compileVariant(material, variantFlags, this.graphProfile ?? undefined);
+            const module = createValidatedShaderModule(this.device, { code: wgsl, label: "OpaquePass.variant" });
+            this.graphVariantShaderModules.set(vkey, module);
+            // Evict oldest if over cap.
+            if (this.graphVariantPipelines.size >= OpaquePass.MAX_VARIANT_PIPELINES) {
+                const oldestKey = this.graphVariantPipelines.keys().next().value;
+                if (oldestKey) {
+                    this.graphVariantPipelines.get(oldestKey)?.destroy();
+                    this.graphVariantShaderModules.get(oldestKey)?.destroy();
+                    this.graphVariantPipelines.delete(oldestKey);
+                    this.graphVariantShaderModules.delete(oldestKey);
+                }
+            }
+        }
+        // Mark the active pipeline as the variant one (built lazily in ensureGraphPipeline).
+        this.graphPipeline = null;
+    }
+    setGraphProfile(profile) {
+        this.graphProfile = profile;
+        this.graphPipeline = null;
+        this.graphBindGroup = null;
+        this.graphExtraBindGroups.clear();
+        this.graphVariantPipelines.clear();
+        this.graphVariantShaderModules.clear();
+    }
+    setExtraBindGroup(group, bindGroup) {
+        this.graphExtraBindGroups.set(group, bindGroup);
+    }
+    setInstanceBuffer(buffer, count) {
+        this.graphInstanceBuffer = buffer;
+        this.graphInstanceCount = count;
+    }
+    setGraphUniformData(data) {
+        this.graphUniformData = data;
+    }
+    ensureGraphPipeline() {
+        if (this.graphPipeline || !this.mesh || !this.graphMaterial?.inlineShaderSource)
+            return;
+        this.graphShaderModule = createValidatedShaderModule(this.device, { code: this.graphMaterial.inlineShaderSource, label: "OpaquePass.graph" });
+        const profile = this.graphProfile;
+        const uniformSize = profile
+            ? this.calcUniformSize(profile)
+            : 192;
+        this.graphCameraBuffer = createUniformBuffer(this.device, Math.max(uniformSize, 16));
+        const vertexAttrs = profile
+            ? profile.vertexLayout.attributes.map((a) => ({
+                shaderLocation: a.location,
+                offset: a.offset,
+                format: a.format,
+            }))
+            : [
+                { shaderLocation: 0, offset: 0, format: "float32x3" },
+                { shaderLocation: 1, offset: 12, format: "float32x3" },
+                { shaderLocation: 2, offset: 24, format: "float32x2" },
+            ];
+        const stride = profile?.vertexLayout.stride ?? this.mesh.layout.stride;
+        const targets = profile
+            ? this.getProfileTargets(profile)
+            : [{ format: this.surfaceFormat }];
+        const topology = profile?.topology ?? "triangle-list";
+        const cullMode = this.graphMaterial.cullMode === "front" ? "front" : this.graphMaterial.cullMode === "none" ? "none" : "back";
+        const depthWrite = profile?.depthWriteEnabled ?? true;
+        this.graphPipeline = this.device.createRenderPipeline({
+            layout: "auto",
+            vertex: {
+                module: this.graphShaderModule,
+                entryPoint: "vs_main",
+                buffers: [{
+                        arrayStride: stride,
+                        attributes: vertexAttrs,
+                    }],
+            },
+            fragment: {
+                module: this.graphShaderModule,
+                entryPoint: "fs_main",
+                targets,
+            },
+            primitive: {
+                topology: topology,
+                cullMode: cullMode,
+            },
+            depthStencil: {
+                format: "depth32float",
+                depthWriteEnabled: depthWrite,
+                depthCompare: "less",
+            },
+        });
+        // Build bind group 0 — uniform buffer + any profile-defined group 0 bindings
+        const group0Entries = [
+            { binding: 0, resource: { buffer: this.graphCameraBuffer } },
+        ];
+        // Add profile-defined bindings for group 0 (e.g. sampler, texture, storage)
+        if (profile) {
+            const g0 = profile.bindGroups.find((bg) => bg.group === 0);
+            if (g0) {
+                for (let _i = 0, _it = g0.entries, _n = _it.length; _i < _n; _i++) {
+                    const entry = _it[_i];
+                    if (entry.binding === 0)
+                        continue; // Already added uniform
+                    // These resources need to be provided externally — skip if not set
+                }
+            }
+        }
+        this.graphBindGroup = this.device.createBindGroup({
+            layout: this.graphPipeline.getBindGroupLayout(0),
+            entries: group0Entries,
+        });
+    }
+    calcUniformSize(profile) {
+        let size = 0;
+        profile.uniformFields.forEach((field) => {
+            if (field.type === "mat4x4<f32>")
+                size += 64;
+            else if (field.type === "vec4<f32>")
+                size += 16;
+            else if (field.type === "vec3<f32>")
+                size += 16; // vec3 aligned to 16
+            else if (field.type === "vec2<f32>")
+                size += 8;
+            else if (field.type === "f32")
+                size += 4;
+            else if (field.type === "u32")
+                size += 4;
+            else
+                size += 16;
+        });
+        // Align to 16
+        return Math.ceil(size / 16) * 16;
+    }
+    getProfileTargets(profile) {
+        // Multi-render-target (deferred GBuffer) — one target per output format.
+        if (profile.outputFormats && profile.outputFormats.length > 0) {
+            return profile.outputFormats.map((fmt) => ({
+                format: fmt,
+            }));
+        }
+        if (profile.blend === "transparent") {
+            return [{
+                    format: this.surfaceFormat,
+                    blend: {
+                        color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                    },
+                }];
+        }
+        if (profile.blend === "additive") {
+            return [{
+                    format: this.surfaceFormat,
+                    blend: {
+                        color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+                        alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
+                    },
+                }];
+        }
+        return [{ format: this.surfaceFormat }];
+    }
+    updateGraphCamera(viewProj) {
+        if (!this.graphCameraBuffer)
+            return;
+        // If custom uniform data is provided, use it directly
+        if (this.graphUniformData) {
+            this.device.queue.writeBuffer(this.graphCameraBuffer, 0, this.graphUniformData);
+            return;
+        }
+        // Default: write viewProj + modelMatrix + cameraPos + time
+        const profile = this.graphProfile;
+        const size = profile ? this.calcUniformSize(profile) : 192;
+        const data = new Float32Array(size / 4);
+        data.set(viewProj, 0);
+        if (profile) {
+            let offset = 16; // after viewProj (mat4x4)
+            const hasModelMatrix = profile.uniformFields.some((f) => f.name === "modelMatrix");
+            if (hasModelMatrix) {
+                data.set(this.modelMatrix, offset);
+                offset += 16;
+            }
+            // cameraPos (vec3) + time (f32) = 4 floats
+            data.set([0, 0, 0, 0], offset);
+        }
+        else {
+            data.set(this.modelMatrix, 16);
+            data.set([0, 0, 0, 0], 32);
+        }
+        this.device.queue.writeBuffer(this.graphCameraBuffer, 0, data);
+    }
+    ensurePBRPipeline() {
+        if (this.pbrPipeline || !this.mesh)
+            return;
+        if (!this.pbrShaderModule) {
+            this.pbrShaderModule = createValidatedShaderModule(this.device, { code: PBR_GBUFFER_SHADER, label: "OpaquePass.pbrGBuffer" });
+        }
+        this.pbrCameraBuffer = createUniformBuffer(this.device, 128);
+        this.pbrModelBuffer = createUniformBuffer(this.device, 64);
+        this.pbrPrevModelBuffer = createUniformBuffer(this.device, 64);
+        this.pbrMaterialIndexBuffer = createUniformBuffer(this.device, 16); // u32 + padding (uniform buffer min alignment)
+        this._pbrCamBuf = new Float32Array(CameraUniformsPBR.floatCount);
+        this._pbrCamView = CameraUniformsPBR.view(this._pbrCamBuf);
+        this.pbrPipeline = this.device.createRenderPipeline({
+            layout: "auto",
+            vertex: {
+                module: this.pbrShaderModule,
+                entryPoint: "vs_main",
+                buffers: [{
+                        arrayStride: this.mesh.layout.stride,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x2" },
+                            { shaderLocation: 3, offset: 32, format: "float32x4" },
+                        ],
+                    }],
+            },
+            fragment: {
+                module: this.pbrShaderModule,
+                entryPoint: "fs_main",
+                targets: [
+                    { format: "rgba8unorm" },
+                    { format: "rgba8unorm" },
+                    { format: "rgba8unorm" },
+                    { format: "rg16float" },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "back" },
+            depthStencil: {
+                format: "depth32float",
+                depthWriteEnabled: true,
+                depthCompare: "less",
+            },
+        });
+        this.pbrCameraBindGroup = this.device.createBindGroup({
+            layout: this.pbrPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.pbrCameraBuffer } },
+                { binding: 1, resource: { buffer: this.pbrModelBuffer } },
+                { binding: 2, resource: { buffer: this.pbrPrevModelBuffer } },
+                { binding: 3, resource: { buffer: this.pbrMaterialIndexBuffer } },
+            ],
+        });
+    }
+    /** Register/update the PBR material in the bindless material manager. */
+    ensurePBRMaterialRegistered() {
+        if (this.pbrMaterialRegistered || !this.pbrMaterial || !this.bindlessRegistry || !this.bindlessMaterialManager)
+            return;
+        const mat = this.pbrMaterial;
+        const registry = this.bindlessRegistry;
+        const params = {
+            baseColor: mat.baseColor,
+            roughness: mat.roughness,
+            metallic: mat.metallic,
+            emissiveIntensity: mat.emissiveIntensity,
+            albedoTexHandle: mat.albedoTextureSourceId
+                ? registry.getHandle(mat.albedoTextureSourceId) ?? registry.defaultWhiteHandle
+                : registry.defaultWhiteHandle,
+            normalTexHandle: mat.normalTextureSourceId
+                ? registry.getHandle(mat.normalTextureSourceId) ?? registry.defaultWhiteHandle
+                : registry.defaultWhiteHandle,
+            metallicRoughnessTexHandle: mat.metallicRoughnessTextureSourceId
+                ? registry.getHandle(mat.metallicRoughnessTextureSourceId) ?? registry.defaultWhiteHandle
+                : registry.defaultWhiteHandle,
+            aoTexHandle: mat.aoTextureSourceId
+                ? registry.getHandle(mat.aoTextureSourceId) ?? registry.defaultWhiteHandle
+                : registry.defaultWhiteHandle,
+            emissiveTexHandle: mat.emissiveTextureSourceId
+                ? registry.getHandle(mat.emissiveTextureSourceId) ?? registry.defaultWhiteHandle
+                : registry.defaultWhiteHandle,
+            textureTransform: mat.textureTransform,
+        };
+        this.pbrMaterialIndex = this.bindlessMaterialManager.registerMaterial(params);
+        // Write the material index into the uniform buffer (u32 at offset 0).
+        const idxData = new Uint32Array(1);
+        idxData[0] = this.pbrMaterialIndex;
+        this.device.queue.writeBuffer(this.pbrMaterialIndexBuffer, 0, idxData);
+        this.pbrMaterialRegistered = true;
+    }
+    updatePBRCamera(viewProj) {
+        if (!this.pbrCameraBuffer || !this.pbrModelBuffer || !this.pbrPrevModelBuffer)
+            return;
+        const v = this._pbrCamView;
+        v.set("viewProj", viewProj);
+        v.set("prevViewProj", this.prevViewProj);
+        this.device.queue.writeBuffer(this.pbrCameraBuffer, 0, this._pbrCamBuf);
+        this.device.queue.writeBuffer(this.pbrModelBuffer, 0, this.modelMatrix);
+        this.device.queue.writeBuffer(this.pbrPrevModelBuffer, 0, this.prevModelMatrix);
+    }
+    prepare(_device) {
+        if (!this.mesh)
+            return;
+        if (!this.shaderModule) {
+            this.shaderModule = createValidatedShaderModule(this.device, {
+                code: this.mode === "gbuffer" ? GBUFFER_SHADER : SIMPLE_SHADER,
+                label: "OpaquePass.gbuffer",
+            });
+        }
+        if (this.mode === "gbuffer") {
+            this.cameraBuffer = createUniformBuffer(this.device, 256);
+            this._gbufferCamBuf = new Float32Array(CameraUniformsGbuffer.floatCount);
+            this._gbufferCamView = CameraUniformsGbuffer.view(this._gbufferCamBuf);
+        }
+        else {
+            this.cameraBuffer = createUniformBuffer(this.device, 128);
+            this._simpleCamBuf = new Float32Array(CameraUniformsSimple.floatCount);
+            this._simpleCamView = CameraUniformsSimple.view(this._simpleCamBuf);
+        }
+        if (this.mode === "gbuffer") {
+            this.pipeline = this.device.createRenderPipeline({
+                layout: "auto",
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: "vs_main",
+                    buffers: [{
+                            arrayStride: this.mesh.layout.stride,
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: "float32x3" },
+                                { shaderLocation: 1, offset: 12, format: "float32x3" },
+                                { shaderLocation: 2, offset: 24, format: "float32x2" },
+                                { shaderLocation: 3, offset: 32, format: "float32x4" },
+                            ],
+                        }],
+                },
+                fragment: {
+                    module: this.shaderModule,
+                    entryPoint: "fs_main",
+                    targets: [
+                        { format: "rgba8unorm" },
+                        { format: "rgba8unorm" },
+                        { format: "rgba8unorm" },
+                        { format: "rg16float" },
+                    ],
+                },
+                primitive: {
+                    topology: "triangle-list",
+                    cullMode: "back",
+                },
+                depthStencil: {
+                    format: "depth32float",
+                    depthWriteEnabled: true,
+                    depthCompare: "less",
+                },
+            });
+        }
+        else {
+            this.pipeline = this.device.createRenderPipeline({
+                layout: "auto",
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: "vs_main",
+                    buffers: [{
+                            arrayStride: this.mesh.layout.stride,
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: "float32x3" },
+                                { shaderLocation: 1, offset: 12, format: "float32x3" },
+                                { shaderLocation: 2, offset: 24, format: "float32x2" },
+                                { shaderLocation: 3, offset: 32, format: "float32x4" },
+                            ],
+                        }],
+                },
+                fragment: {
+                    module: this.shaderModule,
+                    entryPoint: "fs_main",
+                    targets: [{ format: this.surfaceFormat }],
+                },
+                primitive: {
+                    topology: "triangle-list",
+                    cullMode: "back",
+                },
+                depthStencil: {
+                    format: "depth32float",
+                    depthWriteEnabled: true,
+                    depthCompare: "less",
+                },
+            });
+        }
+        this.bindGroup = this.device.createBindGroup({
+            layout: this.pipeline.getBindGroupLayout(0),
+            entries: [{ binding: 0, resource: { buffer: this.cameraBuffer } }],
+        });
+    }
+    updateCamera(viewProj) {
+        if (!this.cameraBuffer)
+            return;
+        this.lastViewProj = viewProj;
+        if (this.mode === "gbuffer") {
+            const v = this._gbufferCamView;
+            v.set("viewProj", viewProj);
+            v.set("prevViewProj", this.prevViewProj);
+            v.set("modelMatrix", this.modelMatrix);
+            v.set("prevModelMatrix", this.prevModelMatrix);
+            this.device.queue.writeBuffer(this.cameraBuffer, 0, this._gbufferCamBuf);
+        }
+        else {
+            const v = this._simpleCamView;
+            v.set("viewProj", viewProj);
+            v.set("modelMatrix", this.modelMatrix);
+            this.device.queue.writeBuffer(this.cameraBuffer, 0, this._simpleCamBuf);
+        }
+    }
+    setup(builder) {
+        if (this.mode === "gbuffer") {
+            if (this.gbufferAlbedoHandle)
+                builder.colorAttachment({ handle: this.gbufferAlbedoHandle, loadOp: "clear", storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 0 } });
+            if (this.gbufferNormalHandle)
+                builder.colorAttachment({ handle: this.gbufferNormalHandle, loadOp: "clear", storeOp: "store", clearValue: { r: 0.5, g: 0.5, b: 0.5, a: 1 } });
+            if (this.gbufferMetallicEmissiveHandle)
+                builder.colorAttachment({ handle: this.gbufferMetallicEmissiveHandle, loadOp: "clear", storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 0 } });
+            if (this.gbufferVelocityHandle)
+                builder.colorAttachment({ handle: this.gbufferVelocityHandle, loadOp: "clear", storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 0 } });
+            if (this.gbufferDepthHandle)
+                builder.depthAttachment({ handle: this.gbufferDepthHandle, depthLoadOp: "load", depthStoreOp: "store", depthClearValue: 1.0 });
+        }
+        else {
+            if (this.surfaceHandle)
+                builder.colorAttachment({ handle: this.surfaceHandle, loadOp: "clear", storeOp: "store", clearValue: { r: 0.1, g: 0.1, b: 0.12, a: 1 } });
+            if (this.depthHandle)
+                builder.depthAttachment({ handle: this.depthHandle, depthLoadOp: "clear", depthStoreOp: "store", depthClearValue: 1.0 });
+        }
+    }
+    execute(ctx) {
+        if (!this.vertexBuffer || !this.indexBuffer || !this.mesh || !ctx.pass)
+            return;
+        this.setPrevViewProj(ctx.prevViewProj);
+        this.updateCamera(ctx.viewProj);
+        const tracked = ctx.pass;
+        if (this.graphMaterial && this.graphMaterial.inlineShaderSource) {
+            this.ensureGraphPipeline();
+            if (!this.graphPipeline || !this.graphBindGroup)
+                return;
+            this.updateGraphCamera(this.lastViewProj);
+            tracked.setPipeline(this.graphPipeline);
+            tracked.setBindGroup(0, this.graphBindGroup);
+            // Set extra bind groups (lights, IBL, etc.)
+            for (const [group, bg] of this.graphExtraBindGroups.entries()) {
+                tracked.setBindGroup(group, bg);
+            }
+            tracked.setVertexBuffer(0, this.vertexBuffer);
+            tracked.setIndexBuffer(this.indexBuffer, this.mesh.indices instanceof Uint16Array ? "uint16" : "uint32");
+            if (this.graphInstanceBuffer && this.graphInstanceCount > 0) {
+                tracked.drawIndexed(this.mesh.indexCount, this.graphInstanceCount);
+            }
+            else {
+                tracked.drawIndexed(this.mesh.indexCount);
+            }
+            return;
+        }
+        if (this.pbrMaterial && this.mode === "gbuffer") {
+            this.ensurePBRPipeline();
+            this.ensurePBRMaterialRegistered();
+            if (!this.pbrPipeline || !this.pbrCameraBindGroup)
+                return;
+            this.updatePBRCamera(this.lastViewProj);
+            tracked.setPipeline(this.pbrPipeline);
+            tracked.setBindGroup(0, this.pbrCameraBindGroup);
+            // Bindless material bind group (@group(3)) — set once per frame by the host.
+            if (this.bindlessBindGroup)
+                tracked.setBindGroup(3, this.bindlessBindGroup);
+            tracked.setVertexBuffer(0, this.vertexBuffer);
+            tracked.setIndexBuffer(this.indexBuffer, this.mesh.indices instanceof Uint16Array ? "uint16" : "uint32");
+            tracked.drawIndexed(this.mesh.indexCount);
+            return;
+        }
+        if (!this.pipeline || !this.bindGroup)
+            return;
+        tracked.setPipeline(this.pipeline);
+        tracked.setBindGroup(0, this.bindGroup);
+        tracked.setVertexBuffer(0, this.vertexBuffer);
+        tracked.setIndexBuffer(this.indexBuffer, this.mesh.indices instanceof Uint16Array ? "uint16" : "uint32");
+        tracked.drawIndexed(this.mesh.indexCount);
+    }
+    getBindGroupLayout() {
+        return this.pipeline?.getBindGroupLayout(0) ?? null;
+    }
+    ensureDepthTexture(width, height) {
+        if (this.depthTexture) {
+            if (this.depthTexture.width === width && this.depthTexture.height === height) {
+                return this.depthTexture;
+            }
+            // Defer destruction — the old depth texture may still be referenced by
+            // in-flight command buffers. It will be destroyed on the next endFrame().
+            this.deferredDepthTextures.push(this.depthTexture);
+        }
+        this.depthTexture = this.device.createTexture({
+            size: [width, height],
+            format: "depth32float",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        return this.depthTexture;
+    }
+    endFrame() {
+        this.deferredDepthTextures.forEach((t) => { t.destroy(); ; });
+        this.deferredDepthTextures = [];
+    }
+    getDepthTextureView() {
+        return this.depthTexture?.createView() ?? null;
+    }
+    getVertexBuffer() {
+        return this.vertexBuffer;
+    }
+    getIndexBuffer() {
+        return this.indexBuffer;
+    }
+    getIndexCount() {
+        return this.mesh?.indexCount ?? 0;
+    }
+    getIndexFormat() {
+        return this.mesh?.indices instanceof Uint16Array ? "uint16" : "uint32";
+    }
+    destroy() {
+        this.vertexBuffer?.destroy();
+        this.indexBuffer?.destroy();
+        this.depthTexture?.destroy();
+        this.deferredDepthTextures.forEach((t) => { t.destroy(); ; });
+        this.deferredDepthTextures = [];
+        this.cameraBuffer?.destroy();
+        this.pbrCameraBuffer?.destroy();
+        this.pbrModelBuffer?.destroy();
+        this.pbrPrevModelBuffer?.destroy();
+        this.pbrMaterialIndexBuffer?.destroy();
+        this.pipeline?.destroy();
+        this.pbrPipeline?.destroy();
+        this.shaderModule?.destroy();
+        this.pbrShaderModule?.destroy();
+        this.vertexBuffer = null;
+        this.indexBuffer = null;
+        this.depthTexture = null;
+        this.cameraBuffer = null;
+        this._gbufferCamView = null;
+        this._gbufferCamBuf = null;
+        this._simpleCamView = null;
+        this._simpleCamBuf = null;
+        this.pipeline = null;
+        this.pbrPipeline = null;
+        this.pbrShaderModule = null;
+        this.shaderModule = null;
+        this.pbrCameraBuffer = null;
+        this.pbrModelBuffer = null;
+        this.pbrPrevModelBuffer = null;
+        this.pbrMaterialIndexBuffer = null;
+        this._pbrCamView = null;
+        this._pbrCamBuf = null;
+        this.pbrMaterial = null;
+        this.pbrMaterialRegistered = false;
+        this.graphCameraBuffer?.destroy();
+        this.graphPipeline?.destroy();
+        this.graphShaderModule?.destroy();
+        this.graphCameraBuffer = null;
+        this.graphBindGroup = null;
+        this.graphMaterial = null;
+        this.graphProfile = null;
+        destroyMapValues(this.graphExtraBindGroups);
+        this.graphInstanceBuffer = null;
+        this.graphInstanceCount = 0;
+        this.graphUniformData = null;
+        destroyMapValues(this.graphVariantPipelines);
+        destroyMapValues(this.graphVariantShaderModules);
+    }
+}