@expofp/renderer 3.34.1 → 3.35.0

package/dist/objects/lighting/Lighting.js

@@ -0,0 +1,385 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { degToRad } from '@expofp/geometry';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Color, Vector3, } from 'three';
+import { useSpace } from '../../space/Space';
+import { clamp } from '../../utils/math';
+import { useSceneEffects } from '../materials/effects/effects-context';
+import { useLightingGui } from './lighting-gui';
+/**
+ * Scene lighting: a hemisphere fill along the plan's up axis, and a warm directional light at a
+ * fixed pitch on the camera's heading. The one intensity control is `contrast`, and `Lighting`
+ * derives both `π`-unit intensities from it every frame — so an up-facing surface (a roof) lands on
+ * its authored color and no surface the design accounts for clips.
+ *
+ * That is also why the renderer skips tone mapping (see `Renderer.tsx` and `ExternalCanvas.tsx`): a
+ * curve brings an unbounded light sum back into range, and `contrast` keeps this rig's sum in range
+ * to begin with, at every pitch.
+ *
+ * Only lit materials see the lights — solid shape batches and models. Every 2D primitive draws
+ * through a `MeshBasicMaterial`, so lines, text and images are unaffected.
+ *
+ * **The lights sit inside the scene's world matrix**, so every direction below is in the plan's own
+ * space, taken there through {@link Space.matrixInverse}. 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 directional light needs its target under the same matrix for that, since its
+ * direction is the difference of two world positions.
+ * @param props - The values a caller set, any subset; see {@link LightingProps}.
+ * @returns The two lights, and the directional light's target.
+ */
+export function Lighting(props) {
+    const { contrast, skyColor, groundColor, directionalColor } = props;
+    // Down to the primitives here rather than in the effect below, so the effect runs when a value
+    // really moved. A caller writing `lighting={{ shadow: {...} }}` inline hands a fresh object every
+    // render, and an object in the dependency list would re-apply and redraw on each of them.
+    const { color: shadowColor, contactDistance, contactStrength, ambientOcclusion, aoRadius, aoStrength, } = props.shadow ?? {};
+    const fillRef = useRef(null);
+    const directionalRef = useRef(null);
+    const targetRef = useRef(null);
+    const space = useSpace();
+    const effects = useSceneEffects();
+    const invalidate = useThree((state) => state.invalidate);
+    // `useState` rather than `useRef` so the render body may read it, the way `useDimPatch` holds its
+    // patch.
+    const [settings] = useState(() => ({ ...LIGHT_DEFAULTS }));
+    // What each light's color was last set from, so a hex string is parsed on change, not per frame.
+    const appliedRef = useRef({ sky: '', ground: '', directional: '' });
+    useLayoutEffect(() => {
+        directionalRef.current.target = targetRef.current;
+    }, []);
+    // The one place a prop reaches the two mutable objects the frame and the shaders read. Both are
+    // written through a function of this module rather than inline, because the React Compiler treats
+    // what a hook returned as frozen for the closure's own body — the discipline `useOccluder` and
+    // `OcclusionPasses` keep for their own writes.
+    useEffect(() => {
+        applyLightValues(settings, { contrast, skyColor, groundColor, directionalColor });
+        applyShadowValues(effects, {
+            color: shadowColor,
+            contactDistance,
+            contactStrength,
+            ambientOcclusion,
+            aoRadius,
+            aoStrength,
+        });
+        // Nothing here re-renders and nothing here draws: the frame reads the rig and the shaders read
+        // the uniforms, so a change needs a frame asking for it.
+        invalidate();
+    }, [
+        settings,
+        effects,
+        invalidate,
+        contrast,
+        skyColor,
+        groundColor,
+        directionalColor,
+        shadowColor,
+        contactDistance,
+        contactStrength,
+        ambientOcclusion,
+        aoRadius,
+        aoStrength,
+    ]);
+    // Built here because `Lighting` is mounted once per scene and owns the visual rig. A no-op while
+    // the debug UI is off.
+    useLightingGui(settings);
+    // Runs only on frames something already asked for, and camera movement is what asks for them.
+    useFrame((state) => {
+        const fill = fillRef.current;
+        const directional = directionalRef.current;
+        aimDirectionalLight(state.camera, space, settings, directional.position);
+        // The plan's up axis, as a point whose world position lands back on it — which is what three
+        // reads a hemisphere light's sky axis from. Recomputed rather than memoized, because the space
+        // is refitted in place and never changes identity.
+        fill.position
+            .setFromMatrixColumn(space.matrix, 2)
+            .normalize()
+            .applyMatrix4(space.matrixInverse);
+        // Here rather than as JSX props: the GUI mutates `settings` in place and asks for a redraw, not
+        // for a React render, so a prop would hold whatever the value was at mount. `applyColor` parses
+        // a hex string only when it changed, so a still rig costs three comparisons a frame.
+        applyColor(fill.color, settings.skyColor, appliedRef.current, 'sky');
+        applyColor(fill.groundColor, settings.groundColor, appliedRef.current, 'ground');
+        applyColor(directional.color, settings.directionalColor, appliedRef.current, 'directional');
+        // The pitch as aimed, not `settings.pitchDegrees`: `trackPitch` takes it from the camera instead.
+        const pitch = Math.acos(clamp(directional.position.z, -1, 1));
+        // Defensive only: the slider never leaves `0`–`1`, but a value set out of band must not hand an
+        // over-range contrast to a ceiling that assumes one.
+        const contrast = clamp(settings.contrast, 0, 1);
+        const { hemisphereIntensity, directionalIntensity } = intensitiesFromContrast(contrast, pitch, fill.color, fill.groundColor, directional.color);
+        fill.intensity = hemisphereIntensity * Math.PI;
+        directional.intensity = directionalIntensity * Math.PI;
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: fillRef, color: LIGHT_DEFAULTS.skyColor, groundColor: LIGHT_DEFAULTS.groundColor, intensity: DEFAULT_INTENSITIES.hemisphereIntensity * Math.PI }), _jsx("directionalLight", { ref: directionalRef, color: LIGHT_DEFAULTS.directionalColor, intensity: DEFAULT_INTENSITIES.directionalIntensity * Math.PI }), _jsx("object3D", { ref: targetRef })] }));
+}
+/**
+ * Writes the rig values a caller gave, and leaves every value the caller omitted as it stands.
+ *
+ * One named write per value rather than an `Object.assign`, because a destructured prop is present
+ * and `undefined` when the caller left it out, and assigning that would wipe the default under it.
+ * @param settings - The mount's own rig, written in place.
+ * @param values - What the caller gave, any subset of it.
+ */
+function applyLightValues(settings, values) {
+    if (values.contrast !== undefined)
+        settings.contrast = values.contrast;
+    if (values.skyColor !== undefined)
+        settings.skyColor = values.skyColor;
+    if (values.groundColor !== undefined)
+        settings.groundColor = values.groundColor;
+    if (values.directionalColor !== undefined)
+        settings.directionalColor = values.directionalColor;
+}
+/**
+ * Writes the darkening values a caller gave onto the scene's own effect state, and leaves every
+ * value the caller omitted as it stands.
+ *
+ * Every write lands on a uniform's `value` or on a plain field a frame callback reads, which is what
+ * lets a caller move the shade of a mounted scene with no shader recompile behind it. The lit
+ * programs captured these very objects when they were compiled.
+ *
+ * The shade is written twice on purpose. three holds a `Color` in the working space and a color
+ * controller reads a hex string, so the uniform and the string beside it are one value in two forms.
+ * @param effects - The mounted scene's own effect state, written in place.
+ * @param values - What the caller gave, any subset of it.
+ */
+function applyShadowValues(effects, values) {
+    if (values.color !== undefined) {
+        effects.shadowHex = values.color;
+        effects.shadowColor.value.set(values.color);
+    }
+    if (values.contactDistance !== undefined)
+        effects.shadowDistance.value = values.contactDistance;
+    if (values.contactStrength !== undefined)
+        effects.shadowStrength.value = values.contactStrength;
+    if (values.ambientOcclusion !== undefined)
+        effects.enabled = values.ambientOcclusion;
+    if (values.aoRadius !== undefined)
+        effects.radius = values.aoRadius;
+    if (values.aoStrength !== undefined)
+        effects.aoStrength.value = values.aoStrength;
+}
+/**
+ * Aims the directional light, in the plan's own space, where up is `+z`.
+ *
+ * With `trackPitch` on it copies the camera's backward axis, which is the pre-overhaul behavior.
+ * Otherwise it takes the plan heading from the camera and holds the configured pitch. A fixed pitch
+ * pins the exact-albedo surface to the up-facing one, which on a floor plan carries the brand color.
+ *
+ * **The heading comes from the camera's up axis.** The forward axis points straight down at pitch
+ * `0`, the default resting pitch, so its ground projection is zero there and the heading would be
+ * undefined. The up axis is the other way round: its ground projection is longest at pitch `0` and
+ * shortest at `MAX_PITCH`, where it is still `cos(85°)` of unit length. It never vanishes, so
+ * nothing here needs a guard, and the light turns with the plan's heading even from overhead.
+ *
+ * That reading holds in external mode too, where the camera is a decomposition of the host's own
+ * matrix rather than one this renderer placed: `setExternalCameraProjection` measures the roll off
+ * that matrix instead of choosing an up axis, precisely so the axis means here what it means under
+ * the fit.
+ *
+ * The ground projection points *against* the heading. At tilt `θ` the camera's up axis is
+ * `(-cos θ · heading, sin θ)`, so negating recovers the direction the camera is on.
+ * @param camera - The scene camera.
+ * @param space - The scene's space, for the plan-to-world mapping.
+ * @param settings - The rig, for `trackPitch` and the pitch.
+ * @param target - Receives the direction.
+ * @returns `target`, unit length.
+ */
+function aimDirectionalLight(camera, space, settings, target) {
+    // Columns 1 and 2 of `matrixWorld` are the camera's up and backward axes. Read directly rather
+    // than through `Camera.getWorldDirection`, which re-runs `updateWorldMatrix` and leaves
+    // `matrixWorldNeedsUpdate` set on every call — which kept the scene dirty and no screenshot ever
+    // settled.
+    if (settings.trackPitch) {
+        return target
+            .setFromMatrixColumn(camera.matrixWorld, 2)
+            .transformDirection(space.matrixInverse);
+    }
+    const up = _up.setFromMatrixColumn(camera.matrixWorld, 1).transformDirection(space.matrixInverse);
+    const pitch = degToRad(settings.pitchDegrees);
+    return target
+        .set(-up.x, -up.y, 0)
+        .normalize()
+        .multiplyScalar(Math.sin(pitch))
+        .setZ(Math.cos(pitch));
+}
+/**
+ * Sets a light's color from a hex string, parsing only when the string changed.
+ *
+ * `Color.set` converts sRGB to the working space, and a string moves only when a color controller
+ * writes a new one.
+ * @param target - The color to write.
+ * @param hex - The CSS hex string to set it from.
+ * @param applied - What each color was last set from.
+ * @param key - Which entry of `applied` this color owns.
+ */
+function applyColor(target, hex, applied, key) {
+    if (applied[key] === hex)
+        return;
+    target.set(hex);
+    applied[key] = hex;
+}
+/**
+ * The largest directional intensity (`d`, in `π` units) a wall facing the light can take at this
+ * pitch and these colors before some channel of it clips — `contrast = 1`'s own `d`.
+ *
+ * **No closed form.** {@link intensitiesFromContrast} ties `h` to `d` through a `min` over channels,
+ * which folds a channel selection into the middle of the wall's own expression; solving that
+ * algebraically means guessing which channel governs *before* knowing `d`, and the answer can change
+ * with `d`. Bisecting sidesteps the guess entirely and is exact for any sky, ground and directional
+ * color, at the cost of a loop three's own frame budget does not notice.
+ *
+ * **The search interval's top is where `h` would reach `0`** — pure directional light, nothing from
+ * the hemisphere — which is `1 / (max_c(k_c) · cos θ)`. Past it {@link intensitiesFromContrast} would
+ * have to hand back a negative hemisphere intensity, which no real light has, so the search never
+ * looks there. `litWallPeak` is monotone increasing in `d` once `h(d)` is substituted in (a fact
+ * about this rig's own shape, not something this function re-derives), so a single bisection over
+ * this interval finds the point where the lit wall reaches exactly `1`.
+ *
+ * **A shallow pitch may never reach `1` at all** — at or below `45°` a wall never receives more
+ * directional light than a roof, so raising `d` only ever pulls the wall *toward* the roof's own
+ * value, never past it. Detected by checking the interval's own top rather than by an angle test,
+ * so the same check also covers a pitch just above `45°` whose colors still cannot clip a wall within
+ * this interval. When that happens the interval's top is `d_max` outright: it is the most directional
+ * light the rig can take at all, clipping or not, so it is also the most `contrast = 1` can mean.
+ *
+ * **The ceiling falls as the pitch steepens past that point**, which reads backward on first glance:
+ * a steeper pitch sends relatively more of a fixed `d` into the wall (`sin θ` rising) and relatively
+ * less into the roof (`cos θ` falling), so less directional intensity is needed before the wall
+ * clips. `contrast = 1` is always the most the rig can take at its own pitch, but "the most" is a
+ * smaller number at a grazing pitch than at a gentle one.
+ * @param pitchRadians - The directional light's angle from the plan's up axis, as aimed.
+ * @param sky - The hemisphere's sky color, linear.
+ * @param ground - The hemisphere's ground color, linear.
+ * @param directionalColor - The directional light's color, linear.
+ * @returns The directional intensity ceiling, in `π` units.
+ */
+function maxDirectional(pitchRadians, sky, ground, directionalColor) {
+    const cos = Math.cos(pitchRadians);
+    let peakDirectionalColor = 0;
+    for (const channel of CHANNELS) {
+        peakDirectionalColor = Math.max(peakDirectionalColor, directionalColor[channel]);
+    }
+    // Guards a grazing or past-vertical pitch, where `cos` is at or below `0`: without this the
+    // interval's top would be infinite, negative, or both.
+    const ceiling = 1 / Math.max(peakDirectionalColor * cos, MIN_PEAK);
+    if (litWallPeak(ceiling, pitchRadians, sky, ground, directionalColor) < 1)
+        return ceiling;
+    let low = 0;
+    let high = ceiling;
+    for (let iteration = 0; iteration < BISECTION_ITERATIONS; iteration++) {
+        const mid = (low + high) / 2;
+        if (litWallPeak(mid, pitchRadians, sky, ground, directionalColor) < 1)
+            low = mid;
+        else
+            high = mid;
+    }
+    return (low + high) / 2;
+}
+/**
+ * The hemisphere and directional intensities, in `π` units, that pin an up-facing surface (a roof)
+ * to exactly the authored sky color on whichever channel would clip first.
+ *
+ * `d` is `contrast` of the way from `0` to {@link maxDirectional}'s own ceiling for this pitch and
+ * these colors — the normalization that gives `contrast` its fixed `0`–`1` range, in place of an
+ * intensity ratio whose usable span moved with the pitch. `h` follows by solving three's own roof
+ * expression, `h·s + d·k·cos θ`, for the value that lands each channel on exactly `1` and taking the
+ * **minimum** across channels: the same "pin the brightest channel, leave the rest a shade under"
+ * rule the roof pin has always used, read off in the other direction — the channel needing the least
+ * `h` to reach `1` is the one that would otherwise run past it, so giving every channel that same,
+ * smaller `h` leaves it exactly on `1` and the others a shade under, which reads as a faint tint
+ * rather than a lost highlight, and holds even for a tinted sky.
+ * @param contrast - `0` to `1`, already assumed in range.
+ * @param pitchRadians - The directional light's angle from the plan's up axis, as aimed.
+ * @param sky - The hemisphere's sky color, linear.
+ * @param ground - The hemisphere's ground color, linear.
+ * @param directionalColor - The directional light's color, linear.
+ * @returns The hemisphere and directional intensities, in `π` units.
+ */
+function intensitiesFromContrast(contrast, pitchRadians, sky, ground, directionalColor) {
+    const directionalIntensity = contrast * maxDirectional(pitchRadians, sky, ground, directionalColor);
+    const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor);
+    return { hemisphereIntensity, directionalIntensity };
+}
+/**
+ * The hemisphere intensity that pins a roof to exactly `1` on its brightest channel, given a
+ * directional intensity already chosen.
+ *
+ * Solving `h·s_c + d·k_c·cos θ = 1` for `h` gives one candidate per channel; the **minimum** of them
+ * is what leaves every channel at or under `1` (see {@link intensitiesFromContrast}'s own doc for
+ * why the minimum, not the maximum, is the pinning rule stated in terms of `h`).
+ * @param directionalIntensity - `d`, in `π` units.
+ * @param pitchRadians - The directional light's angle from the plan's up axis, as aimed.
+ * @param sky - The hemisphere's sky color, linear.
+ * @param directionalColor - The directional light's color, linear.
+ * @returns The hemisphere intensity, in `π` units.
+ */
+function hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor) {
+    const cos = Math.cos(pitchRadians);
+    let hemisphereIntensity = Infinity;
+    for (const channel of CHANNELS) {
+        // Guards a black sky channel, which would otherwise divide by zero. A channel that dark can
+        // never carry a meaningful hemisphere contribution anyway, so flooring the divisor costs nothing
+        // real.
+        const skyChannel = Math.max(sky[channel], MIN_SKY);
+        hemisphereIntensity = Math.min(hemisphereIntensity, (1 - directionalIntensity * directionalColor[channel] * cos) / skyChannel);
+    }
+    return hemisphereIntensity;
+}
+/**
+ * The peak channel of a wall facing the light, given a directional intensity already chosen and the
+ * hemisphere intensity that pairs with it.
+ * @param directionalIntensity - `d`, in `π` units.
+ * @param pitchRadians - The directional light's angle from the plan's up axis, as aimed.
+ * @param sky - The hemisphere's sky color, linear.
+ * @param ground - The hemisphere's ground color, linear.
+ * @param directionalColor - The directional light's color, linear.
+ * @returns The lit wall's brightest channel.
+ */
+function litWallPeak(directionalIntensity, pitchRadians, sky, ground, directionalColor) {
+    const hemisphereIntensity = hemisphereForDirectional(directionalIntensity, pitchRadians, sky, directionalColor);
+    const sin = Math.sin(pitchRadians);
+    let peak = -Infinity;
+    for (const channel of CHANNELS) {
+        const wallMix = (ground[channel] + sky[channel]) / 2;
+        peak = Math.max(peak, hemisphereIntensity * wallMix + directionalIntensity * directionalColor[channel] * sin);
+    }
+    return peak;
+}
+/**
+ * The rig this design agreed, and what each mount starts from.
+ *
+ * `contrast` is `0.7`, measured at the default `60°` pitch with these colors: the roof lands on
+ * `1.00`, the lit wall on `0.92`, the wall facing away on `0.66`, the underside on `0.49`. At
+ * `contrast = 1` the roof and the lit wall both sit on `1.00`, and the separation section 03 of the
+ * design target asks for disappears.
+ */
+const LIGHT_DEFAULTS = {
+    trackPitch: false,
+    pitchDegrees: 60,
+    contrast: 0.7,
+    skyColor: '#ffffff',
+    groundColor: '#b9c1cc',
+    directionalColor: '#fff3e6',
+};
+/** The color channels clipping is decided on, one at a time. */
+const CHANNELS = ['r', 'g', 'b'];
+/** Bisection steps {@link maxDirectional} takes — cheap on a frame, and far past the precision the GUI's own slider step can show. */
+const BISECTION_ITERATIONS = 20;
+/**
+ * The smallest sky channel {@link hemisphereForDirectional} divides by, so a black sky channel hands
+ * back a large, finite hemisphere intensity rather than `Infinity`.
+ */
+const MIN_SKY = 1e-6;
+/**
+ * The smallest `directionalColor · cos θ` peak {@link maxDirectional} divides by, so a grazing or
+ * past-vertical pitch hands back a large, finite ceiling rather than `Infinity` or a negative number.
+ */
+const MIN_PEAK = 1e-6;
+/**
+ * {@link LIGHT_DEFAULTS}' own intensities, computed once so a tree that mounts and never draws still
+ * holds a sensible rig.
+ */
+const DEFAULT_INTENSITIES = intensitiesFromContrast(LIGHT_DEFAULTS.contrast, degToRad(LIGHT_DEFAULTS.pitchDegrees), new Color(LIGHT_DEFAULTS.skyColor), new Color(LIGHT_DEFAULTS.groundColor), new Color(LIGHT_DEFAULTS.directionalColor));
+/** The camera's up axis, reused each frame so aiming allocates nothing. */
+const _up = new Vector3();

