@expofp/renderer 3.2.5 → 3.27.1

package/dist/external/ExternalCanvas.js

@@ -0,0 +1,178 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { _roots, advance, createRoot, extend } from '@react-three/fiber';
+import { StrictMode, useEffect, useEffectEvent, useRef } from 'react';
+import * as THREE from 'three';
+import { Camera, WebGLRenderer } from 'three';
+import { createLogger } from '../utils/logging';
+import { setExternalCameraProjection } from './external-camera';
+import { externalEvents } from './external-events';
+const logger = createLogger('external');
+/**
+ * `<Canvas>`'s stand-in for a host that already owns the canvas: everything the Canvas component
+ * does — boot an R3F root, configure the renderer, the events, the size — minus the one thing it
+ * cannot share, creating the canvas element. It knows nothing of the scene: `children` render into
+ * the root verbatim, so `Renderer` composes one tree and only the mount differs.
+ *
+ * The bootstrap is imperative because the host's contract is: there is no React tree to mount into
+ * until a context exists. R3F's `<Canvas>` cannot serve here — it creates and owns its own canvas
+ * element inside a wrapper it renders, and has no way to adopt a foreign one — so this takes R3F's
+ * own escape hatch for exactly that, `createRoot(canvas)`, which is all `<Canvas>` wraps anyway.
+ * It is configured once per context, while the tree re-renders through props like any other.
+ *
+ * The camera half is the mount's as well, because the host owns it: one bare camera carries
+ * whatever matrix the host handed the frame hook, decomposed into a rigid view and a projection so
+ * that everything reading a camera's transform — culling, raycasts, lighting — works unchanged.
+ * There is no viewbox fit, no controls and no camera commands; the tree above simply mounts none
+ * of them.
+ *
+ * The demand loop inverts. R3F's own `invalidate` is a no-op under `frameloop: 'never'`, so the
+ * store's copy is replaced with the host's `requestFrame` — and every host frame redraws in full,
+ * as a shared canvas requires, starting from `resetState()` so three's GL-state tracking never
+ * trusts what the host's own drawing left behind.
+ * @param props - The host's hooks, and the tree to render into the root.
+ * @returns Nothing; the tree renders on the host's canvas, not in this one.
+ */
+export function ExternalCanvas(props) {
+    const { gl, requestFrame, onFrame, children } = props;
+    // A ref rather than state: nothing renders from the root — the tree renders *into* it — and the
+    // forwarding effect always runs after this one within a commit, so it never reads it stale.
+    const mountedRef = useRef(undefined);
+    // Effect events, so the host handing over a fresh function identity neither re-bootstraps the
+    // root nor goes stale: the bootstrap captures these two, and they read the latest props.
+    const askFrame = useEffectEvent(() => requestFrame());
+    const subscribeFrames = useEffectEvent((draw) => onFrame(draw));
+    useEffect(() => {
+        const external = mountExternal(gl, askFrame, subscribeFrames);
+        mountedRef.current = external;
+        return () => {
+            mountedRef.current = undefined;
+            external?.dispose();
+        };
+    }, [gl]);
+    // The tree flows into the foreign root exactly as it would into a Canvas: every children change
+    // re-renders it, and only a context change re-bootstraps — `gl` is a dependency here for exactly
+    // that case, so a fresh root receives the tree the moment it exists.
+    useEffect(() => {
+        mountedRef.current?.render(_jsx(StrictMode, { children: children }));
+    }, [gl, children]);
+    return null;
+}
+/**
+ * Boots an R3F root on the host's canvas and wires it to the host's frame loop.
+ * @param context - The host's WebGL context.
+ * @param requestFrame - Asks the host for a frame.
+ * @param onFrame - Subscribes the per-frame draw to the host.
+ * @returns The root and its teardown, or `undefined` when the context has no usable canvas.
+ */
+function mountExternal(context, requestFrame, onFrame) {
+    const canvas = context.canvas;
+    if (!(canvas instanceof HTMLCanvasElement)) {
+        logger.warn('external mode needs a context bound to an HTMLCanvasElement');
+        return undefined;
+    }
+    // `<Canvas>` extends R3F's element catalog with the whole THREE namespace itself; a manual root
+    // has to do the same. Idempotent, and the namespace is a module the renderer already ships. The
+    // cast steps past the catalog's constructors-only typing — the namespace carries plain values
+    // too, which `extend` skips at runtime, exactly as the Canvas path relies on.
+    extend(THREE);
+    // Deliberately a bare camera: three's frustum cameras derive their projection, and this one's
+    // arrives whole from the host each frame. Marked manual so R3F's resize handling leaves it
+    // alone; both auto-updates are off because the decomposition writes every matrix by hand.
+    const camera = new Camera();
+    camera.matrixAutoUpdate = false;
+    camera.matrixWorldAutoUpdate = false;
+    camera.manual = true;
+    // Constructed bare on purpose: the plan is drawn in three's own defaults — no tonemapping, sRGB
+    // output — and anything the renderer would opine on is left unset.
+    const glRenderer = new WebGLRenderer({ canvas, context });
+    // Never clear: the host's own layers are already on the canvas when this renderer draws.
+    glRenderer.autoClear = false;
+    // The canvas is the host's, twice over. Three would write the css style along with every resize
+    // unless told otherwise each time; and R3F's unmount forces a context loss on the renderer it
+    // tears down, which on a shared context would take the host's own drawing with it.
+    const applySize = glRenderer.setSize.bind(glRenderer);
+    glRenderer.setSize = (width, height) => applySize(width, height, false);
+    glRenderer.forceContextLoss = () => undefined;
+    const measure = () => {
+        const rect = canvas.getBoundingClientRect();
+        return { width: rect.width, height: rect.height, top: rect.top, left: rect.left };
+    };
+    const root = createRoot(canvas);
+    let disposed = false;
+    let configured = false;
+    let pending;
+    let unsubscribeFrame;
+    let observer;
+    void root
+        .configure({
+        gl: glRenderer,
+        // `flat` is not an opinion here but a shield: R3F's first configure force-writes
+        // `toneMapping` onto any renderer it is handed — ACES filmic unless flat — and flat is the
+        // one value that lands on three's own default, NoToneMapping. Everything else stays as the
+        // bare constructor left it.
+        flat: true,
+        // The cast widens past R3F's frustum-camera union; `manual` above is what keeps R3F's own
+        // camera handling off it.
+        camera: camera,
+        frameloop: 'never',
+        events: externalEvents,
+        size: measure(),
+        dpr: window.devicePixelRatio,
+    })
+        .then(() => {
+        if (disposed)
+            return;
+        const store = _roots.get(canvas)?.store;
+        if (!store)
+            return;
+        // R3F's invalidate no-ops under `frameloop: 'never'`; the host owns the frames, so demand
+        // becomes a repaint request. Replaced after configure, which is what wrote the original.
+        store.setState({
+            invalidate: () => {
+                if (!disposed)
+                    requestFrame();
+            },
+        });
+        store.getState().events.connect?.(canvas);
+        unsubscribeFrame = onFrame((projectionMatrix) => {
+            if (disposed)
+                return;
+            setExternalCameraProjection(camera, projectionMatrix);
+            // Three tracks GL state it did not set; sharing a context means resetting that tracking
+            // at the start of every frame, or the host's own state reads as three's.
+            glRenderer.resetState();
+            advance(performance.now(), true, store.getState());
+        });
+        // The host resizes its own canvas; the root only has to notice. Watching the element beats a
+        // host-specific resize event, and a dpr change reaches the same handler through the resize
+        // the host performs for it. Feature-detected for the oldest WebViews the SDK still runs in —
+        // without the observer the plan still draws, at the size it mounted at.
+        if (typeof ResizeObserver === 'function') {
+            observer = new ResizeObserver(() => {
+                if (disposed)
+                    return;
+                const next = measure();
+                store.getState().setSize(next.width, next.height, next.top, next.left);
+                store.getState().setDpr(window.devicePixelRatio);
+            });
+            observer.observe(canvas);
+        }
+        configured = true;
+        if (pending !== undefined)
+            root.render(pending);
+        requestFrame();
+    });
+    return {
+        render(node) {
+            pending = node;
+            if (configured)
+                root.render(node);
+        },
+        dispose() {
+            disposed = true;
+            observer?.disconnect();
+            unsubscribeFrame?.();
+            root.unmount();
+        },
+    };
+}

