@expofp/renderer 3.38.0 → 3.39.1

package/dist/core/text/MemberTexture.js

@@ -1,4 +1,5 @@
-import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, } from 'three';
+import { Color, DataTexture, FloatType, Frustum, Matrix4, RGBAFormat, Sphere, Vector3, } from 'three';
+import { Y_DOWN_FLIP } from '../../space/Space';
 /**
  * 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.
@@ -43,6 +44,16 @@ export class MemberTexture {
             .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.
@@ -52,6 +63,7 @@ export class MemberTexture {
             // An unsynced member has no layout to write and draws nothing either.
             if (!text?.textRenderInfo)
                 continue;
+            faceCamera(text, _basis);
             const start = memberId * FLOATS_PER_MEMBER;
             if (isDrawn(text)) {
                 this.writeMember(texData, start, text, material, batchColor);
@@ -160,6 +172,43 @@ export class MemberTexture {
         }
     }
 }
+/**
+ * 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 . 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`). Everything else is
+ * read off the member exactly as
+ * `updateMatrix` reads it. Straight overhead the basis is the identity and 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.
+ */
+function faceCamera(text, basis) {
+    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.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.
@@ -192,3 +241,8 @@ 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();

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

@@ -1,4 +1,4 @@
-import { Matrix4 } from 'three';
+import { Matrix4, type Vector2 } from 'three';
 import { Text as TroikaText, type TextMaterial } from 'troika-three-text';
 import { type BatchedTextImpl } from './BatchedText';
 /**
@@ -45,6 +45,21 @@ export declare class TextImpl extends TroikaText {
      * 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.
      *

package/dist/core/text/Text.js

@@ -45,6 +45,21 @@ export class TextImpl extends TroikaText {
      * 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.
      *

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

@@ -56,9 +56,11 @@ export function configureDerivedMaterial(derived, base, uniforms) {
     // 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.
+    // Recompile when the uniform schema changes, since that changes the generated GLSL. The whole
+    // schema, not just whether a texture exists: two batches declaring different uniforms compile
+    // different source, and three compares nothing but this key.
     const cacheKeyBase = derived.customProgramCacheKey.bind(derived);
-    derived.customProgramCacheKey = () => `efpText_${!!uniforms.texture}|${cacheKeyBase()}`;
+    derived.customProgramCacheKey = () => `efpText_${uniforms.shaderKey}|${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

package/dist/events/LayoutDriver.d.ts

@@ -14,12 +14,12 @@ export interface LayoutDriverProps {
  * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
  * costs nothing at all.
  *
- * A move starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
- * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
- * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
- * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
- * stay inside the frame callback, before three's own render, so their attribute writes upload in
- * the very frame that draws them.
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
  *
  * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
  * write them, so a zoom does not re-render a single component — which is what makes it affordable for

package/dist/events/LayoutDriver.js

@@ -5,14 +5,12 @@ import { Frustum } from 'three';
 import { useCameraControls } from '../controls';
 import { measurePixelSize, measureRoll, pixelSizeMoved } from '../space/layout-measure';
 import { useSpace } from '../space/Space';
-import { createLogger } from '../utils/logging';
 import { planFrustum } from './def-culling';
 import { createLayoutTargets, LayoutTargetsContext } from './layout-targets';
-const logger = createLogger('layout');
 /**
- * How much of a frame one drain may spend running layout rules, in milliseconds — the same budget
- * the legacy renderer's `UpdatesSystem` drained its update queue with. Small enough to leave a
- * 60fps frame its render; the backlog it leaves is carried into the next frame, visible defs first.
+ * How much of a frame one drain may spend writing laid-out defs into their slots, in milliseconds —
+ * the same budget the legacy renderer's `UpdatesSystem` drained its update queue with. Small enough
+ * to leave a 60fps frame its render; the backlog it leaves is carried into the next frame.
  */
 const LAYOUT_BUDGET_MS = 3;
 /**
@@ -25,12 +23,12 @@ const LAYOUT_BUDGET_MS = 3;
  * for: under the on-demand loop the camera's own movement is what requests them, so a still plan
  * costs nothing at all.
  *
- * A move starts a **sweep**, never a synchronous pass: each frame drains the registry's backlog for
- * at most {@link LAYOUT_BUDGET_MS}, defs inside the camera's frustum first, and asks for another
- * frame while any backlog remains — so a plan of ten thousand labels re-lays out over a handful of
- * frames instead of stalling one, and what the user is looking at is what lands first. The layouts
- * stay inside the frame callback, before three's own render, so their attribute writes upload in
- * the very frame that draws them.
+ * A move runs every stale rule at once — the cheap half — and starts a **sweep** of the writes: each
+ * frame drains the registry's write queue for at most {@link LAYOUT_BUDGET_MS}, visibility flips
+ * first and then defs inside the camera's frustum, and asks for another frame while any remain — so
+ * a plan of ten thousand labels re-writes over a handful of frames instead of stalling one, and what
+ * the user sees change lands first. The writes stay inside the frame callback, before three's own
+ * render, so they upload in the very frame that draws them.
  *
  * No React is involved in a re-layout. The handlers mutate def fields and the defs' own sync closures
  * write them, so a zoom does not re-render a single component — which is what makes it affordable for
@@ -62,7 +60,6 @@ export function LayoutDriver(props) {
         // The epsilon compares against the sweep's target size, so a camera that stopped mid-sweep does
         // not re-mark the same sweep on every one of the frames that finish it.
         if (pixelSize !== undefined && pixelSizeMoved(pixelSize, targets.pixelSize)) {
-            logger.debug(`pxToSvgScale ${+pixelSize.toFixed(3)}`);
             targets.applyScale(pixelSize);
         }
         // Roll has no epsilon — the imperative renderer swept its roll handlers on any bearing change

package/dist/events/layout-targets.d.ts

@@ -5,67 +5,68 @@ import { type LayerDef, type RenderableDef } from '../types/defs';
  * layout axes.
  *
  * Every def here declares its own `onScale` or `onRoll` — the registry never holds a handler, only
- * the value each def's rule last ran at, per axis. One registry per renderer, reached through {@link LayoutTargetsContext},
- * so two renderers showing the same defs at different zooms do not lay each other's out.
+ * the value each def's rule last ran at, per axis. One registry per renderer, reached through
+ * {@link LayoutTargetsContext}, so two renderers showing the same defs at different zooms do not lay
+ * each other's out.
  *
- * A pixel-size move is a **sweep**, not a synchronous pass: {@link applyScale} marks every registered def
- * stale and {@link drain} works the backlog off a frame's budget at a time, defs the camera can see
- * first. The shape is the legacy renderer's `UpdatesSystem` (fp-engine `core/updates.ts`), whose
- * pending/deferred queues and per-frame time budget this registry inherits — with the queue's unit
- * changed from "def whose fields moved" to "def whose layout rule must re-run".
+ * A move splits in two. **The rules all run at once**, in the frame that noticed it: they are the
+ * cheap half — arithmetic over a def's own fields — and running them together is what lets every
+ * def's *decision*, a dot's "show me now" included, exist the moment the camera moves. **The writes
+ * are a sweep**: what the rules reported changed is queued and {@link drain} carries it to the GPU a
+ * frame's budget at a time — defs whose visibility flipped first, then the rest the camera can see,
+ * then the culled. The queue's shape is the legacy renderer's `UpdatesSystem` (fp-engine
+ * `core/updates.ts`); its unit is a def whose fields moved.
  */
 export interface LayoutTargets {
     /**
-     * The pixel size the registered defs are laid out at — from the moment {@link applyScale} marks a
-     * sweep, the size defs are being *brought* to, which is what the driver's epsilon must compare
-     * against so a camera that stopped moving does not re-mark the same sweep every frame.
+     * The pixel size the registered defs are laid out at, which is what the driver's epsilon compares
+     * against.
      */
     readonly pixelSize: number;
     /**
      * The roll the registered defs are laid out at, in radians clockwise from north — the second
-     * layout axis, compared the way {@link pixelSize} is: against the sweep's target, not the last
-     * drained value.
+     * layout axis, compared the way {@link pixelSize} is.
      */
     readonly roll: number;
-    /** Whether a sweep still has defs to lay out — what makes a caller keep frames coming. */
+    /** Whether writes are still queued — what makes a caller keep frames coming. */
     readonly hasWork: boolean;
     /**
-     * Registers defs for re-layout, and lays out the ones that are not current — so a def is current
-     * from the moment it is registered, and a membership change re-lays out only what it added.
+     * Registers defs for re-layout, and lays out and writes the ones that are not current — so a def
+     * is current from the moment it is registered, and a membership change re-lays out only what it
+     * added.
      * @param defs - The defs to lay out; every one of them declares an `onScale` or an `onRoll`.
      * @returns An unregister function; it also drops whatever of these defs a sweep still queued.
      */
     register(defs: readonly RenderableDef[]): () => void;
     /**
-     * Starts a sweep: records the new pixel size and marks every registered def stale. Nothing is
-     * laid out here — that is {@link drain}'s job — so the frame that noticed the move pays only the
-     * marking. Applying again mid-sweep re-marks at the newer size, and a def the earlier sweep had
-     * not reached is simply laid out once, at that newer size: the backlog coalesces by construction.
+     * Records the new pixel size and runs every registered scale rule against it, queueing what they
+     * report changed. Nothing is written here — that is {@link drain}'s job. Applying again before
+     * the queue drains re-runs the rules at the newer size, and a queued def is written once, with
+     * whatever its fields hold by then: the writes coalesce by construction.
      * @param pixelSize - The new pixel size.
      */
     applyScale(pixelSize: number): void;
     /**
-     * Starts a roll sweep — {@link applyScale}'s counterpart on the other axis, marking only the defs that
-     * declare an `onRoll`. The two axes coalesce independently, and one {@link drain} works both off.
+     * {@link applyScale}'s counterpart on the other axis, running only the rules that declare an
+     * `onRoll`. Both axes feed the one write queue.
      * @param roll - The new roll, in radians clockwise from north.
      */
     applyRoll(roll: number): void;
     /**
-     * Works off the sweep within a frame's budget, and says whether any backlog remains — the
-     * caller's cue to ask for another frame.
+     * Writes queued defs within a frame's budget, and says whether any remain — the caller's cue to
+     * ask for another frame.
      *
-     * Two passes, in the legacy `UpdatesSystem`'s shape: the stale defs first, except that a hidden
-     * def or one the frustum rejects is *deferred* rather than laid out; then the deferred ones, with
-     * whatever budget is left. Priority is all deferral buys — every def is still laid out before the
-     * sweep ends, because whether a def draws can be exactly what its rule decides.
+     * Three passes, in priority order: defs whose rule flipped them between hidden and shown, then
+     * every other queued def, then the ones an earlier pass deferred because the frustum rejects
+     * them. A flip matters most because it is what the user sees change — a label vanishing or a dot
+     * appearing — while a resize of something already shown can wait a frame.
      *
-     * **A drain always takes at least one def**, across the two passes together, however little
-     * budget is left — including none, which is what a worker descheduled before the first check
-     * leaves. That is what makes a sweep unable to stall: each drain shortens the backlog, so the
-     * frames the driver keeps asking for eventually end it. Without the guarantee a drain can dequeue
-     * nothing, return "more to do", and be asked again on the next frame with the same result.
-     * @param frustum - The camera's frustum in plan space, when the caller has one; without it only
-     *   hidden defs are deferred.
+     * **A drain always takes at least one def**, however little budget is left — including none,
+     * which is what a worker descheduled before the first check leaves. That is what makes a sweep
+     * unable to stall: each drain shortens the queue, so the frames the driver keeps asking for
+     * eventually end it.
+     * @param frustum - The camera's frustum in plan space, when the caller has one; without it
+     *   nothing is deferred.
      * @param budgetMs - How much of the frame a call may spend. Non-positive means no limit.
      * @returns Whether defs remain for a later drain.
      */