viewer.renderMode — RenderModeManager

设计意图

viewer.renderMode 是渲染模式域。四个模式(RenderMode:ShadedWithEdges 实色线框 / Wireframe 线框 / Shaded 实色 / HiddenLine 消隐)本质是「面可见性 × 边可见性」的具名组合——模式不单独存储,而是由场景可见性状态推导(单一事实源)。这意味着它与 viewer.edges 作用于同一份状态:renderMode.set(RenderMode.Shaded) 会关边线,随后 edges.setVisible(true) 又把边画回来,两个 manager 不是相互隔离的开关。

模式有两级:set(mode) 全局,setNodes(ids, mode) 按节点覆盖(非叶节点递归到带几何的叶子),clearNodes / resetNodes 回落全局。HiddenLine 还有一组专属设置(setHiddenLineSettings):被遮挡边是否灰显、颜色与不透明度,仅在 HiddenLine 模式下可见生效。

何时用它:工具条的全局模式切换、「上下文聚焦」类交互(全局线框 + 焦点零件实色)、消隐工程图风格的屏上预览。只调边线风格(颜色 / 透明度)归 viewer.edges;把消隐线条导出成 SVG 归 viewer.export。

典型用法

工具条循环切换全局模式:

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

const order = [RenderMode.ShadedWithEdges, RenderMode.Wireframe, RenderMode.Shaded, RenderMode.HiddenLine];
modeBtn.onclick = () => {
  const next = order[(order.indexOf(viewer.renderMode.get()) + 1) % order.length];
  viewer.renderMode.set(next);
};

上下文聚焦(全局线框,焦点零件保持实色线框):

viewer.renderMode.set(RenderMode.Wireframe);
viewer.renderMode.setNodes(focusIds, RenderMode.ShadedWithEdges);
// ……退出聚焦
viewer.renderMode.resetNodes();
viewer.renderMode.set(RenderMode.ShadedWithEdges);

消隐模式 + 隐藏边灰显:

viewer.renderMode.set(RenderMode.HiddenLine);
viewer.renderMode.setHiddenLineSettings({
  showObscured: true,
  obscuredColor: { r: 0.5, g: 0.5, b: 0.5 },
  obscuredOpacity: 0.6,
});

注意事项

• 按节点 HiddenLine 抛 ViewerError(UnsupportedOperation):v1 中 HiddenLine 仅支持全局,setNodes(ids, RenderMode.HiddenLine) 必抛;其余三个模式可按节点设置。
• 与 viewer.edges 共享状态:全局模式与 edges.setVisible 互相覆盖,后调用者生效;get() 返回的是由当前状态推导的模式,可能不是你最后一次 set 的值。
• getNodeMode(id) 返回生效模式(有覆盖用覆盖,否则全局);模型未加载或节点无实例时回落全局模式,不抛错。
• HiddenLineSettings 默认隐藏边不显示(showObscured: false = 纯消隐);设置在非 HiddenLine 模式下保留但不可见。
• resetNodes() 一次清除全部按节点覆盖模式;它不影响 viewer.model 的节点显隐——渲染模式覆盖与可见性是两套独立状态。

完整签名与延伸

• RenderModeManager — 全部方法的精确签名。
• RenderMode / HiddenLineSettings — 四模式枚举与消隐设置字段。
• 指南:显示控制 — 可见性 / 边线 / 渲染模式三者的组合用法与 demo。
• 相邻域:viewer.edges(边线风格)、viewer.export(消隐线条的 SVG 导出)。