@driftengine/core 4.2.1 → 4.4.0

package/dist/render/backend/webgl2/renderer.d.ts

@@ -11,6 +11,8 @@ import type { PassDefinition, PassHandle } from '../../pass.ts';
 import type { Vec3 } from '../../../math/color.ts';
 import { GpuTimer } from '../../gpuTimer.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
+import { LightField } from '../../driftLight/lightField.ts';
+import type { LightFieldOptions, LightFieldSource } from '../../driftLight/lightField.ts';
 /**
  * How far the rush's outermost tap reaches at full strength, in UV.
  *
@@ -541,6 +543,14 @@ export interface TranslucentMeshOptions {
      * that two surfaces overlapping in view blend in submission order. And a surface that writes no
      * depth cannot occlude the sky. A caller wanting both wants the pieces sorted and this left
      * alone.
+     *
+     * **And depth a blended surface writes is where the frame's depth-reading passes stop.** The
+     * global medium marches to it on both backends, and on WebGPU ambient occlusion, the temporal
+     * resolve and motion blur take it for the surface too. Right for a pane that is most of a pixel's
+     * colour; wrong for a faint sheet. A bought courtyard's dirt decals stand a centimetre off their
+     * stone and overhang every corner they wrap, and the haze stopped at each overhang, a clear band
+     * down a pier's whole height. A decal lying on an opaque surface needs no depth to hold the sky
+     * off, since the surface under it already does, so `false` costs it only an order among decals.
      */
     readonly depthWrite?: boolean;
     /**
@@ -777,6 +787,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly panelProgram;
     private readonly panelUniforms;
     private readonly panelVao;
+    /** The unit quad behind `panelVao`, held so `dispose` can release it. */
+    private readonly panelBuffer;
     private readonly filmProgram;
     /**
      * The off-screen colour target, when screen effects are on. Null is not a failure —
@@ -807,6 +819,14 @@ export declare class WebGL2Renderer implements RendererApi {
     /** Whether a palette is currently chosen. Distinct from whether one was ever uploaded. */
     private skinPaletteSet;
     private readonly emptyTexture2D;
+    /** DriftLight's stand-ins while no field is whole: no brick anywhere, and no light. */
+    private readonly emptyDriftIndex;
+    private readonly emptyDriftAtlas;
+    /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
+    private lightField;
+    private driftIndex;
+    private driftAtlas;
+    private readonly driftUniforms;
     private readonly emptyTexture2DArray;
     private readonly emptyTextureCube;
     /** How hard the rush blurs this frame, and how far its outermost tap reaches. */
@@ -865,6 +885,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private motionBlurScale;
     /** How much of the bloom ceiling this frame takes. See `setBloom`. */
     private bloomScale;
+    /** In scene units, once `setBloom` has moved it; null reads the profile's. */
+    private bloomThresholdSet;
     /**
      * This frame's exposure into the tone curve. See `setOutputExposure`.
      *
@@ -972,6 +994,15 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly depthUniforms;
     private readonly depthInstancedProgram;
     private readonly depthInstancedUniforms;
+    /**
+     * The cutout casters' depth programs, rigid and instanced: a leaf or a chain link casts the shape
+     * in its texture's alpha, not its whole card. See `DEPTH_CUTOUT_FRAG`. Chosen per draw by
+     * `cutoutOf`, so an opaque caster never touches them.
+     */
+    private readonly depthCutoutProgram;
+    private readonly depthCutoutUniforms;
+    private readonly depthInstancedCutoutProgram;
+    private readonly depthInstancedCutoutUniforms;
     private readonly scatterDepthProgram;
     private readonly scatterDepthUniforms;
     private readonly shadowMap;
@@ -1030,6 +1061,10 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly probeCapture;
     /** Every probe of the grid, as one array texture. Allocated when a grid is declared. */
     private probeArray;
+    /** Which layers a bake writes and the shading reads. See `probeSweeps.ts`. */
+    private probeSweeps;
+    /** `uProbeGridSets`, rewritten in place. */
+    private readonly probeSets;
     /**
      * Where those probes stand. A single baked probe is a grid of one at that probe's own origin.
      *
@@ -1055,6 +1090,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedEnvironmentAmbient;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
+    /** Whether the bake under way lights its faces by the grid. `ProbeBakeOptions.bounce`. */
+    private probeBounce;
     /** The clip-control extension, or null where this context does not offer it. */
     private clipControl;
     /**
@@ -1157,6 +1194,17 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private activeDepthViewProj;
     private activeDepthPeel;
+    /**
+     * Whether a peel pass has filled the second layer since the first one last opened, which is
+     * what the frame samples it on: the rule the other backend's `peelFilled` states, held here too.
+     *
+     * **Not whether the map exists.** That was the test here, on the belief that a GL texture is
+     * born reading as the far plane; it is born zeroed, and a scene that built the layer and never
+     * peeled it sampled an occluder at the light. `ShadowMap` now clears itself at birth, so an
+     * unfilled layer would read as lit either way — this is what keeps the two backends one
+     * decision, and a frame that does not peel from paying a fetch per tap for nothing.
+     */
+    private peelFilled;
     /**
      * Whether the depth pass this scatter draw interrupts wants back-face culling.
      *
@@ -1167,6 +1215,11 @@ export declare class WebGL2Renderer implements RendererApi {
      * cubemap — so the pass states what it wants and this restores that.
      */
     private depthPassCullsFaces;
