viewer.stats — StatsView

设计意图

viewer.stats 是运行时统计的只读视图,两条轨:getLoader() 看加载侧(分块进度 / 下载字节 / 解码耗时分位)——流式加载是否健康、卡在哪;getRender() 看渲染侧(fps / 帧时 / draw call / 三角形数)——当前视角的渲染负载有多重。纯查询、零副作用,任何频率轮询都安全。

消费方式有 pull 与 push 两种:pull 即随时调 getLoader / getRender 取快照,按自己的节奏刷新;push 即订阅 render 事件(约每秒一次心跳,带 fps / frameMs),不想自己起定时器时用它当节拍器。两者常组合:心跳驱动 UI 更新,快照补齐其余字段。

何时用它:调试 HUD、性能面板、加载进度条的补充数据源(主进度走 model-geom-progress 事件)、上报集成环境的真实渲染表现。

典型用法

性能 HUD(render 心跳驱动,快照补 draw call / 三角形数):

viewer.on("render", ({ fps, frameMs }) => {
  const { drawCalls, triangles } = viewer.stats.getRender();
  hud.textContent = `${fps.toFixed(0)} fps · ${frameMs.toFixed(1)} ms · ${drawCalls} dc · ${triangles} tri`;
});

大模型加载健康监控(失败分块与下载量):

viewer.on("model-geom-progress", () => {
  const { chunks, bytes } = viewer.stats.getLoader();
  if (chunks.failed > 0) console.warn(`${chunks.failed} 个分块加载失败`);
  bar.textContent = `${chunks.loaded}/${chunks.total} · ${(bytes.downloaded / 1e6).toFixed(1)} MB`;
});

注意事项

• getRender() 的 drawCalls / triangles 是 WebGL renderer 上一帧的提交计数——本帧实际画了多少,受 LOD 与节点可见性影响,不是场景三角形总量。
• fps 有两个口径:getRender().fps 由最近一帧帧时折算(瞬时值,逐帧波动);render 事件里的 fps 是发射区间(约 1s)的平均,做展示更平稳。frameMs 两处都是最近一帧耗时。
• getLoader() 未加载模型时各项为 0,不抛错;decode 是几何解码耗时的 p50 / p95(ms)。

完整签名与延伸

• StatsView — 两个方法的精确签名。
• LoaderStats / RenderStats — 统计字段定义。
• 指南:渲染质量与统计 — 统计与质量调整连成的调试场景。
• 概念:事件系统 — render / model-geom-progress 事件参考。