@driftengine/core 3.61.0

package/dist/render/livePointShadowSet.d.ts

@@ -0,0 +1,72 @@
+import type { PointShadowSource, ResolvedPointShadows } from './pointShadowImage.ts';
+interface PositionedLight {
+    x: number;
+    y: number;
+    z: number;
+}
+export declare class LivePointShadowSet<M extends PointShadowSource> {
+    private readonly releaseMap;
+    private readonly maps;
+    private readonly owners;
+    private readonly weights;
+    private primarySlot;
+    private transitionFromSlot;
+    private transitionToSlot;
+    private transitionSeconds;
+    /**
+     * `createMap` rather than a context and a size, so the pool never names a device.
+     * `releaseMap` for the same reason: freeing one is the backend's business.
+     */
+    constructor(createMap: (layer: number) => M, releaseMap: (map: M) => void);
+    update(lights: readonly PositionedLight[], sampled: Int32Array, sampledCount: number, x: number, y: number, z: number, frameDt: number): void;
+    /**
+     * A slot changing hands throws its image away, exactly as a pool slot does.
+     *
+     * **`PointShadowSystem` does this and this class did not**, and the asymmetry is what let a
+     * lamp cast a shadow with nothing making it. A live map holds only movers, baked around the
+     * light that owned the slot — so a slot handed to a different lamp keeps `hasBaked` true and
+     * publishes an image of a mover standing where it stood *near the other light*, at whatever
+     * weight the handover gave it. That map's own pool comment states the rule for the static
+     * half: sampling a slot before its new owner's bake lands reads "another lamp's shadow, from
+     * somewhere else entirely". It is the same rule here and it was not applied.
+     *
+     * A no-op when the slot was free or is being handed back to the same light, so a steady state
+     * does not throw away a good image every frame.
+     */
+    private take;
+    owner(slot: number, sampled: Int32Array, sampledCount: number): number;
+    map(slot: number): M | undefined;
+    /**
+     * Settle the live pair's shader slots and parameters into the caller's arrays.
+     *
+     * The maps themselves stay here and are handed out by `map`, because binding a cubemap is
+     * the one part of this that differs between backends — see `ResolvedPointShadows`.
+     */
+    resolve(sampled: Int32Array, shaderSlots: Int32Array, sampledCount: number, out: ResolvedPointShadows): void;
+    /**
+     * Ramp both live images toward full presence.
+     *
+     * **This did not exist, and its absence meant a moving caster was never shadowed by a point
+     * light at all.** `resolve` publishes `crossfade weight * presence`, and presence is the map's
+     * own arrival ramp — which only moves when something advances it. `PointShadowSystem.advance`
+     * walks *its* pool, and these two are not in it, so the ramp stayed at zero for every frame this
+     * engine has ever rendered. The shader multiplied a correct occlusion by a weight of zero.
+     *
+     * Nothing about it was visible from either side. The layer is baked, the layer index and far
+     * plane are published, `hasBaked` is true and the crossfade weight is 1 — every part reports
+     * itself healthy, and the product of them is nothing. It was found by reading the resolved
+     * weights off a live renderer rather than by reading this file, and the octahedral layer had the
+     * caster in it the whole time.
+     *
+     * The pair is advanced whether or not either is owned: an unowned slot has no image, `advance`
+     * on it is the branch that holds the ramp at zero, and skipping it here would be a second place
+     * that has to know which slots are live.
+     */
+    advance(dt: number): void;
+    /** See `PointShadowSystem.forgetEveryImage`: the storage under these maps was replaced. */
+    forgetEveryImage(): void;
+    dispose(): void;
+    private finishTransition;
+    private clearTransition;
+}
+export {};

package/dist/render/livePointShadowSet.js

