@expofp/renderer 0.0.0-experimental.2d6c681

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

@@ -0,0 +1,233 @@
+import { type BufferGeometry, type Camera, type Intersection, type Material, type Raycaster, type Scene, type WebGLRenderer } from 'three';
+import { BatchedText as TroikaBatchedText, type TextMaterial } from 'troika-three-text';
+import { type UniformSchemaShader } from '../InstanceUniforms';
+import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
+import { type TextImpl } from './Text';
+/**
+ * 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
+ *   `TextImpl._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 InstancedMeshImpl}'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 TextImpl}, 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 declare class BatchedTextImpl extends TroikaBatchedText {
+    /**
+     * Marks this as a text batch. three's brand pattern, which `BatchedMeshImpl` inherits from three
+     * and `InstancedMeshImpl` declares for itself. troika ships no such flag on its own `BatchedText`,
+     * so this one is ours.
+     */
+    readonly isBatchedText = true;
+    /** Per-instance uniform store, shared with {@link BatchedMeshImpl} and {@link InstancedMeshImpl}. */
+    private readonly uniforms;
+    /** The per-member transform and style rows the batch's shader draws from. */
+    private readonly memberTexture;
+    /** Member ids in paint order; the iteration order for packing, and therefore the draw order. */
+    private ordered;
+    /** Id to member, with holes for released ids. Indexed by id, so it needs no map lookup. */
+    private textById;
+    /** Released ids, reused before the high-water mark grows. */
+    private freeIds;
+    private _addedMembersCount;
+    private boundsNeedsUpdate;
+    private batchNeedsSync;
+    /**
+     * 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.
+     */
+    private disposed;
+    constructor();
+    /** Number of members in the batch. */
+    get size(): number;
+    /**
+     * 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 InstancedMeshImpl}, 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(): number;
+    /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
+    private patchedMaterial;
+    /** Marks the batch as needing a sync pass. Members call this through `TextImpl._batchParent`. */
+    requestSync(): void;
+    /**
+     * Marks the batch's bounds as stale. Members call this through `TextImpl._batchParent` whenever
+     * their transform changes, so no caller has to remember to.
+     */
+    invalidateBounds(): void;
+    /**
+     * The member holding an id.
+     * @param memberId - The member to read.
+     * @returns The member, or `undefined` when the id holds none.
+     */
+    getText(memberId: number): TextImpl | undefined;
+    /**
+     * 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: number, visible: boolean): void;
+    /**
+     * 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: readonly TextImpl[]): void;
+    /**
+     * 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: UniformSchemaShader): void;
+    /**
+     * 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: number, name: string, target?: UniformValueObj): UniformValue;
+    /**
+     * 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: number, name: string, value: UniformValue): void;
+    /**
+     * 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: TextImpl): number;
+    removeText(text: TextImpl): void;
+    /**
+     * 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: this): this;
+    dispose(): void;
+    /**
+     * 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(): void;
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+    onBeforeRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material): void;
+    /**
+     * 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?: () => void): void;
+    /** The derived material, or `[outline, main]` once a member configures an outline. */
+    get material(): Material | [outline: TextMaterial, main: TextMaterial];
+    /**
+     * 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: Material | [outline: TextMaterial, main: TextMaterial] | null);
+    /**
+     * 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: Material): TextMaterial;
+    /** Rewrites the batched glyph attributes from the members' render info, and re-measures. */
+    private repackBatchedGeometry;
+    /**
+     * 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.
+     */
+    private materialsNeedUpdate;
+}
+/**
+ * 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 declare const BatchedText: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedTextImpl, import("@react-three/fiber").MathProps<BatchedTextImpl> & import("@react-three/fiber").ReactProps<BatchedTextImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedTextImpl, typeof BatchedTextImpl>, "object">>>>;
+//# sourceMappingURL=BatchedText.d.ts.map