@woosh/meep-engine 3.65.0 → 3.68.0

package/src/shade/renderer/shader/chunk/atmosphere/chunk_get_sun_transmittance.js

@@ -1,59 +1,66 @@
+import {
+    ATMOSPHERE_PARAMETERS_STRUCT,
+    chunk_atmosphere_parameters
+} from "../../../atmosphere/ATMOSPHERE_PARAMETERS_STRUCT.js";
 import { CodeChunk } from "../../compiler/CodeChunk.js";
-import { chunk_atmosphere_density } from "./chunk_atmosphere_density.js";
-import { chunk_atmosphere_height } from "./chunk_atmosphere_height.js";
-import { chunk_atmosphere_intersection } from "./chunk_atmosphere_intersection.js";
-import { chunk_compute_extinction } from "./chunk_compute_extinction.js";
-import { chunk_sphere_intersection } from "./chunk_sphere_intersection.js";
-import { PLANET_CENTER_DECLARATION } from "./PLANET_CENTER_DECLARATION.js";
-import { PLANET_RADIUS_DECLARATION } from "./PLANET_RADIUS_DECLARATION.js";
 
 /**
- * @see https://www.shadertoy.com/view/slSXRW
+ * Integrates direct solar transmittance from `pos` along `sunDir` to the top of the atmosphere,
+ * returning zero when the ray intersects the planet sphere.
+ *
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
  * @type {CodeChunk}
  */
 export const chunk_get_sun_transmittance = CodeChunk.from(
     //language=WGSL
     `
-fn get_sun_transmittance(pos: vec3<f32>, sunDir: vec3<f32>, sunTransmittanceSteps: f32) -> vec3<f32>{
-    
-    if (sphere_intersection(pos, sunDir, PLANET_CENTER, PLANET_RADIUS).x > 0.0) {
-        // we're outside of the atmosphere
-        return vec3(0.0);
+fn get_sun_transmittance_rel_for(
+    atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref},
+    rel: vec3<f32>,
+    sunDir: vec3<f32>,
+    sunTransmittanceSteps: f32
+) -> vec3<f32> {
+    let bounds = atmosphere_ray_bounds_for(atm, rel, sunDir);
+
+    if (bounds.hits_ground) {
+        return vec3<f32>(0.0);
     }
-    
-    let ray_length = atmosphere_intersection(pos, sunDir ).y;
+
+    let ray_length = bounds.t_max;
     var t = 0.0;
-    
-    var transmittance = vec3(1.0);
-    
-    // integrate optical depth
+    var transmittance = vec3<f32>(1.0);
+
     for (var i = 0.0; i < sunTransmittanceSteps; i += 1.0) {
         let f = (i + 0.3) / sunTransmittanceSteps;
-    
         let newT = f * ray_length;
         let dt = newT - t;
         t = newT;
-        
-        let newPos = pos + t * sunDir;
-        
-        let local_height = atmosphere_height(newPos);
-		let local_density  = atmosphere_density(local_height);
-        
-        let extinction = compute_extinction(local_density);
-		
-		transmittance *= exp(-dt * extinction);
-		
+
+        let step_rel = rel + t * sunDir;
+        let local_height = length(step_rel) - atm.planet_radius;
+        let local_density = atmosphere_density_for(atm, local_height);
+        let extinction = atmosphere_extinction_for(atm, local_density);
+
+        transmittance *= exp(-dt * extinction);
     }
-    
+
     return transmittance;
 }
+
+fn get_sun_transmittance_for(
+    atm: ${ATMOSPHERE_PARAMETERS_STRUCT.wgsl_ref},
+    pos_ws: vec3<f32>,
+    sunDir: vec3<f32>,
+    sunTransmittanceSteps: f32
+) -> vec3<f32> {
+    let rel = atmosphere_position_relative_for(atm, pos_ws);
+    return get_sun_transmittance_rel_for(atm, rel, sunDir, sunTransmittanceSteps);
+}
+
+fn get_sun_transmittance(pos_ws: vec3<f32>, sunDir: vec3<f32>, sunTransmittanceSteps: f32) -> vec3<f32> {
+    return get_sun_transmittance_for(atmosphere_earth_parameters(), pos_ws, sunDir, sunTransmittanceSteps);
+}
     `, [
-        chunk_sphere_intersection,
-        chunk_atmosphere_height,
-        chunk_atmosphere_density,
-        PLANET_RADIUS_DECLARATION,
-        PLANET_CENTER_DECLARATION,
-        chunk_atmosphere_intersection,
-        chunk_compute_extinction,
+        chunk_atmosphere_parameters,
     ]
-);
+);

