viewer.quality — RenderQualityManager

设计意图

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

三个刻意的默认值得理解:

• GTAO 默认关 —— 它是每帧开销最大的 pass,需要时经 setAmbientOcclusion({ enabled: true }) 显式开启;且用户显式关闭后,自适应调档不会再替你打开它(用户意图优先于自动策略)。
• SMAA 也默认关 —— 形态学抗锯齿会把 1px 的特征边线羽化成灰、让线条变糊。硬件 MSAA(ViewerOptions.antialias,默认开)已经在处理几何锯齿,再叠 SMAA 得不偿失。这与 ViewerOptions.antialias 是两个独立开关:后者是硬件 MSAA、构造后不可变;本域的 setAntialias 是 SMAA 后处理、运行时可开关。
• 着色风格默认 "matte"(哑光技术视图)—— 面间对比高、结构可读;"showcase" 把不透明件渲成抛光金属,更漂亮但对比低、发白,适合产品展示而非工程审阅。

何时用它:设置面板的质量选项、产品展示场景的视觉调优(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.2(对标 HOOPS 纯头灯;调高增加环境反射)

filmic 视觉呈现(默认是色彩精确的 "none",需要电影感时显式开):

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

着色风格与屏幕描边(两个影响「看起来像不像工程图」的旋钮):

viewer.quality.setShadingStyle("showcase"); // 默认 "matte"(哑光技术视图)

// 屏幕空间描边:默认开、灰色、阈值 0.05。调深调粗可强化轮廓,关掉则只剩烘焙边线
viewer.quality.setEdgeOutline({ color: { r: 0.1, g: 0.1, b: 0.1 }, threshold: 0.03 });
viewer.quality.setEdgeOutline({ enabled: false }); // 只要模型自带的精确边线

描边与边线是两套东西

viewer.edges 控制的是模型自带的烘焙边线(来自 B-Rep 拓扑,精确、可拾取);setEdgeOutline 控制的是屏幕空间描边——对线性化深度取二阶差算出的轮廓,LOD 无关、不 z-fight,用来给屏幕足迹太小、烘焙边线被降噪隐藏的零件兜底一层轮廓。引擎会在烘焙边线的邻域抑制描边,两者不会画成双线。

注意事项

• GTAO 默认关,显式关闭后自适应不再开它:setAmbientOcclusion({ enabled: false }) 是对自动策略的否决,不只是临时关闭。
• setAntialias 是 SMAA,默认关;硬件 MSAA 在 ViewerOptions.antialias(默认 true),构造后不可变——两者不是同一个开关。开 SMAA 会让 1px 边线变糊,只在锯齿明显盖过线条清晰度时才值得。
• 默认色调映射 "none"(色彩精确)、曝光 1.0、环境强度 0.2、着色风格 "matte":构造期初值可经 ViewerOptions.quality 覆盖,运行时再用本域逐项调。
• setEnvironment 替换的是 IBL 环境(默认内置程序化环境),与 viewer.lights 的灯光叠加;加载失败 reject,记得处理。
• "auto" 档只自适应 AO,不缩放渲染分辨率——动态改分辨率会让浏览时整屏闪烁,已被移除。显式档("balanced" / "performance")仍会按档降分辨率。
• 做像素级对比时锁显式档:回归截图之类的场景先 setTier("high"),排除自适应带来的帧间差异。
• 描边与 GTAO 都需要 WebGL2:环境不支持时引擎打一条 warn 并静默跳过该 pass,其余渲染正常。

完整签名与延伸

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