@woosh/meep-engine 3.65.0 → 3.67.0

package/src/shade/renderer/postprocess/eye/GPUCameraExposureManager.d.ts

@@ -5,6 +5,10 @@
  * The factor lives in one buffer for the manager's life, {@link multiplier}, which a frame's {@link update} or
  * {@link unadapted} writes over. A pass recorded ahead of that write in the frame reads the factor the last frame was
  * shown with: the exposure of the image on screen, Unreal Engine's `View.PreExposure`.
+ *
+ * Beside it, {@link adaptation}: the luminance the view is adapted to, cd/m², written by the same pass. Adapted, it is
+ * the luminance the eye has adapted to, without {@link exposure_compensation}; unadapted, it is the luminance the
+ * exposure shows at middle grey.
  */
 export class GPUCameraExposureManager {
     /**
@@ -44,9 +48,17 @@ export class GPUCameraExposureManager {
      * imports it into its graph once, and hands the handle both to the passes that read it ahead of the exposure,
      * which take the last frame's factor, and to {@link update} or {@link unadapted}, which write this frame's.
      *
-     * @returns {GPUBuffer} usable as a uniform or read-only storage
+     * @returns {GPUBuffer} usable as a uniform or read-only storage, and as a copy source, to read it back
      */
     get multiplier(): GPUBuffer;
+    /**
+     * The luminance the view is adapted to, cd/m², {@link F32_CONTAINER_STRUCT}, as the last {@link update} or
+     * {@link unadapted} wrote it. Imported into a frame's graph once and handed to {@link update} or {@link unadapted},
+     * like {@link multiplier}.
+     *
+     * @returns {GPUBuffer} usable as a uniform or read-only storage
+     */
+    get adaptation(): GPUBuffer;
     /**
      * Offer the pipelines {@link update} meters and adapts with — see {@link PipelineEnquiry}.
      * {@link unadapted} dispatches none.
@@ -55,34 +67,48 @@ export class GPUCameraExposureManager {
      */
     enquirePipelines(enquiry: PipelineEnquiry): void;
     /**
-     * This frame's factor from {@link exposure_compensation} alone: 2^compensation.
+     * This frame's factor from {@link exposure_compensation} alone: 2^compensation. Its adaptation is the luminance
+     * that factor shows at middle grey, 0.18 / 2^compensation cd/m².
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
-     * @return {number} the handle of {@link multiplier} with this frame's factor written
+     * @param {number} options.adaptation the graph handle of {@link adaptation}, imported into `graph`
+     * @return {{multiplier: number, adaptation: number}} the handles of {@link multiplier} and {@link adaptation}
+     *         with this frame's written; the object is reused by the next call
      */
-    unadapted({ graph, multiplier, }: {
+    unadapted({ graph, multiplier, adaptation, }: {
         graph: FrameGraph;
         multiplier: number;
-    }): number;
+        adaptation: number;
+    }): {
+        multiplier: number;
+        adaptation: number;
+    };
     /**
      * This frame's factor metered from `input_color`: the luminance adapted toward the frame's, from the last
-     * frame's, by the adaptation speeds; its factor is middle grey over it, times 2^{@link exposure_compensation}.
+     * frame's, by the adaptation speeds; its factor is middle grey over it, times 2^{@link exposure_compensation}. Its
+     * adaptation is that adapted luminance, without the compensation.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.input_color
      * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
+     * @param {number} options.adaptation the graph handle of {@link adaptation}, imported into `graph`
      * @param {number} [options.time_delta_seconds]
-     * @return {number} the handle of {@link multiplier} with this frame's factor written
+     * @return {{multiplier: number, adaptation: number}} the handles of {@link multiplier} and {@link adaptation}
+     *         with this frame's written; the object is reused by the next call
      */
-    update({ input_color, graph, multiplier, time_delta_seconds, }: {
+    update({ input_color, graph, multiplier, adaptation, time_delta_seconds, }: {
         graph: FrameGraph;
         input_color: number;
         multiplier: number;
+        adaptation: number;
         time_delta_seconds?: number;
-    }): number;
+    }): {
+        multiplier: number;
+        adaptation: number;
+    };
     #private;
 }
 export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;

