@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/core/text/MemberTexture.js

@@ -0,0 +1,289 @@
+import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, Vector3, } from 'three';
+import { Y_DOWN_FLIP } from '../../space/Space';
+import { aimDepth } from '../../utils/math';
+/**
+ * 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);
+        // The camera's rotation, brought into the batch's own space, because that is where member
+        // matrices live. Computed once per draw, not once per member. `Y_DOWN_FLIP` plays the camera's
+        // own rest pose here, so `faceCamera` does not bake that pose in twice: once here and once more
+        // in the ordinary view transform at draw time. See `Y_DOWN_FLIP` in `space/Space.ts` for why
+        // this role holds regardless of a member's own scale or rotation.
+        _basis
+            .extractRotation(host.matrixWorld)
+            .transpose()
+            .multiply(_cameraBasis.extractRotation(camera.matrixWorld))
+            .multiply(Y_DOWN_FLIP);
+        // 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;
+        // What a screen-space member's size is exact at, and where the camera looks from. Zero turns the
+        // correction off, for an orthographic camera (no divide to cancel) and for one that never meets
+        // the plan. See `depthScaleOf`.
+        const reference = camera.isPerspectiveCamera
+            ? aimDepth(camera, host.matrixWorld)
+            : 0;
+        _eye.setFromMatrixPosition(camera.matrixWorld);
+        _forward.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
+        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;
+            faceCamera(text, _basis, reference > 0 ? depthScaleOf(text, host.matrixWorld, reference) : 1);
+            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;
+        }
+    }
+}
+/**
+ * How much a screen-space member is scaled so that it keeps the on-screen size its plan-unit size
+ * asks for wherever it sits in a perspective frame.
+ *
+ * The same correction a sprite's shader applies to an image (`spriteDepthScale` in
+ * `sprites/sprite-material.ts`), and for the same reason: a member sized in plan units shrinks by
+ * the projection's divide, and a pitched camera spreads the plan across a range of depths, so one
+ * pixel size is right only where the camera's axis crosses the plan. Without it an image beside its
+ * text is constant in pixels while the text is not, and anything laid out inside the image's
+ * pixels (a count in a counter circle) slides off it as the pin moves up or down the screen.
+ * @param text - The member, with its sprite anchor set.
+ * @param matrixWorld - The batch's world matrix.
+ * @param reference - The depth the plan-unit size is exact at. Must be positive.
+ * @returns The scale, one at the reference depth. One as well for an anchor at or behind the eye.
+ */
+function depthScaleOf(text, matrixWorld, reference) {
+    const anchor = text.spriteAnchor;
+    if (!anchor)
+        return 1;
+    const depth = _offset
+        .set(anchor.x, anchor.y, text.position.z)
+        .applyMatrix4(matrixWorld)
+        .sub(_eye)
+        .dot(_forward);
+    return depth > 0 ? depth / reference : 1;
+}
+/**
+ * Turns a screen-space member to face the camera, and leaves a flat one alone.
+ *
+ * Composed on the CPU, on a loop that already runs once per member per draw, rather than in the
+ * shader. The shader path costs twelve bytes per member of GPU memory and needs a seam on both
+ * `BatchedTextImpl.raycast` and `isDrawn`. This path costs neither, because both of those read the
+ * member's matrix already. Write the sprite matrix there and both follow.
+ *
+ * The composition is
+ * `T(anchor) . basis . S(depth) . T(position - anchor) . Rz(rotation.z) . S(scale)`. The basis is
+ * the camera's rotation brought into the batch's own space, corrected by `Y_DOWN_FLIP` for the
+ * camera's own rest pose (see {@link Y_DOWN_FLIP} in `space/Space.ts`). `S(depth)` is
+ * {@link depthScaleOf}, which scales the offset from the anchor along with the glyphs. Everything
+ * else is read off the member exactly as `updateMatrix` reads it. Straight overhead with the
+ * anchor at the reference depth the basis is the identity and the depth scale is one, so this
+ * reduces to the flat matrix, which is the equality the top-down baseline asserts on screen.
+ *
+ * Written through `setMatrix` only when it changed, so a still camera costs sixteen comparisons and
+ * no bounds invalidation. A pan or a zoom costs the same, because neither moves the camera's
+ * rotation. Only a roll or a pitch dirties a row.
+ * @param text - The member to turn.
+ * @param basis - The camera basis for this draw, in the batch's own space.
+ * @param depthScale - The member's perspective correction. One for none.
+ */
+function faceCamera(text, basis, depthScale) {
+    const anchor = text.spriteAnchor;
+    if (!anchor)
+        return;
+    // `spriteAnchor` carries no z. The offset's z is zero by construction, and the pivot's z is read
+    // off the member's own position instead.
+    _offset.set(text.position.x - anchor.x, text.position.y - anchor.y, 0);
+    _spriteMatrix
+        .copy(basis)
+        .multiply(_step.makeScale(depthScale, depthScale, depthScale))
+        .multiply(_step.makeTranslation(_offset.x, _offset.y, _offset.z))
+        .multiply(_step.makeRotationZ(text.rotation.z))
+        .scale(text.scale)
+        .premultiply(_step.makeTranslation(anchor.x, anchor.y, text.position.z));
+    if (!text.matrix.equals(_spriteMatrix))
+        text.setMatrix(_spriteMatrix);
+}
+/**
+ * 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();
+const _basis = new Matrix4();
+const _cameraBasis = new Matrix4();
+const _spriteMatrix = new Matrix4();
+const _step = new Matrix4();
+const _offset = new Vector3();
+const _eye = new Vector3();
+const _forward = new Vector3();

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

@@ -0,0 +1,88 @@
+import { Matrix4, type Vector2 } from 'three';
+import { Text as TroikaText, type TextMaterial } from 'troika-three-text';
+import { type BatchedTextImpl } 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 TextImpl extends TroikaText {
+    /**
+     * The batch this text belongs to, set by {@link BatchedTextImpl.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: BatchedTextImpl | 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;
+    /**
+     * Where this member pivots when it faces the camera, in the plan's x and y. `null` draws it flat
+     * on the plan.
+     *
+     * One object, set and cleared together, so the two halves cannot disagree. Deliberately not named
+     * `anchorX` or `anchorY`, which troika owns and lists in its syncable properties. Assigning those
+     * would re-run layout and repack the batch on every write. `position`, `quaternion`, `scale` and
+     * `matrix` are all absent from that list, which is what makes the per-draw compose free of layout.
+     *
+     * Two dimensional on purpose. Every line of a def sits at the def's own elevation, so the anchor's
+     * z always equals the member's own `position.z`. There is no separate z to store.
+     *
+     * Derived, never authored. `applyPlacement` sets it from the def's bounds.
+     */
+    spriteAnchor: Vector2 | null;
+    /**
+     * 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<TextImpl, import("@react-three/fiber").MathProps<TextImpl> & import("@react-three/fiber").ReactProps<TextImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<TextImpl, typeof TextImpl>, "object">>>>;
+//# sourceMappingURL=Text.d.ts.map

package/dist/core/text/Text.js

@@ -0,0 +1,230 @@
+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 TextImpl extends TroikaText {
+    /**
+     * The batch this text belongs to, set by {@link BatchedTextImpl.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;
+    /**
+     * Where this member pivots when it faces the camera, in the plan's x and y. `null` draws it flat
+     * on the plan.
+     *
+     * One object, set and cleared together, so the two halves cannot disagree. Deliberately not named
+     * `anchorX` or `anchorY`, which troika owns and lists in its syncable properties. Assigning those
+     * would re-run layout and repack the batch on every write. `position`, `quaternion`, `scale` and
+     * `matrix` are all absent from that list, which is what makes the per-draw compose free of layout.
+     *
+     * Two dimensional on purpose. Every line of a def sits at the def's own elevation, so the anchor's
+     * z always equals the member's own `position.z`. There is no separate z to store.
+     *
+     * Derived, never authored. `applyPlacement` sets it from the def's bounds.
+     */
+    spriteAnchor = null;
+    /**
+     * 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(TextImpl.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(TextImpl);
+// 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