@aura3d/engine 3.0.0 → 3.0.1

package/dist/rendering/WebGPUDevice.js

@@ -1,5 +1,7 @@
+import { WEBGPU_EXTENSION_ATLAS_WGSL, webgpuExtensionAtlasUniforms } from "./WebGPUExtensionAtlas.js";
 import { RenderDeviceError, viewBytes, resolveGpuTargetOwner, spreadGpuTargetInventory } from "./RenderDevice.js";
 import { MAX_WEBGPU_SKINNING_JOINTS } from "./WebGPUSkinningLimits.js";
+import { normalizeWebGPUTemporalOptions, WEBGPU_TAA_FRAGMENT, WEBGPU_TAA_OUTPUT_FRAGMENT } from "./webgpu/WebGPUTemporal.js";
 import { defaultWebGPUBloomWeights, normalizeWebGPUColorGradeOptions, normalizeWebGPUBloomOptions, webgpuBlurFragment, webgpuBloomCompositeFragment, webgpuBrightExtractFragment, webgpuColorGradeFragment, webgpuFxaaFragment, WEBGPU_POST_VERTEX_WGSL } from "./webgpu/WebGPUPostShaders.js";
 import { DEFAULT_DEPTH_SHADER_MARKER } from "./ShaderLibraryCore.js";
 import { reflectShaderSources } from "./ShaderReflection.js";
@@ -24,6 +26,26 @@ const TEXTURE_USAGE = {
     TEXTURE_BINDING: 0x0004
 };
 const DEPTH_TEXTURE_FORMAT = "depth24plus";
