@aura3d/engine 1.4.4 → 1.5.0

package/dist/rendering/DepthPass.d.ts

@@ -12,9 +12,22 @@ export declare class DepthMaterial extends Material {
 }
 export declare class DepthPass extends BaseRenderPass {
     private readonly options;
+    /**
+     * Depth shader modules, shared across `DepthPass` instances and keyed by shader library.
+     *
+     * `ShadowPass` constructs a **new `DepthPass` every time it renders**, so an instance-field cache
+     * was discarded each frame and the depth shader was recompiled and relinked on every shadow pass.
+     * WebGL shader compilation is a synchronous GPU stall: measured on the Aura Clash playable route,
+     * that single per-frame recompile held the whole route at **2 FPS** with 97.8% of profiled time
+     * outside JS, which in turn made every timing-based browser test miss its window.
+     *
+     * A `WeakMap` keyed by the library keeps the entry alive exactly as long as the library is, so a
+     * long-lived renderer compiles the depth shader once while a disposed library is still collectable.
+     * This mirrors the per-device/per-library cache `ForwardPass` already uses.
+     */
+    private static readonly shaderModules;
     private readonly shaderLibrary;
     private readonly material;
-    private shaderModule;
     constructor(options: DepthPassOptions);
     execute(context: RenderPassContext): void;
     private drawCaster;

package/dist/rendering/DepthPass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DepthPass.d.ts","sourceRoot":"","sources":["../../../../packages/rendering/src/DepthPass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,OAAO,EAA6B,KAAK,aAAa,EAA8B,MAAM,iBAAiB,CAAC;AAC5G,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;CAClE;AAED,qBAAa,aAAc,SAAQ,QAAQ;;CAY1C;AAED,qBAAa,SAAU,SAAQ,cAAc;IAK/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,YAAY,CAA6B;gBAEpB,OAAO,EAAE,gBAAgB;IAKtD,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAMzC,OAAO,CAAC,UAAU;IA6BlB,OAAO,CAAC,SAAS;CAMlB"}
+{"version":3,"file":"DepthPass.d.ts","sourceRoot":"","sources":["../../../../packages/rendering/src/DepthPass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtE,OAAO,EAA6B,KAAK,aAAa,EAA8B,MAAM,iBAAiB,CAAC;AAC5G,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;CAClE;AAED,qBAAa,aAAc,SAAQ,QAAQ;;CAY1C;AAED,qBAAa,SAAU,SAAQ,cAAc;IAmB/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAlBpC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAA8C;IAEnF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;gBAEnB,OAAO,EAAE,gBAAgB;IAKtD,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAMzC,OAAO,CAAC,UAAU;IA6BlB,OAAO,CAAC,SAAS;CAQlB"}

package/dist/rendering/DepthPass.js

@@ -20,9 +20,22 @@ export class DepthMaterial extends Material {
 }
 export class DepthPass extends BaseRenderPass {
     options;
+    /**
+     * Depth shader modules, shared across `DepthPass` instances and keyed by shader library.
+     *
+     * `ShadowPass` constructs a **new `DepthPass` every time it renders**, so an instance-field cache
+     * was discarded each frame and the depth shader was recompiled and relinked on every shadow pass.
+     * WebGL shader compilation is a synchronous GPU stall: measured on the Aura Clash playable route,
+     * that single per-frame recompile held the whole route at **2 FPS** with 97.8% of profiled time
+     * outside JS, which in turn made every timing-based browser test miss its window.
+     *
+     * A `WeakMap` keyed by the library keeps the entry alive exactly as long as the library is, so a
+     * long-lived renderer compiles the depth shader once while a disposed library is still collectable.
+     * This mirrors the per-device/per-library cache `ForwardPass` already uses.
+     */
+    static shaderModules = new WeakMap();
     shaderLibrary;
     material = new DepthMaterial();
-    shaderModule = null;
     constructor(options) {
         super("depth", [], ["depth"]);
         this.options = options;
@@ -62,10 +75,12 @@ export class DepthPass extends BaseRenderPass {
         device.draw(command);
     }
     getShader(device) {
-        if (!this.shaderModule) {
-            this.shaderModule = ShaderModule.fromLibrary(this.shaderLibrary, this.material.shaderKey);
+        let module = DepthPass.shaderModules.get(this.shaderLibrary);
+        if (!module) {
+            module = ShaderModule.fromLibrary(this.shaderLibrary, this.material.shaderKey);
+            DepthPass.shaderModules.set(this.shaderLibrary, module);
         }
-        return this.shaderModule.compile(device);
+        return module.compile(device);
     }
 }
 function resolveDepthDrawRange(geometry, range) {

package/dist/rendering/DepthPass.js.map

@@ -1 +1 @@
-{"version":3,"file":"DepthPass.js","sourceRoot":"","sources":["../../../../packages/rendering/src/DepthPass.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DepthPass.js","sourceRoot":"","sources":["../../../../packages/rendering/src/DepthPass.ts"],"names":[],"mappings":"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"}

package/dist/rendering/EnvironmentMapResources.d.ts

@@ -51,6 +51,7 @@ export interface EnvironmentResourceSetOptions {
     readonly toneMapping?: EnvironmentToneMappingOperator;
     readonly specularLevels?: number;
     readonly specularBlurRadius?: number;
+    readonly specularSampleCount?: number;
     readonly irradianceWidth?: number;
     readonly irradianceHeight?: number;
     readonly irradianceBlurRadius?: number;
@@ -69,6 +70,10 @@ export interface EnvironmentMapResourceSet {
         readonly hdrSource: boolean;
         readonly maxLinearValue: number;
         readonly specularMipCount: number;
+        /** Roughness each specular level was GGX-filtered for, ordered by level. */
+        readonly specularLevelRoughness: readonly number[];
+        readonly specularFilterModel: "ggx-importance-sampled-equirect-prefilter";
+        readonly diffuseIrradianceModel: "sh9-cosine-convolved";
         readonly diffuseIrradianceSize: readonly [number, number];
         readonly brdfLutSize: readonly [number, number];
     };
@@ -86,13 +91,66 @@ export declare function encodeLinearHdrEnvironmentToRgba8(source: LinearHdrEnvir
 export declare function encodeLinearHdrEnvironmentToRgbe(source: LinearHdrEnvironmentMapSource): RgbeEnvironmentMapSource;
 export declare function encodeLinearHdrEnvironmentToRgba16f(source: LinearHdrEnvironmentMapSource): TextureMipLevelDescriptor;
 export declare function generateRgba8EnvironmentMipLevels(source: Rgba8EnvironmentMapSource, options?: EnvironmentMipGenerationOptions): readonly TextureMipLevelDescriptor[];
-export declare function generateSpecularPrefilterMipLevels(source: Rgba8EnvironmentMapSource, options?: EnvironmentMipGenerationOptions): readonly TextureMipLevelDescriptor[];
+/**
+ * Real GGX importance-sampled specular prefilter over an RGBA8 environment.
+ *
+ * Each level `i` of `levelCount` is filtered for roughness `i / (levelCount - 1)`
+ * by convolving the linearised source with the GGX lobe for that exact
+ * roughness, so the roughness a shader assigns to a LOD is the roughness the
+ * texels were actually filtered for. The previous implementation delegated to
+ * `generateRgba8EnvironmentMipLevels` with a box-blur radius, which produced a
+ * mip chain whose blur width was unrelated to its nominal roughness.
+ *
+ * `blurRadius` is retained only for call-site compatibility and no longer
+ * affects the filter; `sampleCount` controls GGX sample density instead.
+ */
+export declare function generateSpecularPrefilterMipLevels(source: Rgba8EnvironmentMapSource, options?: EnvironmentSpecularPrefilterGenerationOptions): readonly TextureMipLevelDescriptor[];
+/**
+ * Roughness each specular prefilter level was genuinely filtered for. Callers
+ * must use this rather than deriving roughness from a mip index they did not
+ * generate.
+ */
+export { specularPrefilterLevelRoughness } from "./SpecularPrefilter";
 export declare function generateRgbeEnvironmentMipLevels(source: LinearHdrEnvironmentMapSource, options?: EnvironmentMipGenerationOptions): readonly TextureMipLevelDescriptor[];
+/**
+ * Real GGX specular prefilter for HDR environments, encoded as RGBE per level.
+ * `generateRgbeEnvironmentMipLevels` remains available for plain mip pyramids,
+ * but it is a progressive box downsample and must not be labelled as
+ * roughness-prefiltered.
+ */
+export declare function generateRgbeSpecularPrefilterMipLevels(source: LinearHdrEnvironmentMapSource, options?: EnvironmentSpecularPrefilterGenerationOptions): readonly TextureMipLevelDescriptor[];
 export declare function generateRgba16fEnvironmentMipLevels(source: LinearHdrEnvironmentMapSource, options?: EnvironmentMipGenerationOptions): readonly TextureMipLevelDescriptor[];
 export declare function generateRgba16fSpecularPrefilterMipLevels(source: LinearHdrEnvironmentMapSource, options?: EnvironmentSpecularPrefilterGenerationOptions): readonly TextureMipLevelDescriptor[];
 export declare function generateRgba16fDiffuseIrradianceMipLevel(source: LinearHdrEnvironmentMapSource, options?: DiffuseIrradianceGenerationOptions): TextureMipLevelDescriptor;
+/**
+ * Cosine-convolved diffuse irradiance for RGBA8 environments.
+ *
+ * This previously averaged a square box of source texels, which is not a cosine
+ * convolution: it ignores the hemisphere orientation entirely, so two opposite
+ * normals sampled from nearby texels received nearly identical "irradiance".
+ * The environment is now decoded to linear, projected onto nine irradiance SH
+ * bands with per-texel solid angle weights, and evaluated per output direction.
+ *
+ * `blurRadius` is retained for call-site compatibility and no longer affects
+ * the result.
+ */
 export declare function generateDiffuseIrradianceRgba8(source: Rgba8EnvironmentMapSource, options?: DiffuseIrradianceGenerationOptions): Rgba8EnvironmentMapSource;
+/**
+ * Cosine-convolved diffuse irradiance for HDR environments, encoded as RGBE.
+ * Replaces the previous box average for the same reason as the RGBA8 path.
+ */
 export declare function generateDiffuseIrradianceRgbe(source: LinearHdrEnvironmentMapSource, options?: DiffuseIrradianceGenerationOptions): RgbeEnvironmentMapSource;
 export declare function createEnvironmentMapResourceSet(input: EnvironmentMapResourceInput, options?: EnvironmentResourceSetOptions): EnvironmentMapResourceSet;
+/**
+ * Generates the deterministic GGX split-sum DFG lookup texture used by the
+ * environment-lighting shaders. The historical `Approximate` export name is
+ * retained for API compatibility; each texel is numerically integrated rather
+ * than evaluated from an analytic fit.
+ *
+ * The red channel stores the coefficient multiplied by F0 and the green
+ * channel stores the grazing-angle Fresnel bias:
+ *
+ * `environmentSpecular * (F0 * red + green)`
+ */
 export declare function generateApproximateBrdfLutPixels(descriptor?: BrdfLutDescriptor): Rgba8EnvironmentMapSource;
 //# sourceMappingURL=EnvironmentMapResources.d.ts.map

package/dist/rendering/EnvironmentMapResources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvironmentMapResources.d.ts","sourceRoot":"","sources":["../../../../packages/rendering/src/EnvironmentMapResources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EnvironmentMapResources.d.ts","sourceRoot":"","sources":["../../../../packages/rendering/src/EnvironmentMapResources.ts"],"names":[],"mappings":"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"}

package/dist/rendering/EnvironmentMapResources.js

@@ -1,5 +1,7 @@
 import {} from "./Texture.js";
+import { convolveEnvironmentIrradiance, prefilterGgxEnvironmentLevels, specularPrefilterLevelRoughness } from "./SpecularPrefilter.js";
 const A3D_EPSILON_NUMBER = 0.00001;
+const A3D_MIN_PBR_ROUGHNESS = 0.045;
 export function srgbChannelToLinear(value) {
     const channel = validateNormalizedChannel(value, "sRGB channel");
     return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
@@ -103,12 +105,57 @@ export function generateRgba8EnvironmentMipLevels(source, options = {}) {
     }
     return levels;
 }
+/**
+ * Real GGX importance-sampled specular prefilter over an RGBA8 environment.
+ *
+ * Each level `i` of `levelCount` is filtered for roughness `i / (levelCount - 1)`
+ * by convolving the linearised source with the GGX lobe for that exact
+ * roughness, so the roughness a shader assigns to a LOD is the roughness the
+ * texels were actually filtered for. The previous implementation delegated to
+ * `generateRgba8EnvironmentMipLevels` with a box-blur radius, which produced a
+ * mip chain whose blur width was unrelated to its nominal roughness.
+ *
+ * `blurRadius` is retained only for call-site compatibility and no longer
+ * affects the filter; `sampleCount` controls GGX sample density instead.
+ */
 export function generateSpecularPrefilterMipLevels(source, options = {}) {
-    return generateRgba8EnvironmentMipLevels(source, {
-        levels: options.levels,
-        blurRadius: options.blurRadius ?? 2
+    validateSource(source);
+    const maxLevels = maxMipLevels(source.width, source.height);
+    const requestedLevels = options.levels ?? maxLevels;
+    if (!Number.isInteger(requestedLevels) || requestedLevels < 1) {
+        throw new RangeError("Environment specular prefilter levels must be a positive integer");
+    }
+    const sampleCount = options.sampleCount ?? 64;
+    if (!Number.isInteger(sampleCount) || sampleCount <= 0) {
+        throw new RangeError("Environment specular prefilter sampleCount must be a positive integer");
+    }
+    const levelCount = Math.min(requestedLevels, maxLevels);
+    const linear = decodeRgba8EnvironmentToLinear(source, "srgb");
+    const prefiltered = prefilterGgxEnvironmentLevels(linear, { levels: levelCount, sampleCount });
+    return prefiltered.map((level, index) => {
+        if (index === 0) {
+            // Roughness 0 is a mirror reflection, so level 0 is the unfiltered
+            // source. Copy the bytes instead of round-tripping through sRGB to keep
+            // it bit-exact.
+            return { width: source.width, height: source.height, data: new Uint8Array(source.data) };
+        }
+        const data = new Uint8Array(level.width * level.height * 4);
+        for (let index2 = 0; index2 < level.width * level.height; index2 += 1) {
+            const offset = index2 * 4;
+            data[offset] = encodeColorByte(clamp(level.data[offset] ?? 0, 0, 1), "srgb");
+            data[offset + 1] = encodeColorByte(clamp(level.data[offset + 1] ?? 0, 0, 1), "srgb");
+            data[offset + 2] = encodeColorByte(clamp(level.data[offset + 2] ?? 0, 0, 1), "srgb");
+            data[offset + 3] = 255;
+        }
+        return { width: level.width, height: level.height, data };
     });
 }
+/**
+ * Roughness each specular prefilter level was genuinely filtered for. Callers
+ * must use this rather than deriving roughness from a mip index they did not
+ * generate.
+ */
+export { specularPrefilterLevelRoughness } from "./SpecularPrefilter.js";
 export function generateRgbeEnvironmentMipLevels(source, options = {}) {
     validateHdrSource(source);
     const maxLevels = maxMipLevels(source.width, source.height);
@@ -133,6 +180,32 @@ export function generateRgbeEnvironmentMipLevels(source, options = {}) {
     }
     return levels;
 }
+/**
+ * Real GGX specular prefilter for HDR environments, encoded as RGBE per level.
+ * `generateRgbeEnvironmentMipLevels` remains available for plain mip pyramids,
+ * but it is a progressive box downsample and must not be labelled as
+ * roughness-prefiltered.
+ */
+export function generateRgbeSpecularPrefilterMipLevels(source, options = {}) {
+    validateHdrSource(source);
+    const maxLevels = maxMipLevels(source.width, source.height);
+    const requestedLevels = options.levels ?? maxLevels;
+    if (!Number.isInteger(requestedLevels) || requestedLevels < 1) {
+        throw new RangeError("Environment RGBe specular prefilter levels must be a positive integer");
+    }
+    const sampleCount = options.sampleCount ?? 32;
+    if (!Number.isInteger(sampleCount) || sampleCount <= 0) {
+        throw new RangeError("Environment RGBe specular prefilter sampleCount must be a positive integer");
+    }
+    return prefilterGgxEnvironmentLevels(source, {
+        levels: Math.min(requestedLevels, maxLevels),
+        sampleCount
+    }).map((level) => encodeLinearHdrEnvironmentToRgbe({
+        width: level.width,
+        height: level.height,
+        data: level.data
+    }));
+}
 export function generateRgba16fEnvironmentMipLevels(source, options = {}) {
     validateHdrSource(source);
     const maxLevels = maxMipLevels(source.width, source.height);
@@ -169,19 +242,12 @@ export function generateRgba16fSpecularPrefilterMipLevels(source, options = {})
         throw new RangeError("Environment RGBA16F specular prefilter sampleCount must be a positive integer");
     }
     const mipCount = Math.min(requestedLevels, maxLevels);
-    const levels = [
-        encodeLinearHdrEnvironmentToRgba16f({
-            width: source.width,
-            height: source.height,
-            data: new Float32Array(source.data)
-        })
-    ];
-    for (let mipIndex = 1; mipIndex < mipCount; mipIndex += 1) {
-        const roughness = clamp(mipIndex / Math.max(1, mipCount - 1), 0, 1);
-        const effectiveSamples = Math.max(8, Math.round(sampleCount * lerp(0.5, 1, roughness)));
-        const level = prefilterLinearHdrEnvironmentLevel(source, mipIndex, roughness, effectiveSamples);
-        levels.push(encodeLinearHdrEnvironmentToRgba16f(level));
-    }
+    const prefiltered = prefilterGgxEnvironmentLevels(source, { levels: mipCount, sampleCount });
+    const levels = prefiltered.map((level) => encodeLinearHdrEnvironmentToRgba16f({
+        width: level.width,
+        height: level.height,
+        data: level.data
+    }));
     if (levels.length > 1) {
         const diffuseLevel = levels[levels.length - 1];
         levels[levels.length - 1] = generateRgba16fDiffuseIrradianceMipLevel(source, {
@@ -217,6 +283,18 @@ export function generateRgba16fDiffuseIrradianceMipLevel(source, options = {}) {
     }
     return encodeLinearHdrEnvironmentToRgba16f({ width, height, data });
 }
+/**
+ * Cosine-convolved diffuse irradiance for RGBA8 environments.
+ *
+ * This previously averaged a square box of source texels, which is not a cosine
+ * convolution: it ignores the hemisphere orientation entirely, so two opposite
+ * normals sampled from nearby texels received nearly identical "irradiance".
+ * The environment is now decoded to linear, projected onto nine irradiance SH
+ * bands with per-texel solid angle weights, and evaluated per output direction.
+ *
+ * `blurRadius` is retained for call-site compatibility and no longer affects
+ * the result.
+ */
 export function generateDiffuseIrradianceRgba8(source, options = {}) {
     validateSource(source);
     const width = options.width ?? Math.min(16, source.width);
@@ -228,21 +306,21 @@ export function generateDiffuseIrradianceRgba8(source, options = {}) {
     if (!Number.isInteger(blurRadius) || blurRadius < 0) {
         throw new RangeError("Environment diffuse irradiance blurRadius must be a non-negative integer");
     }
+    const irradiance = convolveEnvironmentIrradiance(decodeRgba8EnvironmentToLinear(source, "srgb"), width, height);
     const data = new Uint8Array(width * height * 4);
-    for (let y = 0; y < height; y += 1) {
-        for (let x = 0; x < width; x += 1) {
-            const sourceX = Math.round((x / Math.max(1, width - 1)) * (source.width - 1));
-            const sourceY = Math.round((y / Math.max(1, height - 1)) * (source.height - 1));
-            const color = sampleBox(source, sourceX, sourceY, blurRadius);
-            const index = (y * width + x) * 4;
-            data[index] = color[0];
-            data[index + 1] = color[1];
-            data[index + 2] = color[2];
-            data[index + 3] = color[3];
-        }
+    for (let index = 0; index < width * height; index += 1) {
+        const offset = index * 4;
+        data[offset] = encodeColorByte(clamp(irradiance.data[offset] ?? 0, 0, 1), "srgb");
+        data[offset + 1] = encodeColorByte(clamp(irradiance.data[offset + 1] ?? 0, 0, 1), "srgb");
+        data[offset + 2] = encodeColorByte(clamp(irradiance.data[offset + 2] ?? 0, 0, 1), "srgb");
+        data[offset + 3] = 255;
     }
     return { width, height, data };
 }
+/**
+ * Cosine-convolved diffuse irradiance for HDR environments, encoded as RGBE.
+ * Replaces the previous box average for the same reason as the RGBA8 path.
+ */
 export function generateDiffuseIrradianceRgbe(source, options = {}) {
     validateHdrSource(source);
     const width = options.width ?? Math.min(16, source.width);
@@ -254,14 +332,11 @@ export function generateDiffuseIrradianceRgbe(source, options = {}) {
     if (!Number.isInteger(blurRadius) || blurRadius < 0) {
         throw new RangeError("Environment diffuse irradiance blurRadius must be a non-negative integer");
     }
+    const irradiance = convolveEnvironmentIrradiance(source, width, height);
     const data = new Uint8Array(width * height * 4);
-    for (let y = 0; y < height; y += 1) {
-        for (let x = 0; x < width; x += 1) {
-            const sourceX = Math.round((x / Math.max(1, width - 1)) * (source.width - 1));
-            const sourceY = Math.round((y / Math.max(1, height - 1)) * (source.height - 1));
-            const color = sampleLinearHdrBox(source, sourceX, sourceY, blurRadius);
-            encodeLinearRgbePixel(color[0], color[1], color[2], color[3], data, (y * width + x) * 4);
-        }
+    for (let index = 0; index < width * height; index += 1) {
+        const offset = index * 4;
+        encodeLinearRgbePixel(irradiance.data[offset] ?? 0, irradiance.data[offset + 1] ?? 0, irradiance.data[offset + 2] ?? 0, 1, data, offset);
     }
     return { width, height, data };
 }
@@ -281,13 +356,13 @@ export function createEnvironmentMapResourceSet(input, options = {}) {
             outputColorSpace: textureEncoding === "rgba8-linear" ? "linear" : "srgb"
         });
     const specularMipLevels = textureEncoding === "rgbe"
-        ? generateRgbeEnvironmentMipLevels(linearForTexture, {
+        ? generateRgbeSpecularPrefilterMipLevels(linearForTexture, {
             levels: options.specularLevels,
-            blurRadius: options.specularBlurRadius ?? 2
+            ...(options.specularSampleCount === undefined ? {} : { sampleCount: options.specularSampleCount })
         })
         : generateSpecularPrefilterMipLevels(base, {
             levels: options.specularLevels,
-            blurRadius: options.specularBlurRadius ?? 2
+            ...(options.specularSampleCount === undefined ? {} : { sampleCount: options.specularSampleCount })
         });
     const diffuseIrradiance = textureEncoding === "rgbe"
         ? generateDiffuseIrradianceRgbe(linearForTexture, {
@@ -317,11 +392,25 @@ export function createEnvironmentMapResourceSet(input, options = {}) {
             hdrSource: inputEncoding === "rgbe" || inputEncoding === "linear-hdr",
             maxLinearValue: Number(maxLinearValue(linear).toFixed(6)),
             specularMipCount: specularMipLevels.length,
+            specularLevelRoughness: specularPrefilterLevelRoughness(specularMipLevels.length),
+            specularFilterModel: "ggx-importance-sampled-equirect-prefilter",
+            diffuseIrradianceModel: "sh9-cosine-convolved",
             diffuseIrradianceSize: [diffuseIrradiance.width, diffuseIrradiance.height],
             brdfLutSize: [brdfLut.width, brdfLut.height]
         }
     };
 }
+/**
+ * Generates the deterministic GGX split-sum DFG lookup texture used by the
+ * environment-lighting shaders. The historical `Approximate` export name is
+ * retained for API compatibility; each texel is numerically integrated rather
+ * than evaluated from an analytic fit.
+ *
+ * The red channel stores the coefficient multiplied by F0 and the green
+ * channel stores the grazing-angle Fresnel bias:
+ *
+ * `environmentSpecular * (F0 * red + green)`
+ */
 export function generateApproximateBrdfLutPixels(descriptor = {}) {
     const width = descriptor.width ?? 32;
     const height = descriptor.height ?? 32;
@@ -337,7 +426,7 @@ export function generateApproximateBrdfLutPixels(descriptor = {}) {
         const roughness = clamp(y / Math.max(1, height - 1), 0, 1);
         for (let x = 0; x < width; x += 1) {
             const nDotV = clamp(x / Math.max(1, width - 1), 0.001, 1);
-            const brdf = integrateGgxEnvironmentBrdf(nDotV, roughness, sampleCount);
+            const brdf = integrateSplitSumGgxEnvironmentBrdf(nDotV, roughness, sampleCount);
             const index = (y * width + x) * 4;
             data[index] = encodeColorByte(brdf[0], "linear");
             data[index + 1] = encodeColorByte(brdf[1], "linear");
@@ -347,7 +436,7 @@ export function generateApproximateBrdfLutPixels(descriptor = {}) {
     }
     return { width, height, data };
 }
-function integrateGgxEnvironmentBrdf(nDotV, roughness, sampleCount) {
+function integrateSplitSumGgxEnvironmentBrdf(nDotV, roughness, sampleCount) {
     const view = [
         Math.sqrt(Math.max(0, 1 - nDotV * nDotV)),
         0,
@@ -369,7 +458,12 @@ function integrateGgxEnvironmentBrdf(nDotV, roughness, sampleCount) {
         if (nDotL <= 0 || nDotH <= 0 || vDotH <= 0) {
             continue;
         }
-        const visibility = ggxGeometrySmithCorrelated(nDotV, nDotL, roughness) * vDotH / Math.max(nDotH * nDotV, A3D_EPSILON_NUMBER);
+        // Split-sum weight for GGX-importance-sampled half vectors. The GGX pdf is
+        // D * nDotH / (4 * vDotH), so the estimator for the specular integral
+        // D * V * nDotL reduces to 4 * V * nDotL * vDotH / nDotH. Dropping the
+        // 4 * nDotL factor (or dividing by nDotV instead) produces values far above
+        // 1 that clamp to white and destroy split-sum energy conservation.
+        const visibility = 4 * ggxGeometrySmithCorrelated(nDotV, nDotL, roughness) * nDotL * vDotH / Math.max(nDotH, A3D_EPSILON_NUMBER);
         const fresnel = Math.pow(1 - vDotH, 5);
         scale += (1 - fresnel) * visibility;
         bias += fresnel * visibility;
@@ -392,7 +486,11 @@ function radicalInverseVdc(bits) {
     return value * 2.3283064365386963e-10;
 }
 function importanceSampleGgx(xi, roughness) {
-    const alpha = Math.max(roughness, 0.001) * Math.max(roughness, 0.001);
+    // Match the minimum perceptual roughness used by the PBR shader's GGX
+    // distribution. Using a narrower proposal than the evaluated lobe biases the
+    // first LUT row even though the runtime shader clamps that row to this value.
+    const clampedRoughness = Math.max(roughness, A3D_MIN_PBR_ROUGHNESS);
+    const alpha = clampedRoughness * clampedRoughness;
     const alpha2 = alpha * alpha;
     const phi = 2 * Math.PI * xi[0];
     const cosTheta = Math.sqrt((1 - xi[1]) / Math.max(1 + (alpha2 - 1) * xi[1], A3D_EPSILON_NUMBER));
@@ -404,7 +502,7 @@ function importanceSampleGgx(xi, roughness) {
     ];
 }
 function ggxGeometrySmithCorrelated(nDotV, nDotL, roughness) {
-    const alpha = Math.max(roughness, 0.045);
+    const alpha = Math.max(roughness, A3D_MIN_PBR_ROUGHNESS);
     const alpha2 = alpha * alpha * alpha * alpha;
     const lambdaV = nDotL * Math.sqrt(Math.max((nDotV - alpha2 * nDotV) * nDotV + alpha2, A3D_EPSILON_NUMBER));
     const lambdaL = nDotV * Math.sqrt(Math.max((nDotL - alpha2 * nDotL) * nDotL + alpha2, A3D_EPSILON_NUMBER));
@@ -451,64 +549,6 @@ function downsampleLinearHdrEnvironmentLevel(source, blurRadius) {
     }
     return { width, height, data };
 }
-function prefilterLinearHdrEnvironmentLevel(source, mipIndex, roughness, sampleCount) {
-    const width = Math.max(1, Math.floor(source.width / 2 ** mipIndex));
-    const height = Math.max(1, Math.floor(source.height / 2 ** mipIndex));
-    const data = new Float32Array(width * height * 4);
-    for (let y = 0; y < height; y += 1) {
-        for (let x = 0; x < width; x += 1) {
-            const direction = equirectPixelDirection(x, y, width, height);
-            const color = prefilterLinearHdrEnvironmentDirection(source, direction, roughness, sampleCount);
-            const index = (y * width + x) * 4;
-            data[index] = color[0];
-            data[index + 1] = color[1];
-            data[index + 2] = color[2];
-            data[index + 3] = color[3];
-        }
-    }
-    return { width, height, data };
-}
-function prefilterLinearHdrEnvironmentDirection(source, reflectionDirection, roughness, sampleCount) {
-    if (roughness <= A3D_EPSILON_NUMBER) {
-        return sampleLinearHdrEquirect(source, reflectionDirection);
-    }
-    const normal = reflectionDirection;
-    const view = reflectionDirection;
-    let red = 0;
-    let green = 0;
-    let blue = 0;
-    let alpha = 0;
-    let totalWeight = 0;
-    for (let sampleIndex = 0; sampleIndex < sampleCount; sampleIndex += 1) {
-        const xi = hammersley2d(sampleIndex, sampleCount);
-        const halfVector = tangentToWorld(importanceSampleGgx(xi, roughness), normal);
-        const vDotH = Math.max(dot3(view, halfVector), 0);
-        const light = normalize3([
-            2 * vDotH * halfVector[0] - view[0],
-            2 * vDotH * halfVector[1] - view[1],
-            2 * vDotH * halfVector[2] - view[2]
-        ]);
-        const nDotL = Math.max(dot3(normal, light), 0);
-        if (nDotL <= A3D_EPSILON_NUMBER) {
-            continue;
-        }
-        const sample = sampleLinearHdrEquirect(source, light);
-        red += sample[0] * nDotL;
-        green += sample[1] * nDotL;
-        blue += sample[2] * nDotL;
-        alpha += sample[3] * nDotL;
-        totalWeight += nDotL;
-    }
-    if (totalWeight <= A3D_EPSILON_NUMBER) {
-        return sampleLinearHdrEquirect(source, reflectionDirection);
-    }
-    return [
-        red / totalWeight,
-        green / totalWeight,
-        blue / totalWeight,
-        alpha / totalWeight
-    ];
-}
 function integrateDiffuseIrradianceOverHemisphere(source, normal, sampleCount) {
     let red = 0;
     let green = 0;