@@ -0,0 +1,258 @@
+import { LIVE_POINT_SHADOW_MAPS } from './lightBudget.js';
+/**
+ * Two live-caster cubemaps with a continuous handoff between owning lights.
+ *
+ * The steady state uses one map. The second is activated only while a nearer
+ * light takes ownership, allowing the old shadow to fade out as the new one
+ * fades in instead of switching a moving caster in one frame.
+ *
+ * **Generic over the map, because none of the handoff is about a device.** Which light owns
+ * which slot, how long a crossfade has run and what weight each carries are the same answers
+ * whichever API holds the cubemaps, and a second copy of them is a shadow that changes hands
+ * differently depending on which backend drew it.
+ */
+/** A quick handoff reads as motion, not as a light switching off. */
+const TRANSITION_SECONDS = 0.18;
+/** A challenger must be 10% nearer before ownership changes. */
+const DISPLACE_RATIO = 0.81;
+export class LivePointShadowSet {
+    releaseMap;
+    maps = [];
+    owners = new Int32Array(LIVE_POINT_SHADOW_MAPS).fill(-1);
+    weights = new Float32Array(LIVE_POINT_SHADOW_MAPS);
+    primarySlot = 0;
+    transitionFromSlot = -1;
+    transitionToSlot = -1;
+    transitionSeconds = 0;
+    /**
+     * `createMap` rather than a context and a size, so the pool never names a device.
+     * `releaseMap` for the same reason: freeing one is the backend's business.
+     */
+    constructor(createMap, releaseMap) {
+        this.releaseMap = releaseMap;
+        /*
+         * The live maps take the array's **first** layers, and that is why they can be built here.
+         *
+         * They are created when the renderer is, before any world has said how many lights it has, so
+         * a layer counted from the end of the array would not yet have a number. Counted from the
+         * front they do: 0 and 1, always, with pool slot i at LIVE_POINT_SHADOW_MAPS + i.
+         */
+        for (let i = 0; i < LIVE_POINT_SHADOW_MAPS; i++)
+            this.maps.push(createMap(i));
+    }
+    update(lights, sampled, sampledCount, x, y, z, frameDt) {
+        if (this.transitionFromSlot >= 0) {
+            const fromOwner = this.owners[this.transitionFromSlot] ?? -1;
+            const toOwner = this.owners[this.transitionToSlot] ?? -1;
+            if (!isSampled(toOwner, sampled, sampledCount)) {
+                this.owners[this.transitionToSlot] = -1;
+                this.weights[this.transitionToSlot] = 0;
+                this.weights[this.transitionFromSlot] = 1;
+                this.clearTransition();
+            }
+            else if (!isSampled(fromOwner, sampled, sampledCount)) {
+                this.finishTransition();
+            }
+            else {
+                this.transitionSeconds += frameDt;
+                const t = Math.min(this.transitionSeconds / TRANSITION_SECONDS, 1);
+                this.weights[this.transitionFromSlot] = 1 - t;
+                this.weights[this.transitionToSlot] = t;
+                if (t >= 1)
+                    this.finishTransition();
+            }
+            if (this.transitionFromSlot >= 0)
+                return;
+        }
+        let nearest = -1;
+        let nearestDistance = Infinity;
+        for (let slot = 0; slot < sampledCount; slot++) {
+            const worldIndex = sampled[slot] ?? -1;
+            const light = worldIndex >= 0 ? lights[worldIndex] : undefined;
+            if (light === undefined)
+                continue;
+            const dx = light.x - x;
+            const dy = light.y - y;
+            const dz = light.z - z;
+            const distance = dx * dx + dy * dy + dz * dz;
+            if (distance < nearestDistance) {
+                nearest = worldIndex;
+                nearestDistance = distance;
+            }
+        }
+        if (nearest < 0) {
+            this.owners.fill(-1);
+            this.weights.fill(0);
+            this.clearTransition();
+            return;
+        }
+        const current = this.owners[this.primarySlot] ?? -1;
+        if (current < 0 || !isSampled(current, sampled, sampledCount)) {
+            this.owners.fill(-1);
+            this.weights.fill(0);
+            this.owners[this.primarySlot] = nearest;
+            this.weights[this.primarySlot] = 1;
+            /* The image in that map was baked around whichever light held the slot before, so it is
+               another lamp's shadow standing under this one until a bake replaces it. See `take`. */
+            this.take(this.primarySlot, current);
+            this.clearTransition();
+            return;
+        }
+        if (nearest === current)
+            return;
+        const currentLight = lights[current];
+        if (currentLight !== undefined) {
+            const dx = currentLight.x - x;
+            const dy = currentLight.y - y;
+            const dz = currentLight.z - z;
+            const currentDistance = dx * dx + dy * dy + dz * dz;
+            if (nearestDistance >= currentDistance * DISPLACE_RATIO)
+                return;
+        }
+        const nextSlot = 1 - this.primarySlot;
+        const displaced = this.owners[nextSlot] ?? -1;
+        this.owners[nextSlot] = nearest;
+        this.weights[nextSlot] = 0;
+        this.take(nextSlot, displaced);
+        this.transitionFromSlot = this.primarySlot;
+        this.transitionToSlot = nextSlot;
+        this.transitionSeconds = 0;
+    }
+    /**
+     * A slot changing hands throws its image away, exactly as a pool slot does.
+     *
+     * **`PointShadowSystem` does this and this class did not**, and the asymmetry is what let a
+     * lamp cast a shadow with nothing making it. A live map holds only movers, baked around the
+     * light that owned the slot — so a slot handed to a different lamp keeps `hasBaked` true and
+     * publishes an image of a mover standing where it stood *near the other light*, at whatever
+     * weight the handover gave it. That map's own pool comment states the rule for the static
+     * half: sampling a slot before its new owner's bake lands reads "another lamp's shadow, from
+     * somewhere else entirely". It is the same rule here and it was not applied.
+     *
+     * A no-op when the slot was free or is being handed back to the same light, so a steady state
+     * does not throw away a good image every frame.
+     */
+    take(slot, previousOwner) {
+        if (previousOwner < 0 || previousOwner === this.owners[slot])
+            return;
+        this.maps[slot]?.forget();
+    }
+    owner(slot, sampled, sampledCount) {
+        const owner = this.owners[slot] ?? -1;
+        return isSampled(owner, sampled, sampledCount) ? owner : -1;
+    }
+    map(slot) {
+        return this.maps[slot];
+    }
+    /**
+     * Settle the live pair's shader slots and parameters into the caller's arrays.
+     *
+     * The maps themselves stay here and are handed out by `map`, because binding a cubemap is
+     * the one part of this that differs between backends — see `ResolvedPointShadows`.
+     */
+    resolve(sampled, shaderSlots, sampledCount, out) {
+        out.liveLayers.fill(-1);
+        out.liveFar.fill(1);
+        out.liveNear.fill(0.01);
+        out.liveSourceRadius.fill(0);
+        /*
+         * Zero, then written under the owning light below. The weights used to be a straight copy of
+         * this set's own two, because the arrays were addressed by live slot; they are addressed by
+         * light now, so a copy would put live slot 1's weight on light 1 — a light that has no live
+         * map at all in most frames.
+         */
+        out.liveWeights.fill(0);
+        for (let liveSlot = 0; liveSlot < LIVE_POINT_SHADOW_MAPS; liveSlot++) {
+            const map = this.maps[liveSlot];
+            const owner = this.owners[liveSlot] ?? -1;
+            let shaderSlot = -1;
+            for (let sampledSlot = 0; sampledSlot < sampledCount; sampledSlot++) {
+                if (sampled[sampledSlot] === owner) {
+                    shaderSlot = shaderSlots[sampledSlot] ?? -1;
+                    break;
+                }
+            }
+            if (map === undefined || shaderSlot < 0 || shaderSlot >= out.liveLayers.length)
+                continue;
+            /*
+             * **A map with no image yet contributes nothing**, which is the guard the static pool
+             * carries in `PointShadowSystem.resolve` and this half was missing. A bake is spread over
+             * frames against a budget, so a live map can be selected before it holds anything — and
+             * what a layer holds before its first bake is a zero depth, which the shader reads as an
+             * occluder pressed against the lamp. The index stays −1, the path the shader already takes
+             * for a light with no map at all.
+             */
+            if (!map.hasBaked)
+                continue;
+            out.liveLayers[shaderSlot] = map.layer;
+            out.liveFar[shaderSlot] = map.far;
+            out.liveNear[shaderSlot] = map.near;
+            out.liveSourceRadius[shaderSlot] = map.sourceRadius;
+            /*
+             * The handover weight *and* the image's own arrival, multiplied.
+             *
+             * They answer different questions and both have to be asked: the weight is how far this
+             * slot is through a crossfade, and the presence is how long its image has existed. A
+             * freshly forgotten map that has just re-baked is at full crossfade weight and no
+             * presence, so without the second factor a whole mover's shadow switches on in one frame
+             * under a lamp that never moved — which is the pop `advance` exists to remove.
+             */
+            out.liveWeights[shaderSlot] = (this.weights[liveSlot] ?? 0) * map.presence;
+        }
+    }
+    /**
+     * Ramp both live images toward full presence.
+     *
+     * **This did not exist, and its absence meant a moving caster was never shadowed by a point
+     * light at all.** `resolve` publishes `crossfade weight * presence`, and presence is the map's
+     * own arrival ramp — which only moves when something advances it. `PointShadowSystem.advance`
+     * walks *its* pool, and these two are not in it, so the ramp stayed at zero for every frame this
+     * engine has ever rendered. The shader multiplied a correct occlusion by a weight of zero.
+     *
+     * Nothing about it was visible from either side. The layer is baked, the layer index and far
+     * plane are published, `hasBaked` is true and the crossfade weight is 1 — every part reports
+     * itself healthy, and the product of them is nothing. It was found by reading the resolved
+     * weights off a live renderer rather than by reading this file, and the octahedral layer had the
+     * caster in it the whole time.
+     *
+     * The pair is advanced whether or not either is owned: an unowned slot has no image, `advance`
+     * on it is the branch that holds the ramp at zero, and skipping it here would be a second place
+     * that has to know which slots are live.
+     */
+    advance(dt) {
+        for (const map of this.maps)
+            map.advance(dt);
+    }
+    /** See `PointShadowSystem.forgetEveryImage`: the storage under these maps was replaced. */
+    forgetEveryImage() {
+        for (const map of this.maps)
+            map.forget();
+    }
+    dispose() {
+        for (const map of this.maps)
+            this.releaseMap(map);
+    }
+    finishTransition() {
+        const fromSlot = this.transitionFromSlot;
+        const toSlot = this.transitionToSlot;
+        if (fromSlot < 0 || toSlot < 0)
+            return;
+        this.owners[fromSlot] = -1;
+        this.weights[fromSlot] = 0;
+        this.weights[toSlot] = 1;
+        this.primarySlot = toSlot;
+        this.clearTransition();
+    }
+    clearTransition() {
+        this.transitionFromSlot = -1;
+        this.transitionToSlot = -1;
+        this.transitionSeconds = 0;
+    }
+}
+function isSampled(worldIndex, sampled, sampledCount) {
+    for (let slot = 0; slot < sampledCount; slot++) {
+        if (sampled[slot] === worldIndex)
+            return true;
+    }
+    return false;
+}