+    /**
+     * Whether the bound material is seen from both faces, so its draws cull nothing. Toggled around
+     * each such draw and handed back, where the other backend bakes it into a pipeline.
+     */
+    private materialDoubleSided;
     /**
      * The one sink handed to every caster enumeration.
      *
@@ -1174,6 +1227,11 @@ export declare class WebGL2Renderer implements RendererApi {
      * per pass would allocate six objects per light per frame.
      */
     private readonly casterSink;
+    /**
+     * What a cutout depth draw needs beyond the plain one: the pass's matrix and peel, the material's
+     * cutoff and UV scale, and its albedo on the surface unit, which the caller gives back after.
+     */
+    private bindCutoutDepth;
     private readonly drawPointShadowFace;
     /**
      * Viewport in CSS pixels rather than device pixels.
@@ -1839,6 +1897,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * whatever box the caller lays out in, and the game's own card is not always the canvas.
      */
     drawText(text: TextRenderer, viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): void;
+    /**
+     * The cell size to draw a bitmap glyph at so every cell covers whole device pixels.
+     *
+     * **The caller snaps, and then measures and draws with the one number.** 4.1.4 applied this
+     * inside `drawText` instead, where `textWidthPx` could not see it — it takes no viewport and so
+     * cannot know the ratio — and every consumer went on laying out against the cell it asked for
+     * while the engine drew a smaller one. A centred line, a right-aligned column and a line fitted
+     * to a box broke together. Snapped here, the arithmetic and the picture cannot disagree.
+     *
+     * **It is on the renderer because only the renderer knows the second number.** `viewportWidth`
+     * is the caller's, and it already passes it to `drawText`; the drawing buffer is not on the
+     * shared surface and a game's text layout is a pure function over CSS pixels, so reaching it
+     * meant threading a canvas through an interface layer to a value the renderer was holding.
+     *
+     * The decision itself stays in `textLayout.ts` and only this binding is per backend, which is
+     * the 2026-08-13 rule: a cell already whole comes back untouched, and the snap is downward so a
+     * line fitted to a box can only leave a gap rather than overflow it.
+     */
+    snapTextCellSize(cellSize: number, viewportWidth: number): number;
     /** Width of the string this handle currently holds, in pixels at a given cell size. */
     textWidth(text: TextRenderer, cellSize: number): number;
     disposeText(text: TextRenderer): void;
