@expofp/renderer 3.2.4 → 3.27.0

package/dist/space/VisibleRect.d.ts

@@ -0,0 +1,72 @@
+import { type Box } from '@expofp/geometry';
+/** Props for {@link VisibleRect}. */
+export interface VisibleRectProps {
+    /**
+     * The part of the canvas the plan should be framed inside, in css pixels from the canvas's
+     * top-left corner.
+     *
+     * Required, because there is no such thing as this component with nothing to do: a caller who
+     * named no rect does not render it at all, which is what keeps the default path free of a
+     * component whose every effect would return early.
+     */
+    rect: Box;
+    /** The scene's viewbox, in plan units: what "the plan fits" is measured against. */
+    viewbox: Box;
+}
+/**
+ * Frames the plan inside a sub-region of the canvas, for a host whose own UI covers the rest.
+ *
+ * **The plan is still drawn across the whole canvas.** Nothing is clipped and nothing is cropped:
+ * the frustum is *expanded*, so the strips behind a header or a bottom sheet show more of the plan
+ * than they would otherwise, while the viewbox itself is guaranteed to land inside the clear
+ * region. That is the point of doing this in the projection rather than with `gl.viewport`.
+ *
+ * **Two calls, and nothing else in the renderer knows.** The transform is a uniform scale and a
+ * translate in clip space, which is exactly what {@link PerspectiveCamera.setViewOffset} expresses
+ * when its virtual screen is *smaller* than the rendered window — the reverse of the tiled-render
+ * case it is usually reached for. Because it lands in `projectionMatrix`, picking, R3F's pointer
+ * events, frustum culling, `Space`'s coordinate conversions and the pixel-size measurement all follow it with
+ * no seam: three re-derives `view` inside every `updateProjectionMatrix()`, so it also survives
+ * R3F's per-resize `aspect` write and `Camera`'s near and far updates.
+ *
+ * The second call is for `camera-controls`, which is the one thing that does *not* read the
+ * projection: it converts a pixel drag to a world offset through `fov` and the element's height,
+ * and finds the cursor's world position for `dollyToCursor` the same way. `setViewport` exists for
+ * exactly that — it tells the controls which part of the element the image occupies — and handed
+ * the landing box it makes every one of those conversions correct, with no fork patch and no
+ * speed fudge. The box keeps the canvas's aspect by construction, which is what leaves
+ * `camera.aspect` right inside the `dollyToCursor` arithmetic.
+ *
+ * **The scale is measured against the plan, not the canvas** — see {@link framingScale}.
+ * @param props - Where to frame the plan, and what to measure the framing against.
+ * @returns Nothing; this renders no scene node.
+ */
+export declare function VisibleRect(props: VisibleRectProps): null;
+/**
+ * How far the plan has to shrink to fit inside the rect: `1` when it already does.
+ *
+ * **Measured against the plan's own footprint, not the canvas's.** Fitting the canvas into the rect
+ * would compose two contain-fits — plan into canvas, then canvas into rect — and a product of two
+ * independent minima is not the minimum the imperative renderer took over the same pair. The two
+ * agree only when the same axis binds both, and disagree in the commonest configuration there is: a
+ * wide hall on a portrait phone, where the plan already fits the clear band and fitting the canvas
+ * into it would shrink the plan by two thirds for nothing.
+ *
+ * Measured against the plan, the factorization telescopes back to what the imperative renderer
+ * computed in one step:
+ *
+ * ```
+ * fitScale · framingScale = min(W/a, H/b) · min(w/(a·fit), h/(b·fit)) = min(w/a, h/b)
+ * ```
+ *
+ * The clamp only guards a rect larger than the canvas; for a rect inside it the result is already
+ * at most `1`, because the fit leaves the plan touching at least one edge.
+ * @param rect - The region to frame the plan inside, in css pixels.
+ * @param viewbox - The scene's viewbox, in plan units.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @returns The scale, in `(0, 1]`.
+ */
+export declare function framingScale(rect: Box, viewbox: Box, width: number, height: number, dpr: number): number;
+//# sourceMappingURL=VisibleRect.d.ts.map

