@driftengine/core 4.9.0 → 4.10.0

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

@@ -1,6 +1,7 @@
 import type { MeshInstances } from '../../instances.ts';
 import type { Mesh } from '../../mesh.ts';
 import type { FrustumPlanes } from '../../../math/frustum.ts';
+import { GlInstanceClocks, type GlBoneAnimation } from './boneAnimations.ts';
 /**
  * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
@@ -29,7 +30,10 @@ export declare class InstancedBatch {
     /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
     private keptRegioned;
     private readonly kept;
-    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean);
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    readonly animation: GlBoneAnimation | null;
+    readonly clocks: GlInstanceClocks | null;
+    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean, animation?: GlBoneAnimation | null);
     upload(gl: WebGL2RenderingContext, data: MeshInstances): void;
     /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
     draw(gl: WebGL2RenderingContext, count: number): void;

package/dist/render/backend/webgl2/instanced.js

@@ -1,5 +1,7 @@
 import { cullInstances, instancesBox } from '../../instanceCull.js';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, createMeshInstances, packInstances, } from '../../instances.js';
+import { packInstanceClocks } from '../../boneAnimation.js';
+import { GlInstanceClocks } from './boneAnimations.js';
 /**
  * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
@@ -28,10 +30,15 @@ export class InstancedBatch {
     /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
     keptRegioned = null;
     kept;
-    constructor(gl, mesh, capacity, cull = false) {
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    animation;
+    clocks;
+    constructor(gl, mesh, capacity, cull = false, animation = null) {
         this.mesh = mesh;
         this.capacity = capacity;
         this.cull = cull;
+        this.animation = animation;
+        this.clocks = animation === null ? null : new GlInstanceClocks(gl, capacity);
         this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
         this.buffer = allocate(gl, capacity);
         this.vao = mesh.createInstanceArray(gl, this.buffer, INSTANCE_STRIDE);
@@ -56,6 +63,10 @@ export class InstancedBatch {
         packInstances(data, this.staging);
         gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
         gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
+        if (this.clocks !== null) {
+            packInstanceClocks(data, this.clocks.staging);
+            this.clocks.upload(gl, count);
+        }
     }
     /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
     draw(gl, count) {
@@ -88,6 +99,7 @@ export class InstancedBatch {
     dispose(gl) {
         gl.deleteVertexArray(this.vao);
         gl.deleteBuffer(this.buffer);
+        this.clocks?.dispose(gl);
         if (this.kept !== null) {
             gl.deleteVertexArray(this.kept.vao);
             gl.deleteBuffer(this.kept.buffer);

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

@@ -44,13 +44,14 @@ import type { AreaLightBuffer, AreaLightSource } from '../../areaLights.ts';
 import type { PhotometricProfile } from '../../iesProfile.ts';
 import type { ShadowLight } from '../../pointShadowSystem.ts';
 import type { ShadowCasters } from '../../shadowCasters.ts';
+import type { StaticDrawsHandle } from '../../staticDraws.ts';
 import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts';
 import { Mesh } from '../../mesh.ts';
 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 { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import { PlumeRenderer } from '../../plumeRenderer.ts';
 import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
@@ -82,6 +83,7 @@ import type { WindStreakOptions } from '../../windStreakRenderer.ts';
 import type { WindField } from '../../windField.ts';
 import type { FlockParams } from '../../flockRenderer.ts';
 import { InstancedBatch } from './instanced.ts';
+import type { BoneAnimationClip, BoneAnimationHandle } from '../../boneAnimation.ts';
 import type { InstancedOptions, MeshInstances } from '../../instances.ts';
 /** Reused each frame: which shader light slot each bound cubemap serves. */
 export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
@@ -1156,6 +1158,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly depthCutoutUniforms;
     private readonly depthInstancedCutoutProgram;
     private readonly depthInstancedCutoutUniforms;
+    /** A crowd's casters: the instanced depth programs that play a bone animation. */
+    private readonly depthAnimatedProgram;
+    private readonly depthAnimatedUniforms;
+    private readonly depthAnimatedCutoutProgram;
+    private readonly depthAnimatedCutoutUniforms;
     private readonly scatterDepthProgram;
     private readonly scatterDepthUniforms;
     /** The sun's static, moving and peeled maps, as layers of one array. See `shadowMap.ts`. */
@@ -1894,7 +1901,7 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * Not a hot path — it re-uploads the whole image and regenerates the mip chain.
      */
-    updateSurfaceTexture(texture: SurfaceTexture, source: TexImageSource): void;
+    updateSurfaceTexture(texture: SurfaceTexture, source: TexImageSource | CompressedTextureSource): void;
     disposeSurfaceTexture(texture: SurfaceTexture): void;
     /**
      * Choose the surface texture the following `drawMesh` calls sample, or `null` for none.
@@ -2035,6 +2042,16 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it did.
      */
     setSurfaceReflectivity(amount: number): void;