@@ -2495,6 +2572,53 @@ export declare class WebGL2Renderer implements RendererApi {
      * than anything in the world.
      */
     setCameraMotionBlur(scale: number): void;
+    /**
+     * The camera has cut: this frame is a new shot, not the next moment of the last one.
+     *
+     * **Everything temporal reprojects through the previous frame's view**: the motion blur measures
+     * its smear against it, and the temporal resolve reads its history through it. A cut is a jump
+     * the renderer cannot tell from a fast camera, so without this a transport that seeks, a respawn
+     * or an edit smears its first frame along the whole jump and blends in a picture of somewhere
+     * else. The caller knows it cut; this is how it says so, before the frame's `beginFrame`.
+     *
+     * What it gives up is one frame of history: the frame after a cut has no blur and no temporal
+     * blend, as the first frame of a session has none. Nothing else is reset.
+     */
+    cameraCut(): void;
+    /**
+     * **Eye adaptation**: how far the frame's exposure follows its own brightness, 0 to 1, and the
+     * seconds since the last frame. 0 is off and the default, and at 0 nothing is metered or allocated.
+     *
+     * The finished scene is metered on the GPU each frame — the log-mean of its luminance — and a
+     * held brightness moves toward it at a fixed rate, about 78% of the way in a second; the composite
+     * then scales scene light toward middle grey by \`strength\` of the stops between them, at most six
+     * either way. So a shaded courtyard floor opens up the way a camera or an eye would, and
+     * \`setOutputExposure\` becomes a bias on top: a night kept darker than a day is a bias under one.
+     * **The time is the caller's**, because the engine takes time from its caller; a held capture
+     * passes 0 and holds. \`cameraCut\` snaps it, so a new shot is metered rather than eased into.
+     *
+     * What it gives up is regional metering: every pixel counts the same. Needs \`screenEffects\` and
+     * \`hdrScene\`, and says so once rather than doing nothing. See \`shaders/exposure.ts\`.
+     */
+    setAutoExposure(strength: number, dtSec: number): void;
+    /**
+     * **Local exposure**: how far each region of the frame is brought toward the frame's own
+     * brightness, 0 to 1. 0 is off and the default, and at 0 nothing more is measured or allocated.
+     *
+     * A tone curve maps one range, and a sunlit courtyard is two: its shaded arcades hold a fiftieth
+     * of the light on its sunlit paving, so exposed for either the other is black or white. This moves
+     * each region `strength` of the stops between it and the frame's held brightness, at most three,
+     * read from a bilateral grid over the exposure meter's tiles, so shade beside sun is lifted as
+     * shade rather than as the average of the two. The eye's held brightness is what regions move
+     * toward, so it is measured whether or not `setAutoExposure` is on; with adaptation off the frame
+     * as a whole keeps the exposure it was given. About 0.5 is a photograph's latitude, and 1 is a
+     * frame with no light and shade left in it.
+     *
+     * What it gives up is contrast between regions, which is the point, and a halo a tile wide where
+     * two regions of one brightness band differ. Needs `screenEffects` and `hdrScene`, and says so
+     * once rather than doing nothing. See `shaders/localExposure.ts`.
+     */
+    setLocalExposure(strength: number): void;
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take.
@@ -2543,8 +2667,15 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * Set before `beginFrame` and held until changed. Ignored entirely when `bloom` is 0, since
      * the chain is never built.
+     *
+     * **`threshold` moves `bloomThreshold` for this frame and every one after**, in the same scene
+     * units. A threshold is compared before exposure is applied, so one fixed at construction means a
+     * different brightness on screen at every exposure. That is harmless while exposure stands still
+     * and wrong for a day whose exposure spans 2.5 to 14: a courtyard blooming at noon, or candles
+     * never blooming at night. A caller whose exposure moves passes what it wants on screen over the
+     * exposure. Omitted leaves it where it was, so a caller that never passes one keeps the profile's.
      */
-    setBloom(scale: number): void;
+    setBloom(scale: number, threshold?: number): void;
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
      *
@@ -2650,6 +2781,21 @@ export declare class WebGL2Renderer implements RendererApi {
      * because a consumer setting a grade every frame would otherwise flood a console.
      */
     setColourGrade(lut: ColourGradeLut | null, strength?: number): void;
+    /**
+     * How strongly the lens darkens the frame's corners, held until changed: 0 is none, 0.5 is about
+     * 1.2 stops at the corner. Applied to scene light before the tone curve, as a lens loses light;
+     * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
+     */
+    setVignette(strength: number): void;
+    /**
+     * Film grain, held until changed: an amplitude in display values (0 is none, 0.03 is a fine
+     * grain) and this frame's seed. **The seed is the caller's**, because the engine takes time from
+     * its caller: pass a new one each frame for grain that moves, and the same one for a still that
+     * is identical run to run. Applied last, after the grade and the veil; see `filmLook.ts`.
+     */
+    setFilmGrain(strength: number, seed: number): void;
+    private warnedLookWithoutComposite;
+    private warnLookWithoutComposite;
     /**
      * What this frame asked for. **Every ceiling here is `null`, and that is the finding.**
      *
@@ -2823,6 +2969,25 @@ export declare class WebGL2Renderer implements RendererApi {
     private useFlatProgram;
     /** Bind the flat pass once per frame; then issue any number of drawMesh calls. */
     bindMeshPass(camera: Camera, env: Environment): void;
+    /**
+     * Sum a scene's many fixed lights into a DriftLight field, which stands in for each of them
+     * wherever the frame's choice of exact lights does not reach. See `driftLight/lightField.ts`.
+     *
+     * Replaces any field made before. The scene then paces `field.bake(bricks)` and calls
+     * `field.follow(buffer.complete, ...)` each frame with the selection that chose its exact lights;
+     * the volume is summed into the frame once every brick has landed.
+     */
+    createLightField(lights: readonly LightFieldSource[], options?: Omit<LightFieldOptions, 'falloff'>): LightField;
+    /** Let go of the field and its volumes; the scene's lights are all exact again. */
+    disposeLightField(): void;
+    private forgetLightFieldVolumes;
+    /**
+     * Upload the field's two volumes, once, when its last brick has baked: nothing samples them
+     * before that, so uploading as bricks land would be work for no picture.
+     */
+    private uploadLightField;
+    /** The field's uniforms and volumes for this pass, or the stand-ins that switch it off. */
+    private bindDriftLight;
     /**
      * Everything one flat program needs to know about this frame.
      *