@driftengine/core 4.5.0 → 4.6.0

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

@@ -55,9 +55,12 @@ import type { Bounds } from '../../../math/bounds.ts';
 import { type ComputeDefinition, type ComputeHandle } from '../../compute.ts';
 import type { PassDefinition, PassHandle } from '../../pass.ts';
 import { GpuInstancedBatch } from './instanced.ts';
-import type { MeshInstances } from '../../instances.ts';
+import type { InstancedOptions, MeshInstances } from '../../instances.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';
 /** Which directional shadow map a pass is filling, matching `renderer.ts`. */
 type ShadowLayer = 'static' | 'static-peel' | 'dynamic';
 export declare class WebGPURenderer implements RendererApi {
@@ -513,6 +516,12 @@ export declare class WebGPURenderer implements RendererApi {
      * what the layout already declares.
      */
     private bloomGroups;
+    /**
+     * The picture the bloom reads, and its size: the scene target, or while reconstructing the
+     * resolved picture at the drawing buffer's size. See `rebuildBloomGroups`.
+     */
+    private bloomSourceWidth;
+    private bloomSourceHeight;
     private frameWidth;
     private frameHeight;
     /**
@@ -671,6 +680,18 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private reconHistories;
     private reconHistoryViews;
+    /**
+     * Each output pixel's flicker record, a pair swapped with the histories: the temporal resolve's
+     * anti-flicker, over the reconstruction's own period (`recon/resolve.ts`).
+     */
+    private reconFlickers;
+    private reconFlickerViews;
+    /** Each output pixel's held depth swing, a pair of its own: see `recon/resolve.ts`. */
+    private reconSwings;
+    private reconSwingViews;
+    /** The anti-flicker's rule for the period last asked for, kept so a frame makes none. */
+    private reconFlickerPhases;
+    private reconFlickerRule;
     private reconWrite;
     private reconHasHistory;
     private reconShown;
@@ -704,6 +725,9 @@ export declare class WebGPURenderer implements RendererApi {
     /** Last frame's raw view-projection and its inverse, and the two eyes. */
     private readonly reconPreviousRawViewProj;
     private readonly reconInverseViewProj;
+    /** The inverse and the reprojection, multiplied in double precision. See `runReconstruction`. */
+    private readonly reconInverse64;
+    private readonly reconReprojection64;
     private readonly reconPreviousInverseViewProj;
     private readonly reconEye;
     private readonly reconPreviousEye;
@@ -831,6 +855,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** Said once for the whole renderer. See `refuseOitMultisampled`. */
     private oitMultisampleRefused;
     private oitReplaying;
+    /** `uSurfaceScene`, resolved once a pass. See `surfaceScene.ts`. */
+    private readonly surfaceScene;
     /** Which buffer the replay is filling, which the pipeline key must carry. */
     private oitMode;
     /**
@@ -1061,6 +1087,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     private materialDoubleSided;
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): GpuSurfaceTexture;
+    /** Several images of one size as an array's layers. See `RendererApi.createSurfaceTextureArray`. */
+    createSurfaceTextureArray(sources: readonly TexImageSource[], options?: SurfaceTextureOptions): GpuSurfaceTexture;
     /**
      * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
      *
@@ -1139,6 +1167,13 @@ export declare class WebGPURenderer implements RendererApi {
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
     setEnvironmentGain(gain: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * How much of the surfaces drawn next survives a screen-door dither. See `renderer.ts`.
+     *
+     * Written straight into the scratch block rather than through `material()`'s callback, because
+     * this one is called per crossfading region per frame and a closure per call is an allocation.
+     */
+    setDitherFade(amount: number): void;
     /**
      * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
      *
@@ -1479,6 +1514,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly waterLayout;
     /** The one-pixel stand-in, kept so the water bind group can be rebuilt without one. */
     private readonly blankView;
+    /** The blank texel as a one-layer array: the stand-in every surface-texture binding takes. */
+    private readonly blankSurfaceView;
     private readonly blankSampler;
     /**
      * A slot per body, not one buffer rewritten before each draw.
@@ -2142,9 +2179,11 @@ export declare class WebGPURenderer implements RendererApi {
      * anyway, because WebGL2 *cannot* and a capability one backend has and the other does not is
      * the shape this repository spent a week removing.
      */
-    createInstanced(mesh: GpuMesh, capacity: number): GpuInstancedBatch;
-    /** Which meshes already carry a batch, so a second is refused rather than silently shared. */
-    private readonly instanced;
+    createInstanced(mesh: GpuMesh, capacity: number, options?: InstancedOptions): GpuInstancedBatch;
+    /** The device instance culls, built on the first culling draw. See `InstanceCullPass`. */
+    private instanceCulls;
+    /** Counts frames, so a batch knows when its cull slots were last taken. */
+    private cullFrame;
     /** Push placement and colour. Only the live prefix; see `GpuInstancedBatch.upload`. */
     uploadInstanced(batch: GpuInstancedBatch, data: MeshInstances): void;
     /** Draw every live instance, opaque. */
@@ -2177,6 +2216,12 @@ export declare class WebGPURenderer implements RendererApi {
      * **What it gives up** against `drawMesh` is skinning and morphing, refused where the variant
      * is built, and a per-instance opacity: `opacity` here dims the whole batch.
      */
+    /**
+     * The next of a batch's cull slots this frame, with its cull queued against the current view; null
+     * when the batch has drawn from `MAX_CULL_SLOTS` views already or the frame's job ring is full,
+     * and the draw then takes every instance.
+     */
+    private takeCullSlot;
     private submitInstanced;
     /** Upload a base mesh and size its per-instance buffers. See `createGpuScatter`. */
     createScatter(base: MeshData, data: InstanceData): GpuScatter;
@@ -2541,6 +2586,8 @@ export declare class WebGPURenderer implements RendererApi {
      * called whenever any of them is replaced.
      */
     private rebuildReconGroups;
+    /** This frame's jitter and temporal frame, decided where its scene camera is bound. See `bindMeshPass`. */
+    private jitterFrame;
     /**
      * Whether a blended draw recorded now lands after the upscale. See `lateRouting.ts`.
      *
@@ -3056,6 +3103,8 @@ export declare class WebGPURenderer implements RendererApi {
      * declares nothing behaves exactly as it did before. Read it beside `visible`, which answers the
      * other half of the same question.
      */
+    /** Whether a world-space box is wholly behind the declared occluders. See `Renderer.occludedBox`. */
+    occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
     occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
     private readonly passes;
     /** Each registered pass's declared reads, as a mask, resolved once at registration. */
@@ -3240,6 +3289,13 @@ export declare class WebGPURenderer implements RendererApi {
     beginInset(rect: InsetRect, clearColor: Vec3 | null): number;
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset(): void;
+    /**
+     * The size of the attachment the open pass draws into: the swap image — the drawing buffer —
+     * in the overlay after the present, the scene's render size in the frame's own pass. A tuple
+     * held once rather than a new array a call.
+     */
+    private passSize;
+    private readonly passSizeOut;
     /**
      * Copy a rectangle of the frame into a 2D canvas, pixel for pixel.
      *
@@ -3476,8 +3532,12 @@ export declare class WebGPURenderer implements RendererApi {
     private probeView;
     private readonly probeSize;
     private readonly probeMipLayout;
-    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
-    private iesTexture;
+    /** The fixture atlas — cookies over profiles — built on first use. See `fixtureAtlas.ts`. */
+    private fixtureTexture;
+    private fixtureView;
+    /** The profiles as packed and the cookie images, kept so either can rebuild the atlas. */
+    private iesAtlas;
+    private cookieImages;
     /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
     private lightField;
     private driftIndex;
@@ -3491,10 +3551,7 @@ export declare class WebGPURenderer implements RendererApi {
     /** The frame's exact lights packed for the traced bake. See `gi/bounceLights.ts`. */
     private readonly bounceLights;
     private readonly bakeLamps;
-    private iesView;
-    private cookieTexture;
-    private cookieView;
-    /** 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;
     /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
     private iesRows;
@@ -3644,11 +3701,30 @@ export declare class WebGPURenderer implements RendererApi {
      * call a tile fills the row without a canvas in between.
      */
     setSpotCookies(images: readonly TexImageSource[]): void;
+    /** Let the atlas go, to be built again from what is in hand the next time it is bound. */
+    private forgetFixtureAtlas;
+    /**
+     * The fixture atlas's view, built from the profiles and cookies in hand if it is not already: the
+     * profiles' rows at the bottom, the cookies' tiles on top. See `renderer.ts` and `fixtureAtlas.ts`.
+     *
+     * **`rgba16float`, not `rgba32float`**: a 32-bit float texture is not filterable in core WebGPU,
+     * and binding one to a filtering sampler takes the whole bind group with it. Both tables want
+     * linear filtering. `RENDER_ATTACHMENT` because `copyExternalImageToTexture` writes through one.
+     */
+    private fixtureAtlasView;
     /**
      * Sum a scene's many fixed lights into a DriftLight field. The same contract as
      * `Renderer.createLightField`; see `driftLight/lightField.ts`.
      */
     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;
@@ -3694,6 +3770,20 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private buildMediumBindGroup;
     private ensureComposite;
+    /**
+     * One group per source the bloom chain reads, in the order `runBloom` indexes them: the picture
+     * first, then every level. The prefilter reads the picture; the downsample into level `i` reads
+     * level `i - 1`, which is group `i`; the upsample into level `i - 1` reads level `i`, which is
+     * group `i + 1`.
+     *
+     * **While reconstructing the picture is the resolved one**, which `ensureReconstruction` makes
+     * after this runs and rebuilds these over. The scene target is the jittered render then: a bright
+     * thing smaller than a render texel is caught in some phases and missed in others, and its halo,
+     * wide and over everything round it, flashed with it — a night street's panels breathing a few
+     * levels of luma frame to frame. Built at the drawing buffer's size, which `ensureComposite`
+     * already sized the pyramid for.
+     */
+    private rebuildBloomGroups;
     /**
      * Every bloom stage's uniform block, written once per size rather than once per frame.
      *