@expofp/renderer 3.38.0 → 3.39.1

package/dist/core/sprites/BatchedSprites.js

@@ -0,0 +1,205 @@
+import { extend } from '@react-three/fiber';
+import { Matrix4, PlaneGeometry, Vector2, Vector3, } from 'three';
+import { InstancedMeshImpl } from '../instanced/InstancedMesh';
+import { RaycastingSprites } from './RaycastingSprites';
+import { ANCHOR_SCHEMA, ANCHOR_UNIFORM, patchSpriteMaterial, spriteReferenceDepth, } from './sprite-material';
+/**
+ * Whether an instanced mesh is a sprite batch.
+ *
+ * three's own brand pattern, which `isLineMaterial` in `BatchedLines` already follows here. A holder
+ * that keeps one mesh field for several batch kinds narrows it with this, instead of keeping a
+ * second field that says which kind it stored.
+ * @param object - The instanced mesh to test.
+ * @returns Whether it is a sprite batch.
+ */
+export function isBatchedSprites(object) {
+    return object.isBatchedSprites === true;
+}
+/**
+ * An instanced mesh whose every member faces the camera.
+ *
+ * The name means what it says, which is why this is a class and not a flag. A batch of sprites is
+ * homogeneous. One atlas is then drawn by two meshes over two disjoint subsets of its images,
+ * instead of one mesh learning about orientation, and the packing never hears about the distinction.
+ *
+ * What facing the camera changes, and nothing else does:
+ *
+ * - The projection, in the shader. See `sprite-material.ts`. Everything else an instanced mesh
+ *   does applies unchanged: slots, visibility, growth, per-instance uniforms, the draw list that is
+ *   also the paint order, and the material wiring.
+ * - The anchor, as a per-instance uniform rather than a fold into the matrix. A sprite pivots
+ *   about its anchor, so the matrix translation has to be the anchor.
+ * - The bounds, which enclose the quad about that anchor. See `getBoundingSphereAt`.
+ * - Picking, which has to run three's own sprite algorithm through a scratch object. See
+ *   `RaycastingSprites`.
+ *
+ * Members are ids, not `Sprite` objects. `BatchedTextImpl` takes `TextImpl` members because troika's
+ * layout is object shaped and asynchronous, and the batch has to pack what those objects produce. A
+ * sprite carries none of that. It is a matrix, an anchor and a color, and every one of those
+ * already lives in a data texture this mesh owns. Reusing three's type as the member representation
+ * would reinstate the object-per-instance layer the port dropped, and would import `SpriteMaterial`
+ * semantics this package does not implement. Three's type is reused where it costs nothing, as
+ * picking scratch.
+ *
+ * This class knows nothing about textures. A uv region belongs to `TextureMaterial` and to the layer
+ * that packs an atlas. A batch drawn with a plain color material works exactly as well, and tints
+ * its members through `setColorAt` like any instanced mesh.
+ *
+ * Render it with `BatchedSprites`.
+ */
+export class BatchedSpritesImpl extends InstancedMeshImpl {
+    /** Marks this as a sprite batch. See `isBatchedSprites`. */
+    isBatchedSprites = true;
+    /**
+     * The quad every member is drawn from, shared by every sprite batch in the process. That is
+     * three's own arrangement, which builds one module-level geometry and lets every `Sprite` share it.
+     *
+     * Seeded here rather than mounted as a child element, because it is not a choice the way an atlas's
+     * quad is. A sprite is a quad, any z is flattened by the projection, and every non-quad
+     * silhouette is a matter of texture alpha. `InstancedMeshImpl` already seeds a throwaway geometry
+     * expecting R3F to replace it, and not rendering a replacement is what makes this one stand.
+     *
+     * Two consequences. Nothing may dispose it, so this class does not override `dispose`. Nothing may
+     * write its bounding sphere, so `getBoundingSphereAt` computes rather than inflating.
+     */
+    geometry = SPRITE_QUAD;
+    /** Three's own sprite algorithm, reached through a scratch object. See `RaycastingSprites`. */
+    raycasting = new RaycastingSprites();
+    /**
+     * @param params - Instance capacity. The buffers grow past it on demand.
+     */
+    constructor(params = {}) {
+        super(params);
+        // Declared by the class rather than by a caller, as `BatchedLinesImpl` declares its endpoints.
+        // The shader that reads this is the one this package writes, and keeping the name here is what
+        // stops a string contract crossing into `objects/`.
+        this.addUniforms(ANCHOR_SCHEMA);
+    }
+    /**
+     * A member's anchor. It is how far the pivot sits from the quad's middle, in unit-quad lengths, y
+     * down, and zero is the middle.
+     * @param id - The member to read.
+     * @param target - Receives the result.
+     * @returns The anchor.
+     */
+    getAnchorAt(id, target = _anchor) {
+        return this.getUniformAt(id, ANCHOR_UNIFORM, target);
+    }
+    /**
+     * Sets a member's anchor, and invalidates the bounds it decides.
+     * @param id - The member to write.
+     * @param x - How far right of the middle the pivot sits, in unit-quad lengths.
+     * @param y - How far below the middle the pivot sits, in unit-quad lengths.
+     */
+    setAnchorAt(id, x, y) {
+        this.setUniformAt(id, ANCHOR_UNIFORM, _anchor.set(x, y));
+        this.invalidateBounds();
+    }
+    /**
+     * Encloses one member: the sphere about its anchor that reaches the quad's furthest corner.
+     *
+     * The anchor is not folded into the matrix, so the matrix translation already is the center and
+     * only the radius needs correcting. That is the exact enclosing sphere for a quad pivoting about
+     * its anchor, up to the max-axis approximation `Sphere.applyMatrix4` already makes on the flat
+     * path. It also holds at every camera angle, which is what a sprite's bounds have to do.
+     *
+     * Two alternatives were rejected. Inflating the shared quad's own bounding sphere replaces a
+     * minimal sphere with a non-minimal one, needs a per-instance factor on a per-geometry field, and
+     * would propagate through every sprite batch in the process. Reading the anchor inside
+     * `InstancedMeshImpl.getBoundingSphereAt` is quad math in a class whose instances are arbitrary
+     * geometry, where `ModelContainer` is a live counter-example.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id, target) {
+        const matrix = this.getMatrixAt(id, _matrix);
+        target.center.setFromMatrixPosition(matrix);
+        target.radius = furthestCorner(this.getAnchorAt(id, _anchor)) * matrix.getMaxScaleOnAxis();
+        return target;
+    }
+    onBeforeRender(renderer, scene, camera, geometry, material, group) {
+        // Measured here rather than handed down from a scene component. The camera is what decides this
+        // value and three supplies it to this hook along with the material about to draw, so nothing has
+        // to thread a per-frame number through the components in between. `BatchedLinesImpl` writes its
+        // own resolution onto its material the same way, and for the same reason.
+        //
+        // Reading `matrixWorld` rather than a scene object keeps this class free of `space/`, and it
+        // answers under a host transform too, because whatever places the plan places this mesh with it.
+        spriteReferenceDepth(material).value = aimDepth(camera, this.matrixWorld);
+        super.onBeforeRender(renderer, scene, camera, geometry, material, group);
+    }
+    patchMaterial(material) {
+        // First, so the instancing patch wraps around it. At compile time the prologue the sprite
+        // patch reads has to be injected before that patch runs.
+        const unpatchSprite = patchSpriteMaterial(material);
+        const unpatchInstancing = super.patchMaterial(material);
+        return () => {
+            unpatchInstancing();
+            unpatchSprite();
+        };
+    }
+    /**
+     * Clears a member as it is handed out, so a reused slot keeps nothing of the one that held it. The
+     * anchor included, which a caller that writes only a matrix would otherwise inherit.
+     * @param id - The member being handed out.
+     */
+    resetInstance(id) {
+        super.resetInstance(id);
+        this.setAnchorAt(id, 0, 0);
+    }
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with the
+ * `Sprite` three puts in the catalog when the canvas mounts.
+ */
+export const BatchedSprites = extend(BatchedSpritesImpl);
+/**
+ * How far the furthest corner of a unit quad lies from its anchor.
+ *
+ * The quad spans half a unit either side of its middle, and the anchor sits `anchor` away from that
+ * middle, so the furthest reach along each axis is half a unit plus that distance.
+ * @param anchor - The anchor's offset from the middle, in unit-quad lengths.
+ * @returns The reach, in unit-quad lengths.
+ */
+function furthestCorner(anchor) {
+    return Math.hypot(0.5 + Math.abs(anchor.x), 0.5 + Math.abs(anchor.y));
+}
+/**
+ * How far the camera's own axis travels before it meets a batch's own plane, in world units.
+ *
+ * That is the depth a plan-unit size is exact at, so it is what the shader cancels the perspective
+ * divide against. It has to agree with the depth `measurePixelSize` in `space/layout-measure.ts`
+ * works at, because a caller's `onScale` rule sizes a def in plan units from the pixel size that
+ * function reports. Without controls mounted that function reads this same crossing point. With
+ * them it reads their distance to their target, and the two agree while the target sits on the
+ * plan, which is what orbiting a floor plan keeps true.
+ *
+ * The plane is the batch's own, taken from its world matrix, because a sprite batch draws at plan
+ * `z = 0` and whatever places the plan places the mesh with it.
+ * @param camera - The camera this draw uses.
+ * @param planToWorld - The batch's world matrix.
+ * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
+ */
+function aimDepth(camera, planToWorld) {
+    // A camera looks down its own negative z.
+    const direction = _direction.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
+    const normal = _normal.setFromMatrixColumn(planToWorld, 2).normalize();
+    const facing = direction.dot(normal);
+    // The camera looks along the plane and never meets it.
+    if (facing === 0)
+        return 0;
+    const eye = _eye.setFromMatrixPosition(camera.matrixWorld);
+    const depth = _origin.setFromMatrixPosition(planToWorld).sub(eye).dot(normal) / facing;
+    // Behind the camera is no measurement, so the shader keeps its plan-unit sizing instead.
+    return depth > 0 ? depth : 0;
+}
+/** The quad every sprite batch draws. One per process. See `BatchedSpritesImpl.geometry`. */
+const SPRITE_QUAD = new PlaneGeometry(1, 1);
+// Scratch, each filled and consumed within one synchronous call.
+const _anchor = new Vector2();
+const _matrix = new Matrix4();
+const _direction = new Vector3();
+const _normal = new Vector3();
+const _eye = new Vector3();
+const _origin = new Vector3();

package/dist/core/sprites/RaycastingSprites.d.ts

@@ -0,0 +1,41 @@
+import { type Object3D, Vector2 } from 'three';
+import { type RaycastHost, Raycasting } from '../instanced/Raycasting';
+/** What this sweep reads off the batch it tests, beyond what every instanced mesh offers. */
+interface RaycastHostSprites extends RaycastHost {
+    /**
+     * A member's anchor, as an offset from the quad's middle, y down.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The anchor.
+     */
+    getAnchorAt(id: number, target: Vector2): Vector2;
+}
+/**
+ * Picking for a sprite batch: each member tested as the standing quad it actually draws.
+ *
+ * A sprite is picked by where it is drawn, not by the footprint it would have lying flat, and
+ * that quad is built after projection. So the test needs the camera. three has the math in
+ * `Sprite.raycast`, and this is how a batch reaches it: one scratch sprite, placed per member. That
+ * is the arrangement `core/lines/RaycastingLines.ts` already uses with its `_line`, and for the same
+ * reason.
+ *
+ * Only `prepareInstance` differs from the instanced sweep this inherits. The whole-batch early out,
+ * the frustum-culled candidates, the visibility test and naming the member each hit belongs to are
+ * the same questions for a sprite as for a flat quad. Answering them in world space is what lets
+ * this inherit them, because three's math projects the ray through the camera and needs it there.
+ *
+ * The camera comes from the raycaster, which three sets and R3F populates, and `Sprite.raycast` reads
+ * it itself. So nothing here captures it.
+ *
+ * Three things are written per test: the scratch's position and scale, its rotation, and its
+ * center. Together they make three draw the same quad the shader draws. They do not match the
+ * shader's formula term for term. Both `SPRITE_QUAD` and three's own sprite geometry use corners at
+ * plus or minus one half on each axis. That corner set stays the same when y is negated, so the
+ * scratch's per-corner math can differ from the shader's and still trace the same four corners. See
+ * the comments below for each piece.
+ */
+export declare class RaycastingSprites extends Raycasting {
+    protected prepareInstance(host: RaycastHostSprites, objectIndex: number): Object3D;
+}
+export {};
+//# sourceMappingURL=RaycastingSprites.d.ts.map

package/dist/core/sprites/RaycastingSprites.js

@@ -0,0 +1,71 @@
+import { Matrix4, Sprite, SpriteMaterial, Vector2, Vector3 } from 'three';
+import { axisLength } from '../../utils/math';
+import { Raycasting } from '../instanced/Raycasting';
+/**
+ * Picking for a sprite batch: each member tested as the standing quad it actually draws.
+ *
+ * A sprite is picked by where it is drawn, not by the footprint it would have lying flat, and
+ * that quad is built after projection. So the test needs the camera. three has the math in
+ * `Sprite.raycast`, and this is how a batch reaches it: one scratch sprite, placed per member. That
+ * is the arrangement `core/lines/RaycastingLines.ts` already uses with its `_line`, and for the same
+ * reason.
+ *
+ * Only `prepareInstance` differs from the instanced sweep this inherits. The whole-batch early out,
+ * the frustum-culled candidates, the visibility test and naming the member each hit belongs to are
+ * the same questions for a sprite as for a flat quad. Answering them in world space is what lets
+ * this inherit them, because three's math projects the ray through the camera and needs it there.
+ *
+ * The camera comes from the raycaster, which three sets and R3F populates, and `Sprite.raycast` reads
+ * it itself. So nothing here captures it.
+ *
+ * Three things are written per test: the scratch's position and scale, its rotation, and its
+ * center. Together they make three draw the same quad the shader draws. They do not match the
+ * shader's formula term for term. Both `SPRITE_QUAD` and three's own sprite geometry use corners at
+ * plus or minus one half on each axis. That corner set stays the same when y is negated, so the
+ * scratch's per-corner math can differ from the shader's and still trace the same four corners. See
+ * the comments below for each piece.
+ */
+export class RaycastingSprites extends Raycasting {
+    prepareInstance(host, objectIndex) {
+        const matrix = host.getMatrixAt(objectIndex, _matrix);
+        // The shader takes the anchor from the instance matrix's translation and the scale from the
+        // model matrix, and a world rotation must not spin a sprite. So the scratch carries a
+        // translation and a scale and no rotation at all.
+        const planToWorld = axisLength(host.matrixWorld, 0);
+        _position.setFromMatrixPosition(matrix).applyMatrix4(host.matrixWorld);
+        _sprite.matrixWorld
+            .makeScale(planToWorld * axisLength(matrix, 0), planToWorld * axisLength(matrix, 1), 1)
+            .setPosition(_position);
+        // The plan-space rotation, read from the instance matrix alone. The shader reads this same
+        // angle from the same matrix. The rest of its formula differs from the scratch's, for the
+        // reason given in the class comment above. No separate negation here: the matrix already
+        // carries `Y_DOWN_FLIP` (see `writeImageMatrix` in `ImageInstance.tsx`), so this angle already
+        // reads the way three's y-up frame wants it.
+        const elements = matrix.elements;
+        _material.rotation = Math.atan2(elements[1], elements[0]);
+        // three's sprite center runs 0 to 1 with the middle at 0.5, and it is y up. Ours is an offset
+        // from the middle and it is y down. The flip cannot ride on a negative scale, because
+        // Sprite.raycast reads the scale through setFromMatrixScale, which returns magnitudes.
+        const anchor = host.getAnchorAt(objectIndex, _anchor);
+        _sprite.center.set(anchor.x + 0.5, 0.5 - anchor.y);
+        return _sprite;
+    }
+}
+/**
+ * The sprite every member is tested through.
+ *
+ * One object rather than one per member, for the reason the instanced sweep keeps a scratch mesh.
+ * What differs between members is the data, and three's raycast reads all of it off the object it is
+ * called on. It is never rendered, so neither its geometry nor its material holds anything to free,
+ * and its material is its own, so a test writes no state the batch is drawing with.
+ *
+ * `sizeAttenuation` stays at `SpriteMaterial`'s default of `true`, which is the behavior that leaves
+ * perspective alone to scale the quad. A sprite is sized in plan units, and constant pixel size
+ * is a caller's `onScale` rule rather than a renderer mode. Nothing exposes this flag, so the two
+ * halves cannot drift apart while that mode stays deferred.
+ */
+const _material = new SpriteMaterial();
+const _sprite = new Sprite(_material);
+const _matrix = new Matrix4();
+const _position = new Vector3();
+const _anchor = new Vector2();

package/dist/core/sprites/sprite-material.d.ts

@@ -0,0 +1,59 @@
+import { type IUniform, type Material, type WebGLProgramParametersWithUniforms } from 'three';
+import { type UniformSchemaShader } from '../InstanceUniforms';
+/**
+ * The per-instance anchor. It is how far the pivot sits from the quad's middle, in unit-quad
+ * lengths, y down. Zero is the middle and `(-0.5, -0.5)` is the top-left corner.
+ *
+ * An offset rather than three's `Sprite.center`, which runs 0 to 1 with the middle at 0.5. Zero then
+ * means centered, so a zero-filled uniform texture is already right and no default constant has to
+ * be kept in step with the shader.
+ *
+ * This file patches the material with free functions, as `instanced-material.ts` and
+ * `lines-material.ts` do. That keeps the patch out of a material component. A `TextureMaterial`
+ * must work as a flat quad or a sprite, and it must not need to know which.
+ */
+export declare const ANCHOR_UNIFORM = "anchorOffset";
+/**
+ * The per-instance uniform a sprite batch declares. There is no sprite flag beside it, because
+ * the class is the flag.
+ */
+export declare const ANCHOR_SCHEMA: UniformSchemaShader;
+/**
+ * The depth a material's sprites are drawn at, as the uniform the shader reads.
+ *
+ * One per material, created on first ask and kept for as long as the material lives. The identity
+ * is the whole point: {@link patchSpriteMaterial} binds this object into every program it compiles,
+ * and a draw writes `.value` through the same object with no recompile behind it. That is the
+ * currency `applyDim` and the scene effects already deal in.
+ *
+ * Owned here rather than handed in, so a mesh sets the depth on the material it is about to draw
+ * with, from its own render hook, instead of passing a value to a patch that runs at another time.
+ * @param material - The material to read the uniform of.
+ * @returns Its reference-depth uniform, in world units. Zero turns the correction off.
+ */
+export declare function spriteReferenceDepth(material: Material): IUniform<number>;
+/**
+ * Wraps a material so the programs it compiles draw their instances facing the camera.
+ *
+ * Installed inside the wrap an instanced draw puts on. By the time this runs, the prologue it reads
+ * is already in the shader, which is why the batch installs this one first.
+ *
+ * This also gives the material its own program cache key. three caches a compiled program under
+ * that key alone, with no way to compare shader source. A sprite compiles different GLSL than a
+ * flat draw of the same material, so without a key of its own, a sprite mesh can be handed a flat
+ * mesh's already-compiled program, and the patched shader above is silently dropped.
+ * @param material - The material the batch is about to draw with.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+export declare function patchSpriteMaterial(material: Material): () => void;
+/**
+ * Replaces three's projection chunk with the sprite projection.
+ *
+ * Does nothing until a batch's prologue is in the shader. That is the guard `applyDim` and
+ * `patchLineShader` use, and for the same reason. A material may be compiled for something that is
+ * not a sprite batch at all, and the GLSL below reads names only the prologue brings into scope.
+ * @param shader - The program parameters to edit.
+ * @returns Whether the shader was patched.
+ */
+export declare function patchSpriteShader(shader: WebGLProgramParametersWithUniforms): boolean;
+//# sourceMappingURL=sprite-material.d.ts.map

package/dist/core/sprites/sprite-material.js

@@ -0,0 +1,192 @@
+import { replaceAnchor } from '../shader-source';
+/**
+ * The per-instance anchor. It is how far the pivot sits from the quad's middle, in unit-quad
+ * lengths, y down. Zero is the middle and `(-0.5, -0.5)` is the top-left corner.
+ *
+ * An offset rather than three's `Sprite.center`, which runs 0 to 1 with the middle at 0.5. Zero then
+ * means centered, so a zero-filled uniform texture is already right and no default constant has to
+ * be kept in step with the shader.
+ *
+ * This file patches the material with free functions, as `instanced-material.ts` and
+ * `lines-material.ts` do. That keeps the patch out of a material component. A `TextureMaterial`
+ * must work as a flat quad or a sprite, and it must not need to know which.
+ */
+export const ANCHOR_UNIFORM = 'anchorOffset';
+/**
+ * The per-instance uniform a sprite batch declares. There is no sprite flag beside it, because
+ * the class is the flag.
+ */
+export const ANCHOR_SCHEMA = { vertex: { [ANCHOR_UNIFORM]: 'vec2' } };
+/**
+ * The depth a material's sprites are drawn at, as the uniform the shader reads.
+ *
+ * One per material, created on first ask and kept for as long as the material lives. The identity
+ * is the whole point: {@link patchSpriteMaterial} binds this object into every program it compiles,
+ * and a draw writes `.value` through the same object with no recompile behind it. That is the
+ * currency `applyDim` and the scene effects already deal in.
+ *
+ * Owned here rather than handed in, so a mesh sets the depth on the material it is about to draw
+ * with, from its own render hook, instead of passing a value to a patch that runs at another time.
+ * @param material - The material to read the uniform of.
+ * @returns Its reference-depth uniform, in world units. Zero turns the correction off.
+ */
+export function spriteReferenceDepth(material) {
+    const existing = referenceDepths.get(material);
+    if (existing)
+        return existing;
+    const uniform = { value: 0 };
+    referenceDepths.set(material, uniform);
+    return uniform;
+}
+/**
+ * Wraps a material so the programs it compiles draw their instances facing the camera.
+ *
+ * Installed inside the wrap an instanced draw puts on. By the time this runs, the prologue it reads
+ * is already in the shader, which is why the batch installs this one first.
+ *
+ * This also gives the material its own program cache key. three caches a compiled program under
+ * that key alone, with no way to compare shader source. A sprite compiles different GLSL than a
+ * flat draw of the same material, so without a key of its own, a sprite mesh can be handed a flat
+ * mesh's already-compiled program, and the patched shader above is silently dropped.
+ * @param material - The material the batch is about to draw with.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+export function patchSpriteMaterial(material) {
+    // Saved raw rather than bound, for the reason patchInstancedMaterial spells out. Restoring a bound
+    // copy would put a different function back, and the next draw would bind that one in turn.
+    /* eslint-disable @typescript-eslint/unbound-method -- restored verbatim; called with `.call`. */
+    const baseOnBeforeCompile = material.onBeforeCompile;
+    const baseCacheKey = material.customProgramCacheKey;
+    /* eslint-enable @typescript-eslint/unbound-method */
+    // A constant suffix is enough: unlike the instancing key, "is a sprite" is fixed by the class,
+    // with no per-draw state to encode.
+    material.customProgramCacheKey = () => `efp_sprite_${baseCacheKey.call(material)}`;
+    material.onBeforeCompile = (shader, renderer) => {
+        // The material's own uniform, so the depth the draw wrote is already in the object this binds.
+        shader.uniforms[REFERENCE_DEPTH_UNIFORM] = spriteReferenceDepth(material);
+        patchSpriteShader(shader);
+        baseOnBeforeCompile.call(material, shader, renderer);
+    };
+    return () => {
+        material.onBeforeCompile = baseOnBeforeCompile;
+        material.customProgramCacheKey = baseCacheKey;
+    };
+}
+/**
+ * Replaces three's projection chunk with the sprite projection.
+ *
+ * Does nothing until a batch's prologue is in the shader. That is the guard `applyDim` and
+ * `patchLineShader` use, and for the same reason. A material may be compiled for something that is
+ * not a sprite batch at all, and the GLSL below reads names only the prologue brings into scope.
+ * @param shader - The program parameters to edit.
+ * @returns Whether the shader was patched.
+ */
+export function patchSpriteShader(shader) {
+    const vertex = shader.vertexShader;
+    // The declaration the uniform prologue emits, not the bare name. A false positive here would
+    // rewrite a projection that has no anchor to read.
+    if (!vertex.includes(`vec2 ${ANCHOR_UNIFORM}`))
+        return false;
+    // Already patched, which is how a second compile of the same source stays harmless.
+    if (!vertex.includes(PROJECT_VERTEX))
+        return false;
+    // The uniform and the helper go above `main`, where GLSL needs them declared.
+    shader.vertexShader = replaceAnchor(`uniform float ${REFERENCE_DEPTH_UNIFORM};\n${DEPTH_SCALE}\n${vertex}`, PROJECT_VERTEX, SPRITE_PROJECT);
+    return true;
+}
+/**
+ * The depth a sprite's plan-unit size is exact at, in world units, as the shader names it.
+ *
+ * One value for the whole draw rather than one per instance, because it describes the camera and
+ * not a member. Zero leaves the perspective divide alone. Internal, because the uniform a caller
+ * writes is {@link spriteReferenceDepth} and no string has to cross with it. See {@link DEPTH_SCALE}.
+ */
+const REFERENCE_DEPTH_UNIFORM = 'spriteReferenceDepth';
+/**
+ * Every patched material's reference depth, keyed by the material. Weak, so a material that goes
+ * takes its uniform with it.
+ */
+const referenceDepths = new WeakMap();
+/**
+ * Three's projection chunk, which the sprite projection takes the place of. Replaced as an
+ * include, because three resolves includes after every `onBeforeCompile` has run.
+ */
+const PROJECT_VERTEX = /* glsl */ `#include <project_vertex>`;
+/**
+ * The sprite projection.
+ *
+ * A vertex is split into an anchor and a local 2D offset. The anchor is the instance matrix's own
+ * translation. three refuses to bake the anchor into the matrix for the same reason: a sprite
+ * pivots about its anchor, so the matrix translation has to be the anchor. The offset is the quad
+ * corner measured from that anchor, run through the instance's own linear map, then planted in the
+ * view basis instead of the plan basis.
+ *
+ * `w = 0` drops the translation, so `instanceMatrix` contributes exactly its rotation and scale.
+ * That is the quad's own 2D linear map. A flat draw applies that map in the world basis and a
+ * sprite applies the same map in the camera basis. The inner quantity is the same, so there is no
+ * ordering question between the two rotations and no angle to extract from a matrix.
+ *
+ * The anchor goes through `modelViewMatrix`, and that choice is about precision rather than about
+ * saving a multiply. three composes that matrix on the CPU in double precision, so its translation
+ * is the object measured from the camera, which is a small number. Multiplying `viewMatrix` by
+ * `modelMatrix` here instead would do the same work in float32 on two large, nearly cancelling
+ * translations. In external mode that is fatal: a MapLibre staticTransform places the plan in
+ * Mercator, where the whole world spans one unit, a venue spans about `5e-6`, and a float32 step
+ * near a coordinate of `0.5` is about `3e-8`. That leaves under two hundred distinct positions
+ * across the venue, which reads as a few pixels of jitter that moves as the camera moves. The flat
+ * path never had the problem, because three's own projection chunk uses `modelViewMatrix` too.
+ *
+ * The scale still comes from `modelMatrix`. A length has no cancellation to lose, so precision does
+ * not force the choice here. `modelViewMatrix` would give the same number, because the view matrix
+ * is rigid, so the view rotation is wasted work. That is three's own reasoning in `sprite.glsl.js`.
+ * The product with `instanceMatrix` would be wrong, because a MapLibre staticTransform rotates the
+ * plan in world space and the length of a rotated column would fold that rotation into the sprite.
+ * That transform forces uniform scale and no shear, so the first column's length is the whole
+ * conversion.
+ *
+ * This shader carries no sign for the plan's y-down convention. The instance matrix already
+ * carries it: `writeImageMatrix` in `objects/images/ImageInstance.tsx` composes `Y_DOWN_FLIP` from
+ * `space/Space.ts` into the linear part before it ever reaches this program. A sprite still has to
+ * look identical to the flat quad when the camera is straight overhead, which is what pins that
+ * flip's sign. A Storybook baseline pins the result, because this is the kind of sign that
+ * survives review and fails on screen.
+ *
+ * `mvPosition` keeps its name, because the chunks after this one read it.
+ */
+const SPRITE_PROJECT = /* glsl */ `
+  vec4 mvPosition = modelViewMatrix * instanceMatrix[ 3 ];
+
+  vec3 local = vec3( position.xy - ${ANCHOR_UNIFORM}, 0.0 );
+  vec2 offset = ( instanceMatrix * vec4( local, 0.0 ) ).xy;
+  float planToWorld = length( modelMatrix[ 0 ].xyz );
+
+  mvPosition.xy += offset.xy * planToWorld * spriteDepthScale( mvPosition.z );
+  gl_Position = projectionMatrix * mvPosition;
+`;
+/**
+ * Cancels the perspective divide, so a sprite keeps the on-screen size its plan-unit bounds ask
+ * for wherever it sits in the frame.
+ *
+ * A sprite is sized in plan units and its quad is added in view space, so the projection divides it
+ * by its own depth and a distant sprite comes out smaller. Straight overhead that is invisible,
+ * because every sprite on the plan sits at one depth. Pitch the camera and the plan spreads across
+ * a range of depths, so one scene-wide pixel size can no longer be right for all of them.
+ *
+ * `referenceDepth` is the depth that pixel size was measured at, which is where the camera's own
+ * axis crosses the plan. Scaling by `depth / referenceDepth` makes the quad grow exactly as fast as
+ * the projection shrinks it, so the two cancel. At the reference depth the factor is one, which is
+ * what keeps `bounds.size` meaning the same plan units it means today.
+ *
+ * Two cases opt out and return one. A `referenceDepth` of zero is the uninitialized value, which
+ * leaves the old behavior in place rather than dividing by it. An orthographic projection performs
+ * no divide to cancel, and `projectionMatrix[2][3]` is what tells the two apart, exactly as three's
+ * own `isPerspectiveMatrix` does.
+ */
+const DEPTH_SCALE = /* glsl */ `
+float spriteDepthScale( const in float viewZ ) {
+  bool isPerspective = projectionMatrix[ 2 ][ 3 ] == -1.0;
+  if ( !isPerspective || ${REFERENCE_DEPTH_UNIFORM} <= 0.0 ) return 1.0;
+
+  return -viewZ / ${REFERENCE_DEPTH_UNIFORM};
+}
+`;

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

@@ -49,6 +49,12 @@ import { type TextImpl } from './Text';
  * 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. */

package/dist/core/text/BatchedText.js

@@ -51,6 +51,12 @@ import { MemberTexture } from './MemberTexture';
  * Render it with {@link BatchedText}.
  */
 export 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.
+     */
+    isBatchedText = true;
     /** Per-instance uniform store, shared with {@link BatchedMeshImpl} and {@link InstancedMeshImpl}. */
     uniforms = new InstanceUniforms();
     /** The per-member transform and style rows the batch's shader draws from. */