@driftengine/core 4.4.2 → 4.6.0

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

@@ -1,4 +1,6 @@
 import { FrameBudget } from '../budget.ts';
+import type { Mover } from '../../recon/mover.ts';
+import type { GlassOptions } from '../../glass.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { Camera } from '../../camera.ts';
 import type { PickHit, PickableSource } from '../../pickable.ts';
@@ -13,6 +15,9 @@ 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';
+import type { DenseLightVolume } from '../../driftLight/denseField.ts';
+import { WorldLightField } from '../../driftLight/worldLightField.ts';
+import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts';
 /**
  * How far the rush's outermost tap reaches at full strength, in UV.
  *
@@ -69,7 +74,7 @@ import type { WindStreakOptions } from '../../windStreakRenderer.ts';
 import type { WindField } from '../../windField.ts';
 import type { FlockParams } from '../../flockRenderer.ts';
 import { InstancedBatch } from './instanced.ts';
-import type { MeshInstances } from '../../instances.ts';
+import type { InstancedOptions, MeshInstances } from '../../instances.ts';
 /** Reused each frame: which shader light slot each bound cubemap serves. */
 export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
 /** Lighting and atmosphere for a frame. The game decides what goes in it. */
@@ -106,6 +111,29 @@ export interface Environment extends Atmosphere {
      * how strongly.
      */
     nightFactor: number;
+    /**
+     * Seconds on the caller's clock, for the surfaces that animate — a sign's pulse, a ticker's
+     * scroll, a flipbook. The caller's rather than a clock read here, so a held clock holds every
+     * surface still and a replay replays them. 0 unless stated.
+     */
+    surfaceTime?: number;
+    /**
+     * How wet the world is, 0 to 1: upward surfaces darken and polish, except materials that say
+     * they stay dry. The scene-wide counterpart of `drawFilm`, which stays for a puddle. 0 unless
+     * stated.
+     */
+    wetness?: number;
+    /**
+     * The share of facade windows lit, 0 to 1, which a scene sets from its time of day. Windows switch
+     * on in steps by a per-window hash, so a rising share lights more windows rather than brightening
+     * the ones already lit. 0 unless stated.
+     */
+    litWindows?: number;
+    /**
+     * The share of windows that stay lit however late it gets, 0 to 1, so the small hours are not a
+     * dark city. 0 unless stated.
+     */
+    lateWindows?: number;
     /**
      * Emission that only shows where the dominant light does not reach, 0 and off by default.
      *
@@ -439,6 +467,31 @@ export interface LightVolumeDrawOptions {
  * boolean is refused everywhere else in this file.
  */
 export interface TranslucentMeshOptions {
+    /**
+     * Add this surface's light to what is behind it instead of covering it: a glow, a beam, a pool
+     * of light under a lamp. Its colour times its opacity is added and nothing is darkened, so black
+     * is invisible and overlapping glows brighten — which is why such surfaces are authored nearly
+     * black where they fade. **Order does not matter** to a sum, so an additive draw is never held
+     * for the order-independent pass; it is drawn where it is asked for. Write depth off with it
+     * (`depthWrite: false`) or a glow hides the glows behind it.
+     */
+    /**
+     * Drawn into the picture a reconstruction resolves, rather than after it. For a surface that
+     * moves with what it lies on — a glow on a wall, a pane in a window — whose one motion is that
+     * surface's, so the resolve can carry it with the surface.
+     *
+     * **Late is the default, and it is right for anything else.** A translucent surface writes no
+     * depth the motion pass could test and may move apart from what shows through it — a caption
+     * over a moving car — so a history can only smear it; after the upscale it is sharp and has none.
+     * **What late gives up** is the edge: drawn unjittered against a depth the jittered render
+     * covered, it meets a silhouette the render drew differently every frame, and a glow along an
+     * edge is let through on one frame and not the next. Reconstructed, it is resolved with the edge.
+     *
+     * Only a reconstructing frame draws anything late, so this changes nothing on WebGL2 or with
+     * `reconstruction` off. An order-independent blended set replays where it replays.
+     */
+    readonly reconstructed?: boolean;
+    readonly additive?: boolean;
     /**
      * `false` draws the mesh exactly its own vertex colour times its own texture, with no
      * ambient, sun, point lights, specular, reflectivity, grain or emissive touching it —
@@ -521,6 +574,13 @@ export interface TranslucentMeshOptions {
      * clear, and it is the whole difference between this and a flat tint.
      */
     readonly thicknessM?: number;
+    /**
+     * Glass: the pane shows what is behind it, by how much it lets through and how little it reflects
+     * at the view angle, blurred by how frosted it is, tinted, and glowing with the lights behind it.
+     * It keeps its own lighting and highlight, which `refraction` alone replaces. Absent, or letting
+     * nothing through, is not glass. See `glass.ts`; `refraction` still bends what a pane shows.
+     */
+    readonly glass?: GlassOptions;
     /**
      * Whether this draw writes depth. `true`, which is what it has always done, unless a caller
      * says otherwise.
@@ -819,6 +879,8 @@ export declare class WebGL2Renderer implements RendererApi {
     /** Whether a palette is currently chosen. Distinct from whether one was ever uploaded. */
     private skinPaletteSet;
     private readonly emptyTexture2D;
+    /** One glass resolution reused by every draw, so a pane allocates nothing. See `glass.ts`. */
+    private readonly glassScratch;
     /** DriftLight's stand-ins while no field is whole: no brick anywhere, and no light. */
     private readonly emptyDriftIndex;
     private readonly emptyDriftAtlas;
@@ -870,6 +932,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private oitActive;
     /** True while the queue is being replayed, so a replayed draw does not record itself again. */
     private oitReplaying;
+    /** `uSurfaceScene`, resolved once a pass. See `surfaceScene.ts`. */
+    private readonly surfaceScene;
+    /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
+    private oitWeight;
+    private ditherFade;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     private oitRefused;
     /** Said once for the whole renderer. See `refuseOitMultisampled`. */
@@ -952,6 +1019,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly taaDepthToViewZ;
     private readonly aoInvProjection;
     private readonly aoProjScale;
+    /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
+    private readonly aoOffset;
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -1008,9 +1077,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly depthInstancedCutoutUniforms;
     private readonly scatterDepthProgram;
     private readonly scatterDepthUniforms;
-    private readonly shadowMap;
-    private readonly peeledShadowMap;
-    private readonly dynamicShadowMap;
+    /** The sun's static, moving and peeled maps, as layers of one array. See `shadowMap.ts`. */
+    private readonly sunShadows;
     private readonly pointShadows;
     /**
      * The layers a world's casting rectangles hold, above the point pool in the same array.
@@ -1044,12 +1112,15 @@ export declare class WebGL2Renderer implements RendererApi {
      * world. See `prepareStaticPointShadows`.
      */
     private pointShadowArray;
-    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
-    private iesTexture;
-    /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
+    /** The fixture atlas — cookies over profiles — allocated on first use. See `fixtureAtlas.ts`. */
+    private fixtureTexture;
+    /** The profiles as packed, kept so a new set of cookies can rebuild the atlas around them. */
+    private iesAtlas;
+    /** The cookie images, kept so a new set of profiles can rebuild the atlas around them. */
+    private cookieImages;
+    /** Rows of profile in the atlas. One until a consumer loads a profile, which is the row of ones. */
     private iesRows;
-    private cookieTexture;
-    /** Tiles in the cookie atlas. 0 is the white placeholder and the whole off path. */
+    /** Cookie tiles in the atlas. 0 is none, and the whole off path. */
     private cookieTiles;
     /** Horizontal planes each profile occupies. 1 unless something asymmetric was loaded. */
     private iesPlanes;
@@ -1181,7 +1252,7 @@ export declare class WebGL2Renderer implements RendererApi {
     /** Non-zero while the drawing buffer is pinned; see `lockDrawingBuffer`. */
     private lockedWidth;
     private lockedHeight;
-    private activeShadowMap;
+    private activeSunLayer;
     private reflectionPassActive;
     private reflectionReadyThisFrame;
     private reflectionAtmosphereY;
@@ -1203,7 +1274,7 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * **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
+     * peeled it sampled an occluder at the light. `SunShadowArray` 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.
      */
@@ -1229,6 +1300,21 @@ export declare class WebGL2Renderer implements RendererApi {
      * Built once at construction, arrow properties closing over `this`: a sink created
      * per pass would allocate six objects per light per frame.
      */
+    /** What the sun's light keeps through glass, made the first time glass casts: `sunGlassTint.ts`. */
+    private sunGlassTint;
+    /** The five programs a pane casts its colour through, compiled the first time glass casts. */
+    private glassTintPrograms;
+    /** True while the glass list is replayed into the glass depth layer through `casterSink`. */
+    private drawingGlassDepth;
+    /** How many times a shadow array grew its glass layers: once per family, and never again. */
+    private sunGlassRebuilds;
+    /** The light a tint pass is drawn for, and one pane's colour and clarity: uploaded per entry. */
+    private readonly glassLight;
+    private readonly glassPane;
+    /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
+    private readonly glassCasters;
+    /** One resolution every glass caster is read through, so recording one allocates nothing. */
+    private readonly glassCasterScratch;
     private readonly casterSink;
     /**
      * What a cutout depth draw needs beyond the plain one: the pass's matrix and peel, the material's
@@ -1236,6 +1322,13 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private bindCutoutDepth;
     private readonly drawPointShadowFace;
+    /**
+     * A lamp's glass, after each face's opaque depth: `PointShadowMap.bake` asks and binds, this
+     * draws, through the same sinks the sun's glass takes and in the face's own matrix.
+     */
+    private readonly pointGlassDraw;
+    /** The glass hook a bake is handed: none at all when glass shadows are off. */
+    private get pointGlass();
     /**
      * Viewport in CSS pixels rather than device pixels.
      *
@@ -1326,6 +1419,11 @@ export declare class WebGL2Renderer implements RendererApi {
      * other half of the same question.
      */
     occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * Whether a world-space box is wholly behind the declared occluders — the tighter question for
+     * something that is a box, such as a region. False with no occlusion buffer. See `occluded`.
+     */
+    occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
     private readonly passes;
     /** Built once so invoking somebody else's pass allocates nothing. See `PassDefinition.draw`. */
     /**
@@ -1441,7 +1539,17 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setSpotCookies(images: readonly TexImageSource[]): void;
     setIesProfiles(profiles: readonly PhotometricProfile[]): void;
-    /** Bind the atlas and say how many rows it has. Always, for the reason `bindClusters` gives. */
+    /**
+     * The fixture atlas from the profiles and cookies in hand: the profiles' rows at the bottom, the
+     * cookies' tiles on top, one `RGBA16F` texture. See `fixtureAtlas.ts` for the layout.
+     *
+     * **Half float, matching what the other backend must use**: a 32-bit float texture is not
+     * filterable in core WebGPU, and both tables are curves and images that want linear filtering.
+     * Linear and clamped: a profile is sampled between two angles, and a cookie's own inset is what
+     * keeps a tile from its neighbour — clamping alone cannot, the seam being interior to the row.
+     */
+    private buildFixtureAtlas;
+    /** Bind the fixture atlas and say what is in it. Always, for the reason `bindClusters` gives. */
     private bindIesAtlas;
     private bindClusters;
     /**
@@ -1601,6 +1709,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * the consumer's decision. What it gains is a GPU object with sane sampler state.
      */
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): SurfaceTexture;
+    /**
+     * Upload several images of one size as the layers of one array, for a merged mesh that names a
+     * layer per vertex (`MeshData.layers`). One material binding then covers every image, which is
+     * what makes a block wearing forty facades one draw. Every layer must be the same size, and the
+     * refusal names the first that is not.
+     */
+    createSurfaceTextureArray(sources: readonly TexImageSource[], options?: SurfaceTextureOptions): SurfaceTexture;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1730,6 +1845,29 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setEnvironmentAmbient(_amount: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * One float of material state, into every flat program.
+     *
+     * **Every one, for `setMaterial`'s reason**: an instanced or skinned draw runs a program of its
+     * own and is entitled to the material its caller set before it. These setters wrote the plain
+     * program alone until 2026-09-30, so on this backend a batch drew with the pass defaults — grain
+     * full, no reflection, no relief — while the other backend, whose material block every variant
+     * reads, drew what was asked.
+     */
+    private writeFlatFloat;
+    /**
+     * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
+     * of detail of one thing.
+     *
+     * 0 is off and is what `bindMeshPass` restores. A positive amount keeps that share of the
+     * pattern's cells, a negative one keeps the complement, so the level fading in drawn at `t` and
+     * the one fading out at `-t` cover every pixel exactly once — no hole, no pixel drawn twice.
+     * Material state like `setSurfaceGrain`; instanced draws read it too, and shadow casters, which
+     * are a pass of their own, do not. See `uDither` in `flat/preamble.ts` for what it costs.
+     */
+    setDitherFade(amount: number): void;
+    /** `uWriteMode`: the order-independent weight and the dither, which share one uniform row. */
+    private writeMode;
     /**
      * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
      *
@@ -1820,7 +1958,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * One batch per mesh: the attributes bind to the mesh's own vertex array, of which a mesh has
      * one. `Mesh.attachInstances` is what refuses a second, and says why.
      */
-    createInstanced(mesh: Mesh, capacity: number): InstancedBatch;
+    createInstanced(mesh: Mesh, capacity: number, options?: InstancedOptions): InstancedBatch;
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch: InstancedBatch, data: MeshInstances): void;
     /** Draw every live instance, opaque. */
@@ -1843,6 +1981,21 @@ export declare class WebGL2Renderer implements RendererApi {
      * consumer's, which is also where the placements are.
      */
     private submitInstanced;
+    /**
+     * Bind what a translucent draw shows through it: the frame's copy, refraction's bend and absorption,
+     * and glass. Returns whether the copy is bound, and so whether `unbindSeeThrough` owes it back.
+     *
+     * **A glass draw takes the copy even when it does not bend**, since a pane shows what is behind it
+     * either way, and asks for the copy's mip chain, which a frosted pane reads blurred. A null copy
+     * leaves both off, so the pane shades as ordinary translucency rather than sampling black.
+     *
+     * **Refused inside a probe's face or a mirror**, as WebGPU's `takeRefractSnapshot` refuses: the
+     * copy is of the frame drawn to the screen, so a pane there would show the wrong picture, and
+     * taking it mid-bake is how a probe's next face came to be attached to the scene's framebuffer.
+     */
+    private bindSeeThrough;
+    /** Put back what `bindSeeThrough` bound: the binding outlives its frame (the 2026-08-27 rule). */
+    private unbindSeeThrough;
     disposeMesh(mesh: Mesh): void;
     /**
      * Release a resource this renderer created, for every kind that needs the context back.
@@ -2329,6 +2482,25 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     drawSceneCasters(casters: ShadowCasters): void;
     drawShadowCasters(casters: ShadowCasters): void;
+    /**
+     * Draw the pass's glass twice: where the nearest pane is, and what the panes let through.
+     *
+     * After the opaque casters, in the pass's own light matrix. A layer that has held glass is
+     * redrawn even when this pass offered none, so glass that has gone takes its colour with it. The
+     * first glass grows the array (`SunShadowArray.growForGlass`) and makes the tint target.
+     */
+    private flushSunGlass;
+    /** The glass list into the glass depth layer: `casterSink` itself, with glass let through. */
+    private readonly glassDepthSink;
+    /** One pane's tint uniforms, and its cutout where it has one. */
+    private bindGlassTint;
+    /**
+     * The glass list into the tint layer, through the tint programs, **culling nothing**: a light
+     * crosses a pane whichever way the pane faces, and a closed glass object has two surfaces on a
+     * ray, so every one counts. What that asks of a model is that a pane be one surface — two-sided
+     * glass says so with `doubleSided`, and a second copy of its triangles is a second pane.
+     */
+    private readonly glassTintSink;
     endShadowPass(): void;
     /**
      * The lit program, built at the largest light budget this device will actually link.
@@ -2586,6 +2758,10 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * 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.
+     *
+     * **A reconstructing renderer depends on it**: its history is the last shot's, and without this
+     * call a cut blends that shot into the first frames of the next. Nothing detects a cut on the
+     * caller's behalf, deliberately — a fast pan and a cut look alike from here.
      */
     cameraCut(): void;
     /**
@@ -2981,6 +3157,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * the volume is summed into the frame once every brick has landed.
      */
     createLightField(lights: readonly LightFieldSource[], options?: Omit<LightFieldOptions, 'falloff'>): LightField;
+    /**
+     * Hand a world's DriftLight volume to the renderer: every fixed light of a city, summed offline by
+     * `bakeDenseField`, standing in past the frame's exact choice. Replaces any field made before, of
+     * either kind; the scene calls `field.follow(buffer.complete, ...)` each frame as it would for
+     * `createLightField`, and marks the lights the volume summed `inLightField` so none is counted
+     * twice. See `driftLight/worldLightField.ts`.
+     */
+    createWorldLightField(volume: DenseLightVolume, options?: WorldLightFieldOptions): WorldLightField;
     /** Let go of the field and its volumes; the scene's lights are all exact again. */
     disposeLightField(): void;
     private forgetLightFieldVolumes;
@@ -3050,13 +3234,14 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     tint?: Vec3 | null, 
     /**
-     * Where the mesh was last frame, which this backend takes and ignores.
+     * Where the mesh was last frame — a `Mover` or a matrix — which this backend takes and ignores.
      *
      * Accepted rather than absent so that one scene draws through both renderers unchanged — the
      * parity rule this repository is built on. Reconstruction is WebGPU's, having no compute stage
-     * here, so there is no motion target for this to be written into.
+     * here, so there is no motion target for this to be written into, and a mover passed here is
+     * neither read nor advanced.
      */
-    _previousModel?: ReadonlyMat4 | null): void;
+    _previousModel?: ReadonlyMat4 | Mover | null): void;
     /**
      * Draw a mesh you can see through, in the same material as everything else by default.
      *