@forgeax/engine-shader 0.1.2

package/src/hdrp-deferred-lighting.wgsl

@@ -0,0 +1,69 @@
+#define_import_path forgeax_view::hdrp_deferred_lighting
+
+#import forgeax_view::common::FullscreenOutput
+#import forgeax_view::common::{View, FogViewParams, FogRay}
+#import forgeax_view::common::fullscreen_triangle
+#import forgeax_view::fog::{apply_fog}
+
+// HDRP deferred lighting producer. The lighting pass consumes the material
+// G-buffer and current-frame depth, reconstructs the fragment world position,
+// then applies the shared analytic Fog exactly once to linear radiance.
+
+@group(0) @binding(0) var<uniform> view : View;
+
+@group(1) @binding(0) var gbufferAlbedo : texture_2d<f32>;
+@group(1) @binding(1) var gbufferSampler : sampler;
+@group(1) @binding(2) var<uniform> deferredParams : vec4<f32>;
+@group(1) @binding(3) var sceneDepth : texture_depth_2d;
+@group(1) @binding(4) var depthSampler : sampler;
+@group(1) @binding(5) var gbufferNormal : texture_2d<f32>;
+@group(1) @binding(6) var gbufferEmissive : texture_2d<f32>;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+fn reconstructWorldPosition(uv : vec2<f32>, depth : f32) -> vec3<f32> {
+  let clip = vec4<f32>(uv * 2.0 - vec2<f32>(1.0), depth, 1.0);
+  let worldH = view.inverseViewProj * clip;
+  return worldH.xyz / worldH.w;
+}
+
+fn fogDeferredRadiance(color : vec4<f32>, worldPos : vec3<f32>) -> vec4<f32> {
+  var origin = view.cameraPos;
+  var direction = normalize(worldPos - origin);
+  var rayDistance = length(worldPos - origin);
+  if (view.temporalProjection.z >= 0.5) {
+    let nearH = view.inverseViewProj * vec4<f32>(0.0, 0.0, 0.0, 1.0);
+    let farH = view.inverseViewProj * vec4<f32>(0.0, 0.0, 1.0, 1.0);
+    let nearPoint = nearH.xyz / nearH.w;
+    let farPoint = farH.xyz / farH.w;
+    direction = normalize(farPoint - nearPoint);
+    origin = worldPos - direction * dot(worldPos - view.cameraPos, direction);
+    rayDistance = max(dot(worldPos - origin, direction), 0.0);
+  }
+  return apply_fog(view.fog, FogRay(origin, direction, rayDistance), color);
+}
+
+@fragment
+fn fs_lighting(in : FullscreenOutput) -> @location(0) vec4<f32> {
+  // The lighting pass runs before the forward lane and shares its cleared
+  // scene target. A far-depth sample is an empty G-buffer pixel; discard it
+  // so deferred lighting preserves the existing clear/background contract.
+  // Writing a synthetic material value here would cover forward-only scenes
+  // (and change the HDRP baseline even when no deferred material is present).
+  let depth = textureSampleLevel(sceneDepth, depthSampler, in.uv, 0);
+  if (depth >= 0.999999) {
+    discard;
+  }
+  let material = textureSampleLevel(gbufferAlbedo, gbufferSampler, in.uv, 0);
+  let normalSample = textureSampleLevel(gbufferNormal, gbufferSampler, in.uv, 0);
+  let emissiveSample = textureSampleLevel(gbufferEmissive, gbufferSampler, in.uv, 0);
+  let normal = normalize(normalSample.xyz * 2.0 - vec3<f32>(1.0));
+  let light = max(dot(normal, normalize(-view.lightDir)), 0.0);
+  let direct = material.rgb * view.lightColor * light * clamp(emissiveSample.a, 0.0, 1.0);
+  let radiance = vec4<f32>(direct + emissiveSample.rgb, material.a);
+  let worldPos = reconstructWorldPosition(in.uv, depth);
+  return fogDeferredRadiance(radiance, worldPos);
+}

package/src/hdrp-ssao.wgsl