package/dist/render/lod.d.ts

@@ -0,0 +1,35 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Bounds } from '../math/bounds.ts';
+/**
+ * Which level of detail a piece of geometry has earned, from how big it looks.
+ *
+ * **Apparent size and not distance, and the difference is the whole of it.** Thresholds in metres
+ * make a cathedral and a doorknob swap detail at the same range, so either the cathedral drops to
+ * its coarsest form while it still fills the screen or the doorknob keeps its finest while it is
+ * two pixels across. Every world with objects of more than one size hits this, and the usual
+ * repair is a per-object distance scale — which is apparent size, arrived at by hand, one object
+ * at a time.
+ */
+/**
+ * The angular radius of a bounded object, in radians, as seen from a point.
+ *
+ * `radius / distance` rather than `atan(radius / distance)`: the two agree to within a percent
+ * out to about a quarter of a radian, which is far larger than anything a level threshold cares
+ * about, and this is a per-object per-frame path.
+ *
+ * Returns `Infinity` for a viewpoint inside the object's own sphere. That is the honest answer —
+ * it fills the view — and it makes the comparison below pick the finest level without a special
+ * case.
+ */
+export declare function apparentSize(bounds: Bounds, model: ReadonlyMat4, eyeX: number, eyeY: number, eyeZ: number): number;
+/**
+ * The index of the level this object has earned.
+ *
+ * `thresholds` are apparent sizes in descending order — the size at which each level *stops*
+ * being good enough. An object larger than the first threshold gets level 0; one smaller than the
+ * last gets the last level, rather than an index off the end of whatever array the caller is
+ * about to look this up in.
+ *
+ * An empty `thresholds` gives 0, which is the only level a caller with no thresholds has.
+ */
+export declare function lodForBounds(bounds: Bounds, model: ReadonlyMat4, eyeX: number, eyeY: number, eyeZ: number, thresholds: readonly number[]): number;

