@expofp/renderer 3.2.5 → 3.27.0

package/dist/core/text/MemberTexture.js

@@ -0,0 +1,194 @@
+import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, } from 'three';
+/**
+ * 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 class MemberTexture {
+    /** One texture per pass, each allocated on the first draw that needs it. */
+    textures = {};
+    /** Whether this pass wrote a value differing from what the texture already held. */
+    needsUpdate = false;
+    /**
+     * 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, material, camera) {
+        const isOutline = material.isTextOutlineMaterial;
+        material.uniforms.uTroikaIsOutline.value = isOutline;
+        const rowCount = host.addedMembersCount;
+        // Floored at one member: `Math.log2(0)` is `-Infinity`, which upstream turns into a zero-width,
+        // `NaN`-height texture.
+        const texture = this.textureFor(isOutline ? 'outline' : 'main', Math.max(1, rowCount));
+        const texData = texture.image.data;
+        this.needsUpdate = false;
+        _matrix
+            .multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse)
+            .multiply(host.matrixWorld);
+        _frustum.setFromProjectionMatrix(_matrix, camera.coordinateSystem);
+        // Hoisted out of the loop: `Text`'s `material` getter calls `hasOutline()`, which walks every
+        // member, so reading it per member made this loop quadratic — and it returns an *array* once
+        // outlines are on, whose `.color` is undefined. The material being drawn is already in hand.
+        const batchColor = host.color ?? material.color ?? 0xffffff;
+        for (let memberId = 0; memberId < rowCount; memberId++) {
+            const text = host.getText(memberId);
+            // An unsynced member has no layout to write and draws nothing either.
+            if (!text?.textRenderInfo)
+                continue;
+            const start = memberId * FLOATS_PER_MEMBER;
+            if (isDrawn(text)) {
+                this.writeMember(texData, start, text, material, batchColor);
+            }
+            else {
+                this.collapse(texData, start);
+            }
+        }
+        // Assigning `false` is a no-op in three — the setter only bumps the version for `true` — so this
+        // requests an upload when something changed and leaves the texture alone when nothing did.
+        texture.needsUpdate = this.needsUpdate;
+        publish(material, texture);
+    }
+    /** Frees both passes' textures. */
+    dispose() {
+        for (const pass of Object.keys(this.textures)) {
+            this.textures[pass]?.dispose();
+            delete this.textures[pass];
+        }
+    }
+    /**
+     * 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.
+     */
+    textureFor(pass, rowCount) {
+        let texture = this.textures[pass];
+        const dataLength = Math.pow(2, Math.ceil(Math.log2(rowCount * FLOATS_PER_MEMBER)));
+        if (texture && dataLength === texture.image.data.length)
+            return texture;
+        texture?.dispose();
+        const width = Math.min(dataLength / 4, 1024);
+        texture = new DataTexture(new Float32Array(dataLength), width, dataLength / 4 / width, RGBAFormat, FloatType);
+        this.textures[pass] = texture;
+        return texture;
+    }
+    /**
+     * 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.
+     */
+    writeMember(texData, start, text, material, batchColor) {
+        const isOutline = material.isTextOutlineMaterial;
+        const matrix = text.matrix.elements;
+        for (let i = 0; i < 16; i++) {
+            this.setTexData(texData, start + i, matrix[i]);
+        }
+        text._prepareForRender(material);
+        const { uTroikaTotalBounds, uTroikaClipRect, uTroikaPositionOffset, uTroikaEdgeOffset, uTroikaBlurRadius, uTroikaStrokeWidth, uTroikaStrokeColor, uTroikaStrokeOpacity, uTroikaFillOpacity, uTroikaCurveRadius, } = material.uniforms;
+        // Total bounds for uv
+        for (let i = 0; i < 4; i++) {
+            this.setTexData(texData, start + 16 + i, uTroikaTotalBounds.value.getComponent(i));
+        }
+        // Clip rect
+        for (let i = 0; i < 4; i++) {
+            this.setTexData(texData, start + 20 + i, uTroikaClipRect.value.getComponent(i));
+        }
+        // Color
+        const color = (isOutline ? text.outlineColor || 0 : text.color) ?? batchColor;
+        this.setTexData(texData, start + 24, _color.set(color).getHex());
+        // Fill opacity / outline opacity
+        this.setTexData(texData, start + 25, uTroikaFillOpacity.value);
+        // Curve radius
+        this.setTexData(texData, start + 26, uTroikaCurveRadius.value);
+        if (isOutline) {
+            // Outline properties
+            this.setTexData(texData, start + 28, uTroikaPositionOffset.value.x);
+            this.setTexData(texData, start + 29, uTroikaPositionOffset.value.y);
+            this.setTexData(texData, start + 30, uTroikaEdgeOffset.value);
+            this.setTexData(texData, start + 31, uTroikaBlurRadius.value);
+        }
+        else {
+            // Stroke properties
+            this.setTexData(texData, start + 28, uTroikaStrokeWidth.value);
+            this.setTexData(texData, start + 29, _color.set(uTroikaStrokeColor.value).getHex());
+            this.setTexData(texData, start + 30, uTroikaStrokeOpacity.value);
+        }
+    }
+    /**
+     * 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.
+     */
+    collapse(texData, start) {
+        for (let i = 0; i < 16; i++) {
+            this.setTexData(texData, start + i, 0);
+        }
+    }
+    /**
+     * 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.
+     */
+    setTexData(texData, index, value) {
+        if (value !== texData[index]) {
+            texData[index] = value;
+            this.needsUpdate = true;
+        }
+    }
+}
+/**
+ * Whether a member draws this frame: shown, and inside the frustum this pass was set up with.
+ * @param text - The member to test.
+ * @returns Whether it draws.
+ */
+function isDrawn(text) {
+    if (!text.visible)
+        return false;
+    return _frustum.intersectsSphere(_sphere.copy(text.geometry.boundingSphere).applyMatrix4(text.matrix));
+}
+/**
+ * Points a material at the texture it should read members from, sizing it in the same write.
+ *
+ * Troika's `setMatrixTexture`, inlined — this is the whole of it. Calling the method instead would
+ * throw on any material that lost it, which is every copy built by calling `material.constructor`;
+ * the uniforms it writes are inherited by all of them, so writing them directly leaves such a copy
+ * drawing the batch where the batch actually is.
+ * @param material - The material being drawn.
+ * @param texture - The texture it should read.
+ */
+function publish(material, texture) {
+    const { uTroikaMatricesTexture, uTroikaMatricesTextureSize } = material.uniforms;
+    uTroikaMatricesTexture.value = texture;
+    uTroikaMatricesTextureSize.value.set(texture.image.width, texture.image.height);
+}
+/** Floats each member occupies; troika's packing, unchanged. */
+const FLOATS_PER_MEMBER = 32;
+// Scratch reused across calls, each filled and consumed within a single synchronous block.
+const _color = new Color();
+const _matrix = new Matrix4();
+const _frustum = new Frustum();
+const _sphere = new Sphere();

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

