@driftengine/core 4.8.2 → 4.8.4

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

@@ -33,6 +33,8 @@ 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 { ClothBindingData } from '../../clothBindingData.ts';
+import { GlClothBinding, GlClothParticles } from './clothTextures.ts';
 import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
 import type { ProbeGridOptions } from '../../probeGrid.ts';
 import type { AreaLightBuffer, AreaLightSource } from '../../areaLights.ts';
@@ -45,6 +47,7 @@ import type { IncrementalMesh } from '../../mesh.ts';
 import type { MeshData } from '../../mesh.ts';
 import type { MeshOptions } from '../api.ts';
 import { SurfaceTexture } from '../../surfaceTexture.ts';
+import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import { PlumeRenderer } from '../../plumeRenderer.ts';
 import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
@@ -823,6 +826,17 @@ export declare class WebGL2Renderer implements RendererApi {
     private flatMorphedUniforms;
     private flatBothProgram;
     private flatBothUniforms;
+    /**
+     * The two skinned variants built with `SKIN_EIGHT` on, for a rig whose vertices name eight
+     * joints: compiled the first time such a mesh is created, and only then. See `skinning.ts`.
+     */
+    private flatSkinned8Program;
+    private flatSkinned8Uniforms;
+    private flatBoth8Program;
+    private flatBoth8Uniforms;
+    /** And its shadow caster, so the shadow parts from nothing the body does. */
+    private depthSkinned8Program;
+    private depthSkinned8Uniforms;
     /** The morph weights the following draws use, or null for none. */
     private morphWeights;
     /**
@@ -856,6 +870,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * before this existed.
      */
     private readonly sceneTarget;
+    /**
+     * Skin's screen-space scattering, made where the profile asks for it and has a composite to add
+     * into, and null otherwise — which is every profile by default. See `GlSkinScatter`.
+     */
+    private readonly skinScatter;
+    /** Whether this frame has spread its skin: once, at its first blended draw or at its end. */
+    private skinScattered;
+    private readonly skinInverseProjection;
     /** So the refusal below is once per renderer rather than once per frame. See `setColourGrade`. */
     private warnedGradeWithoutComposite;
     /** Scratch for a volume's `uDepthToLocal`. Built per draw and never allocated in the loop. */
@@ -878,6 +900,21 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly skinPalette;
     /** Whether a palette is currently chosen. Distinct from whether one was ever uploaded. */
     private skinPaletteSet;
+    /**
+     * Cloth-bound skinned lit programs, keyed `eight|morphed`, compiled when a binding is made for a
+     * mesh of that kind; and their casters, keyed by `eight`. See `ensureClothPrograms`.
+     */
+    private readonly clothFlat;
+    private readonly clothDepth;
+    /** The cloth the next skinned draws are placed by, or null. See `setCloth`. */
+    private cloth;
+    /**
+     * Each shading model's lit programs, keyed `variant|model` by the vertex variant they pair with,
+     * compiled the first time a draw asks for one. See `modelProgram`.
+     */
+    private readonly modelFlat;
+    /** The last palette chosen, which an eye's axis is turned by. See `setSkinPalette`. */
+    private paletteData;
     private readonly emptyTexture2D;
     /** One glass resolution reused by every draw, so a pane allocates nothing. See `glass.ts`. */
     private readonly glassScratch;
@@ -936,6 +973,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly surfaceScene;
     /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
     private oitWeight;
+    /**
+     * How the surfaces drawn next meet the medium: what `setSurfaceFog` set, and `FOG_RECEDE` from
+     * each `bindMeshPass`. A translucent draw's own fog is measured against this and puts it back.
+     */
+    private surfaceFog;
     private ditherFade;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     private oitRefused;
@@ -1298,6 +1340,22 @@ export declare class WebGL2Renderer implements RendererApi {
     private materialHasMaps;
     /** The material last set, so a lit program rebuilt for glass can be given it. */
     private currentMaterial;
+    /**
+     * The frame a dithered cutout's pattern is offset by, advanced at `beginFrame` and wrapped at 64
+     * so the noise's argument stays small. See `cutoutDither.ts`.
+     */
+    private cutoutFrame;
+    /** Scratch for `uCutout`, so a material write allocates nothing. */
+    private readonly cutoutVector;
+    /** The material's model numbers, `uModelParams`, packed by `packModel`. */
+    private readonly modelParams;
+    /** The material's four switches, `uMaterialFlags`: albedo, ORM map, emissive map, two-sided. */
+    private readonly materialFlags;
+    /**
+     * The default framebuffer's sample count, read once, for a frame drawn with no scene target: a
+     * dithered cutout there takes alpha-to-coverage when the canvas itself is multisampled.
+     */
+    private readonly canvasSamples;
     /**
      * The lit stage's switches: what the lit programs were compiled with (`litOn`), and what the
      * profile and the content have asked for since (`litWanted`).
@@ -1729,14 +1787,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * a canvas drawn procedurally at runtime, a decoded bitmap, a video frame — stays
      * the consumer's decision. What it gains is a GPU object with sane sampler state.
      */
-    createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): SurfaceTexture;
+    createSurfaceTexture(source: SurfaceSource, options?: SurfaceTextureOptions): SurfaceTexture;
+    private compressedCache;
+    /**
+     * The BC formats this device takes as blocks, each named with its colour space (`'bc7-srgb'`).
+     *
+     * **Ask before choosing**, because a phone usually answers none: a BC texture handed to
+     * `createSurfaceTexture` where its format is not here is refused by name rather than decoded,
+     * since core ships no decoder. `@driftengine/assets`' loader asks this for every BC texture in a
+     * container and decodes at load where the answer is no. Read from the four extensions WebGL2
+     * spreads BC across; see `glCompressed.ts`.
+     */
+    get compressedFormats(): readonly CompressedTextureFormat[];
     /**
      * 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;
+    createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): SurfaceTexture;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1777,6 +1846,51 @@ export declare class WebGL2Renderer implements RendererApi {
      * runtime out of core.
      */
     setSkinPalette(palette: Float32Array | null): void;
+    /**
+     * The lit program for one vertex variant shading by a model: the standard program's vertex
+     * stage, and the fragment stage with the model's switch on (`modelBound`). Compiled the first
+     * time a draw asks — a scene that names no model compiles none — and fed the pass and the
+     * material at once, as `ensureClothPrograms` feeds its own.
+     */
+    private modelProgram;
+    /**
+     * An eye's axis in the world for this draw, into its program's `uModelParams`: the material's
+     * own numbers with the axis turned by the draw's model matrix and the eye's joint. See
+     * `eyeAxisInWorld`.
+     */
+    private writeEyeAxis;
+    /**
+     * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it,
+     * and by how much. See `ClothBindingData`.
+     *
+     * Refused by name for a mesh with no rig — a binding blends a vertex between its skinning and the
+     * cloth — and for one that disagrees with the mesh. Compiles the programs that draw and cast it
+     * here, at creation, so no frame ever waits on a compile.
+     */
+    createClothBinding(mesh: Mesh, data: ClothBindingData): GlClothBinding;
+    /** One character's particles, `count` of them, to be updated every frame. */
+    createClothParticles(count: number): GlClothParticles;
+    /**
+     * This frame's particles, three floats each, world space; last frame's are kept for motion. A
+     * simulation's output, as it is.
+     */
+    updateClothParticles(particles: GlClothParticles, positions: Float32Array): void;
+    /**
+     * Place the following skinned draws by a cloth: `binding` the mesh's, `particles` the
+     * character's. Null for none, which is every draw until this is called. Both or neither, and
+     * the particles must be as many as the binding names.
+     */
+    setCloth(binding: GlClothBinding | null, particles?: GlClothParticles | null): void;
+    disposeClothBinding(binding: GlClothBinding): void;
+    disposeClothParticles(particles: GlClothParticles): void;
+    /**
+     * The cloth-bound lit program and caster for a rig of this kind, once. Fed at once if a pass is
+     * bound, for the reason `ensureVariant` gives: a program compiled after `bindMeshPass` would
+     * otherwise carry every uniform at zero.
+     */
+    private ensureClothPrograms;
+    /** Bind the cloth's three textures to their units and name them to `u`. */
+    private bindCloth;
     /**
      * Choose the morph weights the following `drawMesh` calls deform by, or null for none.
      *
@@ -1786,6 +1900,14 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setMorphWeights(weights: Float32Array | null): void;
     setMaterial(material: SurfaceMaterial | null): void;
+    /**
+     * How a material's cutout edge is drawn this frame: the material's mode against what the frame can
+     * resolve. A translucent draw tests hard whatever the material says, because a blended draw has
+     * nothing to average a pattern with. See `cutoutDither.ts`.
+     */
+    private cutoutResolveNow;
+    /** The lit pass's `uCutout` for a material this frame, into scratch. See `uCutout`. */
+    private cutoutUniform;
     /**
      * One flat program's view of the current material.
      *
@@ -1808,7 +1930,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * Rebind `SURFACE_TEXTURE_UNIT` to whatever `setSurfaceTexture` last put there.
      *
      * Only `drawSdfText` calls this, after the atlas has finished borrowing the same unit.
-     * No uniform is written here — the flat program's `uAlbedo`/`uAlbedoEnabled` were never
+     * No uniform is written here — the flat program's `uAlbedo` and its flag in `uMaterialFlags` were never
      * touched by the text draw and are still correct, since that draw runs its own separate
      * program. What moved is unit 15's actual `WebGLTexture` binding, which is GL state, not
      * program state, and this puts it back to what `currentSurfaceTexture` says it should be.
@@ -1866,6 +1988,22 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setEnvironmentAmbient(_amount: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
+     * True is the default, and what `bindMeshPass` restores.
+     *
+     * **The opaque counterpart of `TranslucentMeshOptions.fog`**, which a translucent draw has had
+     * all along; the shader's per-draw switch was there, and nothing reached it for an ordinary mesh.
+     * What it is for is a medium that darkens one thing and not another — a floor receding into the
+     * distance under figures that must keep their full value however far from the camera they stand.
+     * Material state like `setSurfaceGrain`: instanced and skinned draws read it too, and a
+     * translucent draw's own `fog` is measured against it and puts it back.
+     *
+     * **What it gives up** is the medium's honesty: a surface out of the fog is drawn as though the
+     * air between it and the eye were empty, so it should be a surface the scene means to stand
+     * apart, not one whose distance is the point.
+     */
+    setSurfaceFog(enabled: boolean): void;
     /**
      * One float of material state, into every flat program.
      *
@@ -1876,6 +2014,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * reads, drew what was asked.
      */
     private writeFlatFloat;
+    /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
+    private writeFlatInt;
     /**
      * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
      * of detail of one thing.
@@ -3288,6 +3428,22 @@ export declare class WebGL2Renderer implements RendererApi {
      * neither read nor advanced.
      */
     _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.
+     */
+    private skinSplits;
+    /**
+     * Spread the frame's skin and add it back: once, at the first blended draw or at the frame's end.
+     * Called first in every draw WebGPU records as blended — translucent meshes and batches, text,
+     * particles, plumes, wind streaks, bolts, lines, caustics, film — so the two backends add skin at
+     * the same point. The frame's depth is copied for the blur to read, and where it cannot be the
+     * diffuse goes back unspread rather than not at all.
+     */
+    private scatterSkin;
+    /** One draw of a mesh, as `drawMesh` describes, of the half of a skin `half` names. */
+    private drawMeshHalf;
     /**
      * Draw a mesh you can see through, in the same material as everything else by default.
      *