WebXR 技术栈深度解析 — truth-lab Pico Ultra 适配实战¶

Canvas → <XR store={xrStore}> → <VRButton>

Canvas → 无 <XR> → 手动 requestSession + setSession

Canvas → <XR store={xrStore}> → 用 customSessionInit 清空 requiredFeatures
                                    → 猴子补丁 setReferenceSpaceType

Canvas → 无任何 XR 库 → 猴子补丁 + 紧邻 setSession 前设 'local'

┌─────────────────────────────────────────────┐
│                 应用层                       │
│  truth-lab (React + Zustand + TypeScript)   │
├─────────────────────────────────────────────┤
│              React 3D 框架层                │
│  @react-three/fiber (R3F)                   │
│  @react-three/drei (工具组件)               │
├─────────────────────────────────────────────┤
│        Three.js 3D 引擎层                   │
│  WebGLRenderer / WebXRManager / Scene       │
├─────────────────────────────────────────────┤
│  浏览器 Web API 层                          │
│  WebXR Device API │ WebGL API              │
├─────────────────────────────────────────────┤
│        GPU (WebGL2 / Vulkan)               │
└─────────────────────────────────────────────┘

顶点数据 → 顶点着色器 → 图元装配 → 光栅化 → 片段着色器 → 输出颜色

class WebXRManager {
  let referenceSpaceType = 'local-floor';  // 默认！重要！
  let session = null;
  const animation = new WebGLAnimation();

  this.setReferenceSpaceType = function(type) {
    referenceSpaceType = type;  // 这是一个闭包变量
  };

  this.setSession = async function(value) {
    session = value;
    // 1. 可选: makeXRCompatible()
    // 2. 设置渲染目标 (XRWebGLLayer 或 XRProjectionLayer)
    // 3. 请求参考空间:
    referenceSpace = await session.requestReferenceSpace(referenceSpaceType);
    // 4. 启动 XR 动画循环
    animation.setContext(session);
    animation.start();
    // 5. 标记 presenting 状态
    scope.isPresenting = true;
    scope.dispatchEvent({ type: 'sessionstart' });
  };
}

// WebGLRenderer.setAnimationLoop
this.setAnimationLoop = function(callback) {
  onAnimationFrameCallback = callback;
  xr.setAnimationLoop(callback);     // 同步设置 XR 回调
  (callback === null) ? animation.stop() : animation.start();
};

function WebGLAnimation() {
  return {
    start() {
      context.requestAnimationFrame(onAnimationFrame);  // XR 设备的 RAF
    },
    setAnimationLoop(callback) {
      animationLoop = callback;
    }
  };
}

function onAnimationFrame(time, frame) {
  // 1. 获取 pose
  pose = frame.getViewerPose(referenceSpace);
  // 2. 设置 XR 帧缓冲
  renderer.setRenderTarget(newRenderTarget);
  // 3. 更新左右眼相机
  // 4. 调用用户回调
  if (onAnimationFrameCallback) onAnimationFrameCallback(time, frame);
  // 5. 继续下一帧
  context.requestAnimationFrame(onAnimationFrame);
}

<Canvas>
  <mesh>
    <boxGeometry />
    <meshStandardMaterial color="red" />
  </mesh>
</Canvas>

function loop(timestamp) {
  frame = requestAnimationFrame(loop);    // 浏览器 RAF
  for (const root of _roots.values()) {
    state = root.store.getState();
    if (state.internal.active 
        && state.frameloop === 'always' 
        && !state.gl.xr?.isPresenting) {  // XR 活跃时跳过
      update(timestamp, state);
    }
  }
}

// 在 configure() 中，一次性设置
if (!state.xr) {
  const handleXRFrame = (timestamp, frame) => {
    advance(timestamp, true, store.getState(), frame);
  };

  const handleSessionChange = () => {
    const state = store.getState();
    state.gl.xr.enabled = state.gl.xr.isPresenting;
    state.gl.xr.setAnimationLoop(state.gl.xr.isPresenting ? handleXRFrame : null);
  };

  gl.xr.addEventListener('sessionstart', handleSessionChange);
  gl.xr.addEventListener('sessionend', handleSessionChange);
}

@react-three/xr
  └── @pmndrs/xr (核心引擎)
        ├── store.ts — XRStore (基于 Zustand)
        ├── init.ts — buildXRSessionInit (session 配置)
        ├── controller/ — 控制器建模
        ├── hand/ — 手部追踪
        ├── pointer/ — 射线交互
        └── space.ts — 参考空间

// 创建 XR Store
function createXRStore(options) {
  const store = createStore(...);

  return {
    setWebXRManager(manager) {
      // 连接 Three.js 的 WebXRManager
      xrManager = manager;
      xrManager.setReferenceSpaceType(
        options.bounded ? 'bounded-floor' : 'local-floor'  // ← 硬编码！
      );
      xrManager.addEventListener('sessionstart', onSessionStart);
    },

    async enterVR() {
      return enterXRSession(domOverlayRoot, 'immersive-vr', options, manager);
    }
  };
}

async function enterXRSession(domOverlayRoot, mode, options, manager) {
  const init = buildXRSessionInit(mode, domOverlayRoot, options);
  const session = await navigator.xr.requestSession(mode, init);
  await setupXRManager(manager, session, options);
}

async function setupXRManager(xr, session, options) {
  await xr.setSession(session);  // THREE.js 的 setSession
}

export function buildXRSessionInit(mode, domOverlayRoot, options) {
  if (options.customSessionInit) return options.customSessionInit;  // 覆盖点

  const requiredFeatures = 
    options.bounded == null ? ['local-floor'] :    // ← 默认路径
    options.bounded ? ['bounded-floor'] : 
    ['unbounded', 'local-floor'];

  return { requiredFeatures, optionalFeatures };
}

浏览器 RAF → R3F loop() → update() → gl.render(scene, camera)

Pico GPU → XR 设备 RAF → WebXRManager.onAnimationFrame
  → 设置帧缓冲 + 更新 XR 相机
  → onAnimationFrameCallback (handleXRFrame)
    → R3F advance()
      → update(timestamp, state, frame)
        → 执行 useFrame 回调
        → gl.render(state.scene, state.camera)
          → THREE 内部: 检测 xr.isPresenting, 使用 XR 相机
  → 提交帧到 XR 设备

用户点击"进入 VR"
  ↓
navigator.xr.requestSession('immersive-vr')
  ↓ 返回 XRSession
gl.xr.setReferenceSpaceType('local')  // monkey-patched
  ↓
gl.xr.setSession(session)
  ↓ THREE 内部
session.requestReferenceSpace('local')  // 成功！
  ↓
gl.xr.enabled = true
scope.isPresenting = true
dispatchEvent('sessionstart')
  ↓ R3F 监听
handleSessionChange()
  → gl.xr.setAnimationLoop(handleXRFrame)
  ↓
XR 帧循环开始
  → handleXRFrame → advance → update → gl.render