@adobe/data-gpu 0.9.69

package/src/graphics/rendering/ibl-render/ibl-render-plugin.ts

@@ -0,0 +1,415 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Mat4x4, Vec3 } from "@adobe/data/math";
+import { pbrCore } from "../pbr-core-plugin.js";
+import { modelLoader } from "../../scene/model/model-loader-plugin.js";
+import { transform } from "../../scene/node/transform-plugin.js";
+import { buildIblResources } from "./ibl/build-ibl-resources.js";
+import { parseHdr } from "./ibl/parse-hdr.js";
+import { VisibleMaterial } from "../visible-material/visible-material.js";
+import { SceneUniforms } from "../../scene/scene-uniforms/scene-uniforms.js";
+import { StandardVertex } from "../standard-vertex/standard-vertex.js";
+import { SkinningAttributes } from "../skinning/skinning-attributes/skinning-attributes.js";
+import { buildIblShader } from "./ibl-shader.wgsl.js";
+import skyboxShader from "./skybox-shader.wgsl.js";
+
+const PREFILTERED_MIP_COUNT = 7;
+
+function createIblBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+    return device.createBindGroupLayout({
+        entries: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+            { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
+            { binding: 3, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        ],
+    });
+}
+
+function createSkyboxBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+    return device.createBindGroupLayout({
+        entries: [
+            { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+            { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+            { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        ],
+    });
+}
+
+/**
+ * pbrIblRender — IBL PBR rendering aggregator. Combines the implementation
+ * plugins needed to draw `Model` entities with image-based lighting:
+ *
+ *   - pbrCore         (ephemeral primitive/material shape declarations)
+ *   - modelLoader     (glTF → primitives)
+ *   - SceneUniforms.plugin (camera + light packed into a GPU buffer)
+ *   - transform       (Node TRS → _worldMatrix)
+ *
+ * The render system is skin-aware — if a primitive has a `_skinVertexBuffer`,
+ * it uses the skinned pipeline and looks up the matching joint bind group.
+ * Add `pbrSkinning` separately to populate those joint matrices for skinned
+ * meshes.
+ *
+ * Adds its own systems:
+ *   - iblInitSystem    : light.environmentUrl → IBL cube/2D textures
+ *   - pbrIblRenderSystem: visible Models → drawIndexed calls
+ *
+ * `_PbrPrimitive` archetype.
+ */
+export const pbrIblRender = Database.Plugin.create({
+    extends: Database.Plugin.combine(pbrCore, modelLoader, SceneUniforms.plugin, transform),
+    resources: {
+        _iblEnvironment:  { default: null as GPUTexture | null, transient: true },
+        _iblIrradiance:   { default: null as GPUTexture | null, transient: true },
+        _iblPrefiltered:  { default: null as GPUTexture | null, transient: true },
+        _iblBrdfLut:      { default: null as GPUTexture | null, transient: true },
+    },
+    systems: {
+        iblInitSystem: {
+            create: db => {
+                let started = false;
+                return () => {
+                    if (started) return;
+                    const { device, light } = db.store.resources;
+                    if (!device) return;
+                    const environmentUrl = light.environmentUrl;
+                    started = true;
+
+                    const buildAndAssign = (hdr?: Awaited<ReturnType<typeof parseHdr>>) => {
+                        const r = buildIblResources(device, {
+                            prefilteredMipCount: PREFILTERED_MIP_COUNT,
+                            hdrSource: hdr,
+                        });
+                        db.store.resources._iblEnvironment = r.environment;
+                        db.store.resources._iblIrradiance = r.irradiance;
+                        db.store.resources._iblPrefiltered = r.prefiltered;
+                        db.store.resources._iblBrdfLut = r.brdfLut;
+                    };
+
+                    if (environmentUrl) {
+                        fetch(environmentUrl)
+                            .then(r => {
+                                if (!r.ok) throw new Error(`HDR fetch failed: ${r.status}`);
+                                return r.arrayBuffer();
+                            })
+                            .then(buf => buildAndAssign(parseHdr(buf)))
+                            .catch(err => {
+                                console.warn("[_pbrIblRender] HDR load failed; using procedural fallback", err);
+                                buildAndAssign();
+                            });
+                    } else {
+                        buildAndAssign();
+                    }
+                };
+            },
+            schedule: { during: ["preRender"] },
+        },
+        pbrIblRenderSystem: {
+            create: db => {
+                let pipeline: GPURenderPipeline | null = null;
+                let skinnedPipeline: GPURenderPipeline | null = null;
+                let skyboxPipeline: GPURenderPipeline | null = null;
+                let sceneLayout: GPUBindGroupLayout | null = null;
+                let materialLayout: GPUBindGroupLayout | null = null;
+                let iblLayout: GPUBindGroupLayout | null = null;
+                let instanceLayout: GPUBindGroupLayout | null = null;
+                let skinnedInstanceLayout: GPUBindGroupLayout | null = null;
+                let skyboxLayout: GPUBindGroupLayout | null = null;
+                let iblSampler: GPUSampler | null = null;
+                let skyboxUniformBuffer: GPUBuffer | null = null;
+                let sceneBindGroup: GPUBindGroup | null = null;
+                let iblBindGroup: GPUBindGroup | null = null;
+                let skyboxBindGroup: GPUBindGroup | null = null;
+                let cachedSceneBuffer: GPUBuffer | null = null;
+                let cachedIblIrradiance: GPUTexture | null = null;
+                let cachedSkyEnvironment: GPUTexture | null = null;
+                const skyboxScratch = new Float32Array(12);
+                type InstanceEntry = { buffer: GPUBuffer; bindGroup: GPUBindGroup; capacity: number };
+                const instanceCache = new Map<number, InstanceEntry>();
+                let instanceScratch = new Float32Array(16);
+
+                return () => {
+                    const {
+                        device, renderPassEncoder, canvasFormat, depthFormat, _sceneUniformsBuffer,
+                        _iblEnvironment, _iblIrradiance, _iblPrefiltered, _iblBrdfLut, camera,
+                    } = db.store.resources;
+                    if (!device || !renderPassEncoder || !_sceneUniformsBuffer || !camera) return;
+                    if (!_iblEnvironment || !_iblIrradiance || !_iblPrefiltered || !_iblBrdfLut) return;
+
+                    if (!sceneLayout) sceneLayout = SceneUniforms.createBindGroupLayout(device);
+                    if (!materialLayout) materialLayout = VisibleMaterial.createBindGroupLayout(device);
+                    if (!iblLayout) iblLayout = createIblBindGroupLayout(device);
+                    if (!instanceLayout) instanceLayout = device.createBindGroupLayout({
+                        entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } }],
+                    });
+                    if (!skinnedInstanceLayout) skinnedInstanceLayout = device.createBindGroupLayout({
+                        entries: [
+                            { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                            { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                        ],
+                    });
+                    if (!skyboxLayout) skyboxLayout = createSkyboxBindGroupLayout(device);
+                    if (!iblSampler) {
+                        iblSampler = device.createSampler({
+                            magFilter: "linear",
+                            minFilter: "linear",
+                            mipmapFilter: "linear",
+                            addressModeU: "clamp-to-edge",
+                            addressModeV: "clamp-to-edge",
+                            addressModeW: "clamp-to-edge",
+                        });
+                    }
+                    if (!skyboxUniformBuffer) {
+                        skyboxUniformBuffer = device.createBuffer({
+                            size: 48,
+                            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                        });
+                    }
+
+                    if (!pipeline) {
+                        const module = device.createShaderModule({
+                            code: buildIblShader({ prefilteredMipCount: PREFILTERED_MIP_COUNT, skinned: false }),
+                        });
+                        pipeline = device.createRenderPipeline({
+                            layout: device.createPipelineLayout({
+                                bindGroupLayouts: [sceneLayout, materialLayout, iblLayout, instanceLayout],
+                            }),
+                            vertex: { module, entryPoint: "vs_main", buffers: [StandardVertex.layout] },
+                            fragment: { module, entryPoint: "fs_main", targets: [{ format: canvasFormat }] },
+                            primitive: { topology: "triangle-list", cullMode: "back" },
+                            depthStencil: { format: depthFormat, depthWriteEnabled: true, depthCompare: "less" },
+                        });
+                    }
+                    if (!skinnedPipeline) {
+                        const module = device.createShaderModule({
+                            code: buildIblShader({ prefilteredMipCount: PREFILTERED_MIP_COUNT, skinned: true }),
+                        });
+                        skinnedPipeline = device.createRenderPipeline({
+                            layout: device.createPipelineLayout({
+                                bindGroupLayouts: [sceneLayout, materialLayout, iblLayout, skinnedInstanceLayout],
+                            }),
+                            vertex: { module, entryPoint: "vs_main", buffers: [StandardVertex.layout, SkinningAttributes.layout] },
+                            fragment: { module, entryPoint: "fs_main", targets: [{ format: canvasFormat }] },
+                            primitive: { topology: "triangle-list", cullMode: "back" },
+                            depthStencil: { format: depthFormat, depthWriteEnabled: true, depthCompare: "less" },
+                        });
+                    }
+                    if (!skyboxPipeline) {
+                        const sm = device.createShaderModule({ code: skyboxShader });
+                        skyboxPipeline = device.createRenderPipeline({
+                            layout: device.createPipelineLayout({ bindGroupLayouts: [skyboxLayout] }),
+                            vertex: { module: sm, entryPoint: "vs_skybox" },
+                            fragment: { module: sm, entryPoint: "fs_skybox", targets: [{ format: canvasFormat }] },
+                            primitive: { topology: "triangle-list" },
+                            depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: "always" },
+                        });
+                    }
+
+                    if (_sceneUniformsBuffer !== cachedSceneBuffer || !sceneBindGroup) {
+                        sceneBindGroup = device.createBindGroup({
+                            layout: sceneLayout,
+                            entries: [{ binding: 0, resource: { buffer: _sceneUniformsBuffer } }],
+                        });
+                        cachedSceneBuffer = _sceneUniformsBuffer;
+                    }
+                    if (_iblIrradiance !== cachedIblIrradiance || !iblBindGroup) {
+                        iblBindGroup = device.createBindGroup({
+                            layout: iblLayout,
+                            entries: [
+                                { binding: 0, resource: _iblIrradiance.createView({ dimension: "cube" }) },
+                                { binding: 1, resource: _iblPrefiltered.createView({ dimension: "cube" }) },
+                                { binding: 2, resource: _iblBrdfLut.createView() },
+                                { binding: 3, resource: iblSampler },
+                            ],
+                        });
+                        cachedIblIrradiance = _iblIrradiance;
+                    }
+                    if (_iblEnvironment !== cachedSkyEnvironment || !skyboxBindGroup) {
+                        skyboxBindGroup = device.createBindGroup({
+                            layout: skyboxLayout,
+                            entries: [
+                                { binding: 0, resource: { buffer: skyboxUniformBuffer } },
+                                { binding: 1, resource: _iblEnvironment.createView({ dimension: "cube" }) },
+                                { binding: 2, resource: iblSampler },
+                            ],
+                        });
+                        cachedSkyEnvironment = _iblEnvironment;
+                    }
+
+                    // Camera basis for the skybox view rays.
+                    const forward = Vec3.normalize(Vec3.subtract(camera.target, camera.position));
+                    const right = Vec3.normalize(Vec3.cross(forward, camera.up));
+                    const upOrtho = Vec3.cross(right, forward);
+                    const tanHalfFov = Math.tan(camera.fieldOfView / 2);
+                    skyboxScratch[0] = right[0];
+                    skyboxScratch[1] = right[1];
+                    skyboxScratch[2] = right[2];
+                    skyboxScratch[3] = camera.aspect;
+                    skyboxScratch[4] = upOrtho[0];
+                    skyboxScratch[5] = upOrtho[1];
+                    skyboxScratch[6] = upOrtho[2];
+                    skyboxScratch[7] = tanHalfFov;
+                    skyboxScratch[8] = forward[0];
+                    skyboxScratch[9] = forward[1];
+                    skyboxScratch[10] = forward[2];
+                    skyboxScratch[11] = 0;
+                    device.queue.writeBuffer(skyboxUniformBuffer, 0, skyboxScratch);
+
+                    renderPassEncoder.setPipeline(skyboxPipeline);
+                    renderPassEncoder.setBindGroup(0, skyboxBindGroup);
+                    renderPassEncoder.draw(3);
+
+                    // Collect visible Models grouped by geometry. World matrix comes
+                    // from each Model's `_worldMatrix` component (written by _transform).
+                    interface ModelEntry { id: number; matrix: Mat4x4 }
+                    const modelsByGeo = new Map<number, ModelEntry[]>();
+                    for (const arch of db.store.queryArchetypes(["geometry", "visible", "_worldMatrix"])) {
+                        const ids = arch.columns.id;
+                        const geoRefs = arch.columns.geometry;
+                        const vis = arch.columns.visible;
+                        const worldMats = arch.columns._worldMatrix;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            if (!vis.get(i)) continue;
+                            const id = ids.get(i);
+                            const m = worldMats.get(i);
+                            const geoId = geoRefs.get(i);
+                            let arr = modelsByGeo.get(geoId);
+                            if (!arr) { arr = []; modelsByGeo.set(geoId, arr); }
+                            arr.push({ id, matrix: m });
+                        }
+                    }
+
+                    const materialMap = new Map<number, GPUBindGroup>();
+                    for (const arch of db.store.queryArchetypes(["_materialBindGroup"])) {
+                        const ids = arch.columns.id;
+                        const bgs = arch.columns._materialBindGroup;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const bg = bgs.get(i); if (bg) materialMap.set(ids.get(i), bg);
+                        }
+                    }
+
+                    const jointBindGroupByModel = new Map<number, GPUBindGroup>();
+                    for (const arch of db.store.queryArchetypes([
+                        "_skeletonModelRef",
+                        "_skeletonJointMatrixBindGroup",
+                    ])) {
+                        const modelRefs = arch.columns._skeletonModelRef;
+                        const bgs = arch.columns._skeletonJointMatrixBindGroup;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const bg = bgs.get(i);
+                            if (bg) jointBindGroupByModel.set(modelRefs.get(i), bg);
+                        }
+                    }
+
+                    renderPassEncoder.setBindGroup(0, sceneBindGroup);
+                    renderPassEncoder.setBindGroup(2, iblBindGroup);
+
+                    let lastPipeline: GPURenderPipeline | null = null;
+                    let lastMat: GPUBindGroup | null = null;
+                    let lastInstBG: GPUBindGroup | null = null;
+                    for (const archetype of db.store.queryArchetypes([
+                        "_vertexBuffer",
+                        "_skinVertexBuffer",
+                        "_indexBuffer",
+                        "_indexCount",
+                        "_indexFormat",
+                        "_material",
+                        "_geometry",
+                        "_nodeLocalMatrix",
+                    ])) {
+                        const vbs = archetype.columns._vertexBuffer;
+                        const skinVbs = archetype.columns._skinVertexBuffer;
+                        const ibs = archetype.columns._indexBuffer;
+                        const counts = archetype.columns._indexCount;
+                        const formats = archetype.columns._indexFormat;
+                        const matRefs = archetype.columns._material;
+                        const geoRefs = archetype.columns._geometry;
+                        const nodeMats = archetype.columns._nodeLocalMatrix;
+                        const primIds = archetype.columns.id;
+                        for (let i = 0; i < archetype.rowCount; i++) {
+                            const geoId = geoRefs.get(i);
+                            const models = modelsByGeo.get(geoId);
+                            if (!models) continue;
+
+                            const skinBuf = skinVbs.get(i);
+                            const nodeMatrix = nodeMats.get(i);
+                            const primId = primIds.get(i);
+                            const mat = materialMap.get(matRefs.get(i));
+                            if (!mat) continue;
+
+                            if (skinBuf) {
+                                // Skinned: one draw per Model; the skeleton owns the
+                                // 2-binding bind group with instance + joint matrices.
+                                if (lastPipeline !== skinnedPipeline) {
+                                    renderPassEncoder.setPipeline(skinnedPipeline);
+                                    lastPipeline = skinnedPipeline;
+                                    lastInstBG = null;
+                                }
+                                if (mat !== lastMat) {
+                                    renderPassEncoder.setBindGroup(1, mat);
+                                    lastMat = mat;
+                                }
+                                renderPassEncoder.setVertexBuffer(0, vbs.get(i)!); // _PbrPrimitive archetype guarantees non-null
+                                renderPassEncoder.setVertexBuffer(1, skinBuf);
+                                renderPassEncoder.setIndexBuffer(ibs.get(i)!, formats.get(i)); // _PbrPrimitive archetype guarantees non-null
+                                for (const model of models) {
+                                    const skeletonBG = jointBindGroupByModel.get(model.id);
+                                    if (!skeletonBG) continue;
+                                    if (skeletonBG !== lastInstBG) {
+                                        renderPassEncoder.setBindGroup(3, skeletonBG);
+                                        lastInstBG = skeletonBG;
+                                    }
+                                    renderPassEncoder.drawIndexed(counts.get(i), 1);
+                                }
+                                continue;
+                            }
+
+                            // Static: instanced draw.
+                            if (lastPipeline !== pipeline) {
+                                renderPassEncoder.setPipeline(pipeline);
+                                lastPipeline = pipeline;
+                                lastInstBG = null;
+                            }
+                            const instCount = models.length;
+                            let entry = instanceCache.get(primId);
+                            if (!entry || entry.capacity < instCount) {
+                                entry?.buffer.destroy();
+                                const buffer = device.createBuffer({
+                                    size: Math.max(instCount * 64, 64),
+                                    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+                                });
+                                const bindGroup = device.createBindGroup({
+                                    layout: instanceLayout,
+                                    entries: [{ binding: 0, resource: { buffer } }],
+                                });
+                                entry = { buffer, bindGroup, capacity: instCount };
+                                instanceCache.set(primId, entry);
+                            }
+                            if (instanceScratch.length < instCount * 16) {
+                                instanceScratch = new Float32Array(instCount * 16);
+                            }
+                            for (let j = 0; j < instCount; j++) {
+                                instanceScratch.set(Mat4x4.multiply(models[j].matrix, nodeMatrix), j * 16);
+                            }
+                            device.queue.writeBuffer(entry.buffer, 0, instanceScratch, 0, instCount * 16);
+
+                            if (mat !== lastMat) {
+                                renderPassEncoder.setBindGroup(1, mat);
+                                lastMat = mat;
+                            }
+                            if (entry.bindGroup !== lastInstBG) {
+                                renderPassEncoder.setBindGroup(3, entry.bindGroup);
+                                lastInstBG = entry.bindGroup;
+                            }
+                            renderPassEncoder.setVertexBuffer(0, vbs.get(i)!); // _PbrPrimitive archetype guarantees non-null
+                            renderPassEncoder.setIndexBuffer(ibs.get(i)!, formats.get(i)); // _PbrPrimitive archetype guarantees non-null
+                            renderPassEncoder.drawIndexed(counts.get(i), instCount);
+                        }
+                    }
+                };
+            },
+            schedule: { during: ["render"], after: ["beginRenderPass", "iblInitSystem", "transformSystem"], before: ["endRenderPass"] },
+        },
+    },
+});