package/dist/render/lod.js

@@ -0,0 +1,65 @@
+/**
+ * Which level of detail a piece of geometry has earned, from how big it looks.
+ *
+ * **Apparent size and not distance, and the difference is the whole of it.** Thresholds in metres
+ * make a cathedral and a doorknob swap detail at the same range, so either the cathedral drops to
+ * its coarsest form while it still fills the screen or the doorknob keeps its finest while it is
+ * two pixels across. Every world with objects of more than one size hits this, and the usual
+ * repair is a per-object distance scale — which is apparent size, arrived at by hand, one object
+ * at a time.
+ */
+/**
+ * The angular radius of a bounded object, in radians, as seen from a point.
+ *
+ * `radius / distance` rather than `atan(radius / distance)`: the two agree to within a percent
+ * out to about a quarter of a radian, which is far larger than anything a level threshold cares
+ * about, and this is a per-object per-frame path.
+ *
+ * Returns `Infinity` for a viewpoint inside the object's own sphere. That is the honest answer —
+ * it fills the view — and it makes the comparison below pick the finest level without a special
+ * case.
+ */
+export function apparentSize(bounds, model, eyeX, eyeY, eyeZ) {
+    const cx = bounds.centre[0] ?? 0;
+    const cy = bounds.centre[1] ?? 0;
+    const cz = bounds.centre[2] ?? 0;
+    const m0 = model[0] ?? 0;
+    const m1 = model[1] ?? 0;
+    const m2 = model[2] ?? 0;
+    const m4 = model[4] ?? 0;
+    const m5 = model[5] ?? 0;
+    const m6 = model[6] ?? 0;
+    const m8 = model[8] ?? 0;
+    const m9 = model[9] ?? 0;
+    const m10 = model[10] ?? 0;
+    const x = m0 * cx + m4 * cy + m8 * cz + (model[12] ?? 0) - eyeX;
+    const y = m1 * cx + m5 * cy + m9 * cz + (model[13] ?? 0) - eyeY;
+    const z = m2 * cx + m6 * cy + m10 * cz + (model[14] ?? 0) - eyeZ;
+    /* The same largest-axis rule `boundsVisible` uses, and for the same reason. */
+    const sx = Math.sqrt(m0 * m0 + m1 * m1 + m2 * m2);
+    const sy = Math.sqrt(m4 * m4 + m5 * m5 + m6 * m6);
+    const sz = Math.sqrt(m8 * m8 + m9 * m9 + m10 * m10);
+    const radius = bounds.radius * Math.max(sx, sy, sz);
+    const distance = Math.sqrt(x * x + y * y + z * z);
+    if (distance <= radius)
+        return Infinity;
+    return radius / distance;
+}
+/**
+ * The index of the level this object has earned.
+ *
+ * `thresholds` are apparent sizes in descending order — the size at which each level *stops*
+ * being good enough. An object larger than the first threshold gets level 0; one smaller than the
+ * last gets the last level, rather than an index off the end of whatever array the caller is
+ * about to look this up in.
+ *
+ * An empty `thresholds` gives 0, which is the only level a caller with no thresholds has.
+ */
+export function lodForBounds(bounds, model, eyeX, eyeY, eyeZ, thresholds) {
+    const size = apparentSize(bounds, model, eyeX, eyeY, eyeZ);
+    for (let level = 0; level < thresholds.length; level += 1) {
+        if (size >= (thresholds[level] ?? 0))
+            return level;
+    }
+    return Math.max(0, thresholds.length - 1);
+}

