@driftengine/core 4.8.5 → 4.8.7

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

@@ -13,6 +13,7 @@ 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 { type BloomResponse } from '../../bloomChain.ts';
 import { LightField } from '../../driftLight/lightField.ts';
 import type { LightFieldOptions, LightFieldSource } from '../../driftLight/lightField.ts';
 import type { DenseLightVolume } from '../../driftLight/denseField.ts';
@@ -33,6 +34,7 @@ import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts
  * Beyond this the velocity is shortened and the direction kept.
  */
 import type { RendererApi } from '../api.ts';
+import type { LightmapPage } from '../../lightmap.ts';
 import type { ClothBindingData } from '../../clothBindingData.ts';
 import { GlClothBinding, GlClothParticles } from './clothTextures.ts';
 import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
@@ -59,7 +61,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';
@@ -196,6 +198,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;
     /**
@@ -208,6 +215,12 @@ export interface Environment extends Atmosphere {
     lightIesAxes: Float32Array;
     /** One per active light: a tile of the cookie atlas, or −1 for none. */
     lightCookies: Float32Array;
+    /**
+     * One per active light: the lighting channels it lights, a mask from 1 to 255. Absent, short, or
+     * a light at 1 is the default channel every surface is on too. See `PointLightSet.lightChannels`
+     * and `SurfaceMaterial.lightChannels`.
+     */
+    lightChannels?: Float32Array;
     /**
      * The rectangular emitters this frame, or null for none.
      *
@@ -994,6 +1007,23 @@ export declare class WebGL2Renderer implements RendererApi {
     private motionBlurScale;
     /** How much of the bloom ceiling this frame takes. See `setBloom`. */
     private bloomScale;
+    /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
+    private readonly ambientSH;
+    /** Scratch for a sprite's depth conversion, so a particle draw allocates nothing. */
+    private readonly spriteInverseProjection;
+    /** Said once: a sprite asked for a soft edge where no depth copy could be had. */
+    private warnedSpriteDepth;
+    /** Said once: more rectangles than the fixed arm shades, and no froxel table for the rest. */
+    private warnedAreaOverflow;
+    /**
+     * `uEnvironmentDials` as it stands: which chain the probe holds, the reflectivity, the gain. One
+     * vector on the device, so written whole, and kept here so a setter moving one keeps the others.
+     */
+    private readonly environmentDials;
+    /** `uEmission` as it stands: the emissive gain and the night factor. */
+    private readonly emission;
+    /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
+    private readonly bloomResponse;
     /** In scene units, once `setBloom` has moved it; null reads the profile's. */
     private bloomThresholdSet;
     /**
@@ -1206,6 +1236,15 @@ 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 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. */
@@ -1806,6 +1845,23 @@ export declare class WebGL2Renderer implements RendererApi {
      * refusal names the first that is not.
      */
     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.
      *
@@ -1937,17 +1993,17 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     private restoreSurfaceTextureUnit;
     /**
-     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     * 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:
+     * the sky's gradient, or the probes'. See `ambientHarmonics.ts` for the basis and the axes.
      *
-     * 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.
+     * **For a thing lit by where it stands**: a consumer sampling a stage's baked volume of indirect
+     * light at a character every frame sets the result around that character's draws, and the
+     * character takes the light of its spot rather than the frame's. It replaces the diffuse ambient
+     * 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.
      *
@@ -1987,6 +2043,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.
@@ -2014,6 +2082,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * reads, drew what was asked.
      */
     private writeFlatFloat;
+    /** A vector of material state, two to four floats, into every flat program. */
+    private writeFlatVector;
     /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
     private writeFlatInt;
     /**
@@ -2320,6 +2390,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.
      *
@@ -2330,6 +2407,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * whole milestone from a buffer nothing had ever written.
      */
     drawParticles(batch: ParticleBatch, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /**
+     * A sprite's two fades and the depth copy the soft one reads. The copy is the frame's opaque
+     * depth, so it is taken only in the frame's own picture: in a mirror or a probe's face it would
+     * be another view's, and the edge stays hard there. Without a scene target there is no copy at
+     * all, and the renderer says so once rather than drawing a hard edge that was asked to be soft.
+     */
+    private bindSpriteFades;
     /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
     createBolts(segmentCapacity: number, label?: string): BoltBatch;
     /**
@@ -3039,8 +3123,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * 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.
+     *
+     * **`response` is how a colour comes in past the threshold and what colour each octave of the
+     * halo takes** — a ramp in place of the subtraction, and a tint a level — held until moved like
+     * the threshold; `null` goes back to the subtraction and white. See `BloomResponse`: it is what
+     * matches a stage built for another engine's bloom, whose tints are how a strength past 1 is
+     * asked for.
      */
-    setBloom(scale: number, threshold?: number): void;
+    setBloom(scale: number, threshold?: number, response?: BloomResponse | null): void;
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
      *
@@ -3550,6 +3640,25 @@ export declare class WebGL2Renderer implements RendererApi {
         readonly height: number;
         readonly data: Float32Array;
     }, options?: ProbeBakeOptions): boolean;
+    /**
+     * One layer of the declared probe grid from an image, the way `setEnvironmentImage` fills a
+     * single probe: the same equirectangular image of linear RGB floats, projected onto the capture
+     * cube and prefiltered into that layer, the others left as they are. Returns false — and says
+     * why — where there is no probe, no grid, or no such layer.
+     *
+     * **What it is for**: a scene baked somewhere else. Another engine's reflection captures are
+     * images taken where each one stands; a consumer fits them to a lattice — for each point, the
+     * capture whose reach holds it — and hands each point its image here, where `bakeProbe` would
+     * have drawn this engine's own world into it.
+     *
+     * `options.irradiance` decides, at grid scope as a bake's does, whether the grid also lights the
+     * scene's diffuse ambient. A grid that crossfades writes the set being swept, as a bake does.
+     */
+    setProbeLayerImage(layer: number, image: {
+        readonly width: number;
+        readonly height: number;
+        readonly data: Float32Array;
+    }, options?: ProbeBakeOptions): boolean;
     /**
      * Draw a volume of light: a beam from a lamp, a shaft through a window, the cone under a
      * street light.