@driftengine/core 4.3.0 → 4.4.0

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

@@ -55,6 +55,8 @@ 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 { LightField } from '../../driftLight/lightField.ts';
+import type { LightFieldOptions, LightFieldSource } from '../../driftLight/lightField.ts';
 /** Which directional shadow map a pass is filling, matching `renderer.ts`. */
 type ShadowLayer = 'static' | 'static-peel' | 'dynamic';
 export declare class WebGPURenderer implements RendererApi {
@@ -770,11 +772,19 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly frameEye;
     /** The environment the frame was drawn with. See `bindMeshPass`. */
     private frameEnv;
+    /**
+     * The sky this frame drew, or null until it draws one. A traced probe's escaping rays read it,
+     * so a frame that stops drawing a sky must not go on lighting its probes with the last one.
+     */
+    private frameSky;
     /** That matrix with the clip-space correction folded in, rebuilt once a frame. */
     private readonly correctedViewProj;
     private readonly skyLayout;
+    /**
+     * A slot a sky draw, as every per-draw resource here is: see `UniformRing` and the 2026-08-27 rule.
+     * It was one buffer rewritten at each draw, which gave every sky in an encoder the last camera.
+     */
     private readonly skyUniforms;
-    private readonly skyStaging;
     private readonly skyFloats;
     private readonly skyBindGroup;
     /** The camera's inverse with the clip correction undone, rebuilt once a frame. */
@@ -940,7 +950,27 @@ export declare class WebGPURenderer implements RendererApi {
      * prefix that has already been uploaded costs one write of unchanged bytes and cannot be
      * wrong: a ring only ever appends within a frame.
      */
+    /**
+     * Every per-draw ring the frame writes and flushes together, in one list.
+     *
+     * **One list, read by the flush and by the probe bake's rewind**, so a ring added to one cannot be
+     * forgotten by the other: a ring flushed but never rewound would let a grid bake spend it, and one
+     * rewound but never flushed would upload nothing. Built on first use, after the constructor has
+     * set every field; `growTo` replaces a ring's buffer, never the ring, so the list stays true.
+     */
+    private ringList;
+    private rings;
     private flushRings;
+    /** Where every ring stands before work that submits an encoder of its own. */
+    private readonly ringMarks;
+    private markRings;
+    /**
+     * Give back every slot taken since `markRings`, once that work has been submitted.
+     *
+     * See `UniformRing.rewind` for why this is safe only after the submit. The palette ring goes back
+     * with them, and the cached palette slot is dropped if it was one of those given back.
+     */
+    private rewindRings;
     private readonly filmLayout;
     private readonly filmVerts;
     private readonly filmFrags;
@@ -1013,6 +1043,8 @@ export declare class WebGPURenderer implements RendererApi {
     private blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
     private readonly uvScale;
+    /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
+    private materialDoubleSided;
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): GpuSurfaceTexture;
     /**
      * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
@@ -1464,7 +1496,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly scatterLayout;
     /** One slot per batch: the gust and the trample field belong to the batch, not the frame. */
     private readonly scatterVerts;
-    private readonly scatterFragUniforms;
+    /** A slot a draw, beside the vertex block's: see `createScatterBindGroupLayout` for why. */
+    private readonly scatterFrags;
     private readonly scatterFragStaging;
     private readonly scatterFragFloats;
     private readonly scatterFragInts;
@@ -1607,17 +1640,28 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly dynamicView;
     /** The peel's own bind groups: `uPeelShadowLayer` at 1, and the static map to peel against. */
     private readonly shadowPeelBindGroup;
+    /**
+     * The cutout casters' layout, and a bind group per cutout map for each layer, built the first
+     * time a map casts and kept: a `createBindGroup` per draw is the allocation the house rules forbid.
+     * Cleared in `forgetBindingsOf`, because a group outliving its texture is a destroyed-texture error
+     * at submit, and a texture's view is new when an update changes its size.
+     */
+    private readonly shadowCutoutLayout;
+    private readonly cutoutGroups;
+    private readonly cutoutPeelGroups;
+    private shadowPeelPassUniforms;
+    private shadowPeelSampler;
     private readonly scatterDepthPeelBindGroup;
     /** Which layer the open pass is writing, so the sink picks the bindings that match it. */
     private shadowLayerIsPeel;
     /**
      * Whether a peel pass has filled the map, which is what the frame may sample it on.
      *
-     * **Not whether the map exists.** `renderer.ts` can ask that question because a GL texture is
-     * born cleared; a WebGPU texture no pass has written holds undefined contents, so a scene
-     * that builds a peel map and never opens the layer would sample garbage. Cleared when the
-     * static layer opens and set when a peel pass ends, which is per frame because both demo
-     * scenes that peel do so every frame.
+     * **Not whether the map exists.** `renderer.ts` asked that question, on the belief that a GL
+     * texture is born reading as the far plane, and it is born zeroed: a scene that built a peel
+     * map and never opened the layer had no sun at all under ANGLE's GL backend. It holds this
+     * rule now as well. Cleared when the static layer opens and set when a peel pass ends, which
+     * is per frame because every scene that peels does so every frame.
      */
     private peelFilled;
     /** One slot per caster, the same trick `perDraw` uses and for the same reason. */
@@ -1658,6 +1702,10 @@ export declare class WebGPURenderer implements RendererApi {
      * otherwise. A lookup rather than a rebind, because a `createBindGroup` per draw is the
      * per-frame allocation the house rules forbid; both groups are built once at init.
      */
+    /** The cutout bind group for `texture` in the open layer, built the first time it casts there. */
+    private cutoutGroup;
+    /** The cutoff and UV scale into a cutout draw's slot, at the offsets its own variant declares. */
+    private writeCutout;
     private shadowGroup;
     /**
      * The skinned shadow bind group for the current layer, rebuilt only when it must be.
@@ -1934,6 +1982,14 @@ export declare class WebGPURenderer implements RendererApi {
     private materialSlotForDraw;
     /** Said once rather than every frame, for the reason `warnedFull` gives. */
     private warnedMaterialsFull;
+    private warnedSkyFull;
+    private warnedParticlesTwice;
+    /**
+     * Which encoder draws are being recorded into, by count: a new one at every `beginFrame`, and one
+     * of its own for each probe bake, restored after. What a batch drawn per encoder is checked by.
+     */
+    private encoderEpoch;
+    private encoderEpochs;
     /**
      * Draw one mesh.
      *
@@ -2281,6 +2337,22 @@ export declare class WebGPURenderer implements RendererApi {
      * that is wrong once.
      */
     private rebuildFlatGroupsForNewRings;
+    /**
+     * The environment view the cached flat groups bind: the grid, or the blank stand-in while the
+     * grid may not be read. What `rebindEnvironment` compares against.
+     */
+    private flatEnvironment;
+    /**
+     * Rebuild the flat groups if, and only if, the environment they bind has changed.
+     *
+     * **Every cached group holds the environment view**, so a change of it makes all of them stale;
+     * but nothing else a bake does touches a group. Rebuilding on every bake's two edges regardless
+     * emptied the cache twice a bake, and every material built its group again inside the bake and
+     * again after it: a courtyard re-baking a few faces a frame spent 28% of its CPU there on the
+     * native host, where a `createBindGroup` costs most. What would make this wrong is a second
+     * binding that a bake changes, which would have to be compared here too.
+     */
+    private rebindEnvironment;
     /**
      * Rebuild the group for the open material, and drop every cached one.
      *
@@ -3074,6 +3146,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** This frame's exposure into the tone curve. Starts at the profile's own. */
     private exposure;
     private bloomScale;
+    /** In scene units, once `setBloom` has moved it; null reads the profile's. */
+    private bloomThresholdSet;
     private rushStrength;
     private motionBlurScale;
     /**
@@ -3085,6 +3159,30 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private readonly veilColor;
     private veilAlpha;
+    private vignette;
+    private grain;
+    private grainSeed;
+    private warnedLookWithoutComposite;
+    /** Eye adaptation: how far, this frame's time step, and the pass once asked for. */
+    private autoExposure;
+    private autoExposureDt;
+    /** How far each region is brought toward the frame. See `setLocalExposure`. */
+    private localExposure;
+    private exposurePass;
+    /**
+     * 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 warnLookWithoutComposite;
     /** How much of the frame's bloom to apply, 0 to 1. Scales the profile's `bloom`. */
     /**
      * The colour grade this and every later frame applies, until it is set again.
@@ -3111,7 +3209,7 @@ export declare class WebGPURenderer implements RendererApi {
      * a 3D write needs both and a wrong one silently shears the cube.
      */
     private uploadGrade;
-    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.
      *
@@ -3124,6 +3222,33 @@ export declare class WebGPURenderer implements RendererApi {
     setSpeedRush(strength: number): void;
     /** How much of the frame's camera motion blur to apply, 0 to 1. */
     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. **The other backend's `setAutoExposure` carries the reasoning**, whole; this is
+     * the same setter over the same state, and the pass is built the first time it is asked for, so
+     * a renderer that never adapts carries none of it.
+     */
+    setAutoExposure(strength: number, dtSec: number): void;
+    /**
+     * Local exposure. **The other backend's `setLocalExposure` carries the reasoning**, whole; this is
+     * the same setter over the same state, sharing eye adaptation's pass, which is built the first
+     * time either is asked for.
+     */
+    setLocalExposure(strength: number): void;
+    /** The exposure pass, built once; the composite's group holds placeholders until it exists. */
+    private ensureExposurePass;
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take. **The other backend's `setDepthOfField` carries the reasoning**, whole: the
@@ -3203,6 +3328,8 @@ export declare class WebGPURenderer implements RendererApi {
      * over a lobe-convolved one.
      */
     private readonly probe;
+    /** The views, groups and attachments a bake draws with, made once. See `probeTargets.ts`. */
+    private readonly probeTargets;
     /**
      * The prefiltered cube: what the lit pass samples, one GGX-convolved level per roughness.
      *
@@ -3234,6 +3361,19 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly probeMipLayout;
     /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
     private iesTexture;
+    /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
+    private lightField;
+    private driftIndex;
+    private driftAtlas;
+    private driftIndexView;
+    private driftAtlasView;
+    private readonly driftUniforms;
+    /** The same field resolved for a traced probe, and what the baker binds; null while not whole. */
+    private readonly bakeDriftUniforms;
+    private bakeLightField;
+    /** 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;
@@ -3258,8 +3398,9 @@ export declare class WebGPURenderer implements RendererApi {
      * mirroring uninitialised memory is worse than a car mirroring a gradient — the rule one probe
      * already had, unchanged by there being more of them.
      */
-    private probeFilled;
-    private probeFilledCount;
+    private probeSweeps;
+    /** `uProbeGridSets`, rewritten in place. */
+    private readonly probeSets;
     /**
      * Whether a bake is running, which is when the cube may be neither sampled nor bound.
      *
@@ -3267,9 +3408,17 @@ export declare class WebGPURenderer implements RendererApi {
      * load-bearing rather than defensive: WebGPU rejects a pass that holds the texture it writes.
      */
     private probePassActive;
+    /** Whether the bake under way lights its faces by the grid. `ProbeBakeOptions.bounce`. */
+    private probeBounce;
+    /**
+     * Whether the shading may read the grid now: once every probe is filled, and not during a bake
+     * unless it is a bounce bake. A bounce bake's faces are drawn into the probe's own cube and only
+     * the resolve writes the array, in a pass of its own, so no pass both samples and writes it.
+     */
+    private probeReadable;
     /** How many mip levels the roughness blur has to work with. `flat.ts` reads this. */
     private get probeMaxLod();
-    /** Whether every layer of the grid has been convolved. See `probeFilled`. */
+    /** Whether a whole sweep of the grid has been convolved. See `probeSweeps.ts`. */
     private get probeBaked();
     /**
      * Record that one layer now holds a convolution, without counting a rebake twice.
@@ -3378,6 +3527,20 @@ export declare class WebGPURenderer implements RendererApi {
      * call a tile fills the row without a canvas in between.
      */
     setSpotCookies(images: readonly TexImageSource[]): void;
+    /**
+     * 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;
+    /** 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, and rebuild the groups
+     * that bind them: nothing samples them before that, so uploading as bricks land would be work
+     * for no picture, and a rebuild per brick would be a bind group per brick.
+     */
+    private uploadLightField;
     setIesProfiles(profiles: readonly PhotometricProfile[]): void;
     /** Each level from the one above it, six faces at a time. See `probePass.ts`. */
     private buildProbeChain;