@woosh/meep-engine 3.11.0 → 3.11.1

package/src/shade/playground/volumetrics_froxel/main.js

@@ -0,0 +1,619 @@
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import {
+    ParticipatingMediaVolume,
+    VolumetricsParticleSpec
+} from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+
+/**
+ * The froxel volumetrics pass, with the controls that make its known defects visible.
+ *
+ * `shader_volumetrics_build_lighting` and the passes around it were reviewed statically and five
+ * correctness findings came out of it (C-01 … C-05). Four are geometric, and geometry is the one
+ * class of defect a unit test can prove but not show: an emulator can assert that a sample lands at
+ * the wrong depth, and it still cannot tell you whether that reads as a smear, a seam, or nothing
+ * at all. This page exists so each fix can be looked at before and after.
+ *
+ * Every control below is aimed at one finding. The panel says which.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/` and resolves the one bare
+ * specifier the renderer reaches for. The panel is hand-rolled for the same reason the Sponza page
+ * hand-rolls its own — a dozen inputs are not worth a dependency the library does not otherwise
+ * have.
+ *
+ * @see src/shade/renderer/volumetrics/NOTES.md
+ */
+
+/**
+ * Served out of `test_assets/`, which is gitignored and unpublished — `test_assets/README.md` has
+ * how it gets there.
+ *
+ * glTF rather than the `.shade` scene sitting next to it: that export's header reads format
+ * version 1 and `deserialize_scene` accepts version 2 only, deliberately and with no backward
+ * compatibility. Re-exporting it is the fix if the `.shade` is ever wanted.
+ *
+ * @type {string}
+ */
+const SCENE_URL = '/test_assets/flying_world_-_battle_of_the_trash_god/v2/scene.gltf';
+
+/**
+ * A low sun, which is what the volumetrics want: it rakes the scene, so the shafts have something
+ * to be cast by, and it sits near the horizon where the sun can be swung in and out of the frustum
+ * without also swinging it behind the terrain.
+ *
+ * @type {string}
+ */
+const ENVIRONMENT_URL = '/test_assets/environments/octahedral/venice_sunset_2k.hdr';
+
+/**
+ * Camera placements carried over from the sibling repo's playground, where they were found by
+ * hand while looking at this exact scene. Keeping the numbers rather than re-deriving them means a
+ * before/after pair is taken from the same place to the pixel.
+ *
+ * The `c` field names the finding each one is good for; the panel groups by it.
+ */
+const VIEWS = [
+    {
+        id: 'overview',
+        label: 'Dead overview',
+        c: 'orientation',
+        hint: 'the whole island — start here',
+        position: { x: -44.23572420730413, y: 16.787419516572818, z: -0.3908097424888902 },
+        rotation: { x: -0.10289617976426199, y: 0.8965686124184902, z: -0.32052909150868936, w: -0.2878162624184363 }
+    },
+    {
+        id: 'vol_0',
+        label: 'Fog bank, wide',
+        c: 'C-01',
+        hint: 'fog fills the frame corners, where the depth error is largest',
+        position: { x: -39.165083083628595, y: 9.002002938463146, z: -12.822321096883556 },
+        rotation: { x: 0.0461501744849993, y: 0.9414711984407541, z: -0.14428237367052793, w: 0.3011390717750397 }
+    },
+    {
+        id: 'vol_1',
+        label: 'Inside the fog',
+        c: 'C-01',
+        hint: 'camera inside the medium — radial thinning shows against a flat wall of fog',
+        position: { x: -57.19543561067503, y: 4.497368033549733, z: -5.431935542965578 },
+        rotation: {
+            x: 0.0012158994167123557,
+            y: 0.9584376528911036,
+            z: -0.0040851224490818586,
+            w: 0.28527022081489145
+        }
+    },
+    {
+        id: 'broadside',
+        label: 'Island broadside',
+        c: 'C-03',
+        hint: 'the island against open sky — the clearest place to swing the sun in and out of frame',
+        position: { x: -30, y: 11, z: -5 },
+        rotation: {
+            x: 0.08308534470573395,
+            y: -0.7022085341941733,
+            z: 0.08308534470573395,
+            w: 0.7022085341941732
+        }
+    },
+    {
+        id: 'above',
+        label: 'Island from above',
+        c: 'C-03',
+        hint: 'all six volumes at once, with sky behind them',
+        position: { x: -18, y: 26, z: 26 },
+        rotation: {
+            x: -0.09605984305376475,
+            y: 0.8751796663464206,
+            z: -0.19438519850844194,
+            w: -0.43248982966896177
+        }
+    },
+    {
+        id: 'cloud_deck',
+        label: 'Inside the cloud deck',
+        c: 'C-01',
+        hint: 'uniform medium filling the frame — radial thinning reads as a vignette here',
+        position: { x: -57, y: -10, z: 20 },
+        rotation: { x: 0, y: 0.9999652844073138, z: 0.008332465433472727, w: 0 }
+    },
+    {
+        id: 'aliasing_0',
+        label: 'Volume edge',
+        c: 'C-02',
+        hint: 'a fog volume boundary against geometry — a half-froxel shift moves this edge',
+        position: { x: -44.358600521646366, y: 8.13976892720825, z: 2.6707745658793725 },
+        rotation: { x: -0.07197787209539422, y: 0.9277035010259875, z: -0.24609398688026018, w: -0.2713358614966388 }
+    },
+    {
+        id: 'aliasing_1',
+        label: 'Volume edge, above',
+        c: 'C-02',
+        hint: 'the same boundary from above, where the slab stack is edge-on',
+        position: { x: -36.56903863396318, y: 19.1017887067011, z: 13.881382214134083 },
+        rotation: { x: -0.0961072760435774, y: 0.9036695806244697, z: -0.3054532939528032, w: -0.28432897453277794 }
+    },
+    {
+        id: 'inside_out',
+        label: 'Under the island',
+        c: 'C-05',
+        hint: 'thin haze over a dark ground — per-froxel noise is most legible here',
+        position: { x: -61.55864473831582, y: 23.7158848700074, z: -19.634434309820563 },
+        rotation: { x: 0.27745576215003553, y: 0.0922110339369582, z: -0.026764015593898134, w: 0.9559284035634205 }
+    },
+];
+
+/**
+ * The participating media, carried over from the sibling repo's setup for this scene. Positions are
+ * tuned to the model, so they move with it and not with anything here.
+ *
+ * `target_extinction` rather than `density`: it normalizes across particle specs, so swapping a
+ * preset changes how the medium *looks* without changing how much light it stops.
+ *
+ * @param {Scene} scene
+ */
+function add_participating_media(scene) {
+
+    /**
+     * @param {object} spec
+     * @param {number[]} spec.position
+     * @param {number[]} spec.scale
+     * @param {object} spec.particle from MIE_PARTICLES_STANDARD_PRECOMPUTED
+     * @param {number} spec.extinction
+     * @param {number} spec.fade
+     * @param {number} [spec.yaw_degrees]
+     */
+    function volume({ position, scale, particle, extinction, fade, yaw_degrees = 0 }) {
+        const v = new ParticipatingMediaVolume();
+
+        v.transform.position.set(...position);
+        v.transform.scale.set(...scale);
+
+        if (yaw_degrees !== 0) {
+            v.transform.rotation.fromAxisAngle(Vector3.up, yaw_degrees * DEG_TO_RAD);
+        }
+
+        v.fade_distance = fade;
+        v.particle_spec = VolumetricsParticleSpec.fromMeep(particle);
+        v.target_extinction = extinction;
+
+        scene.volumetrics.add(v);
+
+        return v;
+    }
+
+    const P = MIE_PARTICLES_STANDARD_PRECOMPUTED;
+
+    // the dense bank along the western edge — the thickest medium in the scene, and the one that
+    // fills the frame corners from the `vol_0` view
+    volume({
+        position: [-55, 4, -5.116],
+        scale: [10, 3, 20],
+        yaw_degrees: 83,
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 1,
+        fade: 0.5,
+    });
+
+    // graveyard
+    volume({
+        position: [-51.98019820725889, 7.899311905935347, -15.3228393616169],
+        scale: [7, 5, 7],
+        particle: P.FOG_DROPLET_SMALL,
+        extinction: 0.4,
+        fade: 1,
+    });
+
+    // mine
+    volume({
+        position: [-50.846390607312934, 0.3159949821015605, 17.89429433940319],
+        scale: [10, 7, 10],
+        particle: P.COARSE_DUST_MEDIUM,
+        extinction: 0.4,
+        fade: 4,
+    });
+
+    // large crystal
+    volume({
+        position: [-53.41918585295826, 17.333878151116526, 29.90844167706601],
+        scale: [18, 10, 18],
+        particle: P.MARITIME_HAZE_MEDIUM,
+        extinction: 0.1,
+        fade: 4,
+    });
+
+    // the low cloud deck the island sits above — big and thin, so it is what a wide FOV sees at the
+    // frame edges
+    volume({
+        position: [-57.36387203979457, -15, 2.607232848593789],
+        scale: [400, 20, 400],
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 0.1,
+        fade: 4,
+    });
+
+    // ball cloud overhead
+    volume({
+        position: [-51.137423384559284, 33, 5.593067265589105],
+        scale: [15, 15, 15],
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 1,
+        fade: 7,
+    });
+}
+
+/**
+ * A rolling mean frame time, so the readout is legible rather than jittering.
+ */
+class FrameTimer {
+    #samples = new Float64Array(60);
+    #count = 0;
+    #cursor = 0;
+
+    add(seconds) {
+        this.#samples[this.#cursor] = seconds * 1000;
+        this.#cursor = (this.#cursor + 1) % this.#samples.length;
+        this.#count = Math.min(this.#count + 1, this.#samples.length);
+    }
+
+    reset() {
+        this.#count = 0;
+        this.#cursor = 0;
+    }
+
+    get mean_ms() {
+        if (this.#count === 0) {
+            return 0;
+        }
+
+        let total = 0;
+        for (let i = 0; i < this.#count; i++) {
+            total += this.#samples[i];
+        }
+        return total / this.#count;
+    }
+}
+
+/**
+ * Point a directional light along a heading, in place.
+ *
+ * The sun's azimuth is the control C-03 turns on: the shadow ray is clipped against a frustum whose
+ * far plane is degenerate, so a sun direction that lies inside the view cone never exits it. Swing
+ * the sun through the frame and the media self-shadowing should be steady; if it switches on as the
+ * sun leaves the frustum, that is the finding.
+ *
+ * @param {DirectionalLight} light
+ * @param {number} azimuth_degrees 0 points along +X
+ * @param {number} elevation_degrees above the horizon
+ */
+function aim_light(light, azimuth_degrees, elevation_degrees) {
+    const azimuth = azimuth_degrees * DEG_TO_RAD;
+    const elevation = elevation_degrees * DEG_TO_RAD;
+
+    const horizontal = Math.cos(elevation);
+
+    // direction the light travels — downward for a sun above the horizon
+    const direction = new Vector3(
+        Math.cos(azimuth) * horizontal,
+        -Math.sin(elevation),
+        Math.sin(azimuth) * horizontal
+    ).normalize();
+
+    const q = new Quaternion();
+    q.fromUnitVectors(Vector3.forward, direction);
+    q.normalize();
+
+    light.transform_local.setRotation(q.x, q.y, q.z, q.w);
+    light.updateMatrices();
+}
+
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const status_element = element('status');
+    const stats_element = element('stats');
+
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    const canvas = element('view');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        set_status('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
+        return;
+    }
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.1;
+    camera.far = 120;
+    camera.fov = 60 * DEG_TO_RAD;
+    // aspect is set by the frame loop, which is the first place the viewport has a size
+
+    const scene = new Scene();
+
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // handy from the console
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.controller = controller;
+
+    // ---- scene ----------------------------------------------------------------------------
+
+    set_status(`loading ${SCENE_URL} …`);
+
+    try {
+        const bundle = await load_gltf(SCENE_URL, { assetManager: await make_playground_asset_manager() });
+
+        scene.add(bundle.scenes);
+    } catch (error) {
+        set_status(
+            `could not load the scene (${error.message}). Put the assets under test_assets/ — `
+            + `see test_assets/README.md.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    const sun = make_sunlight({ intensity: 0.6, temperature: 5500 });
+
+    scene.lights.add(sun);
+
+    add_participating_media(scene);
+
+    load_default_environment(scene, ENVIRONMENT_URL).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    // ---- controls -------------------------------------------------------------------------
+
+    const frame_timer = new FrameTimer();
+
+    let paused = false;
+
+    /** Re-render and drop the frame-time history, since a setting change invalidates it. */
+    function repaint() {
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    }
+
+    // -- views
+
+    const views_element = element('views');
+
+    /** @param {object} view */
+    function go_to(view) {
+        camera.transform.fromJSON({ position: view.position, rotation: view.rotation });
+
+        // the controller holds its own spherical state and would otherwise snap the camera back on
+        // the next update
+        controller.from_transform(camera.transform);
+
+        repaint();
+    }
+
+    for (const view of VIEWS) {
+        const button = document.createElement('button');
+
+        button.className = 'view';
+        button.title = view.hint;
+        button.innerHTML = `<span class="tag">${view.c}</span>${view.label}`;
+        button.addEventListener('click', () => {
+            go_to(view);
+            set_status(view.hint);
+        });
+
+        views_element.appendChild(button);
+    }
+
+    // -- sun
+
+    let sun_azimuth = 200;
+    let sun_elevation = 12;
+
+    function update_sun() {
+        aim_light(sun, sun_azimuth, sun_elevation);
+
+        element('sun_azimuth_value').textContent = `${sun_azimuth}°`;
+        element('sun_elevation_value').textContent = `${sun_elevation}°`;
+
+        repaint();
+    }
+
+    element('sun_azimuth').addEventListener('input', event => {
+        sun_azimuth = Number(event.target.value);
+        update_sun();
+    });
+
+    element('sun_elevation').addEventListener('input', event => {
+        sun_elevation = Number(event.target.value);
+        update_sun();
+    });
+
+    /**
+     * Put the sun directly in front of the camera, or directly behind it, at the current elevation.
+     *
+     * This is the C-03 A/B reduced to two clicks. "Into view" places the sun's direction inside the
+     * frustum's direction cone, which is the condition under which `frustum_clip_ray` returns its
+     * 1e20 sentinel.
+     *
+     * @param {boolean} in_front
+     */
+    function aim_sun_relative_to_camera(in_front) {
+        // Straight off the view matrix rather than by rotating a basis vector through the camera's
+        // quaternion by hand: the third row of a view matrix is the camera's backward axis, so this
+        // is the renderer's own answer and cannot disagree with what is on screen. The hand-rolled
+        // version this replaces had a sign error that put the sun behind the camera on both
+        // branches, which is invisible in a screenshot and made the C-03 A/B read as a null result.
+        // The matrices are rebuilt during render, so a placement made this tick is not in them yet
+        // — reading straight after `go_to` would aim the sun at wherever the camera used to be.
+        camera.update();
+
+        const vm = camera.view_matrix;
+
+        const forward_x = -vm[2];
+        const forward_z = -vm[10];
+
+        // `aim_light` takes the direction light *travels*, so the sun sits opposite it. Placing the
+        // sun on the camera's forward axis therefore means aiming its travel back along that axis.
+        const toward_sun_x = in_front ? forward_x : -forward_x;
+        const toward_sun_z = in_front ? forward_z : -forward_z;
+
+        const azimuth = Math.atan2(-toward_sun_z, -toward_sun_x) / DEG_TO_RAD;
+
+        sun_azimuth = Math.round((azimuth % 360 + 360) % 360);
+
+        element('sun_azimuth').value = String(sun_azimuth);
+
+        update_sun();
+    }
+
+    element('sun_into_view').addEventListener('click', () => {
+        aim_sun_relative_to_camera(true);
+        set_status('sun placed in front of the camera — C-03 predicts media self-shadowing vanishes here', 'warn');
+    });
+
+    element('sun_behind').addEventListener('click', () => {
+        aim_sun_relative_to_camera(false);
+        set_status('sun placed behind the camera — C-03 predicts media self-shadowing returns here', 'pass');
+    });
+
+    // -- camera
+
+    element('fov').addEventListener('input', event => {
+        const degrees = Number(event.target.value);
+
+        camera.fov = degrees * DEG_TO_RAD;
+
+        element('fov_value').textContent = `${degrees}°`;
+
+        repaint();
+    });
+
+    // -- volumetrics knobs, read by GPUViewVolumetrics on every metadata update
+
+    element('vol_taa').addEventListener('change', event => {
+        globalThis.__VOL_TAA_ENABLED = event.target.checked;
+        repaint();
+    });
+
+    element('taa').addEventListener('change', event => {
+        renderer.feature_taa_enabled = event.target.checked;
+        repaint();
+    });
+
+    // Off by default on this page. Auto exposure keeps adapting for seconds after anything changes,
+    // which makes a before/after pair differ by more than most of the fixes being judged here do —
+    // it read as a large effect with the wrong sign more than once while this page was being built.
+    renderer.feature_automatic_exposure_enabled = false;
+
+    element('auto_exposure').addEventListener('change', event => {
+        renderer.feature_automatic_exposure_enabled = event.target.checked;
+        repaint();
+    });
+
+    element('froxel_far').addEventListener('input', event => {
+        const value = Number(event.target.value);
+
+        // the slider's top notch means "no split", which is the engine default
+        globalThis.__VOL_FROXEL_FAR = value >= 120 ? Infinity : value;
+
+        element('froxel_far_value').textContent = value >= 120 ? 'off' : `${value} m`;
+
+        repaint();
+    });
+
+    element('ms_octaves').addEventListener('input', event => {
+        const value = Number(event.target.value);
+
+        globalThis.__VOL_MS_OCTAVES = value;
+
+        element('ms_octaves_value').textContent = String(value);
+
+        repaint();
+    });
+
+    element('pause').addEventListener('click', () => {
+        paused = !paused;
+        element('pause').textContent = paused ? 'Resume' : 'Pause';
+    });
+
+    element('log_camera').addEventListener('click', () => {
+        const t = camera.transform;
+
+        const json = {
+            position: { x: t.position.x, y: t.position.y, z: t.position.z },
+            rotation: { x: t.rotation.x, y: t.rotation.y, z: t.rotation.z, w: t.rotation.w }
+        };
+
+        console.log(JSON.stringify(json, null, 4));
+        set_status('camera written to the console', 'pass');
+    });
+
+    // ---- start ----------------------------------------------------------------------------
+
+    update_sun();
+    go_to(VIEWS[0]);
+
+    controller.movement_speed_scale = 4;
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    set_status(`loaded — ${scene.instances.instances.length} instances, ${scene.volumetrics.volumes.length} media volumes`, 'pass');
+
+    // ---- frame loop -----------------------------------------------------------------------
+
+    const FRAME_RATE_LIMIT = 60;
+
+    create_frame_loop(time_delta_s => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+
+        if (paused) {
+            return;
+        }
+
+        renderer.render(camera, scene, time_delta_s);
+
+        frame_timer.add(time_delta_s);
+
+        const mean = frame_timer.mean_ms;
+
+        stats_element.textContent =
+            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps`
+            + `  ·  fov ${Math.round(camera.fov / DEG_TO_RAD)}°`;
+    }, FRAME_RATE_LIMIT);
+}

