@plasius/gpu-lighting 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -20,19 +20,22 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
-## [0.2.4] - 2026-06-14
+## [0.2.5] - 2026-06-15
 
 - **Added**
-  - (placeholder)
+  - Added concrete volumetric WGSL kernels for `volumetricShadow` and
+    `froxelIntegrate`, covering froxel shadow history plus scattering/extinction
+    integration for the published realtime and reference profiles.
+  - Added concrete HDRI/IBL WGSL kernels for `irradianceConvolution`,
+    `specularPrefilter`, and `brdfLut`.
 
 - **Changed**
-  - (placeholder)
+  - README now documents the delivered volumetrics and HDRI kernel scope with
+    technique-level descriptions instead of leaving those exported jobs implied.
 
 - **Fixed**
-  - (placeholder)
-
-- **Security**
-  - (placeholder)
+  - Package tests now fail if any exported `hybrid`, `volumetrics`, or `hdri`
+    job regresses to placeholder text or an empty/no-op `process_job` body.
 
 ## [0.2.2] - 2026-06-11
 
@@ -461,7 +464,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 [0.1.16]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.16
 [0.1.17]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.17
 [0.1.19]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.1.19
-[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/gpu-lighting/compare/v0.2.5...HEAD
 [0.2.0]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.0
 [0.2.2]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.2
-[0.2.4]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.4
+[0.2.5]: https://github.com/Plasius-LTD/gpu-lighting/releases/tag/v0.2.5

package/README.md

@@ -325,6 +325,11 @@ The package now ships concrete WGSL contracts for:
 - `hybrid.screenTrace`: first-hit reflection tracing over the shared hybrid scene contracts
 - `hybrid.radianceCache`: irradiance history updates for cache-backed indirect reuse
 - `hybrid.finalGather`: cache + trace composition with temporal reuse for the hybrid GI path
+- `volumetrics.volumetricShadow`: slice-aware Beer-Lambert shadow history for fog and shafts
+- `volumetrics.froxelIntegrate`: froxel scattering/extinction integration with temporal stability
+- `hdri.irradianceConvolution`: cosine-weighted diffuse environment convolution
+- `hdri.specularPrefilter`: roughness-aware environment prefiltering for glossy IBL
+- `hdri.brdfLut`: split-sum BRDF LUT integration for image-based lighting
 - `pathtracer.pathTrace`: analytic scene tracing, bounce integration, and sky fallback
 - `pathtracer.accumulate`: progressive history resolve with reset handling
 - `pathtracer.denoise`: spatial-temporal bilateral filtering for reference previews
@@ -354,12 +359,12 @@ graph.
   - `accumulate`
   - `denoise`
 - `volumetrics`
-  - `froxelIntegrate`
-  - `volumetricShadow`
+  - `froxelIntegrate`: accumulates participating-media scattering/extinction per froxel
+  - `volumetricShadow`: resolves directional shadow transmittance history per froxel
 - `hdri`
-  - `irradianceConvolution`
-  - `specularPrefilter`
-  - `brdfLut`
+  - `irradianceConvolution`: builds diffuse irradiance from the environment source
+  - `specularPrefilter`: builds roughness-aware glossy environment mip data
+  - `brdfLut`: integrates the split-sum BRDF lookup surface for IBL
 
 ## Demo
 

package/dist/techniques/techniques/hdri/brdf-lut.job.wgsl

@@ -1,3 +1,71 @@
-fn process_job() {
-  // Placeholder BRDF LUT generation stage.
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read_write> hdriBrdfLutOutput: array<vec4<f32>>;
+
+fn lut_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn lut_index(pixel: vec2<u32>) -> u32 {
+  let extent = lut_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn saturate(value: f32) -> f32 {
+  return clamp(value, 0.0, 1.0);
+}
+
+fn geometry_schlick_ggx(ndotv: f32, roughness: f32) -> f32 {
+  let alpha = max(roughness * roughness, 0.001);
+  let k = (alpha + 1.0) * (alpha + 1.0) / 8.0;
+  return ndotv / max(ndotv * (1.0 - k) + k, 0.001);
+}
+
+fn geometry_smith(ndotv: f32, ndotl: f32, roughness: f32) -> f32 {
+  return geometry_schlick_ggx(ndotv, roughness) * geometry_schlick_ggx(ndotl, roughness);
+}
+
+fn fresnel_schlick(cos_theta: f32) -> f32 {
+  return pow(1.0 - saturate(cos_theta), 5.0);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = lut_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let uv = (vec2<f32>(global_id.xy) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let ndotv = saturate(uv.x);
+  let roughness = clamp_roughness(uv.y + iblPrecomputeParams.roughness * 0.15);
+  let sample_total = max(iblPrecomputeParams.sample_count, 1u);
+  var integrated_brdf = vec2<f32>(0.0);
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= sample_total) {
+      break;
+    }
+
+    let sample_u = (f32(sample_index) + 0.5) / f32(sample_total);
+    let sample_v = fract(f32(sample_index) * 0.61803398875);
+    let ndotl = saturate(sqrt(sample_u));
+    let vdoth = saturate(mix(ndotv, 1.0, sample_v));
+    let geometry = geometry_smith(ndotv, ndotl, roughness);
+    let fresnel = fresnel_schlick(vdoth);
+    integrated_brdf = integrated_brdf + vec2<f32>(
+      (1.0 - fresnel) * geometry,
+      fresnel * geometry
+    );
+
+    sample_index = sample_index + 1u;
+  }
+
+  integrated_brdf =
+    integrated_brdf / f32(sample_total) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriBrdfLutOutput[lut_index(global_id.xy)] = vec4<f32>(
+    integrated_brdf.x,
+    integrated_brdf.y,
+    roughness,
+    ndotv
+  );
 }

package/dist/techniques/techniques/hdri/irradiance-convolution.job.wgsl

@@ -1,3 +1,92 @@
-fn process_job() {
-  // Placeholder irradiance convolution stage.
+struct HdriConvolutionSample {
+  direction_radiance: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read> hdriEnvironmentInput: array<HdriConvolutionSample>;
+@group(0) @binding(2) var<storage, read_write> hdriIrradianceOutput: array<vec4<f32>>;
+
+fn face_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn face_pixel_index(pixel: vec2<u32>) -> u32 {
+  let extent = face_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn direction_from_texel(pixel: vec2<u32>, extent: u32) -> vec3<f32> {
+  let uv = (vec2<f32>(pixel) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let phi = (uv.x * 2.0 - 1.0) * 3.141592653589793;
+  let theta = uv.y * 3.141592653589793;
+  let sin_theta = sin(theta);
+  return safe_normalize(
+    vec3<f32>(
+      cos(phi) * sin_theta,
+      cos(theta),
+      sin(phi) * sin_theta
+    )
+  );
+}
+
+fn direction_to_index(direction: vec3<f32>, extent: u32) -> u32 {
+  let dir = safe_normalize(direction);
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = fract(phi / (2.0 * 3.141592653589793) + 0.5);
+  let v = clamp(theta / 3.141592653589793, 0.0, 0.999999);
+  let pixel = vec2<u32>(
+    min(u32(floor(u * f32(extent))), extent - 1u),
+    min(u32(floor(v * f32(extent))), extent - 1u)
+  );
+  return face_pixel_index(pixel);
+}
+
+fn sample_environment(direction: vec3<f32>) -> vec3<f32> {
+  let index = direction_to_index(direction, face_extent());
+  return hdriEnvironmentInput[index].direction_radiance.xyz;
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = face_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let normal = direction_from_texel(global_id.xy, extent);
+  var accumulated_irradiance = vec3<f32>(0.0);
+  var total_weight = 0.0;
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= extent) {
+      break;
+    }
+
+    let sample_pixel = vec2<u32>(
+      (global_id.x + sample_index) % extent,
+      (global_id.y + sample_index * 3u) % extent
+    );
+    let sample_direction = direction_from_texel(sample_pixel, extent);
+    let cosine_weight = max(dot(normal, sample_direction), 0.0);
+    if (cosine_weight > 0.0) {
+      accumulated_irradiance =
+        accumulated_irradiance + sample_environment(sample_direction) * cosine_weight;
+      total_weight = total_weight + cosine_weight;
+    }
+
+    sample_index = sample_index + 1u;
+  }
+
+  let irradiance =
+    accumulated_irradiance / max(total_weight, 0.0001) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriIrradianceOutput[face_pixel_index(global_id.xy)] = vec4<f32>(irradiance, 1.0);
 }

package/dist/techniques/techniques/hdri/specular-prefilter.job.wgsl

@@ -1,3 +1,111 @@
-fn process_job() {
-  // Placeholder specular prefilter stage.
+struct HdriSpecularSample {
+  direction_radiance: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read> hdriEnvironmentInput: array<HdriSpecularSample>;
+@group(0) @binding(2) var<storage, read_write> hdriSpecularOutput: array<vec4<f32>>;
+
+fn face_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn face_pixel_index(pixel: vec2<u32>) -> u32 {
+  let extent = face_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn direction_from_texel(pixel: vec2<u32>, extent: u32) -> vec3<f32> {
+  let uv = (vec2<f32>(pixel) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let phi = (uv.x * 2.0 - 1.0) * 3.141592653589793;
+  let theta = uv.y * 3.141592653589793;
+  let sin_theta = sin(theta);
+  return safe_normalize(
+    vec3<f32>(
+      cos(phi) * sin_theta,
+      cos(theta),
+      sin(phi) * sin_theta
+    )
+  );
+}
+
+fn direction_to_index(direction: vec3<f32>, extent: u32) -> u32 {
+  let dir = safe_normalize(direction);
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = fract(phi / (2.0 * 3.141592653589793) + 0.5);
+  let v = clamp(theta / 3.141592653589793, 0.0, 0.999999);
+  let pixel = vec2<u32>(
+    min(u32(floor(u * f32(extent))), extent - 1u),
+    min(u32(floor(v * f32(extent))), extent - 1u)
+  );
+  return face_pixel_index(pixel);
+}
+
+fn sample_environment(direction: vec3<f32>) -> vec3<f32> {
+  let index = direction_to_index(direction, face_extent());
+  return hdriEnvironmentInput[index].direction_radiance.xyz;
+}
+
+fn importance_sample_hemisphere(normal: vec3<f32>, xi: vec2<f32>, roughness: f32) -> vec3<f32> {
+  let phi = 2.0 * 3.141592653589793 * xi.x;
+  let alpha = max(roughness * roughness, 0.001);
+  let cos_theta = sqrt((1.0 - xi.y) / max(1.0 + (alpha * alpha - 1.0) * xi.y, 0.001));
+  let sin_theta = sqrt(max(1.0 - cos_theta * cos_theta, 0.0));
+  let tangent_seed = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(normal.y) > 0.9);
+  let tangent = safe_normalize(cross(tangent_seed, normal));
+  let bitangent = cross(normal, tangent);
+  return safe_normalize(
+    tangent * cos(phi) * sin_theta +
+    bitangent * sin(phi) * sin_theta +
+    normal * cos_theta
+  );
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = face_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let normal = direction_from_texel(global_id.xy, extent);
+  let view_direction = normal;
+  let roughness = clamp_roughness(iblPrecomputeParams.roughness);
+  var prefiltered_radiance = vec3<f32>(0.0);
+  var importance_weight = 0.0;
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= extent) {
+      break;
+    }
+
+    let xi = vec2<f32>(
+      (f32(sample_index) + 0.5) / f32(extent),
+      fract((f32(sample_index) * 0.7548776662466927) + (f32(global_id.x) + f32(global_id.y)) * 0.01)
+    );
+    let half_vector = importance_sample_hemisphere(normal, xi, roughness);
+    let sample_direction = reflect(-view_direction, half_vector);
+    let ndotl = max(dot(normal, sample_direction), 0.0);
+    if (ndotl > 0.0) {
+      let weight = mix(ndotl, pow(ndotl, 1.0 / max(roughness + 0.05, 0.05)), roughness);
+      prefiltered_radiance =
+        prefiltered_radiance + sample_environment(sample_direction) * weight;
+      importance_weight = importance_weight + weight;
+    }
+
+    sample_index = sample_index + 1u;
+  }
+
+  let resolved_radiance =
+    prefiltered_radiance / max(importance_weight, 0.0001) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriSpecularOutput[face_pixel_index(global_id.xy)] = vec4<f32>(resolved_radiance, roughness);
 }

package/dist/techniques/techniques/volumetrics/froxel-integrate.job.wgsl

@@ -1,3 +1,106 @@
-fn process_job() {
-  // Placeholder froxel integration stage for volumetric lighting.
+struct VolumetricIntegrationParams {
+  light_direction: vec3<f32>,
+  history_blend: f32,
+  extinction_bias: f32,
+  ambient_boost: f32,
+  integration_step_scale: f32,
+  phase_bias: f32,
+  temporal_stability: f32,
+  reserved: f32,
+};
+
+struct FroxelMediumVoxel {
+  extinction_density: vec4<f32>,
+  inscattering_anisotropy: vec4<f32>,
+};
+
+struct VolumetricShadowHistory {
+  shadow_transmittance: vec4<f32>,
+  depth_phase: vec4<f32>,
+};
+
+struct FroxelIntegratedVoxel {
+  integrated_scattering: vec4<f32>,
+  integrated_extinction: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> froxelGridParams: FroxelGridParams;
+@group(0) @binding(1) var<uniform> volumetricIntegrationParams: VolumetricIntegrationParams;
+@group(0) @binding(2) var<storage, read> froxelMediumInput: array<FroxelMediumVoxel>;
+@group(0) @binding(3) var<storage, read> froxelShadowInput: array<VolumetricShadowHistory>;
+@group(0) @binding(4) var<storage, read_write> froxelIntegratedOutput: array<FroxelIntegratedVoxel>;
+
+fn froxel_integrate_index(coord: vec3<u32>) -> u32 {
+  let plane = max(froxelGridParams.grid_width, 1u) * max(froxelGridParams.grid_height, 1u);
+  return coord.z * plane + coord.y * max(froxelGridParams.grid_width, 1u) + coord.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn henyey_greenstein(cos_theta: f32, anisotropy: f32) -> f32 {
+  let g = clamp(anisotropy, -0.85, 0.85);
+  let denominator = pow(max(1.0 + g * g - 2.0 * g * cos_theta, 0.001), 1.5);
+  return (1.0 - g * g) / max(12.566370614359172 * denominator, 0.001);
+}
+
+@compute @workgroup_size(4, 4, 4)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  if (
+    global_id.x >= froxelGridParams.grid_width ||
+    global_id.y >= froxelGridParams.grid_height ||
+    global_id.z >= froxelGridParams.grid_depth
+  ) {
+    return;
+  }
+
+  let index = froxel_integrate_index(global_id);
+  let medium = froxelMediumInput[index];
+  let shadow = froxelShadowInput[index];
+  let previous = froxelIntegratedOutput[index];
+  let light_direction = safe_normalize(volumetricIntegrationParams.light_direction);
+  let slice_depth = (f32(global_id.z) + 0.5) / max(f32(froxelGridParams.grid_depth), 1.0);
+  let density = max(medium.extinction_density.w + volumetricIntegrationParams.extinction_bias, 0.0);
+  let extinction = max(medium.extinction_density.xyz, vec3<f32>(0.0001));
+  let albedo = clamp(medium.inscattering_anisotropy.xyz, vec3<f32>(0.0), vec3<f32>(4.0));
+  let anisotropy = medium.inscattering_anisotropy.w;
+  let phase = henyey_greenstein(light_direction.y, anisotropy + volumetricIntegrationParams.phase_bias * 0.1);
+  let step_length =
+    max(volumetricIntegrationParams.integration_step_scale, 0.2) /
+    max(f32(froxelGridParams.grid_depth), 1.0);
+  let shadow_visibility = shadow.shadow_transmittance.w;
+  let ambient_term = vec3<f32>(0.08, 0.1, 0.14) * max(volumetricIntegrationParams.ambient_boost, 0.0);
+  let sample = MediumSample(
+    extinction,
+    (albedo * (0.25 + slice_depth * 0.5) + ambient_term) * shadow_visibility * phase
+  );
+  let transmittance = exp(-sample.extinction * density * step_length);
+  let integrated_scattering =
+    sample.inscattering *
+    froxelGridParams.scattering_strength *
+    (1.0 - transmittance) *
+    (1.0 + shadow.depth_phase.z * 0.2);
+  let integrated_extinction = sample.extinction * density * step_length;
+  let stability = clamp(
+    shadow.depth_phase.w * volumetricIntegrationParams.temporal_stability,
+    0.0,
+    1.0
+  );
+  let blend = clamp(volumetricIntegrationParams.history_blend, 0.0, 0.98) * stability;
+  let resolved_scattering =
+    previous.integrated_scattering.xyz * blend +
+    integrated_scattering * (1.0 - blend);
+  let resolved_extinction =
+    previous.integrated_extinction.xyz * blend +
+    integrated_extinction * (1.0 - blend);
+
+  froxelIntegratedOutput[index] = FroxelIntegratedVoxel(
+    vec4<f32>(resolved_scattering, shadow_visibility),
+    vec4<f32>(resolved_extinction, stability)
+  );
 }

package/dist/techniques/techniques/volumetrics/volumetric-shadow.job.wgsl

@@ -1,3 +1,97 @@
-fn process_job() {
-  // Placeholder volumetric shadow resolve stage.
+struct VolumetricLightParams {
+  light_direction: vec3<f32>,
+  history_blend: f32,
+  light_color: vec3<f32>,
+  shadow_strength: f32,
+  slice_depth_scale: f32,
+  density_bias: f32,
+  phase_bias: f32,
+  jitter_amount: f32,
+};
+
+struct FroxelMediumVoxel {
+  extinction_density: vec4<f32>,
+  inscattering_anisotropy: vec4<f32>,
+};
+
+struct VolumetricShadowHistory {
+  shadow_transmittance: vec4<f32>,
+  depth_phase: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> froxelGridParams: FroxelGridParams;
+@group(0) @binding(1) var<uniform> volumetricLightParams: VolumetricLightParams;
+@group(0) @binding(2) var<storage, read> froxelMediumInput: array<FroxelMediumVoxel>;
+@group(0) @binding(3) var<storage, read> froxelShadowHistory: array<VolumetricShadowHistory>;
+@group(0) @binding(4) var<storage, read_write> froxelShadowOutput: array<VolumetricShadowHistory>;
+
+fn froxel_shadow_index(coord: vec3<u32>) -> u32 {
+  let plane = max(froxelGridParams.grid_width, 1u) * max(froxelGridParams.grid_height, 1u);
+  return coord.z * plane + coord.y * max(froxelGridParams.grid_width, 1u) + coord.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn henyey_greenstein(cos_theta: f32, anisotropy: f32) -> f32 {
+  let g = clamp(anisotropy, -0.85, 0.85);
+  let denominator = pow(max(1.0 + g * g - 2.0 * g * cos_theta, 0.001), 1.5);
+  return (1.0 - g * g) / max(12.566370614359172 * denominator, 0.001);
+}
+
+@compute @workgroup_size(4, 4, 4)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  if (
+    global_id.x >= froxelGridParams.grid_width ||
+    global_id.y >= froxelGridParams.grid_height ||
+    global_id.z >= froxelGridParams.grid_depth
+  ) {
+    return;
+  }
+
+  let index = froxel_shadow_index(global_id);
+  let medium = froxelMediumInput[index];
+  let previous = froxelShadowHistory[index];
+  let light_direction = safe_normalize(volumetricLightParams.light_direction);
+  let slice_depth = (f32(global_id.z) + 0.5) / max(f32(froxelGridParams.grid_depth), 1.0);
+  let density = max(medium.extinction_density.w + volumetricLightParams.density_bias, 0.0);
+  let extinction = max(dot(medium.extinction_density.xyz, vec3<f32>(0.2126, 0.7152, 0.0722)), 0.0001);
+  let anisotropy = medium.inscattering_anisotropy.w;
+  let phase_weight = henyey_greenstein(light_direction.y, anisotropy);
+  let depth_scale = max(volumetricLightParams.slice_depth_scale, 0.25);
+  let shadow_distance = depth_scale * mix(0.35, 1.35, slice_depth);
+  let optical_depth = (density * 0.7 + extinction * 0.3) * shadow_distance;
+  let raw_transmittance = exp(-optical_depth);
+  let horizon_wrap = 0.35 + 0.65 * saturate(light_direction.y * 0.5 + 0.5);
+  let jitter = fract(
+    f32(global_id.x * 19u + global_id.y * 47u + global_id.z * 73u) * 0.61803398875
+  );
+  let visibility = clamp(
+    raw_transmittance * horizon_wrap * (1.0 - volumetricLightParams.jitter_amount * (jitter - 0.5)),
+    0.0,
+    1.0
+  );
+  let history_visibility = previous.shadow_transmittance.w;
+  let blend = clamp(volumetricLightParams.history_blend, 0.0, 0.98);
+  let shadow_transmittance = mix(visibility, history_visibility, blend);
+  let light_radiance =
+    volumetricLightParams.light_color *
+    shadow_transmittance *
+    max(volumetricLightParams.shadow_strength, 0.0) *
+    (0.55 + phase_weight * 0.45);
+  let depth_confidence = clamp(
+    slice_depth * 0.45 + shadow_transmittance * 0.35 + (1.0 - density) * 0.2,
+    0.0,
+    1.0
+  );
+
+  froxelShadowOutput[index] = VolumetricShadowHistory(
+    vec4<f32>(light_radiance, shadow_transmittance),
+    vec4<f32>(slice_depth, optical_depth, phase_weight, depth_confidence)
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-lighting",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Advanced lighting WGSL modules and planning profiles for @plasius/gpu-worker.",
   "type": "module",
   "sideEffects": false,

package/src/techniques/hdri/brdf-lut.job.wgsl

@@ -1,3 +1,71 @@
-fn process_job() {
-  // Placeholder BRDF LUT generation stage.
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read_write> hdriBrdfLutOutput: array<vec4<f32>>;
+
+fn lut_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn lut_index(pixel: vec2<u32>) -> u32 {
+  let extent = lut_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn saturate(value: f32) -> f32 {
+  return clamp(value, 0.0, 1.0);
+}
+
+fn geometry_schlick_ggx(ndotv: f32, roughness: f32) -> f32 {
+  let alpha = max(roughness * roughness, 0.001);
+  let k = (alpha + 1.0) * (alpha + 1.0) / 8.0;
+  return ndotv / max(ndotv * (1.0 - k) + k, 0.001);
+}
+
+fn geometry_smith(ndotv: f32, ndotl: f32, roughness: f32) -> f32 {
+  return geometry_schlick_ggx(ndotv, roughness) * geometry_schlick_ggx(ndotl, roughness);
+}
+
+fn fresnel_schlick(cos_theta: f32) -> f32 {
+  return pow(1.0 - saturate(cos_theta), 5.0);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = lut_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let uv = (vec2<f32>(global_id.xy) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let ndotv = saturate(uv.x);
+  let roughness = clamp_roughness(uv.y + iblPrecomputeParams.roughness * 0.15);
+  let sample_total = max(iblPrecomputeParams.sample_count, 1u);
+  var integrated_brdf = vec2<f32>(0.0);
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= sample_total) {
+      break;
+    }
+
+    let sample_u = (f32(sample_index) + 0.5) / f32(sample_total);
+    let sample_v = fract(f32(sample_index) * 0.61803398875);
+    let ndotl = saturate(sqrt(sample_u));
+    let vdoth = saturate(mix(ndotv, 1.0, sample_v));
+    let geometry = geometry_smith(ndotv, ndotl, roughness);
+    let fresnel = fresnel_schlick(vdoth);
+    integrated_brdf = integrated_brdf + vec2<f32>(
+      (1.0 - fresnel) * geometry,
+      fresnel * geometry
+    );
+
+    sample_index = sample_index + 1u;
+  }
+
+  integrated_brdf =
+    integrated_brdf / f32(sample_total) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriBrdfLutOutput[lut_index(global_id.xy)] = vec4<f32>(
+    integrated_brdf.x,
+    integrated_brdf.y,
+    roughness,
+    ndotv
+  );
 }

package/src/techniques/hdri/irradiance-convolution.job.wgsl

@@ -1,3 +1,92 @@
-fn process_job() {
-  // Placeholder irradiance convolution stage.
+struct HdriConvolutionSample {
+  direction_radiance: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read> hdriEnvironmentInput: array<HdriConvolutionSample>;
+@group(0) @binding(2) var<storage, read_write> hdriIrradianceOutput: array<vec4<f32>>;
+
+fn face_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn face_pixel_index(pixel: vec2<u32>) -> u32 {
+  let extent = face_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn direction_from_texel(pixel: vec2<u32>, extent: u32) -> vec3<f32> {
+  let uv = (vec2<f32>(pixel) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let phi = (uv.x * 2.0 - 1.0) * 3.141592653589793;
+  let theta = uv.y * 3.141592653589793;
+  let sin_theta = sin(theta);
+  return safe_normalize(
+    vec3<f32>(
+      cos(phi) * sin_theta,
+      cos(theta),
+      sin(phi) * sin_theta
+    )
+  );
+}
+
+fn direction_to_index(direction: vec3<f32>, extent: u32) -> u32 {
+  let dir = safe_normalize(direction);
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = fract(phi / (2.0 * 3.141592653589793) + 0.5);
+  let v = clamp(theta / 3.141592653589793, 0.0, 0.999999);
+  let pixel = vec2<u32>(
+    min(u32(floor(u * f32(extent))), extent - 1u),
+    min(u32(floor(v * f32(extent))), extent - 1u)
+  );
+  return face_pixel_index(pixel);
+}
+
+fn sample_environment(direction: vec3<f32>) -> vec3<f32> {
+  let index = direction_to_index(direction, face_extent());
+  return hdriEnvironmentInput[index].direction_radiance.xyz;
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = face_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let normal = direction_from_texel(global_id.xy, extent);
+  var accumulated_irradiance = vec3<f32>(0.0);
+  var total_weight = 0.0;
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= extent) {
+      break;
+    }
+
+    let sample_pixel = vec2<u32>(
+      (global_id.x + sample_index) % extent,
+      (global_id.y + sample_index * 3u) % extent
+    );
+    let sample_direction = direction_from_texel(sample_pixel, extent);
+    let cosine_weight = max(dot(normal, sample_direction), 0.0);
+    if (cosine_weight > 0.0) {
+      accumulated_irradiance =
+        accumulated_irradiance + sample_environment(sample_direction) * cosine_weight;
+      total_weight = total_weight + cosine_weight;
+    }
+
+    sample_index = sample_index + 1u;
+  }
+
+  let irradiance =
+    accumulated_irradiance / max(total_weight, 0.0001) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriIrradianceOutput[face_pixel_index(global_id.xy)] = vec4<f32>(irradiance, 1.0);
 }

package/src/techniques/hdri/specular-prefilter.job.wgsl

@@ -1,3 +1,111 @@
-fn process_job() {
-  // Placeholder specular prefilter stage.
+struct HdriSpecularSample {
+  direction_radiance: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> iblPrecomputeParams: IblPrecomputeParams;
+@group(0) @binding(1) var<storage, read> hdriEnvironmentInput: array<HdriSpecularSample>;
+@group(0) @binding(2) var<storage, read_write> hdriSpecularOutput: array<vec4<f32>>;
+
+fn face_extent() -> u32 {
+  return max(iblPrecomputeParams.sample_count, 1u);
+}
+
+fn face_pixel_index(pixel: vec2<u32>) -> u32 {
+  let extent = face_extent();
+  return pixel.y * extent + pixel.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn direction_from_texel(pixel: vec2<u32>, extent: u32) -> vec3<f32> {
+  let uv = (vec2<f32>(pixel) + vec2<f32>(0.5)) / max(vec2<f32>(f32(extent)), vec2<f32>(1.0));
+  let phi = (uv.x * 2.0 - 1.0) * 3.141592653589793;
+  let theta = uv.y * 3.141592653589793;
+  let sin_theta = sin(theta);
+  return safe_normalize(
+    vec3<f32>(
+      cos(phi) * sin_theta,
+      cos(theta),
+      sin(phi) * sin_theta
+    )
+  );
+}
+
+fn direction_to_index(direction: vec3<f32>, extent: u32) -> u32 {
+  let dir = safe_normalize(direction);
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = fract(phi / (2.0 * 3.141592653589793) + 0.5);
+  let v = clamp(theta / 3.141592653589793, 0.0, 0.999999);
+  let pixel = vec2<u32>(
+    min(u32(floor(u * f32(extent))), extent - 1u),
+    min(u32(floor(v * f32(extent))), extent - 1u)
+  );
+  return face_pixel_index(pixel);
+}
+
+fn sample_environment(direction: vec3<f32>) -> vec3<f32> {
+  let index = direction_to_index(direction, face_extent());
+  return hdriEnvironmentInput[index].direction_radiance.xyz;
+}
+
+fn importance_sample_hemisphere(normal: vec3<f32>, xi: vec2<f32>, roughness: f32) -> vec3<f32> {
+  let phi = 2.0 * 3.141592653589793 * xi.x;
+  let alpha = max(roughness * roughness, 0.001);
+  let cos_theta = sqrt((1.0 - xi.y) / max(1.0 + (alpha * alpha - 1.0) * xi.y, 0.001));
+  let sin_theta = sqrt(max(1.0 - cos_theta * cos_theta, 0.0));
+  let tangent_seed = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(normal.y) > 0.9);
+  let tangent = safe_normalize(cross(tangent_seed, normal));
+  let bitangent = cross(normal, tangent);
+  return safe_normalize(
+    tangent * cos(phi) * sin_theta +
+    bitangent * sin(phi) * sin_theta +
+    normal * cos_theta
+  );
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let extent = face_extent();
+  if (global_id.x >= extent || global_id.y >= extent) {
+    return;
+  }
+
+  let normal = direction_from_texel(global_id.xy, extent);
+  let view_direction = normal;
+  let roughness = clamp_roughness(iblPrecomputeParams.roughness);
+  var prefiltered_radiance = vec3<f32>(0.0);
+  var importance_weight = 0.0;
+  var sample_index = 0u;
+  loop {
+    if (sample_index >= extent) {
+      break;
+    }
+
+    let xi = vec2<f32>(
+      (f32(sample_index) + 0.5) / f32(extent),
+      fract((f32(sample_index) * 0.7548776662466927) + (f32(global_id.x) + f32(global_id.y)) * 0.01)
+    );
+    let half_vector = importance_sample_hemisphere(normal, xi, roughness);
+    let sample_direction = reflect(-view_direction, half_vector);
+    let ndotl = max(dot(normal, sample_direction), 0.0);
+    if (ndotl > 0.0) {
+      let weight = mix(ndotl, pow(ndotl, 1.0 / max(roughness + 0.05, 0.05)), roughness);
+      prefiltered_radiance =
+        prefiltered_radiance + sample_environment(sample_direction) * weight;
+      importance_weight = importance_weight + weight;
+    }
+
+    sample_index = sample_index + 1u;
+  }
+
+  let resolved_radiance =
+    prefiltered_radiance / max(importance_weight, 0.0001) * max(iblPrecomputeParams.exposure_bias, 0.0001);
+  hdriSpecularOutput[face_pixel_index(global_id.xy)] = vec4<f32>(resolved_radiance, roughness);
 }

package/src/techniques/volumetrics/froxel-integrate.job.wgsl

@@ -1,3 +1,106 @@
-fn process_job() {
-  // Placeholder froxel integration stage for volumetric lighting.
+struct VolumetricIntegrationParams {
+  light_direction: vec3<f32>,
+  history_blend: f32,
+  extinction_bias: f32,
+  ambient_boost: f32,
+  integration_step_scale: f32,
+  phase_bias: f32,
+  temporal_stability: f32,
+  reserved: f32,
+};
+
+struct FroxelMediumVoxel {
+  extinction_density: vec4<f32>,
+  inscattering_anisotropy: vec4<f32>,
+};
+
+struct VolumetricShadowHistory {
+  shadow_transmittance: vec4<f32>,
+  depth_phase: vec4<f32>,
+};
+
+struct FroxelIntegratedVoxel {
+  integrated_scattering: vec4<f32>,
+  integrated_extinction: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> froxelGridParams: FroxelGridParams;
+@group(0) @binding(1) var<uniform> volumetricIntegrationParams: VolumetricIntegrationParams;
+@group(0) @binding(2) var<storage, read> froxelMediumInput: array<FroxelMediumVoxel>;
+@group(0) @binding(3) var<storage, read> froxelShadowInput: array<VolumetricShadowHistory>;
+@group(0) @binding(4) var<storage, read_write> froxelIntegratedOutput: array<FroxelIntegratedVoxel>;
+
+fn froxel_integrate_index(coord: vec3<u32>) -> u32 {
+  let plane = max(froxelGridParams.grid_width, 1u) * max(froxelGridParams.grid_height, 1u);
+  return coord.z * plane + coord.y * max(froxelGridParams.grid_width, 1u) + coord.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn henyey_greenstein(cos_theta: f32, anisotropy: f32) -> f32 {
+  let g = clamp(anisotropy, -0.85, 0.85);
+  let denominator = pow(max(1.0 + g * g - 2.0 * g * cos_theta, 0.001), 1.5);
+  return (1.0 - g * g) / max(12.566370614359172 * denominator, 0.001);
+}
+
+@compute @workgroup_size(4, 4, 4)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  if (
+    global_id.x >= froxelGridParams.grid_width ||
+    global_id.y >= froxelGridParams.grid_height ||
+    global_id.z >= froxelGridParams.grid_depth
+  ) {
+    return;
+  }
+
+  let index = froxel_integrate_index(global_id);
+  let medium = froxelMediumInput[index];
+  let shadow = froxelShadowInput[index];
+  let previous = froxelIntegratedOutput[index];
+  let light_direction = safe_normalize(volumetricIntegrationParams.light_direction);
+  let slice_depth = (f32(global_id.z) + 0.5) / max(f32(froxelGridParams.grid_depth), 1.0);
+  let density = max(medium.extinction_density.w + volumetricIntegrationParams.extinction_bias, 0.0);
+  let extinction = max(medium.extinction_density.xyz, vec3<f32>(0.0001));
+  let albedo = clamp(medium.inscattering_anisotropy.xyz, vec3<f32>(0.0), vec3<f32>(4.0));
+  let anisotropy = medium.inscattering_anisotropy.w;
+  let phase = henyey_greenstein(light_direction.y, anisotropy + volumetricIntegrationParams.phase_bias * 0.1);
+  let step_length =
+    max(volumetricIntegrationParams.integration_step_scale, 0.2) /
+    max(f32(froxelGridParams.grid_depth), 1.0);
+  let shadow_visibility = shadow.shadow_transmittance.w;
+  let ambient_term = vec3<f32>(0.08, 0.1, 0.14) * max(volumetricIntegrationParams.ambient_boost, 0.0);
+  let sample = MediumSample(
+    extinction,
+    (albedo * (0.25 + slice_depth * 0.5) + ambient_term) * shadow_visibility * phase
+  );
+  let transmittance = exp(-sample.extinction * density * step_length);
+  let integrated_scattering =
+    sample.inscattering *
+    froxelGridParams.scattering_strength *
+    (1.0 - transmittance) *
+    (1.0 + shadow.depth_phase.z * 0.2);
+  let integrated_extinction = sample.extinction * density * step_length;
+  let stability = clamp(
+    shadow.depth_phase.w * volumetricIntegrationParams.temporal_stability,
+    0.0,
+    1.0
+  );
+  let blend = clamp(volumetricIntegrationParams.history_blend, 0.0, 0.98) * stability;
+  let resolved_scattering =
+    previous.integrated_scattering.xyz * blend +
+    integrated_scattering * (1.0 - blend);
+  let resolved_extinction =
+    previous.integrated_extinction.xyz * blend +
+    integrated_extinction * (1.0 - blend);
+
+  froxelIntegratedOutput[index] = FroxelIntegratedVoxel(
+    vec4<f32>(resolved_scattering, shadow_visibility),
+    vec4<f32>(resolved_extinction, stability)
+  );
 }

package/src/techniques/volumetrics/volumetric-shadow.job.wgsl

@@ -1,3 +1,97 @@
-fn process_job() {
-  // Placeholder volumetric shadow resolve stage.
+struct VolumetricLightParams {
+  light_direction: vec3<f32>,
+  history_blend: f32,
+  light_color: vec3<f32>,
+  shadow_strength: f32,
+  slice_depth_scale: f32,
+  density_bias: f32,
+  phase_bias: f32,
+  jitter_amount: f32,
+};
+
+struct FroxelMediumVoxel {
+  extinction_density: vec4<f32>,
+  inscattering_anisotropy: vec4<f32>,
+};
+
+struct VolumetricShadowHistory {
+  shadow_transmittance: vec4<f32>,
+  depth_phase: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> froxelGridParams: FroxelGridParams;
+@group(0) @binding(1) var<uniform> volumetricLightParams: VolumetricLightParams;
+@group(0) @binding(2) var<storage, read> froxelMediumInput: array<FroxelMediumVoxel>;
+@group(0) @binding(3) var<storage, read> froxelShadowHistory: array<VolumetricShadowHistory>;
+@group(0) @binding(4) var<storage, read_write> froxelShadowOutput: array<VolumetricShadowHistory>;
+
+fn froxel_shadow_index(coord: vec3<u32>) -> u32 {
+  let plane = max(froxelGridParams.grid_width, 1u) * max(froxelGridParams.grid_height, 1u);
+  return coord.z * plane + coord.y * max(froxelGridParams.grid_width, 1u) + coord.x;
+}
+
+fn safe_normalize(value: vec3<f32>) -> vec3<f32> {
+  let length_value = length(value);
+  if (length_value <= 0.000001) {
+    return vec3<f32>(0.0, 1.0, 0.0);
+  }
+  return value / length_value;
+}
+
+fn henyey_greenstein(cos_theta: f32, anisotropy: f32) -> f32 {
+  let g = clamp(anisotropy, -0.85, 0.85);
+  let denominator = pow(max(1.0 + g * g - 2.0 * g * cos_theta, 0.001), 1.5);
+  return (1.0 - g * g) / max(12.566370614359172 * denominator, 0.001);
+}
+
+@compute @workgroup_size(4, 4, 4)
+fn process_job(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  if (
+    global_id.x >= froxelGridParams.grid_width ||
+    global_id.y >= froxelGridParams.grid_height ||
+    global_id.z >= froxelGridParams.grid_depth
+  ) {
+    return;
+  }
+
+  let index = froxel_shadow_index(global_id);
+  let medium = froxelMediumInput[index];
+  let previous = froxelShadowHistory[index];
+  let light_direction = safe_normalize(volumetricLightParams.light_direction);
+  let slice_depth = (f32(global_id.z) + 0.5) / max(f32(froxelGridParams.grid_depth), 1.0);
+  let density = max(medium.extinction_density.w + volumetricLightParams.density_bias, 0.0);
+  let extinction = max(dot(medium.extinction_density.xyz, vec3<f32>(0.2126, 0.7152, 0.0722)), 0.0001);
+  let anisotropy = medium.inscattering_anisotropy.w;
+  let phase_weight = henyey_greenstein(light_direction.y, anisotropy);
+  let depth_scale = max(volumetricLightParams.slice_depth_scale, 0.25);
+  let shadow_distance = depth_scale * mix(0.35, 1.35, slice_depth);
+  let optical_depth = (density * 0.7 + extinction * 0.3) * shadow_distance;
+  let raw_transmittance = exp(-optical_depth);
+  let horizon_wrap = 0.35 + 0.65 * saturate(light_direction.y * 0.5 + 0.5);
+  let jitter = fract(
+    f32(global_id.x * 19u + global_id.y * 47u + global_id.z * 73u) * 0.61803398875
+  );
+  let visibility = clamp(
+    raw_transmittance * horizon_wrap * (1.0 - volumetricLightParams.jitter_amount * (jitter - 0.5)),
+    0.0,
+    1.0
+  );
+  let history_visibility = previous.shadow_transmittance.w;
+  let blend = clamp(volumetricLightParams.history_blend, 0.0, 0.98);
+  let shadow_transmittance = mix(visibility, history_visibility, blend);
+  let light_radiance =
+    volumetricLightParams.light_color *
+    shadow_transmittance *
+    max(volumetricLightParams.shadow_strength, 0.0) *
+    (0.55 + phase_weight * 0.45);
+  let depth_confidence = clamp(
+    slice_depth * 0.45 + shadow_transmittance * 0.35 + (1.0 - density) * 0.2,
+    0.0,
+    1.0
+  );
+
+  froxelShadowOutput[index] = VolumetricShadowHistory(
+    vec4<f32>(light_radiance, shadow_transmittance),
+    vec4<f32>(slice_depth, optical_depth, phase_weight, depth_confidence)
+  );
 }