@@ -0,0 +1,174 @@
+// hdrp-ssao.wgsl — HDRP Screen-Space Ambient Occlusion.
+// feat-20260612-hdrp-ssao M2 / w8.
+//
+// Two fullscreen fragment passes following LO 5.9:
+//   fs_ssao_calc — 64-sample hemisphere SSAO with range check, writes R8 scalar.
+//   fs_ssao_blur — 4x4 box blur (16 tap), reads ssaoRaw, writes R8 scalar.
+//
+// plan-strategy D-1: SSAO owns its uniform group (@group(2)) with view +
+//   projection + inverseProjection (3 mat4, 192 B UBO). Does NOT read View UBO.
+// plan-strategy D-2: exactly 2 pass, no H/V split.
+// requirements OOS-3: 4x4 box blur only; no depth-aware/bilateral.
+// requirements OOS-4: no depth-reconstruction path for normals; reads normal from
+//   g-buffer RT0 (packed world-space normal, 0.5*n+0.5 in rgba16f).
+//
+// BGL layout (@group(0), SSAO-dedicated; w37 expansion for D-A/D-D + dawn fix):
+//   @binding(0) var<uniform> ssao_uniform : SsaoUniform   (256 B UBO)
+//   @binding(1) var<uniform> ssao_kernel : array<vec4<f32>,64>  (1024 B UBO)
+//   @binding(2) var ssao_noise_texture : texture_2d<f32>  (4x4 rgba32float)
+//   @binding(3) var ssao_noise_sampler : sampler          (filtering, for noise tile)
+//   @binding(4) var gbuffer_normal : texture_2d<f32>      (RT0, packed world normal)
+//   @binding(5) var hdr_depth : texture_depth_2d          (hardware depth)
+//   @binding(6) var ssao_depth_sampler : sampler          (non-filtering, for hdr_depth)
+//   @binding(7) var ssaoRaw : texture_2d<f32>             (half-res calc output, blur input)
+//   @binding(8) var ssaoSampler : sampler                 (filtering, for ssaoRaw)
+//
+// Sampler split (w37 dawn-blocker fix): WebGPU validation requires depth
+// textures (sampleType=depth) to be sampled with non-filtering or comparison
+// samplers, not filtering. Pre-w37 the BGL had a single `filtering` sampler at
+// binding 3 paired with hdr_depth at binding 5, which crashed every HDRP PSO
+// build on dawn. ssao_depth_sampler at binding 6 is the non-filtering sampler
+// dedicated to hdr_depth; ssao_noise_sampler at binding 3 stays filtering for
+// the float noise/normal textures.
+//
+// fs_ssao_calc: reads g-buffer normal + hdrDepth, writes half-res R8.
+// fs_ssao_blur: reads ssaoRaw (half-res R8), writes half-res R8 (D-D fix:
+//   pre-w37 blur erroneously read gbuffer_normal — copy-paste typo from
+//   fs_ssao_calc).
+//
+// Vertex stage: both passes use fullscreen_triangle from common.wgsl.
+//
+// Research F1-F6 (LO 5.9 GLSL -> WGSL translation), KB ref:
+//   .forgeax-harness/knowledge-base/references/repos/learnopengl/src/5.advanced_lighting/9.ssao/
+
+#define_import_path forgeax_hdrp::ssao
+
+#import forgeax_view::common::{fullscreen_triangle, FullscreenOutput}
+
+// ── SSAO uniform (3 mat4 + vec4 intensityPad, 256 B, D-1 + D-C) ─────────────
+//
+// intensityPad carries the lighting intensity plus the calc radius/bias.
+// The lighting shader reads intensity from `cluster_uniform.near_far_log.w`
+// (HDRP unified BGL @group(2) @binding(6)); the calc shader reads radius and
+// bias here. Keeping the values in this existing vec4 preserves the one-shot
+// 256 B UBO write and avoids a second parameter binding.
+
+struct SsaoUniform {
+  view              : mat4x4<f32>,  // world -> view
+  projection        : mat4x4<f32>,  // view -> clip
+  inverseProjection : mat4x4<f32>,  // NDC -> view
+  intensityPad      : vec4<f32>,    // x = intensity, y = radius, z = bias
+};
+
+// ── SSAO binding declarations (@group(2)) ───────────────────────────────────
+
+@group(0) @binding(0) var<uniform> ssao_uniform      : SsaoUniform;
+@group(0) @binding(1) var<uniform> ssao_kernel  : array<vec4<f32>, 64>;
+@group(0) @binding(2) var ssao_noise_texture          : texture_2d<f32>;
+@group(0) @binding(3) var ssao_noise_sampler          : sampler;
+@group(0) @binding(4) var gbuffer_normal              : texture_2d<f32>;
+@group(0) @binding(5) var hdr_depth                   : texture_depth_2d;
+@group(0) @binding(6) var ssao_depth_sampler          : sampler;
+@group(0) @binding(7) var ssaoRaw                     : texture_2d<f32>;
+@group(0) @binding(8) var ssaoSampler                 : sampler;
+
+// ── vertex: fullscreen triangle (SSOT in common.wgsl) ───────────────────────
+
+struct SsaoVsOut {
+  @builtin(position) position : vec4<f32>,
+  @location(0) uv             : vec2<f32>,
+};
+
+@vertex
+fn vs_ssao(@builtin(vertex_index) vertex_index : u32) -> SsaoVsOut {
+  let ft = fullscreen_triangle(vertex_index);
+  var out : SsaoVsOut;
+  out.position = ft.position;
+  out.uv = ft.uv;
+  return out;
+}
+
+// ── fs_ssao_calc: 64-sample hemisphere SSAO (LO 5.9) ────────────────────────
+
+@fragment
+fn fs_ssao_calc(in : SsaoVsOut) -> @location(0) f32 {
+  // Reconstruct view-space position from depth + NDC.
+  let depth = textureSampleLevel(hdr_depth, ssao_depth_sampler, in.uv, 0);
+  // NDC reconstruction: screen-space xy in [-1,1], depth in [0,1].
+  let ndc = vec4<f32>(in.uv * 2.0 - 1.0, depth, 1.0);
+  // Transform NDC -> view via inverse projection.
+  var viewPosH = ssao_uniform.inverseProjection * ndc;
+  viewPosH = viewPosH / viewPosH.w;
+  let viewPos = viewPosH.xyz;
+
+  // Read and unpack world-space normal from g-buffer RT0.
+  let packedNormal = textureSample(gbuffer_normal, ssao_noise_sampler, in.uv).rgb;
+  let worldNormal = normalize(packedNormal * 2.0 - 1.0);
+
+  // Rotate world normal to view-space.
+  let viewNormal = normalize((ssao_uniform.view * vec4<f32>(worldNormal, 0.0)).xyz);
+
+  // Read noise for per-pixel TBN rotation.
+  let noiseScale = vec2<f32>(textureDimensions(ssao_noise_texture, 0)) / 4.0;
+  // Actually: scale factor is screenDim / noiseDim. Use a fixed factor for half-res.
+  // The noise texture is 4x4 and tiled via REPEAT sampling.
+  let screenDim = vec2<f32>(textureDimensions(gbuffer_normal, 0));
+  let noiseUV = in.uv * screenDim / 4.0;
+  let randomVec = normalize(textureSample(ssao_noise_texture, ssao_noise_sampler, noiseUV).xyz);
+
+  // TBN: Gram-Schmidt orthonormalization (tangent-space -> view-space).
+  let tangent = normalize(randomVec - viewNormal * dot(randomVec, viewNormal));
+  let bitangent = cross(viewNormal, tangent);
+  let TBN = mat3x3<f32>(tangent, bitangent, viewNormal);
+
+  // SSAO parameters are install-time config values projected by the host.
+  let radius = ssao_uniform.intensityPad.y;
+  let bias = ssao_uniform.intensityPad.z;
+
+  var occlusion = 0.0;
+  for (var i = 0u; i < 64u; i = i + 1u) {
+    // Tangent-space sample -> view-space via TBN.
+    let sampleTangent = ssao_kernel[i].xyz;
+    var sampleView = TBN * sampleTangent;
+    sampleView = viewPos + sampleView * radius;
+
+    // Project sample to screen.
+    var offset = ssao_uniform.projection * vec4<f32>(sampleView, 1.0);
+    offset = offset / offset.w;
+    offset = offset * 0.5 + 0.5;
+
+    // Sample depth at the projected screen location.
+    let sampleDepth = textureSampleLevel(hdr_depth, ssao_depth_sampler, offset.xy, 0);
+    // Reconstruct view-space z of the sampled fragment (at offset.xy).
+    var sampledViewPosH = ssao_uniform.inverseProjection * vec4<f32>(offset.xy * 2.0 - 1.0, sampleDepth, 1.0);
+    sampledViewPosH = sampledViewPosH / sampledViewPosH.w;
+    let sampledViewZ = sampledViewPosH.z;
+
+    // Range check: smoothstep based on distance along view-z axis.
+    let rangeCheck = smoothstep(0.0, 1.0, radius / abs(viewPos.z - sampledViewZ));
+    let sampleContrib = select(0.0, 1.0, sampledViewZ >= sampleView.z + bias);
+    occlusion += sampleContrib * rangeCheck;
+  }
+
+  occlusion = 1.0 - (occlusion / 64.0);
+  return occlusion;
+}
+
+// ── fs_ssao_blur: 4x4 box blur (LO 5.9, OOS-3) ─────────────────────────────
+
+@fragment
+fn fs_ssao_blur(in : SsaoVsOut) -> @location(0) f32 {
+  // D-D fix: blur reads ssaoRaw (half-res calc output), not gbuffer_normal.
+  // Pre-w37 the dimensions + sample texture both incorrectly named
+  // gbuffer_normal — copy-paste typo from fs_ssao_calc that produced no
+  // occlusion at all (the blur ran a 4x4 average over packed world normals).
+  let texelSize = 1.0 / vec2<f32>(textureDimensions(ssaoRaw, 0));
+  var result = 0.0;
+  for (var x = -2; x < 2; x = x + 1) {
+    for (var y = -2; y < 2; y = y + 1) {
+      let offset = vec2<f32>(f32(x), f32(y)) * texelSize;
+      result += textureSample(ssaoRaw, ssaoSampler, in.uv + offset).r;
+    }
+  }
+  return result / 16.0;
+}

