@driftengine/core 4.8.6 → 4.9.0

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

@@ -12,6 +12,7 @@ import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
 import type { PassDefinition, PassHandle } from '../../pass.ts';
 import type { Vec3 } from '../../../math/color.ts';
 import { GpuTimer } from '../../gpuTimer.ts';
+import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
 import { type BloomResponse } from '../../bloomChain.ts';
 import { LightField } from '../../driftLight/lightField.ts';
@@ -61,7 +62,7 @@ import type { Atmosphere } from '../../atmosphere.ts';
 import { InstancedMesh } from '../../instancedMesh.ts';
 import { ParticleBatch } from '../../particleBatch.ts';
 import type { ParticleBatchOptions } from '../../particleBatch.ts';
-import type { ParticleInstances } from '../../particlePool.ts';
+import type { DeviceParticles, ParticleInstances } from '../../particlePool.ts';
 import { BoltBatch } from '../../boltBatch.ts';
 import type { BoltSegments } from '../../boltPool.ts';
 import { LineBatch } from '../../lineBatch.ts';
@@ -72,6 +73,8 @@ import { TextRenderer } from '../../textRenderer.ts';
 import { SdfTextRenderer } from '../../sdfTextRenderer.ts';
 import type { SdfFont } from '../../sdfFont.ts';
 import type { SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { DisplayRange } from '../../displayRange.ts';
+import { type FilmicCurve } from '../../filmicCurve.ts';
 import type { RenderBackend } from '../api.ts';
 import type { TextStyle } from '../../textLayout.ts';
 import { WindStreakRenderer } from '../../windStreakRenderer.ts';
@@ -198,6 +201,11 @@ export interface Environment extends Atmosphere {
     lightDirections: Float32Array;
     /** Two per active light: the cosine of the inner cone angle, then of the outer. */
     lightConeCos: Float32Array;
+    /**
+     * One per active light: its own falloff exponent, or 0 for the frame's. Optional: absent is 0 for
+     * every light. See `PointLightSource.falloffExponent`.
+     */
+    lightFalloffExponents?: Float32Array;
     /** One per active light: a row of the photometric atlas, or −1 for none. */
     lightIesProfiles: Float32Array;
     /**
@@ -969,6 +977,10 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly reflectionQueue;
     /** Built on the first frame that submits a surface, and never for a scene with none. */
     private ssr;
+    /** The frame's materials' reflections, resolved; null where off. See `frameReflections.ts`. */
+    private readonly frameReflections;
+    /** Their two maps on the scene's framebuffer, null where they cannot be drawn. */
+    private readonly reflectionTargets;
     /** Said once where a reflection cannot be traced at all. */
     private reflectionsRefused;
     /** Where the frame's camera stands, which is what gives a reconstructed normal its sign. */
@@ -1028,6 +1040,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it asked to be and nothing about it changes.
      */
     private exposure;
+    /** The `filmic` curve's eight constants, held until `setFilmicCurve` is called again. */
+    private readonly filmConstants;
     /**
      * This frame's veil colour, and how much of it to composite. See `setFrameVeil`.
      *
@@ -1229,8 +1243,26 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedNoPointShadowArray;
     /** Said once, for the retired ambient dial. */
     private warnedEnvironmentAmbient;
+    /** The overlay the draws wear, `uOverlay`: see `setSurfaceOverlay`. */
+    private readonly overlayFloats;
+    /** Its atlas, and the 2D copy of it bound where the refraction copy goes. */
+    private overlayMaps;
+    private overlayTexture;
+    /** Whether this device's lit stage has room for the overlay's vectors: asked once. */
+    private overlayRoom;
+    private warnedOverlayRoom;
+    private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
+    /**
+     * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
+     * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
+     */
+    private capturePassActive;
+    /** Each capture's framebuffer, beside the texture a material binds. See `createSceneCapture`. */
+    private readonly captureTargets;
+    /** Said once, where a driver refuses to draw into a capture. */
+    private warnedCapture;
     /** 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. */
@@ -1544,6 +1576,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * call. `init` runs now rather than at the first frame, because building a pipeline in the
      * frame loop is the allocation the house rules are about.
      */
+    /** Each registered pass's declared reads, as a mask, resolved once at registration. */
+    private readonly passReads;
     registerPass(definition: PassDefinition): PassHandle;
     /**
      * How many registered passes declare `prepare`, so a frame with none walks nothing.
@@ -1833,6 +1867,21 @@ export declare class WebGL2Renderer implements RendererApi {
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): SurfaceTexture;
     /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
     createLightmap(page: LightmapPage): SurfaceTexture;
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. Half floats where the frame keeps range, as a probe does.
+     */
+    createSceneCapture(width: number, height: number): SurfaceTexture;
+    /**
+     * Draw the scene into a capture from `camera`: `draw` is handed the camera, its matrices updated
+     * for the capture's shape, and submits the scene as it would to the screen. See `RendererApi`.
+     *
+     * **Radiance, as a probe bake stores it**: the output transform and exposure are held off for the
+     * pass, so the frame grades a screen showing it once. No temporal jitter, which a capture has no
+     * resolve to undo. Returns whether it drew: false for a texture that is not a capture, or one the
+     * driver will not draw into.
+     */
+    captureScene(capture: SurfaceTexture, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1963,18 +2012,6 @@ export declare class WebGL2Renderer implements RendererApi {
      * program state, and this puts it back to what `currentSurfaceTexture` says it should be.
      */
     private restoreSurfaceTextureUnit;
-    /**
-     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
-     *
-     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
-     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
-     * This stays as the override for the case that has no answer to state: an imported model
-     * arrives with no grain information at all, and a caller drawing one decides for it.
-     *
-     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
-     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
-     * leaves geometry that did not exactly as it is.
-     */
     /**
      * The ambient the following draws take, as nine spherical-harmonic coefficients of incoming
      * radiance — red, green and blue of each, twenty-seven numbers — or `null` for the frame's own:
@@ -1986,6 +2023,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * only — a glossy surface still reflects the probes — and it is pass state like the material,
      * which `bindMeshPass` clears, so a mirror or a probe bake drawn after does not inherit it.
      */
+    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     /**
      * How much of the environment the following draws mirror, 0 to 1.
      *
@@ -1996,8 +2034,28 @@ export declare class WebGL2Renderer implements RendererApi {
      * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
      * exactly as it did.
      */
-    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     setSurfaceReflectivity(amount: number): void;
+    /**
+     * The overlay the following draws wear — a rim of light, a dissolve, wrinkles by region — or null
+     * for none. Pass state, as the material is: `bindMeshPass` puts it back to none. See
+     * `surfaceOverlay.ts` for what it lays and `shaders/flat/overlay.ts` for how.
+     *
+     * **Refused, said once, where the lit stage has no room for it.** Fifteen vectors more than the
+     * program this device fits: counted from the source as `fitFlatProgram` counts, and on a device
+     * whose limit is the 256 an Adreno 740 reports, the eight-light build at 254 has none. The draws
+     * then wear nothing, which is the picture a game without the feature draws. Its atlas is bound as
+     * a 2D copy of its first layer, in the refraction copy's unit (`SurfaceTexture.flatLayer`); a
+     * compressed atlas has no copy and is read as none, also said once.
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
+    /** The overlay's atlas into the refraction copy's unit, as a 2D copy, or the empty texture. */
+    private bindOverlayMaps;
+    /** The most fragment uniform vectors this GPU offers a stage. */
+    private fragmentVectorLimit;
+    /** What the lit shader at this renderer's budget leaves of the limit, with no overlay. */
+    private overlayRoomLeft;
+    /** Whether the lit shader with the overlay compiled in fits this GPU: counted once. */
+    private overlayFits;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
      *
@@ -2026,6 +2084,18 @@ export declare class WebGL2Renderer implements RendererApi {
      * a coordinated release is happening anyway.
      */
     setEnvironmentAmbient(_amount: number): void;
+    /**
+     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     *
+     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
+     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
+     * This stays as the override for the case that has no answer to state: an imported model
+     * arrives with no grain information at all, and a caller drawing one decides for it.
+     *
+     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
+     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
+     * leaves geometry that did not exactly as it is.
+     */
     setSurfaceGrain(amount: number): void;
     /**
      * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
@@ -2361,6 +2431,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * emitters; it is a material that knows what a particle is.
      */
     createParticles(capacity: number, options: ParticleBatchOptions): ParticleBatch;
+    /**
+     * Particles a caller's own compute wrote: WebGPU's alone, since this backend has no compute stage
+     * to have written them (`computeSupported`). Said once, and nothing is drawn.
+     */
+    drawDeviceParticles(_batch: ParticleBatch, _particles: DeviceParticles, _camera: Camera, _env: Environment, _timeSeconds: number): void;
+    /** Said once: see `drawDeviceParticles`. */
+    private warnedDeviceParticles;
     /**
      * Draw a live particle pool.
      *
@@ -2979,8 +3056,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * Set before `beginFrame` and held until changed, like `setSpeedRush`, which it sits
      * beside for the same reason: both describe how the finished image is presented rather
      * than anything in the world.
+     *
+     * `maxShare` is the longest smear, as a share of the frame (0.03 unless given, at most half): a
+     * fast turn softens the frame rather than erasing it. **Each drawn object's own motion is
+     * followed only under a reconstruction on WebGPU**, which draws the motion target it reads; here,
+     * and on WebGPU without one, the camera's motion alone smears the frame, and a draw that names
+     * where it was last frame is told so once.
      */
-    setCameraMotionBlur(scale: number): void;
+    setCameraMotionBlur(scale: number, maxShare?: number): void;
+    /** The longest smear, as a share of the frame. See `setCameraMotionBlur`. */
+    private motionBlurMax;
+    private warnedObjectBlur;
     /**
      * The camera has cut: this frame is a new shot, not the next moment of the last one.
      *
@@ -3142,6 +3228,30 @@ export declare class WebGL2Renderer implements RendererApi {
      * black frame with a sign error in it.
      */
     setOutputExposure(exposure: number): void;
+    /**
+     * The `filmic` curve this and every later frame is graded through, until it is set again: a
+     * grading volume's five numbers, solved once here into the constants the resolve reads. Ignored
+     * unless `outputTransform` is `filmic`. A number out of range is clamped into it and said once,
+     * since a frame loop must not throw. See `filmicCurve.ts`.
+     */
+    setFilmicCurve(curve: FilmicCurve): void;
+    private warnedFilmClamped;
+    /**
+     * The range the frame goes out in: `'high'` where the profile asked for `highDynamicRange`, the
+     * frame holds light past white and the display shows it — on WebGPU — and `'standard'` otherwise.
+     * **Always standard here**: this backend draws into a canvas of eight bits a channel, which has
+     * nothing above white to show. Typed as the question rather than this backend's answer, because
+     * the shared surface is derived from this class.
+     */
+    readonly displayRange: DisplayRange;
+    /** Why it is that range, in words, for a game choosing its look and for a bug report. */
+    get displayRangeReason(): string;
+    /**
+     * How bright paper white and the display's peak are, in one unit, held until changed: their
+     * ratio is how far above white the highlights may run where `displayRange` is `'high'`, and
+     * nothing changes where it is standard, which is always here.
+     */
+    setDisplayLuminance(paperWhite: number, peak: number): void;
     /**
      * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
      *
@@ -3206,6 +3316,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
      */
     setVignette(strength: number): void;
+    /**
+     * The lens's colour fringe, held until changed: `intensity` is a percentage, 0 is none, and red
+     * and green are pulled toward the centre by their wavelength's distance from blue, growing from
+     * `start` — a share of the half-frame, 0 the centre — to the whole of it at the edge. Applied to
+     * scene light at the composite's first read. Needs `screenEffects`, and says so once rather than
+     * doing nothing. See `shaders/fringe.ts`.
+     */
+    setChromaticAberration(intensity: number, start?: 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
@@ -3481,12 +3599,18 @@ export declare class WebGL2Renderer implements RendererApi {
      * 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 | Mover | null): void;
+    previousModel?: ReadonlyMat4 | Mover | null): void;
     /**
      * Whether a skin draw now draws its two halves: the profile asked, the frame has not spread its
      * skin yet, this is the frame's own picture — not a mirror's or a probe's, nor an overlay after
      * the frame — and the blur's target can be had.
      */
+    /**
+     * Whether a draw now is the frame's own, opaque and lit, and so writes the two maps beside its
+     * colour: not a mirror's, a probe's or a capture's, whose framebuffers have no maps, and not after
+     * the frame. See `reflectionSurfaceTargets.ts`.
+     */
+    private reflectionKeeps;
     private skinSplits;
     /**
      * Spread the frame's skin and add it back: once, at the first blended draw or at the frame's end.