@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/platform/xr-fake.js

@@ -0,0 +1,434 @@
+/// <reference path="./xr-types.d.ts" preserve="true" />
+/**
+ * A fake WebXR stack for unit tests (ws/xr): `XRSystem`, `XRSession`, `XRFrame`, input sources
+ * and the WebXR/WebGPU binding, stepped by hand. `installFakeXr(device)` puts a `navigator.xr`
+ * and a `globalThis.XRGPUBinding` in place over a fake GPU device (`createFakeDevice`), so
+ * `createGame`'s `ctx.xr.enter()`, `XrSurface` and `XrPointerSource` run end to end in Node;
+ * the returned `uninstall` restores the globals. Not exported from any module index.
+ *
+ * Geometry: two eyes at ±`ipd / 2` on x, looking down -z with a 90° projection, side by side in
+ * one `textureType: 'texture'` layer texture (`2 * eyeWidth × eyeHeight`); a `texture-array`
+ * layer gives each eye its own array layer. Input sources carry a position and point down -z.
+ */
+function translation(x, y, z) {
+    const m = new Float32Array(16);
+    m[0] = m[5] = m[10] = m[15] = 1;
+    m[12] = x;
+    m[13] = y;
+    m[14] = z;
+    return m;
+}
+/** A rigid transform that is a pure translation, with its inverse. */
+export function fakeTransform(x, y, z) {
+    const make = (sx, sy, sz, inv) => ({
+        position: { x: sx, y: sy, z: sz, w: 1 },
+        orientation: { x: 0, y: 0, z: 0, w: 1 },
+        matrix: translation(sx, sy, sz),
+        get inverse() {
+            return inv();
+        },
+    });
+    const a = make(x, y, z, () => b);
+    const b = make(-x, -y, -z, () => a);
+    return a;
+}
+function perspective90(aspect) {
+    const near = 0.1;
+    const far = 100;
+    const m = new Float32Array(16);
+    m[0] = 1 / aspect;
+    m[5] = 1;
+    m[10] = far / (near - far);
+    m[11] = -1;
+    m[14] = (near * far) / (near - far);
+    return m;
+}
+export class FakeXrSpace {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+export class FakeXrReferenceSpace extends FakeXrSpace {
+    getOffsetReferenceSpace() {
+        return this;
+    }
+}
+export class FakeXrJointSpace extends FakeXrSpace {
+    jointName;
+    constructor(jointName) {
+        super(jointName);
+        this.jointName = jointName;
+    }
+}
+/** A hand whose joint positions a test sets (`joints.set('thumb-tip', [x, y, z])`). */
+export class FakeXrHand {
+    joints = new Map();
+    spaces = new Map();
+    get size() {
+        return this.spaces.size;
+    }
+    get(joint) {
+        let s = this.spaces.get(joint);
+        if (!s) {
+            s = new FakeXrJointSpace(joint);
+            this.spaces.set(joint, s);
+        }
+        return s;
+    }
+}
+export class FakeXrInputSource {
+    handedness;
+    targetRayMode = 'tracked-pointer';
+    targetRaySpace;
+    gripSpace = null;
+    profiles = ['generic-trigger-squeeze'];
+    /** Where the target ray starts, in the reference space; it points down -z. */
+    position = [0, 1, 0];
+    /** `buttons[0]` trigger, `buttons[1]` squeeze. */
+    buttons = [
+        { pressed: false, touched: false, value: 0 },
+        { pressed: false, touched: false, value: 0 },
+    ];
+    /** Null for a source without a gamepad (events only). */
+    gamepad;
+    hand = null;
+    constructor(handedness, opts = {}) {
+        this.handedness = handedness;
+        this.targetRaySpace = new FakeXrSpace(`${handedness}-ray`);
+        this.gamepad =
+            opts.gamepad === false ? null : { buttons: this.buttons, axes: [] };
+        if (opts.hand)
+            this.hand = new FakeXrHand();
+    }
+}
+export class FakeXrFrame {
+    session;
+    predictedDisplayTime;
+    constructor(session, predictedDisplayTime) {
+        this.session = session;
+        this.predictedDisplayTime = predictedDisplayTime;
+    }
+    getViewerPose(referenceSpace) {
+        if (!this.session.tracking)
+            return undefined;
+        if (referenceSpace !== this.session.referenceSpace)
+            return undefined;
+        const s = this.session;
+        const [hx, hy, hz] = s.headPosition;
+        const half = s.opts.ipd / 2;
+        const proj = perspective90(s.opts.eyeWidth / s.opts.eyeHeight);
+        const view = (eye, dx) => ({
+            eye,
+            projectionMatrix: proj,
+            transform: fakeTransform(hx + dx, hy, hz),
+        });
+        return {
+            transform: fakeTransform(hx, hy, hz),
+            emulatedPosition: false,
+            views: [view('left', -half), view('right', half)],
+        };
+    }
+    getPose(space, baseSpace) {
+        if (baseSpace !== this.session.referenceSpace)
+            return undefined;
+        for (const src of this.session.inputSources) {
+            if (src.targetRaySpace === space) {
+                const [x, y, z] = src.position;
+                return { transform: fakeTransform(x, y, z), emulatedPosition: false };
+            }
+        }
+        return undefined;
+    }
+    getJointPose(joint, baseSpace) {
+        if (baseSpace !== this.session.referenceSpace)
+            return undefined;
+        for (const src of this.session.inputSources) {
+            const p = src.hand?.joints.get(joint.jointName);
+            if (src.hand?.get(joint.jointName) === joint && p) {
+                return {
+                    transform: fakeTransform(p[0], p[1], p[2]),
+                    emulatedPosition: false,
+                    radius: 0.01,
+                };
+            }
+        }
+        return undefined;
+    }
+}
+class FakeInputSourceEvent extends Event {
+    frame;
+    inputSource;
+    constructor(type, frame, inputSource) {
+        super(type);
+        this.frame = frame;
+        this.inputSource = inputSource;
+    }
+}
+class FakeSourcesChangeEvent extends Event {
+    session;
+    added;
+    removed;
+    constructor(session, added, removed) {
+        super('inputsourceschange');
+        this.session = session;
+        this.added = added;
+        this.removed = removed;
+    }
+}
+export class FakeXrSession extends EventTarget {
+    mode;
+    init;
+    opts;
+    inputSources = [];
+    referenceSpace = new FakeXrReferenceSpace('reference');
+    renderState = { depthNear: 0.1, depthFar: 1000, layers: [] };
+    visibilityState = 'visible';
+    headPosition = [0, 1.6, 0];
+    /** False makes `getViewerPose` return nothing (tracking lost). */
+    tracking = true;
+    ended = false;
+    /** Every `requestReferenceSpace` type asked for. */
+    referenceSpaceRequests = [];
+    renderStateUpdates = [];
+    pending = new Map();
+    nextHandle = 1;
+    frameTime = 0;
+    constructor(mode, init, opts) {
+        super();
+        this.mode = mode;
+        this.init = init;
+        this.opts = opts;
+    }
+    /** The clock of the frame running now (the last `step`), ms. */
+    get now() {
+        return this.frameTime;
+    }
+    /** Callbacks waiting for the next frame. */
+    get pendingFrames() {
+        return this.pending.size;
+    }
+    requestReferenceSpace(type) {
+        this.referenceSpaceRequests.push(type);
+        return Promise.resolve(this.referenceSpace);
+    }
+    updateRenderState(state = {}) {
+        this.renderStateUpdates.push(state);
+        this.renderState = { ...this.renderState, ...state };
+    }
+    requestAnimationFrame(callback) {
+        const h = this.nextHandle++;
+        this.pending.set(h, callback);
+        return h;
+    }
+    cancelAnimationFrame(handle) {
+        this.pending.delete(handle);
+    }
+    /** Run the pending frame callbacks with a new `XRFrame`, `dtMs` after the last one. */
+    step(dtMs = 1000 / 72) {
+        this.frameTime += dtMs;
+        const frame = new FakeXrFrame(this, this.frameTime);
+        const cbs = [...this.pending.values()];
+        this.pending.clear();
+        for (const cb of cbs)
+            cb(this.frameTime, frame);
+        return frame;
+    }
+    /** Add an input source (fires `inputsourceschange`). */
+    addInputSource(src) {
+        this.inputSources.push(src);
+        this.dispatchEvent(new FakeSourcesChangeEvent(this, [src], []));
+    }
+    removeInputSource(src) {
+        const i = this.inputSources.indexOf(src);
+        if (i < 0)
+            return;
+        this.inputSources.splice(i, 1);
+        this.dispatchEvent(new FakeSourcesChangeEvent(this, [], [src]));
+    }
+    /** Fire `selectstart` / `selectend` (or `squeeze…`) for a source, as a headset would. */
+    fire(kind, src, down) {
+        const frame = new FakeXrFrame(this, this.frameTime);
+        this.dispatchEvent(new FakeInputSourceEvent(`${kind}${down ? 'start' : 'end'}`, frame, src));
+        if (!down)
+            this.dispatchEvent(new FakeInputSourceEvent(kind, frame, src));
+    }
+    end() {
+        if (!this.ended) {
+            this.ended = true;
+            this.pending.clear();
+            const ev = new Event('end');
+            ev.session = this;
+            this.dispatchEvent(ev);
+        }
+        return Promise.resolve();
+    }
+}
+export class FakeXrSystem {
+    opts;
+    sessions = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    isSessionSupported(mode) {
+        return Promise.resolve(this.opts.supported && mode === 'immersive-vr');
+    }
+    requestSession(mode, init) {
+        if (!this.opts.supported)
+            return Promise.reject(new Error('NotSupportedError'));
+        const s = new FakeXrSession(mode, init, this.opts);
+        this.sessions.push(s);
+        return Promise.resolve(s);
+    }
+    /** The session requested last. */
+    get session() {
+        const s = this.sessions.at(-1);
+        if (!s)
+            throw new Error('no session requested');
+        return s;
+    }
+}
+export class FakeXrProjectionLayer {
+    binding;
+    init;
+    layout = 'stereo';
+    mipLevels = 1;
+    needsRedraw = false;
+    ignoreDepthValues = false;
+    fixedFoveation = null;
+    destroyed = false;
+    /** Textures handed out so far (one per frame when rotating). */
+    colorTextures = [];
+    depthTextures = [];
+    color = null;
+    depth = null;
+    lastFrameTime = -1;
+    constructor(binding, init) {
+        this.binding = binding;
+        this.init = init;
+    }
+    get textureType() {
+        return this.init.textureType ?? 'texture';
+    }
+    get textureWidth() {
+        const w = this.binding.session.opts.eyeWidth;
+        return this.textureType === 'texture' ? 2 * w : w;
+    }
+    get textureHeight() {
+        return this.binding.session.opts.eyeHeight;
+    }
+    get textureArrayLength() {
+        return this.textureType === 'texture' ? 1 : 2;
+    }
+    /** This frame's textures, made on first use and, when rotating, anew each frame. */
+    textures(frameTime) {
+        const rotate = this.binding.session.opts.rotateTextures && frameTime !== this.lastFrameTime;
+        this.lastFrameTime = frameTime;
+        if (!this.color || rotate) {
+            const size = [this.textureWidth, this.textureHeight, this.textureArrayLength];
+            const device = this.binding.device;
+            this.color = device.createTexture({
+                label: 'xr-layer-color',
+                size,
+                format: this.init.colorFormat ?? 'rgba8unorm',
+                usage: GPUTextureUsage.RENDER_ATTACHMENT,
+            });
+            this.colorTextures.push(this.color);
+            this.depth = this.init.depthStencilFormat
+                ? device.createTexture({
+                    label: 'xr-layer-depth',
+                    size,
+                    format: this.init.depthStencilFormat,
+                    usage: GPUTextureUsage.RENDER_ATTACHMENT,
+                })
+                : null;
+            if (this.depth)
+                this.depthTextures.push(this.depth);
+        }
+        return { color: this.color, depth: this.depth };
+    }
+    destroy() {
+        this.destroyed = true;
+    }
+}
+export class FakeXRGPUBinding {
+    session;
+    device;
+    nativeProjectionScaleFactor = 1;
+    layers = [];
+    constructor(session, device) {
+        this.session = session;
+        this.device = device;
+    }
+    createProjectionLayer(init = {}) {
+        const l = new FakeXrProjectionLayer(this, init);
+        this.layers.push(l);
+        return l;
+    }
+    getViewSubImage(layer, view) {
+        const l = layer;
+        const { color, depth } = l.textures(this.session.now);
+        const w = this.session.opts.eyeWidth;
+        const h = this.session.opts.eyeHeight;
+        const right = view.eye === 'right';
+        const array = l.textureType === 'texture-array';
+        return {
+            colorTexture: color,
+            depthStencilTexture: depth,
+            viewport: { x: right && !array ? w : 0, y: 0, width: w, height: h },
+            getViewDescriptor: () => array ? { dimension: '2d', baseArrayLayer: right ? 1 : 0, arrayLayerCount: 1 } : {},
+        };
+    }
+    getPreferredColorFormat() {
+        return 'rgba8unorm';
+    }
+}
+/**
+ * Install `navigator.xr` and `XRGPUBinding` fakes. `supported: false` keeps `navigator.xr` but
+ * answers no to `immersive-vr`; to test a browser with no WebXR at all, install nothing.
+ */
+export function installFakeXr(opts = {}) {
+    const full = {
+        eyeWidth: opts.eyeWidth ?? 64,
+        eyeHeight: opts.eyeHeight ?? 32,
+        ipd: opts.ipd ?? 0.064,
+        supported: opts.supported ?? true,
+        rotateTextures: opts.rotateTextures ?? false,
+    };
+    const system = new FakeXrSystem(full);
+    const bindings = [];
+    const Binding = function (session, device) {
+        const b = new FakeXRGPUBinding(session, device);
+        bindings.push(b);
+        return b;
+    };
+    const g = globalThis;
+    const hadBinding = Object.getOwnPropertyDescriptor(g, 'XRGPUBinding');
+    Object.defineProperty(g, 'XRGPUBinding', { value: Binding, configurable: true, writable: true });
+    let nav = g.navigator;
+    let madeNavigator = false;
+    if (!nav) {
+        nav = {};
+        Object.defineProperty(g, 'navigator', { value: nav, configurable: true, writable: true });
+        madeNavigator = true;
+    }
+    const hadXr = Object.getOwnPropertyDescriptor(nav, 'xr');
+    Object.defineProperty(nav, 'xr', { value: system, configurable: true });
+    return {
+        system,
+        bindings,
+        step: (dtMs) => system.session.step(dtMs),
+        uninstall() {
+            if (hadBinding)
+                Object.defineProperty(g, 'XRGPUBinding', hadBinding);
+            else
+                delete g.XRGPUBinding;
+            if (madeNavigator)
+                delete g.navigator;
+            else if (hadXr)
+                Object.defineProperty(nav, 'xr', hadXr);
+            else
+                delete nav.xr;
+        },
+    };
+}

package/dist/platform/xr-surface.d.ts

@@ -0,0 +1,120 @@
+/// <reference path="./xr-types.d.ts" preserve="true" />
+/**
+ * The XR surface (ws/xr; ARCHITECTURE "Surface"): a `SceneTarget` per eye per frame. Built on
+ * the WebXR/WebGPU binding, it makes one `XRProjectionLayer` for the session (colour in
+ * `SCENE_FORMAT`, since every material's pipeline writes that format, plus a `DEPTH_FORMAT`
+ * depth texture) and each frame turns the viewer pose into `XrEyeView`s: a `Camera` whose
+ * projection and view matrices are the `XRView`'s (`viewIndex` = eye index, depth on) and a
+ * `SceneTarget` adopting the eye's part of the layer (`SceneTarget.external`). Eyes that share
+ * one layer texture (the default `texture` layout, side by side) share one target and differ by
+ * `camera.screen`, so the renderer clears it once and scissors each eye to its viewport; a
+ * `texture-array` layer gives each eye its own target over its array layer.
+ *
+ * Two ways to draw the eyes. Direct (the default): each eye is a scene pass into its layer
+ * target; the colour goes to the layer as linear HDR, the emissive target is written and
+ * dropped and no post stack runs. Through the post stack (`scene: true`, ws/xr-post, what
+ * `createGame` uses): the surface keeps `scene`, one HDR `SceneTarget` the size of an eye
+ * (allocated on the first frame, resized when the layer's eye size changes), every eye camera
+ * covers it whole and the caller renders each eye into it and resolves it into the eye's layer
+ * target at `eye.viewport` (`renderer.render(frame, eye.camera, surface.scene)` then
+ * `renderer.resolve(surface.scene, eye.target.color.view, eye.viewport)`), so the headset sees
+ * the same bloom, tone map and grade as the screen; the layer then takes `colorFormat`, the
+ * format the post stack writes (`renderer.format`), and no depth by default.
+ *
+ * `head` is a camera at the viewer pose with the first eye's projection, for the scenes' one
+ * `render(frame, camera, alpha)` call per frame.
+ */
+import { Camera } from '../render/camera.js';
+import { SceneTarget, type SceneTargetAux, type SceneTargetViewport } from '../render/scene-target.js';
+export interface XrSurfaceOptions {
+    /** The space poses are expressed in (the game's `local-floor`, `local` or `viewer` space). */
+    referenceSpace: XRReferenceSpace;
+    /**
+     * Colour format of the layer. Default `SCENE_FORMAT`, what the engine's materials write;
+     * with `scene` pass the format the post stack writes (`renderer.format`).
+     */
+    colorFormat?: GPUTextureFormat;
+    /**
+     * Depth format of the layer, or null for a layer without depth. Default `DEPTH_FORMAT`, or
+     * null with `scene` (depth then lives in the scene target; the layer never receives it).
+     */
+    depthStencilFormat?: GPUTextureFormat | null;
+    /**
+     * Draw the eyes through the post stack (ws/xr-post): keep `scene`, an eye-sized HDR target,
+     * give every eye camera the whole of it (`screen` 0,0,1,1) and leave the layer target for
+     * `renderer.resolve`. Default false: eyes draw into the layer directly.
+     */
+    scene?: boolean;
+    /** `texture` (default, eyes side by side in one texture) or `texture-array` (a layer per eye). */
+    textureType?: 'texture' | 'texture-array';
+    /** The session's near and far planes, metres. Defaults 0.1 and 1000. */
+    depthNear?: number;
+    depthFar?: number;
+    /**
+     * Aux attachments the eyes render with (ws/render-11; `createGame({ aux })` passes its own):
+     * velocity, rough-metal, as `SceneTargetDesc.aux`. Direct, each eye target adopting the layer
+     * makes them (`SceneTarget.external({ aux })`) at the eye's size; with `scene`, the scene
+     * target every eye renders into has them and the layer targets, only resolved into, do not.
+     * Each eye's camera keeps its own previous view-projection, so an eye's velocity is its own
+     * motion. Default none.
+     */
+    aux?: SceneTargetAux;
+}
+/** One eye of one frame: where it looks and what it draws into. */
+export interface XrEyeView {
+    /** The eye's index in the viewer pose (0 left, 1 right on a headset); `camera.viewIndex`. */
+    readonly index: number;
+    readonly eye: XREye;
+    /**
+     * Projection and view from the `XRView`; `screen` is the viewport as a fraction of the target,
+     * or the whole unit square when the surface has a `scene` target.
+     */
+    readonly camera: Camera;
+    /**
+     * The target adopting the layer's texture for this eye; shared when the eyes share a texture.
+     * With `scene`, what the eye is resolved into, not what it is rendered into.
+     */
+    readonly target: SceneTarget;
+    /** The eye's part of `target`, in texture pixels (`renderer.resolve`'s viewport). */
+    readonly viewport: SceneTargetViewport;
+}
+export declare class XrSurface {
+    readonly session: XRSession;
+    readonly device: GPUDevice;
+    readonly binding: XRGPUBinding;
+    readonly layer: XRProjectionLayer;
+    readonly referenceSpace: XRReferenceSpace;
+    /**
+     * A camera at the viewer pose (between the eyes) with the first eye's projection, depth on,
+     * updated by `views`: what the scenes record through once per frame.
+     */
+    readonly head: Camera;
+    /**
+     * With `scene: true`, the eye-sized HDR target every eye renders into before `resolve`;
+     * made by the first `views` with a pose and resized when the eye size changes. Null before
+     * then, and always null for a direct surface.
+     */
+    scene: SceneTarget | null;
+    private readonly eyes;
+    private readonly out;
+    private readonly viaScene;
+    /** `opts.aux`: on the scene target with `scene`, else on each eye target. */
+    private readonly aux;
+    private destroyed;
+    /**
+     * Makes the session's projection layer and installs it (`session.updateRenderState`).
+     * Throws where the browser has no `XRGPUBinding`; check `XrSurface.supported()` first.
+     */
+    constructor(session: XRSession, device: GPUDevice, opts: XrSurfaceOptions);
+    /** True where `XRGPUBinding` exists (the WebXR/WebGPU binding). */
+    static supported(): boolean;
+    /**
+     * The eyes of this frame, in viewer-pose order, each with its camera aimed and its target
+     * adopting the layer's texture for the frame. Empty when the pose is unavailable (tracking
+     * lost). The array and the views are reused; read them within the frame.
+     */
+    views(frame: XRFrame): readonly XrEyeView[];
+    private makeScene;
+    /** Frees the eye targets' own textures, the scene target and the layer. The session is left to its owner. */
+    destroy(): void;
+}