package/src/ibl-brdf-lut.wgsl

@@ -0,0 +1,92 @@
+#define_import_path forgeax_pbr::ibl_brdf_lut
+
+// @forgeax/engine-shader - ibl-brdf-lut.wgsl
+// (feat-20260520-skylight-ibl-cubemap M3 / t46).
+//
+// BRDF integration LUT bake (Karis 2013 split-sum, second factor).
+// One-shot fullscreen pass into a 256x256 RG16F target. Output channels:
+//   R = sum (1 - Fc) * G * (V . H) / (N . H * N . V)
+//   G = sum     Fc  * G * (V . H) / (N . H * N . V)
+// where Fc = (1 - V . H)^5. This LUT is consumed at runtime by
+// sampleIblSpecular() in ibl-sampling.wgsl.
+//
+// Zero @group(1) bindings -- the LUT is computed entirely from screen-space
+// position + Hammersley sequence + shared math. AC-06 / plan D-10 fixes
+// BRDF_LUT_SIZE = 256u as the SSOT constant; the host (IblPipelineCache)
+// reads the same constant via a TS mirror.
+//
+// Entries: fullscreen_vs + brdfLutBake_fs.
+
+#import forgeax_pbr::ibl_shared::{hammersley, importanceSampleGGX, iblGeometrySmith}
+
+struct VsOut {
+  @builtin(position) clip: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+};
+
+// AC-06 / plan D-10: BRDF LUT resolution. Both the bake fragment and the
+// caller (IblPipelineCache.runIblPrecompute) align on this SSOT constant.
+const BRDF_LUT_SIZE: u32 = 256u;
+const BRDF_LUT_SAMPLE_COUNT: u32 = 1024u;
+
+@vertex
+fn fullscreen_vs(@builtin(vertex_index) vi: u32) -> VsOut {
+  // Fullscreen triangle covering NDC [-1,1]^2.
+  var x: f32 = -1.0;
+  var y: f32 = -1.0;
+  if (vi == 1u) {
+    x = 3.0;
+  }
+  if (vi == 2u) {
+    y = 3.0;
+  }
+  var out: VsOut;
+  out.clip = vec4<f32>(x, y, 0.0, 1.0);
+  out.worldPos = vec3<f32>(0.0); // unused
+  return out;
+}
+
+@fragment
+fn brdfLutBake_fs(@builtin(position) pos: vec4<f32>) -> @location(0) vec4<f32> {
+  // Screen-space framebuffer position maps to (NdotV, roughness) in [0, 1]^2.
+  // Caller renders a fullscreen quad at BRDF_LUT_SIZE x BRDF_LUT_SIZE viewport
+  // (256x256 per plan D-10 / AC-06). pos.x / pos.y are framebuffer pixel
+  // coordinates in [0.5, BRDF_LUT_SIZE - 0.5].
+  let denom = f32(BRDF_LUT_SIZE - 1u);
+  let NdotV = clamp(pos.x / denom, 0.0, 1.0);
+  let roughness = clamp(pos.y / denom, 0.0, 1.0);
+
+  // Reconstruct V from NdotV in canonical frame: N = (0, 0, 1).
+  let V = vec3<f32>(
+    sqrt(clamp(1.0 - NdotV * NdotV, 0.0, 1.0)),
+    0.0,
+    NdotV,
+  );
+  let N = vec3<f32>(0.0, 0.0, 1.0);
+
+  var A: f32 = 0.0;
+  var B: f32 = 0.0;
+
+  for (var i: u32 = 0u; i < BRDF_LUT_SAMPLE_COUNT; i = i + 1u) {
+    let Xi = hammersley(i, BRDF_LUT_SAMPLE_COUNT);
+    let H = importanceSampleGGX(Xi, N, roughness);
+    let L = normalize(2.0 * dot(V, H) * H - V);
+
+    let NdotL = max(L.z, 0.0);
+    if (NdotL > 0.0) {
+      let NdotH = max(H.z, 0.0);
+      let VdotH = max(dot(V, H), 0.0);
+
+      let G = iblGeometrySmith(NdotV, NdotL, roughness);
+      let GVis = (G * VdotH) / max(NdotH * NdotV, 1e-5);
+      let Fc = pow(max(1.0 - VdotH, 0.0), 5.0);
+
+      A += (1.0 - Fc) * GVis;
+      B += Fc * GVis;
+    }
+  }
+  A = A / f32(BRDF_LUT_SAMPLE_COUNT);
+  B = B / f32(BRDF_LUT_SAMPLE_COUNT);
+
+  return vec4<f32>(A, B, 0.0, 1.0);
+}