package/dist/external/external-camera.d.ts

@@ -0,0 +1,17 @@
+import { type Camera } from 'three';
+/**
+ * Decomposes the host's combined world-to-clip matrix into a rigid view matrix and a projection
+ * matrix, publishing all four matrices (and their inverses) on the camera.
+ *
+ * Ported from the imperative renderer's `ExternalCameraSystem`. The split is not unique — many
+ * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
+ * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
+ * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
+ * absorbed into P, where it breaks none of those.
+ * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
+ *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
+ * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen
+ *   elements column-major.
+ */
+export declare function setExternalCameraProjection(camera: Camera, mainMatrix: ArrayLike<number>): void;
+//# sourceMappingURL=external-camera.d.ts.map

package/dist/external/external-camera.js

@@ -0,0 +1,82 @@
+import { Matrix3, Matrix4, Vector3 } from 'three';
+/**
+ * Decomposes the host's combined world-to-clip matrix into a rigid view matrix and a projection
+ * matrix, publishing all four matrices (and their inverses) on the camera.
+ *
+ * Ported from the imperative renderer's `ExternalCameraSystem`. The split is not unique — many
+ * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
+ * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
+ * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
+ * absorbed into P, where it breaks none of those.
+ * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
+ *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
+ * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen
+ *   elements column-major.
+ */
+export function setExternalCameraProjection(camera, mainMatrix) {
+    const M = _main.fromArray(mainMatrix);
+    const e = M.elements; // column-major storage: M[row, col] = e[row + 4 * col]
+    // Step 1: camera world position c.
+    //
+    // A standard perspective projection P has its fourth column equal to (0, 0, ±f, 0), so
+    // P · [0; 0; 0; 1] is zero in rows 0, 1, and 3. The view matrix V maps the camera position to
+    // view-space origin: V · [c; 1] = [0; 0; 0; 1]. Composing these:
+    //
+    //     M · [c; 1] = P · V · [c; 1] = P · [0; 0; 0; 1] = (0, 0, k, 0)
+    //
+    // so rows 0, 1, and 3 of M dotted with [c; 1] all equal zero. That is a 3×3 linear system for
+    // the three components of c, independent of NDC z conventions (standard OpenGL vs. reverse-z),
+    // so it works for both maplibre and a vanilla GL setup.
+    _system.set(e[0], e[4], e[8], e[1], e[5], e[9], e[3], e[7], e[11]);
+    _position.set(-e[12], -e[13], -e[15]).applyMatrix3(_system.invert());
+    // Step 2: view direction in world space.
+    //
+    // Unproject two world-space points along the central view ray and take their difference. The
+    // clip-space z boundaries (±1) are used rather than an interior NDC z because maplibre's
+    // projection has an infinite far plane in a reverse-z arrangement: an interior z (0 in
+    // particular) unprojects to a homogeneous direction at infinity and comes back as NaN after the
+    // w-divide. z = ±1 always produces finite points, so the subtraction is well-defined.
+    //
+    // Which of the two is the near plane depends on the projection's z convention — reverse-z under
+    // maplibre, standard under vanilla GL — so it is settled by distance to the eye recovered above:
+    // the near point is the closer one, and the view looks from it toward the other. (The imperative
+    // renderer hardcoded maplibre's ordering; measuring is what makes both conventions work.)
+    _mainInverse.copy(M).invert();
+    _near.set(0, 0, 1).applyMatrix4(_mainInverse);
+    _far.set(0, 0, -1).applyMatrix4(_mainInverse);
+    if (_near.distanceToSquared(_position) > _far.distanceToSquared(_position)) {
+        _direction.copy(_near).sub(_far).normalize();
+    }
+    else {
+        _direction.copy(_far).sub(_near).normalize();
+    }
+    // Step 3: synthesize a rigid view matrix via look-at.
+    //
+    // The choice of "up" is arbitrary as long as it is not parallel to the view direction: any
+    // non-degenerate choice yields a valid (P′, V′) pair, because P is recomputed from
+    // M · matrixWorld at the end. The fallback handles top-down or bottom-up views where world +z
+    // aligns with the view ray.
+    _up.set(0, 0, 1);
+    if (Math.abs(_up.dot(_direction)) > 0.999)
+        _up.set(0, 1, 0);
+    _target.copy(_position).add(_direction);
+    camera.matrixWorld.lookAt(_position, _target, _up);
+    camera.matrixWorld.setPosition(_position);
+    camera.matrixWorldInverse.copy(camera.matrixWorld).invert();
+    // Step 4: derive projection so that P · V = M exactly.
+    //
+    // P = M · matrixWorld, because matrixWorld = V⁻¹ and therefore P · V = (M · V⁻¹) · V = M. Any
+    // scale or skew that did not fit into the rigid V lives in P.
+    camera.projectionMatrix.multiplyMatrices(M, camera.matrixWorld);
+    camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+}
+// Scratch, reused across calls so a per-frame update allocates nothing.
+const _main = new Matrix4();
+const _mainInverse = new Matrix4();
+const _system = new Matrix3();
+const _position = new Vector3();
+const _near = new Vector3();
+const _far = new Vector3();
+const _direction = new Vector3();
+const _target = new Vector3();
+const _up = new Vector3();