package/src/graphics/rendering/ibl-render/ibl-shader.wgsl.ts

@@ -0,0 +1,185 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { wgslStructFields } from "@adobe/data/typed-buffer";
+import { schema as sceneUniformsSchema } from "../../scene/scene-uniforms/schema.js";
+import { schema as visibleMaterialSchema } from "../visible-material/schema.js";
+import brdf from "./brdf.wgsl.js";
+
+export interface IblShaderOptions {
+    prefilteredMipCount: number;
+    /** When true, the vertex shader accepts JOINTS_0 / WEIGHTS_0 attributes and
+     *  a joint-matrix storage buffer in bind group 4, and blends each vertex by
+     *  the four weighted joint matrices before applying the instance transform. */
+    skinned: boolean;
+}
+
+export function buildIblShader(options: IblShaderOptions): string {
+    // Skinned variant adds jointMatrices as binding 1 of group 3 (sharing the
+    // slot with instance matrices) so we stay within WebGPU's default
+    // maxBindGroups = 4 limit.
+    const skinningBindings = options.skinned ? /* wgsl */ `
+@group(3) @binding(1) var<storage, read> jointMatrices: array<mat4x4<f32>>;
+` : "";
+
+    const vertexInputs = options.skinned ? /* wgsl */ `
+struct VertexInput {
+    @location(0) position: vec3f,
+    @location(1) normal: vec3f,
+    @location(2) tangent: vec4f,
+    @location(3) uv: vec2f,
+    @location(4) joints: vec4u,
+    @location(5) weights: vec4f,
+}` : /* wgsl */ `
+struct VertexInput {
+    @location(0) position: vec3f,
+    @location(1) normal: vec3f,
+    @location(2) tangent: vec4f,
+    @location(3) uv: vec2f,
+}`;
+
+    const vertexMain = options.skinned ? /* wgsl */ `
+@vertex
+fn vs_main(@builtin(instance_index) instanceIndex: u32, in: VertexInput) -> VertexOutput {
+    let skinMat =
+        jointMatrices[in.joints.x] * in.weights.x +
+        jointMatrices[in.joints.y] * in.weights.y +
+        jointMatrices[in.joints.z] * in.weights.z +
+        jointMatrices[in.joints.w] * in.weights.w;
+    let m = instances[instanceIndex] * skinMat;
+    let m3 = mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz);
+    let normalMat = mat3x3<f32>(
+        cross(m3[1], m3[2]),
+        cross(m3[2], m3[0]),
+        cross(m3[0], m3[1]),
+    );
+    let worldPos = m * vec4f(in.position, 1.0);
+    var out: VertexOutput;
+    out.clipPosition = scene.viewProjectionMatrix * worldPos;
+    out.worldPosition = worldPos.xyz;
+    out.normal = normalize(normalMat * in.normal);
+    out.tangent = normalize(m3 * in.tangent.xyz);
+    out.bitangent = normalize(cross(out.normal, out.tangent) * in.tangent.w);
+    out.uv = in.uv;
+    return out;
+}` : /* wgsl */ `
+@vertex
+fn vs_main(@builtin(instance_index) instanceIndex: u32, in: VertexInput) -> VertexOutput {
+    let m = instances[instanceIndex];
+    let m3 = mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz);
+    let normalMat = mat3x3<f32>(
+        cross(m3[1], m3[2]),
+        cross(m3[2], m3[0]),
+        cross(m3[0], m3[1]),
+    );
+    let worldPos = m * vec4f(in.position, 1.0);
+    var out: VertexOutput;
+    out.clipPosition = scene.viewProjectionMatrix * worldPos;
+    out.worldPosition = worldPos.xyz;
+    out.normal = normalize(normalMat * in.normal);
+    out.tangent = normalize(m3 * in.tangent.xyz);
+    out.bitangent = normalize(cross(out.normal, out.tangent) * in.tangent.w);
+    out.uv = in.uv;
+    return out;
+}`;
+
+    return /* wgsl */ `
+struct SceneUniforms {
+${wgslStructFields(sceneUniformsSchema)}
+}
+
+struct VisibleMaterial {
+${wgslStructFields(visibleMaterialSchema)}
+}
+
+@group(0) @binding(0) var<uniform> scene: SceneUniforms;
+
+@group(1) @binding(0) var<uniform> material: VisibleMaterial;
+@group(1) @binding(1) var baseColorTexture: texture_2d<f32>;
+@group(1) @binding(2) var metallicRoughnessTexture: texture_2d<f32>;
+@group(1) @binding(3) var normalTexture: texture_2d<f32>;
+@group(1) @binding(4) var occlusionTexture: texture_2d<f32>;
+@group(1) @binding(5) var emissiveTexture: texture_2d<f32>;
+@group(1) @binding(6) var pbrSampler: sampler;
+
+@group(2) @binding(0) var iblIrradiance: texture_cube<f32>;
+@group(2) @binding(1) var iblPrefiltered: texture_cube<f32>;
+@group(2) @binding(2) var iblBrdfLut: texture_2d<f32>;
+@group(2) @binding(3) var iblSampler: sampler;
+
+@group(3) @binding(0) var<storage, read> instances: array<mat4x4<f32>>;
+${skinningBindings}
+const PREFILTERED_MIP_COUNT: f32 = ${options.prefilteredMipCount.toFixed(1)};
+
+${vertexInputs}
+
+struct VertexOutput {
+    @builtin(position) clipPosition: vec4f,
+    @location(0) worldPosition: vec3f,
+    @location(1) normal: vec3f,
+    @location(2) tangent: vec3f,
+    @location(3) bitangent: vec3f,
+    @location(4) uv: vec2f,
+}
+
+${vertexMain}
+
+${brdf}
+
+@fragment
+fn fs_main(in: VertexOutput) -> @location(0) vec4f {
+    let baseColor = textureSample(baseColorTexture, pbrSampler, in.uv) * material.baseColorFactor;
+
+    let mr = textureSample(metallicRoughnessTexture, pbrSampler, in.uv);
+    let metallic = mr.b * material.metallicFactor;
+    var roughness = mr.g * material.roughnessFactor;
+    roughness = max(roughness, MIN_ROUGHNESS);
+    let alpha = roughness * roughness;
+
+    let occlusion = textureSample(occlusionTexture, pbrSampler, in.uv).r;
+    let emissive = textureSample(emissiveTexture, pbrSampler, in.uv).rgb * material.emissiveFactor;
+
+    let nSampled = textureSample(normalTexture, pbrSampler, in.uv).rgb * 2.0 - vec3f(1.0);
+    let nScaled = vec3f(nSampled.xy * material.normalScale, nSampled.z);
+    let tbn = mat3x3<f32>(in.tangent, in.bitangent, in.normal);
+    let N = normalize(tbn * nScaled);
+
+    let V = normalize(scene.cameraPosition - in.worldPosition);
+    let nDotV = max(dot(N, V), 0.001);
+    let R = reflect(-V, N);
+
+    let f0 = mix(vec3f(0.04), baseColor.rgb, metallic);
+
+    // --- IBL contribution (split-sum) ---
+    let F_ibl = f_schlick_roughness(nDotV, f0, roughness);
+    let kD_ibl = (vec3f(1.0) - F_ibl) * (1.0 - metallic);
+
+    let irradiance = textureSampleLevel(iblIrradiance, iblSampler, N, 0.0).rgb;
+    let diffuseIbl = kD_ibl * irradiance * baseColor.rgb;
+
+    let mipLevel = roughness * (PREFILTERED_MIP_COUNT - 1.0);
+    let prefiltered = textureSampleLevel(iblPrefiltered, iblSampler, R, mipLevel).rgb;
+    let envBrdf = textureSampleLevel(iblBrdfLut, iblSampler, vec2f(nDotV, roughness), 0.0).rg;
+    let specularIbl = prefiltered * (F_ibl * envBrdf.x + envBrdf.y);
+
+    let ambient = (diffuseIbl + specularIbl) * mix(1.0, occlusion, material.occlusionStrength);
+
+    // --- Direct light (keeps parity with the direct renderer's single light) ---
+    let L = normalize(-scene.lightDirection);
+    let H = normalize(V + L);
+    let nDotL = max(dot(N, L), 0.0);
+    let nDotH = max(dot(N, H), 0.0);
+    let vDotH = max(dot(V, H), 0.0);
+    let D_d = d_ggx(nDotH, alpha);
+    let G_d = g_smith(nDotV, nDotL, alpha);
+    let F_d = f_schlick(vDotH, f0);
+    let spec_d = (D_d * G_d * F_d) / (4.0 * nDotV * nDotL + 0.0001);
+    let kD_d = (vec3f(1.0) - F_d) * (1.0 - metallic);
+    let direct = (kD_d * baseColor.rgb / PI + spec_d) * scene.lightColor * nDotL;
+
+    let color = direct + ambient + emissive;
+    let mapped = tone_map_aces(color);
+    let gamma = pow(mapped, vec3f(1.0 / 2.2));
+    return vec4f(gamma, baseColor.a);
+}
+`;
+}

