@expofp/renderer 3.2.5 → 3.27.0

package/dist/objects/Background.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from 'react';
+import { type ColorInput } from '../types/defs';
+/** Props for {@link Background}. */
+export interface BackgroundProps {
+    /** The background color. */
+    color: ColorInput;
+}
+/**
+ * The scene's background: a screen-space quad drawn below every layer, replacing what a clear
+ * color would paint — and unlike one, dimmed with the venue. The root `Layer` renders it inside
+ * its own group, under the root layer's dim provider, so the dim reaches this material exactly as
+ * it reaches a layer's.
+ *
+ * **Screen-space in the vertex shader**, as the imperative renderer drew it: projection is
+ * replaced with the quad's own xy in clip space at the far plane, so it covers the canvas edge to
+ * edge under any camera — fit, zoom, roll, pitch — and no matrix above it is ever read.
+ *
+ * It draws through the same {@link ColorMaterial} as the layers, with one addition through the
+ * material's pre-dim hook: a quad has no batch prologue, so the per-instance dim uniform the
+ * unmodified dim patch looks for is declared here as a constant pinned to "inherit" — every
+ * fragment defers to the layer amount, which is the point.
+ *
+ * **Draw order**: `renderOrder` 0 puts it level with the first layer group, and the tie falls to
+ * `material.id` — this material is created as the root layer mounts, before the scheduler admits
+ * any leaf, so it draws first. That ordering is load-bearing: flat content writes no depth, so
+ * anything drawn after the quad simply paints over it.
+ * @param props - The color.
+ * @returns The quad.
+ */
+export declare function Background(props: BackgroundProps): ReactNode;
+//# sourceMappingURL=Background.d.ts.map

package/dist/objects/Background.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { declareBeforeMain } from '../core/shader-source';
+import { ColorMaterial } from './materials/ColorMaterial';
+import { DIM_INHERIT, DIM_UNIFORM } from './materials/dim';
+/**
+ * The scene's background: a screen-space quad drawn below every layer, replacing what a clear
+ * color would paint — and unlike one, dimmed with the venue. The root `Layer` renders it inside
+ * its own group, under the root layer's dim provider, so the dim reaches this material exactly as
+ * it reaches a layer's.
+ *
+ * **Screen-space in the vertex shader**, as the imperative renderer drew it: projection is
+ * replaced with the quad's own xy in clip space at the far plane, so it covers the canvas edge to
+ * edge under any camera — fit, zoom, roll, pitch — and no matrix above it is ever read.
+ *
+ * It draws through the same {@link ColorMaterial} as the layers, with one addition through the
+ * material's pre-dim hook: a quad has no batch prologue, so the per-instance dim uniform the
+ * unmodified dim patch looks for is declared here as a constant pinned to "inherit" — every
+ * fragment defers to the layer amount, which is the point.
+ *
+ * **Draw order**: `renderOrder` 0 puts it level with the first layer group, and the tie falls to
+ * `material.id` — this material is created as the root layer mounts, before the scheduler admits
+ * any leaf, so it draws first. That ordering is load-bearing: flat content writes no depth, so
+ * anything drawn after the quad simply paints over it.
+ * @param props - The color.
+ * @returns The quad.
+ */
+export function Background(props) {
+    // One handler for the material's life, per `ColorMaterial`'s contract for its pre-dim hook.
+    const [onBeforeCompile] = useState(() => (parameters) => {
+        parameters.vertexShader = parameters.vertexShader.replace('#include <project_vertex>', 
+        /* glsl */ `gl_Position = vec4(transformed.xy, 1.0, 1.0);`);
+        parameters.fragmentShader = declareBeforeMain(parameters.fragmentShader, 
+        /* glsl */ `const float ${DIM_UNIFORM} = ${DIM_INHERIT}.0;`);
+    });
+    return (_jsxs("mesh", { name: "background", renderOrder: 0, frustumCulled: false, children: [_jsx("planeGeometry", { args: [2, 2] }), _jsx(ColorMaterial, { color: props.color, onBeforeCompile: onBeforeCompile })] }));
+}