package/dist/external/external-events.d.ts

@@ -0,0 +1,14 @@
+import { type EventManager, type RootStore } from '@react-three/fiber';
+/**
+ * R3F's DOM event manager, aiming its rays through the hosted camera.
+ *
+ * The default manager computes its ray with three's `setFromCamera`, which refuses a camera that is
+ * neither perspective nor orthographic — and the external camera is deliberately neither, one folded
+ * matrix with no transform of its own. Only the computation changes: hit testing, hover tracking,
+ * capture and the missed-click path all stay R3F's, so picking under a host behaves exactly as it
+ * does under the renderer's own canvas.
+ * @param store - The root the manager serves.
+ * @returns The event manager.
+ */
+export declare function externalEvents(store: RootStore): EventManager<HTMLElement>;
+//# sourceMappingURL=external-events.d.ts.map

package/dist/external/external-events.js

@@ -0,0 +1,33 @@
+import { events as createDomEvents } from '@react-three/fiber';
+import { castRay } from '../space/Space';
+/**
+ * R3F's DOM event manager, aiming its rays through the hosted camera.
+ *
+ * The default manager computes its ray with three's `setFromCamera`, which refuses a camera that is
+ * neither perspective nor orthographic — and the external camera is deliberately neither, one folded
+ * matrix with no transform of its own. Only the computation changes: hit testing, hover tracking,
+ * capture and the missed-click path all stay R3F's, so picking under a host behaves exactly as it
+ * does under the renderer's own canvas.
+ * @param store - The root the manager serves.
+ * @returns The event manager.
+ */
+export function externalEvents(store) {
+    const manager = createDomEvents(store);
+    return {
+        ...manager,
+        // The canvas is the host's and carries the host's own pointer handling; listening one element
+        // up leaves it alone, while `offsetX` stays canvas-relative — the events still target the
+        // canvas, which sits alone in its container.
+        connect(target) {
+            manager.connect?.(target.parentElement ?? target);
+        },
+        compute(event, state) {
+            state.pointer.set((event.offsetX / state.size.width) * 2 - 1, -(event.offsetY / state.size.height) * 2 + 1);
+            // R3F's pointer is a bare Vector2; the set above is what put it in NDC.
+            castRay(state.raycaster, state.pointer, state.camera);
+            // Screen-space raycasts — a route line answering at its drawn width — read the camera off the
+            // raycaster; `setFromCamera` writes it and the general-camera path must too.
+            state.raycaster.camera = state.camera;
+        },
+    };
+}