package/src/ibl-equirect-to-cube.wgsl

@@ -0,0 +1,56 @@
+#define_import_path forgeax_pbr::ibl_equirect_to_cube
+
+// @forgeax/engine-shader - ibl-equirect-to-cube.wgsl
+// (feat-20260520-skylight-ibl-cubemap M3 / t43).
+//
+// Equirectangular HDRI -> cubemap projection pass.
+// Per LearnOpenGL §6.2.1: render a unit cube from each of the 6 face views,
+// fragment shader maps the world-space direction to equirect UV and samples
+// the input HDRI texture.
+//
+// @group(0) = per-face viewProj uniform.
+// @group(1) = equirect texture_2d + sampler. NOTE: this is the ONLY ibl-*
+//             module that binds a texture_2d at @group(1); the irradiance /
+//             prefilter modules bind texture_cube at the same slot, which
+//             is why the round-1 single-file design collided.
+//
+// Entries:
+//   - cubemap_vs        (shared VS used by irradiance + prefilter as well;
+//                        each module redeclares its own copy because WGSL
+//                        modules cannot cross-import entry points)
+//   - equirectToCube_fs
+
+#import forgeax_pbr::ibl_shared::{sampleSphericalMap}
+
+struct CubemapVsIn {
+  @location(0) pos: vec3<f32>,
+};
+struct CubemapVsOut {
+  @builtin(position) clip: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+};
+
+struct CubemapFaceUniforms {
+  viewProj: mat4x4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> faceUniforms: CubemapFaceUniforms;
+
+@group(1) @binding(0) var equirectTexture: texture_2d<f32>;
+@group(1) @binding(1) var equirectSamplerS: sampler;
+
+@vertex
+fn cubemap_vs(in0: CubemapVsIn) -> CubemapVsOut {
+  var out: CubemapVsOut;
+  out.clip = faceUniforms.viewProj * vec4<f32>(in0.pos, 1.0);
+  out.worldPos = in0.pos;
+  return out;
+}
+
+@fragment
+fn equirectToCube_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
+  let dir = normalize(in0.worldPos);
+  let uv = sampleSphericalMap(dir);
+  let color = textureSample(equirectTexture, equirectSamplerS, uv);
+  return vec4<f32>(color.rgb, 1.0);
+}