package/src/shade/renderer/shader/chunk/atmosphere/chunk_position_relative_to_planet_center.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_position_relative_to_planet_center.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/chunk_position_relative_to_planet_center.js"],"names":[],"mappings":"AAGA,iEASE;0BAZwB,6BAA6B"}
+{"version":3,"file":"chunk_position_relative_to_planet_center.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/atmosphere/chunk_position_relative_to_planet_center.js"],"names":[],"mappings":"AAIA,iEAUE;0BAbwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/atmosphere/chunk_position_relative_to_planet_center.js

@@ -1,13 +1,15 @@
+import { ATMOSPHERE_UNIT_SCALE_DECLARATION } from "../../../atmosphere/ATMOSPHERE_UNIT_SCALE.js";
 import { CodeChunk } from "../../compiler/CodeChunk.js";
 import { PLANET_CENTER_DECLARATION } from "./PLANET_CENTER_DECLARATION.js";
 
 export const chunk_position_relative_to_planet_center = CodeChunk.from(
-//language=WGSL
+    //language=WGSL
     `
-fn position_relative_to_planet_center(pos:vec3<f32>) -> vec3<f32> {
-    return pos - PLANET_CENTER;
+fn position_relative_to_planet_center(pos: vec3<f32>) -> vec3<f32> {
+    return pos * METERS_TO_ATMOSPHERE_UNITS - PLANET_CENTER;
 }
     `, [
+        ATMOSPHERE_UNIT_SCALE_DECLARATION,
         PLANET_CENTER_DECLARATION
     ]
 );

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.d.ts

@@ -9,6 +9,12 @@ export const M3_REC709_TO_AP1: Float64Array;
  * @type {Float64Array}
  */
 export const M3_AP1_TO_REC709: Float64Array;
+/**
+ * AP1's contribution of each channel to Y, the row Unreal calls `AP1_RGB2Y`: the shader's `AP1_LUMINANCE`, for code that
+ * measures AP1 luma on the CPU.
+ * @type {Float64Array}
+ */
+export const AP1_LUMINANCE: Float64Array;
 /**
  * - `CRM_FROM_REC709_TO_AP1` and `CRM_FROM_AP1_TO_REC709`: {@link M3_REC709_TO_AP1} and its inverse.
  * - `AP1_LUMINANCE`: AP1's contribution of each channel to Y, the row Unreal calls `AP1_RGB2Y`.

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_CRM_REC709_AP1.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,+BAFU,YAAY,CAE8B;AAIpD;;;GAGG;AACH,+BAFU,YAAY,CAE8B;AAYpD;;;;;;;GAOG;AACH,mCAFU,SAAS,CASjB;0BAzDwB,gCAAgC"}
+{"version":3,"file":"chunk_CRM_REC709_AP1.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,+BAFU,YAAY,CAE8B;AAIpD;;;GAGG;AACH,+BAFU,YAAY,CAE8B;AAGpD;;;;GAIG;AACH,4BAFU,YAAY,CAEoE;AAW1F;;;;;;;GAOG;AACH,mCAFU,SAAS,CASjB;0BAhEwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.js

@@ -35,6 +35,13 @@ m3_multiply(M3_REC709_TO_AP1, XYZ_TO_AP1, M3_REC709_TO_AP1);
 export const M3_AP1_TO_REC709 = new Float64Array(9);
 m3_invert(M3_AP1_TO_REC709, M3_REC709_TO_AP1);
 
+/**
+ * AP1's contribution of each channel to Y, the row Unreal calls `AP1_RGB2Y`: the shader's `AP1_LUMINANCE`, for code that
+ * measures AP1 luma on the CPU.
+ * @type {Float64Array}
+ */
+export const AP1_LUMINANCE = Float64Array.of(AP1_TO_XYZ[3], AP1_TO_XYZ[4], AP1_TO_XYZ[5]);
+
 /**
  * @param {Float64Array} m row-major
  * @returns {string} a WGSL `mat3x3<f32>` constructor, column by column

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.d.ts

@@ -1,10 +1,10 @@
 /**
  * `color_grade(scene, grade, keys)`: exposed scene-linear Rec.709 through a {@link ColorGrade}, white balance, then
- * primaries, then hue curves, to Rec.709 again, not negative. `grade` is the grade's {@link COLOR_GRADE_STRUCT} and
- * `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
+ * primaries, then saturation against luma, then hue curves, to Rec.709 again, not negative. `grade` is the grade's
+ * {@link COLOR_GRADE_STRUCT} and `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
  *
- * Also defines each stage on its own: `color_grade_primaries(ap1, grade)` and
- * `color_grade_hue_curves(color, counts, keys)`.
+ * Also defines each stage on its own: `color_grade_primaries(ap1, grade)`,
+ * `color_grade_luma_saturation(ap1, counts, keys, first)` and `color_grade_hue_curves(color, counts, keys)`.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_color_grade.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,gCAFU,SAAS,CA0HjB;0BAxIwB,gCAAgC"}
+{"version":3,"file":"chunk_color_grade.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,gCAFU,SAAS,CA2MjB;0BAzNwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.js

@@ -9,11 +9,11 @@ import { chunk_oklab_to_linear_srgb } from "../oklab/chunk_oklab_to_linear_srgb.
 
 /**
  * `color_grade(scene, grade, keys)`: exposed scene-linear Rec.709 through a {@link ColorGrade}, white balance, then
- * primaries, then hue curves, to Rec.709 again, not negative. `grade` is the grade's {@link COLOR_GRADE_STRUCT} and
- * `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
+ * primaries, then saturation against luma, then hue curves, to Rec.709 again, not negative. `grade` is the grade's
+ * {@link COLOR_GRADE_STRUCT} and `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
  *
- * Also defines each stage on its own: `color_grade_primaries(ap1, grade)` and
- * `color_grade_hue_curves(color, counts, keys)`.
+ * Also defines each stage on its own: `color_grade_primaries(ap1, grade)`,
+ * `color_grade_luma_saturation(ap1, counts, keys, first)` and `color_grade_hue_curves(color, counts, keys)`.
  *
  * @type {CodeChunk}
  */