+    /**
+     * The reflectivity and environment gain the setters gave the pass, and the ones the material
+     * set now states, or null where it states none (`SurfaceMaterial.reflectivity`). A draw wears the
+     * material's where it has one and the pass's otherwise.
+     */
+    private passReflectivity;
+    private passEnvironmentGain;
+    private materialReflectivity;
+    private materialEnvironmentGain;
+    private writeEnvironmentDials;
     /**
      * 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
@@ -2231,6 +2248,40 @@ export declare class WebGL2Renderer implements RendererApi {
      * one. `Mesh.attachInstances` is what refuses a second, and says why.
      */
     createInstanced(mesh: Mesh, capacity: number, options?: InstancedOptions): InstancedBatch;
+    /**
+     * A bone animation an instanced batch can play (`InstancedOptions.animation`): per frame, a turn
+     * and a place for each bone, which every vertex of the batch's mesh follows — the bone its second
+     * coordinates' u names, times `boneScale` — at each instance's own moment of the clip. What a
+     * crowd is made of: every instance moves at the frame's rate on its own clock, in the colour pass
+     * and in every shadow, with nothing on the processor after this. See `boneAnimation.ts` for the
+     * clip's layout and the arithmetic, which both backends run.
+     *
+     * What it gives up against skinning is the blend: a vertex follows one bone. Refused, with what
+     * was wrong, for a clip whose numbers are not its size, or past 2,048 bones or frames.
+     */
+    createBoneAnimation(clip: BoneAnimationClip): BoneAnimationHandle;
+    /** Release a clip. A batch still playing it draws nothing, and casts nothing, after. */
+    disposeBoneAnimation(animation: BoneAnimationHandle): void;
+    /**
+     * The clock a bone animation plays by this frame, in seconds on the caller's clock: an instance's
+     * moment is this times its rate plus its phase (`MeshInstances.clocks`). **Set it before the
+     * shadows are drawn**, once a frame, as the wind is set: a shadow drawn under one clock and its
+     * caster under another come apart at the frame's rate. 0 until set, which holds every crowd at
+     * the moment its phases name.
+     */
+    setAnimationTime(seconds: number): void;
+    /** The clock `setAnimationTime` set. */
+    private animationTime;
+    /**
+     * An animated batch's clip, clocks and numbers into whichever program is bound: the three vertex
+     * textures on units of their own (`lightBudget.ts`), the clip's speed and bone scale, the clock.
+     */
+    private bindAnimation;
+    /** The animated instanced program, compiled on first use. See `ensureInstancedProgram`. */
+    private flatAnimatedProgram;
+    private flatAnimatedUniforms;
+    /** Compile the animated variant, once, and feed it this frame's pass state. */
+    private ensureAnimatedProgram;
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch: InstancedBatch, data: MeshInstances): void;
     /** Draw every live instance, opaque. */
@@ -2765,6 +2816,43 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     drawSceneCasters(casters: ShadowCasters): void;
     drawShadowCasters(casters: ShadowCasters): void;
+    /**
+     * Draws that do not change between frames, enumerated once and kept: what a stage, a set or any
+     * world that stands still draws, recorded so a frame replays it rather than issuing it.
+     *
+     * **The same enumeration `drawSceneCasters` takes**, called once, here: rigid meshes and instanced
+     * batches, each with its material. A skinned mesh or a scatter batch is refused by name, since
+     * both change every frame. What it captures is what the enumeration said at the time — the
+     * matrices and the instance counts are copied, so a caller's scratch is free to move on — while
+     * the meshes, batches, textures and materials stay the caller's: a list must be disposed, or made
+     * again, before anything it holds is, and made again when a material it holds is changed.
+     *
+     * **What it is for is the frame's processor time.** WebGPU records the list into a render bundle
+     * per view and replays it with one call, where a draw issued a frame at a time costs its encoding
+     * every frame and again for every view that draws it. This backend has no bundles and replays the
+     * entries through the scene-caster path every frame, at the cost a frame drawing them itself pays;
+     * the picture is the same.
+     *
+     * What a list gives up against drawing each frame is culling: every entry is drawn in every view,
+     * because a bundle cannot leave one out. A world split into lists by region culls by list.
+     */
+    createStaticDraws(casters: ShadowCasters): StaticDrawsHandle;
+    /**
+     * Draw a list into the open mesh pass, under the camera, the lights and the fog `bindMeshPass`
+     * set — the frame's, a mirror's, a capture's. Opaque draws, through each entry's material.
+     *
+     * **Its draws are rigid and wear no overlay**, so a skin palette, morph weights, cloth or a surface
+     * overlay set before it is put back to none, as `bindMeshPass` puts an overlay back; and no
+     * material is left set after it, which is what `setMaterial(null)` leaves. The state a pass set —
+     * the grain, the relief, the fog, the grade — is the list's to draw with, as it is any draw's, and
+     * a list drawn under a different one is recorded again for it on WebGPU.
+     */
+    drawStaticDraws(draws: StaticDrawsHandle): void;
+    /** Release a list. Its meshes, batches and materials are the caller's and are not released. */
+    disposeStaticDraws(draws: StaticDrawsHandle): void;
+    /** A disposed list drawn, said once: the frame loop does not throw. */
+    private warnStaticDisposed;
+    private warnedStaticDisposed;
     /**
      * Draw the pass's glass twice: where the nearest pane is, and what the panes let through.
      *