+const WEBGPU_NATIVE_COPY_FRAGMENT = `
+@group(0) @binding(0) var<uniform> params: vec4<f32>;
+@group(0) @binding(1) var linearSampler: sampler;
+@group(0) @binding(2) var source: texture_2d<f32>;
+@fragment fn fs_copy(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+ return textureSample(source, linearSampler, clamp(uv, params.xy * 0.5, vec2<f32>(1.0) - params.xy * 0.5));
+}`;
+const WEBGPU_NATIVE_TONE_FRAGMENT = `
+@group(0) @binding(0) var<uniform> params: vec4<f32>;
+@group(0) @binding(1) var linearSampler: sampler;
+@group(0) @binding(2) var source: texture_2d<f32>;
+@fragment fn fs_tone(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+ let sample = textureSample(source, linearSampler, uv);
+ var c = max(sample.rgb * params.x / params.w, vec3<f32>(0.0));
+ if (params.y > 2.5) { let toe=max(c-vec3<f32>(0.004),vec3<f32>(0.0)); c=min((toe*(6.2*toe+vec3<f32>(0.5)))/(toe*(6.2*toe+vec3<f32>(1.7))+vec3<f32>(0.06)),c*1.08); }
+ else if (params.y > 1.5) { c = clamp((c * (2.51 * c + vec3<f32>(0.03))) / (c * (2.43 * c + vec3<f32>(0.59)) + vec3<f32>(0.14)), vec3<f32>(0.0), vec3<f32>(1.0)); }
+ else if (params.y > 0.5) { c = c / (vec3<f32>(1.0) + c); }
+ if (params.z > 0.5) { c = select(1.055 * pow(c, vec3<f32>(1.0 / 2.4)) - vec3<f32>(0.055), c * 12.92, c <= vec3<f32>(0.0031308)); }
+ return vec4<f32>(c, sample.a);
+}`;
 class WebGPURenderBuffer {
     id;
     usage;
@@ -58,9 +80,13 @@ class WebGPUShaderProgram {
     entryPoints;
     nativeUniformLayout;
     portableBindings;
+    nativeColorDefaultVertex;
+    nativeAtlasVertex;
     disposed = false;
     renderPipelines = new Map();
-    constructor(id, label, marker, reflection, modules, entryPoints, nativeUniformLayout, portableBindings) {
+    nativeColorDefaultModule;
+    atlasVertexModules = new Map();
+    constructor(id, label, marker, reflection, modules, entryPoints, nativeUniformLayout, portableBindings, nativeColorDefaultVertex, nativeAtlasVertex) {
         this.id = id;
         this.label = label;
         this.marker = marker;
@@ -69,6 +95,8 @@ class WebGPUShaderProgram {
         this.entryPoints = entryPoints;
         this.nativeUniformLayout = nativeUniformLayout;
         this.portableBindings = portableBindings;
+        this.nativeColorDefaultVertex = nativeColorDefaultVertex;
+        this.nativeAtlasVertex = nativeAtlasVertex;
     }
     dispose() {
         this.disposed = true;
@@ -162,6 +190,8 @@ export class WebGPUDevice {
     nativeBloomPasses = 0;
     nativeColorGradePasses = 0;
     nativeFxaaPasses = 0;
+    nativeTaaPasses = 0;
+    nativeTemporalBindings = 0;
     webgpuPostPipelines = new Map();
     webgpuPostLinearSampler = null;
     lastWebGPUBloom = null;
@@ -312,7 +342,7 @@ export class WebGPUDevice {
                 this.device.createShaderModule({ label: `${sources.label}-fragment`, code: nativeSources.fragment })
             ]
             : [];
-        const shader = new WebGPUShaderProgram(this.nextId++, sources.label, sources.marker, reflectShaderSources(sources), modules, nativeSources.entryPoints, nativeSources.uniformLayout, nativeSources.portableBindings ?? []);
+        const shader = new WebGPUShaderProgram(this.nextId++, sources.label, sources.marker, reflectShaderSources(sources), modules, nativeSources.entryPoints, nativeSources.uniformLayout, nativeSources.portableBindings ?? [], nativeSources.colorDefaultVertex, nativeSources.atlasVertex);
         this.shaders.add(shader);
         return shader;
     }
@@ -787,6 +817,13 @@ export class WebGPUDevice {
         this.rasterizeDraw(command, vertexBuffer);
         this.drawCalls += 1;
     }
+    async waitForSubmittedWork() {
+        this.assertAlive();
+        if (!this.device.queue.onSubmittedWorkDone) {
+            throw new RenderDeviceError("Native GPU queue completion is unavailable", "GPU_COMPLETION_UNAVAILABLE");
+        }
+        await this.device.queue.onSubmittedWorkDone();
+    }
     endFrame() {
         this.assertFrame();
         this.frameActive = false;
@@ -821,6 +858,8 @@ export class WebGPUDevice {
             ["nativeBloomPasses", this.nativeBloomPasses],
             ["nativeColorGradePasses", this.nativeColorGradePasses],
             ["nativeFxaaPasses", this.nativeFxaaPasses],
+            ["nativeTaaPasses", this.nativeTaaPasses],
+            ["nativeTemporalBindings", this.nativeTemporalBindings],
             ["canvasSubmissions", this.canvasSubmissions]
         ]);
     }
@@ -879,7 +918,7 @@ export class WebGPUDevice {
      *
      * Renders bright-extract -> separable-blur mip pyramid -> composite over
      * the source, all as real WGSL fullscreen passes on this device. Returns a
-     * fresh rgba8 target owned by the caller (dispose it); every intermediate
+     * fresh rgba16f target owned by the caller (dispose it); every intermediate
      * is disposed before return. Throws fail-closed when the native device
      * cannot run fullscreen passes.
      */
@@ -893,7 +932,10 @@ export class WebGPUDevice {
         }
         const width = src.width;
         const height = src.height;
-        const mipFormat = normalized.halfFloat ? "rgba16f" : "rgba8";
+        // Preserve HDR source energy even at performance quality. Bloom adds to
+        // scene radiance before tone mapping, so its composite is always floating point.
+        const halfFloat = normalized.halfFloat || src.colorTexture.format === "rgba16f" || src.colorTexture.format === "rgba32f";
+        const mipFormat = halfFloat ? "rgba16f" : "rgba8";
         const owned = [];
         const track = (target) => {
             owned.push(target);
@@ -943,7 +985,7 @@ export class WebGPUDevice {
                 level = mipTarget;
             }
             const weights = defaultWebGPUBloomWeights(normalized.mipCount);
-            const composite = track(this.createRenderTarget({ width, height, format: "rgba8", label: "a3d-webgpu-bloom-composite" }));
+            const composite = track(this.createRenderTarget({ width, height, format: "rgba16f", label: "a3d-webgpu-bloom-composite" }));
             const mipViews = mips.map((mipTarget) => {
                 const view = this.requireRenderTarget(mipTarget).nativeView;
                 if (!view)
@@ -958,13 +1000,13 @@ export class WebGPUDevice {
                 views: [srcView, ...mipViews],
                 target: composite
             });
-            const bytesPerPixel = normalized.halfFloat ? 8 : 4;
+            const bytesPerPixel = halfFloat ? 8 : 4;
             const targetBytes = width * height * bytesPerPixel
-                + mips.reduce((total, mipTarget) => total + mipTarget.width * mipTarget.height * bytesPerPixel, 0)
-                + width * height * 4;
+                + mips.reduce((total, mipTarget) => total + mipTarget.width * mipTarget.height * bytesPerPixel * 2, 0)
+                + width * height * 8;
             this.lastWebGPUBloom = {
                 mipCount: normalized.mipCount,
-                halfFloat: normalized.halfFloat,
+                halfFloat,
                 targetBytes,
                 compositeGain: normalized.strength,
                 passes: 1 + normalized.mipCount * 2 + 1,
@@ -1033,9 +1075,8 @@ export class WebGPUDevice {
     /**
      * muse3jsparity-PRD J2 — native WebGPU FXAA.
      * Compact FXAA 3.11 console core (luma neighborhood, one perpendicular
-     * blend tap pair; flat neighborhoods pass through untouched). TAA is
-     * intentionally out of scope: no velocity/history inputs exist on the
-     * WebGPU path (same withheld doctrine as the root A3 nodes).
+     * blend tap pair; flat neighborhoods pass through untouched). Temporal
+     * antialiasing has a separate GPU history contract in executeWebGPUTaa.
      */
     executeWebGPUFxaa(source) {
         this.reclaimWebGPUPostUniformBuffers();
@@ -1062,16 +1103,108 @@ export class WebGPUDevice {
             throw error;
         }
     }
+    /** Native target-to-target chain. Unsupported passes fail before any submission. */
+    presentLdrPostprocess(source, options) {
+        this.assertAlive();
+        const supported = new Set(["bloom", "tone-mapping", "color-grade", "fxaa", "taa"]);
+        for (const pass of options.passes) {
+            if (!supported.has(pass.name))
+                throw new RenderDeviceError(`Native WebGPU postprocess does not support ${pass.name}`, "WEBGPU_POSTPROCESS_UNSUPPORTED", { pass: pass.name });
+        }
+        const owned = [];
+        let current = source;
+        const track = (target) => { owned.push(target); current = target; };
+        try {
+            for (const pass of options.passes) {
+                if (pass.name === "bloom")
+                    track(this.executeWebGPUBloom(current, pass.options));
+                else if (pass.name === "color-grade")
+                    track(this.executeWebGPUColorGrade(current, pass.options));
+                else if (pass.name === "fxaa")
+                    track(this.executeWebGPUFxaa(current));
+                else if (pass.name === "taa") {
+                    const temporal = pass.options.temporal;
+                    if (!temporal)
+                        throw new RenderDeviceError("Native WebGPU TAA requires GPU temporal bindings", "TEMPORAL_NATIVE_REQUIRED");
+                    track(this.executeWebGPUTaa(current, { ...temporal, ...(typeof pass.options.blend === "number" ? { blend: pass.options.blend } : {}) }));
+                }
+                else if (pass.name === "tone-mapping") {
+                    const tone = { ...options.toneMappingDefaults, ...pass.options };
+                    const operator = tone.operator ?? "reinhard";
+                    const operatorId = operator === "linear" || operator === "none" ? 0 : operator === "reinhard" ? 1 : operator === "aces" || operator === "aces-filmic" ? 2 : operator === "filmic" ? 3 : -1;
+                    if (operatorId < 0)
+                        throw new RenderDeviceError(`Unsupported native WebGPU tone operator ${String(operator)}`, "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    const exposure = typeof tone.exposure === "number" ? tone.exposure : 1;
+                    const whitePoint = typeof tone.whitePoint === "number" ? tone.whitePoint : 1;
+                    if (!Number.isFinite(whitePoint) || whitePoint <= 0)
+                        throw new RenderDeviceError("Invalid tone white point", "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    if (!Number.isFinite(exposure) || exposure < 0)
+                        throw new RenderDeviceError("Invalid tone exposure", "WEBGPU_POSTPROCESS_UNSUPPORTED");
+                    const target = this.createRenderTarget({ width: source.width, height: source.height, format: "rgba8", label: "a3d-webgpu-tone" });
+                    owned.push(target);
+                    this.runWebGPUFullscreenPass({ label: "webgpu-tone", fragment: WEBGPU_NATIVE_TONE_FRAGMENT, entryPoint: "fs_tone",
+                        uniforms: new Float32Array([exposure, operatorId, tone.outputColorSpace === "srgb" ? 1 : 0, whitePoint]),
+                        views: [this.requireRenderTarget(current).nativeView], target });
+                    current = target;
+                }
+            }
+            const target = options.outputTarget ?? null;
+            if (target === current)
+                throw new RenderDeviceError("Native WebGPU presentation source/output alias", "INVALID_RESOURCE");
+            this.runWebGPUFullscreenPass({ label: "webgpu-post-present", fragment: WEBGPU_NATIVE_COPY_FRAGMENT, entryPoint: "fs_copy",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, 0, 0]),
+                views: [this.requireRenderTarget(current).nativeView], target });
+            if (!target) {
+                this.activeRenderTarget = null;
+                this.canvasSubmissions += 1;
+            }
+        }
+        finally {
+            for (const target of owned)
+                target.dispose();
+        }
+    }
+    /** Resolve GPU velocity/history into caller-owned historyOutput, returning scene-alpha color. */
+    executeWebGPUTaa(source, options) {
+        this.assertAlive();
+        const [blend, depthThreshold] = normalizeWebGPUTemporalOptions(options);
+        const targets = [source, options.velocity, options.history, options.historyOutput];
+        if (new Set(targets).size !== targets.length)
+            throw new RenderDeviceError("TAA targets must not alias", "NATIVE_POST_UNSUPPORTED");
+        const native = targets.map((target) => this.requireRenderTarget(target));
+        if (native.some((target) => target.width !== source.width || target.height !== source.height || !target.nativeView)) {
+            throw new RenderDeviceError("TAA requires same-size native source, velocity and history targets", "NATIVE_POST_UNSUPPORTED");
+        }
+        if (targets.slice(1).some((target) => target.colorTexture.format !== "rgba16f")) {
+            throw new RenderDeviceError("TAA velocity/history targets require rgba16f", "NATIVE_POST_UNSUPPORTED");
+        }
+        const out = this.createRenderTarget({ width: source.width, height: source.height, format: "rgba16f", label: "a3d-webgpu-taa-color" });
+        try {
+            this.runWebGPUFullscreenPass({ label: "webgpu-taa", fragment: WEBGPU_TAA_FRAGMENT, entryPoint: "fs_taa",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, blend, options.historyValid ? 1 : 0, depthThreshold, 0, 0, 0]),
+                views: native.slice(0, 3).map((target) => target.nativeView), target: options.historyOutput });
+            this.runWebGPUFullscreenPass({ label: "webgpu-taa-output", fragment: WEBGPU_TAA_OUTPUT_FRAGMENT, entryPoint: "fs_taa_output",
+                uniforms: new Float32Array([1 / source.width, 1 / source.height, 0, 0]),
+                views: [native[3].nativeView, native[0].nativeView], target: out });
+            this.nativeTaaPasses += 2;
+            this.nativeTemporalBindings += 3;
+            return out;
+        }
+        catch (error) {
+            out.dispose();
+            throw error;
+        }
+    }
     runWebGPUFullscreenPass(args) {
         // No assertFrame here on purpose: these are target-to-target passes with
         // their own encoders, so they run both inside a Renderer frame (scene ->
         // post chaining) and after it closed (proof harnesses that render, then
         // post, then read back).
         this.assertAlive();
-        const target = this.requireRenderTarget(args.target);
-        const targetView = target.nativeView;
+        const target = args.target ? this.requireRenderTarget(args.target) : null;
+        const targetView = target ? target.nativeView : this.canvasContext?.getCurrentTexture().createView();
         if (!targetView) {
-            throw new RenderDeviceError("WebGPU post target has no native view", "NATIVE_POST_UNSUPPORTED", { label: target.label });
+            throw new RenderDeviceError("WebGPU post target has no native view", "NATIVE_POST_UNSUPPORTED", { label: target?.label ?? "canvas" });
         }
         if (!this.device.createShaderModule || !this.device.createRenderPipeline || !this.device.createCommandEncoder
             || !this.device.createSampler || !this.device.createBuffer || !this.device.createBindGroup) {
@@ -1084,8 +1217,10 @@ export class WebGPUDevice {
             // the submit) so per-pass validation failures land here labeled.
             scopeDevice.pushErrorScope?.("validation");
         }
-        const format = webgpuTextureFormat(target.colorTexture.format);
-        const cacheKey = `${args.label}:${args.entryPoint}:${format}`;
+        const format = target ? webgpuTextureFormat(target.colorTexture.format) : this.presentationFormat;
+        // Bloom quality changes the fragment binding layout (one texture per mip).
+        // A label/format-only key can reuse the wrong native pipeline after a quality change.
+        const cacheKey = `${args.label}:${args.entryPoint}:${format}:${args.fragment}`;
         let pipeline = this.webgpuPostPipelines.get(cacheKey);
         if (!pipeline) {
             const vertexModule = this.device.createShaderModule({ label: `${args.label}-vs`, code: WEBGPU_POST_VERTEX_WGSL });
@@ -1141,7 +1276,8 @@ export class WebGPUDevice {
             submitted = true;
             // The pass owns every pixel (fullscreen triangle), so a later
             // readPixelsAsync must NOT flush a stale pending clear over it.
-            target.nativeNeedsClear = false;
+            if (target)
+                target.nativeNeedsClear = false;
             this.nativeRenderPasses += 1;
             // Retired, not destroyed: the submit only enqueues; the pass reads
             // these uniforms when the GPU gets to it.
@@ -1202,6 +1338,8 @@ export class WebGPUDevice {
             throw new RenderDeviceError("No active frame", "NO_ACTIVE_FRAME");
         }
     }
+    temporalLossListeners = new Set();
+    onDeviceLost(listener) { this.temporalLossListeners.add(listener); return () => this.temporalLossListeners.delete(listener); }
     observeDeviceLost() {
         const lost = this.device.lost;
         if (!lost || typeof lost.then !== "function")
@@ -1210,12 +1348,24 @@ export class WebGPUDevice {
             if (this.disposed)
                 return;
             this.contextLost = true;
+            for (const listener of this.temporalLossListeners) {
+                try {
+                    listener();
+                }
+                catch { /* Continue notifying owners. */ }
+            }
             const detail = [info.reason, info.message].filter(Boolean).join(": ");
             this.lastError = detail ? `WebGPU device lost: ${detail}` : "WebGPU device lost";
         }).catch((error) => {
             if (this.disposed)
                 return;
             this.contextLost = true;
+            for (const listener of this.temporalLossListeners) {
+                try {
+                    listener();
+                }
+                catch { /* Continue notifying owners. */ }
+            }
             this.lastError = `WebGPU device lost promise rejected: ${error instanceof Error ? error.message : String(error)}`;
         });
     }
@@ -1289,9 +1439,9 @@ export class WebGPUDevice {
                     const worldA = transformPosition(localA, modelMatrix);
                     const worldB = transformPosition(localB, modelMatrix);
                     const worldC = transformPosition(localC, modelMatrix);
-                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA);
-                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB);
-                    const colorC = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexC);
+                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA, colorAttribute?.components);
+                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB, colorAttribute?.components);
+                    const colorC = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexC, colorAttribute?.components);
                     const uvA = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexA);
                     const uvB = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexB);
                     const uvC = readVertexUv(vertexBuffer.bytes, command.vertexFormat.stride, uvAttribute?.offset, indexC);
@@ -1304,15 +1454,15 @@ export class WebGPUDevice {
                     const indexB = indices[offset + 1];
                     const a = transformPosition(readLocal(indexA), matrix);
                     const b = transformPosition(readLocal(indexB), matrix);
-                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA);
-                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB);
+                    const colorA = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexA, colorAttribute?.components);
+                    const colorB = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, indexB, colorAttribute?.components);
                     rasterizeLine(this.activeRenderTarget, a, b, color, colorA, colorB, depthTest, depthWrite);
                 }
             }
             else {
                 for (const index of indices) {
                     const point = transformPosition(readLocal(index), matrix);
-                    const vertexColor = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, index);
+                    const vertexColor = readVertexColor(vertexBuffer.bytes, command.vertexFormat.stride, colorAttribute?.offset, index, colorAttribute?.components);
                     rasterizePoint(this.activeRenderTarget, point, multiplyColor(color, vertexColor), depthTest, depthWrite);
                 }
             }
