OCCT 实战（4）基础类 | 4.1、StdPrs_ShadedShape 类

前言：

StdPrs_ShadedShape 是 OCCT 中用于以着色模式（Shaded Mode）可视化拓扑形状（TopoDS_Shape） 的标准呈现器（Presentation Builder）类。它属于 StdPrs（Standard Presentations）模块，专门负责将几何/拓扑数据转换为可用于 3D 渲染的图形图元（Graphic Primitives），尤其适用于需要真实感渲染（如带法向、材质、光照）的场景。

一、StdPrs_ShadedShape 类

1、简介

• 核心功能：将 TopoDS_Shape（如面、壳、实体等）转换为支持 OpenGL 或其他图形 API 渲染的三角网格（triangulation）表示，并生成对应的着色（shaded）图形。
• 适用对象：主要处理具有面（faces）的拓扑结构（如 TopoDS_Face, TopoDS_Shell, TopoDS_Solid），对线框或点类形状无效果。
• 依赖机制：
  • 自动调用 BRepMesh_IncrementalMesh 对形状进行三角剖分（若尚未网格化）。
  • 利用面的法向、顶点法向（可选）实现平滑或硬边渲染。
  • 支持通过 Prs3d_Drawer 控制颜色、材质、是否显示边线（wireframe on shaded）等。

✅ 简言之：StdPrs_ShadedShape 是 OCCT 中实现实体/曲面着色显示的标准工具类。

2、Add 接口详解

2.1、作用

StdPrs_ShadedShape::Add 主要负责将给定的 TopoDS_Shape 按照指定的渲染属性（通过 Prs3d_Drawer 提供）添加到 Prs3d_Presentation 中，从而实现形状的着色显示。具体来说，它会计算形状的表面法线，并基于光照模型计算每个像素的颜色值，以此来生成具有真实感的图像。这使得形状看起来更加立体和生动，有助于增强视觉效果，尤其是在展示复杂三维模型时。

2.2、函数签名

static void Add(
    const Handle(Prs3d_Presentation)& thePresentation,
    const TopoDS_Shape&                theShape,
    const Handle(Prs3d_Drawer)&        theDrawer
);

2.3、参数说明

参数	类型	作用
thePresentation	Handle(Prs3d_Presentation)	输出容器：用于接收生成的图形图元（如三角形、边线等）。最终由 AIS 或 V3d 渲染系统绘制到视图中。
theShape	const TopoDS_Shape&	输入几何：待显示的拓扑形状。通常应包含面（face）或体（solid），否则可能无内容可渲染。
theDrawer	Handle(Prs3d_Drawer)	渲染属性配置器：控制着色外观，包括： • 面颜色（FaceBoundaryDraw()、FaceAspect()->SetColor()） • 是否显示边线（IsWireFrameOnShaded()） • 材质（ShadingAspect()->SetMaterial()） • 网格精度（通过 HLRAngle、Discretization 等间接影响）

2.4、工作原理

• 检查三角剖分：若 theShape 的面尚未三角化（即没有 Poly_Triangulation），则自动调用 BRepMesh_IncrementalMesh 进行离散化（使用 theDrawer 中的精度参数）。
• 遍历所有面： 对每个 TopoDS_Face，提取其三角网格（Poly_Triangulation）和节点法向（如有）。
• 构建图形图元：
  • 使用 Graphic3d_ArrayOfTriangles 添加三角面片。
  • 若启用了“Shaded with edges”（即 theDrawer->IsWireFrameOnShaded() 为 true），还会额外添加边线（调用 StdPrs_WFDeflectionShape 或类似逻辑）。
• 应用材质与颜色：从 theDrawer->ShadingAspect() 获取材质和颜色，应用于生成的图元。
• 添加到 Presentation：将所有图元加入 thePresentation，供后续渲染使用。