package/dist/space/VisibleRect.js

@@ -0,0 +1,129 @@
+import { useThree } from '@react-three/fiber';
+import { useLayoutEffect } from 'react';
+import { useCameraControls } from '../controls';
+import { isPerspective } from './camera-kind';
+import { useCanvasSize } from './canvas-size';
+import { fitScale } from './Space';
+/**
+ * Frames the plan inside a sub-region of the canvas, for a host whose own UI covers the rest.
+ *
+ * **The plan is still drawn across the whole canvas.** Nothing is clipped and nothing is cropped:
+ * the frustum is *expanded*, so the strips behind a header or a bottom sheet show more of the plan
+ * than they would otherwise, while the viewbox itself is guaranteed to land inside the clear
+ * region. That is the point of doing this in the projection rather than with `gl.viewport`.
+ *
+ * **Two calls, and nothing else in the renderer knows.** The transform is a uniform scale and a
+ * translate in clip space, which is exactly what {@link PerspectiveCamera.setViewOffset} expresses
+ * when its virtual screen is *smaller* than the rendered window — the reverse of the tiled-render
+ * case it is usually reached for. Because it lands in `projectionMatrix`, picking, R3F's pointer
+ * events, frustum culling, `Space`'s coordinate conversions and the pixel-size measurement all follow it with
+ * no seam: three re-derives `view` inside every `updateProjectionMatrix()`, so it also survives
+ * R3F's per-resize `aspect` write and `Camera`'s near and far updates.
+ *
+ * The second call is for `camera-controls`, which is the one thing that does *not* read the
+ * projection: it converts a pixel drag to a world offset through `fov` and the element's height,
+ * and finds the cursor's world position for `dollyToCursor` the same way. `setViewport` exists for
+ * exactly that — it tells the controls which part of the element the image occupies — and handed
+ * the landing box it makes every one of those conversions correct, with no fork patch and no
+ * speed fudge. The box keeps the canvas's aspect by construction, which is what leaves
+ * `camera.aspect` right inside the `dollyToCursor` arithmetic.
+ *
+ * **The scale is measured against the plan, not the canvas** — see {@link framingScale}.
+ * @param props - Where to frame the plan, and what to measure the framing against.
+ * @returns Nothing; this renders no scene node.
+ */
+export function VisibleRect(props) {
+    const { rect, viewbox } = props;
+    const invalidate = useThree((state) => state.invalidate);
+    // Held rather than identified. `Camera` keeps only its camera's uuid because it *assigns* to
+    // fields of it and the React Compiler refuses to lower that; everything here is a method call,
+    // which the compiler is content with — so the dependency can be the camera itself and the effect
+    // needs no second read to find it.
+    const camera = useThree((state) => state.camera);
+    const controls = useCameraControls();
+    const { width, height, dpr } = useCanvasSize();
+    // Derived during render and depended on as three numbers, so a caller handing over a fresh `Box`
+    // each render — a MobX computed, say — does not re-place the framing for an unchanged rect.
+    const scale = framingScale(rect, viewbox, width, height, dpr);
+    const centerX = rect.center.x;
+    const centerY = rect.center.y;
+    useLayoutEffect(() => {
+        if (!isPerspective(camera))
+            return undefined;
+        if (width <= 0 || height <= 0)
+            return undefined;
+        // Nothing to place: a rect the plan already fills, sat in the middle of the canvas, works out to
+        // the identity, and leaving the camera untouched says so.
+        if (scale === 1 && centerX === width / 2 && centerY === height / 2)
+            return undefined;
+        placeFraming(camera, controls, scale, centerX, centerY, width, height);
+        invalidate();
+        return () => {
+            camera.clearViewOffset();
+            controls?.setViewport(null, 0, 0, 0);
+            invalidate();
+        };
+    }, [scale, centerX, centerY, width, height, camera, controls, invalidate]);
+    return null;
+}
+/**
+ * How far the plan has to shrink to fit inside the rect: `1` when it already does.
+ *
+ * **Measured against the plan's own footprint, not the canvas's.** Fitting the canvas into the rect
+ * would compose two contain-fits — plan into canvas, then canvas into rect — and a product of two
+ * independent minima is not the minimum the imperative renderer took over the same pair. The two
+ * agree only when the same axis binds both, and disagree in the commonest configuration there is: a
+ * wide hall on a portrait phone, where the plan already fits the clear band and fitting the canvas
+ * into it would shrink the plan by two thirds for nothing.
+ *
+ * Measured against the plan, the factorization telescopes back to what the imperative renderer
+ * computed in one step:
+ *
+ * ```
+ * fitScale · framingScale = min(W/a, H/b) · min(w/(a·fit), h/(b·fit)) = min(w/a, h/b)
+ * ```
+ *
+ * The clamp only guards a rect larger than the canvas; for a rect inside it the result is already
+ * at most `1`, because the fit leaves the plan touching at least one edge.
+ * @param rect - The region to frame the plan inside, in css pixels.
+ * @param viewbox - The scene's viewbox, in plan units.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ * @param dpr - Device pixels per css pixel.
+ * @returns The scale, in `(0, 1]`.
+ */
+export function framingScale(rect, viewbox, width, height, dpr) {
+    const fit = fitScale(viewbox, width * dpr, height * dpr);
+    // The plan's footprint on the canvas at zoom 1, in device pixels — the viewbox fit sizes one
+    // world unit to one device pixel, so this is the viewbox scaled and nothing more.
+    const planWidth = viewbox.size.width * fit;
+    const planHeight = viewbox.size.height * fit;
+    if (!(planWidth > 0) || !(planHeight > 0))
+        return 1;
+    return Math.min((rect.size.width * dpr) / planWidth, (rect.size.height * dpr) / planHeight, 1);
+}
+/**
+ * Writes the framing onto the camera and the controls.
+ *
+ * A function taking both rather than two statements in the effect, which is what lets the caller
+ * hold the controls from a hook: the React Compiler rejects a write to a *field of* a hook's return
+ * value and is content once that value is an argument someone else was passed.
+ *
+ * The camera call reads: the natural frustum maps to a virtual screen of `scale · canvas` css
+ * pixels, positioned so its centre lands on the rect's centre, and the canvas is the window onto
+ * it. The controls call names the same box in the element's own coordinates, `y` measured from the
+ * bottom as `setViewport` takes it.
+ * @param camera - The camera to place the framing on.
+ * @param controls - The scene's controls, when they have mounted.
+ * @param scale - How far the plan shrinks; see {@link framingScale}.
+ * @param centerX - The rect's centre, in css pixels from the canvas's left edge.
+ * @param centerY - The rect's centre, in css pixels from the canvas's top edge.
+ * @param width - The canvas width in css pixels.
+ * @param height - The canvas height in css pixels.
+ */
+function placeFraming(camera, controls, scale, centerX, centerY, width, height) {
+    const boxWidth = scale * width;
+    const boxHeight = scale * height;
+    camera.setViewOffset(boxWidth, boxHeight, boxWidth / 2 - centerX, boxHeight / 2 - centerY, width, height);
+    controls?.setViewport(centerX - boxWidth / 2, height - boxHeight / 2 - centerY, boxWidth, boxHeight);
+}