package/dist/objects/Lighting.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,85 @@
+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. Under the viewbox fit that axis is world -z, the
+        // side the camera is on; under a caller's own transform it is wherever that transform puts it.
+        //
+        // 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');

package/dist/objects/containers/SlotContainer.d.ts

@@ -0,0 +1,266 @@
+import { type Intersection, type Object3D } from 'three';
+import { type UniformSchemaShader } from '../../core/InstanceUniforms';
+import { type UniformValue } from '../../core/SquareDataTexture';
+import { type RenderableDef } from '../../types/defs';
+/**
+ * What a container needs from the mesh it writes into.
+ *
+ * A capability rather than a union of our mesh classes: `BatchedMeshExt`, `InstancedMeshExt`,
+ * `BatchedLinesExt` and `BatchedTextExt` share no base below `Object3D`, yet every one of them
+ * declares per-instance uniforms and hides an instance the same way — which is all a container
+ * touches generically. Everything else it reaches through its own mesh type, which the subclass
+ * names.
+ */
+export interface SlotMesh extends Object3D {
+    /**
+     * Declares per-instance uniforms, merged with whatever is already declared.
+     * @param schema - The uniforms to add.
+     */
+    addUniforms(schema: UniformSchemaShader): void;
+    /**
+     * Writes one instance's uniform.
+     * @param slot - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    setUniformAt(slot: number, name: string, value: UniformValue): void;
+    /**
+     * Shows or hides one instance.
+     * @param slot - The instance to show or hide.
+     * @param visible - Whether it draws.
+     */
+    setVisibleAt(slot: number, visible: boolean): void;
+}
+/**
+ * An entry in a mesh's render list. Every mesh's sort callback receives a list of these — the
+ * published shapes differ in what else they carry, but each entry identifies its instance by
+ * `index`, which is all a paint-order sort needs.
+ */
+export interface RenderListItem {
+    /** The instance id the entry draws. */
+    index: number;
+}
+/**
+ * One entry in the list `BatchedMesh.customSort` receives. three's published types describe only
+ * `start`, `count`, and `z`, but the runtime also passes `index` — the instance id — which is the
+ * only way a sort can map an entry back to the instance that produced it.
+ */
+export interface BatchedMeshRenderItem extends RenderListItem {
+    /** Offset of the instance's geometry in the shared draw range. */
+    start: number;
+    /** Length of the instance's geometry draw range. */
+    count: number;
+    /** Instance depth along the camera's view direction. */
+    z: number;
+}
+/** How one container differs from the default, passed up by its constructor. */
+export interface SlotContainerOptions {
+    /**
+     * The per-instance uniforms the mesh declares on {@link SlotContainer.bind}. Defaults to the dim
+     * alone, which every def type carries. A container whose mesh needs more (an image's uv region, a
+     * model's opacity) passes the merged schema rather than declaring twice: `InstanceUniforms.add`
+     * rebuilds the backing texture, so two calls would build it twice per bind.
+     */
+    schema?: UniformSchemaShader;
+    /**
+     * Sort the draw list descending, so the *first* instance drawn is the one that paints on top.
+     *
+     * For a batch whose material keeps the first fragment to reach a pixel and rejects the rest,
+     * which is how the line material stops translucent lines darkening where they overlap: there,
+     * draw order is the reverse of paint order. Slots are still labeled in paint order either way.
+     */
+    reverse?: boolean;
+}
+/**
+ * One layer's mesh bookkeeping: the bound mesh, which slot each def holds, and the paint order
+ * across them.
+ *
+ * A container is what stands between a layer's defs and one mesh. It is created during render,
+ * sized to the membership it first sees, and held in `useState` for as long as its component is
+ * mounted; the mesh itself is R3F's, constructed from the subclass's args and handed back through
+ * {@link bind}, so R3F owns its lifetime and disposal. Instances claim and release slots from their
+ * own effects, and write their type-specific state through the subclass's own methods.
+ *
+ * What lives here is everything that does not depend on which def type is drawn:
+ *
+ * - **Slot allocation**, in both directions. `slotOf` is what a paint-order pass over the layer's
+ *   defs looks each def up with, and {@link defAt} is what turns a pointer hit — which names a slot
+ *   — back into the def that drew it. Slots come from a mesh's free list, so a released slot may be
+ *   handed to a different def later; freeing by slot keeps both directions from outliving the claim
+ *   they describe.
+ * - **Paint order**, explicitly. Instance ids come from a mesh's free list, so they do not track
+ *   sibling order — a container that let slot order stand in for paint order would reorder itself
+ *   after any claim/release churn, and again under StrictMode's remount, which re-claims in reverse.
+ *   Explicit order is also what the 2D painter's algorithm needs: 2D content never writes depth, so
+ *   nothing it draws is in the buffer for the next 2D fragment to test against, and the draw list's
+ *   order is the only thing that decides overlap.
+ * - **The two fields every def type carries**, `hidden` and `dim`, through {@link setVisibleAt} and
+ *   {@link setDimAt} — which is what lets one hook drive them for every def type.
+ *
+ * A subclass supplies {@link addInstance} and {@link removeInstance}, names its mesh and def types,
+ * and adds whatever its own defs need.
+ * @template R - The per-instance resource a claim allocates against (a geometry, a texture region,
+ *   a line count); compared by identity, so a stable reference means a stable slot. `null` for a
+ *   container whose members share everything.
+ * @template M - The mesh this container writes into.
+ * @template T - The def kind the layer holds.
+ */
+export declare abstract class SlotContainer<R, M extends SlotMesh = SlotMesh, T extends RenderableDef = RenderableDef> {
+    /**
+     * Sorts a mesh's render list into paint order. Assigned straight to the mesh's `customSort` JSX
+     * prop, whose R3F-generated type leaves the value effectively unchecked — so the entry type here
+     * needs no cast against three's published one, which omits `index`.
+     *
+     * An arrow property rather than a method, because it is handed over as a bare value and a
+     * prototype method would arrive unbound.
+     * @param list - The render list, sorted in place.
+     */
+    readonly customSort: (list: RenderListItem[]) => void;
+    /**
+     * The layer's membership, in authored paint order. Kept so a def whose own dim changes can re-run
+     * the order pass without this container having re-rendered — `update(def)` reaches the instance,
+     * not here.
+     */
+    protected layerDefs: readonly T[];
+    /**
+     * Whether the layer is dimmed, which is what a def without a `dim` of its own inherits.
+     *
+     * A flag rather than the layer's amount, because the amount is the shader's business and this is
+     * only ever asked a yes-or-no question. It is also what makes an eased layer dim cheap: the order
+     * pass re-runs when the value crosses zero, not on every frame of the ease.
+     */
+    protected layerDimmed: boolean;
+    /**
+     * Whether each slot currently draws dimmed, so a dim write that does not cross the split costs
+     * nothing.
+     */
+    protected readonly dimmedBySlot: (boolean | undefined)[];
+    /**
+     * Each def's order, durable and weak — collected with the def. It outlives a slot, so a re-claim
+     * can seed the new slot's order without waiting for the next order pass.
+     */
+    private readonly orderByDef;
+    /** Each slot's place in the paint order, read by {@link customSort}. */
+    private readonly orderBySlot;
+    private readonly slotByDef;
+    private readonly defBySlot;
+    private readonly schema;
+    private readonly sortDirection;
+    /** Set by {@link bind}, which runs before any effect can claim a slot. */
+    private boundMesh;
+    /**
+     * @param options - How this container differs from the default.
+     */
+    constructor(options?: SlotContainerOptions);
+    /**
+     * The mesh every instance writes into. Undefined until {@link bind}; refs attach before passive
+     * effects run, so every claim and slot write sees it bound.
+     */
+    get mesh(): M;
+    /**
+     * Binds the mesh R3F constructed from this container's args, declaring its per-instance uniforms.
+     *
+     * Bind-once: the ref-cleanup `null` and any re-bind are ignored, because React StrictMode cycles
+     * refs (attach → cleanup → attach) around a passive effect cycle — a container that forgot its
+     * mesh there would turn {@link release} into a no-op and leak the slot when the remounted instance
+     * re-claims, and one that re-declared its uniforms would strand the values already written into
+     * them.
+     * @param mesh - The mounted mesh, or the ref-cleanup `null`.
+     */
+    bind(mesh: M | null): void;
+    /**
+     * Reserves a slot for one instance, backed by `resource`.
+     *
+     * Paint order is deliberately not a parameter: it is a property of the whole sibling list, so the
+     * component writes it for every def in one pass after each membership change (see
+     * {@link setPaintOrder}) — an instance never learns its index, which is what lets a memoized
+     * instance ignore structural re-renders entirely.
+     * @param def - The def the slot will draw; def-to-slot bookkeeping is keyed by its identity.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot index.
+     */
+    claim(def: RenderableDef, resource: R): number;
+    /**
+     * Frees a slot, and everything recorded about the claim it held.
+     * @param slot - The slot to free.
+     */
+    release(slot: number): void;
+    /**
+     * The def holding a slot — the reverse of {@link claim}.
+     * @param slot - The slot to look up, or `undefined` for a hit that named none.
+     * @returns The def, or `undefined` when the slot is free.
+     */
+    defAt(slot: number | undefined): RenderableDef | undefined;
+    /**
+     * The def an intersection with this container's mesh hit.
+     *
+     * Which field of an intersection names a slot is the container's own knowledge — `instanceId` for
+     * an instanced mesh, `batchId` for a batched one, the member id for a text batch, whose defs own
+     * several — so it is answered here rather than at each registration site.
+     * @param hit - The intersection to trace.
+     * @returns The def, or `undefined` when the hit cannot be traced to one.
+     */
+    defFromHit(hit: Intersection): RenderableDef | undefined;
+    /**
+     * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
+     * all of them.
+     * @param slot - The slot to show or hide.
+     * @param visible - Whether the instance should draw.
+     */
+    setVisibleAt(slot: number, visible: boolean): void;
+    /**
+     * Sets one instance's own dim, or clears it back to its layer's.
+     *
+     * The counterpart to {@link setVisibleAt}, and here for the same reason: `dim` is a `SharedDef`
+     * field, so `useDefSync` drives it for every def type. The raw field is passed through rather than
+     * an encoded amount, which keeps the sentinel — and the rest of the shader's contract — inside the
+     * material module that reads it.
+     * @param slot - The slot to dim.
+     * @param dim - The def's `dim`; `undefined` defers to the layer's.
+     */
+    setDimAt(slot: number, dim: number | undefined): void;
+    /**
+     * Writes an encoded dim into a slot's uniform — the part of {@link setDimAt} that knows how a slot
+     * maps onto the mesh, split out so a container whose slot spans several mesh instances overrides
+     * only that and keeps the split-crossing check above.
+     * @param slot - The slot to write.
+     * @param amount - The encoded amount, from `instanceDim`.
+     */
+    protected writeDim(slot: number, amount: number): void;
+    /**
+     * Declares the layer's membership and dim, and re-runs the order pass over them.
+     *
+     * The component calls this from an effect after each structural change — child effects run first,
+     * so every mounted instance has claimed by then. Defs that have not claimed yet are recorded
+     * anyway: a later claim seeds its slot's order from this assignment, which is what keeps a
+     * re-claim correctly ordered without React involvement.
+     * @param defs - The current membership, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs: readonly T[], layerDimmed: boolean): void;
+    /**
+     * Labels every claimed slot with its place in the layer's draw order, undimmed defs last.
+     *
+     * Overridden by a container whose mesh has no sortable draw list, where ordering means handing the
+     * mesh a rebuilt member list instead.
+     */
+    protected applyOrder(): void;
+    /**
+     * The slot a def holds, for an order pass walking the layer's defs.
+     * @param def - The def to look up.
+     * @returns The slot, or `undefined` when the def has not claimed one.
+     */
+    protected slotOf(def: RenderableDef): number | undefined;
+    /**
+     * Allocates one instance in the mesh.
+     * @param resource - The per-instance resource to allocate against.
+     * @returns The slot the mesh allocated.
+     */
+    protected abstract addInstance(resource: R): number;
+    /**
+     * Frees one instance in the mesh.
+     * @param slot - The slot to free.
+     */
+    protected abstract removeInstance(slot: number): void;
+}
+//# sourceMappingURL=SlotContainer.d.ts.map