@@ -0,0 +1,73 @@
+import { Matrix4 } from 'three';
+import { Text as TroikaText, type TextMaterial } from 'troika-three-text';
+import { type BatchedTextExt } from './BatchedText';
+/**
+ * troika's `Text` with the deviations a batched, 2D-painter renderer needs.
+ *
+ * Four departures from upstream, each load-bearing:
+ *
+ * 1. **The clip rect is not applied to the geometry when batched.** Upstream ends
+ *    `_prepareForRender` with `geometry.applyClipRect(…)`, but a member's geometry *is* the batch's
+ *    shared `GlyphsGeometry` — applying one member's rect would clip the whole batch, and dirty a
+ *    buffer every member then re-dirties. The batch reads the rect out of the uniforms instead.
+ * 2. **`depthOffset` is unsupported.** Upstream writes `material.polygonOffset` and friends from it
+ *    on every render, so a base material that set them itself is overwritten every frame — with
+ *    `false`, since `depthOffset` defaults to `0`. Set polygon offset on the base material directly;
+ *    this class never touches it.
+ * 3. **The `color` shortcut is skipped when batched.** It mutates the *shared* derived material once
+ *    per member per frame, and the batch ignores `material.color` anyway — it reads `text.color`
+ *    straight into the data texture.
+ * 4. **`strokeOpacity` defaults to `1` rather than staying `undefined`.** Upstream leaves it unset
+ *    when `strokeWidth` is `0`; the batch writes that uniform into a `Float32Array`, where
+ *    `undefined` becomes `NaN`, and `NaN !== NaN` makes its change-detection report a write every
+ *    frame — re-uploading the whole texture forever.
+ *
+ * Members are **not in the scene graph**, so nothing calls `updateMatrixWorld` for them: their local
+ * `matrix` is the transform the batch draws with, and the batch's bounds pass is what recomposes it.
+ * That pass runs only when something reports a move, and three gives `position` and `scale` no change
+ * callback — so after moving a member, call {@link updateMatrix}, or write the matrix wholesale with
+ * {@link setMatrix}. Both report back through {@link _batchParent}.
+ *
+ * Render it with {@link Text}.
+ */
+export declare class TextExt extends TroikaText {
+    /**
+     * The batch this text belongs to, set by {@link BatchedTextExt.addText}. It is how a member
+     * reaches its batch without the batch scanning for changes: property writes invalidate the sync
+     * through it, and transform writes invalidate the bounds.
+     */
+    _batchParent: BatchedTextExt | undefined;
+    /**
+     * Backing store for the `_needsSync` accessor installed on the prototype below.
+     *
+     * Initialized `true`, which is both what a fresh member wants — it has never been laid out — and
+     * exactly what the base constructor leaves behind: its own property writes set the flag before
+     * this initializer runs, so seeding `false` here would quietly undo them.
+     */
+    _syncFlag: boolean;
+    /**
+     * Writes the local transform directly and tells the batch its bounds moved.
+     *
+     * Turns off `matrixAutoUpdate`, so the batch's bounds pass leaves the matrix alone — the caller
+     * owns it from here.
+     * @param matrix - The transform to draw this text with.
+     */
+    setMatrix(matrix: Matrix4): void;
+    /**
+     * Recomposes the local matrix from `position`/`quaternion`/`scale`, and tells the batch its bounds
+     * moved.
+     *
+     * Members are not in the scene graph, so three never calls this; a caller that moved one should,
+     * and the report is what schedules the batch's bounds pass. That pass recomposes the matrix again
+     * — harmless, and it is what leaves a caller who reaches for `invalidateBounds` instead equally
+     * correct.
+     */
+    updateMatrix(): void;
+    _prepareForRender(material: TextMaterial): void;
+}
+/**
+ * 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 Text: 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<TextExt, import("@react-three/fiber").MathProps<TextExt> & import("@react-three/fiber").ReactProps<TextExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<TextExt, typeof TextExt>, "object">>>>;
+//# sourceMappingURL=Text.d.ts.map

package/dist/core/text/Text.js

@@ -0,0 +1,215 @@
+import { extend } from '@react-three/fiber';
+import { Color, Matrix4, Vector3 } from 'three';
+import { Text as TroikaText } from 'troika-three-text';
+/**
+ * troika's `Text` with the deviations a batched, 2D-painter renderer needs.
+ *
+ * Four departures from upstream, each load-bearing:
+ *
+ * 1. **The clip rect is not applied to the geometry when batched.** Upstream ends
+ *    `_prepareForRender` with `geometry.applyClipRect(…)`, but a member's geometry *is* the batch's
+ *    shared `GlyphsGeometry` — applying one member's rect would clip the whole batch, and dirty a
+ *    buffer every member then re-dirties. The batch reads the rect out of the uniforms instead.
+ * 2. **`depthOffset` is unsupported.** Upstream writes `material.polygonOffset` and friends from it
+ *    on every render, so a base material that set them itself is overwritten every frame — with
+ *    `false`, since `depthOffset` defaults to `0`. Set polygon offset on the base material directly;
+ *    this class never touches it.
+ * 3. **The `color` shortcut is skipped when batched.** It mutates the *shared* derived material once
+ *    per member per frame, and the batch ignores `material.color` anyway — it reads `text.color`
+ *    straight into the data texture.
+ * 4. **`strokeOpacity` defaults to `1` rather than staying `undefined`.** Upstream leaves it unset
+ *    when `strokeWidth` is `0`; the batch writes that uniform into a `Float32Array`, where
+ *    `undefined` becomes `NaN`, and `NaN !== NaN` makes its change-detection report a write every
+ *    frame — re-uploading the whole texture forever.
+ *
+ * Members are **not in the scene graph**, so nothing calls `updateMatrixWorld` for them: their local
+ * `matrix` is the transform the batch draws with, and the batch's bounds pass is what recomposes it.
+ * That pass runs only when something reports a move, and three gives `position` and `scale` no change
+ * callback — so after moving a member, call {@link updateMatrix}, or write the matrix wholesale with
+ * {@link setMatrix}. Both report back through {@link _batchParent}.
+ *
+ * Render it with {@link Text}.
+ */
+export class TextExt extends TroikaText {
+    /**
+     * The batch this text belongs to, set by {@link BatchedTextExt.addText}. It is how a member
+     * reaches its batch without the batch scanning for changes: property writes invalidate the sync
+     * through it, and transform writes invalidate the bounds.
+     */
+    _batchParent = undefined;
+    /**
+     * Backing store for the `_needsSync` accessor installed on the prototype below.
+     *
+     * Initialized `true`, which is both what a fresh member wants — it has never been laid out — and
+     * exactly what the base constructor leaves behind: its own property writes set the flag before
+     * this initializer runs, so seeding `false` here would quietly undo them.
+     */
+    _syncFlag = true;
+    /**
+     * Writes the local transform directly and tells the batch its bounds moved.
+     *
+     * Turns off `matrixAutoUpdate`, so the batch's bounds pass leaves the matrix alone — the caller
+     * owns it from here.
+     * @param matrix - The transform to draw this text with.
+     */
+    setMatrix(matrix) {
+        this.matrixAutoUpdate = false;
+        this.matrix.copy(matrix);
+        this._batchParent?.invalidateBounds();
+    }
+    /**
+     * Recomposes the local matrix from `position`/`quaternion`/`scale`, and tells the batch its bounds
+     * moved.
+     *
+     * Members are not in the scene graph, so three never calls this; a caller that moved one should,
+     * and the report is what schedules the batch's bounds pass. That pass recomposes the matrix again
+     * — harmless, and it is what leaves a caller who reaches for `invalidateBounds` instead equally
+     * correct.
+     */
+    updateMatrix() {
+        super.updateMatrix();
+        this._batchParent?.invalidateBounds();
+    }
+    _prepareForRender(material) {
+        const defaultStrokeColor = 0x808080;
+        const defaultOrient = '+x+y';
+        const isOutline = material.isTextOutlineMaterial;
+        const uniforms = material.uniforms;
+        const textInfo = this.textRenderInfo;
+        const batched = this._batchParent !== undefined;
+        if (textInfo) {
+            const { sdfTexture, blockBounds } = textInfo;
+            const { width, height } = sdfTexture.image;
+            uniforms.uTroikaSDFTexture.value = sdfTexture;
+            uniforms.uTroikaSDFTextureSize.value.set(width, height);
+            uniforms.uTroikaSDFGlyphSize.value = textInfo.sdfGlyphSize;
+            uniforms.uTroikaSDFExponent.value = textInfo.sdfExponent;
+            uniforms.uTroikaTotalBounds.value.fromArray(blockBounds);
+            uniforms.uTroikaUseGlyphColors.value = !isOutline && !!textInfo.glyphColors;
+            let distanceOffset = 0;
+            let blurRadius = 0;
+            let strokeWidth = 0;
+            let fillOpacity;
+            // Deviation 4 (see class docs): initialized, not left undefined, so the batch never writes
+            // `NaN` into its data texture and re-uploads it on every frame thereafter.
+            let strokeOpacity = 1;
+            let strokeColor;
+            let offsetX = 0;
+            let offsetY = 0;
+            if (isOutline) {
+                const { outlineWidth, outlineOffsetX, outlineOffsetY, outlineBlur, outlineOpacity } = this;
+                distanceOffset = this._parsePercent(outlineWidth) || 0;
+                blurRadius = Math.max(0, this._parsePercent(outlineBlur) || 0);
+                fillOpacity = outlineOpacity;
+                offsetX = this._parsePercent(outlineOffsetX) || 0;
+                offsetY = this._parsePercent(outlineOffsetY) || 0;
+            }
+            else {
+                strokeWidth = Math.max(0, this._parsePercent(this.strokeWidth) || 0);
+                if (strokeWidth) {
+                    strokeColor = this.strokeColor;
+                    uniforms.uTroikaStrokeColor.value.set(strokeColor ?? defaultStrokeColor);
+                    strokeOpacity = this.strokeOpacity ?? 1;
+                }
+                fillOpacity = this.fillOpacity;
+            }
+            uniforms.uTroikaEdgeOffset.value = distanceOffset;
+            uniforms.uTroikaPositionOffset.value.set(offsetX, offsetY);
+            uniforms.uTroikaBlurRadius.value = blurRadius;
+            uniforms.uTroikaStrokeWidth.value = strokeWidth;
+            uniforms.uTroikaStrokeOpacity.value = strokeOpacity;
+            uniforms.uTroikaFillOpacity.value = fillOpacity ?? 1;
+            uniforms.uTroikaCurveRadius.value = this.curveRadius || 0;
+            const clipRect = this.clipRect;
+            if (clipRect && Array.isArray(clipRect) && clipRect.length === 4) {
+                uniforms.uTroikaClipRect.value.fromArray(clipRect);
+            }
+            else {
+                // no clipping - choose a finite rect that shouldn't ever be reached by overflowing glyphs or outlines
+                const pad = (this.fontSize || 0.1) * 100;
+                uniforms.uTroikaClipRect.value.set(blockBounds[0] - pad, blockBounds[1] - pad, blockBounds[2] + pad, blockBounds[3] + pad);
+            }
+            // Deviation 1 (see class docs): the geometry is the batch's, shared by every member.
+            if (!batched)
+                this.geometry.applyClipRect(uniforms.uTroikaClipRect.value);
+        }
+        uniforms.uTroikaSDFDebug.value = !!this.debugSDF;
+        // Deviation 2 (see class docs): upstream wrote `material.polygonOffset`,
+        // `polygonOffsetFactor` and `polygonOffsetUnits` from `this.depthOffset` here.
+        // Deviation 3 (see class docs): the shortcut writes to the shared derived material, and the
+        // batch reads `text.color` directly, so batched members skip it entirely.
+        if (!batched) {
+            // Shortcut for setting material color via `color` prop on the mesh; this is
+            // applied only to the derived material to avoid mutating a shared base material.
+            const color = isOutline ? this.outlineColor || 0 : this.color;
+            if (color == null) {
+                // @ts-expect-error - Vendored
+                delete material.color; //inherit from base
+            }
+            else {
+                // eslint-disable-next-line no-prototype-builtins
+                const colorObj = material.hasOwnProperty('color')
+                    ? material.color
+                    : (material.color = new Color());
+                if (color !== colorObj._input || typeof color === 'object') {
+                    colorObj.set((colorObj._input = color));
+                }
+            }
+        }
+        // base orientation
+        let orient = this.orientation || defaultOrient;
+        if (orient !== material._orientation) {
+            const rotMat = uniforms.uTroikaOrient.value;
+            orient = orient.replace(/[^-+xyz]/g, '');
+            const match = orient !== defaultOrient && /^([-+])([xyz])([-+])([xyz])$/.exec(orient);
+            if (match) {
+                const [, hSign, hAxis, vSign, vAxis] = match;
+                // @ts-expect-error - Vendored
+                _horizontal.set(0, 0, 0)[hAxis] = hSign === '-' ? 1 : -1;
+                // @ts-expect-error - Vendored
+                _vertical.set(0, 0, 0)[vAxis] = vSign === '-' ? -1 : 1;
+                _matrix.lookAt(ORIGIN, _horizontal.cross(_vertical), _vertical);
+                rotMat.setFromMatrix4(_matrix);
+            }
+            else {
+                rotMat.identity();
+            }
+            material._orientation = orient;
+        }
+    }
+}
+/**
+ * Routes every write of troika's own dirty flag through the batch.
+ *
+ * Upstream re-declares all eighteen syncable properties (`text`, `fontSize`, `anchorX`, …) as
+ * accessors that set `_needsSync`; hooking the flag itself instead of copying that list covers every
+ * one of them, plus the queued-resync path inside `Text.sync`, and cannot drift when troika adds a
+ * nineteenth.
+ *
+ * Runs during `super()` — the base constructor seeds the syncable properties — at which point the
+ * `_batchParent` field initializer has not run yet, so the optional call is doing real work.
+ */
+Object.defineProperty(TextExt.prototype, '_needsSync', {
+    configurable: true,
+    get() {
+        return this._syncFlag;
+    },
+    set(value) {
+        this._syncFlag = value;
+        // Undefined while the base constructor runs, which is fine: a member is always constructed
+        // before it joins a batch, so there is no parent to tell yet.
+        if (value)
+            this._batchParent?.requestSync();
+    },
+});
+/**
+ * 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 Text = extend(TextExt);
+// Scratch reused across calls, each filled and consumed within a single synchronous block.
+const _matrix = new Matrix4();
+const _horizontal = new Vector3();
+const _vertical = new Vector3();
+/** The eye a base-orientation `lookAt` turns about — always the local origin. */
+const ORIGIN = new Vector3();