@@ -65,6 +65,78 @@ fn color_grade_primaries(ap1: vec3<f32>, grade: ${COLOR_GRADE_STRUCT.wgsl_ref})
     return shadows * weight_shadows + midtones * weight_midtones + highlights * weight_highlights;
 }
 
+// each AP1 channel drawn away from the luma by its factor, read at the luma's stops from middle grey: the all-channel
+// curve times the channel's own; counts are the red, green, blue and all-channel curves' keys, in that order, starting
+// at key 'first'
+fn color_grade_luma_saturation(
+    ap1: vec3<f32>,
+    counts: vec4<u32>,
+    keys: ptr<storage, array<${ANIMATION_CURVE_KEYFRAME_STRUCT.wgsl_ref}>, read>,
+    first: u32,
+) -> vec3<f32> {
+    let luma = dot(ap1, AP1_LUMINANCE);
+
+    // a colour with no luma has no tonal place to read the curves at, and nothing to saturate
+    if (all(counts == vec4<u32>(0u)) || luma <= 0.0) {
+        return ap1;
+    }
+
+    let stops = log2(luma / 0.18);
+
+    var saturation = vec3<f32>(1.0);
+
+    if (counts.x > 0u) {
+        saturation.x = animation_curve_evaluate_keys(keys, first, counts.x, stops);
+    }
+    if (counts.y > 0u) {
+        saturation.y = animation_curve_evaluate_keys(keys, first + counts.x, counts.y, stops);
+    }
+    if (counts.z > 0u) {
+        saturation.z = animation_curve_evaluate_keys(keys, first + counts.x + counts.y, counts.z, stops);
+    }
+    if (counts.w > 0u) {
+        saturation *= animation_curve_evaluate_keys(keys, first + counts.x + counts.y + counts.z, counts.w, stops);
+    }
+
+    return max(vec3<f32>(0.0), mix(vec3<f32>(luma), ap1, saturation));
+}
+
+// each AP1 channel multiplied by its gain, and every channel by 2^exposure, read at the luma's stops from middle grey;
+// counts are the red, green and blue gain curves' keys and the exposure curve's, in that order, starting at key 'first'
+fn color_grade_luma_gain(
+    ap1: vec3<f32>,
+    counts: vec4<u32>,
+    keys: ptr<storage, array<${ANIMATION_CURVE_KEYFRAME_STRUCT.wgsl_ref}>, read>,
+    first: u32,
+) -> vec3<f32> {
+    let luma = dot(ap1, AP1_LUMINANCE);
+
+    // a colour with no luma has no tonal place to read the curves at
+    if (all(counts == vec4<u32>(0u)) || luma <= 0.0) {
+        return ap1;
+    }
+
+    let stops = log2(luma / 0.18);
+
+    var gain = vec3<f32>(1.0);
+    var exposure = 0.0;
+
+    if (counts.x > 0u) {
+        gain.x = animation_curve_evaluate_keys(keys, first, counts.x, stops);
+    }
+    if (counts.y > 0u) {
+        gain.y = animation_curve_evaluate_keys(keys, first + counts.x, counts.y, stops);
+    }
+    if (counts.z > 0u) {
+        gain.z = animation_curve_evaluate_keys(keys, first + counts.x + counts.y, counts.z, stops);
+    }
+    if (counts.w > 0u) {
+        exposure = animation_curve_evaluate_keys(keys, first + counts.x + counts.y + counts.z, counts.w, stops);
+    }
+
+    return max(vec3<f32>(0.0), ap1 * gain * exp2(exposure));
+}
+
 // hue shift, chroma scale and lightness against OkLCh hue; counts.xyz are the three curves' keys, in that order
 fn color_grade_hue_curves(
     color: vec3<f32>,
@@ -123,7 +195,16 @@ fn color_grade(
 ) -> vec3<f32> {
     let white_balance = mat3x3<f32>(grade.white_balance_c0.xyz, grade.white_balance_c1.xyz, grade.white_balance_c2.xyz);
 
-    let ap1 = color_grade_primaries(CRM_FROM_REC709_TO_AP1 * (white_balance * scene), grade);
+    let primaries = color_grade_primaries(CRM_FROM_REC709_TO_AP1 * (white_balance * scene), grade);
+
+    // the luma curves' keys follow the hue curves': saturation's, then gain's
+    let counts = grade.curve_counts;
+    let saturation_counts = grade.luma_curve_counts;
+    let hue_keys = counts.x + counts.y + counts.z;
+    let saturation_keys = saturation_counts.x + saturation_counts.y + saturation_counts.z + saturation_counts.w;
+
+    let gained = color_grade_luma_gain(primaries, grade.luma_gain_counts, keys, hue_keys + saturation_keys);
+    let ap1 = color_grade_luma_saturation(gained, saturation_counts, keys, hue_keys);
 
     let graded = max(CRM_FROM_AP1_TO_REC709 * ap1, vec3<f32>(0.0));
 

package/src/shade/renderer/shader/chunk/color/tonemap/purkinje/chunk_apply_purkinje_shift.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How much of the eye's response is the rods', at an adaptation, across a response range: 1 at and below `rods_below`,
+ * 0 at and above `cones_above`, linear in log luminance in between. CIE 191's range is
+ * {@link PURKINJE_MESOPIC_MIN_NITS} to {@link PURKINJE_MESOPIC_MAX_NITS}. The share `apply_purkinje_shift` blends by,
+ * for code that needs it on the CPU.
+ *
+ * @param {number} adaptation_luminance cd/m²
+ * @param {number} rods_below cd/m², over 0
+ * @param {number} cones_above cd/m², over `rods_below`
+ * @returns {number} 0 to 1
+ */
+export function purkinje_rod_share(adaptation_luminance: number, rods_below: number, cones_above: number): number;
+/**
+ * Rec.709 photopic luminance weights: what the cones see of a linear Rec.709 colour.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_PHOTOPIC: ReadonlyArray<number>;
+/**
+ * Rec.709 scotopic luminance weights: what the rods see of a linear Rec.709 colour. They sum to 1, so a grey has the
+ * same scotopic luminance as photopic.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_SCOTOPIC: ReadonlyArray<number>;
+/**
+ * "Rod blue": the colour the scotopic signal is carried by. Artistic: (0.3, 0.5, 0.9) mimics the sensation of the
+ * rods' 507 nm peak.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_NIGHT_TINT: ReadonlyArray<number>;
+/**
+ * CIE 191's mesopic range, cd/m²: rods alone below the lower bound (scotopic), cones alone above the upper (photopic).
+ * The response range of the tone mapper's run-time shift.
+ */
+export const PURKINJE_MESOPIC_MIN_NITS: 0.005;
+export const PURKINJE_MESOPIC_MAX_NITS: 5;
+/**
+ * Purkinje shift.
+ * Human vision system shifts color perception away from red in night-time conditions.
+ *
+ * ```wgsl
+ * fn purkinje_rod_share(adaptation_luminance: f32, rods_below: f32, cones_above: f32) -> f32
+ * fn apply_purkinje_shift(color_rec709: vec3<f32>, rod_share: f32) -> vec3<f32>
+ * ```
+ *
+ * `purkinje_rod_share` is how much of the eye's response is the rods' at `adaptation_luminance`, the luminance the eye
+ * is adapted to, across a response range, all in cd/m²: 1 at and below `rods_below`, 0 at and above `cones_above`
+ * (which must be over `rods_below`, itself over 0), linear in log luminance in between. CIE 191's mesopic range,
+ * `PURKINJE_MESOPIC_MIN_NITS` to `PURKINJE_MESOPIC_MAX_NITS` (0.005 to 5 cd/m²), is the eye's.
+ *
+ * `apply_purkinje_shift` blends `color_rec709`, scene-linear Rec.709, towards the rod response by `rod_share`: at 0 the
+ * colour is returned as it is; at 1 it is the rod response alone, its scotopic luminance carried by a blue tint. The
+ * shift is linear in the colour, so it gives the same result ahead of the exposure as after it.
+ *
+ * The constants are the module's exports ({@link PURKINJE_REC709_SCOTOPIC} and the rest), and
+ * {@link purkinje_rod_share} is the share on the CPU.
+ *
+ * NOTE: this should go before the tonemapper.
+ *
+ * Notes on deriving it from the rod and cone responses: PURKINJE_PHYSICAL_DERIVATION_NOTES.md, beside this file.
+ *
+ * @see J. Patry, "Real-Time Samurai Cinema: Lighting, Atmosphere, and Tonemapping in Ghost of Tsushima", Advances in
+ *      Real-Time Rendering in Games, SIGGRAPH 2021 — the primary reference.
+ *      https://www.advances.realtimerendering.com/s2021/jpatry_advances2021/index.html
+ * @see A. G. Kirk, J. F. O'Brien, "Perceptually based tone mapping for low-light conditions", ACM TOG 30(4), 2011.
+ *      https://www2.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-91.pdf
+ * @see D. Cao, J. Pokorny, V. C. Smith, A. J. Zele, "Rod contributions to color perception: linear with rod
+ *      contrast", Vision Research 48(26), 2008.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_apply_purkinje_shift: CodeChunk;
+import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_apply_purkinje_shift.d.ts.map

package/src/shade/renderer/shader/chunk/color/tonemap/purkinje/chunk_apply_purkinje_shift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_apply_purkinje_shift.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/purkinje/chunk_apply_purkinje_shift.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;GAUG;AACH,yDALW,MAAM,cACN,MAAM,eACN,MAAM,GACJ,MAAM,CAQlB;AA5CD;;;GAGG;AACH,uCAFU,cAAc,MAAM,CAAC,CAEiD;AAEhF;;;;GAIG;AACH,uCAFU,cAAc,MAAM,CAAC,CAEiD;AAEhF;;;;GAIG;AACH,kCAFU,cAAc,MAAM,CAAC,CAEmC;AAElE;;;GAGG;AACH,8CAA+C;AAC/C,0CAA2C;AAsC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,yCAFU,SAAS,CAwCjB;0BA1IwB,mCAAmC"}

package/src/shade/renderer/shader/chunk/color/tonemap/purkinje/chunk_apply_purkinje_shift.js

@@ -0,0 +1,139 @@
+import { CodeChunk } from "../../../../compiler/CodeChunk.js";
+
+/**
+ * Rec.709 photopic luminance weights: what the cones see of a linear Rec.709 colour.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_PHOTOPIC = Object.freeze([0.2126, 0.7152, 0.0722]);
+
+/**
+ * Rec.709 scotopic luminance weights: what the rods see of a linear Rec.709 colour. They sum to 1, so a grey has the
+ * same scotopic luminance as photopic.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_REC709_SCOTOPIC = Object.freeze([0.0070, 0.5190, 0.4740]);
+
+/**
+ * "Rod blue": the colour the scotopic signal is carried by. Artistic: (0.3, 0.5, 0.9) mimics the sensation of the
+ * rods' 507 nm peak.
+ * @type {ReadonlyArray<number>}
+ */
+export const PURKINJE_NIGHT_TINT = Object.freeze([0.3, 0.5, 0.9]);
+
+/**
+ * CIE 191's mesopic range, cd/m²: rods alone below the lower bound (scotopic), cones alone above the upper (photopic).
+ * The response range of the tone mapper's run-time shift.
+ */
+export const PURKINJE_MESOPIC_MIN_NITS = 0.005;
+export const PURKINJE_MESOPIC_MAX_NITS = 5;
+
+/**
+ * How much of the eye's response is the rods', at an adaptation, across a response range: 1 at and below `rods_below`,
+ * 0 at and above `cones_above`, linear in log luminance in between. CIE 191's range is
+ * {@link PURKINJE_MESOPIC_MIN_NITS} to {@link PURKINJE_MESOPIC_MAX_NITS}. The share `apply_purkinje_shift` blends by,
+ * for code that needs it on the CPU.
+ *
+ * @param {number} adaptation_luminance cd/m²
+ * @param {number} rods_below cd/m², over 0
+ * @param {number} cones_above cd/m², over `rods_below`
+ * @returns {number} 0 to 1
+ */
+export function purkinje_rod_share(adaptation_luminance, rods_below, cones_above) {
+    const low = Math.log(rods_below);
+    const high = Math.log(cones_above);
+    const t = (Math.log(Math.min(Math.max(adaptation_luminance, rods_below), cones_above)) - low) / (high - low);
+
+    return 1 - Math.min(1, Math.max(0, t));
+}
+
+/**
+ * @param {number} value
+ * @returns {string} as a WGSL float literal, with a point
+ */
+function wgsl_float(value) {
+    const text = String(value);
+    return /[.e]/.test(text) ? text : `${text}.0`;
+}
+
+/**
+ * @param {ReadonlyArray<number>} v
+ * @returns {string}
+ */
+function wgsl_vec3(v) {
+    return `vec3<f32>(${v.map(wgsl_float).join(", ")})`;
+}
+
+/**
+ * Purkinje shift.
+ * Human vision system shifts color perception away from red in night-time conditions.
+ *
+ * ```wgsl
+ * fn purkinje_rod_share(adaptation_luminance: f32, rods_below: f32, cones_above: f32) -> f32
+ * fn apply_purkinje_shift(color_rec709: vec3<f32>, rod_share: f32) -> vec3<f32>
+ * ```
+ *
+ * `purkinje_rod_share` is how much of the eye's response is the rods' at `adaptation_luminance`, the luminance the eye
+ * is adapted to, across a response range, all in cd/m²: 1 at and below `rods_below`, 0 at and above `cones_above`
+ * (which must be over `rods_below`, itself over 0), linear in log luminance in between. CIE 191's mesopic range,
+ * `PURKINJE_MESOPIC_MIN_NITS` to `PURKINJE_MESOPIC_MAX_NITS` (0.005 to 5 cd/m²), is the eye's.
+ *
+ * `apply_purkinje_shift` blends `color_rec709`, scene-linear Rec.709, towards the rod response by `rod_share`: at 0 the
+ * colour is returned as it is; at 1 it is the rod response alone, its scotopic luminance carried by a blue tint. The
+ * shift is linear in the colour, so it gives the same result ahead of the exposure as after it.
+ *
+ * The constants are the module's exports ({@link PURKINJE_REC709_SCOTOPIC} and the rest), and
+ * {@link purkinje_rod_share} is the share on the CPU.
+ *
+ * NOTE: this should go before the tonemapper.
+ *
+ * Notes on deriving it from the rod and cone responses: PURKINJE_PHYSICAL_DERIVATION_NOTES.md, beside this file.
+ *
+ * @see J. Patry, "Real-Time Samurai Cinema: Lighting, Atmosphere, and Tonemapping in Ghost of Tsushima", Advances in
+ *      Real-Time Rendering in Games, SIGGRAPH 2021 — the primary reference.
+ *      https://www.advances.realtimerendering.com/s2021/jpatry_advances2021/index.html
+ * @see A. G. Kirk, J. F. O'Brien, "Perceptually based tone mapping for low-light conditions", ACM TOG 30(4), 2011.
+ *      https://www2.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-91.pdf
+ * @see D. Cao, J. Pokorny, V. C. Smith, A. J. Zele, "Rod contributions to color perception: linear with rod
+ *      contrast", Vision Research 48(26), 2008.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_apply_purkinje_shift = CodeChunk.from(
+    //language=WGSL
+    `
+const PURKINJE_REC709_PHOTOPIC = ${wgsl_vec3(PURKINJE_REC709_PHOTOPIC)}; // Day (Cones)
+const PURKINJE_REC709_SCOTOPIC = ${wgsl_vec3(PURKINJE_REC709_SCOTOPIC)}; // Night (Rods) - Validated
+const PURKINJE_NIGHT_TINT = ${wgsl_vec3(PURKINJE_NIGHT_TINT)};
+const PURKINJE_MESOPIC_MIN_NITS = ${wgsl_float(PURKINJE_MESOPIC_MIN_NITS)}; // Rods dominate below this
+const PURKINJE_MESOPIC_MAX_NITS = ${wgsl_float(PURKINJE_MESOPIC_MAX_NITS)}; // Cones dominate above this
+
+// how much of the response is the rods', linear in log luminance across the response range: a perceptually linear
+// transition
+fn purkinje_rod_share(adaptation_luminance: f32, rods_below: f32, cones_above: f32) -> f32 {
+    let logLum = log(clamp(adaptation_luminance, rods_below, cones_above));
+
+    let logLow = log(rods_below);
+    let logHigh = log(cones_above);
+    let logDelta = logHigh - logLow;
+
+    return 1.0 - saturate( (logLum - logLow) / logDelta );
+}
+
+fn apply_purkinje_shift(
+    color_rec709: vec3<f32>,
+    rod_share: f32
+) -> vec3<f32>{
+    // 1. Calculate Rod Luminance (Night)
+    // Note: Red objects will have a near-zero Y_night, making them turn black.
+    // Blue objects will have a high Y_night, making them appear brighter.
+    let Y_night = dot(color_rec709, PURKINJE_REC709_SCOTOPIC);
+
+    // 2. Construct the Night Vision Image
+    // We treat the rod signal as a scalar intensity applied to our blue tint
+    let color_night = Y_night * PURKINJE_NIGHT_TINT;
+
+    // 3. Lerp from Day view to Night view, by the rods' share
+    return mix(color_rec709, color_night, rod_share);
+}
+    `
+);

package/src/shade/renderer/shader/chunk/depth/chunk_get_device_depth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The device depth a camera's projection gives a view depth, the inverse of {@link chunk_get_view_space_depth}:
+ *
+ * ```wgsl
+ * fn get_device_depth(view_depth: f32, camera: CameraUniforms) -> f32
+ * ```
+ *
+ * Reverse Z, as `device_depth_to_view_space` is ({@link compute_device_depth_to_view_space_depth_params}).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_get_device_depth: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_get_device_depth.d.ts.map

package/src/shade/renderer/shader/chunk/depth/chunk_get_device_depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_get_device_depth.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/depth/chunk_get_device_depth.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CAiBjB;0BA5BwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/depth/chunk_get_device_depth.js

@@ -0,0 +1,30 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * The device depth a camera's projection gives a view depth, the inverse of {@link chunk_get_view_space_depth}:
+ *
+ * ```wgsl
+ * fn get_device_depth(view_depth: f32, camera: CameraUniforms) -> f32
+ * ```
+ *
+ * Reverse Z, as `device_depth_to_view_space` is ({@link compute_device_depth_to_view_space_depth_params}).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_get_device_depth = CodeChunk.from(
+    //language=WGSL
+    `
+fn get_device_depth(
+    view_depth: f32,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref}
+) -> f32 {
+
+    let device_to_view_depth = camera.device_depth_to_view_space;
+
+    return device_to_view_depth.y / view_depth - device_to_view_depth.x;
+}
+    `, [
+        CAMERA_UNIFORM_STRUCT.declaration_chunk,
+    ]
+);

package/src/shade/renderer/shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Clarberg's equal-area mapping between the unit square and the unit sphere, octahedrally folded: every
+ * region of the square covers 4π times its area of the sphere, so a regular n×n grid of texels splits the
+ * sphere into texels of 4π/n² steradians each, and a point drawn uniformly inside a texel is a direction drawn
+ * uniformly over that texel's solid angle.
+ *
+ * ```wgsl
+ * fn uv_equal_area_sphere_decode(uv: vec2<f32>) -> vec3<f32>   // the square [0, 1]² to a unit vector
+ * fn uv_equal_area_sphere_encode(direction: vec3<f32>) -> vec2<f32>   // any non-zero vector to the square
+ * ```
+ *
+ * The square's diamond |2u−1| + |2v−1| ≤ 1 is the +z hemisphere and its centre +z; the four corners meet at −z.
+ * The fold is the standard octahedral one, so the square's edges join as an octahedral map's do.
+ *
+ * @see Petrik Clarberg, "Fast Equal-Area Mapping of the (Hemi)Sphere using SIMD", Journal of Graphics Tools
+ *   13(3), 2008
+ * @type {CodeChunk}
+ */
+export const chunk_uv_equal_area_sphere: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_uv_equal_area_sphere.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_uv_equal_area_sphere.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,yCAFU,SAAS,CAwCZ;0BA3DmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.js

@@ -0,0 +1,60 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { PI_DECLARATION } from "../../math/PI_DECLARATION.js";
+
+/**
+ * Clarberg's equal-area mapping between the unit square and the unit sphere, octahedrally folded: every
+ * region of the square covers 4π times its area of the sphere, so a regular n×n grid of texels splits the
+ * sphere into texels of 4π/n² steradians each, and a point drawn uniformly inside a texel is a direction drawn
+ * uniformly over that texel's solid angle.
+ *
+ * ```wgsl
+ * fn uv_equal_area_sphere_decode(uv: vec2<f32>) -> vec3<f32>   // the square [0, 1]² to a unit vector
+ * fn uv_equal_area_sphere_encode(direction: vec3<f32>) -> vec2<f32>   // any non-zero vector to the square
+ * ```
+ *
+ * The square's diamond |2u−1| + |2v−1| ≤ 1 is the +z hemisphere and its centre +z; the four corners meet at −z.
+ * The fold is the standard octahedral one, so the square's edges join as an octahedral map's do.
+ *
+ * @see Petrik Clarberg, "Fast Equal-Area Mapping of the (Hemi)Sphere using SIMD", Journal of Graphics Tools
+ *   13(3), 2008
+ * @type {CodeChunk}
+ */
+export const chunk_uv_equal_area_sphere = CodeChunk.from(
+    //language=WGSL
+    `
+fn uv_equal_area_sphere_decode(uv: vec2<f32>) -> vec3<f32> {
+    let s = fma(uv, vec2<f32>(2.0), vec2<f32>(-1.0));
+    let d = 1.0 - (abs(s.x) + abs(s.y));
+    let r = 1.0 - abs(d);
+
+    // the square's centre and corners are the poles, where r is zero and the azimuth is any
+    let phi = select((PI * 0.25) * ((abs(s.y) - abs(s.x)) / r + 1.0), 0.0, r == 0.0);
+    let f = r * sqrt(2.0 - r * r);
+
+    return vec3<f32>(
+        f * sign(s.x) * abs(cos(phi)),
+        f * sign(s.y) * abs(sin(phi)),
+        sign(d) * (1.0 - r * r),
+    );
+}
+
+fn uv_equal_area_sphere_encode(direction: vec3<f32>) -> vec2<f32> {
+    let n = normalize(direction);
+    let a = abs(n);
+    let r = sqrt(max(1.0 - a.z, 0.0));
+
+    // the azimuth in the quadrant, 0 along x to 1 along y; on the z axis r is zero and it is never read
+    let tangent = min(a.x, a.y) / max(max(a.x, a.y), 1e-30);
+    let half_turn = atan(tangent) * (2.0 / PI);
+    let phi = select(half_turn, 1.0 - half_turn, a.x < a.y);
+
+    var folded = vec2<f32>(r - phi * r, phi * r);
+
+    folded = select(folded, 1.0 - folded.yx, n.z < 0.0);
+    folded = select(folded, -folded, n.xy < vec2<f32>(0.0));
+
+    return fma(folded, vec2<f32>(0.5), vec2<f32>(0.5));
+}
+`, [
+        PI_DECLARATION,
+    ]);