@expofp/renderer 3.38.0 → 3.39.0

package/dist/objects/text/text-layout.js

@@ -54,6 +54,11 @@ export function layoutText(def) {
         const scaleX = line.fontSize;
         // Negative: the y flip. Also why the clip rect below comes out correctly ordered — dividing by a
         // negative scale swaps its min and max back.
+        //
+        // `TextImpl.orientation` looks like the right tool for this flip, but it only reaches the shader
+        // as a uniform. `BatchedTextImpl.raycast` and `isDrawn` pick and cull through `text.matrix` and
+        // its geometry's bounds on the CPU, which never read it, so using `orientation` here draws
+        // correctly and picks the wrong region.
         const scaleY = -scaleX;
         placed.push({
             anchorX: alignment.horizontal,
@@ -80,16 +85,25 @@ export function layoutText(def) {
     return placed;
 }
 /**
- * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
  * offset, the line's scale, and its clip rect.
  *
- * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
- * batch — members are not in the scene graph, so nothing else would.
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
  * @param text - The member to place.
  * @param line - The line's local placement.
  * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
  */
-export function applyPlacement(text, line, bounds) {
+export function applyPlacement(text, line, bounds, screenSpace) {
     const { rotation } = bounds;
     const position = _position
         .set(line.offsetX, line.offsetY)
@@ -98,6 +112,18 @@ export function applyPlacement(text, line, bounds) {
     text.position.set(position.x, position.y, bounds.elevation);
     text.rotation.set(0, 0, rotation);
     text.scale.set(line.scaleX, line.scaleY, 1);
+    if (screenSpace) {
+        // Mutated in place rather than replaced, so a per-update write allocates nothing.
+        const anchor = text.spriteAnchor ?? new Vector2();
+        anchor.set(bounds.center.x, bounds.center.y);
+        text.spriteAnchor = anchor;
+        // The compose owns the matrix from here. Nothing may recompose it from the three fields above.
+        text.matrixAutoUpdate = false;
+    }
+    else {
+        text.spriteAnchor = null;
+        text.matrixAutoUpdate = true;
+    }
     text.updateMatrix();
     // Held as one array for the member's life: `clipRect` is not a syncable property, so this is a
     // plain per-frame read and mutating it in place avoids a per-update allocation.

package/dist/space/Space.d.ts

@@ -307,4 +307,19 @@ export declare function castRay(raycaster: Raycaster, ndc: NDCPointLike, camera:
  * would go.
  */
 export declare const HANDEDNESS_FLIP: Matrix4;
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export declare const Y_DOWN_FLIP: Matrix4;
 //# sourceMappingURL=Space.d.ts.map

package/dist/space/Space.js

@@ -2,7 +2,7 @@ import { Point } from '@expofp/geometry';
 import { createContext, use } from 'react';
 import { Matrix4, Plane, Ray, Raycaster, Vector2, Vector3, Vector4, } from 'three';
 import { createLogger } from '../utils/logging';
-import { clamp } from '../utils/math';
+import { axisLength, clamp } from '../utils/math';
 import { projectsFromFrustum } from './camera-kind';
 const logger = createLogger('space');
 /**
@@ -302,15 +302,6 @@ export function castRay(raycaster, ndc, camera) {
         .sub(raycaster.ray.origin)
         .normalize();
 }
-/**
- * The length one unit along an axis is drawn at.
- * @param matrix - The matrix to measure.
- * @param axis - Which axis: `0` for x, `1` for y.
- * @returns The transformed axis's length.
- */
-function axisLength(matrix, axis) {
-    return new Vector3().setFromMatrixColumn(matrix, axis).length();
-}
 /**
  * The last step of both paths into world space: mirror z.
  *
@@ -330,6 +321,21 @@ function axisLength(matrix, axis) {
  * would go.
  */
 export const HANDEDNESS_FLIP = new Matrix4().makeScale(1, 1, -1);
+/**
+ * The plan's y-down convention, mirrored for a consumer that reads y as up.
+ *
+ * One value, two unrelated roles. In `ImageInstance.tsx` it is the plan-to-view y mirror composed
+ * into a screen-space quad's own 2D linear map, so the quad's offset reads correctly once the
+ * shader plants it in the view basis. In `MemberTexture.ts` it is the camera's own rest pose
+ * relative to the plan. Its job there is to stop that pose being applied twice, once baked into a
+ * member's own matrix and once more by the ordinary view transform at draw time. That role does
+ * not depend on the sign of a member's own `scale.y`. The requirement is that the billboard matrix
+ * equal the flat matrix at the rest pose, and the scale cancels from both sides of that equality.
+ *
+ * The two roles share a value by coincidence of geometry, not by a shared derivation. Check both
+ * call sites before changing this constant for either reason.
+ */
+export const Y_DOWN_FLIP = new Matrix4().makeScale(1, -1, 1);
 /** The plan's own plane in plan space, which every pointer position is reported on. */
 const PLAN_PLANE = new Plane(new Vector3(0, 0, 1), 0);
 /**

package/dist/types/defs.d.ts

@@ -75,6 +75,22 @@ export interface LayerDef<T extends RenderableDef = RenderableDef> extends Share
     readonly name: string;
     /** Collection of layer's children. Mixing different types of children is not supported. */
     children: RenderableDefCollection<T>;
+    /**
+     * Draws this layer and its subtree above 3D content. Depth testing goes off, and the layer is
+     * ordered by the overlay tier rather than by the plan tier.
+     *
+     * A layer property, and a forced one. Depth mode is per material and render order is per group, so
+     * no implementation can vary either per instance. A def-level override could not be honored even
+     * if a caller wrote one.
+     *
+     * **This is for planar content.** A volume that stops depth testing loses its own self occlusion,
+     * because its far faces then paint over its near ones in pack order. So a solid shape batch and a
+     * model batch ignore this flag. A solid batch also warns once that it did.
+     *
+     * **A descendant cannot opt back out**: three propagates a group's render order to its whole
+     * subtree, so a descendant left in the plan tier would invert the nesting.
+     */
+    overlay?: boolean;
 }
 /** Shape definition. */
 export interface ShapeDef extends SharedDef {
@@ -105,6 +121,21 @@ export interface ImageDef extends SharedDef {
      * [0, 0] is the top-left corner, [0.5, 0.5] is the center (default), [1, 1] is the bottom-right corner.
      */
     origin?: [number, number];
+    /**
+     * Faces the camera, pivoting about `bounds.center` at `bounds.elevation`, at the size `bounds.size`
+     * gives in **plan units**. That is the same meaning `bounds.size` has for a flat def. A caller that
+     * wants a constant on-screen size keeps doing what markers do today, which is an `onScale` rule
+     * that rebuilds the bounds from the pixel size.
+     *
+     * `bounds.rotation` keeps its meaning, which is a spin about the content plane's normal. For a
+     * screen-space def that plane is the screen, so there is no separate spin field. An `onRoll` rule
+     * still runs, so keep this off where the rotation carries a plan bearing. Such a def would point
+     * at one screen direction however the plan is turned.
+     *
+     * Changing this at runtime is supported. The def moves between the layer's flat mesh and its
+     * camera-facing mesh, which never touches the atlas packing.
+     */
+    screenSpace?: boolean;
 }
 /** Text definition */
 export interface TextDef extends SharedDef {
@@ -123,6 +154,12 @@ export interface TextDef extends SharedDef {
     padding: [number, number];
     /** {@link TextAlignment} object describing text's alignment */
     alignment: TextAlignment;
+    /**
+     * As `ImageDef.screenSpace`. The block faces the camera and keeps its plan anchor and its
+     * plan-unit font sizes. The whole block pivots about `bounds.center`, on one anchor shared by
+     * every line, which is what keeps a stack from splaying under tilt.
+     */
+    screenSpace?: boolean;
 }
 /** Single text line definition */
 export interface TextLineDef {

package/dist/utils/logging.d.ts

@@ -12,9 +12,12 @@ export interface Logger {
     error: Debugger;
 }
 /**
- * Creates a logger with the given namespace.
- * @param namespace - The namespace to use for the logger.
- * @returns A logger with the given namespace.
+ * Creates a logger for one namespace, nested under the root namespace.
+ *
+ * Each level prints only if you enable its namespace, for example with
+ * `debug.enable('efp:renderer:*')`.
+ * @param namespace - The namespace to nest under the root namespace.
+ * @returns A logger with four levels, all under that namespace.
  */
 export declare function createLogger(namespace: string): Logger;
 /**

package/dist/utils/logging.js

@@ -3,20 +3,28 @@ import createLog from 'debug';
 import { isLayerDefs } from '../types/guards';
 const rootNamespace = 'efp:renderer';
 /**
- * Creates a logger with the given namespace.
- * @param namespace - The namespace to use for the logger.
- * @returns A logger with the given namespace.
+ * Creates a logger for one namespace, nested under the root namespace.
+ *
+ * Each level prints only if you enable its namespace, for example with
+ * `debug.enable('efp:renderer:*')`.
+ * @param namespace - The namespace to nest under the root namespace.
+ * @returns A logger with four levels, all under that namespace.
  */
 export function createLogger(namespace) {
     const fullNamespace = namespace ? `${rootNamespace}:${namespace}` : rootNamespace;
     const info = createLog(fullNamespace);
-    info.log = console.info.bind(console);
+    // Each wrapper reads the console method at call time, not at setup time. A plain
+    // `console.warn.bind(console)` freezes the method the console object held at that
+    // moment. A test can later replace `console.warn`, for example with
+    // `vi.spyOn(console, 'warn')`. The frozen copy still calls the old method, so the
+    // spy never sees the call.
+    info.log = (...args) => console.info(...args);
     const debug = info.extend('debug');
-    debug.log = console.debug.bind(console);
+    debug.log = (...args) => console.debug(...args);
     const warn = info.extend('warn');
-    warn.log = console.warn.bind(console);
+    warn.log = (...args) => console.warn(...args);
     const error = info.extend('error');
-    error.log = console.error.bind(console);
+    error.log = (...args) => console.error(...args);
     return {
         debug,
         info,

package/dist/utils/math.d.ts

@@ -1,3 +1,4 @@
+import { type Matrix4 } from 'three';
 /**
  * Holds a value inside an inclusive range.
  *
@@ -21,4 +22,14 @@ export declare function clamp(value: number, min: number, max: number): number;
  * @returns The value in `[0, modulus)`.
  */
 export declare function euclideanModulo(value: number, modulus: number): number;
+/**
+ * The length one unit along an axis is drawn at, which is the scale the matrix applies there.
+ *
+ * Reads the elements directly rather than through a vector, because picking calls this per instance
+ * per test and a scratch vector would be one more shared object to reason about.
+ * @param matrix - The matrix to measure.
+ * @param axis - Which axis. `0` is x, `1` is y and `2` is z.
+ * @returns The transformed axis's length.
+ */
+export declare function axisLength(matrix: Matrix4, axis: number): number;
 //# sourceMappingURL=math.d.ts.map

package/dist/utils/math.js

@@ -25,3 +25,17 @@ export function clamp(value, min, max) {
 export function euclideanModulo(value, modulus) {
     return ((value % modulus) + modulus) % modulus;
 }
+/**
+ * The length one unit along an axis is drawn at, which is the scale the matrix applies there.
+ *
+ * Reads the elements directly rather than through a vector, because picking calls this per instance
+ * per test and a scratch vector would be one more shared object to reason about.
+ * @param matrix - The matrix to measure.
+ * @param axis - Which axis. `0` is x, `1` is y and `2` is z.
+ * @returns The transformed axis's length.
+ */
+export function axisLength(matrix, axis) {
+    const elements = matrix.elements;
+    const at = axis * 4;
+    return Math.hypot(elements[at], elements[at + 1], elements[at + 2]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.38.0",
+  "version": "3.39.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.38.0"
+    "@expofp/geometry": "3.39.0"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",