package/src/ibl-irradiance.wgsl

@@ -0,0 +1,89 @@
+#define_import_path forgeax_pbr::ibl_irradiance
+
+// @forgeax/engine-shader - ibl-irradiance.wgsl
+// (feat-20260520-skylight-ibl-cubemap M3 / t44).
+//
+// Diffuse irradiance convolution. Per LearnOpenGL §6.2.2: hemisphere
+// Riemann sum (sampleDelta = 0.025) integrates the env cubemap to produce
+// the convolved irradiance cubemap consumed by sampleIblDiffuse() at
+// runtime.
+//
+// @group(0) = per-face viewProj uniform.
+// @group(1) = env cubemap (texture_cube<f32>) + sampler. This is the same
+//             slot the prefilter module uses for its env cube, BUT because
+//             round-2 keeps each ibl-* module physically separate, the WGSL
+//             (group, binding) global-uniqueness rule applies per module
+//             rather than across the family.
+//
+// Entries: cubemap_vs + irradianceConvolve_fs.
+
+#import forgeax_pbr::ibl_shared::{PI}
+
+struct CubemapVsIn {
+  @location(0) pos: vec3<f32>,
+};
+struct CubemapVsOut {
+  @builtin(position) clip: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+};
+
+struct CubemapFaceUniforms {
+  viewProj: mat4x4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> faceUniforms: CubemapFaceUniforms;
+
+@group(1) @binding(0) var envCube: texture_cube<f32>;
+@group(1) @binding(1) var envSamplerS: sampler;
+
+const IRRADIANCE_SAMPLE_DELTA: f32 = 0.025;
+
+@vertex
+fn cubemap_vs(in0: CubemapVsIn) -> CubemapVsOut {
+  var out: CubemapVsOut;
+  out.clip = faceUniforms.viewProj * vec4<f32>(in0.pos, 1.0);
+  out.worldPos = in0.pos;
+  return out;
+}
+
+@fragment
+fn irradianceConvolve_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
+  let N = normalize(in0.worldPos);
+  let up0 = select(
+    vec3<f32>(0.0, 1.0, 0.0),
+    vec3<f32>(1.0, 0.0, 0.0),
+    abs(N.y) > 0.999,
+  );
+  let right = normalize(cross(up0, N));
+  let up = normalize(cross(N, right));
+
+  var irradiance = vec3<f32>(0.0);
+  var nrSamples: f32 = 0.0;
+
+  var phi: f32 = 0.0;
+  while (phi < 2.0 * PI) {
+    var theta: f32 = 0.0;
+    while (theta < 0.5 * PI) {
+      let tangentSample = vec3<f32>(
+        sin(theta) * cos(phi),
+        sin(theta) * sin(phi),
+        cos(theta),
+      );
+      let sampleVec = tangentSample.x * right +
+                      tangentSample.y * up +
+                      tangentSample.z * N;
+
+      let sampleColor = textureSampleLevel(
+        envCube, envSamplerS, sampleVec, 0.0,
+      ).rgb;
+      irradiance += sampleColor * cos(theta) * sin(theta);
+      nrSamples += 1.0;
+      theta += IRRADIANCE_SAMPLE_DELTA;
+    }
+    phi += IRRADIANCE_SAMPLE_DELTA;
+  }
+
+  // IRRADIANCE_PAYLOAD_E_TIMES_PI: the stored payload is E * pi.
+  irradiance = PI * irradiance / max(nrSamples, 1.0);
+  return vec4<f32>(irradiance, 1.0);
+}