package/src/shade/renderer/postprocess/eye/GPUCameraExposureManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUCameraExposureManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/eye/GPUCameraExposureManager.js"],"names":[],"mappings":"AAwBA;;;;;;;GAOG;AACH;IA0DI;;;OAGG;IACH,+BAyBC;IAtED;;;;OAIG;IACH,qBAFU,MAAM,CAEU;IAE1B;;;;OAIG;IACH,uBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,yBAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,uBAFU,MAAM,CAEY;IA4C5B,gBAMC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;OAKG;IACH,0BAFW,eAAe,QAMzB;IAED;;;;;;;OAOG;IACH;QAJ+B,KAAK;QACT,UAAU,EAA1B,MAAM;QACL,MAAM,CAejB;IAoBD;;;;;;;;;;OAUG;IACH;QAN+B,KAAK;QACT,WAAW,EAA3B,MAAM;QACU,UAAU,EAA1B,MAAM;QACW,kBAAkB,GAAnC,MAAM;QACL,MAAM,CAmDjB;;CA2EJ;8BA7TY,OAAO,6CAA6C,EAAE,eAAe"}
+{"version":3,"file":"GPUCameraExposureManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/eye/GPUCameraExposureManager.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;GAWG;AACH;IAuEI;;;OAGG;IACH,+BAoCC;IAlFD;;;;OAIG;IACH,qBAFU,MAAM,CAEU;IAE1B;;;;OAIG;IACH,uBAFU,MAAM,CAEY;IAE5B;;;;;OAKG;IACH,yBAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,uBAFU,MAAM,CAEY;IAwD5B,gBAOC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;OAKG;IACH,0BAFW,eAAe,QAMzB;IAED;;;;;;;;;;OAUG;IACH;QAN+B,KAAK;QACT,UAAU,EAA1B,MAAM;QACU,UAAU,EAA1B,MAAM;QACL;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAwBnD;IAsBD;;;;;;;;;;;;;OAaG;IACH;QAR+B,KAAK;QACT,WAAW,EAA3B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,UAAU,EAA1B,MAAM;QACW,kBAAkB,GAAnC,MAAM;QACL;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CA4DnD;;CA4EJ;8BAnYY,OAAO,6CAA6C,EAAE,eAAe"}

package/src/shade/renderer/postprocess/eye/GPUCameraExposureManager.js

@@ -17,6 +17,11 @@ const HISTOGRAM_DESCRIPTOR = BufferResourceDescriptor.empty(
     GPUBufferUsage.STORAGE,
 );
 