package/dist/space/camera-handle.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The camera's zoom, as the rest of the renderer asks about it.
+ *
+ * Zoom is a factor, not a distance: `1` frames the scene's viewbox exactly, `2` shows half of it.
+ * The camera stores a distance, and the two convert through the buffer height — which is why this
+ * is a handle published by {@link Camera} rather than arithmetic a caller could do itself.
+ */
+export interface CameraHandle {
+    /** The zoom factor the camera is currently at. */
+    readonly zoomFactor: number;
+    /**
+     * The camera distance that shows the plan at a zoom factor.
+     * @param zoomFactor - The factor to convert.
+     * @returns The distance in world units.
+     */
+    zoomFactorToDistance(zoomFactor: number): number;
+    /**
+     * The zoom factor a camera distance shows the plan at.
+     * @param distance - The distance in world units.
+     * @returns The factor.
+     */
+    distanceToZoomFactor(distance: number): number;
+}
+/** The scene's camera handle, published by {@link Camera}. */
+export declare const CameraContext: import("react").Context<CameraHandle | undefined>;
+/**
+ * The scene's camera handle, once {@link Camera} has published it.
+ * @returns The handle, or `undefined` when rendered outside a scene.
+ */
+export declare function useCamera(): CameraHandle | undefined;
+/**
+ * The zoom handle {@link Camera} publishes.
+ *
+ * A plain object rather than anything reactive: every member is derived from the buffer height it
+ * was built against and whatever the camera holds when it is asked, so there is no state here to go
+ * stale — only a factor and the two conversions that turn it into a distance and back.
+ *
+ * Takes a reading rather than the canvas state: the one live number it needs is how far the camera
+ * is from the plan, and asking for that instead of for the store keeps this file pure arithmetic —
+ * with no view on where a distance comes from, and nothing to import from `controls`.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param getDistance - How far the camera currently is from the plan, in world units, read at the
+ *   moment of asking.
+ * @returns The handle.
+ */
+export declare function createCameraHandle(bufferHeight: number, getDistance: () => number): CameraHandle;
+/**
+ * The camera distance at which the drawing buffer's height covers exactly that many world units —
+ * zoom factor `1`.
+ *
+ * Paired with the viewbox fit, which sizes a world unit to a device pixel, this is what "the plan
+ * fills the canvas" means as a number.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param fov - The camera's vertical field of view in degrees.
+ * @returns The distance in world units, or `0` while the buffer has no height.
+ */
+export declare function zoomIdentityDistance(bufferHeight: number, fov: number): number;
+/**
+ * The camera's vertical field of view, in degrees — `2·atan(1/3)`, the value the imperative renderer
+ * took from Mapbox.
+ *
+ * Narrow on purpose. The plan is laid out against a single pixel-to-plan factor per frame (see
+ * `readPixelSize`), which under perspective is only ever an approximation across a tilted view; the
+ * narrower the field, the closer that approximation holds.
+ */
+export declare const CAMERA_FOV = 36.87;
+//# sourceMappingURL=camera-handle.d.ts.map