package/src/ibl-prefilter.wgsl

@@ -0,0 +1,101 @@
+#define_import_path forgeax_pbr::ibl_prefilter
+
+// @forgeax/engine-shader - ibl-prefilter.wgsl
+// (feat-20260520-skylight-ibl-cubemap M3 / t45).
+//
+// GGX specular prefilter pass (Karis 2013 split-sum). For each roughness
+// mip level, importance-sample the environment cubemap with SAMPLE_COUNT
+// Hammersley samples; the result is the prefiltered radiance cube
+// consumed by sampleIblSpecular() at runtime.
+//
+// @group(0) layout (dual uniform -- the (b3) compose test in the round-2
+// dawn suite exercises this ordering):
+//   binding(0) = CubemapFaceUniforms { viewProj }      (per-face)
+//   binding(1) = PrefilterUniforms   { roughness, faceSize, _pad0, _pad1 }
+// @group(1) = env cubemap + sampler. Same shape as ibl-irradiance, but
+//             physically isolated -- both bind @binding(0) to a texture_cube
+//             inside *their own* module without colliding because round-2
+//             ships each module as a separate file.
+//
+// Entries: cubemap_vs + prefilterEnv_fs.
+
+#import forgeax_pbr::ibl_shared::{PI, hammersley, importanceSampleGGX, iblDGGX}
+
+struct CubemapVsIn {
+  @location(0) pos: vec3<f32>,
+};
+struct CubemapVsOut {
+  @builtin(position) clip: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+};
+
+struct CubemapFaceUniforms {
+  viewProj: mat4x4<f32>,
+};
+
+struct PrefilterUniforms {
+  roughness: f32,
+  faceSize: f32,
+  // Keep the uniform block 16-byte aligned on WebGL2 downlevel backends.
+  _pad0: f32,
+  _pad1: f32,
+};
+
+@group(0) @binding(0) var<uniform> faceUniforms: CubemapFaceUniforms;
+@group(0) @binding(1) var<uniform> prefUniforms: PrefilterUniforms;
+
+@group(1) @binding(0) var envCube: texture_cube<f32>;
+@group(1) @binding(1) var envSamplerS: sampler;
+
+const PREFILTER_SAMPLE_COUNT: u32 = 1024u;
+
+@vertex
+fn cubemap_vs(in0: CubemapVsIn) -> CubemapVsOut {
+  var out: CubemapVsOut;
+  out.clip = faceUniforms.viewProj * vec4<f32>(in0.pos, 1.0);
+  out.worldPos = in0.pos;
+  return out;
+}
+
+@fragment
+fn prefilterEnv_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
+  let roughness = prefUniforms.roughness;
+  // V = R = N (cubemap capture from origin assumption).
+  let N = normalize(in0.worldPos);
+  let V = N;
+
+  var prefilteredColor = vec3<f32>(0.0);
+  var totalWeight: f32 = 0.0;
+
+  for (var i: u32 = 0u; i < PREFILTER_SAMPLE_COUNT; i = i + 1u) {
+    let Xi = hammersley(i, PREFILTER_SAMPLE_COUNT);
+    let H = importanceSampleGGX(Xi, N, roughness);
+    let L = normalize(2.0 * dot(V, H) * H - V);
+
+    let NdotL = max(dot(N, L), 0.0);
+    if (NdotL > 0.0) {
+      // Mip level from solid-angle PDF ratio.
+      let D0 = iblDGGX(max(dot(N, H), 0.0), roughness);
+      let NdotH0 = max(dot(N, H), 0.0);
+      let HdotV = max(dot(H, V), 0.0);
+      let pdf = D0 * NdotH0 / (4.0 * HdotV) + 0.0001;
+
+      let resolution: f32 = 512.0;
+      let saTexel = 4.0 * PI / (6.0 * resolution * resolution);
+      let saSample = 1.0 / (f32(PREFILTER_SAMPLE_COUNT) * pdf + 0.0001);
+
+      let mipLevel = select(
+        0.5 * log2(saSample / saTexel),
+        0.0,
+        roughness == 0.0,
+      );
+
+      prefilteredColor += textureSampleLevel(
+        envCube, envSamplerS, L, mipLevel,
+      ).rgb * NdotL;
+      totalWeight += NdotL;
+    }
+  }
+  prefilteredColor = prefilteredColor / max(totalWeight, 0.001);
+  return vec4<f32>(prefilteredColor, 1.0);
+}