+/**
+ * The luminance an exposure of one shows at middle grey, cd/m²: the scene value the adaptation maps to 0.18.
+ */
+const MIDDLE_GREY = 0.18;
+
 const TARGET_LUMINANCE_DESCRIPTOR = BufferResourceDescriptor.from(
     F32_CONTAINER_STRUCT.size,
     GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM,
@@ -29,6 +34,10 @@ const TARGET_LUMINANCE_DESCRIPTOR = BufferResourceDescriptor.from(
  * The factor lives in one buffer for the manager's life, {@link multiplier}, which a frame's {@link update} or
  * {@link unadapted} writes over. A pass recorded ahead of that write in the frame reads the factor the last frame was
  * shown with: the exposure of the image on screen, Unreal Engine's `View.PreExposure`.
+ *
+ * Beside it, {@link adaptation}: the luminance the view is adapted to, cd/m², written by the same pass. Adapted, it is
+ * the luminance the eye has adapted to, without {@link exposure_compensation}; unadapted, it is the luminance the
+ * exposure shows at middle grey.
  */
 export class GPUCameraExposureManager {
     /**
@@ -47,6 +56,18 @@ export class GPUCameraExposureManager {
      */
     #multiplier;
 
+    /**
+     * {@link F32_CONTAINER_STRUCT}: the adaptation the last {@link update} or {@link unadapted} wrote, cd/m².
+     * @type {GPUTypedBuffer}
+     */
+    #adaptation;
+
+    /**
+     * The handles {@link update} and {@link unadapted} return, kept across frames.
+     * @type {{multiplier: number, adaptation: number}}
+     */
+    #written = { multiplier: -1, adaptation: -1 };
+
     /**
      * How fast do we adapt to brighter environments?
      * in f-stops per second.
@@ -78,15 +99,16 @@ export class GPUCameraExposureManager {
     exposure_compensation = 0.0;
 
     // what each pass's execution reads, kept across frames: a frame records them and runs them before the next does
-    #unadapted_data = { output: -1 };
+    #unadapted_data = { output: -1, adaptation: -1 };
     #unadapted_value = { value: 1.0 };
+    #unadapted_adaptation = { value: MIDDLE_GREY };
     #build_data = { input_color: -1, output: -1 };
     #parse_data = { input_histogram: -1, output: -1 };
-    #adapt_data = { goal: -1, previous: -1, adapted: -1, out_multiplier: -1 };
+    #adapt_data = { goal: -1, previous: -1, adapted: -1, out_multiplier: -1, out_adaptation: -1 };
     #adapt_settings = { speed_up: 0, speed_down: 0, time_delta: 0, exp_transition_distance: 0, compensation: 0 };
     #build_bindings = { tInput: null, histogram: null };
     #parse_bindings = { histogram: null, output: null };
-    #adapt_bindings = { goal: null, previous: null, settings: this.#adapt_settings, adapted: null, out_multiplier: null };
+    #adapt_bindings = { goal: null, previous: null, settings: this.#adapt_settings, adapted: null, out_multiplier: null, out_adaptation: null };
 
     /**
      *
@@ -110,13 +132,24 @@ export class GPUCameraExposureManager {
         this.#multiplier = GPUTypedBuffer.create({
             label: 'exposure multiplier',
             device,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
             type: F32_CONTAINER_STRUCT,
             initial_value: {
                 value: 1.0
             }
         });
 
+        // what a factor of one shows at middle grey, until the first frame writes its own
+        this.#adaptation = GPUTypedBuffer.create({
+            label: 'exposure adaptation',
+            device,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            type: F32_CONTAINER_STRUCT,
+            initial_value: {
+                value: MIDDLE_GREY
+            }
+        });
+
     }
 
     destroy() {
@@ -125,6 +158,7 @@ export class GPUCameraExposureManager {
         }
 
         this.#multiplier.destroy();
+        this.#adaptation.destroy();
     }
 
     /**
@@ -132,12 +166,23 @@ export class GPUCameraExposureManager {
      * imports it into its graph once, and hands the handle both to the passes that read it ahead of the exposure,
      * which take the last frame's factor, and to {@link update} or {@link unadapted}, which write this frame's.
      *
-     * @returns {GPUBuffer} usable as a uniform or read-only storage
+     * @returns {GPUBuffer} usable as a uniform or read-only storage, and as a copy source, to read it back
      */
     get multiplier() {
         return this.#multiplier.buffer;
     }
 
+    /**
+     * The luminance the view is adapted to, cd/m², {@link F32_CONTAINER_STRUCT}, as the last {@link update} or
+     * {@link unadapted} wrote it. Imported into a frame's graph once and handed to {@link update} or {@link unadapted},
+     * like {@link multiplier}.
+     *
+     * @returns {GPUBuffer} usable as a uniform or read-only storage
+     */
+    get adaptation() {
+        return this.#adaptation.buffer;
+    }
+
     /**
      * Offer the pipelines {@link update} meters and adapts with — see {@link PipelineEnquiry}.
      * {@link unadapted} dispatches none.
@@ -151,26 +196,37 @@ export class GPUCameraExposureManager {
     }
 
     /**
-     * This frame's factor from {@link exposure_compensation} alone: 2^compensation.
+     * This frame's factor from {@link exposure_compensation} alone: 2^compensation. Its adaptation is the luminance
+     * that factor shows at middle grey, 0.18 / 2^compensation cd/m².
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
-     * @return {number} the handle of {@link multiplier} with this frame's factor written
+     * @param {number} options.adaptation the graph handle of {@link adaptation}, imported into `graph`
+     * @return {{multiplier: number, adaptation: number}} the handles of {@link multiplier} and {@link adaptation}
+     *         with this frame's written; the object is reused by the next call
      */
     unadapted({
                   graph,
                   multiplier,
+                  adaptation,
               }) {
         assert.defined(graph, 'graph');
         assert.isNonNegativeInteger(multiplier, 'multiplier');
+        assert.isNonNegativeInteger(adaptation, 'adaptation');
 
         const data = this.#unadapted_data;
         const pass = graph.add("unadapted", data, this.#execute_unadapted);
 
         data.output = pass.write(multiplier);
+        data.adaptation = pass.write(adaptation);
+
+        const written = this.#written;
 
-        return data.output;
+        written.multiplier = data.output;
+        written.adaptation = data.adaptation;
+
+        return written;
     }
 
     /**
@@ -186,26 +242,32 @@ export class GPUCameraExposureManager {
 
         // compensation is in f-stops: each stop doubles/halves brightness
         this.#unadapted_value.value = Math.pow(2, this.exposure_compensation);
+        this.#unadapted_adaptation.value = MIDDLE_GREY / this.#unadapted_value.value;
 
         // in the command stream, so a pass recorded ahead of this one still reads the last frame's factor
         encoder.writeValueBuffer(resources.get(data.output), 0, F32_CONTAINER_STRUCT, this.#unadapted_value);
+        encoder.writeValueBuffer(resources.get(data.adaptation), 0, F32_CONTAINER_STRUCT, this.#unadapted_adaptation);
     }
 
     /**
      * This frame's factor metered from `input_color`: the luminance adapted toward the frame's, from the last
-     * frame's, by the adaptation speeds; its factor is middle grey over it, times 2^{@link exposure_compensation}.
+     * frame's, by the adaptation speeds; its factor is middle grey over it, times 2^{@link exposure_compensation}. Its
+     * adaptation is that adapted luminance, without the compensation.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
      * @param {number} options.input_color
      * @param {number} options.multiplier the graph handle of {@link multiplier}, imported into `graph`
+     * @param {number} options.adaptation the graph handle of {@link adaptation}, imported into `graph`
      * @param {number} [options.time_delta_seconds]
-     * @return {number} the handle of {@link multiplier} with this frame's factor written
+     * @return {{multiplier: number, adaptation: number}} the handles of {@link multiplier} and {@link adaptation}
+     *         with this frame's written; the object is reused by the next call
      */
     update({
                input_color,
                graph,
                multiplier,
+               adaptation,
                time_delta_seconds = 0.01666,
            }) {
 
@@ -219,6 +281,7 @@ export class GPUCameraExposureManager {
 
         assert.defined(graph, 'graph');
         assert.isNonNegativeInteger(multiplier, 'multiplier');
+        assert.isNonNegativeInteger(adaptation, 'adaptation');
         assert.isNumber(time_delta_seconds, 'time_delta_seconds');
         assert.greaterThanOrEqual(time_delta_seconds, 0, 'time_delta_seconds');
 
@@ -249,8 +312,14 @@ export class GPUCameraExposureManager {
         adapt_data.previous = adapt_pass.read(graph_import_buffer(graph, exposure_buffer_previous.buffer, "previous adapted luminance"));
         adapt_data.adapted = adapt_pass.write(graph_import_buffer(graph, exposure_buffer_current.buffer, "adapted luminance"));
         adapt_data.out_multiplier = adapt_pass.write(multiplier);
+        adapt_data.out_adaptation = adapt_pass.write(adaptation);
+
+        const written = this.#written;
+
+        written.multiplier = adapt_data.out_multiplier;
+        written.adaptation = adapt_data.out_adaptation;
 
-        return adapt_data.out_multiplier;
+        return written;
     }
 
     /**
@@ -319,6 +388,7 @@ export class GPUCameraExposureManager {
         bindings.previous = resources.get(data.previous);
         bindings.adapted = resources.get(data.adapted);
         bindings.out_multiplier = resources.get(data.out_multiplier);
+        bindings.out_adaptation = resources.get(data.out_adaptation);
 
         shader_autoexposure_adapt.dispatch({
             encoder: context.encoder,

package/src/shade/renderer/postprocess/eye/shader_autoexposure_adapt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_autoexposure_adapt.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/eye/shader_autoexposure_adapt.js"],"names":[],"mappings":"AASA,sDAsBE;AA+FF,sDAIG;6BAjI0B,mCAAmC;8BAElC,+BAA+B"}
+{"version":3,"file":"shader_autoexposure_adapt.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/eye/shader_autoexposure_adapt.js"],"names":[],"mappings":"AASA,sDAsBE;AAkGF,sDAIG;6BApI0B,mCAAmC;8BAElC,+BAA+B"}

package/src/shade/renderer/postprocess/eye/shader_autoexposure_adapt.js

@@ -41,6 +41,7 @@ resources.createGroup()
     .addUniform("previous", F32_CONTAINER_STRUCT)
     .addStorageBuffer("adapted", F32_CONTAINER_STRUCT, true)
     .addStorageBuffer("out_multiplier", F32_CONTAINER_STRUCT, true)
+    .addStorageBuffer("out_adaptation", F32_CONTAINER_STRUCT, true)
 ;
 
 
@@ -64,6 +65,7 @@ fn main(){
     */
     if (!(goal.value > 0.0)) {
         adapted.value = previous.value;
+        out_adaptation.value = previous.value;
 
         out_multiplier.value = (MIDDLE_GREY / current_linear) * exp2(settings.compensation);
 
@@ -113,7 +115,8 @@ fn main(){
     // convert back to linear space
     let new_linear = exp2(new_ev);
     adapted.value = new_linear;
-    
+    out_adaptation.value = new_linear;
+
     // apply final transforms
 
     let shifted = MIDDLE_GREY / adapted.value;

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,65 @@
+/**
+ * How much of the eye's response is the rods', at an adaptation: 1 at and below {@link PURKINJE_MESOPIC_MIN_NITS}, 0 at
+ * and above {@link PURKINJE_MESOPIC_MAX_NITS}, linear in log luminance in between. The share `apply_purkinje_shift`
+ * blends by, for code that needs it on the CPU.
+ *
+ * @param {number} adaptation_luminance cd/m²
+ * @returns {number} 0 to 1
+ */
+export function purkinje_rod_share(adaptation_luminance: 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).
+ */
+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 apply_purkinje_shift(color_rec709: vec3<f32>, adaptation_luminance: f32) -> vec3<f32>
+ * fn purkinje_rod_share(adaptation_luminance: f32) -> f32
+ * ```
+ *
+ * `color_rec709` is scene-linear Rec.709; `adaptation_luminance` is the luminance the eye is adapted to, cd/m². Above
+ * 5 cd/m² the colour is returned as it is; below 0.005 cd/m² it is the rod response alone, its scotopic luminance
+ * carried by a blue tint; in between the two blend linearly in log luminance, by `purkinje_rod_share`. 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":"AAiCA;;;;;;;GAOG;AACH,yDAHW,MAAM,GACJ,MAAM,CAQlB;AA7CD;;;GAGG;AACH,uCAFU,cAAc,MAAM,CAAC,CAEiD;AAEhF;;;;GAIG;AACH,uCAFU,cAAc,MAAM,CAAC,CAEiD;AAEhF;;;;GAIG;AACH,kCAFU,cAAc,MAAM,CAAC,CAEmC;AAElE;;GAEG;AACH,8CAA+C;AAC/C,0CAA2C;AAwC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,yCAFU,SAAS,CAwCjB;0BAvIwB,mCAAmC"}