package/src/shade/renderer/Renderer.d.ts

@@ -48,6 +48,19 @@ export class Renderer {
     feature_tetrahedron_point_shadows: boolean;
     feature_bloom_enabled: boolean;
     feature_automatic_exposure_enabled: boolean;
+    set exposure_compensation(arg: number);
+    /**
+     * Fixed exposure, in f-stops, used when {@link feature_automatic_exposure_enabled} is off.
+     *
+     * Turning adaptation off without being able to set this leaves the frame at 2 stops, which is
+     * black for any scene the eye would otherwise have opened up for — so the flag alone is not
+     * usable. Anything comparing two renders wants adaptation off and this pinned: eye adaptation
+     * keeps drifting for seconds after a change, which makes two shots of the *same* setting differ
+     * by more than the change being judged.
+     *
+     * @returns {number}
+     */
+    get exposure_compensation(): number;
     /**
      * Virtual texture streaming (opt-in per material via
      * {@link StandardShadeMaterial#vt_stack}). This flag is the system-wide

package/src/shade/renderer/Renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"AA4FA;IAOI,0BAEC;IAED;;OAEG;IACH,0BAAQ;IAER;;;;;;OAMG;IACH,kDAEC;IAED;;OAEG;IACH,kBAAO;IAYP;;;OAGG;IACH,2BAEC;IAaD,0CAGC;IAED,uCAEC;IAED;;;;OAIG;IACH,wBAFU,yBAAyB,CAEoB;IAEvD,6BAA4B;IAC5B,8BAA4B;IAC5B;;;;OAIG;IACH,mCAAkC;IAClC;;;;;;;OAOG;IACH,mCAFU,OAAO,CAEyB;IAC1C,+BAA6B;IAC7B,4CAA0C;IAE1C;;;;;;;OAOG;IACH,0BAFU,OAAO,CAEe;IAQhC;;;;;OAKG;IACH,sCAOC;IAjBD,mCAEC;IAiBD;;;;;;;;;OASG;IACH,6BAFU,OAAO,CAEmB;IAWpC;;;;;OAKG;IACH,8BAA+C;IAE/C;;;;;;;;OAQG;IACH,6BAFU,OAAO,CAEmB;IAEpC;;;;;;;;;;;;;;OAcG;IACH,8BAFU,OAAO,CAEoB;IAErC;;;;;;;;;;OAUG;IACH,qBAFU,OAAO,CAEW;IAU5B;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;;;;;OAQG;IACH,eAFU,UAAU,GAAC,QAAQ,CAEF;IAU3B;;;;OAIG;IACH,gCAAwD;IAExD;;;;;;;;;;;;OAYG;IACH,gBAFU,OAAO,CAEK;IAEtB;;;OAGG;IACH,4BAFU,OAAO,CAEiB;IAKlC;;;OAGG;IACH,yBAEC;IAOD;;;OAGG;IACH,gCAEC;IAcD;;;;;;;;;OASG;IACH,qBAA+B;IAE/B,wBAA+B;IAE/B;;;OAGG;IACH,kBAA4B;IAiB5B;;;OAGG;IACH,2CAeC;IAED;;;OAGG;IACH,wCAEC;IA0BD;;;OAGG;IACH,iCAEC;IAED;;;;OAIG;IACH,2BAEC;IAQD;;;OAGG;IACH,+CAIC;IAED;;;OAGG;IACH,gDAIC;IAwCD;;;OAGG;IACH,6BAcC;IA1BD;;;OAGG;IACH,0BAEC;IA4BD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAFU,oBAAkB,IAAI,CAET;IAEvB;;OAEG;IACH;;;;;;;;;;;;;;OAcG;IACH,2DAEC;IAED;;;;;OAKG;IACH,8CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,UAAU,GACR,MAAM,CAIlB;IAGD,sCAIC;IAeD;;;;OAIG;IACH,iCAFY,gBAAgB,CAW3B;IAED;;;OAGG;IACH,6BAYC;IAED;;;;OAIG;IACH,wCAFa,2BAA2B,CAcvC;IAGD;;;OAGG;IACH,+BAuBC;IAmMD;;;;OAIG;IACH,0BAEC;IAgBD;;;;;;OAMG;IACH,cAFU,iBAAiB,CAEU;IAErC;;;;;;OAMG;IACH,eAgBC;IAiFD;;;;;OAKG;IACH,+EA0NC;IAED;;OAEG;IACH,gBAGC;IAQD,4BAwBC;IAqID;;;;;OAKG;IACH,UAHW,MAAM,KACN,MAAM,QAgBhB;IAoFD,0CAMC;IAED;;;;;;;;;;OAUG;IACH,qEAHW,MAAM,GACJ,OAAO,CAsBnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,8EAJW,MAAM,UACN,iBAAiB,GACf,OAAO,CA62BnB;;CACJ;6BAh5E4B,yBAAyB;0CACZ,gCAAgC;2BAL/C,yCAAyC;6BACvC,4CAA4C;8BAC3C,2CAA2C;4BAc7C,uBAAuB;gCA1BnB,sBAAsB;mBAjDnC,oCAAoC;oBACnC,4BAA4B;kCAuEd,gCAAgC;2BAvCvC,2BAA2B;iCAoCrB,0CAA0C;4CAvB/B,+DAA+D;yBA7BlF,yBAAyB;kCAgDhB,wBAAwB;oBAVtC,0BAA0B;uCAJP,sDAAsD"}
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"AA4FA;IAOI,0BAEC;IAED;;OAEG;IACH,0BAAQ;IAER;;;;;;OAMG;IACH,kDAEC;IAED;;OAEG;IACH,kBAAO;IAYP;;;OAGG;IACH,2BAEC;IAaD,0CAGC;IAED,uCAEC;IAED;;;;OAIG;IACH,wBAFU,yBAAyB,CAEoB;IAEvD,6BAA4B;IAC5B,8BAA4B;IAC5B;;;;OAIG;IACH,mCAAkC;IAClC;;;;;;;OAOG;IACH,mCAFU,OAAO,CAEyB;IAC1C,+BAA6B;IAC7B,4CAA0C;IAkB1C,uCAKC;IArBD;;;;;;;;;;OAUG;IACH,oCAGC;IASD;;;;;;;OAOG;IACH,0BAFU,OAAO,CAEe;IAQhC;;;;;OAKG;IACH,sCAOC;IAjBD,mCAEC;IAiBD;;;;;;;;;OASG;IACH,6BAFU,OAAO,CAEmB;IAWpC;;;;;OAKG;IACH,8BAA+C;IAE/C;;;;;;;;OAQG;IACH,6BAFU,OAAO,CAEmB;IAEpC;;;;;;;;;;;;;;OAcG;IACH,8BAFU,OAAO,CAEoB;IAErC;;;;;;;;;;OAUG;IACH,qBAFU,OAAO,CAEW;IAU5B;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;;;;;OAQG;IACH,eAFU,UAAU,GAAC,QAAQ,CAEF;IAU3B;;;;OAIG;IACH,gCAAwD;IAExD;;;;;;;;;;;;OAYG;IACH,gBAFU,OAAO,CAEK;IAEtB;;;OAGG;IACH,4BAFU,OAAO,CAEiB;IAKlC;;;OAGG;IACH,yBAEC;IAOD;;;OAGG;IACH,gCAEC;IAcD;;;;;;;;;OASG;IACH,qBAA+B;IAE/B,wBAA+B;IAE/B;;;OAGG;IACH,kBAA4B;IAiB5B;;;OAGG;IACH,2CAeC;IAED;;;OAGG;IACH,wCAEC;IA0BD;;;OAGG;IACH,iCAEC;IAED;;;;OAIG;IACH,2BAEC;IAQD;;;OAGG;IACH,+CAIC;IAED;;;OAGG;IACH,gDAIC;IAwCD;;;OAGG;IACH,6BAcC;IA1BD;;;OAGG;IACH,0BAEC;IA4BD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAFU,oBAAkB,IAAI,CAET;IAEvB;;OAEG;IACH;;;;;;;;;;;;;;OAcG;IACH,2DAEC;IAED;;;;;OAKG;IACH,8CAFa,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,UAAU,GACR,MAAM,CAIlB;IAGD,sCAIC;IAeD;;;;OAIG;IACH,iCAFY,gBAAgB,CAW3B;IAED;;;OAGG;IACH,6BAYC;IAED;;;;OAIG;IACH,wCAFa,2BAA2B,CAcvC;IAGD;;;OAGG;IACH,+BAuBC;IAmMD;;;;OAIG;IACH,0BAEC;IAgBD;;;;;;OAMG;IACH,cAFU,iBAAiB,CAEU;IAErC;;;;;;OAMG;IACH,eAgBC;IAiFD;;;;;OAKG;IACH,+EA0NC;IAED;;OAEG;IACH,gBAGC;IAQD,4BAwBC;IAqID;;;;;OAKG;IACH,UAHW,MAAM,KACN,MAAM,QAgBhB;IAoFD,0CAMC;IAED;;;;;;;;;;OAUG;IACH,qEAHW,MAAM,GACJ,OAAO,CAsBnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,8EAJW,MAAM,UACN,iBAAiB,GACf,OAAO,CA62BnB;;CACJ;6BAv6E4B,yBAAyB;0CACZ,gCAAgC;2BAL/C,yCAAyC;6BACvC,4CAA4C;8BAC3C,2CAA2C;4BAc7C,uBAAuB;gCA1BnB,sBAAsB;mBAjDnC,oCAAoC;oBACnC,4BAA4B;kCAuEd,gCAAgC;2BAvCvC,2BAA2B;iCAoCrB,0CAA0C;4CAvB/B,+DAA+D;yBA7BlF,yBAAyB;kCAgDhB,wBAAwB;oBAVtC,0BAA0B;uCAJP,sDAAsD"}

package/src/shade/renderer/Renderer.js

@@ -187,6 +187,29 @@ export class Renderer {
     feature_bloom_enabled = true;
     feature_automatic_exposure_enabled = true;
 
+    /**
+     * Fixed exposure, in f-stops, used when {@link feature_automatic_exposure_enabled} is off.
+     *
+     * Turning adaptation off without being able to set this leaves the frame at 2 stops, which is
+     * black for any scene the eye would otherwise have opened up for — so the flag alone is not
+     * usable. Anything comparing two renders wants adaptation off and this pinned: eye adaptation
+     * keeps drifting for seconds after a change, which makes two shots of the *same* setting differ
+     * by more than the change being judged.
+     *
+     * @returns {number}
+     */
+    get exposure_compensation() {
+        // the manager is built in initialize(); before that there is no value to report
+        return this.#autoexposure === undefined ? 0 : this.#autoexposure.exposure_compensation;
+    }
+
+    set exposure_compensation(v) {
+        assert.isNumber(v, 'exposure_compensation');
+        assert.defined(this.#autoexposure, 'autoexposure (set exposure_compensation after initialize)');
+
+        this.#autoexposure.exposure_compensation = v;
+    }
+
     /**
      * Virtual texture streaming (opt-in per material via
      * {@link StandardShadeMaterial#vt_stack}). This flag is the system-wide