@expofp/renderer 3.34.1 → 3.35.0

package/dist/objects/models/Models.js

@@ -5,6 +5,7 @@ import { InstancedMesh } from '../../core/instanced/InstancedMesh';
 import { sameSequence } from '../../utils/arrays';
 import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
+import { useOccluder } from '../lighting/occluder';
 import { ModelMaterial } from '../materials/ModelMaterial';
 import { loadModel } from './gltf-cache';
 import { MODEL_KINDS, ModelContainer, modelKindOf, OPACITY_UNIFORM, } from './model-container';
@@ -28,6 +29,10 @@ const logger = createLogger('models');
  */
 export function Models(props) {
     const { defs } = props;
+    // Handed to each part's mesh as a prefix of *its* members, the way `Shapes` hands one to each of
+    // its batches: a model layer is small and its meshes are few, and the scheduler sizes the next
+    // slice from what this one actually cost.
+    const mounted = props.mounted ?? defs.length;
     // The layer split two ways at once: by url, because that is what a mesh's geometry comes from,
     // and by kind, because `transparent` is a material property and a translucent copy of a model
     // therefore cannot share a mesh with an opaque one (see `modelKindOf`).
@@ -84,7 +89,7 @@ export function Models(props) {
                 const members = partition.batches[kind].get(asset.url);
                 if (!members)
                     return null;
-                return (_jsx(Fragment, { children: asset.parts.map((part) => (_jsx(ModelPartMesh, { asset: asset, part: part, defs: members, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, part.id))) }, kind));
+                return (_jsx(Fragment, { children: asset.parts.map((part) => (_jsx(ModelPartMesh, { asset: asset, part: part, defs: members, mounted: mounted, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, part.id))) }, kind));
             }) }, asset.url))) }));
 }
 /**
@@ -128,11 +133,14 @@ function emptied(previous) {
  */
 function ModelPartMesh(props) {
     const { asset, part, defs, kind, renderOrder, onKindMismatch } = props;
+    // Only the instances are staged; the container is sized and ordered from every member.
+    const mounted = props.mounted ?? defs.length;
     // Ordering is a no-op for models — their container declares it so, and the mesh depth-sorts itself
     // instead — but the hit resolution is not: `InstancedMeshExt.raycast` walks the live slots,
     // skipping deleted and hidden ones, and raycasts the real merged geometry, so a hit names the
     // model's actual triangles and the slot that drew them.
     const container = useContainer(() => new ModelContainer(asset.extents, defs.length, kind), defs);
+    const occluder = useOccluder();
     // Assigned after mount rather than passed to the constructor: the container is built once and
     // outlives every render, so it cannot close over a current callback. Nothing can fire before this
     // runs — the split that placed these defs was computed from the same opacities they mount with.
@@ -150,7 +158,15 @@ function ModelPartMesh(props) {
     // needs (see `ModelContainer.meshMatrix`); `matrixAutoUpdate` off because it is composed, not
     // decomposed from position/rotation/scale. `sortObjects` is what a depth-writing draw wants in
     // place of paint order — nearest first while opaque, farthest first once the material blends.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), matrixAutoUpdate: false, matrix: container.meshMatrix, sortObjects: true, renderOrder: renderOrder, children: [_jsx("primitive", { object: part.geometry, attach: "geometry", dispose: null }), _jsx(ModelMaterial, { source: part.material, opacityUniform: OPACITY_UNIFORM, translucent: kind === 'translucent' })] }), defs.map((def) => (_jsx(ModelInstance, { def: def, container: container }, defKey(def))))] }));
+    //
+    // The opaque mesh asks for occlusion, or a model would neither occlude nor be occluded; the
+    // translucent one stays out, because a surface you can see through must not cast full occlusion,
+    // and asks with `null` — which is also what a detaching `ref` says, so the layer number and the
+    // scene's registry are `useOccluder`'s alone.
+    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => {
+                    container.bind(mesh);
+                    occluder(kind === 'opaque' ? mesh : null);
+                }, matrixAutoUpdate: false, matrix: container.meshMatrix, sortObjects: true, renderOrder: renderOrder, children: [_jsx("primitive", { object: part.geometry, attach: "geometry", dispose: null }), _jsx(ModelMaterial, { source: part.material, opacityUniform: OPACITY_UNIFORM, translucent: kind === 'translucent' })] }), defs.slice(0, mounted).map((def) => (_jsx(ModelInstance, { def: def, container: container }, defKey(def))))] }));
 }
 /**
  * Loads one model, reporting a failure rather than rejecting — one missing model should not cost a

package/dist/objects/models/model-container.js

@@ -1,6 +1,6 @@
 import { Matrix4, Quaternion, Vector3 } from 'three';
 import { SlotContainer } from '../containers';
-import { DIM_SCHEMA } from '../materials/dim';
+import { DIM_SCHEMA } from '../materials/effects/color-dim';
 /**
  * The per-instance uniform a model mesh reads its opacity from. The container owns the name: it
  * declares the schema on bind and writes each slot's value, and hands the name to `ModelMaterial`,

package/dist/objects/shapes/Shapes.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useState } from 'react';
 import { BatchedMesh } from '../../core/batch/BatchedMesh';
 import { defKey, useContainer } from '../containers';
+import { useOccluder } from '../lighting/occluder';
 import { ColorMaterial } from '../materials/ColorMaterial';
 import { SHAPE_KINDS, ShapeContainer, shapeKindOf } from './shape-container';
 import { ShapeInstance } from './ShapeInstance';
@@ -22,6 +23,11 @@ import { ShapeInstance } from './ShapeInstance';
  */
 export function Shapes(props) {
     const { defs } = props;
+    // Handed to each batch as a prefix of *its* members rather than apportioned between them: the
+    // batches are three at most, so a slice can overshoot the scheduler's budget by that factor at
+    // worst, and the scheduler measures what a slice actually cost and sizes the next one from it.
+    // Apportioning would cost a walk of the layer's defs per render to find where the prefix falls.
+    const mounted = props.mounted ?? defs.length;
     // Held in state rather than derived each render, the same "adjust on prop change" shape `Images`
     // uses for its pack — because the split has a second trigger besides `defs`. A def's color and its
     // shape are ordinary slot writes that never re-render this component, so either one crossing a
@@ -64,7 +70,7 @@ export function Shapes(props) {
             const members = batches[kind];
             if (!members)
                 return null;
-            return (_jsx(ShapeBatch, { defs: members, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
+            return (_jsx(ShapeBatch, { defs: members, mounted: mounted, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
         }) }));
 }
 /**
@@ -92,6 +98,8 @@ function partitionShapes(defs, mounted) {
  */
 function ShapeBatch(props) {
     const { defs, kind, renderOrder, onKindMismatch } = props;
+    // Only the instances are staged; the container is sized, reserved and ordered from every member.
+    const mounted = props.mounted ?? defs.length;
     // Sized from the first render's defs; membership changes grow the mesh in place, never rebuild
     // it. The container is bookkeeping plus CPU-side template geometries, so the copy StrictMode's
     // double-invoked initializer discards and the one an unmount strands are both plain garbage.
@@ -99,6 +107,7 @@ function ShapeBatch(props) {
     // Stickiness costs this nothing: a batch mounts on the render that first fills it, so the defs
     // sizing the container are a real membership rather than the empty one it may later stand at.
     const container = useContainer(() => new ShapeContainer(defs, kind), defs);
+    const occluder = useOccluder();
     // Assigned after mount rather than passed to the constructor: the container is built once and
     // outlives every render, so it cannot close over a current callback. Nothing can fire before this
     // runs — the split that placed these defs was computed from the same colors they mount with.
@@ -116,5 +125,14 @@ function ShapeBatch(props) {
     // claimed slot — `capacity` is a frozen snapshot, so that never happens. The `ref` arrow is
     // deliberate: `ref={container.bind}` would make the React Compiler infer `container` itself as a
     // ref and reject its render-time reads.
-    return (_jsxs(_Fragment, { children: [_jsx(BatchedMesh, { args: container.capacity, ref: (mesh) => container.bind(mesh), customSort: container.customSort, renderOrder: renderOrder, children: _jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' }) }), defs.map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
+    //
+    // The opaque volumes are what the depth prepass draws, so their batch asks for occlusion: the
+    // translucent ones stay out because a surface you can see through must not cast full occlusion,
+    // and the planar ones stay out because that is what keeps ambient occlusion and the contact
+    // shadow disjoint. A batch of either of those kinds asks with `null`, which is also what a
+    // detaching `ref` says — so the layer number and the scene's registry are `useOccluder`'s alone.
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedMesh, { args: container.capacity, ref: (mesh) => {
+                    container.bind(mesh);
+                    occluder(kind === 'solid' ? mesh : null);
+                }, customSort: container.customSort, renderOrder: renderOrder, children: _jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' }) }), defs.slice(0, mounted).map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
 }

package/dist/objects/text/Texts.js

@@ -31,11 +31,13 @@ import { TextInstance } from './TextInstance';
  */
 export function Texts(props) {
     const { defs } = props;
+    // Only the instances are staged; the container is built and ordered from the whole membership.
+    const mounted = props.mounted ?? defs.length;
     const invalidate = useThree((state) => state.invalidate);
     // The container is bookkeeping only — the members and the mesh are created against R3F's object —
     // so the copy StrictMode's double-invoked initializer discards is plain garbage.
     const container = useContainer(() => new TextContainer(invalidate), defs);
     // The `ref` arrow (not `ref={container.bind}`) keeps the React Compiler from inferring `container`
     // itself as a ref and rejecting its render-time reads.
-    return (_jsxs(_Fragment, { children: [_jsx(BatchedText, { ref: (mesh) => container.bind(mesh), children: _jsx(ColorMaterial, {}) }), defs.map((def) => (_jsx(TextInstance, { def: def, container: container }, defKey(def))))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedText, { ref: (mesh) => container.bind(mesh), children: _jsx(ColorMaterial, {}) }), defs.slice(0, mounted).map((def) => (_jsx(TextInstance, { def: def, container: container }, defKey(def))))] }));
 }

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

@@ -1,7 +1,7 @@
 import { TextExt } from '../../core/text/Text';
 import { sameSequence } from '../../utils/arrays';
 import { SlotContainer } from '../containers';
-import { dimOrdered, isDimmed } from '../materials/dim';
+import { dimOrdered, isDimmed } from '../materials/effects/color-dim';
 import { LAYOUT_FONT_SIZE, LINE_HEIGHT } from './text-layout';
 /**
  * One text layer's bookkeeping: a group of members per def, and the paint order across them.

package/dist/space/Scene.d.ts

@@ -1,5 +1,6 @@
 import { type Box } from '@expofp/geometry';
 import { type ReactNode } from 'react';
+import { type LightingProps } from '../objects/lighting';
 import { type SceneDef } from '../types/defs';
 import { type CameraProps } from './Camera';
 /** Props for {@link Scene}: the scene to draw, plus the camera limits it passes straight down. */
@@ -15,6 +16,8 @@ export interface SceneProps extends CameraProps {
      * The part of the canvas the plan should be framed inside; see {@link RendererProps.visibleRect}.
      */
     visibleRect?: Box;
+    /** The lighting and darkening values a caller set; see {@link RendererProps.lighting}. */
+    lighting?: LightingProps;
     /**
      * Whether an external host owns the camera. When set, the scene mounts no {@link Camera} — and
      * with it no fit, no `visibleRect` framing and no camera commands: the view arrives from the

package/dist/space/Scene.js

@@ -6,7 +6,8 @@ import { Background } from '../objects/Background';
 import { TextureBudget, TextureBudgetContext } from '../objects/images/texture-budget';
 import { Layer } from '../objects/layer/index';
 import { createMountScheduler, MountSchedulerContext } from '../objects/layer/mount-scheduler';
-import { Lighting } from '../objects/Lighting';
+import { Lighting, OcclusionPasses } from '../objects/lighting';
+import { createSceneEffects, SceneEffectsContext, } from '../objects/materials/effects/effects-context';
 import { createLogger, printScene } from '../utils/logging';
 import { Camera } from './Camera';
 import { useCanvasSize } from './canvas-size';
@@ -26,14 +27,14 @@ const logger = createLogger('scene');
  * @returns The scene.
  */
 export function Scene(props) {
-    const { sceneDef, memoryLimit, visibleRect, external, children, ...cameraProps } = props;
+    const { sceneDef, memoryLimit, lighting, visibleRect, external, children, ...cameraProps } = props;
     const { viewbox, staticTransform } = sceneDef;
     useEffect(() => {
         if (visibleRect && staticTransform) {
             logger.warn('visibleRect is ignored for a scene with a staticTransform');
         }
     }, [visibleRect, staticTransform]);
-    const graph = (_jsx(SceneGraph, { sceneDef: sceneDef, memoryLimit: memoryLimit, children: children }));
+    const graph = (_jsx(SceneGraph, { sceneDef: sceneDef, memoryLimit: memoryLimit, lighting: lighting, children: children }));
     return (_jsx(PlanSpace, { sceneDef: sceneDef, children: external ? (graph) : (_jsxs(Camera, { ...cameraProps, children: [visibleRect && !staticTransform && _jsx(VisibleRect, { rect: visibleRect, viewbox: viewbox }), graph] })) }));
 }
 /**
@@ -78,7 +79,7 @@ function PlanSpace(props) {
  * @returns The graph.
  */
 function SceneGraph(props) {
-    const { sceneDef, memoryLimit, children } = props;
+    const { sceneDef, memoryLimit, lighting, children } = props;
     const { viewbox, staticTransform, rootLayer } = sceneDef;
     const { width, height, dpr } = useCanvasSize();
     const invalidate = useThree((state) => state.invalidate);
@@ -87,6 +88,17 @@ function SceneGraph(props) {
     // One budget for the scene's lifetime; the limit is synced rather than the budget rebuilt, so an
     // atlas's registration survives a `memoryLimit` change.
     const [budget] = useState(() => new TextureBudget(memoryLimit));
+    // One object for the scene's lifetime, published above both halves of the tree: the passes write
+    // into it and the lit materials inside the world group read it, and neither may import the other.
+    // The plan matrix uniform holds the space's own `matrixInverse`. The space recomputes that matrix
+    // in place on every refit and never replaces it, so a lit material reads the current fit with no
+    // copy, from its very first commit. Never write through `planFromWorld.value`, because the write
+    // lands in the space itself.
+    const [effects] = useState(() => {
+        const effects = createSceneEffects();
+        effects.planFromWorld.value = space.matrixInverse;
+        return effects;
+    });
     const worldRef = useRef(null);
     useLayoutEffect(() => {
         space.refit({ viewbox, width, height, dpr, staticTransform });
@@ -108,5 +120,5 @@ function SceneGraph(props) {
     useEffect(() => {
         printScene(sceneDef, logger.debug);
     }, [sceneDef]);
-    return (_jsxs(LayoutDriver, { children: [_jsxs("group", { name: "world", ref: worldRef, matrixAutoUpdate: false, matrix: space.matrix, children: [_jsx(Lighting, {}), _jsx(TextureBudgetContext, { value: budget, children: _jsx(MountSchedulerContext, { value: scheduler, children: _jsx(Layer, { layer: rootLayer, children: sceneDef.background !== undefined && _jsx(Background, { color: sceneDef.background }) }) }) })] }), children] }));
+    return (_jsx(SceneEffectsContext, { value: effects, children: _jsxs(LayoutDriver, { children: [_jsxs("group", { name: "world", ref: worldRef, matrixAutoUpdate: false, matrix: space.matrix, children: [_jsx(TextureBudgetContext, { value: budget, children: _jsx(MountSchedulerContext, { value: scheduler, children: _jsx(Layer, { layer: rootLayer, children: sceneDef.background !== undefined && _jsx(Background, { color: sceneDef.background }) }) }) }), _jsx(Lighting, { ...lighting })] }), _jsx(OcclusionPasses, {}), children] }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.34.1",
+  "version": "3.35.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.34.1"
+    "@expofp/geometry": "3.35.0"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",

package/dist/objects/Lighting.d.ts

@@ -1,20 +0,0 @@
-/**
- * Scene lighting: a hemisphere fill from above the plan plus a directional key that follows the
- * camera, so a surface square-on to the viewer is shaded by exactly its own color (see
- * {@link HALF_ALBEDO}).
- *
- * Only lit materials see any of this — solid shape batches and models. Every 2D primitive draws
- * through a `MeshBasicMaterial`, so lines, text and images are unaffected by a light no matter what
- * the scene holds. That is deliberate: a route line or a booth label has no meaningful surface
- * normal, and shading one would make its color depend on where the camera is.
- *
- * **These sit inside the scene's world matrix**, so every direction below is expressed in the plan's
- * own space and taken there through {@link Space.matrixInverse} — one inverse, shared, rather than
- * one per light. Three reads a light's direction from where it ends up in the *world*, so the two
- * transforms cancel and the light points where it was aimed under any fit. The key light needs a
- * target inside the same space for that to hold: its direction is the difference of two world
- * positions, and only a target under the same matrix cancels the fit's translation.
- * @returns The fill and key lights, and the key's target.
- */
-export declare function Lighting(): import("react").JSX.Element;
-//# sourceMappingURL=Lighting.d.ts.map

package/dist/objects/Lighting.js

@@ -1,85 +0,0 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame } from '@react-three/fiber';
-import { useLayoutEffect, useRef } from 'react';
-import { Color } from 'three';
-import { useSpace } from '../space/Space';
-/**
- * Scene lighting: a hemisphere fill from above the plan plus a directional key that follows the
- * camera, so a surface square-on to the viewer is shaded by exactly its own color (see
- * {@link HALF_ALBEDO}).
- *
- * Only lit materials see any of this — solid shape batches and models. Every 2D primitive draws
- * through a `MeshBasicMaterial`, so lines, text and images are unaffected by a light no matter what
- * the scene holds. That is deliberate: a route line or a booth label has no meaningful surface
- * normal, and shading one would make its color depend on where the camera is.
- *
- * **These sit inside the scene's world matrix**, so every direction below is expressed in the plan's
- * own space and taken there through {@link Space.matrixInverse} — one inverse, shared, rather than
- * one per light. Three reads a light's direction from where it ends up in the *world*, so the two
- * transforms cancel and the light points where it was aimed under any fit. The key light needs a
- * target inside the same space for that to hold: its direction is the difference of two world
- * positions, and only a target under the same matrix cancels the fit's translation.
- * @returns The fill and key lights, and the key's target.
- */
-export function Lighting() {
-    const fillRef = useRef(null);
-    const keyRef = useRef(null);
-    const targetRef = useRef(null);
-    const space = useSpace();
-    useLayoutEffect(() => {
-        keyRef.current.target = targetRef.current;
-    }, []);
-    // Taken from the camera's own backward axis rather than from the controls' target: only the
-    // direction matters for a directional light — the target below pins the other end — so this needs
-    // no access to `controls`, and unlike normalizing the camera's *position* it stays correct when
-    // the plan's coordinates are far from the origin, which SVG viewboxes routinely are.
-    //
-    // Column 2 of `matrixWorld` is that backward axis: where the light belongs, shining from the
-    // camera toward what it looks at. Read with `setFromMatrixColumn` rather than through
-    // `Camera.getWorldDirection`, which negates the axis and, worse, re-runs `updateWorldMatrix` —
-    // leaving the camera's `matrixWorldNeedsUpdate` set on every single call, which kept the scene
-    // perpetually dirty and no screenshot ever settled.
-    //
-    // Under the on-demand loop this runs only on frames something already asked for, and camera
-    // movement is what asks for them, so a still plan costs nothing.
-    useFrame((state) => {
-        keyRef.current.position
-            .setFromMatrixColumn(state.camera.matrixWorld, 2)
-            .transformDirection(space.matrixInverse);
-        // The plan's own up axis, as a point whose world position lands back on it — which is what three
-        // reads a hemisphere light's sky axis from. It is world -z either way, the side the camera is
-        // on: every path into world space ends with handedness flip.
-        //
-        // Computed here rather than memoized against the space because the space is refitted in place
-        // and so never changes identity — and it is four vector operations on a frame that was going to
-        // aim the key light anyway.
-        fillRef.current.position
-            .setFromMatrixColumn(space.matrix, 2)
-            .normalize()
-            .applyMatrix4(space.matrixInverse);
-    });
-    return (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: fillRef, color: LIGHT_COLOR, groundColor: GROUND_COLOR, intensity: HALF_ALBEDO }), _jsx("directionalLight", { ref: keyRef, color: LIGHT_COLOR, intensity: HALF_ALBEDO }), _jsx("object3D", { ref: targetRef })] }));
-}
-/**
- * Each light's intensity, so the two together sum to `π`.
- *
- * three's diffuse BRDF is `albedo / π`, so a light of intensity `I` reaching a surface head-on
- * contributes `I · albedo / π`. At `0.5π` each contributes half the albedo, and the pair sums to
- * exactly the albedo — a surface facing the camera therefore renders at precisely the color the plan
- * author picked, and only faces turning away darken. The key light tracks the camera and the fill's
- * sky axis points at it too, so "facing the camera" is the same set of surfaces for both.
- *
- * Two things elsewhere are load-bearing for that identity rather than cosmetic: the lit material sets
- * `ior = 1` and `specularIntensity = 0`, which drive `F0` to zero so no specular lobe pushes a facing
- * surface *above* its albedo, and `<Canvas flat>` keeps tone mapping off, which would remap the
- * result. Change either and the identity quietly stops holding.
- */
-const HALF_ALBEDO = 0.5 * Math.PI;
-/**
- * Both lights' color — one shared constant, because the {@link HALF_ALBEDO} identity is a property
- * of the pair: two halves sum back to the author's color only when they are halves of the *same*
- * color. Each light copies it on mount, so writing to a light's own color never reaches the other.
- */
-const LIGHT_COLOR = new Color('white');
-/** The fill's ground half: pure black, so the side facing away from the sky axis adds nothing. */
-const GROUND_COLOR = new Color('black');