@woosh/meep-engine 3.64.1 → 3.67.0

package/src/shade/renderer/grass/surface/shader_grass_surface_want.js

@@ -0,0 +1,251 @@
+import { CAMERA_RESOURCE } from "../../camera/CAMERA_RESOURCE.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { chunk_slot_stack } from "../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
+import { SCENE_DATABASE_RESOURCE } from "../../scene/SCENE_DATABASE_RESOURCE.js";
+import { chunk_aabb3_from_transformed_corners } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_from_transformed_corners.js";
+import { chunk_aabb3_intersects_frustum } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_lower_bound_branchless } from "../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_grass_directory } from "./chunk_grass_directory.js";
+import { chunk_grass_surface_frame } from "./chunk_grass_surface_frame.js";
+import { chunk_grass_surface_window } from "./chunk_grass_surface_window.js";
+import {
+    GRASS_COLUMN_CROSSINGS,
+    GRASS_POOL_FREE_COUNT,
+    GRASS_POOL_STARVED,
+    GRASS_SLOT_HEIGHT_MAX,
+    GRASS_SLOT_HEIGHT_MIN,
+    GRASS_SLOT_LAYER_COUNT,
+    GRASS_SLOT_LEVEL_LAYER,
+    GRASS_SLOT_NORMAL_SPREAD,
+    GRASS_SLOT_STATE,
+    GRASS_SLOT_STATE_BAKED,
+    GRASS_SLOT_STATE_ORPHAN,
+    GRASS_SLOT_STATE_PENDING,
+    GRASS_SLOT_STATE_STALE,
+    GRASS_SLOT_SURFACE,
+    GRASS_SLOT_SURFEL_COUNT,
+    GRASS_SLOT_TILE_X,
+    GRASS_SLOT_TILE_Z,
+    GRASS_SLOT_WANTED_FRAME
+} from "./GRASS_SURFACE.js";
+import {
+    GRASS_DIRECTORY_RESOURCE,
+    GRASS_POOL_RESOURCE,
+    GRASS_SURFACE_VIEW_SETTINGS,
+    GRASS_SURFACES_RESOURCE
+} from "./GRASS_SURFACE_VIEW.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", GRASS_SURFACE_VIEW_SETTINGS);
+
+resources.createGroup()
+    .add(CAMERA_RESOURCE)
+    .add(SCENE_DATABASE_RESOURCE)
+    .add(GRASS_SURFACES_RESOURCE)
+    .addStorageBuffer("prefix_sums", COLLECTION_U32_STRUCT_READ)
+    .add(GRASS_POOL_RESOURCE)
+    .add(GRASS_DIRECTORY_RESOURCE)
+    .addStorageBuffer("grass_free", WebGPUArray.u32, true)
+    .addStorageBuffer("grass_jobs", COLLECTION_U32_STRUCT_WRITE, true);
+
+/**
+ * Asks for the tiles of the grass surfaces a view wants, a thread a tile of a window
+ * ({@link shader_grass_surface_window_count}, whose counts, summed, are `prefix_sums`).
+ *
+ * A thread finds its level of its surface from the sums and its tile from its place among that window's
+ * threads. A tile outside its level's ring (`grass_tile_wanted`) or outside the view's frustum is not
+ * wanted, and the thread ends.
+ *
+ * **A wanted tile's layers.** Layer 0 always; and once layer 0 is baked, the layers past it that its record
+ * counts. For each:
+ *
+ * - held by a slot (`grass_directory_find`): the slot's record is stamped with the frame. A stale slot also
+ *   takes a place in the frame's bake list, with what a bake gathers into its record reset, and keeps its
+ *   state: it reads as it was until the bake has run;
+ * - not held: the thread takes a place in the frame's bake list (`grass_jobs`, at most `job_capacity`
+ *   places, a count that keeps rising past them) and a slot off the free stack, writes the slot's record
+ *   for the layer, pending, and lists it in the directory. With the bake list full the layer waits for a
+ *   later frame. With no slot free the place holds `GRASS_SLOT_NONE` and the pool's starved count rises.
+ *   A slot the directory has no room for is marked an orphan and its place holds `GRASS_SLOT_NONE`.
+ *
+ * Every thread's layers are its own, so no two threads of a dispatch ask for the same one; two views ask
+ * in two dispatches, and the second finds what the first took.
+ *
+ * Dispatched through `shader_prefix_sum_to_command`'s folded command.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_grass_surface_want = ComputeShader.from({
+    label: "Grass Surface Want",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+// what a bake counts and gathers into a slot's record, as a bake is to find it
+fn grass_slot_reset_bake(record: u32) {
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_LAYER_COUNT}u], 0u);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_SURFEL_COUNT}u], 0u);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_HEIGHT_MIN}u], 0xFFFFFFFFu);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_HEIGHT_MAX}u], 0u);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_NORMAL_SPREAD}u], 0u);
+}
+
+// stamp the layer's slot as wanted, or take a slot and a place in the bake for it; the slot that holds it, or none yet
+fn grass_want_layer(surface: u32, level: u32, layer: u32, tile: vec2<i32>) -> u32 {
+    let level_layer = level | (layer << 8u);
+
+    let held = grass_directory_find(surface, level_layer, tile);
+
+    if (held != GRASS_SLOT_NONE) {
+        let record = grass_slot_record(held);
+
+        atomicStore(&grass_pool[record + ${GRASS_SLOT_WANTED_FRAME}u], settings.frame);
+
+        if (atomicLoad(&grass_pool[record + ${GRASS_SLOT_STATE}u]) == ${GRASS_SLOT_STATE_STALE}u) {
+            // baked again where it is, once the frame's bake has a place for it; until then it reads as it was
+            let place = atomicAdd(&grass_jobs.count, 1u);
+
+            if (place < settings.job_capacity) {
+                grass_slot_reset_bake(record);
+
+                grass_jobs.elements[place] = held;
+            }
+        }
+
+        return held;
+    }
+
+    let place = atomicAdd(&grass_jobs.count, 1u);
+
+    if (place >= settings.job_capacity) {
+        return GRASS_SLOT_NONE;
+    }
+
+    let slot = slot_stack_pop(&grass_pool[${GRASS_POOL_FREE_COUNT}u], &grass_free, settings.slot_capacity);
+
+    grass_jobs.elements[place] = slot;
+
+    if (slot == SLOT_STACK_NONE) {
+        atomicAdd(&grass_pool[${GRASS_POOL_STARVED}u], 1u);
+
+        return GRASS_SLOT_NONE;
+    }
+
+    let record = grass_slot_record(slot);
+
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_SURFACE}u], surface);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_LEVEL_LAYER}u], level_layer);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_TILE_X}u], bitcast<u32>(tile.x));
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_TILE_Z}u], bitcast<u32>(tile.y));
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_STATE}u], ${GRASS_SLOT_STATE_PENDING}u);
+    atomicStore(&grass_pool[record + ${GRASS_SLOT_WANTED_FRAME}u], settings.frame);
+
+    grass_slot_reset_bake(record);
+
+    if (!grass_directory_insert(surface, level_layer, tile, slot)) {
+        atomicStore(&grass_pool[record + ${GRASS_SLOT_STATE}u], ${GRASS_SLOT_STATE_ORPHAN}u);
+
+        grass_jobs.elements[place] = GRASS_SLOT_NONE;
+
+        return GRASS_SLOT_NONE;
+    }
+
+    return slot;
+}
+
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = folded_workgroup_index(workgroup_id) * ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u + lane;
+
+    // the sums are inclusive: a thread belongs to the first window whose sum is past it
+    let windows = prefix_sums.count;
+    let index = lower_bound_branchless(&prefix_sums.elements, thread + 1u, windows);
+
+    if (index >= windows) {
+        return;
+    }
+
+    var place = thread;
+
+    if (index > 0u) {
+        place -= prefix_sums.elements[index - 1u];
+    }
+
+    let surface = grass_surfaces[index / settings.level_count];
+    let level = index % settings.level_count;
+
+    let frame = grass_surface_frame(${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, surface.node));
+    let eye = grass_world_to_frame(frame, camera.transform[3].xyz);
+
+    let window = grass_surface_window(settings, surface, level, eye);
+
+    let tile = window.corner + vec2<i32>(i32(place % window.size.x), i32(place / window.size.x));
+
+    let tile_box = grass_tile_box(settings, surface, level, tile);
+
+    if (!grass_tile_wanted(settings, surface, level, tile_box, eye)) {
+        return;
+    }
+
+    // where the tile's grass can be, against the view's frustum
+    let low = tile_box.low;
+    let high = tile_box.high;
+
+    let box = aabb3_from_transformed_corners(array<vec3<f32>, 8>(
+        vec3<f32>(low.x, low.y, low.z),
+        vec3<f32>(high.x, low.y, low.z),
+        vec3<f32>(low.x, high.y, low.z),
+        vec3<f32>(high.x, high.y, low.z),
+        vec3<f32>(low.x, low.y, high.z),
+        vec3<f32>(high.x, low.y, high.z),
+        vec3<f32>(low.x, high.y, high.z),
+        vec3<f32>(high.x, high.y, high.z),
+    ), frame);
+
+    if (!aabb3_intersects_frustum(box, camera.frustum)) {
+        return;
+    }
+
+    let top = grass_want_layer(surface.node, level, 0u, tile);
+
+    if (top == GRASS_SLOT_NONE) {
+        return;
+    }
+
+    let record = grass_slot_record(top);
+
+    if (atomicLoad(&grass_pool[record + ${GRASS_SLOT_STATE}u]) != ${GRASS_SLOT_STATE_BAKED}u) {
+        return;
+    }
+
+    // a tile has no more layers than a column's walk has crossings
+    let layers = min(atomicLoad(&grass_pool[record + ${GRASS_SLOT_LAYER_COUNT}u]), ${GRASS_COLUMN_CROSSINGS}u);
+
+    for (var layer = 1u; layer < layers; layer++) {
+        grass_want_layer(surface.node, level, layer, tile);
+    }
+}
+`, [
+            chunk_folded_workgroup_index,
+            chunk_lower_bound_branchless,
+            chunk_slot_stack,
+            chunk_aabb3_from_transformed_corners,
+            chunk_aabb3_intersects_frustum,
+            chunk_grass_surface_frame,
+            chunk_grass_surface_window,
+            chunk_grass_directory,
+            TRANSFORMS_TABLE.chunk_read_field('global'),
+        ]),
+});

package/src/shade/renderer/grass/surface/shader_grass_surface_window_count.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Threads in a workgroup of {@link shader_grass_surface_window_count}.
+ *
+ * @type {number}
+ */
+export const GRASS_SURFACE_WINDOW_COUNT_WORKGROUP_SIZE: number;
+/**
+ * Counts the tiles a view may want of each level of each grass surface, a thread a level of a surface.
+ *
+ * Thread `s * level_count + l` writes how many tiles the window of level `l` of surface `s` has
+ * (`grass_surface_window`) to `grass_window_counts.elements` at its own index, and thread 0 writes how many
+ * counts there are to `grass_window_counts.count`. Threads past `surface_count * level_count` write nothing,
+ * so the dispatch covers that many threads and need not be exact.
+ *
+ * The counts are what a prefix scan turns into a thread a tile for {@link shader_grass_surface_want}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_grass_surface_window_count: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_grass_surface_window_count.d.ts.map

package/src/shade/renderer/grass/surface/shader_grass_surface_window_count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_grass_surface_window_count.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/grass/surface/shader_grass_surface_window_count.js"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wDAFU,MAAM,CAE4C;AAY5D;;;;;;;;;;;GAWG;AACH,gDAFU,aAAa,CAoCpB;8BArE2B,+BAA+B"}

package/src/shade/renderer/grass/surface/shader_grass_surface_window_count.js

@@ -0,0 +1,75 @@
+import { CAMERA_RESOURCE } from "../../camera/CAMERA_RESOURCE.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { TRANSFORMS_TABLE } from "../../scene/chunk_scene_database_access.js";
+import { SCENE_DATABASE_RESOURCE } from "../../scene/SCENE_DATABASE_RESOURCE.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_grass_surface_frame } from "./chunk_grass_surface_frame.js";
+import { chunk_grass_surface_window } from "./chunk_grass_surface_window.js";
+import { GRASS_SURFACE_VIEW_SETTINGS, GRASS_SURFACES_RESOURCE } from "./GRASS_SURFACE_VIEW.js";
+
+/**
+ * Threads in a workgroup of {@link shader_grass_surface_window_count}.
+ *
+ * @type {number}
+ */
+export const GRASS_SURFACE_WINDOW_COUNT_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", GRASS_SURFACE_VIEW_SETTINGS);
+
+resources.createGroup()
+    .add(CAMERA_RESOURCE)
+    .add(SCENE_DATABASE_RESOURCE)
+    .add(GRASS_SURFACES_RESOURCE)
+    .addStorageBuffer("grass_window_counts", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * Counts the tiles a view may want of each level of each grass surface, a thread a level of a surface.
+ *
+ * Thread `s * level_count + l` writes how many tiles the window of level `l` of surface `s` has
+ * (`grass_surface_window`) to `grass_window_counts.elements` at its own index, and thread 0 writes how many
+ * counts there are to `grass_window_counts.count`. Threads past `surface_count * level_count` write nothing,
+ * so the dispatch covers that many threads and need not be exact.
+ *
+ * The counts are what a prefix scan turns into a thread a tile for {@link shader_grass_surface_want}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_grass_surface_window_count = ComputeShader.from({
+    label: "Grass Surface Window Count",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${GRASS_SURFACE_WINDOW_COUNT_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let index = id.x;
+    let total = settings.surface_count * settings.level_count;
+
+    if (index == 0u) {
+        grass_window_counts.count = total;
+    }
+
+    if (index >= total) {
+        return;
+    }
+
+    let surface = grass_surfaces[index / settings.level_count];
+    let level = index % settings.level_count;
+
+    let frame = grass_surface_frame(${TRANSFORMS_TABLE.marshalling_method_read_field('global')}(&scene_database, surface.node));
+    let eye = grass_world_to_frame(frame, camera.transform[3].xyz);
+
+    let window = grass_surface_window(settings, surface, level, eye);
+
+    grass_window_counts.elements[index] = window.size.x * window.size.y;
+}
+`, [
+            chunk_grass_surface_frame,
+            chunk_grass_surface_window,
+            TRANSFORMS_TABLE.chunk_read_field('global'),
+        ]),
+});

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,