@expofp/renderer 3.2.5 → 3.27.0

package/dist/core/text/BatchedText.js

@@ -0,0 +1,467 @@
+import { extend } from '@react-three/fiber';
+import { Box3, Sphere, } from 'three';
+import { BatchedText as TroikaBatchedText, Text as TroikaText, } from 'troika-three-text';
+import { InstanceUniforms } from '../InstanceUniforms';
+import { configureDerivedMaterial, patchBaseMaterial, readsMemberMatrices, } from './batched-text-material';
+import { packGlyphs } from './glyph-packing';
+import { MemberTexture } from './MemberTexture';
+/**
+ * troika's `BatchedText` with stable member ids, explicit paint order, and per-instance uniforms.
+ *
+ * Upstream keys everything by pack order — a counter assigned while packing the glyph attributes —
+ * which shifts on every add, remove and reorder, so no id survives a repack and nothing outside the
+ * class can address a member. This class separates the two things that counter conflated:
+ *
+ * - **The id** is a stable, batch-allocated index (free list, high-water mark). It is the row a
+ *   member occupies in the matrix texture and in the uniforms texture, and it is what
+ *   {@link addText} hands back so a caller can address the member later.
+ * - **Paint order** is the order ids are iterated while packing, since draw order is simply the
+ *   order glyph runs appear in the batched attributes. {@link setOrder} sets it.
+ *
+ * Those are independent — the id is the *value* written into `aTroikaTextBatchMemberIndex`, the
+ * order is *where* it is written — which is what lets a batch have both numbered uniforms and a 2D
+ * painter's draw order without an indirect-index texture. The cost is that a pure reorder still
+ * repacks (rewriting the glyph attributes), where a `BatchedMesh` would only re-sort its draw list.
+ *
+ * Other departures from upstream:
+ *
+ * - **Sync is flag-driven, not scanned.** Members report property writes through
+ *   `TextExt._batchParent`, so an idle frame costs nothing instead of walking every member.
+ * - **Per-member frustum culling and visibility**, by zeroing a hidden member's matrix so its glyphs
+ *   collapse to a degenerate triangle. See {@link MemberTexture}.
+ * - **Bounds are cached**, recomputed only when {@link invalidateBounds} says they moved, where
+ *   upstream recomposed every member's matrix on every frame. The recompose itself stays in
+ *   {@link updateBounds}, so a caller cannot forget it; what changed is that every mutation which
+ *   moves a member now reports back, rather than the flag being set by accident.
+ * - **The derived material inherits the base's `transparent`**, rather than troika forcing it true.
+ *   See {@link configureDerivedMaterial}.
+ *
+ * **Not built on {@link InstancedMeshExt}'s machinery**, despite the family resemblance. That mesh
+ * draws one shared geometry through a per-frame list of instance ids, so it culls and sorts by
+ * rewriting the list; here draw order *is* the order glyph runs sit in the attributes, so a reorder
+ * costs a repack and culling collapses a matrix row instead. Its members are real objects carrying
+ * bounds and a layout of their own rather than indices into one geometry, its ids are allocated
+ * per member rather than in bulk by count, and visibility rides on the member's own `visible`. What
+ * the two genuinely share is {@link InstanceUniforms}.
+ *
+ * Members must be {@link TextExt}, and are assumed to agree on `orientation` and `sdfGlyphSize`:
+ * both feed uniforms that are batch-wide rather than per-member, so mixing them across a batch
+ * leaves whichever member was written last in charge.
+ *
+ * Render it with {@link BatchedText}.
+ */
+export class BatchedTextExt extends TroikaBatchedText {
+    /** Per-instance uniform store, shared with {@link BatchedMeshExt} and {@link InstancedMeshExt}. */
+    uniforms = new InstanceUniforms();
+    /** The per-member transform and style rows the batch's shader draws from. */
+    memberTexture = new MemberTexture();
+    /** Member ids in paint order; the iteration order for packing, and therefore the draw order. */
+    ordered = [];
+    /** Id to member, with holes for released ids. Indexed by id, so it needs no map lookup. */
+    textById = [];
+    /** Released ids, reused before the high-water mark grows. */
+    freeIds = [];
+    _addedMembersCount = 0;
+    boundsNeedsUpdate = false;
+    batchNeedsSync = true;
+    /**
+     * Whether {@link dispose} has run. Syncing a member is asynchronous — troika fetches and parses
+     * the font — so a batch can be torn down with a repack still pending against it.
+     */
+    disposed = false;
+    constructor() {
+        super();
+        this.addEventListener('synccomplete', () => {
+            this.boundsNeedsUpdate = true;
+        });
+    }
+    /** Number of members in the batch. */
+    get size() {
+        return this._members.size;
+    }
+    /**
+     * One past the highest id ever handed out — the row count both textures are sized to, and the
+     * bound every per-member sweep iterates to. Larger than {@link size} whenever a removal left a
+     * hole.
+     *
+     * **A pure high-water mark: removing a member never pulls it back in**, unlike `Instances`, the
+     * equivalent for {@link InstancedMeshExt}, which shrinks past trailing dead ids. Converting either
+     * to the other buys nothing. A dead row costs the sweeps here one array read and a `continue`; and
+     * this same number also sizes both textures, where `Instances` has a separate `capacity` for that
+     * — so shrinking it would reallocate the matrix and uniform textures every time the last member
+     * left, to save those reads.
+     */
+    get addedMembersCount() {
+        return this._addedMembersCount;
+    }
+    /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
+    patchedMaterial = null;
+    /** Marks the batch as needing a sync pass. Members call this through `TextExt._batchParent`. */
+    requestSync() {
+        this.batchNeedsSync = true;
+    }
+    /**
+     * Marks the batch's bounds as stale. Members call this through `TextExt._batchParent` whenever
+     * their transform changes, so no caller has to remember to.
+     */
+    invalidateBounds() {
+        this.boundsNeedsUpdate = true;
+    }
+    /**
+     * The member holding an id.
+     * @param memberId - The member to read.
+     * @returns The member, or `undefined` when the id holds none.
+     */
+    getText(memberId) {
+        return this.textById[memberId];
+    }
+    /**
+     * Shows or hides a member. A hidden member keeps its id and its glyphs; it is collapsed at draw
+     * time rather than repacked out, so hiding costs no repack.
+     *
+     * Invalidates the bounds, because they enclose only the visible members — without this, hiding
+     * one would leave the batch's sphere too large and showing one would leave it too small, either
+     * way mis-culling the whole batch.
+     * @param memberId - The member to show or hide.
+     * @param visible - Whether it draws.
+     */
+    setVisibleAt(memberId, visible) {
+        const text = this.textById[memberId];
+        if (!text || text.visible === visible)
+            return;
+        text.visible = visible;
+        this.invalidateBounds();
+    }
+    /**
+     * Sets the order members draw in — the order their glyph runs are packed into the batched
+     * attributes, which is the only thing that resolves overlap between texts: 2D content never writes
+     * depth, so depth testing has nothing of its own to compare against.
+     *
+     * Resolved to ids as it is copied, rather than retained as members: the caller's array is
+     * usually its own live membership list, and the repack wants the row each run belongs to anyway.
+     * @param texts - Every member, in paint order. Members missing from it are not drawn, and anything
+     *   that is not a member is dropped.
+     */
+    setOrder(texts) {
+        this.ordered = [];
+        for (const text of texts) {
+            const memberId = this._members.get(text)?.index;
+            if (memberId !== undefined)
+                this.ordered.push(memberId);
+        }
+        this._needsRepack = true;
+        this.batchNeedsSync = true;
+        this.boundsNeedsUpdate = true;
+    }
+    /**
+     * Declares per-instance uniforms, merging with any already declared and rebuilding the backing
+     * texture (existing values carried across). See {@link InstanceUniforms.add}.
+     * @param schema - The uniforms to add.
+     */
+    addUniforms(schema) {
+        this.uniforms.add(schema, Math.max(1, this._addedMembersCount));
+        // The generated GLSL changed shape, so whatever was compiled against the old layout is stale.
+        this.materialsNeedUpdate();
+    }
+    /**
+     * Reads one member's uniform.
+     * @param memberId - The member to address.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    getUniformAt(memberId, name, target) {
+        return this.uniforms.get(memberId, name, target);
+    }
+    /**
+     * Writes one member's uniform and marks its row for upload.
+     * @param memberId - The member to address.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    setUniformAt(memberId, name, value) {
+        this.uniforms.set(memberId, name, value);
+    }
+    /**
+     * Adds a member, allocating it an id.
+     * @param text - The text to batch.
+     * @returns The member’s id — stable for as long as it stays in the batch, and the index every
+     *   other method here takes.
+     */
+    addText(text) {
+        const existing = this._members.get(text);
+        if (existing)
+            return existing.index;
+        const memberId = this.freeIds.pop() ?? this._addedMembersCount++;
+        super.addText(text);
+        // Upstream leaves this at -1 until a repack assigns pack order; here it is the stable id, set
+        // once, and the repack only reads it.
+        this._members.get(text).index = memberId;
+        text._batchParent = this;
+        this.textById[memberId] = text;
+        this.ordered.push(memberId);
+        // Both textures are sized by the high-water mark; the matrix texture resizes itself inside
+        // `MemberTexture`, the uniforms texture has to be told.
+        this.uniforms.resize(this._addedMembersCount);
+        this.batchNeedsSync = true;
+        this.boundsNeedsUpdate = true;
+        return memberId;
+    }
+    removeText(text) {
+        const info = this._members.get(text);
+        // Detaches the `synccomplete` listener, deletes the member, and sets `_needsRepack`.
+        super.removeText(text);
+        if (!info)
+            return;
+        this.textById[info.index] = undefined;
+        this.freeIds.push(info.index);
+        if (text._batchParent === this)
+            text._batchParent = undefined;
+        const position = this.ordered.indexOf(info.index);
+        if (position >= 0)
+            this.ordered.splice(position, 1);
+        this.batchNeedsSync = true;
+        this.boundsNeedsUpdate = true;
+    }
+    /**
+     * Copies the text-level properties, and deliberately not the membership.
+     *
+     * Upstream hands the *source's own* members to the copy. Members are owned rather than shared —
+     * {@link addText} points `_batchParent` at the batch they join — so that step silently cuts the
+     * source off from its own members: nothing they report afterwards reaches the batch still drawing
+     * them. Cloning the members instead would be correct but costs a font fetch and a layout per
+     * member, so a copy starts empty and a caller that wants members adds its own.
+     *
+     * Not hypothetical: three.js devtools clones the object it highlights.
+     * @param source - The batch to copy from.
+     * @returns This batch.
+     */
+    copy(source) {
+        // `Text`'s copy, reached past `BatchedText`'s — the membership hand-off is the only thing the
+        // override adds, and there is no flag to skip just that.
+        TroikaText.prototype.copy.call(this, source);
+        return this;
+    }
+    dispose() {
+        // Set before anything else: a sync started earlier may still be waiting on a font, and its
+        // repack must not run against the geometry this is about to release.
+        this.disposed = true;
+        // Disposes the geometry. The matrix textures are ours, not the empty record troika looks in.
+        super.dispose();
+        // Upstream leaves every member holding a listener on the disposed batch, and every member of
+        // ours holding a `_batchParent` back-reference; both keep the batch alive.
+        for (const text of this.textById) {
+            if (!text)
+                continue;
+            super.removeText(text);
+            if (text._batchParent === this)
+                text._batchParent = undefined;
+        }
+        this.memberTexture.dispose();
+        this.uniforms.dispose();
+        this.ordered.length = 0;
+        this.textById.length = 0;
+        this.freeIds.length = 0;
+        this._addedMembersCount = 0;
+        this.dispatchEvent(disposeEvent);
+    }
+    /**
+     * Refreshes every member's local matrix and recomputes the batch's bounds from them.
+     *
+     * Inherited `updateMatrixWorld` calls this once per frame, so the flag is what keeps it cheap:
+     * upstream recomposed every member's matrix on every frame whether anything moved or not.
+     *
+     * Members are not in the scene graph, so this pass is the only thing that maintains their
+     * matrices — which is why the recompose sits ahead of the visibility check rather than inside it.
+     * A member hidden now may be shown later in the same frame, after this pass has run, and the
+     * per-draw texture fill would otherwise draw it at wherever it last stood.
+     */
+    updateBounds() {
+        if (!this.boundsNeedsUpdate)
+            return;
+        const bbox = this.geometry.boundingBox.makeEmpty();
+        for (const memberId of this.ordered) {
+            const text = this.textById[memberId];
+            if (!text)
+                continue;
+            if (text.matrixAutoUpdate)
+                text.updateMatrix(); // ignore world matrix
+            if (!text.visible)
+                continue;
+            _box.copy(text.geometry.boundingBox).applyMatrix4(text.matrix);
+            bbox.union(_box);
+        }
+        bbox.getBoundingSphere(this.geometry.boundingSphere);
+        // Cleared last, not first: `updateMatrix` above reports back through `invalidateBounds`, so
+        // clearing up front would let this pass re-dirty itself and recompute forever.
+        this.boundsNeedsUpdate = false;
+    }
+    raycast(raycaster, intersects) {
+        // Inherited, `Text.raycast` tests a *single* block's bounds — and for a batch the block it reads
+        // is whichever member synced last, at the batch's own transform, so upstream reports one phantom
+        // rectangle and never names a member. Here each member is tested against its own bounds instead,
+        // and the hits carry the member’s id so a caller can trace one back to what it drew.
+        //
+        // Picking is block-shaped, not glyph-shaped: a hit anywhere in a line's box counts, gaps between
+        // letters included. That matches how a label reads as one target.
+        this.updateBounds();
+        // Whole-batch early-out over the visible members' bounds, so a layer nowhere near the pointer
+        // costs one sphere test. Skipped while the bounds are degenerate — before the first sync, or
+        // with every member hidden — where an empty box yields no usable sphere.
+        const bounds = this.geometry.boundingSphere;
+        if (bounds && Number.isFinite(bounds.radius) && bounds.radius > 0) {
+            _sphere.copy(bounds).applyMatrix4(this.matrixWorld);
+            if (!raycaster.ray.intersectsSphere(_sphere))
+                return;
+        }
+        for (let memberId = 0; memberId < this._addedMembersCount; memberId++) {
+            const text = this.textById[memberId];
+            // An unsynced member has no bounds to test: troika lays text out asynchronously, and until it
+            // finishes the member draws nothing either.
+            if (!text?.visible || !text.textRenderInfo)
+                continue;
+            // Members are not in the scene graph, so nothing maintains their world matrices — `updateBounds`
+            // keeps only the local ones. Composing it here is what lets troika's own block test run
+            // unchanged, and it is the same matrix the shader places the member with.
+            if (text.matrixAutoUpdate)
+                text.updateMatrix();
+            text.matrixWorld.multiplyMatrices(this.matrixWorld, text.matrix);
+            const before = intersects.length;
+            text.raycast(raycaster, intersects);
+            // The member named itself as the hit object; relabel the tail it just appended so hits point at
+            // the batch and name the member, which is the only identifier a caller can resolve.
+            for (let hit = before; hit < intersects.length; hit++) {
+                intersects[hit].object = this;
+                intersects[hit].instanceId = memberId;
+            }
+        }
+    }
+    onBeforeRender(renderer, scene, camera, geometry, material) {
+        if (this.batchNeedsSync)
+            this.sync();
+        // Not always the batch's own material: `scene.overrideMaterial` substitutes one wholesale, and
+        // a devtool inspecting the scene may hand over a copy of ours. Upstream tests
+        // `isTroikaTextMaterial`, which is too loose — see {@link readsMemberMatrices}.
+        if (readsMemberMatrices(material))
+            this.memberTexture.prepareForRender(this, material, camera);
+        this.uniforms.texture?.update(renderer);
+    }
+    /**
+     * Syncs members and repacks the batched geometry if needed.
+     *
+     * Unlike upstream, `callback` is invoked on every path — including the ones that find nothing to
+     * do — so `new Promise(resolve => batch.sync(resolve))` always settles.
+     * @param callback - Invoked once the batch is in sync.
+     */
+    sync(callback) {
+        if (this.disposed || !this.batchNeedsSync) {
+            callback?.();
+            return;
+        }
+        this.batchNeedsSync = false;
+        let needsRepack = this._needsRepack;
+        this._needsRepack = false;
+        const pendingSyncs = [];
+        this._members.forEach((packingInfo, text) => {
+            const needsMemberSync = text._needsSync;
+            if (packingInfo.dirty || needsMemberSync) {
+                packingInfo.dirty = false;
+                needsRepack = true;
+                if (needsMemberSync)
+                    pendingSyncs.push(new Promise((resolve) => text.sync(resolve)));
+            }
+        });
+        if (!needsRepack) {
+            callback?.();
+            return;
+        }
+        this.dispatchEvent(syncStartEvent);
+        const repack = () => {
+            // Disposed while a member was still loading its font: the geometry this would write into is
+            // already released, and nothing is left to draw it. The callback still runs, so a caller
+            // awaiting the sync is not stranded by a teardown.
+            if (!this.disposed) {
+                this.repackBatchedGeometry();
+                this.dispatchEvent(syncCompleteEvent);
+            }
+            callback?.();
+        };
+        if (pendingSyncs.length) {
+            void Promise.all(pendingSyncs).then(repack);
+        }
+        else {
+            repack();
+        }
+    }
+    /** The derived material, or `[outline, main]` once a member configures an outline. */
+    get material() {
+        return super.material;
+    }
+    /**
+     * Sets the *base* material to derive from, tolerating the pair the getter answers with.
+     *
+     * The accessor is asymmetric upstream — the getter returns `[outline, main]` once an outline is
+     * configured, the setter only understands a single base — so `object.material =
+     * f(object.material)` stores an array where a material belongs, and the next read walks off it
+     * and takes the render loop down. Keeping the main pass makes the round trip a no-op, which is
+     * what a caller writing it meant; the outline is derived from the main one anyway.
+     *
+     * three.js devtools recolors a highlighted object exactly that way, and `Mesh.copy` does it too,
+     * so both a highlight and a {@link copy} of stroked text reach here with a pair.
+     */
+    set material(value) {
+        super.material = Array.isArray(value) ? value[value.length - 1] : value;
+    }
+    /**
+     * Derives the batch's material: this batch's uniforms onto the base, then troika's derivation,
+     * then the corrections that make the result drawable as a batch.
+     * @param baseMaterial - The material to derive from.
+     * @returns The derived material.
+     */
+    createDerivedMaterial(baseMaterial) {
+        // Once per material — a second wrap would nest, declaring the prologue twice.
+        if (baseMaterial !== this.patchedMaterial) {
+            this.patchedMaterial = baseMaterial;
+            patchBaseMaterial(baseMaterial, this.uniforms);
+        }
+        const derived = super.createDerivedMaterial(baseMaterial);
+        return configureDerivedMaterial(derived, baseMaterial, this.uniforms);
+    }
+    /** Rewrites the batched glyph attributes from the members' render info, and re-measures. */
+    repackBatchedGeometry() {
+        const renderInfo = packGlyphs(this.geometry, this.ordered, (memberId) => this.textById[memberId]);
+        // The inherited `Text` code reads `this.textRenderInfo` for whole-batch state (the SDF atlas,
+        // its glyph size and exponent), which the pass hands back from whichever member it last saw.
+        if (renderInfo) {
+            this._textRenderInfo = renderInfo;
+        }
+        this.boundsNeedsUpdate = true;
+        this.updateBounds();
+    }
+    /**
+     * Flags the material(s) for recompilation, e.g. after the uniform schema changed.
+     *
+     * Handles the pair `material` returns once an outline is configured, not just the single derived
+     * material — missing the outline layer would leave it compiled against the previous uniform
+     * layout.
+     */
+    materialsNeedUpdate() {
+        const material = this.material;
+        for (const m of Array.isArray(material) ? material : [material]) {
+            m.needsUpdate = true;
+        }
+    }
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with anything
+ * three puts in the catalog when the canvas mounts.
+ */
+export const BatchedText = extend(BatchedTextExt);
+// Reused rather than built per dispatch: three's `dispatchEvent` stamps `target` on the object it
+// is handed, so these are one allocation for the batch's lifetime instead of one per event.
+const syncStartEvent = { type: 'syncstart' };
+const syncCompleteEvent = { type: 'synccomplete' };
+const disposeEvent = { type: 'dispose' };
+// Scratch reused across calls, each filled and consumed within a single synchronous block.
+const _sphere = new Sphere();
+const _box = new Box3();

package/dist/core/text/MemberTexture.d.ts

@@ -0,0 +1,90 @@
+import { type Camera, type ColorRepresentation, Matrix4 } from 'three';
+import { type BatchTextMaterial } from 'troika-three-text';
+import { type TextExt } from './Text';
+/** What {@link MemberTexture} reads off the batch it fills for. */
+export interface MemberTextureHost {
+    /**
+     * The batch's world transform. Member matrices are local to *it*, so the frustum has to be built
+     * against this — upstream composed with `scene.matrixWorld`, which agrees only while the batch
+     * sits at the scene root with an identity transform, and every layer is a nested `<group>`.
+     */
+    matrixWorld: Matrix4;
+    /** One past the highest id ever handed out — the rows the texture is sized to, and swept. */
+    addedMembersCount: number;
+    /** The batch's own color, which a member with none of its own draws in. */
+    color: ColorRepresentation | undefined;
+    /**
+     * The member holding an id.
+     * @param memberId - The member to read.
+     * @returns The member, or `undefined` when the id holds none.
+     */
+    getText(memberId: number): TextExt | undefined;
+}
+/**
+ * The data texture a batch's shader reads each member's transform and style from: one 32-float row
+ * per member, refilled once per draw with frustum culling folded in.
+ *
+ * Troika's `BatchedText.prepareForRender`, lifted out of the class and given ownership of the
+ * textures it fills — a pair, since the outline pass writes different fields into the same layout.
+ * Rows are addressed by id, so the texture is sized to the batch's high-water mark rather than to
+ * its live member count.
+ *
+ * Departures from upstream:
+ *
+ * - **The frustum is built against the batch**, not the scene root. See
+ *   {@link MemberTextureHost.matrixWorld}.
+ * - **Hidden and culled members are collapsed, not repacked out** — a zero matrix takes every glyph
+ *   of the member to a point, so it costs vertex shading but no fragments, and no repack.
+ * - **The upload is conditional.** Writes are compared against what the texture already holds, so a
+ *   frame that changed nothing sends nothing.
+ * - **`setMatrixTexture` is inlined**, so a material that lost the method still draws. See
+ *   {@link publish}.
+ */
+export declare class MemberTexture {
+    /** One texture per pass, each allocated on the first draw that needs it. */
+    private readonly textures;
+    /** Whether this pass wrote a value differing from what the texture already held. */
+    private needsUpdate;
+    /**
+     * Refills the texture for one draw and points the material at it.
+     * @param host - The batch being drawn.
+     * @param material - The text material being drawn, main or outline.
+     * @param camera - The camera to cull against.
+     */
+    prepareForRender(host: MemberTextureHost, material: BatchTextMaterial, camera: Camera): void;
+    /** Frees both passes' textures. */
+    dispose(): void;
+    /**
+     * The pass's texture, sized to hold every row, reallocated when the row count outgrows it.
+     * @param pass - Which pass is being drawn.
+     * @param rowCount - Rows the texture must hold, at least one.
+     * @returns The texture.
+     */
+    private textureFor;
+    /**
+     * Writes one member's row: its transform, then the style fields the pass being drawn reads.
+     *
+     * The member populates the material's uniforms itself, since that is where the defaults and the
+     * percentage parsing live; this reads the results straight back out of them.
+     * @param texData - The texture's backing array.
+     * @param start - The row's first float.
+     * @param text - The member to write.
+     * @param material - The material being drawn, main or outline.
+     * @param batchColor - The color a member with none of its own draws in.
+     */
+    private writeMember;
+    /**
+     * Zeroes a member's matrix, taking every glyph of it to a point.
+     * @param texData - The texture's backing array.
+     * @param start - The row's first float.
+     */
+    private collapse;
+    /**
+     * Writes one float, noting whether it changed.
+     * @param texData - The texture's backing array.
+     * @param index - The float's index.
+     * @param value - The value to write.
+     */
+    private setTexData;
+}
+//# sourceMappingURL=MemberTexture.d.ts.map