@@ -1326,7 +1476,27 @@ export class WebGPUDevice {
         if (!hasNativeRenderPipeline(this.device))
             return;
         const shader = this.requireShader(command.shader);
-        const vertexModule = shader.modules[0];
+        // GL supplies an opaque white default for an absent vertex color. Native
+        // WGSL inputs must instead match the actual vertex buffer layout.
+        const useDefaultColor = shader.nativeColorDefaultVertex && !command.vertexFormat?.attributes.some(attribute => attribute.semantic === "color");
+        if (useDefaultColor && !shader.nativeColorDefaultModule) {
+            shader.nativeColorDefaultModule = this.device.createShaderModule?.({ label: `${shader.label}-vertex-default-color`, code: shader.nativeColorDefaultVertex });
+        }
+        let vertexModule = useDefaultColor ? shader.nativeColorDefaultModule : shader.modules[0];
+        if (shader.nativeAtlasVertex) {
+            const hasColor = command.vertexFormat?.attributes.some(attribute => attribute.shaderLocation === 4) ?? false;
+            const hasUv1 = command.vertexFormat?.attributes.some(attribute => attribute.shaderLocation === 7) ?? false;
+            const key = `${hasColor}:${hasUv1}`;
+            if (!shader.atlasVertexModules.has(key)) {
+                let source = shader.nativeAtlasVertex;
+                if (!hasColor)
+                    source = source.replace(", @location(4) color: vec4<f32>", "").replace("output.color = color;", "output.color = vec4<f32>(1.0);");
+                if (!hasUv1)
+                    source = source.replace(", @location(7) uv1: vec2<f32>", "").replace("output.uv1 = uv1;", "output.uv1 = vec2<f32>(0.0);");
+                shader.atlasVertexModules.set(key, this.device.createShaderModule?.({ label: `${shader.label}-atlas-vertex-${key}`, code: source }));
+            }
+            vertexModule = shader.atlasVertexModules.get(key);
+        }
         const fragmentModule = shader.modules[1] ?? vertexModule;
         if (!vertexModule || !fragmentModule)
             return;
@@ -1386,12 +1556,19 @@ export class WebGPUDevice {
         const uniformBuffer = usesNativeDrawUniforms(shader.nativeUniformLayout) ? this.createNativeDrawUniformBuffer(command) : null;
         const sampledTexture = shader.nativeUniformLayout === "generated-texture" ? this.createNativeSampledTextureBinding(uniformBaseColorTextureBinding(command.uniforms)) : null;
         const materialTextures = usesNativePbrTextureBindings(shader.nativeUniformLayout) ? this.createNativePbrTextureBindings(command) : null;
+        const atlasResources = shader.nativeUniformLayout === "generated-atlas-pbr" ? this.createNativeAtlasBindings(command) : null;
+        if (shader.nativeUniformLayout === "generated-atlas-pbr" && !atlasResources) {
+            uniformBuffer?.destroy();
+            return;
+        }
         if (shader.nativeUniformLayout === "generated-texture" && !sampledTexture) {
             uniformBuffer?.destroy();
+            atlasResources?.buffer.destroy();
             return;
         }
         if (usesNativePbrTextureBindings(shader.nativeUniformLayout) && !materialTextures) {
             uniformBuffer?.destroy();
+            atlasResources?.buffer.destroy();
             return;
         }
         if (shader.nativeUniformLayout === "portable" && !portableResources)
@@ -1402,6 +1579,7 @@ export class WebGPUDevice {
                 layout: pipeline.getBindGroupLayout(0),
                 entries: portableResources?.entries ?? [
                     { binding: 0, resource: { buffer: uniformBuffer } },
+                    ...(atlasResources?.entries ?? []),
                     ...(sampledTexture ? [
                         { binding: 1, resource: sampledTexture.sampler },
                         { binding: 2, resource: sampledTexture.view }
@@ -1458,6 +1636,7 @@ export class WebGPUDevice {
             if (!pass.setIndexBuffer || !pass.drawIndexed) {
                 pass.end();
                 uniformBuffer?.destroy();
+                atlasResources?.buffer.destroy();
                 portableResources?.buffer.destroy();
                 this.lastError = "Native WebGPU indexed draw skipped because the render-pass encoder does not expose indexed draw APIs.";
                 return;
@@ -1474,6 +1653,7 @@ export class WebGPUDevice {
         if (this.activeRenderTarget)
             this.activeRenderTarget.nativeNeedsClear = false;
         uniformBuffer?.destroy();
+        atlasResources?.buffer.destroy();
         portableResources?.buffer.destroy();
         this.nativeSubmissions += 1;
         if (sampledTexture)
@@ -1488,7 +1668,7 @@ export class WebGPUDevice {
             this.nativePassthroughSubmissions += 1;
             this.nativeTextureBindings += portableResources?.actualTextureCount ?? 0;
         }
-        if (shader.nativeUniformLayout === "generated-pbr" || shader.nativeUniformLayout === "generated-textured-pbr" || shader.nativeUniformLayout === "generated-instanced-pbr")
+        if (shader.nativeUniformLayout === "generated-pbr" || shader.nativeUniformLayout === "generated-atlas-pbr" || shader.nativeUniformLayout === "generated-textured-pbr" || shader.nativeUniformLayout === "generated-instanced-pbr")
             this.nativePbrSubmissions += 1;
         if (shader.nativeUniformLayout === "generated-instanced-pbr")
             this.nativeInstancedSubmissions += 1;
@@ -1496,6 +1676,7 @@ export class WebGPUDevice {
             this.nativeSkinnedSubmissions += 1;
         if (shader.nativeUniformLayout === "generated-morph-unlit")
             this.nativeMorphSubmissions += 1;
+        this.nativeTextureBindings += atlasResources?.actualTextureCount ?? 0;
         if (materialTextures?.actualBaseColor)
             this.nativeTextureBindings += 1;
         if (materialTextures?.actualNormal)
@@ -1799,6 +1980,36 @@ export class WebGPUDevice {
         this.device.queue.writeBuffer(buffer, 0, data);
         return buffer;
     }
+    createNativeAtlasBindings(command) {
+        const definitions = [
+            ["u_extensionScalarAtlas", 20, 0, "linear"],
+            ["u_clearcoatNormalTexture", 22, 21, "linear"],
+            ["u_sheenColorTexture", 24, 23, "srgb"],
+            ["u_anisotropyTexture", 26, 25, "linear"],
+            ["u_emissiveTexture", 28, 27, "srgb"]
+        ];
+        const entries = [];
+        let actualTextureCount = 0;
+        for (const [name, textureIndex, samplerIndex, colorSpace] of definitions) {
+            const actualTexture = this.createNativeSampledTextureBinding(uniformTextureBinding(command.uniforms, name));
+            if (textureIndex === 20 && !actualTexture)
+                throw new RenderDeviceError("Native extension atlas requires a resolved scalar atlas texture", "TEXTURE_BINDING_MISSING");
+            const texture = actualTexture
+                ?? this.createNativeFallbackSampledTextureBinding(`atlas-${name}`, name.includes("Normal") ? [128, 128, 255, 255] : [255, 255, 255, 255], colorSpace);
+            if (!texture)
+                return null;
+            if (texture.actual)
+                actualTextureCount += 1;
+            entries.push({ binding: textureIndex, resource: texture.view });
+            if (samplerIndex)
+                entries.push({ binding: samplerIndex, resource: texture.sampler });
+        }
+        const data = webgpuExtensionAtlasUniforms(command.uniforms);
+        const buffer = this.device.createBuffer({ label: "extension-atlas-uniforms", size: data.byteLength, usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST });
+        this.device.queue.writeBuffer(buffer, 0, data);
+        entries.push({ binding: 19, resource: { buffer } });
+        return { buffer, entries, actualTextureCount };
+    }
     createNativePortableBindings(command, bindings) {
         if (!this.device.createBindGroup)
             return null;
@@ -2105,6 +2316,7 @@ function usesNativeDrawUniforms(layout) {
 }
 function usesNativePbrTextureBindings(layout) {
     return layout === "generated-pbr" ||
+        layout === "generated-atlas-pbr" ||
         layout === "generated-textured-pbr" ||
         layout === "generated-instanced-pbr";
 }
@@ -2360,7 +2572,7 @@ function jointPaletteFor(uniforms) {
     const count = Math.min(MAX_WEBGPU_SKINNING_JOINTS, Math.floor(length / 16));
     return count > 0 ? uniformMat4Array(value, count) : [];
 }
-function readVertexColor(bytes, stride, offset, vertexIndex) {
+function readVertexColor(bytes, stride, offset, vertexIndex, components = 4) {
     if (offset === undefined)
         return [1, 1, 1, 1];
     const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -2369,7 +2581,7 @@ function readVertexColor(bytes, stride, offset, vertexIndex) {
         view.getFloat32(base, true),
         view.getFloat32(base + 4, true),
         view.getFloat32(base + 8, true),
-        view.getFloat32(base + 12, true)
+        components >= 4 ? view.getFloat32(base + 12, true) : 1
     ];
 }
 function readVertexUv(bytes, stride, offset, vertexIndex) {
@@ -2554,7 +2766,9 @@ function createNativeShaderSources(sources) {
         return { ...nativeInstancedPbrShader(vertexEntry, fragmentEntry, sources.marker), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-instanced-pbr" };
     }
     if (sources.marker.includes("pbr-textured")) {
-        return { ...nativeTexturedPbrShader(vertexEntry, fragmentEntry, sources.marker, nativeShaderUsesTangent(sources.vertex)), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-textured-pbr" };
+        const atlas = /uniform\s+sampler2D\s+u_extensionScalarAtlas/.test(sources.fragment);
+        const native = nativeTexturedPbrShader(vertexEntry, fragmentEntry, sources.marker, nativeShaderUsesTangent(sources.vertex), atlas);
+        return { ...native, ...(atlas ? { atlasVertex: native.vertex } : {}), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: atlas ? "generated-atlas-pbr" : "generated-textured-pbr" };
     }
     if (sources.marker.includes("pbr-direct")) {
         return sources.fragment.includes("u_baseColorTexture")
@@ -2568,20 +2782,89 @@ function createNativeShaderSources(sources) {
         return { ...nativeMorphUnlitShader(vertexEntry, fragmentEntry, sources.marker), entryPoints: [vertexEntry, fragmentEntry], uniformLayout: "generated-morph-unlit" };
     }
     if (/sampler2D/.test(sources.fragment) && /layout\s*\(\s*location\s*=\s*2\s*\)\s*in\s+vec2/.test(sources.vertex)) {
+        const colorInput = /layout\s*\(\s*location\s*=\s*(\d+)\s*\)\s*in\s+(?:lowp\s+|mediump\s+|highp\s+)?vec([34])\s+(?:a_color|color)\s*;/.exec(sources.vertex);
+        const colorParameter = colorInput ? `, @location(${colorInput[1]}) vertexColor: vec${colorInput[2]}<f32>` : "";
+        const drawUniforms = `struct DrawUniforms {
+  modelViewProjection: mat4x4<f32>,
+  color: vec4<f32>,
+};
+@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;`;
+        const vertexOutput = `struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+  ${colorInput ? "@location(1) color: vec4<f32>," : ""}
+};`;
+        const vertex = `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@vertex
+fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(2) uv: vec2<f32>${colorParameter}) -> VertexOutput {
+  var output: VertexOutput;
+  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
+  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);
+  output.uv = uv;
+  ${colorInput ? `output.color = ${colorInput[2] === "3" ? "vec4<f32>(vertexColor, 1.0)" : "vertexColor"};` : ""}
+  return output;
+}
+`;
         return {
-            vertex: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n  @location(0) uv: vec2<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@vertex\nfn ${vertexEntry}(@location(0) position: vec3<f32>, @location(2) uv: vec2<f32>) -> VertexOutput {\n  var output: VertexOutput;\n  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
-  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);\n  output.uv = uv;\n  return output;\n}\n`,
-            fragment: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n  @location(0) uv: vec2<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n@group(0) @binding(1) var u_textureSampler: sampler;\n@group(0) @binding(2) var u_texture: texture_2d<f32>;\n\n@fragment\nfn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {\n  return u_draw.color * textureSample(u_texture, u_textureSampler, input.uv);\n}\n`,
+            vertex,
+            colorDefaultVertex: colorInput ? vertex.replace(colorParameter, "").replace(/output\.color = [^;]+;/, "output.color = vec4<f32>(1.0);") : undefined,
+            fragment: `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@group(0) @binding(1) var u_textureSampler: sampler;
+@group(0) @binding(2) var u_texture: texture_2d<f32>;
+@fragment
+fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
+  return u_draw.color * textureSample(u_texture, u_textureSampler, input.uv)${colorInput ? " * input.color" : ""};
+}
+`,
             entryPoints: [vertexEntry, fragmentEntry],
             uniformLayout: "generated-texture"
         };
     }
+    // Basic GLSL programs (including unlit primitives and particle sprites)
+    // declare their color input explicitly. Preserve that location and component
+    // count; RGB inputs use opaque alpha, while RGBA alpha modulates the material.
+    // Depth programs intentionally do not consume material/vertex color.
+    const colorInput = sources.marker.includes(DEFAULT_DEPTH_SHADER_MARKER) ? null
+        : /layout\s*\(\s*location\s*=\s*(\d+)\s*\)\s*in\s+(?:lowp\s+|mediump\s+|highp\s+)?vec([34])\s+(?:a_color|color)\s*;/.exec(sources.vertex);
+    const colorParameter = colorInput ? `, @location(${colorInput[1]}) vertexColor: vec${colorInput[2]}<f32>` : "";
+    const vertexOutput = `struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  ${colorInput ? "@location(0) color: vec4<f32>," : ""}
+};`;
+    const drawUniforms = `struct DrawUniforms {
+  modelViewProjection: mat4x4<f32>,
+  color: vec4<f32>,
+};
+@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;`;
+    const vertex = `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@vertex
+fn ${vertexEntry}(@location(0) position: vec3<f32>${colorParameter}) -> VertexOutput {
+  var output: VertexOutput;
+  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
+  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);
+  ${colorInput ? `output.color = ${colorInput[2] === "3" ? "vec4<f32>(vertexColor, 1.0)" : "vertexColor"};` : ""}
+  return output;
+}
+`;
     return {
-        vertex: `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) position: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@vertex\nfn ${vertexEntry}(@location(0) position: vec3<f32>) -> VertexOutput {\n  var output: VertexOutput;\n  let clipPosition = u_draw.modelViewProjection * vec4<f32>(position, 1.0);
-  output.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.z * 0.5 + clipPosition.w * 0.5, clipPosition.w);\n  return output;\n}\n`,
+        vertex,
+        colorDefaultVertex: colorInput ? vertex.replace(colorParameter, "").replace(/output\.color = [^;]+;/, "output.color = vec4<f32>(1.0);") : undefined,
         fragment: sources.marker.includes(DEFAULT_DEPTH_SHADER_MARKER)
             ? nativeDepthFragment(sources.marker, fragmentEntry)
-            : `// ${sources.marker}\nstruct DrawUniforms {\n  modelViewProjection: mat4x4<f32>,\n  color: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u_draw: DrawUniforms;\n\n@fragment\nfn ${fragmentEntry}() -> @location(0) vec4<f32> {\n  return u_draw.color;\n}\n`,
+            : `// ${sources.marker}
+${drawUniforms}
+${vertexOutput}
+@fragment
+fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
+  return u_draw.color${colorInput ? " * input.color" : ""};
+}
+`,
         entryPoints: [vertexEntry, fragmentEntry],
         uniformLayout: "generated-basic"
     };
@@ -2725,7 +3008,7 @@ fn a3dWebGPUClipPosition(clipPosition: vec4<f32>) -> vec4<f32> {
 function nativeShaderUsesTangent(vertexSource) {
     return /\ba_tangent\b/.test(vertexSource) || /layout\s*\(\s*location\s*=\s*3\s*\)\s*in\s+vec4/.test(vertexSource);
 }
-function nativePbrFragmentPrelude(marker) {
+function nativePbrFragmentPrelude(marker, atlas = false) {
     return `// ${marker}
 ${nativeUniformStruct()}
 @group(0) @binding(1) var u_baseSampler: sampler;
@@ -2747,12 +3030,15 @@ ${nativeUniformStruct()}
 @group(0) @binding(17) var u_spotShadowSampler: sampler;
 @group(0) @binding(18) var u_spotShadowTexture: texture_2d<f32>;
 
+${atlas ? WEBGPU_EXTENSION_ATLAS_WGSL : ""}
+
 struct VertexOutput {
   @builtin(position) position: vec4<f32>,
   @location(0) normal: vec3<f32>,
   @location(1) uv: vec2<f32>,
   @location(2) worldPosition: vec3<f32>,
   @location(3) tangent: vec4<f32>,
+  ${atlas ? "@location(4) uv1: vec2<f32>, @location(5) color: vec4<f32>," : ""}
 };
 
 fn fresnelSchlick(cosTheta: f32, f0: vec3<f32>) -> vec3<f32> {
@@ -2765,14 +3051,16 @@ fn fresnelSchlickRoughness(cosTheta: f32, f0: vec3<f32>, roughness: f32) -> vec3
 }
 
 fn ggxDistribution(nDotH: f32, roughness: f32) -> f32 {
-  let a = max(roughness * roughness, 0.045);
+  let a = ${atlas ? "max(roughness, 0.045) * max(roughness, 0.045)" : "max(roughness * roughness, 0.045)"};
   let a2 = a * a;
-  let denom = max((nDotH * nDotH) * (a2 - 1.0) + 1.0, 0.001);
-  return a2 / max(3.14159265 * denom * denom, 0.001);
+  // At roughness .045 the true denominator before squaring is ~4.1e-6.
+  // A .001/.00001 floor destroys the normalized low-roughness GGX lobe.
+  let denom = max((nDotH * nDotH) * (a2 - 1.0) + 1.0, ${atlas ? "0.00000001" : "0.001"});
+  return a2 / max(3.14159265 * denom * denom, ${atlas ? "0.0000000000000001" : "0.001"});
 }
 
 fn ggxVisibilitySmithCorrelated(nDotV: f32, nDotL: f32, roughness: f32) -> f32 {
-  let a = max(roughness * roughness, 0.045);
+  let a = ${atlas ? "max(roughness, 0.045) * max(roughness, 0.045)" : "max(roughness * roughness, 0.045)"};
   let a2 = a * a;
   let lambdaV = nDotL * sqrt(max((nDotV - a2 * nDotV) * nDotV + a2, 0.00001));
   let lambdaL = nDotV * sqrt(max((nDotL - a2 * nDotL) * nDotL + a2, 0.00001));
@@ -2898,18 +3186,18 @@ fn a3dNativeShadowFactor(worldPosition: vec3<f32>, normal: vec3<f32>, lightDirec
   return mix(1.0, 1.0 - occlusion, clamp(strength, 0.0, 1.0));
 }
 
-fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worldPosition: vec3<f32>, fragmentPosition: vec2<f32>) -> vec4<f32> {
+fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worldPosition: vec3<f32>, fragmentPosition: vec2<f32>${atlas ? ", uv1: vec2<f32>, vertexColor: vec4<f32>" : ""}) -> vec4<f32> {
   var normal = normalize(normalInput);
   if (u_draw.morph0.x > 0.5) {
-    normal = perturbNormal(normal, tangentFrame, textureSample(u_normalTexture, u_normalSampler, uv).rgb, u_draw.morph0.y);
+    normal = perturbNormal(normal, tangentFrame, textureSample(u_normalTexture, u_normalSampler, ${atlas ? "atlasUv(1u, uv, uv1)" : "uv"}).rgb, u_draw.morph0.y);
   }
   let viewDirection = normalize(u_draw.camera.xyz - worldPosition);
   let lightDirection = normalize(vec3<f32>(0.36, 0.52, 0.78));
   let halfVector = normalize(lightDirection + viewDirection);
-  var baseColor = u_draw.color.rgb;
-  var materialAlpha = u_draw.color.a;
+  var baseColor = u_draw.color.rgb${atlas ? " * vertexColor.rgb" : ""};
+  var materialAlpha = u_draw.color.a${atlas ? " * vertexColor.a" : ""};
   if (u_draw.flags.x > 0.5) {
-    let baseSample = textureSample(u_baseTexture, u_baseSampler, uv);
+    let baseSample = textureSample(u_baseTexture, u_baseSampler, ${atlas ? "atlasUv(0u, uv, uv1)" : "uv"});
     baseColor = baseColor * baseSample.rgb;
     materialAlpha = materialAlpha * baseSample.a;
   }
@@ -2918,16 +3206,14 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let productBodyGate = productPropBodyGate(sourceProductBaseColor, u_draw.materialFlags.z) * (1.0 - productOrangeGate * 0.92);
   let productSurfaceGate = clamp(productBodyGate + productOrangeGate * 0.72, 0.0, 1.0);
   baseColor = productPropAlbedo(sourceProductBaseColor, u_draw.materialFlags.z);
-  if (materialAlpha < u_draw.material.x) {
-    discard;
-  }
+  ${atlas ? "" : "if (materialAlpha < u_draw.material.x) { discard; }"}
   let transmission = clamp(max(u_draw.material.y, u_draw.material.z), 0.0, 1.0);
-  let metallicRoughnessSample = textureSample(u_metallicRoughnessTexture, u_metallicRoughnessSampler, uv);
+  let metallicRoughnessSample = textureSample(u_metallicRoughnessTexture, u_metallicRoughnessSampler, ${atlas ? "atlasUv(2u, uv, uv1)" : "uv"});
   let metallicRoughnessEnabled = step(0.5, u_draw.materialFlags.x);
   let occlusionEnabled = step(0.5, u_draw.materialFlags.y);
   let sampledMetallic = clamp(u_draw.params.x * metallicRoughnessSample.b, 0.0, 1.0);
   let sampledRoughness = clamp(u_draw.params.y * metallicRoughnessSample.g, 0.045, 1.0);
-  let sampledOcclusion = mix(1.0, textureSample(u_occlusionTexture, u_occlusionSampler, uv).r, clamp(u_draw.morph0.z, 0.0, 1.0));
+  let sampledOcclusion = mix(1.0, textureSample(u_occlusionTexture, u_occlusionSampler, ${atlas ? "atlasUv(3u, uv, uv1)" : "uv"}).r, clamp(u_draw.morph0.z, 0.0, 1.0));
   let metallic = mix(clamp(u_draw.params.x, 0.0, 1.0), sampledMetallic, metallicRoughnessEnabled);
   let roughness = mix(clamp(u_draw.params.y, 0.045, 1.0), sampledRoughness, metallicRoughnessEnabled);
   let occlusion = mix(1.0, sampledOcclusion, occlusionEnabled);
@@ -2937,16 +3223,23 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let nDotV = max(dot(normal, viewDirection), 0.001);
   let nDotH = max(dot(normal, halfVector), 0.001);
   let vDotH = max(dot(viewDirection, halfVector), 0.001);
-  let f0 = mix(vec3<f32>(0.04, 0.04, 0.04), baseColor, metallic);
+  let dielectricF0 = ${atlas ? "vec3<f32>(pow((u_atlas.substrate.x-1.0)/(u_atlas.substrate.x+1.0),2.0)) * clamp(u_atlas.specularColor.rgb,vec3<f32>(0.0),vec3<f32>(1.0)) * clamp(u_atlas.substrate.y,0.0,1.0)" : "vec3<f32>(0.04, 0.04, 0.04)"};
+  let f0 = mix(dielectricF0, baseColor, metallic);
   let fresnel = fresnelSchlick(vDotH, f0);
   let distribution = ggxDistribution(nDotH, roughness);
   let visibility = ggxVisibilitySmithCorrelated(nDotV, nDotL, roughness);
   let lDotH = max(dot(lightDirection, halfVector), 0.0);
-  let kd = (vec3<f32>(1.0, 1.0, 1.0) - fresnel) * (1.0 - metallic);
+  ${atlas ? `// The film replaces the substrate Fresnel in the dielectric energy split.
+  // Retaining the old kd while adding film specular creates or loses energy.
+  let filmFresnel = atlasIridescenceFresnel(f0, vDotH, uv, uv1);
+  let filmMaximum = max(max(filmFresnel.r, filmFresnel.g), filmFresnel.b);
+  let diffuseFresnel = select(fresnel, vec3<f32>(filmMaximum), u_atlas.iridescence.y > 0.0);
+  let kd = (vec3<f32>(1.0) - diffuseFresnel) * (1.0 - metallic);` : "let kd = (vec3<f32>(1.0, 1.0, 1.0) - fresnel) * (1.0 - metallic);"}
   let specular = fresnel * distribution * visibility;
   let diffuse = kd * baseColor * diffuseBurley(nDotV, nDotL, lDotH, roughness) / 3.14159265;
   var environment = baseColor * u_draw.params.z * (0.28 + 0.72 * clamp(normal.y * 0.5 + 0.5, 0.0, 1.0)) * occlusion;
   var environmentSpecularContribution = vec3<f32>(0.0, 0.0, 0.0);
+  var environmentExtensionRadiance = vec3<f32>(0.0);
   if (u_draw.flags.w > 0.5) {
     let reflectionDirection = reflect(-viewDirection, normal);
     let diffuseUv = vec2<f32>(fract(atan2(normal.z, normal.x) / 6.2831853 + 0.5), acos(clamp(normal.y, -1.0, 1.0)) / 3.14159265);
@@ -2957,8 +3250,10 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
     let brdf = textureSampleLevel(u_brdfTexture, u_brdfSampler, vec2<f32>(nDotV, roughness), 0.0).rg;
     let environmentFresnel = fresnelSchlickRoughness(nDotV, f0, roughness);
     let environmentDiffuse = (vec3<f32>(1.0, 1.0, 1.0) - environmentFresnel) * (1.0 - metallic) * diffuseEnv * baseColor * u_draw.params.w * occlusion;
-    let environmentSpecular = specularEnv * (f0 * brdf.x + vec3<f32>(brdf.y, brdf.y, brdf.y)) * max(u_draw.reserved0.w, 0.0);
+    ${atlas ? "let environmentF0 = atlasIridescenceEnvironmentF0(f0, nDotV, uv, uv1);" : "let environmentF0 = f0;"}
+    let environmentSpecular = specularEnv * (environmentF0 * brdf.x + vec3<f32>(brdf.y, brdf.y, brdf.y)) * max(u_draw.reserved0.w, 0.0);
     environmentSpecularContribution = environmentSpecular;
+    environmentExtensionRadiance = specularEnv * max(u_draw.reserved0.w, 0.0);
     environment = environment + environmentDiffuse + environmentSpecular;
   }
   // J2 native shadow projections: directional PCF mirrors GLSL
@@ -2998,7 +3293,8 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
     }
   }
   let legacyDirect = (diffuse + specular) * nDotL * 2.25 * shadow;
-  let litOpaqueLinearColor = environment + select(legacyDirect, clusteredDirect, u_draw.materialFlags.w > 0.5);
+  let litOpaqueLinearColor = environment + select(legacyDirect, clusteredDirect, u_draw.materialFlags.w > 0.5)
+    ${atlas ? "+ atlasExtensionLighting(normal, tangentFrame, viewDirection, lightDirection, uv, uv1, shadow, environmentExtensionRadiance, f0, roughness) + u_atlas.emissive.rgb * u_atlas.factors.y * mix(vec3<f32>(1.0), textureSample(u_emissiveTexture, u_emissiveSampler, atlasUv(4u, uv, uv1)).rgb, u_atlas.maps[4].control.z)" : ""};
   let smoothedBodyColor = mix(baseColor, vec3<f32>(1.0, 0.88, 0.012), productBodyGate * 0.32);
   let smoothedBeakColor = mix(baseColor, vec3<f32>(1.0, 0.24, 0.018), productOrangeGate * 0.82);
   let softBodyProduct = smoothedBodyColor * (1.5 + 0.06 * nDotL) + specular * nDotL * 0.018;
@@ -3008,6 +3304,7 @@ fn shadePbr(normalInput: vec3<f32>, tangentFrame: vec4<f32>, uv: vec2<f32>, worl
   let transmittedTint = baseColor * u_draw.params.w * (0.18 + 0.42 * clamp(1.0 - roughness, 0.0, 1.0)) + environmentSpecularContribution * 1.35;
   let linearColor = mix(opaqueLinearColor, opaqueLinearColor * 0.22 + transmittedTint, transmission);
   let outputAlpha = mix(materialAlpha, min(materialAlpha, 0.22), transmission);
+  ${atlas ? "if (materialAlpha < u_draw.material.x) { discard; }" : ""}
   return vec4<f32>(encodePbrOutput(linearColor), outputAlpha);
 }
 `;
@@ -3044,7 +3341,7 @@ fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
 `
     };
 }
-function nativeTexturedPbrShader(vertexEntry, fragmentEntry, marker, usesTangent) {
+function nativeTexturedPbrShader(vertexEntry, fragmentEntry, marker, usesTangent, atlas = false) {
     return {
         vertex: `// ${marker}
 ${nativeUniformStruct()}
@@ -3054,24 +3351,26 @@ struct VertexOutput {
   @location(1) uv: vec2<f32>,
   @location(2) worldPosition: vec3<f32>,
   @location(3) tangent: vec4<f32>,
+  ${atlas ? "@location(4) uv1: vec2<f32>, @location(5) color: vec4<f32>," : ""}
 };
 
 @vertex
-fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(1) normal: vec3<f32>, @location(2) uv: vec2<f32>${usesTangent ? ", @location(3) tangent: vec4<f32>" : ""}) -> VertexOutput {
+fn ${vertexEntry}(@location(0) position: vec3<f32>, @location(1) normal: vec3<f32>, @location(2) uv: vec2<f32>${usesTangent ? ", @location(3) tangent: vec4<f32>" : ""}${atlas ? ", @location(4) color: vec4<f32>, @location(7) uv1: vec2<f32>" : ""}) -> VertexOutput {
   var output: VertexOutput;
   let worldPosition = (u_draw.instance0 * vec4<f32>(position, 1.0)).xyz;
   output.position = a3dWebGPUClipPosition(u_draw.modelViewProjection * vec4<f32>(position, 1.0));
   output.normal = normalize((u_draw.normalMatrix * vec4<f32>(normal, 0.0)).xyz);
   output.uv = uv;
+  ${atlas ? "output.uv1 = uv1; output.color = color;" : ""}
   output.worldPosition = worldPosition;
   ${usesTangent ? "output.tangent = vec4<f32>(normalize((u_draw.normalMatrix * vec4<f32>(tangent.xyz, 0.0)).xyz), tangent.w);" : "output.tangent = vec4<f32>(1.0, 0.0, 0.0, 1.0);"}
   return output;
 }
 `,
-        fragment: `${nativePbrFragmentPrelude(marker)}
+        fragment: `${nativePbrFragmentPrelude(marker, atlas)}
 @fragment
 fn ${fragmentEntry}(input: VertexOutput) -> @location(0) vec4<f32> {
-  return shadePbr(input.normal, input.tangent, input.uv, input.worldPosition, input.position.xy);
+  return shadePbr(input.normal, input.tangent, input.uv, input.worldPosition, input.position.xy${atlas ? ", input.uv1, input.color" : ""});
 }
 `
     };