package/dist/space/camera-handle.js

@@ -0,0 +1,63 @@
+import { degToRad } from '@expofp/geometry';
+import { createContext, use } from 'react';
+/** The scene's camera handle, published by {@link Camera}. */
+export const CameraContext = createContext(undefined);
+/**
+ * The scene's camera handle, once {@link Camera} has published it.
+ * @returns The handle, or `undefined` when rendered outside a scene.
+ */
+export function useCamera() {
+    return use(CameraContext);
+}
+/**
+ * The zoom handle {@link Camera} publishes.
+ *
+ * A plain object rather than anything reactive: every member is derived from the buffer height it
+ * was built against and whatever the camera holds when it is asked, so there is no state here to go
+ * stale — only a factor and the two conversions that turn it into a distance and back.
+ *
+ * Takes a reading rather than the canvas state: the one live number it needs is how far the camera
+ * is from the plan, and asking for that instead of for the store keeps this file pure arithmetic —
+ * with no view on where a distance comes from, and nothing to import from `controls`.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param getDistance - How far the camera currently is from the plan, in world units, read at the
+ *   moment of asking.
+ * @returns The handle.
+ */
+export function createCameraHandle(bufferHeight, getDistance) {
+    const identity = zoomIdentityDistance(bufferHeight, CAMERA_FOV);
+    const toZoomFactor = (distance) => identity > 0 && distance > 0 ? identity / distance : 1;
+    return {
+        get zoomFactor() {
+            return toZoomFactor(getDistance());
+        },
+        zoomFactorToDistance(zoomFactor) {
+            return zoomFactor > 0 ? identity / zoomFactor : identity;
+        },
+        distanceToZoomFactor: toZoomFactor,
+    };
+}
+/**
+ * The camera distance at which the drawing buffer's height covers exactly that many world units —
+ * zoom factor `1`.
+ *
+ * Paired with the viewbox fit, which sizes a world unit to a device pixel, this is what "the plan
+ * fills the canvas" means as a number.
+ * @param bufferHeight - The drawing buffer's height in device pixels.
+ * @param fov - The camera's vertical field of view in degrees.
+ * @returns The distance in world units, or `0` while the buffer has no height.
+ */
+export function zoomIdentityDistance(bufferHeight, fov) {
+    if (bufferHeight <= 0)
+        return 0;
+    return bufferHeight / 2 / Math.tan(degToRad(fov) / 2);
+}
+/**
+ * The camera's vertical field of view, in degrees — `2·atan(1/3)`, the value the imperative renderer
+ * took from Mapbox.
+ *
+ * Narrow on purpose. The plan is laid out against a single pixel-to-plan factor per frame (see
+ * `readPixelSize`), which under perspective is only ever an approximation across a tilted view; the
+ * narrower the field, the closer that approximation holds.
+ */
+export const CAMERA_FOV = 36.87;

