@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/Renderer.js

@@ -14,13 +14,21 @@ import { WebGPUExtensionType } from "../descriptor/WebGPUExtensionType.js";
 import { SHADE_DEVICE_FLOOR } from "../device/SHADE_DEVICE_FLOOR.js";
 import { shade_device_floor_unmet } from "../device/shade_device_floor_unmet.js";
 import { ShadeDeviceFailure } from "../device/ShadeDeviceFailure.js";
+import { PipelineEnquiry } from "../device/pipeline/PipelineEnquiry.js";
 import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
 import { CameraManager } from "./camera/CameraManager.js";
 import { shader_background } from "./deferred/shader_background.js";
 import { shader_composite_volumetrics } from "./deferred/shader_composite_volumetrics.js";
-import { shader_deferred_main, shader_deferred_main_restir } from "./deferred/shader_deferred_main.js";
+import { shader_deferred_main } from "./deferred/shader_deferred_main.js";
+import { LOCAL_LIGHT_SHADING } from "./deferred/LOCAL_LIGHT_SHADING.js";
+import { LocalLightShading } from "./deferred/LocalLightShading.js";
 import { shader_tonemap_HDR } from "./deferred/shader_tonemap_HDR.js";
+import { shader_tonemap_HDR_none } from "./deferred/shader_tonemap_HDR_none.js";
+import { shader_tonemap_HDR_pbr_neutral } from "./deferred/shader_tonemap_HDR_pbr_neutral.js";
 import { shader_tonemap_LDR } from "./deferred/shader_tonemap_LDR.js";
+import { shader_tonemap_LDR_none } from "./deferred/shader_tonemap_LDR_none.js";
+import { shader_tonemap_LDR_pbr_neutral } from "./deferred/shader_tonemap_LDR_pbr_neutral.js";
+import { TonemapDisplaySettings } from "./deferred/TonemapDisplaySettings.js";
 import { FrameContext } from "./extension/FrameContext.js";
 import { FramePhase } from "./extension/FramePhase.js";
 import { GBufferTextures } from "./extension/GBufferTextures.js";
@@ -40,9 +48,15 @@ import { GPULightProbeVolumeRenderer } from "./global_illumination/lpv/bake/GPUL
 import { shader_diffuse_LPV } from "./global_illumination/lpv/shader_diffuse_LPV.js";
 import { shader_resolve_indirect_lighting } from "./global_illumination/shader_resolve_indirect_lighting.js";
 import { GraphicsContext } from "./GraphicsContext.js";
-import { graph_build_light_clusters } from "./light/cluster/graph_build_light_clusters.js";
+import {
+    enquire_build_light_clusters_pipelines,
+    graph_build_light_clusters
+} from "./light/cluster/graph_build_light_clusters.js";
 import { AccumulatingPathTracer } from "./path_tracer/accumulating/AccumulatingPathTracer.js";
-import { graph_postprocess_bloom } from "./postprocess/bloom/graph_postprocess_bloom.js";
+import {
+    enquire_postprocess_bloom_pipelines,
+    graph_postprocess_bloom
+} from "./postprocess/bloom/graph_postprocess_bloom.js";
 import { shader_ffx_rcas } from "./postprocess/cas/shader_ffx_rcas.js";
 import { DepthOfFieldU } from "./postprocess/dof/gather/DepthOfFieldU.js";
 import { DepthOfField } from "./postprocess/dof/raymarch/DepthOfField.js";
@@ -52,7 +66,10 @@ import { NSS } from "./postprocess/nss/NSS.js";
 import { PostProcess } from "./postprocess/PostProcess.js";
 import { shader_depth_occlusion_clip } from "./postprocess/taa/shader_depth_occlusion_clip.js";
 import { TAA } from "./postprocess/taa/TAA.js";