package/dist/core/text/batched-text-material.d.ts

@@ -0,0 +1,56 @@
+import { type Material } from 'three';
+import { type BatchTextMaterial, type TextMaterial } from 'troika-three-text';
+import { type InstanceUniforms } from '../InstanceUniforms';
+/**
+ * The material side of a text batch: what troika's derivation has to become before it can draw a
+ * batch's members, and where the batch's per-instance uniforms are declared.
+ *
+ * Troika builds that material in two moments with its own derivation between them, so the work
+ * splits the same way — {@link patchBaseMaterial} runs on the base material *before*
+ * `createDerivedMaterial`, {@link configureDerivedMaterial} on the result *after*. Each order is
+ * load-bearing; see the two.
+ *
+ * Free functions holding no state, as `instanced-material.ts` is. What is per-batch — which material
+ * has already been wrapped — stays on the batch.
+ */
+/** The per-member index attribute troika's batch material declares, and the uniforms texture indexes by. */
+export declare const MEMBER_INDEX_ATTRIBUTE = "aTroikaTextBatchMemberIndex";
+/**
+ * Wraps a base material's `onBeforeCompile` so a batch's per-instance uniforms are declared ahead of
+ * anything the material itself patches in.
+ *
+ * The prologue goes on the **base**, ahead of troika's rewrite: troika calls the base material's
+ * handler first and then rebuilds `main` around it, renaming the original `troikaOrigMain`.
+ * Injecting here puts the prologue and whatever the material patches in on the same side of that
+ * rename, so a material patch reading a per-instance uniform finds it in scope; injecting from the
+ * derived handler instead would strand the two in different functions.
+ *
+ * Call once per material — a second wrap would nest, and the caller holds the memo that prevents it.
+ * @param material - The base material troika derives from.
+ * @param uniforms - The batch's per-instance uniforms.
+ */
+export declare function patchBaseMaterial(material: Material, uniforms: InstanceUniforms): void;
+/**
+ * Finishes troika's derivation: reverts its two impositions on the base, and installs the one shader
+ * hook a batch needs.
+ * @param derived - What `createDerivedMaterial` returned.
+ * @param base - The material it was derived from.
+ * @param uniforms - The batch's per-instance uniforms, whose presence the program is cached by.
+ * @returns `derived`.
+ */
+export declare function configureDerivedMaterial(derived: TextMaterial, base: Material, uniforms: InstanceUniforms): TextMaterial;
+/**
+ * Whether a material draws through the batched text shader — the only thing a batch's per-draw
+ * texture fill asks of the material it is handed.
+ *
+ * `isTroikaTextMaterial`, which upstream tests instead, does not establish that. Troika sets it on
+ * the text derivation, which the batch's material only sits on top of — so a plain unbatched `Text`
+ * material carries the flag too, and filling one would write matrices its shader never reads. The
+ * uniforms are the honest test: a batch derives over a link that declares them, an unbatched `Text`
+ * never does, and every derivation merges its base's uniform map forward, so they survive into any
+ * sibling built by calling `material.constructor`.
+ * @param material - The material three is about to draw with.
+ * @returns Whether it reads its transforms from a matrix texture.
+ */
+export declare function readsMemberMatrices(material: Material): material is BatchTextMaterial;
+//# sourceMappingURL=batched-text-material.d.ts.map