package/dist/render/mesh.d.ts

@@ -0,0 +1,177 @@
+/** Static GPU mesh: interleaving is skipped in favor of three tight buffers. */
+import { MorphTexture } from './backend/webgl2/morphTexture.ts';
+import type { Bounds } from '../math/bounds.ts';
+export type { MeshData } from '@driftengine/drft';
+export { validateMeshData } from '@driftengine/drft';
+import type { MeshData } from '@driftengine/drft';
+export declare class Mesh {
+    private readonly vao;
+    private readonly buffers;
+    /**
+     * The position and normal buffers, kept so `update` can rewrite them.
+     *
+     * Null unless the mesh was created `dynamic`. A mesh that never deforms pays nothing for
+     * this — two references, and only where a consumer asked.
+     */
+    private readonly deformable;
+    /** How many floats the position buffer holds, so an update of the wrong size is refused. */
+    private readonly positionFloats;
+    private readonly indexCount;
+    /**
+     * The constant values this mesh's *absent* attributes are shaded with, re-applied on
+     * every draw.
+     *
+     * **`vertexAttrib*f` is context state, not vertex-array state.** `enableVertexAttribArray`
+     * and the pointers belong to the VAO and are restored when it is bound; the constant a
+     * *disabled* attribute reads is global and is not. So setting these once in the
+     * constructor and trusting the VAO to carry them is wrong: it makes a mesh's appearance
+     * depend on which mesh was constructed last, which is a property of unrelated code
+     * somewhere else in the frame.
+     *
+     * It survived because every mesh here happens to want the same constants, so the global
+     * values are correct by coincidence. The first mesh to want a different roughness would
+     * have silently changed the shading of every mesh that never mentioned one — a defect
+     * with no error, no warning and no plausible connection to its cause.
+     *
+     * Re-applying per draw costs four calls on a mesh that omits everything and none on a
+     * mesh that supplies it all, and makes a draw depend on nothing but itself.
+     */
+    private readonly constants;
+    /**
+     * How big this mesh is, in its own space.
+     *
+     * Measured here because the positions are already in hand: the upload walks them anyway, so a
+     * caller gets bounds for nothing and no `MeshData` producer has to supply them. Everything that
+     * wants to know whether this is on screen starts from this object.
+     */
+    readonly bounds: Bounds;
+    /** Whether this mesh carries a rig, which decides which flat program draws it. */
+    readonly isSkinned: boolean;
+    /**
+     * This mesh's morph deltas, or null for geometry that does not deform.
+     *
+     * **Owned by the mesh rather than set per draw**, which is the difference between this and the
+     * joint palette: a palette belongs to a *pose* and changes every frame, where deltas are
+     * geometry and never change. Uploaded once with the vertex buffers; only the weights are
+     * per-draw state.
+     */
+    readonly morph: MorphTexture | null;
+    /**
+     * Whether this mesh carries a tangent frame, for the shader that has to be told.
+     *
+     * The attribute cannot say so itself: `vertexDefaults.ts` supplies `[1, 0, 0, 1]` when it is
+     * absent — a usable frame rather than a sentinel, because a zero tangent normalises to a NaN.
+     * Read off the same branch below that chooses between the buffer and that constant.
+     */
+    readonly hasTangents: boolean;
+    /**
+     * Buffers allocated but not yet filled, in the order the constructor made them.
+     *
+     * Empty except between the steps of an incremental upload; `uploads` drains it and nothing
+     * else touches it. Held as the source arrays rather than as copies, so spreading an upload
+     * costs no memory — the caller's `MeshData` is alive until the last step either way.
+     */
+    private readonly pending;
+    /** Set by the constructor before it allocates anything. See the `spread` parameter. */
+    private readonly spread;
+    /**
+     * Whether all of this mesh's geometry has reached the device.
+     *
+     * False only between the steps of an incremental upload. **`drawMesh` refuses to draw an
+     * incomplete mesh**, and that refusal is the contract: the buffers are allocated and zeroed
+     * from the first frame, so drawing one would be a fan of degenerate triangles through the
+     * origin. Drawing *what has landed* was the other option and is worse — a mesh whose triangle
+     * count grows over several frames is a stranger artefact than a square that is briefly absent.
+     */
+    get complete(): boolean;
+    /**
+     * @param spread Allocate the buffers now and fill them from `uploads` later. Off by default,
+     * and the default is the fast path: filling a buffer with `bufferData` in one call skips the
+     * zero-fill that `bufferData(size)` then `bufferSubData` pays for, and every mesh in the
+     * engine that does not need to be spread should keep skipping it.
+     */
+    constructor(gl: WebGL2RenderingContext, data: MeshData, dynamic?: boolean, spread?: boolean);
+    /** Caller is responsible for having the flat program + uniforms bound. */
+    draw(gl: WebGL2RenderingContext): void;
+    /**
+     * Bind one buffer's per-instance attributes to this mesh's vertex array.
+     *
+     * **One batch per mesh, and the vertex array is why.** A `Mesh` owns exactly one, so a second
+     * batch would rebind locations 11 to 15 on the array the first still draws through — and what
+     * comes out is one batch's instances placed by the other's matrices, which reads as a transform
+     * bug in the consumer's own code rather than as a misuse of this.
+     *
+     * **What would make it wrong** is a consumer legitimately wanting two batches of one mesh,
+     * which wants a vertex array per batch rather than a flag here.
+     */
+    attachInstances(gl: WebGL2RenderingContext, buffer: WebGLBuffer, stride: number): void;
+    /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
+    private instanced;
+    /**
+     * Draw `count` instances through the attributes `attachInstances` bound.
+     *
+     * The constants are re-applied exactly as `draw` does — a vertex array restores the arrays and
+     * not the constant attributes, and an absent optional attribute is a constant here.
+     */
+    drawInstances(gl: WebGL2RenderingContext, count: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    /**
+     * Rewrite this mesh's positions, and its normals where the caller has them.
+     *
+     * **Only the two attributes that move.** Colour, emissive and the rest describe what a surface
+     * *is* and do not change because it bent; rewriting them would be uploading unchanged bytes
+     * every frame. A caller with genuinely changing colour wants a second mesh or a tint.
+     *
+     * **The bounds are recomputed**, because everything that decides whether this is on screen
+     * starts from them — a cloth that blew sideways out of its original box would be culled while
+     * still visible, which is the kind of bug that only shows up at the edge of the frame.
+     */
+    update(gl: WebGL2RenderingContext, positions: Float32Array, normals?: Float32Array): void;
+    private attachAttribute;
+    /**
+     * Give a bound buffer its storage, and its contents now or later.
+     *
+     * The one place the two paths differ, and they differ in exactly one call: eagerly, the data
+     * goes in with the allocation; spread, the allocation is sized and the array is queued. Both
+     * hand the same bytes to the same buffer, which is what keeps a mesh that lands over six
+     * frames identical to one that lands in a single call.
+     */
+    private allocate;
+    /**
+     * Fill the buffers, a bounded step at a time. Done when it returns `done`.
+     *
+     * A step is one attribute, or a slice of one where the attribute is bigger than
+     * `UPLOAD_BYTES_PER_STEP`. **There is still no interleave here** — this backend's three tight
+     * buffers are the reason a consumer measured the same drive as smooth on WebGL2 and hitching
+     * on the other one, and dividing an upload is not a reason to give that up.
+     *
+     * The call that returns `done` is the one that does the last step's work, so a mesh of *n*
+     * chunks takes exactly *n* calls.
+     *
+     * The vertex array object is bound around each step because one of these writes an index
+     * buffer, and an `ELEMENT_ARRAY_BUFFER` binding belongs to whichever array object is current —
+     * writing it with somebody else's bound would quietly repoint their indices at this mesh.
+     */
+    uploads(gl: WebGL2RenderingContext): Generator<void, void, void>;
+}
+/** A mesh on its way to the device, and the iterator that gets it there. */
+export interface IncrementalMesh {
+    /**
+     * Usable at once — it can be held, measured and disposed — but not drawable until the upload
+     * finishes. See `Mesh.complete`.
+     */
+    readonly mesh: Mesh;
+    /** Advance the upload by one bounded step. Done when it returns `done`. */
+    readonly upload: Iterator<void, void>;
+}
+/**
+ * Upload a mesh over as many frames as the caller gives it.
+ *
+ * The twin of `createGpuMeshIncremental` on the other backend, and the cheaper of the two: there
+ * is no interleave to divide here, so a step is an attribute or a slice of one.
+ *
+ * What is paid at creation and not spread: validation, the bounds, the vertex array object and
+ * the allocations. The bounds are the deliberate one — a streamer places and culls a region from
+ * them before a byte of it has landed.
+ */
+export declare function createMeshIncremental(gl: WebGL2RenderingContext, data: MeshData, dynamic?: boolean): IncrementalMesh;