OpenSceneGraph + 符号 + 渲染器管线
第一篇：OpenSceneGraph 场景图与「Symbol + Renderer」管线
摘要
本文基于实际工程，说明如何以OpenSceneGraph（OSG）为渲染底座，将业务侧的SceneObject + Symbol与FeatureLayerRenderer解耦，实现点、线、面、外部网格等多类数据到可绘制 OSG 子图的统一出口，并说明与每帧 UPDATE 回调（FeatureUpdater）、要素调度器（FeatureDispatcher）的衔接关系。
1. 设计目标
- 数据与绘制分离：场景对象只表达「是什么、几何/范围/符号」，不直接散落
addChild。 - 一类图层一个渲染器：FeatureLayerRenderer集中实现「带符号的场景对象 →
osg::Node/StateSet」。 - 与瓦片模型路径区分：外部网格（osgb 等）在工程注释中明确走要素调度器，与瓦片模型调度不同入口，避免两套需求混在同一套巨型函数里。
2. 核心类职责（与工程对应）
| 类/模块 | 职责 |
|---|---|
| SceneObject/ 派生类（如SceneMeshModelImp） | 业务侧场景对象；通过doSymbolic等参与生成 OSG 子图；网格可关联Model或文件路径。 |
| Symbol/MeshModelSymbol等 | 描述显示样式、资源 URL、格式枚举等，是符号化输入。 |
| FeatureLayerRenderer | 一个要素图层一个实例；提供symbolScenePoint/Line/…/symbolScenePointModel等，将符号落到具体节点。 |
| FeatureDispatcher | 要素与临时对象的调度、异步加载与渲染更新操作的生产；与FeatureLayerRenderer强关联。 |
| FeatureUpdater | 实现osg::NodeCallback，在UPDATE_VISITER中调用FeatureDispatcher::updateScene(node, nv)，驱动每帧对节点与调度的消费。 |
3. 网格模型（osgb 等）在管线的位置（文字流程）
- 上层为场景对象设置MeshModelSymbol（含资源路径与类型，如 osgb）。
- 资源在IO 与调度链中加载后，符号化走SceneMeshModelImp::doSymbolic等。
- 解析到可绘制几何时，osgDB 可读格式由osgDB::readNodeFile进整棵子图，贴图由OSG 插件按文件引用加载；setOsgGeometry时用ComputeBoundsVisitor计算包围盒，供后续空间索引与视锥使用。
- 与FeatureLayerRenderer::symbolScenePointModel等衔接，将结果挂到要素用变换节点上。
说明：SceneMeshModelImp源文件头注释中写明了自顶至底的调用关系（FeatureUpdater → FeatureDispatcher → doSymbolic →symbolScenePointModel）。
4. 类图
5. 与 OSG 的绑定方式（每帧更新）
- FeatureUpdater挂在getFeatureLayersRootNode()上；仅在UPDATE遍历时把控制权交给FeatureDispatcher，避免在业务线程里随意改子图。
- 与第二篇的FUT_Add 批处理、NodeTreeManager等共同构成对场景图写入的纪律。
6.典型踩坑
1. 把「能读文件」当成「能显示」
外部格式走osgDB::readNodeFile时，常误以为失败只在返回值里。工程里还依赖读入后包围盒/范围（例如用ComputeBoundsVisitor或等价逻辑）来驱动后续调度和空间索引。若路径、插件、工作目录或贴图相对引用异常，子图可能半空、半显示或范围无效，表现为「加载成功却不入树/不调度/相机跳不过去」。心得：在符号化与设置几何之后，显式检查包围体是否有效，并与「临时对象先不入八叉、加载后再入」的设计对齐。
2. 在错误线程/错误时机改场景图FeatureUpdater只在UPDATE 访问器里进入要素调度的updateScene；业务侧若在线程里直接对根节点addChild，容易与 OSG 的遍历/裁剪并发。心得：挂接、增删、替换尽量走已有队列/更新阶段；需要短时图操作时用节点管理器/操作对象那套路径，避免「哪里方便哪里改树」。
3. 重复addChild与「调度还没跟上」
工程注释里曾出现「初始化完成的对象重复添加、更新阶段先removeChild再add」的临时权宜。这通常来自同对象多次进入路径（例如重入调度、或加载完成与可见性刷新各触发一次）。心得：一次对象唯一渲染资源与一次挂接应对齐状态机；排查时谁在什么状态下又投递了一次。
4. 符号变了但图没变
符号与几何分离时，容易出现只改Symbol没触发doSynchronize/ 渲染器重新符号化。mesh 路径还涉及是否重新读文件/复用子图。心得：符号改变要落到「重新走符号化或明确的替换算子」上，并留意高亮/普通两套资源是否切换干净。
5. 贴图/路径
注释写明 osgb 等由插件按文件内引用解析贴图，本层不强制setImage。坑往往在工作目录、大小写、中文路径、倾斜摄影目录结构。心得：在测试环境固定「数据根目录 + 与 osgb 的相对关系」，必要时在符号或加载层做根路径统一，而不是在 UI 里写死一串绝对路径。
7.参数调优心得
1. 要素侧 LRU（如FeatureLRUCache）容量
代码里为节点缓存设过默认容量（数百量级）并可调。偏小：高要素量或频繁进离视区时，反复符号化/建节点，CPU 和 GC（引用计数/分配）都会抖。偏大：常驻显存/内存上升，换页时反而卡。心得：在目标机器上压测「相机拖动摇摆 + 同图层」，看帧时间方差与峰值内存，在「很少重复访问」的图层适当关小或关缓存；在「同一批对象反复出现」的场景给足容量。
2. 与调度取消令牌的关系
临时对象加载路径里，曾对是否取消调度令牌做过专门取舍（大模型加载中不被错误取消）。调优时若发现「一转动相机，加载被掐断」，检查与CancellationToken相关的策略是否过激进；若发现「切场景仍占满 IO」，看是否应取消的没取消。
3. 包围盒与「先不挂索引」
对 mesh，若初值无有效范围，会走稍后再进八叉的路径。调优不是调一个魔法数字，而是保证读入后尽快得到稳态包围（大模型、动画节点、变 LOD 的盒是否稳定）。若拾取/裁剪异常，优先查盒与进树时机是否一致。
4. 日志与符号化成本
工程里曾把日志等级在要素相关构造里收紧到偏错误级，以减轻热点路径开销。心得：发布版关 debug 洪泛；自己排查符号化慢时，单点计时比全局日志更有用（读盘 vsreadNodevs 合并到一层 Transform）。
5. 与第二、三篇的联动FeatureLayerRenderer这一层不宜为省一次调用而缓存「跨类型错误」的osg::Node；正确缓存尽量落在LRU或明确的生命周期里（见第三篇的 LRU 与 key 设计）。调优是全链路的，不是只调一个「渲染器开关」。
8. 关键词
OpenSceneGraph、场景图、符号化、FeatureLayerRenderer、SceneMeshModelImp、FeatureDispatcher、FeatureUpdater