package/src/ibl-sampling.wgsl

@@ -0,0 +1,58 @@
+#define_import_path forgeax_pbr::ibl_sampling
+
+// @forgeax/engine-shader - ibl-sampling.wgsl
+// (feat-20260520-skylight-ibl-cubemap M3 / t47).
+//
+// Runtime IBL sampling helpers consumed by pbr.wgsl. Each helper takes the
+// texture + sampler as function arguments rather than declaring its own
+// @group/@binding, so the host (pbr.wgsl's @group(1) material BGL,
+// Skylight resources at @binding(7..13) per D-5 round-4) owns the
+// binding layout and this module composes cleanly anywhere.
+//
+// Zero @group/@binding declarations -- this is the symmetric counterpart
+// to ibl-shared.wgsl for runtime sampling code.
+//
+// Exports:
+//   - sampleIblDiffuse(N, irradianceMap, irradianceSampler)
+//   - sampleIblSpecular(N, V, roughness, F0, prefilterMap, prefilterSampler,
+//                       brdfLut, brdfLutSampler)
+
+#import forgeax_pbr::ibl_shared::{PI, fresnelSchlickRoughness, inverseRotateEnvironment}
+
+// Sample pre-convolved irradiance from the irradiance cubemap.
+// Y is negated to compensate for WebGPU's top-left texture origin vs the
+// OpenGL convention used during equirect-to-cube render passes.
+fn sampleIblDiffuse(
+  normal: vec3<f32>,
+  rotation: vec4<f32>,
+  irradianceMap: texture_cube<f32>,
+  irradianceSampler: sampler,
+) -> vec3<f32> {
+  let rotated = inverseRotateEnvironment(normal, rotation);
+  let dir = vec3<f32>(rotated.x, -rotated.y, rotated.z);
+  let irradianceEOverPi = textureSample(irradianceMap, irradianceSampler, dir).rgb;
+  return irradianceEOverPi / PI;
+}
+
+// Split-sum specular IBL: prefiltered env * (F0 * scale + bias).
+fn sampleIblSpecular(
+  normal: vec3<f32>,
+  view: vec3<f32>,
+  roughness: f32,
+  F0: vec3<f32>,
+  rotation: vec4<f32>,
+  prefilterMap: texture_cube<f32>,
+  prefilterSampler: sampler,
+  brdfLut: texture_2d<f32>,
+  brdfLutSampler: sampler,
+) -> vec3<f32> {
+  let NdotV = max(dot(normal, view), 0.001);
+  let R = reflect(-view, normal);
+  let rotated = inverseRotateEnvironment(R, rotation);
+  let Rflip = vec3<f32>(rotated.x, -rotated.y, rotated.z);
+  let mip = roughness * 4.0;
+  let prefilteredColor = textureSampleLevel(prefilterMap, prefilterSampler, Rflip, mip).rgb;
+  let envBRDF = textureSample(brdfLut, brdfLutSampler, vec2<f32>(NdotV, roughness)).rg;
+  let F = fresnelSchlickRoughness(NdotV, F0, roughness);
+  return prefilteredColor * (F * envBRDF.r + envBRDF.g);
+}