viewer.quality — RenderQualityManager

设计意图

viewer.quality 是渲染质量域,管视觉保真与性能之间的取舍:抗锯齿(SMAA 后处理)、环境光遮蔽(GTAO)、色调映射与曝光、IBL 环境,以及统摄这一切的质量档(QualityTier)。默认档是 "auto"——按帧时 EMA(指数滑动平均)自适应升降档,大模型掉帧时自动降质保流畅;setTier 设显式档("high" / "balanced" / "performance")即锁定并关闭自适应。

两个刻意的默认值得理解:GTAO 默认关——它是每帧开销最大的 pass,需要时经 setAmbientOcclusion({ enabled: true }) 显式开启;且用户显式关闭后,自适应调档不会再替你打开它(用户意图优先于自动策略)。SMAA 与 MSAA 是两个独立的抗锯齿:ViewerOptions.antialias 是硬件 MSAA、构造后不可变;本域的 setAntialias 是 SMAA 后处理、运行时可开关,两者叠加。

何时用它:设置面板的质量选项、产品展示场景的视觉调优(HDRI 环境 / 曝光)、需要还原材质标称色的色彩精确模式。配合 viewer.stats 观测调整效果;灯光本身归 viewer.lights。

典型用法

设置面板的「画质」三挡(显式档锁定,关闭自适应):

import type { QualityTier } from "@modelcubes/viewer-core";

qualitySelect.onchange = () => {
  viewer.quality.setTier(qualitySelect.value as QualityTier); // "high" | "balanced" | "performance"
};
autoBtn.onclick = () => viewer.quality.setTier("auto"); // 回到帧时自适应

产品展示调优(开 AO + 换 HDRI 环境 + 提环境强度):

viewer.quality.setAmbientOcclusion({ enabled: true, intensity: 1.2 });
await viewer.quality.setEnvironment("/env/studio.hdr"); // equirect HDRI,返回加载 Promise
viewer.quality.setEnvironmentIntensity(0.8); // 默认 0.5

色彩精确模式(关 filmic 压缩,还原材质标称色):

viewer.quality.setToneMapping("linear", 1.0); // 默认 "aces" + 曝光 0.7

注意事项

• GTAO 默认关,显式关闭后自适应不再开它:setAmbientOcclusion({ enabled: false }) 是对自动策略的否决,不只是临时关闭。
• setAntialias 是 SMAA(运行时后处理,默认开);硬件 MSAA 在 ViewerOptions.antialias(默认 true),构造后不可变——两者不是同一个开关。
• 默认色调映射 "aces"、曝光 0.7、环境强度 0.5:构造期初值可经 ViewerOptions.quality 覆盖,运行时再用本域逐项调。
• setEnvironment 替换的是 IBL 环境(默认内置程序化环境),与 viewer.lights 的灯光叠加;加载失败 reject,记得处理。
• "auto" 档会动态改分辨率缩放与 AO:做像素级对比(回归截图等)时先 setTier 锁定显式档,排除自适应扰动。

完整签名与延伸

• RenderQualityManager — 全部方法的精确签名。
• QualityOptions / QualityTier / ToneMappingMode — 构造期初值与档位 / 模式取值。
• 指南:渲染质量与统计 — 质量与统计连成的调试场景。
• 相邻域:viewer.lights(灯光,与 IBL 叠加的另一半光照)、viewer.stats(观测调整效果)。