@driftengine/core 3.61.0

package/dist/render/mesh.js

@@ -0,0 +1,466 @@
+/** Static GPU mesh: interleaving is skipped in favor of three tight buffers. */
+import { MorphTexture } from './backend/webgl2/morphTexture.js';
+import { ABSENT_ATTRIBUTE } from './vertexDefaults.js';
+import { UPLOAD_BYTES_PER_STEP } from './uploadStep.js';
+/*
+ * `MeshData` and its validator live in `@driftengine/drft`, because the container's whole
+ * job is to carry one and the format package must be readable by something that never
+ * draws. Re-exported here so every consumer that took them from the renderer still can.
+ */
+import { boundsOfPositions, createBounds } from '../math/bounds.js';
+export { validateMeshData } from '@driftengine/drft';
+import { validateMeshData } from '@driftengine/drft';
+/**
+ * The roughness a mesh that never mentions one is shaded with.
+ *
+ * Solved rather than picked: it is the roughness whose normalised lobe has the same
+ * half-power width — 6.88 degrees — as the fixed `pow(ndh, 96)` this engine used before
+ * roughness existed. A world built before the attribute therefore keeps the highlight it
+ * was authored against, in width as well as in strength.
+ *
+ * It was 0.28, which claimed to do that and did not: 0.28 is 2.9 degrees, less than half
+ * as wide, and against the un-normalised lobe of the time it peaked 52 times higher as
+ * well. Both halves are fixed — `flat.ts` normalises the lobe, and this is the width that
+ * actually matches.
+ */
+/* The engine's fixed lobe, stated once in `vertexDefaults.ts` so both backends read one number. */
+const DEFAULT_ROUGHNESS = ABSENT_ATTRIBUTE['roughness']?.[0] ?? 0.4277;
+/** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
+const ATTR_POSITION = 0;
+const ATTR_NORMAL = 1;
+const ATTR_COLOR = 2;
+const ATTR_EMISSIVE = 3;
+const ATTR_SPECULAR = 4;
+const ATTR_UV = 5;
+const ATTR_EMISSIVE_COLOR = 6;
+const ATTR_ROUGHNESS = 7;
+const ATTR_GRAIN = 8;
+const ATTR_RELIEF = 9;
+/** Four components, which makes it the widest attribute the layout carries. See `generateTangents`. */
+const ATTR_TANGENT = 10;
+/* Skinning. Thirteen of WebGL2's guaranteed sixteen attributes are spoken for with these two. */
+const ATTR_JOINTS = 11;
+/*
+ * The four-lane per-vertex channel, and the fourteenth attribute.
+ *
+ * **13 is the last location the plain and skinned variants can both spare.** Skinning holds 11 and
+ * 12; an instanced draw holds 11 through 15 and therefore cannot carry this at all, which is why
+ * `flatVert` throws on the pair rather than dropping the attribute. A silent drop is a consumer
+ * setting sway, watching nothing move, and having nothing to read about why.
+ */
+const ATTR_CHANNEL = 13;
+const ATTR_WEIGHTS = 12;
+/**
+ * One absent attribute's constant, at the width the table gave it.
+ *
+ * **The four-component arm is the one that was missing**, and it was missing in both draw paths
+ * because they held a copy of this each. `vertexAttrib3f` leaves `w` at its default of **1**, so a
+ * four-float entry in `ABSENT_ATTRIBUTE` reached the driver with its last lane overwritten:
+ * `channel`'s `(0, 1, 1, 0)` arrived as `(0, 1, 1, 1)`. Nothing showed it — that lane is the
+ * reserved one and nothing reads it, and `tangents`' `(1, 0, 0, 1)` happens to want the default —
+ * but `joints` and `weights` are four-wide too, and the table is meant to be the one place an
+ * absent attribute's meaning is written down. A table nothing applies faithfully is not a source
+ * of truth. `vertexDefaults.test.ts` pins the tuples; this is what pins that they arrive.
+ */
+function applyConstant(gl, location, value) {
+    const [x = 0, y = 0, z = 0, w = 0] = value;
+    if (value.length === 1)
+        gl.vertexAttrib1f(location, x);
+    else if (value.length === 2)
+        gl.vertexAttrib2f(location, x, y);
+    else if (value.length === 3)
+        gl.vertexAttrib3f(location, x, y, z);
+    else
+        gl.vertexAttrib4f(location, x, y, z, w);
+}
+export class Mesh {
+    vao;
+    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.
+     */
+    deformable = null;
+    /** How many floats the position buffer holds, so an update of the wrong size is refused. */
+    positionFloats;
+    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.
+     */
+    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.
+     */
+    bounds = createBounds();
+    /** Whether this mesh carries a rig, which decides which flat program draws it. */
+    isSkinned;
+    /**
+     * 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.
+     */
+    morph;
+    /**
+     * 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.
+     */
+    hasTangents;
+    /**
+     * 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.
+     */
+    pending = [];
+    /** Set by the constructor before it allocates anything. See the `spread` parameter. */
+    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() {
+        return this.pending.length === 0;
+    }
+    /**
+     * @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, data, dynamic = false, spread = false) {
+        validateMeshData(data);
+        this.spread = spread;
+        boundsOfPositions(data.positions, this.bounds);
+        this.positionFloats = data.positions.length;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('createVertexArray failed');
+        this.vao = vao;
+        this.indexCount = data.indices.length;
+        gl.bindVertexArray(vao);
+        /*
+         * `DYNAMIC_DRAW` where a consumer said the geometry moves, and only there. The hint is
+         * advisory — a `STATIC_DRAW` buffer accepts `bufferSubData` perfectly well — but a driver
+         * that has been told the truth can place the buffer where a rewrite is cheap, and a driver
+         * that has been told a lie every frame is the shape of a stall nobody can find.
+         */
+        const usage = dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW;
+        const positions = this.attachAttribute(gl, ATTR_POSITION, data.positions, 3, usage);
+        const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage);
+        if (dynamic)
+            this.deformable = { positions, normals };
+        this.attachAttribute(gl, ATTR_COLOR, data.colors, 3);
+        this.attachAttribute(gl, ATTR_EMISSIVE, data.emissive, 1);
+        /*
+         * Absent means "not shiny", supplied as a constant rather than as a buffer of
+         * zeroes. `vertexAttrib1f` sets the value a *disabled* attribute reads, so this
+         * costs no buffer, no upload and no per-vertex fetch — which is what lets the
+         * seventeen other places that build a mesh stay exactly as they are.
+         */
+        if (data.specular === undefined) {
+            gl.disableVertexAttribArray(ATTR_SPECULAR);
+            this.constants.push({ location: ATTR_SPECULAR, value: ABSENT_ATTRIBUTE['specular'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_SPECULAR, data.specular, 1);
+        }
+        /* Absent means "no surface texture", by the same constant-attribute trick. */
+        if (data.uvs === undefined) {
+            gl.disableVertexAttribArray(ATTR_UV);
+            this.constants.push({ location: ATTR_UV, value: ABSENT_ATTRIBUTE['uvs'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_UV, data.uvs, 2);
+        }
+        /* Absent means "inherit albedo", supplied as the constant the shader tests for. */
+        if (data.emissiveColor === undefined) {
+            gl.disableVertexAttribArray(ATTR_EMISSIVE_COLOR);
+            this.constants.push({
+                location: ATTR_EMISSIVE_COLOR,
+                value: ABSENT_ATTRIBUTE['emissiveColor'],
+            });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_EMISSIVE_COLOR, data.emissiveColor, 3);
+        }
+        /* Absent means the engine's long-standing fixed lobe. See `roughness`. */
+        if (data.roughness === undefined) {
+            gl.disableVertexAttribArray(ATTR_ROUGHNESS);
+            this.constants.push({ location: ATTR_ROUGHNESS, value: ABSENT_ATTRIBUTE['roughness'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_ROUGHNESS, data.roughness, 1);
+        }
+        /*
+         * Absent means no grain at all, and that is the whole point of the attribute rather
+         * than a default chosen for convenience: a surface that never says it is mineral is
+         * not mineral. The two previous versions inferred it, and both inferences were wrong.
+         */
+        if (data.relief === undefined) {
+            gl.disableVertexAttribArray(ATTR_RELIEF);
+            this.constants.push({ location: ATTR_RELIEF, value: ABSENT_ATTRIBUTE['relief'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_RELIEF, data.relief, 1);
+        }
+        /*
+         * Both or neither — `validateMeshData` refuses one without the other, so a mesh reaching here
+         * with joints has weights. `isSkinned` is what decides which of the two flat programs a draw
+         * takes; see `WebGL2Renderer.drawMesh`.
+         */
+        this.isSkinned = data.joints !== undefined;
+        this.morph =
+            data.morphTargets === undefined || data.morphTargetCount === undefined
+                ? null
+                : new MorphTexture(gl, data.morphTargets, data.positions.length / 3, data.morphTargetCount);
+        if (data.joints === undefined || data.weights === undefined) {
+            this.constants.push({ location: ATTR_JOINTS, value: ABSENT_ATTRIBUTE['joints'] });
+            this.constants.push({ location: ATTR_WEIGHTS, value: ABSENT_ATTRIBUTE['weights'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_JOINTS, data.joints, 4);
+            this.attachAttribute(gl, ATTR_WEIGHTS, data.weights, 4);
+        }
+        this.hasTangents = data.tangents !== undefined;
+        if (data.tangents === undefined) {
+            gl.disableVertexAttribArray(ATTR_TANGENT);
+            this.constants.push({ location: ATTR_TANGENT, value: ABSENT_ATTRIBUTE['tangents'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_TANGENT, data.tangents, 4);
+        }
+        if (data.grain === undefined) {
+            gl.disableVertexAttribArray(ATTR_GRAIN);
+            this.constants.push({ location: ATTR_GRAIN, value: ABSENT_ATTRIBUTE['grain'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_GRAIN, data.grain, 1);
+        }
+        /*
+         * Absent means planted, fully sunlit and opaque, by the same constant-attribute trick every
+         * optional attribute above uses — no buffer, no upload, no per-vertex fetch. That is what
+         * lets a mesh which never heard of this attribute cost exactly what it cost before, and it
+         * is the property that ruled out folding the loose material floats into vec4s to buy the
+         * location this spends.
+         */
+        if (data.channel === undefined) {
+            gl.disableVertexAttribArray(ATTR_CHANNEL);
+            this.constants.push({ location: ATTR_CHANNEL, value: ABSENT_ATTRIBUTE['channel'] });
+        }
+        else {
+            this.attachAttribute(gl, ATTR_CHANNEL, data.channel, 4);
+        }
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error('createBuffer failed');
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, data.indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /** Caller is responsible for having the flat program + uniforms bound. */
+    draw(gl) {
+        gl.bindVertexArray(this.vao);
+        // The VAO restores the arrays; these it cannot. See `constants`.
+        for (const constant of this.constants) {
+            const value = constant.value;
+            applyConstant(gl, constant.location, value);
+        }
+        gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0);
+    }
+    /**
+     * 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, buffer, stride) {
+        if (this.instanced) {
+            throw new Error('Mesh: this mesh already has an instanced batch — a Mesh owns one vertex array, so a ' +
+                'second batch would rebind the attributes the first draws through.');
+        }
+        this.instanced = true;
+        gl.bindVertexArray(this.vao);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        /* Four vec4 columns then a vec3 tint: a mat4 is not a vertex attribute in GLSL ES 300. */
+        for (let column = 0; column < 4; column += 1) {
+            const location = 11 + column;
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, 4, gl.FLOAT, false, stride, column * 16);
+            gl.vertexAttribDivisor(location, 1);
+        }
+        gl.enableVertexAttribArray(15);
+        gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
+        gl.vertexAttribDivisor(15, 1);
+        gl.bindVertexArray(null);
+    }
+    /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
+    instanced = false;
+    /**
+     * 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, count) {
+        gl.bindVertexArray(this.vao);
+        for (const constant of this.constants) {
+            const value = constant.value;
+            applyConstant(gl, constant.location, value);
+        }
+        gl.drawElementsInstanced(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0, count);
+    }
+    dispose(gl) {
+        this.morph?.dispose(gl);
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+    }
+    /**
+     * 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, positions, normals) {
+        if (this.deformable === null) {
+            throw new Error('this mesh was not created with { dynamic: true }, so its buffers are not set up to be ' +
+                'rewritten. Say so at `createMesh` — the flag is what decides the buffer hint and ' +
+                'what is kept to make an update possible.');
+        }
+        if (positions.length !== this.positionFloats) {
+            throw new Error(`this mesh has ${this.positionFloats / 3} vertices and the update has ` +
+                `${positions.length / 3}. A mesh's vertex count is fixed at creation: the index buffer, ` +
+                'the pipeline and every other attribute are sized against it.');
+        }
+        boundsOfPositions(positions, this.bounds);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.deformable.positions);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, positions);
+        if (normals !== undefined) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.deformable.normals);
+            gl.bufferSubData(gl.ARRAY_BUFFER, 0, normals);
+        }
+    }
+    attachAttribute(gl, location, data, size, usage = gl.STATIC_DRAW) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error('createBuffer failed');
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        this.allocate(gl, gl.ARRAY_BUFFER, buffer, data, usage);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        return buffer;
+    }
+    /**
+     * 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.
+     */
+    allocate(gl, target, buffer, data, usage) {
+        if (!this.spread) {
+            gl.bufferData(target, data, usage);
+            return;
+        }
+        gl.bufferData(target, data.byteLength, usage);
+        this.pending.push({ target, buffer, data });
+    }
+    /**
+     * 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) {
+        const chunks = [];
+        for (const one of this.pending) {
+            const width = one.data.BYTES_PER_ELEMENT ?? 1;
+            const length = one.data.byteLength / width;
+            const per = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / width));
+            for (let from = 0; from < length; from += per) {
+                chunks.push({ ...one, from, to: Math.min(from + per, length) });
+            }
+        }
+        for (let at = 0; at < chunks.length; at++) {
+            const chunk = chunks[at];
+            const width = chunk.data.BYTES_PER_ELEMENT ?? 1;
+            gl.bindVertexArray(this.vao);
+            gl.bindBuffer(chunk.target, chunk.buffer);
+            gl.bufferSubData(chunk.target, chunk.from * width, chunk.data, chunk.from, chunk.to - chunk.from);
+            gl.bindVertexArray(null);
+            if (at < chunks.length - 1)
+                yield;
+        }
+        this.pending.length = 0;
+    }
+}
+/**
+ * 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 function createMeshIncremental(gl, data, dynamic = false) {
+    const mesh = new Mesh(gl, data, dynamic, true);
+    return { mesh, upload: mesh.uploads(gl) };
+}

package/dist/render/occlusion.d.ts

@@ -0,0 +1,81 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Bounds } from '../math/bounds.ts';
+export interface OcclusionOptions {
+    /** Texels across. The height follows the aspect. */
+    readonly width: number;
+    readonly height: number;
+}
+export declare class OcclusionBuffer {
+    /**
+     * The pyramid, level 0 first, each level a quarter of the one before.
+     *
+     * One allocation per level rather than one buffer with offsets, because the test indexes a level
+     * by its own width and an offset table would be a second thing to keep in step.
+     */
+    private levels;
+    private widths;
+    private heights;
+    private built;
+    private occluders;
+    /** The view-projection this frame's occluders were rasterised through. */
+    private readonly viewProj;
+    constructor(options: OcclusionOptions);
+    get width(): number;
+    get height(): number;
+    /** How many occluders were declared this frame. Zero means every test answers "draw it". */
+    get declared(): number;
+    /**
+     * Rebuild the pyramid for a new size. Called when the drawing buffer's aspect changes.
+     *
+     * Levels stop at 1x1: the coarsest level is one texel covering the whole frame, which is what a
+     * rectangle spanning the screen is tested against.
+     */
+    resize(options: OcclusionOptions): void;
+    /** Start a frame: clear to the far plane and take the matrix everything will be projected by. */
+    begin(viewProj: ReadonlyMat4): void;
+    /**
+     * Declare one occluder: a box in local space, placed by a model matrix.
+     *
+     * **A box rather than the mesh**, which is the same bargain a bounding sphere makes for the
+     * frustum: an occluder that is smaller than the thing it stands for is conservative, and a
+     * consumer knows the box that fits inside its wall. *What would make it wrong* is a consumer
+     * handing the mesh's own bounds for a shape with a hole in it, which would occlude through the
+     * hole — so the parameter is the box you may safely be hidden by, not the box you occupy.
+     */
+    addOccluder(min: ReadonlyArray<number> | Float32Array, max: ReadonlyArray<number> | Float32Array, model: ReadonlyMat4): void;
+    /**
+     * Whether a bounding sphere is entirely behind the declared occluders.
+     *
+     * **False whenever anything is uncertain**, which is every case the arithmetic cannot settle: no
+     * occluders, a sphere crossing the near plane, a rectangle off the side of the frame. Drawing
+     * something hidden costs a draw call; culling something visible is a hole.
+     */
+    occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * A world point into buffer coordinates and depth, written into `CORNERS` at `slot`.
+     *
+     * Returns false for a point at or behind the eye, where the perspective divide has no meaning —
+     * and a false anywhere abandons the whole shape, occluder or occludee, because a partial
+     * projection is exactly the kind of half-answer that produces a hole.
+     */
+    private project;
+    /**
+     * One triangle of an occluder's back face into level 0, keeping the nearest depth per texel.
+     *
+     * A half-space rasteriser over the triangle's own bounding box, sampling at texel centres. Depth
+     * is interpolated in screen space rather than perspective-correct — which for a *bound* is the
+     * safe direction only if it never under-estimates, so the depth written is the plane's value at
+     * the texel centre plus half a texel of gradient each way. A bound that is too far occludes less.
+     */
+    private triangle;
+    /**
+     * Erode by one texel, then reduce by maximum into every coarser level.
+     *
+     * **The erosion is what makes the whole thing conservative** and it costs one pass: a triangle
+     * sampled at texel centres covers up to half a texel too much at every silhouette, so any texel
+     * next to an unwritten one gives its bound back. The reduction is a maximum because the test asks
+     * "is every texel under this rectangle already covered by something nearer", and a maximum over
+     * children answers that for the parent.
+     */
+    private buildPyramid;
+}