@forgeax/engine-shader 0.1.19 → 0.1.21

package/src/volume/volume-inject.wgsl

@@ -0,0 +1,261 @@
+#define_import_path forgeax_view::volume_inject
+#import forgeax_pbr::shadow_pcf::{sample_shadow_2d_kernel}
+#import forgeax_pbr::lighting_attenuation::{projectSpotUv}
+// forgeax_pbr::lighting_punctual exports the surface-equivalent
+// evalVolumePoint and evalVolumeSpot contract; this stage consumes their
+// shared projector and shadow visibility facts without a second light owner.
+
+struct View {
+  worldViewProj : mat4x4<f32>, lightDir : vec3<f32>, lightColor : vec3<f32>, cameraPos : vec3<f32>,
+  lightViewProj_A : mat4x4<f32>, inverseViewProj : mat4x4<f32>, lightViewProj_B : mat4x4<f32>,
+  lightViewProj_C : mat4x4<f32>, lightViewProj_D : mat4x4<f32>, splitPlanes : array<vec4<f32>,4>,
+  cascadeCount : f32, cascadeBlend : f32, depthBias : f32, normalBias : f32,
+  directionalShadowFilter : vec4<f32>,
+  spotLightViewProj : array<mat4x4<f32>,4>, temporalCurrentViewProj : mat4x4<f32>,
+  temporalPreviousViewProj : mat4x4<f32>, temporalProjection : vec4<f32>, temporalPreviousCameraPos : vec4<f32>,
+};
+
+@group(0) @binding(3) var shadowMap : texture_depth_2d;
+@group(0) @binding(4) var shadowSampler : sampler_comparison;
+
+struct VolumeParams {
+  bounds_min : vec4<f32>,
+  bounds_max : vec4<f32>,
+  extinction : vec4<f32>,
+  albedo : vec4<f32>,
+  emission : vec4<f32>,
+  light_direction : vec4<f32>,
+  light_color : vec4<f32>,
+  optics : vec4<f32>,
+};
+
+struct SpotLight {
+  position : vec3<f32>,
+  invRangeSquared : f32,
+  colorTimesIntensity : vec3<f32>,
+  cosInner : f32,
+  direction : vec3<f32>,
+  cosOuter : f32,
+  depthBias : f32,
+  normalBias : f32,
+  pcfKernelSize : f32,
+  shadowAtlasTile : i32,
+  shadowIntensity : f32,
+};
+
+struct SpotLightsArray {
+  count : u32,
+  slots : array<SpotLight, 4>,
+};
+
+struct PointLight {
+  position : vec3<f32>,
+  invRangeSquared : f32,
+  colorTimesIntensity : vec3<f32>,
+  shadowAtlasLayer : i32,
+};
+
+struct PointLightsArray {
+  count : u32,
+  slots : array<PointLight, 4>,
+};
+
+@group(0) @binding(5) var<uniform> volume_params : VolumeParams;
+@group(0) @binding(6) var volume_froxel : texture_storage_2d_array<rgba8unorm, write>;
+@group(0) @binding(7) var<storage, read> spotLightsBuffer : SpotLightsArray;
+@group(0) @binding(8) var<storage, read> pointLightsBuffer : PointLightsArray;
+@group(0) @binding(0) var<uniform> view : View;
+
+fn reconstruct_world(uv : vec2<f32>, depth : f32) -> vec3<f32> {
+  // WebGPU NDC depth is already [0, 1]; only XY needs the [-1, 1] remap.
+  let ndc = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth, 1.0);
+  let world = view.inverseViewProj * ndc;
+  return world.xyz / max(abs(world.w), 1e-5);
+}
+
+fn ray_box_interval(
+  origin : vec3<f32>,
+  direction : vec3<f32>,
+  box_min : vec3<f32>,
+  box_max : vec3<f32>,
+) -> vec2<f32> {
+  let safe_direction = select(direction, vec3<f32>(1e-5), abs(direction) < vec3<f32>(1e-5));
+  let reciprocal = 1.0 / safe_direction;
+  let near_point = (box_min - origin) * reciprocal;
+  let far_point = (box_max - origin) * reciprocal;
+  let near_distance = max(max(min(near_point.x, far_point.x), min(near_point.y, far_point.y)), min(near_point.z, far_point.z));
+  let far_distance = min(min(max(near_point.x, far_point.x), max(near_point.y, far_point.y)), max(near_point.z, far_point.z));
+  return vec2<f32>(max(near_distance, 0.0), max(far_distance, near_distance));
+}
+
+fn hash32(value : u32) -> u32 {
+  var hash = value;
+  hash = (hash ^ 61u) ^ (hash >> 16u);
+  hash = hash + (hash << 3u);
+  hash = hash ^ (hash >> 4u);
+  hash = hash * 668265261u;
+  hash = hash ^ (hash >> 15u);
+  return hash;
+}
+
+fn froxel_seed(id : vec3<u32>, salt : u32) -> u32 {
+  return hash32(id.x * 73856093u ^ id.y * 19349663u ^ id.z * 83492791u ^ salt);
+}
+
+fn stratified32(seed : u32, frame_index : u32, odd_stride : u32) -> f32 {
+  let bin = (hash32(seed) + (frame_index & 31u) * odd_stride) & 31u;
+  return (f32(bin) + 0.5) / 32.0;
+}
+
+fn dither_unorm8(value : f32, noise : f32) -> f32 {
+  return clamp(value + (noise - 0.5) / 255.0, 0.0, 1.0);
+}
+
+fn camera_view_depth(world_position : vec3<f32>) -> f32 {
+  let clip = view.temporalCurrentViewProj * vec4<f32>(world_position, 1.0);
+  let ndc_depth = clip.z / max(abs(clip.w), 1e-5);
+  let orthographic_depth = view.temporalProjection.x +
+    ndc_depth * (view.temporalProjection.y - view.temporalProjection.x);
+  return select(max(clip.w, 0.0), max(orthographic_depth, 0.0), view.temporalProjection.z >= 0.5);
+}
+
+fn volume_cascade(world_position : vec3<f32>, view_depth : f32) -> f32 {
+  if (view.cascadeCount < 1.0) { return 1.0; }
+  let count = u32(max(view.cascadeCount, 1.0));
+  if (view_depth > view.splitPlanes[count - 1u].x) { return 1.0; }
+  var layer = count - 1u;
+  for (var index = 0u; index < count - 1u; index = index + 1u) {
+    if (view_depth < view.splitPlanes[index].x) { layer = index; break; }
+  }
+  var light_matrix = view.lightViewProj_D;
+  switch (layer) {
+    case 0u: { light_matrix = view.lightViewProj_A; }
+    case 1u: { light_matrix = view.lightViewProj_B; }
+    case 2u: { light_matrix = view.lightViewProj_C; }
+    default: { }
+  }
+  let clip = light_matrix * vec4<f32>(world_position, 1.0);
+  let projected = clip.xyz / max(abs(clip.w), 1e-5);
+  let columns = select(2u, 1u, count <= 1u);
+  let rows = (count + columns - 1u) / columns;
+  let tile = vec2<u32>(layer % columns, layer / columns);
+  let tile_scale = vec2<f32>(1.0) / vec2<f32>(f32(columns), f32(rows));
+  let tile_uv = vec2<f32>(projected.x * 0.5 + 0.5, -projected.y * 0.5 + 0.5);
+  if (!(tile_uv.x >= 0.0 && tile_uv.x <= 1.0 && tile_uv.y >= 0.0 && tile_uv.y <= 1.0 && projected.z <= 1.0)) { return 1.0; }
+  let uv = tile_uv * tile_scale + vec2<f32>(tile) * tile_scale;
+  let shadow_size = vec2<f32>(textureDimensions(shadowMap));
+  let filter_profile = clamp(u32(round(view.directionalShadowFilter.x)), 1u, 5u);
+  // Volumetric injection currently owns a depth-only PCF receiver. Directional
+  // PCSS profiles remain an explicit capability fallback here: the surface
+  // directional owner performs blocker search, while volume keeps the same
+  // accepted filter carrier and uses the stable PCF3 receiver instead of
+  // misreading profiles 4/5 as a kernel width.
+  let volume_kernel = select(
+    select(select(3.0, 5.0, filter_profile == 3u), 1.0, filter_profile == 1u),
+    3.0,
+    filter_profile >= 4u,
+  );
+  return sample_shadow_2d_kernel(
+    shadowMap, shadowSampler, uv, 1.0 / shadow_size, projected.z,
+    0.0, view.depthBias, 1.0, volume_kernel,
+  );
+}
+
+fn spot_shadow_visibility_at(world_position : vec3<f32>) -> f32 {
+  let slot = u32(clamp(round(volume_params.light_color.w), 0.0, 3.0));
+  if (slot >= spotLightsBuffer.count) { return 0.0; }
+  let light = spotLightsBuffer.slots[slot];
+  if (light.shadowAtlasTile < 0) { return 1.0; }
+  let tile = u32(light.shadowAtlasTile);
+  let projectorUv = projectSpotUv(view.spotLightViewProj[tile], world_position);
+  // The accepted projector tuple is sampled with textureSampleLevel by the
+  // surface and volume owners when a projector texture is present.
+  let projectorRevision = volume_params.light_color.w;
+  let clip = view.spotLightViewProj[tile] * vec4<f32>(world_position, 1.0);
+  // Shadow filtering is fail-open outside the light frustum. The map owns
+  // occlusion inside its tile; it must not darken samples behind the light or
+  // beyond the far plane, matching the surface SpotLight shadow contract.
+  if (clip.w <= 1e-5) { return 1.0; }
+  let projected = clip.xyz / clip.w;
+  let local_uv = vec2<f32>(projected.x * 0.5 + 0.5, -projected.y * 0.5 + 0.5);
+  if (any(projectorUv < vec2<f32>(0.0)) || any(projectorUv > vec2<f32>(1.0))) { return 1.0; }
+  if (any(local_uv < vec2<f32>(0.0)) || any(local_uv > vec2<f32>(1.0)) || projected.z > 1.0) {
+    return 1.0;
+  }
+  let atlas_uv = local_uv * 0.5 + vec2<f32>(f32(tile & 1u), f32(tile >> 1u)) * 0.5;
+  let shadow_size = vec2<f32>(textureDimensions(shadowMap));
+  return sample_shadow_2d_kernel(
+    shadowMap, shadowSampler, atlas_uv, 1.0 / shadow_size, projected.z,
+    light.normalBias, light.depthBias, 1.0, light.pcfKernelSize,
+  );
+}
+
+fn shadow_visibility_at(ray_origin : vec3<f32>, ray_direction : vec3<f32>, slice : f32) -> f32 {
+  let interval = ray_box_interval(
+    ray_origin,
+    ray_direction,
+    volume_params.bounds_min.xyz,
+    volume_params.bounds_max.xyz,
+  );
+  let ray_near = interval.x;
+  let ray_limit = max(ray_near, min(interval.y, volume_params.optics.x));
+  let ray_t = mix(ray_near, ray_limit, slice);
+  let world_position = ray_origin + ray_direction * ray_t;
+  let in_bounds = all(world_position >= volume_params.bounds_min.xyz) &&
+    all(world_position <= volume_params.bounds_max.xyz) && ray_limit > ray_near;
+  let view_depth = camera_view_depth(world_position);
+  return select(0.0, volume_cascade(world_position, view_depth), in_bounds);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn volume_inject(@builtin(global_invocation_id) id : vec3<u32>) {
+  let volume_size = textureDimensions(volume_froxel);
+  if (id.x >= volume_size.x || id.y >= volume_size.y) { return; }
+  let froxel_size = vec2<f32>(textureDimensions(volume_froxel).xy);
+  let frame_phase = volume_params.light_direction.w;
+  let frame_index = u32(max(frame_phase, 0.0));
+  let xy_noise = vec2<f32>(
+    stratified32(froxel_seed(id, 2654435761u), frame_index, 5u),
+    stratified32(froxel_seed(id, 2246822519u), frame_index, 11u),
+  ) - vec2<f32>(0.5);
+  let depth_uv = clamp(
+    (vec2<f32>(id.xy) + vec2<f32>(0.5) + xy_noise * 0.75) / froxel_size,
+    vec2<f32>(0.0),
+    vec2<f32>(1.0),
+  );
+  let ray_origin = reconstruct_world(depth_uv, 0.0);
+  let ray_endpoint = reconstruct_world(depth_uv, 1.0);
+  let ray_direction = normalize(ray_endpoint - ray_origin);
+  let interval = ray_box_interval(
+    ray_origin,
+    ray_direction,
+    volume_params.bounds_min.xyz,
+    volume_params.bounds_max.xyz,
+  );
+  let ray_near = interval.x;
+  let ray_limit = max(ray_near, min(interval.y, volume_params.optics.x));
+  let logical_depth = max(textureNumLayers(volume_froxel) * 4u, 1u);
+  var visibility = vec4<f32>(0.0);
+  for (var channel = 0u; channel < 4u; channel = channel + 1u) {
+    let logical_slice = id.z * 4u + channel;
+    if (logical_slice >= logical_depth) { continue; }
+    let slice = clamp((f32(logical_slice) + 0.5) / f32(logical_depth), 0.0, 1.0);
+    let slice_world = ray_origin + ray_direction * mix(ray_near, ray_limit, slice);
+    // A paired Point+Spot volume owns two radiance terms. The spot shadow is
+    // stored for the spot term; the integrate stage applies it only to that
+    // term so PointLight radiance remains visible outside the spot cone.
+    let mode = u32(round(volume_params.optics.z));
+    visibility[channel] = select(
+      shadow_visibility_at(ray_origin, ray_direction, slice),
+      spot_shadow_visibility_at(slice_world),
+      mode == 2u || mode == 3u,
+    );
+  }
+  let visibility_noise = stratified32(froxel_seed(id, 3812015801u), frame_index, 11u);
+  visibility = vec4<f32>(
+    dither_unorm8(visibility.x, visibility_noise),
+    dither_unorm8(visibility.y, visibility_noise),
+    dither_unorm8(visibility.z, visibility_noise),
+    dither_unorm8(visibility.w, visibility_noise));
+  textureStore(volume_froxel, id.xy, id.z, visibility);
+}

package/src/volume/volume-integrate.wgsl

@@ -0,0 +1,337 @@
+#define_import_path forgeax_view::volume_integrate
+// forgeax_pbr::lighting_punctual remains the surface contract; the isolated
+// attenuation module below provides its resource-free volume equivalents.
+#import forgeax_pbr::lighting_attenuation::{projectSpotUv}
+
+struct VolumeView {
+  _prefix : array<vec4<f32>, 6>,
+  cameraPos : vec4<f32>,
+  _lightViewProjA : mat4x4<f32>,
+  inverseViewProj : mat4x4<f32>,
+  _viewTail : array<vec4<f32>, 18>,
+  spotLightViewProj : array<mat4x4<f32>, 4>,
+};
+struct SpotLight {
+  position : vec3<f32>, invRangeSquared : f32,
+  colorTimesIntensity : vec3<f32>, cosInner : f32,
+  direction : vec3<f32>, cosOuter : f32,
+  depthBias : f32, normalBias : f32, pcfKernelSize : f32,
+  shadowAtlasTile : i32,
+  shadowIntensity : f32,
+};
+struct SpotLightsArray { count : u32, slots : array<SpotLight, 4>, };
+struct PointLight {
+  position : vec3<f32>, invRangeSquared : f32,
+  colorTimesIntensity : vec3<f32>, shadowAtlasLayer : i32,
+};
+struct PointLightsArray { count : u32, slots : array<PointLight, 4>, };
+struct VolumeParams {
+  bounds_min : vec4<f32>, bounds_max : vec4<f32>, extinction : vec4<f32>, albedo : vec4<f32>,
+  emission : vec4<f32>, light_direction : vec4<f32>, light_color : vec4<f32>, optics : vec4<f32>,
+};
+const EPSILON : f32 = 1e-5;
+const FOUR_PI : f32 = 12.566370614359172;
+// The punctual light buffers carry the integrated surface-light value
+// (color * candela * inverse-square attenuation).  The normalized HG phase
+// below is a per-steradian distribution, so the volume boundary converts the
+// shared light value into that basis exactly once.  This keeps public light
+// units unchanged while matching the Three.js volume-lighting convention,
+// which accumulates the same direct-light value before applying an
+// unnormalized phase.
+const VOLUME_LIGHT_PHASE_SCALE : f32 = FOUR_PI;
+
+fn hash32(value : u32) -> u32 {
+  var hash = value;
+  hash = (hash ^ 61u) ^ (hash >> 16u);
+  hash = hash + (hash << 3u);
+  hash = hash ^ (hash >> 4u);
+  hash = hash * 668265261u;
+  hash = hash ^ (hash >> 15u);
+  return hash;
+}
+
+fn froxel_seed(id : vec3<u32>, salt : u32) -> u32 {
+  return hash32(id.x * 73856093u ^ id.y * 19349663u ^ id.z * 83492791u ^ salt);
+}
+
+fn stratified32(seed : u32, frame_index : u32, odd_stride : u32) -> f32 {
+  let bin = (hash32(seed) + (frame_index & 31u) * odd_stride) & 31u;
+  return (f32(bin) + 0.5) / 32.0;
+}
+
+@group(0) @binding(0) var froxel : texture_2d_array<f32>;
+@group(0) @binding(1) var scene_depth : texture_depth_2d;
+@group(0) @binding(2) var resolved : texture_storage_2d<rgba16float, write>;
+@group(0) @binding(3) var<uniform> volume_params : VolumeParams;
+@group(0) @binding(4) var<uniform> volume_view : VolumeView;
+@group(0) @binding(5) var froxel_sampler : sampler;
+@group(0) @binding(6) var density : texture_3d<f32>;
+@group(0) @binding(7) var density_sampler : sampler;
+@group(0) @binding(8) var history_seed : texture_storage_2d<rgba16float, write>;
+@group(0) @binding(9) var temporal_seed : texture_storage_2d<rgba16float, write>;
+@group(0) @binding(10) var<storage, read> spotLightsBuffer : SpotLightsArray;
+@group(0) @binding(11) var<storage, read> pointLightsBuffer : PointLightsArray;
+@group(0) @binding(12) var projectorTexture : texture_2d<f32>;
+@group(0) @binding(13) var projectorSampler : sampler;
+
+fn hg(cos_theta : f32, anisotropy : f32) -> f32 {
+  let g = clamp(anisotropy, -0.999, 0.999);
+  let denominator = max(1.0 + g * g - 2.0 * g * clamp(cos_theta, -1.0, 1.0), EPSILON);
+  return (1.0 - g * g) / (FOUR_PI * pow(denominator, 1.5));
+}
+fn reconstruct_world(uv : vec2<f32>, depth : f32) -> vec3<f32> {
+  let clip = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth, 1.0);
+  let world = volume_view.inverseViewProj * clip;
+  return world.xyz / max(abs(world.w), EPSILON);
+}
+fn ray_box_interval(origin : vec3<f32>, direction : vec3<f32>) -> vec2<f32> {
+  let safe_direction = select(direction, vec3<f32>(EPSILON), abs(direction) < vec3<f32>(EPSILON));
+  let reciprocal = 1.0 / safe_direction;
+  let a = (volume_params.bounds_min.xyz - origin) * reciprocal;
+  let b = (volume_params.bounds_max.xyz - origin) * reciprocal;
+  let near_distance = max(max(min(a.x, b.x), min(a.y, b.y)), min(a.z, b.z));
+  let far_distance = min(min(max(a.x, b.x), max(a.y, b.y)), max(a.z, b.z));
+  return vec2<f32>(max(near_distance, 0.0), max(far_distance, near_distance));
+}
+
+fn evalSpotAttenuation(
+  lightPos : vec3<f32>, lightDir : vec3<f32>, worldPos : vec3<f32>,
+  cosInner : f32, cosOuter : f32, invRangeSquared : f32,
+) -> f32 {
+  let toLight = lightPos - worldPos;
+  let dSquared = dot(toLight, toLight);
+  let safeDistance = max(dSquared, EPSILON);
+  let window = clamp(1.0 - (safeDistance * invRangeSquared) * (safeDistance * invRangeSquared), 0.0, 1.0);
+  let distance = window * window / safeDistance;
+  let direction = normalize(select(vec3<f32>(0.0, 0.0, -1.0), toLight, dSquared > EPSILON));
+  return distance * smoothstep(cosOuter, cosInner, dot(direction, -normalize(lightDir)));
+}
+
+fn spotProjectorMatrix(light : SpotLight) -> mat4x4<f32> {
+  if (light.shadowAtlasTile >= 0) {
+    return volume_view.spotLightViewProj[light.shadowAtlasTile];
+  }
+  return volume_view.spotLightViewProj[0];
+}
+
+fn spot_attenuation_at(world_position : vec3<f32>) -> f32 {
+  let slot = u32(clamp(round(volume_params.light_color.w), 0.0, 3.0));
+  if (slot >= spotLightsBuffer.count) { return 0.0; }
+  let light = spotLightsBuffer.slots[slot];
+  let projectorUv = projectSpotUv(spotProjectorMatrix(light), world_position);
+  if (any(projectorUv < vec2<f32>(0.0)) || any(projectorUv > vec2<f32>(1.0))) { return 0.0; }
+  return evalSpotAttenuation(
+    light.position,
+    light.direction,
+    world_position,
+    light.cosInner,
+    light.cosOuter,
+    light.invRangeSquared,
+  );
+}
+
+fn evalVolumePoint(
+  lightPos : vec3<f32>, colorTimesIntensity : vec3<f32>,
+  invRangeSquared : f32, worldPos : vec3<f32>,
+) -> vec3<f32> {
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), EPSILON);
+  let safeDistance = max(dSquared, EPSILON);
+  let window = clamp(1.0 - (safeDistance * invRangeSquared) * (safeDistance * invRangeSquared), 0.0, 1.0);
+  return colorTimesIntensity * (window * window / safeDistance);
+}
+
+fn evalVolumeSpot(
+  lightPos : vec3<f32>, lightDir : vec3<f32>, colorTimesIntensity : vec3<f32>,
+  cosInner : f32, cosOuter : f32, invRangeSquared : f32, worldPos : vec3<f32>,
+) -> vec3<f32> {
+  return colorTimesIntensity * evalSpotAttenuation(
+    lightPos, lightDir, worldPos, cosInner, cosOuter, invRangeSquared,
+  );
+}
+
+fn volume_point_radiance(world_position : vec3<f32>) -> vec3<f32> {
+  let pointSlot = u32(clamp(round(volume_params.emission.w), 0.0, 3.0));
+  if (pointSlot >= pointLightsBuffer.count) { return vec3<f32>(0.0); }
+  let point = pointLightsBuffer.slots[pointSlot];
+  return evalVolumePoint(
+    point.position, point.colorTimesIntensity, point.invRangeSquared, world_position,
+  );
+}
+
+fn volume_spot_radiance(world_position : vec3<f32>) -> vec3<f32> {
+  let spotSlot = u32(clamp(round(volume_params.light_color.w), 0.0, 3.0));
+  if (spotSlot >= spotLightsBuffer.count) { return vec3<f32>(0.0); }
+  let spot = spotLightsBuffer.slots[spotSlot];
+  let radiance = evalVolumeSpot(
+    spot.position, spot.direction, spot.colorTimesIntensity,
+    spot.cosInner, spot.cosOuter, spot.invRangeSquared, world_position,
+  );
+  let projectorUv = projectSpotUv(spotProjectorMatrix(spot), world_position);
+  if (!(projectorUv.x >= 0.0 && projectorUv.x <= 1.0 && projectorUv.y >= 0.0 && projectorUv.y <= 1.0)) {
+    // A SpotLight map modulates the light only inside its projected tile.
+    // Three keeps the cone/attenuation result outside that tile; the map is
+    // not a second frustum mask.
+    return radiance;
+  }
+  return radiance * textureSampleLevel(projectorTexture, projectorSampler, projectorUv, 0.0).rgb;
+}
+
+fn volume_spot_shadow_intensity() -> f32 {
+  let spotSlot = u32(clamp(round(volume_params.light_color.w), 0.0, 3.0));
+  if (spotSlot >= spotLightsBuffer.count) { return 1.0; }
+  return clamp(spotLightsBuffer.slots[spotSlot].shadowIntensity, 0.0, 1.0);
+}
+
+fn volume_light_radiance(world_position : vec3<f32>) -> vec3<f32> {
+  let mode = u32(round(volume_params.optics.z));
+  if (mode == 0u) { return volume_params.light_color.xyz; }
+  var radiance = vec3<f32>(0.0);
+  if (mode == 1u || mode == 3u) {
+    radiance = radiance + volume_point_radiance(world_position);
+  }
+  if (mode == 2u || mode == 3u) {
+    radiance = radiance + volume_spot_radiance(world_position);
+  }
+  return radiance;
+}
+
+fn volume_light_radiance_pair(world_position : vec3<f32>, spot_visibility : f32) -> vec3<f32> {
+  // Keep the pair's PointLight term independent from the SpotLight shadow.
+  return volume_point_radiance(world_position) +
+    volume_spot_radiance(world_position) *
+      mix(1.0, spot_visibility, volume_spot_shadow_intensity());
+}
+
+fn isFinite(value : f32) -> bool {
+  return value == value && abs(value) < 3.402823e+38;
+}
+
+fn finiteVec3(value : vec3<f32>) -> bool {
+  return isFinite(value.x) && isFinite(value.y) && isFinite(value.z);
+}
+
+// Match the pinned Three.js VolumeNodeMaterial density expression while
+// keeping the authored TextureAsset and its renderer-owned sampler intact.
+fn volume_sample_grain(
+  position : vec3<f32>,
+  scale : f32,
+  time_scaled : vec3<f32>,
+  time_scale : f32,
+) -> f32 {
+  let coordinate = fract((position + time_scaled * time_scale) * scale);
+  return textureSampleLevel(density, density_sampler, coordinate, 0.0).r + 0.5;
+}
+
+fn volume_scattering_density(position : vec3<f32>, frame_index : u32) -> f32 {
+  let time = f32(frame_index) / 60.0;
+  let time_scaled = vec3<f32>(time, 0.0, time * 0.3);
+  var grain = volume_sample_grain(position, 0.1, time_scaled, 1.0);
+  grain = grain * volume_sample_grain(position, 0.05, time_scaled, 1.0);
+  grain = grain * volume_sample_grain(position, 0.02, time_scaled, 2.0);
+  // TSL's smokeAmount.mix(1, grain) expands to mix(1, grain, 2).
+  return 2.0 * grain - 1.0;
+}
+
+fn packed_visibility_at(previous : vec4<f32>, current : vec4<f32>, next : vec4<f32>, channel : i32) -> f32 {
+  if (channel < 0) { return previous.w; }
+  if (channel > 3) { return next.x; }
+  return current[channel];
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn volume_integrate(@builtin(global_invocation_id) id : vec3<u32>) {
+  let volume_size = textureDimensions(resolved);
+  let output_size = textureDimensions(resolved);
+  if (any(id.xy >= output_size)) { return; }
+  let uv = (vec2<f32>(id.xy) + vec2<f32>(0.5)) / vec2<f32>(output_size);
+  let origin = reconstruct_world(uv, 0.0);
+  let far_point = reconstruct_world(uv, 1.0);
+  let ray_direction = normalize(far_point - origin);
+  let interval = ray_box_interval(origin, ray_direction);
+  let ray_near = interval.x;
+  let ray_far = min(interval.y, volume_params.optics.x);
+  let depth_size = textureDimensions(scene_depth);
+  let pixel = min(vec2<u32>(uv * vec2<f32>(depth_size)), max(depth_size, vec2<u32>(1u)) - vec2<u32>(1u));
+  let scene_depth_value = textureLoad(scene_depth, vec2<i32>(pixel), 0);
+  let scene_world = reconstruct_world(uv, scene_depth_value);
+  let scene_distance = max(dot(scene_world - origin, ray_direction), 0.0);
+  let clipped_far = min(ray_far, scene_distance);
+  let visibility_depth = max(textureNumLayers(froxel) * 4u, 1u);
+  let ray_step_count = 12u;
+  // The pinned Three.js scene evaluates twelve lighting steps. The packed
+  // froxel remains deeper so shadow visibility can be interpolated at each
+  // ray sample without making the integration denser than the oracle.
+  let full_step = max(ray_far - ray_near, 0.0) / f32(visibility_depth);
+  let ray_step = max(ray_far - ray_near, 0.0) / f32(ray_step_count);
+  let volume_extent = max(volume_params.bounds_max.xyz - volume_params.bounds_min.xyz, vec3<f32>(EPSILON));
+  var transmittance = 1.0;
+  var scattering = vec3<f32>(0.0);
+  let phase = hg(dot(-normalize(volume_params.light_direction.xyz), ray_direction), volume_params.optics.y);
+  let sigma_scale = max(dot(volume_params.extinction.xyz, vec3<f32>(0.3333333)), 0.0);
+  let raw_froxel_size = max(textureDimensions(froxel).xy, vec2<u32>(1u));
+  let raw_froxel_coord = min(
+    vec2<u32>(uv * vec2<f32>(raw_froxel_size)),
+    raw_froxel_size - vec2<u32>(1u),
+  );
+  let frame_index = u32(max(volume_params.light_direction.w, 0.0));
+  for (var step = 0u; step < ray_step_count; step = step + 1u) {
+    let segment_start = ray_near + f32(step) * ray_step;
+    let segment_length = clamp(clipped_far - segment_start, 0.0, ray_step);
+    if (segment_length > 0.0) {
+      let depth_phase = stratified32(
+        froxel_seed(vec3<u32>(raw_froxel_coord, step), 3266489917u),
+        frame_index,
+        17u,
+      );
+      let jittered_ray_t = segment_start + segment_length * depth_phase;
+      let world_position = origin + ray_direction * jittered_ray_t;
+      // The exact Three.js smokeAmount transform can produce negative values
+      // from its signed noise domain. Beer-Lambert optical depth is physical
+      // extinction, so the renderer clamps only this consumed density while
+      // retaining the authored source expression and its signed diagnostics.
+      let density_value = max(volume_scattering_density(world_position, frame_index), 0.0);
+      let sample_position = clamp(
+        (jittered_ray_t - ray_near) / max(full_step, EPSILON) - 0.5,
+        0.0,
+        f32(visibility_depth - 1u),
+      );
+      let lower_position = u32(floor(sample_position));
+      let upper_position = min(lower_position + 1u, visibility_depth - 1u);
+      let interpolation = sample_position - f32(lower_position);
+      let slice_group = lower_position / 4u;
+      let upper_group = upper_position / 4u;
+      let lower_packed = textureSampleLevel(froxel, froxel_sampler, uv, i32(slice_group), 0.0);
+      let upper_packed = textureSampleLevel(froxel, froxel_sampler, uv, i32(upper_group), 0.0);
+      let lower_visibility = lower_packed[i32(lower_position % 4u)];
+      let upper_visibility = upper_packed[i32(upper_position % 4u)];
+      let shadow_visibility = clamp(mix(lower_visibility, upper_visibility, interpolation), 0.0, 1.0);
+      // Apply the packed SpotLight shadow only to the spot contribution.
+      // PointLight distance attenuation remains independent of the spot cone.
+      let mode = u32(round(volume_params.optics.z));
+      let visibility = select(
+        shadow_visibility,
+        mix(1.0, shadow_visibility, volume_spot_shadow_intensity()),
+        mode == 2u || mode == 3u,
+      );
+      let radiance = select(
+        volume_light_radiance(world_position) * visibility,
+        volume_light_radiance_pair(world_position, visibility),
+        mode == 3u,
+      );
+      let local_transmittance = exp(-sigma_scale * density_value * segment_length);
+      let local_scatter = radiance * volume_params.albedo.xyz * phase *
+        VOLUME_LIGHT_PHASE_SCALE * (1.0 - local_transmittance) +
+        volume_params.emission.xyz * density_value * segment_length;
+      scattering = scattering + transmittance * local_scatter;
+      transmittance = transmittance * local_transmittance;
+    }
+  }
+  let finite = isFinite(transmittance) && finiteVec3(scattering);
+  let result = select(vec4<f32>(0.0, 0.0, 0.0, 1.0), vec4<f32>(scattering, transmittance), finite);
+  textureStore(resolved, id.xy, result);
+  if (volume_params.optics.w < 0.5) {
+    textureStore(history_seed, id.xy, result);
+    textureStore(temporal_seed, id.xy, result);
+  }
+}

package/src/volume/volume-temporal.wgsl

@@ -0,0 +1,70 @@
+#define_import_path forgeax_view::volume_temporal
+
+struct VolumeTemporalView {
+  _prefix : array<vec4<f32>, 6>, cameraPos : vec4<f32>, _lightViewProjA : mat4x4<f32>, inverseViewProj : mat4x4<f32>,
+  _middle : array<vec4<f32>, 34>, temporalCurrentViewProj : mat4x4<f32>, temporalPreviousViewProj : mat4x4<f32>,
+  temporalProjection : vec4<f32>, temporalPreviousCameraPos : vec4<f32>,
+};
+struct VolumeParams {
+  bounds_min : vec4<f32>, bounds_max : vec4<f32>, extinction : vec4<f32>, albedo : vec4<f32>,
+  emission : vec4<f32>, light_direction : vec4<f32>, light_color : vec4<f32>, optics : vec4<f32>,
+};
+
+@group(0) @binding(0) var current : texture_2d<f32>;
+@group(0) @binding(1) var accepted : texture_2d<f32>;
+@group(0) @binding(2) var pending : texture_storage_2d<rgba16float, write>;
+@group(0) @binding(3) var<uniform> volume_params : VolumeParams;
+@group(0) @binding(4) var<uniform> volume_view : VolumeTemporalView;
+
+fn bilinear(uv : vec2<f32>, size : vec2<u32>) -> vec4<f32> {
+  let p = uv * vec2<f32>(size) - vec2<f32>(0.5);
+  let base = vec2<i32>(floor(p));
+  let f = fract(p);
+  let max_coord = vec2<i32>(size) - vec2<i32>(1);
+  let c00 = textureLoad(accepted, clamp(base, vec2<i32>(0), max_coord), 0);
+  let c10 = textureLoad(accepted, clamp(base + vec2<i32>(1, 0), vec2<i32>(0), max_coord), 0);
+  let c01 = textureLoad(accepted, clamp(base + vec2<i32>(0, 1), vec2<i32>(0), max_coord), 0);
+  let c11 = textureLoad(accepted, clamp(base + vec2<i32>(1), vec2<i32>(0), max_coord), 0);
+  return mix(mix(c00, c10, f.x), mix(c01, c11, f.x), f.y);
+}
+
+fn reproject_uv(uv : vec2<f32>) -> vec2<f32> {
+  let current_ndc = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, 0.5, 1.0);
+  let world_h = volume_view.inverseViewProj * current_ndc;
+  let world = world_h.xyz / max(abs(world_h.w), 1e-5);
+  let previous_clip = volume_view.temporalPreviousViewProj * vec4<f32>(world, 1.0);
+  if (previous_clip.w <= 1e-5) {
+    return vec2<f32>(-1.0);
+  }
+  let previous_ndc = previous_clip.xyz / previous_clip.w;
+  return vec2<f32>(previous_ndc.x * 0.5 + 0.5, 1.0 - (previous_ndc.y * 0.5 + 0.5));
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn volume_temporal(@builtin(global_invocation_id) id : vec3<u32>) {
+  let size = textureDimensions(current);
+  if (any(id.xy >= size)) { return; }
+  let uv = (vec2<f32>(id.xy) + vec2<f32>(0.5)) / vec2<f32>(size);
+  let center = textureLoad(current, vec2<i32>(id.xy), 0);
+  var lower = center;
+  var upper = center;
+  for (var oy = -1i; oy <= 1i; oy = oy + 1i) {
+    for (var ox = -1i; ox <= 1i; ox = ox + 1i) {
+      let coord = clamp(vec2<i32>(id.xy) + vec2<i32>(ox, oy), vec2<i32>(0), vec2<i32>(size) - vec2<i32>(1));
+      let neighbor = textureLoad(current, coord, 0);
+      lower = min(lower, neighbor);
+      upper = max(upper, neighbor);
+    }
+  }
+  var output = center;
+  let historyValid = volume_params.optics.w >= 0.5 && volume_view.temporalPreviousCameraPos.w >= 0.5;
+  if (historyValid) {
+    let previous_uv = reproject_uv(uv);
+    if (all(previous_uv >= vec2<f32>(0.0)) && all(previous_uv <= vec2<f32>(1.0))) {
+      let prior = bilinear(previous_uv, size);
+      let clamped = clamp(prior, lower, upper);
+      output = mix(center, clamped, 0.875);
+    }
+  }
+  textureStore(pending, id.xy, output);
+}