package/dist/objects/lighting/OcclusionPasses.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+/**
+ * Screen-space ambient occlusion, in three passes a frame.
+ *
+ * The prepass draws {@link OCCLUSION_LAYER} into the one target that carries the depth texture. The
+ * AO pass reads that depth and writes how closed in each fragment is. The blur pass reads that
+ * output and the same depth, and writes what the lit materials read. Both quad passes bind a target
+ * with no depth attachment, because WebGL2 leaves a draw that samples its own framebuffer undefined.
+ * See `occlusion-targets.ts` for the three targets and the two textures under them.
+ *
+ * All three run on a frustum wider than the visible one. Geometry just outside the view then still
+ * occludes what is inside it, so no seam of missing darkening runs down the screen edges.
+ *
+ * Three things switch the passes off, and each one clears `aoActive` first. The debug GUI clears
+ * `enabled`, or the `occluders` registry is empty, and both of those free the render targets. A failed
+ * `renderTargets.sync()` is a capability gate that frees nothing, because it built nothing.
+ *
+ * The default frame priority puts this after the camera, which settles at negative priorities. It also
+ * puts this before R3F's own draw, so the texture is ready before any material samples it.
+ * @returns Nothing. This renders no scene node.
+ */
+export declare function OcclusionPasses(): ReactNode;
+//# sourceMappingURL=OcclusionPasses.d.ts.map