package/dist/space/camera-kind.d.ts

@@ -0,0 +1,26 @@
+import { type Camera, type OrthographicCamera, type PerspectiveCamera } from 'three';
+/**
+ * Whether a camera projects perspectively.
+ *
+ * Three's own `isPerspectiveCamera` brand rather than `instanceof`, so a camera from a second copy
+ * of three — a host's, under external mode — answers the same as one of ours.
+ * @param camera - The camera to test.
+ * @returns Whether it is a perspective camera.
+ */
+export declare function isPerspective(camera: Camera): camera is PerspectiveCamera;
+/**
+ * Whether a camera projects orthographically.
+ * @param camera - The camera to test.
+ * @returns Whether it is an orthographic camera.
+ */
+export declare function isOrthographic(camera: Camera): camera is OrthographicCamera;
+/**
+ * Whether a camera derives its own projection from a frustum, rather than carrying one handed to it.
+ *
+ * The question three's `Raycaster.setFromCamera` asks before it refuses a camera, and the one
+ * `Camera.tsx` and `VisibleRect.tsx` ask before writing frustum fields nothing else has.
+ * @param camera - The camera to test.
+ * @returns Whether it projects either standard way.
+ */
+export declare function projectsFromFrustum(camera: Camera): boolean;
+//# sourceMappingURL=camera-kind.d.ts.map

package/dist/space/camera-kind.js

@@ -0,0 +1,30 @@
+/**
+ * Whether a camera projects perspectively.
+ *
+ * Three's own `isPerspectiveCamera` brand rather than `instanceof`, so a camera from a second copy
+ * of three — a host's, under external mode — answers the same as one of ours.
+ * @param camera - The camera to test.
+ * @returns Whether it is a perspective camera.
+ */
+export function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+/**
+ * Whether a camera projects orthographically.
+ * @param camera - The camera to test.
+ * @returns Whether it is an orthographic camera.
+ */
+export function isOrthographic(camera) {
+    return camera.isOrthographicCamera === true;
+}
+/**
+ * Whether a camera derives its own projection from a frustum, rather than carrying one handed to it.
+ *
+ * The question three's `Raycaster.setFromCamera` asks before it refuses a camera, and the one
+ * `Camera.tsx` and `VisibleRect.tsx` ask before writing frustum fields nothing else has.
+ * @param camera - The camera to test.
+ * @returns Whether it projects either standard way.
+ */
+export function projectsFromFrustum(camera) {
+    return isPerspective(camera) || isOrthographic(camera);
+}

package/dist/space/canvas-size.d.ts