-import { graph_add_per_object_velocity } from "./postprocess/velocity/graph_add_per_object_velocity.js";
+import {
+    enquire_per_object_velocity_pipelines,
+    graph_add_per_object_velocity
+} from "./postprocess/velocity/graph_add_per_object_velocity.js";
 import { shader_debug_velocity } from "./postprocess/velocity/shader_debug_velocity.js";
 import {
     graph_rasterize_meshes_transparent_oit
@@ -66,19 +83,25 @@ import {
 import {
     viz_rasterization_opaque_pass_descriptor
 } from "./rasterize/native/viz/viz_rasterization_opaque_pass_descriptor.js";
+import { CullPolicy } from "./rasterize/bucket/construct_primitive_state.js";
 import { RasterizationJob } from "./rasterize/RasterizationJob.js";
-import { graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scene.js";
+import { enquire_rasterize_scene_pipelines, graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scene.js";
 import { ReSTIRDI } from "./restir/di/ReSTIRDI.js";
 import { GPUParticleSystem } from "./particles/GPUParticleSystem.js";
 import { SceneManager } from "./scene/SceneManager.js";
 import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
+import { ShadeToneMappingMode } from "./ShadeToneMappingMode.js";
 import { ShadeTransparencyMode } from "./ShadeTransparencyMode.js";
 import { AVBOITSettings } from "./rasterize/native/avboit/AVBOITSettings.js";
+import { ShaderSwitchSet } from "./shader/compiler/ShaderSwitchSet.js";
 import { graph_image_pass } from "./shader/graph/graph_image_pass.js";
 import { graph_import_buffer } from "./shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
 import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
 import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
+import { SHADOW_DIRECTIONAL_TECHNIQUE } from "./shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.js";
+import { INDIRECT_LIGHTING } from "./INDIRECT_LIGHTING.js";
+import { ShadowDirectionalTechnique } from "./shadow/map/ShadowDirectionalTechnique.js";
 import { SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT } from "./shadow/map/csm/SHADOWMAP_CSM_DEFAULT_CASCADE_COUNT.js";
 import { DEFAULT_VSM_FIRST_TEXEL_SIZE } from "./shadow/vsm/DEFAULT_VSM_FIRST_TEXEL_SIZE.js";
 import { DEFAULT_VSM_PAGE_BUDGET } from "./shadow/vsm/DEFAULT_VSM_PAGE_BUDGET.js";
@@ -200,6 +223,14 @@ export class Renderer {
      */
     transparency_mode = ShadeTransparencyMode.AVBOIT;
 
+    /**
+     * How the exposed scene colour becomes display colour, on every output. An SDR and an HDR display run the same
+     * mode, so a scene looks alike on both; see {@link ShadeToneMappingMode}. Read every frame, so it can be flipped
+     * at runtime. A mode not in use at {@link initialize} compiles its pass on the first frame that draws with it.
+     * @type {ShadeToneMappingMode}
+     */
+    tone_mapping_mode = ShadeToneMappingMode.GT7;
+
     /**
      * Switches of the AVBOIT mode, read every frame while {@link transparency_mode} selects it.
      * @type {AVBOITSettings}
@@ -284,6 +315,41 @@ export class Renderer {
      */
     feature_virtual_shadow_maps = false;
 
+    /**
+     * The values of the shader switches, for every pass this renderer records: what its feature flags
+     * make of the switches its shaders decide ({@link SHADOW_DIRECTIONAL_TECHNIQUE} from
+     * {@link feature_virtual_shadow_maps}, {@link INDIRECT_LIGHTING} from {@link indirect_lighting_mode},
+     * {@link LOCAL_LIGHT_SHADING} from {@link feature_restir_di_enabled}).
+     * A pass hands it to the shaders it draws with, which build their variant for it. Interned, so it
+     * stays the same object until a flag changes, and looking a variant up by it allocates nothing.
+     *
+     * @type {ShaderSwitchSet}
+     */
+    #shader_switches = ShaderSwitchSet.EMPTY;
+
+    /**
+     * @returns {ShaderSwitchSet} see {@link #shader_switches}
+     */
+    get shader_switches() {
+        return this.#shader_switches;
+    }
+
+    /**
+     * Bring {@link #shader_switches} up to the feature flags. Allocates nothing while they are unchanged.
+     */
+    #update_shader_switches() {
+        this.#shader_switches = this.#shader_switches
+            .with(
+                SHADOW_DIRECTIONAL_TECHNIQUE,
+                this.feature_virtual_shadow_maps ? ShadowDirectionalTechnique.Virtual : ShadowDirectionalTechnique.Cascades
+            )
+            .with(INDIRECT_LIGHTING, this.indirect_lighting_mode)
+            .with(
+                LOCAL_LIGHT_SHADING,
+                this.feature_restir_di_enabled ? LocalLightShading.ReSTIR : LocalLightShading.Clustered
+            );
+    }
+
     /**
      * Virtual shadow map pages a scene may render per frame, pushed to the scene's shadow context
      * each frame; see {@link DEFAULT_VSM_PAGE_BUDGET} for what a page costs and what waits.
@@ -1014,13 +1080,14 @@ export class Renderer {
         const lpv = scene_ctx.light_probe_volume;
         let diffuse_pass;
         let specular_pass;
-        let ssr_inputs;
+        // the running mode's source, for SSR's resolve to fall back to; it is given no other mode's
+        let ssr_brick4;
+        let ssr_lpv;
 
         // Each mode owns its diffuse/specular pair and any fused implementation.
         // SSR overrides specular below using the same explicitly selected mode.
         switch (mode) {
             case ShadeIndirectLightingMode.IBL:
-                ssr_inputs = { input_environment: gr_texture_environment };
                 diffuse_pass = {
                     shader: shader_diffuse_IBL,
                     inputs: {
@@ -1067,7 +1134,7 @@ export class Renderer {
                     });
                     return current_color_out;
                 }
-                ssr_inputs = { brick4: scene_ctx.volumetric_light_map };
+                ssr_brick4 = scene_ctx.volumetric_light_map;
                 diffuse_pass = {
                     shader: shader_brick4_diffuse,
                     inputs: {
@@ -1095,7 +1162,7 @@ export class Renderer {
                 break;
 
             case ShadeIndirectLightingMode.LPV:
-                ssr_inputs = { lpv, input_environment: gr_texture_environment };
+                ssr_lpv = lpv;
                 diffuse_pass = {
                     shader: shader_diffuse_LPV,
                     inputs: {
@@ -1133,7 +1200,6 @@ export class Renderer {
         if (this.feature_ssr_enabled) {
             const ssr = this.#postprocess.ssr.graph_pass({
                 graph,
-                ...ssr_inputs,
                 view_ctx,
                 jitter: view_ctx.jitter,
                 input_depth_previous: gr_texture_depth_previous,
@@ -1147,7 +1213,10 @@ export class Renderer {
                 input_occlusion: gr_occlusion_clip,
                 camera_current: gr_buffer_camera_current,
                 camera_previous: gr_buffer_camera_previous,
-                indirect_lighting_mode: mode,
+                input_environment: gr_texture_environment,
+                brick4: ssr_brick4,
+                lpv: ssr_lpv,
+                shader_switches: this.#shader_switches,
                 resolution,
             });
 
@@ -1323,12 +1392,12 @@ export class Renderer {
     #hdr_supported = false;
 
     /**
-     * What's the peak brightness of the display?
-     * Only valid for HDR.
+     * What every tonemap pass is told about the display: the primaries the canvas was actually configured with, and
+     * the peak brightness, which only the HDR passes read.
      *
-     * @type {number}
+     * @type {TonemapDisplaySettings}
      */
-    #display_peak_brightness_nits = 1000;
+    #tonemap_settings = new TonemapDisplaySettings();
 
     #update_presentation_format() {
 
@@ -1358,10 +1427,10 @@ export class Renderer {
 
         if (isHDR) {
             // Currently, there is no way to interrogate this from the browser, so going with an assumption
-            this.#display_peak_brightness_nits = 1000;
+            this.#tonemap_settings.peak_nits = 1000;
         } else {
             // Assume SDR nits
-            this.#display_peak_brightness_nits = 80;
+            this.#tonemap_settings.peak_nits = 80;
         }
 
         if (isHDR === previous_value) {
@@ -1581,6 +1650,125 @@ export class Renderer {
 
         window.matchMedia("(dynamic-range: high)").addEventListener("change", this.#update_hdr_support);
 
+        this.#prepare_pipelines();
+    }
+
+    /**
+     * Offer the pipelines a frame draws with — see {@link PipelineEnquiry}. {@link initialize}
+     * compiles the answer off the main thread, and {@link render} draws nothing until it is in.
+     *
+     * Each subsystem is asked only when the feature flag that runs it is on, so the answer follows the
+     * features as they are set at that moment. It covers the default renderer: the opaque raster,
+     * shading, IBL, ambient occlusion, TAA, sharpening, bloom, exposure and the tonemap. Everything
+     * else is made the old way, by the first frame that draws with it: the features that are off by
+     * default (ReSTIR's passes, SSR, depth of field, motion blur, NSS, path tracing), the indirect
+     * lighting modes other than IBL, a feature turned on after {@link initialize}, and whatever a
+     * scene's content brings — shadow casters, transparent and alpha-tested materials, volumes,
+     * particles.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry) {
+        const graphics = this.#graphics;
+
+        // The longest compile goes first. With everything else compiling beside it this one is the
+        // whole wait (~1 s of a cold simple-cube's ~1.1 s), and where there are fewer compile
+        // workers than pipelines, the order they are asked for is roughly the order they start.
+        this.#update_shader_switches();
+
+        const deferred_shader = shader_deferred_main.variant(this.#shader_switches);
+
+        enquiry.render.push(deferred_shader.pipeline);
+
+        // the scene colour target's format: the background and the indirect-lighting resolve draw into
+        // the target the shading pass made
+        const color_formats = [deferred_shader.pipeline.fragment.targets[0].format];
+
+        graphics.materials.enquirePipelines(enquiry);
+        this.#scenes.enquirePipelines(enquiry);
+
+        enquire_rasterize_scene_pipelines(enquiry, viz_rasterization_opaque_pass_descriptor, CullPolicy.Standard);
+
+        enquire_per_object_velocity_pipelines(enquiry);
+        enquiry.render.push(shader_depth_occlusion_clip.pipeline);
+        enquire_build_light_clusters_pipelines(enquiry);
+
+        if (this.feature_ssao_enabled) {
+            this.#postprocess.ssao.enquirePipelines(enquiry);
+        }
+
+        enquiry.render.push(shader_background.pipeline_for(color_formats));
+
+        if (this.indirect_lighting_mode === ShadeIndirectLightingMode.IBL) {
+            if (!this.feature_ssr_enabled) {
+                // what SSR replaces
+                enquiry.render.push(shader_specular_IBL.pipeline);
+            }
+
+            enquiry.render.push(shader_diffuse_IBL.pipeline);
+            enquiry.render.push(shader_resolve_indirect_lighting.pipeline_for(color_formats));
+        }
+
+        if (this.feature_taa_enabled && this.upscale_type === ShadeUpscalerType.TAA) {
+            this.#taa.enquirePipelines(enquiry, this.#textures_taa_history[0].descriptor.format);
+        }
+
+        if (this.feature_sharpening_enabled) {
+            enquiry.render.push(shader_ffx_rcas.pipeline);
+        }
+
+        if (this.feature_bloom_enabled) {
+            enquire_postprocess_bloom_pipelines(enquiry);
+        }
+
+        if (this.feature_automatic_exposure_enabled) {
+            this.#autoexposure.enquirePipelines(enquiry);
+        }
+
+        enquiry.render.push(this.#tonemap_shader().pipeline_for([this.#presentation_format]));
+    }
+
+    /**
+     * The pass that writes the canvas: the output's dynamic range picks the SDR or the HDR form, and
+     * {@link tone_mapping_mode} picks the operator.
+     *
+     * @returns {import("./shader/ImageShader.js").ImageShader}
+     */
+    #tonemap_shader() {
+        assert.enum(this.tone_mapping_mode, ShadeToneMappingMode, 'tone_mapping_mode');
+
+        if (this.tone_mapping_mode === ShadeToneMappingMode.NONE) {
+            return this.#hdr_supported ? shader_tonemap_HDR_none : shader_tonemap_LDR_none;
+        }
+
+        if (this.tone_mapping_mode === ShadeToneMappingMode.PBR_NEUTRAL) {
+            return this.#hdr_supported ? shader_tonemap_HDR_pbr_neutral : shader_tonemap_LDR_pbr_neutral;
+        }
+
+        return this.#hdr_supported ? shader_tonemap_HDR : shader_tonemap_LDR;
+    }
+
+    /**
+     * Compile what {@link enquirePipelines} offers, off the main thread — see {@link PipelineEnquiry}.
+     */
+    #prepare_pipelines() {
+        const enquiry = PipelineEnquiry.from(this.device);
+
+        this.enquirePipelines(enquiry);
+
+        const graphics = this.#graphics;
+
+        const render = enquiry.render;
+
+        for (let i = 0; i < render.length; i++) {
+            graphics.render_pipelines.prepare(render[i]);
+        }
+
+        const compute = enquiry.compute;
+
+        for (let i = 0; i < compute.length; i++) {
+            graphics.compute_pipelines.prepare(compute[i]);
+        }
     }
 
     /**
@@ -1738,16 +1926,29 @@ export class Renderer {
         };
 
 
+        let configured_color_space = preferred_color_space;
+
         try {
             context.configure(config);
         } catch (e) {
             // try fall-back colorspace
+            configured_color_space = 'srgb';
+
             context.configure({
                 ...config,
-                colorSpace: 'srgb'
+                colorSpace: configured_color_space
             });
         }
 
+        // The tonemap passes write in whatever primaries the canvas ended up with. Ask it rather than trust the
+        // request: a browser that does not know `colorSpace` ignores the member without throwing, and shows sRGB.
+        const configuration = context.getConfiguration?.();
+
+        if (configuration !== undefined && configuration !== null) {
+            configured_color_space = configuration.colorSpace ?? 'srgb';
+        }
+
+        this.#tonemap_settings.set_canvas_color_space(configured_color_space);
     }
 
     #apply_size() {
@@ -1959,9 +2160,11 @@ export class Renderer {
      * simulation, the animation tick and exposure adaptation all step by it. Zero by default, which
      * draws the current state and moves nothing; a fixed fraction of a second here instead would run
      * the simulation at that rate no matter what the caller's clock was doing.
-     * @returns {boolean} whether a frame was encoded and submitted. False only when there is nothing
-     * to draw with — the device was lost, or the renderer destroyed. Frames the GPU has not finished
-     * yet neither hold this one back nor make it return false.
+     * @returns {boolean} whether a frame was encoded and submitted. False when there is nothing to
+     * draw with — the device was lost, or the renderer destroyed — and while a pipeline prepared
+     * ahead of use is still compiling: the ones {@link initialize} asked for, or a template
+     * prewarmed at a level load. Frames the GPU has not finished yet neither
+     * hold this one back nor make it return false.
      */
     render(
         camera,
@@ -1974,6 +2177,18 @@ export class Renderer {
             return false;
         }
 
+        const graphics = this.#graphics;
+
+        if (graphics.render_pipelines.pending_count > 0 || graphics.compute_pipelines.pending_count > 0) {
+            /*
+             Pipelines prepared ahead of use are still compiling. A frame encoded now would make
+             each one it reaches again, synchronously — one after another on the thread that also
+             presents the page, the very wait the asynchronous compile exists to avoid. Nothing is
+             encoded and the canvas keeps what it had.
+            */
+            return false;
+        }
+
         this.#ensure_context_configured();
 
         const canvas_texture = this.context.getCurrentTexture();
@@ -2147,6 +2362,8 @@ export class Renderer {
         // Virtual shadow maps for directional lights, and what they may spend; a flip of the flag or
         // of the first texel rebuilds the maps inside process_lights.
         sm.use_virtual_shadow_maps = this.feature_virtual_shadow_maps;
+        // and the shaders that sample those maps, built for the same technique, in the same frame
+        this.#update_shader_switches();
         sm.virtual_page_budget = this.#shadow_virtual_page_budget;
         sm.virtual_lod_bias = this.shadow_virtual_lod_bias;
         sm.virtual_first_texel_size = this.#shadow_virtual_first_texel_size;
@@ -2486,6 +2703,7 @@ export class Renderer {
             camera: view_ctx.camera,
             hzb: gr_texture_hzb,
             resolution: view_ctx.resolution,
+            limits: graphics.collection_limits,
         });
 
         // The view's volumetrics: the fog every surface is seen through (participating media ->
@@ -2502,7 +2720,10 @@ export class Renderer {
             light_cluster_lookup: light_clusters.lookup,
             light_cluster_parameters: light_clusters.parameters,
             shadowmap_atlas: gr_shadowmap_atlas,
-            indirect_lighting_mode: this.indirect_lighting_mode,
+            shader_switches: this.#shader_switches,
+            // the running mode's GI source, for froxel GI; it is given no other mode's
+            brick4: this.indirect_lighting_mode === ShadeIndirectLightingMode.Brick4 ? view_ctx.scene.volumetric_light_map : undefined,
+            lpv: this.indirect_lighting_mode === ShadeIndirectLightingMode.LPV ? view_ctx.scene.light_probe_volume : undefined,
         });
 
         /**
@@ -2512,18 +2733,15 @@ export class Renderer {
         let current_color_out = -1;
 
         // ReSTIR DI — stochastic direct lighting of local (point+spot) lights.
-        // When enabled, resolve per-pixel point+spot radiance and shade with the
-        // ReSTIR deferred variant (no brute-force cluster loop). The variant is a
-        // separate compiled shader, selected here at the JS level rather than via
-        // a runtime branch inside the shader.
-        let deferred_shader = shader_deferred_main;
-
+        // When enabled, resolve per-pixel point+spot radiance; the shader switches
+        // make the deferred pass read it in place of its cluster loop.
         const deferred_inputs = {
             gBufferDepth: gr_texture_depth_current,
             gBufferPBR: gr_texture_pbr,
             gBufferNormal: gr_texture_normal,
             gBufferAlbedo: gr_texture_material_albedo_ao,
             gBufferEmissive: gr_texture_material_emissive,
+            tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
 
             //
             light_data: lights.buffer_data,
@@ -2543,8 +2761,6 @@ export class Renderer {
         };
 
         if (this.feature_restir_di_enabled) {
-            deferred_shader = shader_deferred_main_restir;
-
             deferred_inputs.tRestirRadiance = this.#restir_di.execute({
                 graph,
                 view: view_ctx,
@@ -2565,7 +2781,7 @@ export class Renderer {
         // Main shading pass
         [current_color_out] = graph_image_pass({
             graph,
-            shader: deferred_shader,
+            shader: shader_deferred_main.variant(this.#shader_switches),
             input_depth: gr_texture_depth_current,
             inputs: deferred_inputs,
             output_resolution: view_ctx.resolution,
@@ -2763,7 +2979,7 @@ export class Renderer {
                 volumetrics_metadata: volumetrics.metadata,
                 volumetrics_irradiance: volumetrics.irradiance,
 
-                indirect_lighting_mode: this.indirect_lighting_mode,
+                shader_switches: this.#shader_switches,
                 avboit: this.avboit,
                 side_channels,
             });
@@ -2961,31 +3177,18 @@ export class Renderer {
 
         current_color_out = record_scene_color.color;
 
-        if (this.#hdr_supported) {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_tonemap_HDR,
-                inputs: {
-                    input_color: current_color_out,
-                    settings: {
-                        peak_nits: this.#display_peak_brightness_nits,
-                        paper_white_nits: 100, // SDR spec is 80, but 100 has been accepted as de-facto in recent years
-                    },
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        } else {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_tonemap_LDR,
-                inputs: {
-                    input_color: current_color_out,
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        }
+        // every pass reads from the settings only the members its immediate struct names: the canvas's primaries
+        // from its working space, and, on an HDR display, the peak
+        [current_color_out] = graph_image_pass({
+            graph,
+            shader: this.#tonemap_shader(),
+            inputs: {
+                input_color: current_color_out,
+                settings: this.#tonemap_settings,
+                exposure
+            },
+            output: [gr_texture_canvas]
+        });
 
         /*
          The canvas is written here and cannot be read: a texture may not be a render attachment and

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

@@ -0,0 +1,17 @@
+/**
+ * Spatio-temporal blue noise, two channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC2_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Spatio-temporal blue noise, three channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC3_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The split-sum DFG lookup (`STATIC_GRAPHICS_ENGINE_ASSETS.split_sum`), sampled linearly.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SPLIT_SUM_LUT_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "./shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,iCAFU,wBAAwB,CAE2E;AAE7G;;;GAGG;AACH,iCAFU,wBAAwB,CAE2E;AAE7G;;;GAGG;AACH,qCAFU,wBAAwB,CAE2D;yCAlBpD,+CAA+C"}

package/src/shade/renderer/STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js

@@ -0,0 +1,19 @@
+import { ShaderResourceDescriptor } from "./shader/resource/ShaderResourceDescriptor.js";
+
+/**
+ * Spatio-temporal blue noise, two channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC2_RESOURCE = ShaderResourceDescriptor.texture("tSTBN_vec2", "unfilterable-float", "3d");
+
+/**
+ * Spatio-temporal blue noise, three channels (`STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3`).
+ * @type {ShaderResourceDescriptor}
+ */
+export const STBN_VEC3_RESOURCE = ShaderResourceDescriptor.texture("tSTBN_vec3", "unfilterable-float", "3d");
+
+/**
+ * The split-sum DFG lookup (`STATIC_GRAPHICS_ENGINE_ASSETS.split_sum`), sampled linearly.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SPLIT_SUM_LUT_RESOURCE = ShaderResourceDescriptor.texture("tSplitSum", "float");

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

@@ -0,0 +1,14 @@
+/**
+ * How the exposed scene colour becomes display colour.
+ *
+ * One choice for every display. The same mode runs on an SDR and an HDR output, so a scene looks the same on both up
+ * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and there is no per-output
+ * setting on purpose.
+ */
+export type ShadeToneMappingMode = number;
+export namespace ShadeToneMappingMode {
+    let GT7: number;
+    let NONE: number;
+    let PBR_NEUTRAL: number;
+}
+//# sourceMappingURL=ShadeToneMappingMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShadeToneMappingMode.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/ShadeToneMappingMode.js"],"names":[],"mappings":";;;;;;;mCAOU,MAAM"}

package/src/shade/renderer/ShadeToneMappingMode.js

@@ -0,0 +1,30 @@
+/**
+ * How the exposed scene colour becomes display colour.
+ *
+ * One choice for every display. The same mode runs on an SDR and an HDR output, so a scene looks the same on both up
+ * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and there is no per-output
+ * setting on purpose.
+ *
+ * @enum {number}
+ */
+export const ShadeToneMappingMode = {
+    /**
+     * GT7 tone mapping (Polyphony Digital, SIGGRAPH 2025). An exposed 1.0 shows at a 250 cd/m² paper white on both
+     * outputs. SDR clips at that paper white, the curve's SDR mode, and HDR rolls off to the display's peak.
+     */
+    GT7: 0,
+    /**
+     * No tone mapping: the exposed colour as it is, with 1.0 at SDR white. An SDR output clips everything above 1.0,
+     * and an HDR output shows it as far as the display reaches.
+     */
+    NONE: 1,
+    /**
+     * Khronos PBR Neutral (Lalish, 2024). Base colours under 0.8 come out as they are, less a 0.04 Fresnel offset, and
+     * hues never shift: made for showing products. SDR is the specification, which rolls highlights off to SDR white
+     * and toward white. HDR puts the display's peak in place of the specification's 1, so everything below the
+     * compression start looks the same on both outputs, and a highlight rolls off to the display's peak instead.
+     *
+     * An exposed 0.18 shows at 0.14 of SDR white, where {@link GT7} shows it at 0.179.
+     */
+    PBR_NEUTRAL: 2,
+};

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -28,6 +28,14 @@
  *     update path.
  */
 export class GPUAnimationManager {
+    /**
+     * Offer the pipelines {@link tick} runs on every frame: the transform hierarchy, which composes
+     * world matrices whether or not anything is animated — see {@link PipelineEnquiry}. The clip,
+     * pose and skinning passes are left to the first frame that has a clip or a skin.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: PipelineEnquiry): void;
     /**
      * @param {GPUDevice} device
      * @param {string} label
@@ -518,6 +526,7 @@ export class GPUAnimationManager {
     destroy(): void;
     #private;
 }
+export type PipelineEnquiry = import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 export type AnimationCurve = import("../../../engine/animation/curve/AnimationCurve.js").AnimationCurve;
 export type GPURecordWriter = import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter;
 export type ShadeGPUCommandContext = import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}