package/dist/core/text/batched-text-material.js

@@ -0,0 +1,121 @@
+import { openMain } from '../shader-source';
+/**
+ * The material side of a text batch: what troika's derivation has to become before it can draw a
+ * batch's members, and where the batch's per-instance uniforms are declared.
+ *
+ * Troika builds that material in two moments with its own derivation between them, so the work
+ * splits the same way — {@link patchBaseMaterial} runs on the base material *before*
+ * `createDerivedMaterial`, {@link configureDerivedMaterial} on the result *after*. Each order is
+ * load-bearing; see the two.
+ *
+ * Free functions holding no state, as `instanced-material.ts` is. What is per-batch — which material
+ * has already been wrapped — stays on the batch.
+ */
+/** The per-member index attribute troika's batch material declares, and the uniforms texture indexes by. */
+export const MEMBER_INDEX_ATTRIBUTE = 'aTroikaTextBatchMemberIndex';
+/**
+ * Wraps a base material's `onBeforeCompile` so a batch's per-instance uniforms are declared ahead of
+ * anything the material itself patches in.
+ *
+ * The prologue goes on the **base**, ahead of troika's rewrite: troika calls the base material's
+ * handler first and then rebuilds `main` around it, renaming the original `troikaOrigMain`.
+ * Injecting here puts the prologue and whatever the material patches in on the same side of that
+ * rename, so a material patch reading a per-instance uniform finds it in scope; injecting from the
+ * derived handler instead would strand the two in different functions.
+ *
+ * Call once per material — a second wrap would nest, and the caller holds the memo that prevents it.
+ * @param material - The base material troika derives from.
+ * @param uniforms - The batch's per-instance uniforms.
+ */
+export function patchBaseMaterial(material, uniforms) {
+    const onBeforeCompileBase = material.onBeforeCompile.bind(material);
+    material.onBeforeCompile = (shader, renderer) => {
+        uniforms.patchShader(shader, MEMBER_INDEX_ATTRIBUTE);
+        onBeforeCompileBase(shader, renderer);
+    };
+}
+/**
+ * Finishes troika's derivation: reverts its two impositions on the base, and installs the one shader
+ * hook a batch needs.
+ * @param derived - What `createDerivedMaterial` returned.
+ * @param base - The material it was derived from.
+ * @param uniforms - The batch's per-instance uniforms, whose presence the program is cached by.
+ * @returns `derived`.
+ */
+export function configureDerivedMaterial(derived, base, uniforms) {
+    // troika forces `transparent = true` on every derived text material, which moves the batch into
+    // three's *transparent* render list — drawn after every opaque object regardless of `renderOrder`,
+    // so text would always cover the layers above it. Our base materials get alpha blending from
+    // `CustomBlending` instead (objects/materials/shared.ts), so this restores what the base asked for.
+    // Everything else troika leaves alone already delegates to the base through the prototype chain.
+    derived.transparent = base.transparent;
+    // With `transparent` reverted the batch renders from three's *opaque* list, which
+    // `painterSortStable` orders by `material.id` — and troika builds its outline material with
+    // `id + 0.1`, so the preliminary outline pass would sort *after* the fill and paint over it. (Its
+    // own forced transparency hid this: the transparent list sorts by depth, with no `material.id`
+    // term.) Building it here, with a lower id, restores the intended order; troika's getter finds it
+    // already cached and uses it.
+    derived._outlineMtl = makeOutlineMaterial(derived);
+    // Recompile when the uniform schema changes, since that changes the generated GLSL.
+    const cacheKeyBase = derived.customProgramCacheKey.bind(derived);
+    derived.customProgramCacheKey = () => `efpText_${!!uniforms.texture}|${cacheKeyBase()}`;
+    // Assignment, *not* the read-bind-wrap pattern the sibling meshes use: troika defines
+    // `onBeforeCompile` as an accessor pair whose getter returns troika's own handler and whose setter
+    // stashes ours (troika-three-utils DerivedMaterial), so calling through the getter from inside our
+    // handler would re-enter troika's, which calls ours again. Troika invokes this one last, after its
+    // shader upgrade, which is the only thing that has to be true.
+    derived.onBeforeCompile = (shader) => {
+        // Late by necessity: troika's own `vertexTransform` *reads* this offset, and the transform runs
+        // from the main it builds, ahead of the base's. Initializing any earlier would leave the
+        // transform reading the garbage this exists to prevent.
+        shader.vertexShader = openMain(shader.vertexShader, POSITION_OFFSET_INIT);
+    };
+    return derived;
+}
+/**
+ * Whether a material draws through the batched text shader — the only thing a batch's per-draw
+ * texture fill asks of the material it is handed.
+ *
+ * `isTroikaTextMaterial`, which upstream tests instead, does not establish that. Troika sets it on
+ * the text derivation, which the batch's material only sits on top of — so a plain unbatched `Text`
+ * material carries the flag too, and filling one would write matrices its shader never reads. The
+ * uniforms are the honest test: a batch derives over a link that declares them, an unbatched `Text`
+ * never does, and every derivation merges its base's uniform map forward, so they survive into any
+ * sibling built by calling `material.constructor`.
+ * @param material - The material three is about to draw with.
+ * @returns Whether it reads its transforms from a matrix texture.
+ */
+export function readsMemberMatrices(material) {
+    return !!material.uniforms?.uTroikaMatricesTexture;
+}
+/**
+ * Builds the outline pass's material: troika's own recipe, with the id inverted.
+ *
+ * Prototype-chained to the fill material so it shares every uniform and shader, exactly as troika
+ * does — the two differ only in `isTextOutlineMaterial`, which is what the per-draw fill branches on
+ * to write the outline row of the data texture.
+ * @param derived - The fill material to derive the outline pass from.
+ * @returns The outline material.
+ */
+function makeOutlineMaterial(derived) {
+    const outline = Object.create(derived, {
+        // Below the fill, not above it: three's opaque sort is ascending by `material.id`, and the
+        // outline is a *preliminary* pass. A fraction keeps it clear of every integer material id.
+        id: { value: derived.id - 0.5 },
+    });
+    outline.isTextOutlineMaterial = true;
+    outline.depthWrite = false;
+    outline.map = null;
+    // troika disposes its own outline material with the fill; matched so replacing it leaks nothing.
+    derived.addEventListener('dispose', function onDispose() {
+        derived.removeEventListener('dispose', onDispose);
+        outline.dispose();
+    });
+    return outline;
+}
+/**
+ * Seeds the position-offset varying. An uninitialized varying reads as garbage on some Samsung/Mali
+ * drivers, and troika's `vertexTransform` only assigns this one in the outline branch — so the main
+ * pass would never write it at all.
+ */
+const POSITION_OFFSET_INIT = /* glsl */ `uTroikaPositionOffset = vec2(0.0);`;