@@ -0,0 +1,24 @@
+/** How large the canvas is, and how densely it draws. */
+export interface CanvasSize {
+    /** Width in css pixels. */
+    readonly width: number;
+    /** Height in css pixels. */
+    readonly height: number;
+    /** Device pixels per css pixel. Multiply by it for drawing-buffer sizes. */
+    readonly dpr: number;
+}
+/**
+ * The canvas's size, subscribed to one number at a time.
+ *
+ * Never read `state.size` as an object. R3F re-runs its canvas configuration on every render of the
+ * `<Canvas>` element and replaces that object as it goes, dimensions unchanged or not — so a
+ * component selecting it re-renders on renders that changed nothing, and anything memoized against
+ * it is rebuilt. Selecting the numbers is immune, because the numbers only move when the canvas
+ * really does.
+ *
+ * The returned object is a fresh literal, which costs nothing: it is not what the subscription
+ * compares, and the React Compiler keeps its identity stable across renders where the numbers hold.
+ * @returns The canvas's css size and device pixel ratio.
+ */
+export declare function useCanvasSize(): CanvasSize;
+//# sourceMappingURL=canvas-size.d.ts.map

package/dist/space/canvas-size.js

@@ -0,0 +1,20 @@
+import { useThree } from '@react-three/fiber';
+/**
+ * The canvas's size, subscribed to one number at a time.
+ *
+ * Never read `state.size` as an object. R3F re-runs its canvas configuration on every render of the
+ * `<Canvas>` element and replaces that object as it goes, dimensions unchanged or not — so a
+ * component selecting it re-renders on renders that changed nothing, and anything memoized against
+ * it is rebuilt. Selecting the numbers is immune, because the numbers only move when the canvas
+ * really does.
+ *
+ * The returned object is a fresh literal, which costs nothing: it is not what the subscription
+ * compares, and the React Compiler keeps its identity stable across renders where the numbers hold.
+ * @returns The canvas's css size and device pixel ratio.
+ */
+export function useCanvasSize() {
+    const width = useThree((state) => state.size.width);
+    const height = useThree((state) => state.size.height);
+    const dpr = useThree((state) => state.viewport.dpr);
+    return { width, height, dpr };
+}

package/dist/space/clipping.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The steepest the plan may **ever** be pitched away from face-on, in degrees.
+ *
+ * A hard cap, not a setting. The near plane below is sized against this angle: pitching the camera
+ * foreshortens an elevation along the view axis, and this is the steepest view the depth guarantee
+ * must survive, so a steeper view is one it never allowed for. `Camera` clamps `maxPitch` to it,
+ * and defaults to it.
+ *
+ * Deliberately **not** what the polygon offsets in `objects/materials` are sized against, though the
+ * imperative renderer's were (`⌈tan(maxPolarAngle)⌉`): a slope-scaled `polygonOffsetFactor` reads
+ * the actual slope per draw, so no worst-case angle enters that calculation — see `sharedParams`.
+ *
+ * In degrees, like every pitch the renderer's API talks about; the cosine the arithmetic actually
+ * wants is {@link MIN_PITCH_COSINE}, so the conversion happens once, here, and nowhere else.
+ *
+ * The imperative renderer's own limit, and the angle its depth guarantee was stated against.
+ */
+export declare const MAX_PITCH = 85;
+/**
+ * The near clipping plane that keeps depth precision at the plan constant as the camera dollies.
+ *
+ * Two constraints set it, and the larger wins so precision is never traded away for headroom:
+ *
+ * - **Headroom.** `distance × (1 − HEADROOM_RATIO)`. Dominates at close and default zoom, where it
+ *   keeps the near plane a fixed fraction of the way to the plan and precision is already better
+ *   than asked for.
+ * - **Precision.** `distance² / (levels × precision)`, the distance a depth buffer of that many
+ *   levels can still resolve at the plan. Dominates far out, where it buys the guarantee back at
+ *   the cost of some headroom.
+ *
+ * The guarantee is stated in **plan** units — see {@link ELEVATION_PRECISION} — so it is scaled
+ * into world units before the depth buffer is asked about it. The imperative renderer did not do
+ * that: it applied the plan-unit constant to world distances, which quietly loosened the guarantee
+ * on any plan drawn smaller than world scale. On a 60 000-unit plan in a 1600-pixel buffer that is a
+ * factor of 2.7 at default zoom, enough for two surfaces separated by exactly the documented minimum
+ * to z-fight.
+ *
+ * Sized against {@link MAX_PITCH} rather than against whatever pitch a scene currently allows, which
+ * is the conservative choice on purpose: the worst case is the only one that is always true, and a
+ * near plane computed from the pitch *in force* would have to be recomputed whenever that moved and
+ * would silently weaken the guarantee wherever nothing was enforcing a limit at all. What it costs
+ * is headroom, and only in the regime where {@link MIN_HEADROOM_RATIO} has already capped it.
+ * @param distance - Camera distance to the plan, in world units.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The near plane in world units, or `undefined` while the camera sits on the plan.
+ */
+export declare function nearPlane(distance: number, scale: number): number | undefined;
+/**
+ * The far plane for a camera that may pull back that far, with a factor of two spare so content
+ * behind the plan — anything at a negative elevation — is not clipped at full zoom-out.
+ * @param maxDistance - The furthest the camera may get from the plan, in world units.
+ * @returns The far plane in world units.
+ */
+export declare function farPlane(maxDistance: number): number;
+//# sourceMappingURL=clipping.d.ts.map

