@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/post/post-stack.d.ts

@@ -0,0 +1,302 @@
+import type { PostInputs, PostProcessor, Renderer } from '../render/renderer.js';
+import type { SceneTargetViewport } from '../render/scene-target.js';
+import { type Ease } from './blend.js';
+import { type PostQuality, type PostSettings, type PostSettingsPatch } from './settings.js';
+import { Taa } from './taa.js';
+/**
+ * The painterly post stack: bloom (mip chain), floor mist, god rays, ACES tonemap, colour
+ * grade, vignette, dither, plus ambient occlusion and depth of field over the scene depth when
+ * the frame has one (ws/post-depth; off by default), the finishing passes (ws/post-2, all
+ * off by default): a depth/normal outline, chromatic aberration, sharpen, a 3D LUT, film grain
+ * in the composite, and FXAA as one extra pass after it, and the third pass (ws/post-3, all
+ * off by default): TAA, screen-space reflections, auto-exposure, white balance, motion blur
+ * (camera, or per object from a velocity target since ws/post-4) and lens dirt. Plug it into a renderer with `renderer.post = new PostStack(r)`.
+ *
+ * Every pass reads the frame from `PostInputs` alone (ws/post-4): the view matrices and the
+ * jitter from `view`, the projection from `projection`, per-surface roughness and metalness
+ * from `roughMetal`, per-pixel motion from `velocity`. While TAA runs the stack declares
+ * `wantsJitter` and drives the Halton jitter through `renderer.setJitter` (ws/post-6), so every
+ * camera the renderer draws is jittered, XR eyes and offscreen views included.
+ *
+ * Settings are plain objects you can mutate at runtime (`post.settings.bloom.intensity = 2`)
+ * or patch with `post.set({ mist: { density: 0.4 } })`. Disabled passes are skipped entirely.
+ * `post.blendTo(patch, seconds, ease?)` eases numeric settings over time instead.
+ */
+export declare class PostStack implements PostProcessor {
+    readonly settings: PostSettings;
+    /**
+     * Cost caps (bloom levels, ray samples, fog octaves). Independent of `settings`, so scene
+     * presets and blends keep working under a lower quality tier. Change with `setQuality`.
+     */
+    readonly quality: PostQuality;
+    /**
+     * The TAA jitter sequence (ws/post-3): `post.taa.jitter(i)` is the `i`-th offset. While TAA
+     * runs the stack hands it to `renderer.setJitter` (ws/post-6).
+     */
+    readonly taa: Taa;
+    /**
+     * How many times a TAA history was reset (first frame, resize, re-enable). In XR each eye
+     * keeps its own history (ws/xr-taa), so each eye's reset counts.
+     */
+    historyResets: number;
+    private readonly renderer;
+    private readonly uniforms;
+    /**
+     * XR eyes (ws/render-12): every eye resolves on the frame's one encoder, so a `writeBuffer`
+     * per eye would leave each pass reading the last eye's uniforms at submit. An encode with a
+     * `viewport` writes its block into its own slot of this staging ring and copies it into each
+     * pass's buffer on the encoder, just before the pass. Made on the first such encode.
+     */
+    private eyeUniforms;
+    /** The staging slot of the encode under way, or -1: write the passes' buffers directly. */
+    private eyeSlot;
+    private eyeNext;
+    private readonly prefilter;
+    private readonly down;
+    private readonly up;
+    private readonly rays;
+    private readonly composite;
+    /** Bilinear upscale of the scene-resolution composite (`quality.compositeAtScene`). */
+    private readonly upscale;
+    /** Depth passes (ws/post-depth): run only on frames with `inputs.depth` and the pass enabled. */
+    private readonly ao;
+    private readonly aoBlur;
+    private readonly dof;
+    /** Finishing passes (ws/post-2): FXAA after the composite, the outline mask before it. */
+    private readonly fxaa;
+    private readonly outline;
+    /** Post 3 (ws/post-3): the TAA resolve, the half-res SSR march and the motion-blur gather. */
+    private readonly taaPass;
+    private readonly ssrPass;
+    private readonly motionBlurPass;
+    /** The auto-exposure compute passes, made on the first frame in `'auto'` mode. */
+    private exposurePasses;
+    private bloomTex;
+    private mipViews;
+    private raysTex;
+    private raysView;
+    private levels;
+    /** Levels asked for at the last resize (before the size clamp), to detect real changes. */
+    private requestedLevels;
+    private width;
+    private height;
+    private boundEmissive;
+    private boundDepth;
+    /** Bind groups per scene-colour view; cleared whenever any other input or target changes. */
+    private readonly groups;
+    /** Half-res AO (raw and blurred) and DoF targets, made on the first frame that needs them. */
+    private aoTex;
+    private aoView;
+    private aoBlurTex;
+    private aoBlurView;
+    private dofTex;
+    private dofView;
+    private aoGroup;
+    private aoBlurGroup;
+    /** Scene-size outline mask, made on the first frame that needs it; freed on resize. */
+    private outlineTex;
+    private outlineView;
+    private outlineGroup;
+    private warnedOutline;
+    /** Output-size FXAA input (the composite's result), made on the first frame that needs it. */
+    private fxaaTex;
+    private fxaaView;
+    private fxaaGroup;
+    private fxaaWidth;
+    private fxaaHeight;
+    /** The 1×1×1 LUT bound while `lut.texture` is null, and the view of the bound LUT. */
+    private readonly lutPlaceholder;
+    private readonly lutPlaceholderView;
+    private boundLut;
+    private lutView;
+    /** The bound lens-dirt texture and its view (`null` → bloom mip 0 as a placeholder). */
+    private boundDirt;
+    private dirtView;
+    /** Seconds of frame time while `grain.animated`: the grain's seed. */
+    private grainSeed;
+    /**
+     * TAA history slots (ws/post-3; per view since ws/xr-taa): the screen's, and one per XR eye
+     * viewport, each with its scene-size history pair and aux pair (ws/post-5), made on the
+     * view's first TAA frame. At most `TAA_HISTORY_SLOTS`; no allocation once every view has one.
+     */
+    private readonly histories;
+    /** Counts TAA resolves: `TaaHistory.used`. */
+    private taaUse;
+    /** `encode`'s extra target, reused (no allocation per frame). */
+    private readonly taaExtra;
+    /** Half-res SSR term and scene-size motion-blur result, made on the first frame that needs them. */
+    private ssrTex;
+    private ssrView;
+    private motionBlurTex;
+    private motionBlurView;
+    private readonly frameState;
+    /** The current EV (`exposure`), eased in auto mode, `log2(grade.exposure)` in manual. */
+    private ev;
+    private taaOn;
+    private taaVelocityOn;
+    private ssrOn;
+    private motionBlurOn;
+    private readonly depthInfo;
+    private raysGroup;
+    private downGroups;
+    private upGroups;
+    /** Scene-size composite target (display-encoded, swapchain format) and its upscale group. */
+    private ldrTex;
+    private ldrView;
+    private upscaleGroup;
+    private readonly blendConstant;
+    private readonly noClear;
+    private readonly blender;
+    private lastTime;
+    /**
+     * The hook the stack gives `renderer.setJitter` while TAA runs (made once: no per-frame
+     * closure). It runs in `beginFrame`, so only while it is installed, and checks there that the
+     * stack is still attached (ws/post-7): a stack whose TAA resolve did not run during the last
+     * frame, or a renderer with no post processor, has been detached, and the hook clears itself
+     * before the frame draws.
+     */
+    private readonly jitterFn;
+    /** True while the stack has set `renderer.setJitter` (cleared once TAA stops or on `destroy`). */
+    private jitterHooked;
+    /** A TAA resolve ran since the hook last ran (ws/post-7: the stack is still attached). */
+    private jitterResolved;
+    /** The resolved god-ray source (x, y, visibility) when `godRays.direction` placed it. */
+    private readonly raySrc;
+    private boundRoughMetal;
+    private boundVelocity;
+    private boundTaaVelocity;
+    /** `godRays.direction` through the frame's view, or null when `x`/`y` place the rays. */
+    private raySource;
+    constructor(renderer: Renderer, patch?: PostSettingsPatch);
+    /** Change the cost caps. Bloom level changes reallocate the mip chain on the next frame. */
+    setQuality(patch: Partial<PostQuality>): this;
+    /** Bloom levels actually used: the setting, capped by quality, clamped to 2..8. */
+    private wantLevels;
+    /** Patch settings section by section. */
+    set(patch: PostSettingsPatch): this;
+    /**
+     * Ease settings toward `patch` over `seconds` of frame time (default ease: smoothstep).
+     * Numbers and RGB colours interpolate from their current values. `enabled: true` applies
+     * at once, so set the pass's strength to 0 first to fade it in. `enabled: false`, `tonemap`,
+     * `dither` and `bloom.levels` switch at the end. A later `set` or `blendTo` on the same
+     * key takes over from wherever the blend is. `seconds <= 0` behaves like `set`.
+     */
+    blendTo(patch: PostSettingsPatch, seconds: number, ease?: Ease): this;
+    /** True while a `blendTo` is still running. */
+    get blending(): boolean;
+    /** Jump every running blend to its end value. */
+    finishBlend(): this;
+    /**
+     * The current exposure in EV (ws/post-3): the eased auto-exposure value while
+     * `exposure.mode` is `'auto'`, else `log2(grade.exposure)`. The multiplier is `2^EV`.
+     */
+    get exposure(): number;
+    /**
+     * The renderer reads this before each view (`PostProcessor.wantsJitter`): true while TAA is
+     * enabled and allowed by `quality.taa`, so the cameras' `setJitter` reaches their projection.
+     */
+    get wantsJitter(): boolean;
+    /** True when the last `encode` ran the TAA resolve (depth present, enabled, allowed). */
+    get taaActive(): boolean;
+    /**
+     * True when the last TAA resolve reprojected by the velocity target (ws/post-5):
+     * `taa.reprojection` `'velocity'` and the frame had one.
+     */
+    get taaVelocityActive(): boolean;
+    /** True when the last `encode` ran the SSR march. */
+    get ssrActive(): boolean;
+    /** True when the last `encode` ran the motion-blur gather. */
+    get motionBlurActive(): boolean;
+    /**
+     * Advance running blends to frame time `time` (seconds). `encode` calls this; call it
+     * yourself only when driving the stack without rendering. Steps are capped at 0.1 s, so
+     * a hidden tab or long hitch slows a blend rather than skipping it.
+     */
+    advanceBlend(time: number): void;
+    resize(width: number, height: number): void;
+    /**
+     * Record the stack from `inputs` into `output`. With `viewport` (ws/xr-post: one eye of a
+     * shared XR layer) the composite covers that rect only and loads the rest of the output;
+     * otherwise it clears and covers the whole output. Inputs of another size than the last
+     * `resize` (an eye-sized target through `renderer.resolve`) resize the stack first, so the
+     * same stack serves the screen and a headset in turn.
+     */
+    encode(encoder: GPUCommandEncoder, inputs: PostInputs, output: GPUTextureView, viewport?: SceneTargetViewport): void;
+    /**
+     * Pick how this encode's uniform block reaches the passes (ws/render-12). Without a viewport
+     * (the screen, one encode per submit) each pass's buffer is written directly, as before.
+     * With one (an XR eye; the eyes share a submit) the block goes into the next slot of a ring of
+     * `EYE_UNIFORM_SLOTS` and `upload` copies it on the encoder, so each eye's passes read that
+     * eye's reprojection, jitter and ray source. No allocation after the first eye.
+     */
+    private beginUploads;
+    /** This encode's uniform block into `buffer` (the pass's): see `beginUploads`. */
+    private upload;
+    /**
+     * After the first TAA frame, hand the Halton sequence to `renderer.setJitter` (the renderer
+     * runs it from frame 0 at the next `beginFrame`, so the sequence restarts each time TAA
+     * starts); once TAA stops, clear the hook with `null`, once. Only on those edges: a hook set
+     * by someone else in between is left alone. Ownership is read from the renderer (ws/post-8):
+     * the hook is this stack's while `renderer.jitter === this.jitterFn`. Another stack (or the
+     * page) that sets its hook on the same renderer takes it over: this one then never clears
+     * it, and sets its own again once the renderer has none.
+     */
+    private syncJitter;
+    /** Drop the hook: clear it with `null` if it is still this stack's, else leave it alone. */
+    private releaseJitter;
+    /** Ease the EV toward the metered target in auto mode; mirror the manual value otherwise. */
+    private updateExposure;
+    /** Scene-size outline mask. Forces the bind groups to be rebuilt. */
+    private allocOutline;
+    /** Output-size FXAA input, remade when the output size changes (a resize, or an XR eye). */
+    private allocFxaa;
+    private freeFxaa;
+    /**
+     * The TAA history slot of the view `viewport` names (ws/xr-taa): the screen's without one,
+     * else the eye whose rect it is. A new view takes a free slot, or past `TAA_HISTORY_SLOTS`
+     * the least recently used one (reset). No allocation once every view has a slot.
+     */
+    private historyFor;
+    /**
+     * The two scene-size TAA history textures of `h` (ws/post-3) and their aux pair. The first
+     * slot keeps the ws/post-3 labels (`post-taa-history-0/1`); slot `n` appends `-v<n>`.
+     */
+    private allocHistory;
+    /** Mark every TAA history invalid: the next resolve of each view copies its frame. */
+    private invalidateHistories;
+    /** Half-res SSR term (premultiplied colour, fade in alpha). */
+    private allocSsr;
+    /** Scene-size motion-blur result. */
+    private allocMotionBlur;
+    private freeTemporal;
+    /** Point the composite at `lut.texture` (or the placeholder); a change rebuilds the group. */
+    private bindLut;
+    /** Point the composite at the lens-dirt texture (or bloom mip 0 as a placeholder). */
+    private bindDirt;
+    /** Scene-size composite target, made on first use (a resize or tier change frees it). */
+    private allocLdr;
+    private freeLdr;
+    /** Half-res AO targets (raw and blurred). Forces the bind groups to be rebuilt. */
+    private allocAo;
+    /** Half-res DoF target: blurred colour, CoC in alpha. Forces the bind groups to be rebuilt. */
+    private allocDof;
+    private freeDepthTargets;
+    /** Drop every cached bind group: the next frame rebuilds the ones it uses. */
+    private invalidateGroups;
+    /** Track the emissive and depth views; a change drops the cached groups and rebuilds the depth-only ones. */
+    private bindInputs;
+    /** The cached groups for a scene-colour view (an empty set on first use). */
+    private groupsFor;
+    private prefilterGroup;
+    private compositeGroup;
+    private dofGroup;
+    private ssrGroup;
+    private motionBlurGroup;
+    /** The TAA resolve group reading the raw colour, history `read` of `h` and its aux. */
+    private taaGroup;
+    /**
+     * Free the stack's GPU resources and clear the `renderer.setJitter` hook if TAA had set it
+     * (ws/post-6). The stack is not usable afterwards.
+     */
+    destroy(): void;
+}