package/src/graphics/rendering/ibl-render/skybox-shader.wgsl.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import brdf from "./brdf.wgsl.js";
+
+// Skybox shader. Computes the view-ray direction in the vertex shader from the
+// camera's orthonormal basis + half-FOV — bypasses the perspective matrix
+// inverse, which would otherwise depend on the project's specific
+// clip-space convention. Depth state is "always" with no write so primitives
+// drawn afterward in the same render pass overlap correctly.
+export default /* wgsl */ `
+struct SkyboxUniforms {
+    right: vec3f,
+    aspect: f32,
+    up: vec3f,
+    tanHalfFov: f32,
+    forward: vec3f,
+    _pad: f32,
+}
+@group(0) @binding(0) var<uniform> sky: SkyboxUniforms;
+@group(0) @binding(1) var skyCubemap: texture_cube<f32>;
+@group(0) @binding(2) var skySampler: sampler;
+
+struct SkyboxOutput {
+    @builtin(position) clip: vec4f,
+    @location(0) dir: vec3f,
+}
+
+@vertex
+fn vs_skybox(@builtin(vertex_index) i: u32) -> SkyboxOutput {
+    let xs = array<f32, 3>(-1.0, 3.0, -1.0);
+    let ys = array<f32, 3>(-1.0, -1.0, 3.0);
+    let xn = xs[i];
+    let yn = ys[i];
+    var out: SkyboxOutput;
+    out.clip = vec4f(xn, yn, 0.0, 1.0);
+    out.dir = sky.forward
+        + sky.right * (xn * sky.aspect * sky.tanHalfFov)
+        + sky.up * (yn * sky.tanHalfFov);
+    return out;
+}
+
+${brdf}
+
+@fragment
+fn fs_skybox(in: SkyboxOutput) -> @location(0) vec4f {
+    let dir = normalize(in.dir);
+    let raw = textureSampleLevel(skyCubemap, skySampler, dir, 0.0).rgb;
+    let mapped = tone_map_aces(raw);
+    return vec4f(pow(mapped, vec3f(1.0 / 2.2)), 1.0);
+}
+`;