package/dist/space/clipping.js

@@ -0,0 +1,108 @@
+/**
+ * Where the camera's frustum begins and ends.
+ *
+ * Both planes answer the same question from opposite sides — what the camera can still draw — and
+ * they are set on different clocks: the near plane follows the camera's distance, every frame it
+ * moves, because that is what depth precision at the plan depends on; the far plane is fixed by how
+ * far the zoom bounds let the camera retreat, so it changes only when those do.
+ */
+import { degToRad } from '@expofp/geometry';
+/**
+ * The steepest the plan may **ever** be pitched away from face-on, in degrees.
+ *
+ * A hard cap, not a setting. The near plane below is sized against this angle: pitching the camera
+ * foreshortens an elevation along the view axis, and this is the steepest view the depth guarantee
+ * must survive, so a steeper view is one it never allowed for. `Camera` clamps `maxPitch` to it,
+ * and defaults to it.
+ *
+ * Deliberately **not** what the polygon offsets in `objects/materials` are sized against, though the
+ * imperative renderer's were (`⌈tan(maxPolarAngle)⌉`): a slope-scaled `polygonOffsetFactor` reads
+ * the actual slope per draw, so no worst-case angle enters that calculation — see `sharedParams`.
+ *
+ * In degrees, like every pitch the renderer's API talks about; the cosine the arithmetic actually
+ * wants is {@link MIN_PITCH_COSINE}, so the conversion happens once, here, and nowhere else.
+ *
+ * The imperative renderer's own limit, and the angle its depth guarantee was stated against.
+ */
+export const MAX_PITCH = 85;
+/**
+ * The near clipping plane that keeps depth precision at the plan constant as the camera dollies.
+ *
+ * Two constraints set it, and the larger wins so precision is never traded away for headroom:
+ *
+ * - **Headroom.** `distance × (1 − HEADROOM_RATIO)`. Dominates at close and default zoom, where it
+ *   keeps the near plane a fixed fraction of the way to the plan and precision is already better
+ *   than asked for.
+ * - **Precision.** `distance² / (levels × precision)`, the distance a depth buffer of that many
+ *   levels can still resolve at the plan. Dominates far out, where it buys the guarantee back at
+ *   the cost of some headroom.
+ *
+ * The guarantee is stated in **plan** units — see {@link ELEVATION_PRECISION} — so it is scaled
+ * into world units before the depth buffer is asked about it. The imperative renderer did not do
+ * that: it applied the plan-unit constant to world distances, which quietly loosened the guarantee
+ * on any plan drawn smaller than world scale. On a 60 000-unit plan in a 1600-pixel buffer that is a
+ * factor of 2.7 at default zoom, enough for two surfaces separated by exactly the documented minimum
+ * to z-fight.
+ *
+ * Sized against {@link MAX_PITCH} rather than against whatever pitch a scene currently allows, which
+ * is the conservative choice on purpose: the worst case is the only one that is always true, and a
+ * near plane computed from the pitch *in force* would have to be recomputed whenever that moved and
+ * would silently weaken the guarantee wherever nothing was enforcing a limit at all. What it costs
+ * is headroom, and only in the regime where {@link MIN_HEADROOM_RATIO} has already capped it.
+ * @param distance - Camera distance to the plan, in world units.
+ * @param scale - World units per plan unit, from the scene's {@link Space}.
+ * @returns The near plane in world units, or `undefined` while the camera sits on the plan.
+ */
+export function nearPlane(distance, scale) {
+    if (distance <= 0)
+        return undefined;
+    // Pitching the camera foreshortens an elevation along the view axis, so the separation the depth
+    // buffer actually sees is the plan one times the cosine.
+    const precision = ELEVATION_PRECISION * scale * MIN_PITCH_COSINE;
+    const near = (distance * distance) / (DEPTH_BUFFER_LEVELS * precision);
+    return Math.min(Math.max(near, distance * (1 - HEADROOM_RATIO)), distance * (1 - MIN_HEADROOM_RATIO));
+}
+/**
+ * The far plane for a camera that may pull back that far, with a factor of two spare so content
+ * behind the plan — anything at a negative elevation — is not clipped at full zoom-out.
+ * @param maxDistance - The furthest the camera may get from the plan, in world units.
+ * @returns The far plane in world units.
+ */
+export function farPlane(maxDistance) {
+    return Math.max(maxDistance, 0.1) * 2;
+}
+/**
+ * Minimum z-axis separation between overlapping surfaces, in **plan** units.
+ *
+ * **For plan data providers:** shapes sharing an x/y footprint — an elevated platform over a floor
+ * area, layered decorations at one position — must be separated by at least this much on z to be
+ * ordered correctly. No minimum horizontal separation is required: screen-pixel density and depth
+ * precision both scale with camera distance and with the scene's scale, so any separation visible on
+ * screen already has depth margin, at any viewport size, zoom, scale or camera rotation.
+ *
+ * Deliberately the renderer's own constant rather than `@expofp/geometry`'s `ELEVATION_TOLERANCE`,
+ * which happens to hold the same number. They answer different questions — geometry's is "are these
+ * two elevations the same point?", this one is "must these two elevations still draw in the right
+ * order?" — and importing it would let a tuning of the geometry predicate silently re-tune the depth
+ * buffer.
+ */
+const ELEVATION_PRECISION = 0.1;
+/**
+ * Fraction of the camera's distance kept clear of the near plane at close and default zoom, so
+ * depth-buffer levels are not spent on the empty space between the camera and the plan.
+ */
+const HEADROOM_RATIO = 0.98;
+/**
+ * Least headroom the precision constraint may leave. Without it a plan drawn very small — a viewbox
+ * hundreds of times the buffer — asks for a near plane beyond the camera's own target and blanks the
+ * canvas. Past this point precision degrades instead, which is visible only where two surfaces are
+ * within the documented minimum of each other.
+ */
+const MIN_HEADROOM_RATIO = 0.5;
+/** 24-bit depth buffer: 2²⁴ discrete levels, which covers 99%+ of devices. */
+const DEPTH_BUFFER_LEVELS = 2 ** 24;
+/**
+ * How much of an elevation survives being viewed at {@link MAX_PITCH} — the least of it the depth
+ * buffer ever has to resolve, and so the figure the near plane is sized against.
+ */
+const MIN_PITCH_COSINE = Math.cos(degToRad(MAX_PITCH));