《VulkanSceneGraph 1.1.16 源码深度解析》第三章 Visitor 体系与遍历语义:267 个 apply 的组织方式
源码基线:VulkanSceneGraph 1.1.16 本章对应模块:
include/vsg/core/(Visitor.h、ConstVisitor.h、visit.h、Object.h的accept/traverse) 前置章节:第一章 1.5(Inherit的 CRTP)、1.10(一帧的纵切面)
3.0 一个 accept 背后的七次间接跳转
先看一行最普通的代码。你在 VSG 里想找出场景中所有的相机,于是:
auto findCameras = vsg::FindCameras::create();
scene->accept(*findCameras);
这行代码的语义谁都能说清楚:"遍历场景,把相机收集起来"。但如果你问一句"它到底执行了哪些函数调用、跳了几次虚表",多数人答不上来。而这个数字恰好决定了三件事:为什么 VSG 要写 1156 行几乎重复的 Visitor.cpp、为什么 RecordTraversal 不肯继承 Visitor、为什么给 Visitor 加一个重载是 ABI 破坏。
从 include/vsg/core/Inherit.h 开始。每个用 Inherit 派生的类,都自动获得三个 accept 重写:
// include/vsg/core/Inherit.h:70
void accept(Visitor& visitor) override { visitor.apply(static_cast<Subclass&>(*this)); }
void accept(ConstVisitor& visitor) const override { visitor.apply(static_cast<const Subclass&>(*this)); }
void accept(RecordTraversal& visitor) const override { visitor.apply(static_cast<const Subclass&>(*this)); }
拿一个具体的类展开。假设 scene 的实际类型是 vsg::Group:
scene->accept(*findCameras)先做重载决议:静态类型是ref_ptr<Node>(或Node*),实参是FindCameras&,能匹配的只有accept(Visitor&),于是编译器生成一次对Object::accept(Visitor&)这个虚函数的调用。- 运行期虚分派到
Inherit<Object, Group>::accept(Visitor&)(Group的继承链是Group → Node → Object,accept只被Inherit实现一次,所有派生类共用同一份机器码,但虚表槽指向它)。 - 这个函数体里是
visitor.apply(static_cast<Group&>(*this))。注意:visitor的静态类型是Visitor&,实参的静态类型是Group&,所以重载决议在编译期就选中了Visitor::apply(Group&)。 apply是虚函数且非限定调用,所以仍然是一次虚分派:重写了就跳过去,没重写就进Visitor::apply(Group&),其函数体只有一句apply(static_cast<Node&>(value));。同一套动作在Node&上重演一次,才到Object&。Visitor::apply(Object&)是空函数体。如果FindCameras重写了它,那么在第 5 步就跳进FindCameras::apply(Object&),函数体是:
// src/vsg/app/Camera.cpp:58
void FindCameras::apply(Object& object)
{
_objectPath.push_back(&object);
object.traverse(*this); // 又一次虚分派:traverse(Visitor&)
_objectPath.pop_back();
}
object 的静态类型是 Object&,traverse 是 Object 的虚函数,Group 用 t_traverse 重写了它:
// include/vsg/nodes/Group.h:48
template<class N, class V>
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children) child->accept(visitor);
}
到这里,Group 的 children 才被枚举,每个 child 重新回到第 1 步。
一次 accept 的完整账:1 次虚分派(accept)+ 若干次虚分派(apply 链,跳数取决于你的重写位置)+ 1 次虚分派(traverse)。如果 FindCameras 只重写了 apply(Object&),那么一个 Group 节点要走 4 次间址(accept→apply(Group)→apply(Node)→apply(Object))再加 1 次 traverse。而一个 vsg::ViewportState 要走 7 次 apply 调用(连 accept 一起算是 8 次)——因为它的继承链是 ViewportState → GraphicsPipelineState → StateCommand → Command → Compilable → Node → Object,6 条边才到 Object。
把 267 个 apply 参数类型按"从自己到 Object 的继承边数"统计一遍,分布是这样的:
到 Object 的边数 | 类型数 | 代表类型 | apply 调用次数 | 含 accept 的总间址次数 |
|---|---|---|---|---|
| 0 | 1 | Object | 1 | 2 |
| 1 | 30 | Node、Data、Viewer、GraphicsPipeline、UIEvent | 2 | 3 |
| 2 | 156 | Group、Transform、Command、Light、127 个 Value/Array 别名 | 3 | 4 |
| 3 | 27 | StateGroup、View、CommandGraph、InstanceNode、KeyEvent | 4 | 5 |
| 4 | 36 | MatrixTransform、Geometry、Draw、SecondaryCommandGraph | 5 | 6 |
| 5 | 8 | StateSwitch、BindGraphicsPipeline、GraphicsPipelineState | 6 | 7 |
| 6 | 9 | 九个管线状态类(ViewportState、RasterizationState 等) | 7 | 8 |
这张表是本章所有性能讨论的地基。请记住三个数字:典型节点 4–6 次间址,最深 8 次,而每增加一层继承就多一次可能预测失败的间接分支。
3.0.1 为什么这个数字值得一章的篇幅
为什么 Visitor.cpp 有 1156 行却几乎不做事? 266 个非空 apply 的函数体都只有一句 apply(static_cast<X&>(value)),作用是让"只关心 Data 的访问者"接住 Value/Array 共 127 个模板别名,而不必写 127 个重写。这条路径的入口是 virtual void apply(Data&);(include/vsg/core/Visitor.h:200),第一跳在 void Visitor::apply(Data& value)(src/vsg/core/Visitor.cpp:35)——它和相邻的 External、MipmapLayout 一样,只把参数转成 Object&。
为什么 RecordTraversal 另起炉灶,用 33 个非虚 apply(const X&)? 逐帧遍历的节点数是 10 万量级,每次多 3–6 次间接分支乘起来就是毫秒级。它靠一个 void apply(const Object& object);(include/vsg/app/RecordTraversal.h:116)兜底,同一批重载里还有 QuadGroup、TileDatabase 这些容器节点;未特化类型隐式转成 const Object& 后落到 object.traverse(*this)(src/vsg/app/RecordTraversal.cpp:126),而这行代码要先调 getCommandBuffer——只有当该类型的 traverse(RecordTraversal&) 被重写时才有下一步。
为什么补丁版本禁改虚表? Visitor 的虚表有 285 个槽位(267 个 apply + getInstrumentation + 16 个来自 Object 的虚函数 + 1 个析构槽)。getInstrumentation 的默认实现在 virtual Instrumentation* getInstrumentation() { return nullptr; }(include/vsg/core/Visitor.h:195):绝大多数访问者不插桩,但槽位必须存在,因为 InstrumentationNode 会调它。任何"加一个 apply 重载"的改动都会让后续槽位后移,用户的 Visitor 子类二进制立即失效。
3.0.2 本章的问题清单
本章只回答七个能落到行号上的问题:
accept里一句visitor.apply(static_cast<Subclass&>(*this))(include/vsg/core/Inherit.h:70)凭什么在 267 个重载里选中正确的那一个?- 决定"降级到谁"的既不是继承关系也不是虚分派,而是
static_cast的目标类型:CoordinateFrame转成Transform&、Geometry转成Command&(src/vsg/core/Visitor.cpp:629)。写错目标的后果是什么? Visitor::apply(Object&)是空函数体(src/vsg/core/Visitor.cpp:21),它是Objects、External这些根类型的降级终点;它与"不声明这个重载"的差别在哪?Object::traverse(Visitor&)声明为{},为什么遍历必须由访问者手写?RecordTraversal只有 33 个非虚重载,凭什么覆盖 267 种类型而不丢功能?Mask只有 64 位(include/vsg/core/Mask.h:20),traversalMask为什么要在访问者、View入口、CommandBuffer三处各存一份?- 漏写一个
apply为什么既不报错也不崩溃?override与cast<>各能挡住哪一半?
3.0.3 答案骨架
- 分派是"编译期重载决议 + 运行期虚分派"两次独立决议:
accept在编译期确定参数的静态类型(Subclass),apply的虚分派在运行期确定实际重写(include/vsg/core/Inherit.h:70)。 - 降级方向由转型目标写死:
CoordinateFrame走Transform&,Geometry走Command&(src/vsg/core/Visitor.cpp:629),所以"处理所有几何体"不能只写apply(Geometry&)。 - 默认不遍历:
Inherit只转发三个accept,一个traverse都不重写(include/vsg/core/Inherit.h:70),基类那份是空的——"访问到"与"下沉"是两件事。 - 子节点集合随访问者变化:
StateGroup的通用traverse走stateCommands再走children,RecordTraversal版本只走children(include/vsg/nodes/StateGroup.h:75)。 - 录制器的 33 个重载靠"状态交给栈":未特化类型走一次
const Object&兜底(include/vsg/app/RecordTraversal.h:116),状态由State栈差分。 - 掩码不是节点属性:
Mask是uint64_t(include/vsg/core/Mask.h:20),但只有View、Switch、Layer、RegionOfInterest、StateSwitch五处存了mask字段。 - 漏重载是静默降级:
is_compatible在Visitor里重写了(include/vsg/core/Visitor.h:491),RecordTraversal里没有,于是连cast<>也一起失效。
3.1 数字解剖:267 个 apply 是怎么排布的
include/vsg/core/Visitor.h 共 510 行,其中 267 行是 virtual void apply(X&); 声明。它们不是随意排列的,而是按类型族分段,每段一个注释标题:
| 分段 | 数量 | 类型族 | 为什么单独成段 |
|---|---|---|---|
| (无注释,文件开头) | 5 | Object、Objects、External、Data、MipmapLayout | 五个"根"类型,其他一切都从这里降级 |
// Values | 37 | 标量、向量、矩阵的 Value<T> 别名 | 描述符/UBO 里的单个值 |
// Arrays | 37 | 一维数组 | 顶点属性、索引、纹理数据的载体 |
// Array2Ds | 34 | 二维数组 | 纹理、图像 |
// Array3Ds | 19 | 三维数组 | 体数据 |
// Nodes | 30 | 场景图节点 | 遍历的主角 |
// text | 4 | Text、TextGroup、TextTechnique、TextLayout | 排版对象(Technique/Layout 不是节点) |
// animation | 8 | 动画与采样器 | Animation 不是节点,AnimationGroup 是 |
// Vulkan nodes | 47 | 命令、状态、管线、描述符、BufferInfo/ImageInfo | 最大的一段,直接映射 Vulkan 对象 |
// mesh shading classes | 3 | DrawMeshTasks* | 独立的扩展能力 |
// ui events | 25 | 事件层级 | Trackball、Keyboard 等访问者的输入 |
// utils | 1 | ShaderCompileSettings | 单个配置对象 |
// app | 16 | 相机、视图、命令图、投影/视矩阵 | 框架层对象 |
// general classes | 1 | FrameStamp | 帧信息 |
五个数字值得注意。
第一,Vulkan nodes 段有 47 个,比 Nodes 段的 30 个还多。 这和第一章 1.2 节"state/ 目录比 nodes/ 还大"是同一现象的两面:Vulkan 的状态是显式对象,显式对象就要有自己的类型和 apply。GraphicsPipeline 在 OpenGL 时代是"一个 ID + 一堆 glState 调用",在 Vulkan 里是 VkPipeline + VkPipelineLayout + 8 个 Vk*StateCreateInfo,于是九个状态类各占一个重载——它们恰好就是 3.0 节表格里跳数为 6 的那九个。
第二,Values 37 = Arrays 37,Array2Ds 34,Array3Ds 19。 二维/三维比一维少,是因为它们不支持 string、bool、block64/block128 这些做不成 VkFormat 的类型:Array2D 的存在意义就是"能映射成 VkImage",而 VkFormat 里没有 64 位块压缩的单通道格式。
第三,Value/Array 这四个模板没有用 Inherit 派生,accept 是在 Visitor.h 里补上的。 Visitor.h 文件末尾有四段:
// include/vsg/core/Visitor.h:495
template<typename T>
void Value<T>::accept(Visitor& visitor) { visitor.apply(*this); }
template<typename T>
void Array<T>::accept(Visitor& visitor) { visitor.apply(*this); }
template<typename T>
void Array2D<T>::accept(Visitor& visitor) { visitor.apply(*this); }
template<typename T>
void Array3D<T>::accept(Visitor& visitor) { visitor.apply(*this); }
去 include/vsg/core/Value.h 第 39 行看,Value 的声明是 class VSG_TEMPLATE_DECLSPEC Value : public Data——直接继承 Data,不是 Inherit<Data, Value<T>>。Array(Array.h 第 35 行)、Array2D、Array3D 同样如此。所以它们没有 Inherit 提供的 accept,必须自己声明:
// include/vsg/core/Value.h:80
// implementation provided by Visitor.h
void accept(Visitor& visitor) override;
void accept(ConstVisitor& visitor) const override;
原因在包含关系:Value.h 不能包含 Visitor.h(Visitor.h 要正向声明 267 个类型,其中就包括 Value 的别名),而在 Value.h 里内联定义 accept 又要求 Visitor 是完整类型才能做重载决议。定义放到 Visitor.h 末尾,实例化点也就落在那里。
第二个"手工补齐"的例子:Value 没有声明 accept(RecordTraversal&),于是继承 Object 的默认实现——visitor.apply(*this),参数隐式转成 const Object&,落到 RecordTraversal::apply(const Object&),traverse 为空,静默跳过。这是对的:录制阶段不需要描述符里的标量值。
这四个模板类同时暴露了 Data 家族的代价:因为不用 Inherit,create/clone/sizeofObject/className/is_compatible/accept 全要手写(Value.h 第 57–83 行),而 Inherit 版本只要 6 行。成因是模板实例化点:Inherit<Data, Value<T>> 会把 accept 定义在类体内,而 VSG 想把它推迟到 Visitor.h。代价是任何一处漏写(比如忘了 accept(ConstVisitor&))不报错,只在 ConstVisitor 遍历时静默落到 Data 分支。
顺带澄清:is_compatible 里的 typeid(Value) 在类模板内部指当前实例化,所以 cast<Value<vec4>>() 对 Value<vec3> 返回空。访问者不走 cast,只走 apply 重载链,不受影响。
第四,267 个声明分布在 13 个族里,但族与族之间没有继承关系。 apply(Group&) 和 apply(Geometry&) 是平级的虚函数,不存在"apply 的继承树"。类型族的层次完全由 apply 函数体的转型方向表达(Geometry 降级到 Command,Command 降级到 Compilable,Compilable 降级到 Node)。
第五,两份代码不共享任何一行。 ConstVisitor.h 同样 510 行、ConstVisitor.cpp 同样 1156 行。不用模板或宏生成的原因:虚表要求每个 apply 有独立槽位与独立函数地址,宏压得下源码、压不掉符号与调试信息。这是"源码重复换可调试性",代价是加一个重载必须两处同步——好消息是漏了会编译失败(Inherit::accept(ConstVisitor&) 会调用不存在的重载)。
3.1.1 虚表的实际大小
把 Object 的虚函数数清楚(include/vsg/core/Object.h 第 81–184 行):
| 来源 | 槽位数 |
|---|---|
sizeofObject、className、type_info、is_compatible | 4 |
clone、compare | 2 |
accept(Visitor&)、traverse(Visitor&) | 2 |
accept(ConstVisitor&)、traverse(ConstVisitor&) | 2 |
accept(RecordTraversal&)、traverse(RecordTraversal&) | 2 |
read、write | 2 |
_attemptDelete | 1 |
| 析构函数(Itanium ABI 下占 2 槽:complete + deleting) | 2 |
Object 小计 | 17 |
Visitor::getInstrumentation | 1 |
Visitor::apply × 267 | 267 |
Visitor 合计 | 285 |
285 × 8 字节 = 2280 字节。这个 vtable 每个 Visitor 派生类一份(不是每个实例一份),所以内存开销可以忽略;真正的成本在二进制体积:每个 Visitor 子类的 .o 里都有一份 2.2KB 的只读数据,加上 Visitor.cpp 里 267 个函数的机器码(每个约 15–25 字节:一次 mov 取 this、一次 mov 取参数、一次间接跳转)。Visitor.cpp 编译出的目标文件里,这 267 个函数合计约 5–7KB 代码,是"零成本抽象"的入场费。
这里有一个容易被忽略的事实:apply(Object&) 是空函数,编译器会把它优化成 ret。但优化不掉虚表槽位——它必须存在,因为 Inherit::accept 不保证用户重写了它。同理,266 个转型函数里,绝大部分在真实程序里从未被调用(比如 apply(wstringValue&)),但它们都在虚表里占位,都在 .so 里占代码。这是"封闭访问者集合"的静态成本:267 个槽位 vs 你实际用到的 5–10 个。
3.2 1156 行里的 266 行是同一句话
打开 src/vsg/core/Visitor.cpp,你会看到一种近乎荒诞的重复。以下是从文件里连续摘出的三段(省略了中间几十个类似的):
void Visitor::apply(Objects& value) { apply(static_cast<Object&>(value)); }
void Visitor::apply(External& value) { apply(static_cast<Object&>(value)); }
void Visitor::apply(Data& value) { apply(static_cast<Object&>(value)); }
void Visitor::apply(MipmapLayout& value) { apply(static_cast<Object&>(value)); }
void Visitor::apply(vec3Value& value) { apply(static_cast<Data&>(value)); }
void Visitor::apply(dvec3Value& value) { apply(static_cast<Data&>(value)); }
void Visitor::apply(Group& value) { apply(static_cast<Node&>(value)); }
void Visitor::apply(LOD& value) { apply(static_cast<Node&>(value)); }
void Visitor::apply(MatrixTransform& value) { apply(static_cast<Transform&>(value)); }
void Visitor::apply(Geometry& value) { apply(static_cast<Command&>(value)); }
用脚本统计过:267 个函数,266 个的函数体恰好是一句 apply(static_cast<X&>(value));,剩下 1 个是空的 apply(Object&)。 没有例外,没有注释,没有条件判断。
这 266 行是整章最需要读懂的地方。它们做的事情,用一句话概括:
把"我没有为这个类型写处理逻辑"这件事,翻译成"去问我上一层的处理逻辑"。
3.2.1 一次转型,两重语义
apply(static_cast<Group&>(value)); 这一句里藏着两个独立的机制,必须分开看。
机制一:static_cast 决定"问谁"。 它把 Group& 转成 Node&,于是重载决议选中 apply(Node&) 这个槽位。如果写成 static_cast<Object&>,就跨过 Node 直接问 Object,那么用户重写的 apply(Node&) 就永远接不到 Group——这是本章第一个真实陷阱,3.12 节还有更多。
机制二:非限定调用决定"怎么问"。 apply(...) 没有写 this->apply(...),也没有写 Visitor::apply(...),所以它是虚调用。因此"问上一层"不是静态解析到 Visitor::apply(Node&),而是动态分派到实际类型上最深的那个 apply(Node&) 重写。
这两个机制组合起来,才让"部分重写"成为可能。举例:你写了一个访问者,只重写了 apply(Node&):
struct CountNodes : public vsg::Visitor
{
size_t count = 0;
void apply(vsg::Node& node) override
{
++count;
node.traverse(*this);
}
};
现在遍历一棵含 Group、MatrixTransform、Geometry 的树。对 Group:
accept选中apply(Group&)→ 你没重写,走Visitor::apply(Group&)→apply(static_cast<Node&>)→ 虚分派命中你的CountNodes::apply(Node&)✅
对 MatrixTransform:
accept选中apply(MatrixTransform&)→ 走Visitor::apply(MatrixTransform&)→apply(static_cast<Transform&>)→ 你没重写apply(Transform&),走Visitor::apply(Transform&)→apply(static_cast<Group&>)→ 走Visitor::apply(Group&)→apply(static_cast<Node&>)→ 命中你的重写 ✅
四次虚调用之后,你的 apply(Node&) 收到了所有节点。这就是 266 行转型代码的唯一价值:把"重写任意一层"变成"覆盖该层以下的所有类型"。 换句话说,Visitor 的重载集合是一棵以继承关系为形状的责任链,每个 apply 是链上的一环,缺省行为是"往下传"。
反过来看,如果你重写了 apply(Group&) 而没调用 traverse,那么整棵子树都不会被访问——因为 apply(Group&) 是 Group 的入口,你不往下走,链就断了。这是第二个真实陷阱,比第一个更常见。
3.2.2 为什么是"降级"而不是"升级"
为什么默认是降级,而不是空、也不是自动 traverse?空实现会让"只重写 apply(Node&)"的访问者收不到任何 Group,267 个类型必须逐个精确重写;自动 traverse 则让"只看容器本身"的意图无法表达,而 C++ 没有"调用父类实现但跳过其中一行"的语法。降级是唯一能让部分特化成立的默认行为,遍历是唯一能让访问者控制顺序的行为——把两者分开才能自由组合:
// 只要数量,不要顺序控制
void apply(Object& object) override { ++count; object.traverse(*this); }
// 要前序+后序,自己管栈
void apply(Group& group) override
{
onEnter(group);
group.traverse(*this);
onExit(group);
}
3.2.3 数据:267 个函数体的分类
把 266 句转型按目标类型归类,可以看出降级方向严格跟随继承关系:
| 转型目标 | 数量 | 典型来源 |
|---|---|---|
Data& | 127 | 37 Value + 37 Array + 34 Array2D + 19 Array3D |
Object& | 30 | Objects、External、Node、BufferInfo、ImageInfo、Viewer、FrameStamp |
Command& | 21 | Draw、DrawIndexed、BindVertexBuffers、ClearAttachments、ResetQueryPool、DrawMeshTasks* |
Node& | 17 | Group、LOD、Switch、Light、Compilable 等 |
WindowEvent& | 10 | 六个窗口事件 + KeyEvent/PointerEvent/TouchEvent/DropEvent 的父类 |
GraphicsPipelineState& | 9 | 九个管线状态类 |
StateCommand& | 8 | BindDescriptorSet(s)、BindViewDescriptorSets、Bind*Pipeline |
Group& | 7 | StateGroup、Transform、CommandGraph、SecondaryCommandGraph、RenderGraph、View、CullGroup |
ViewMatrix& | 4 | LookAt、LookDirection、RelativeViewMatrix、TrackingViewMatrix |
ProjectionMatrix& | 4 | Perspective、Orthographic、RelativeProjection、EllipsoidPerspective |
Light& | 4 | 四种光源 |
AnimationSampler& | 4 | 四种采样器 |
UIEvent& / TouchEvent& / PointerEvent& / DropEvent& | 各 3 | 事件层级的中间层 |
Transform& | 2 | MatrixTransform、CoordinateFrame |
KeyEvent& / Descriptor& / Compilable& | 各 2 | 中间层 |
CommandGraph& | 1 | SecondaryCommandGraph |
这张表能直接回答"重写哪一层最划算",把相关行的数量加起来就是覆盖范围:
apply(Command&):21(直接降级)+ 8(StateCommand分支)+ 9(GraphicsPipelineState分支)= 38 个类型,是"处理所有命令"的正确落点。apply(Group&):7(直接降级)+ 2(Transform及其两个子类)= 9 个。Switch、Layer、DepthSorted不在其中,它们直接降级到Node&(3.2.6)。apply(Geometry&):只有Geometry自己。VertexDraw、VertexIndexDraw、InstanceDraw走Command分支,不经过Geometry(3.2.4)。apply(Node&):17 个直接降级到Node的类型及其全部后代,统计意义上是"所有场景图节点"。
规律:覆盖范围 = 该行数量 + 以它为祖先的所有行数量之和。想少写重载又覆盖够全,就往上找一层;想精确处理某一类,就往下找。
3.2.4 一个真实的层级陷阱:Geometry 不是"所有几何体"
vsg::Geometry 的继承链是 Geometry → Command → Compilable → Node → Object(跳数 4)。而 vsg::VertexDraw 是 VertexDraw → Command,不经过 Geometry。Visitor.cpp 里三个函数暴露了这一点:
void Visitor::apply(Geometry& value) { apply(static_cast<Command&>(value)); }
void Visitor::apply(VertexDraw& value) { apply(static_cast<Command&>(value)); }
void Visitor::apply(VertexIndexDraw& value) { apply(static_cast<Command&>(value)); }
三个平级的转型。所以"我要处理所有几何体"写成 apply(Geometry&) 是错的——VertexDraw 和 VertexIndexDraw 是更原始的绘制命令,它们绕过了 Geometry 的"顶点+索引+绘制"聚合。正确做法是重写 apply(Command&) 再自己判断,或者三个都重写。
这不是 VSG 的设计缺陷,而是 Vulkan 的对象模型:VertexDraw 对应 vkCmdDraw,VertexIndexDraw 对应 vkCmdDrawIndexed,Geometry 是"把两者打包成一个可复用的复合对象"。它们在 API 层就是平级的。访问者的继承树必须与 Vulkan 的对象树同构,否则降级关系就会说谎。
3.2.5 值类型与数组:54 个"零信息"转型的坐标
Values/Arrays/Array2Ds/Array3Ds 四段的 127 个重载全部降级到 Data&,两个家族的函数体逐字对称(ConstVisitor 只是多了 const)。下表给抽样坐标,左侧类型名就是被转型的静态类型:
| 类型 | 降级到 | Visitor.cpp | ConstVisitor.cpp |
|---|---|---|---|
stringValue | Data& | Visitor.cpp:49 | ConstVisitor.cpp:49 |
vec3Value | Data& | Visitor.cpp:81 | ConstVisitor.cpp:81 |
dvec3Value | Data& | Visitor.cpp:93 | ConstVisitor.cpp:93 |
bvec3Value | Data& | Visitor.cpp:105 | ConstVisitor.cpp:105 |
ubvec4Value | Data& | Visitor.cpp:121 | ConstVisitor.cpp:121 |
svec3Value | Data& | Visitor.cpp:129 | ConstVisitor.cpp:129 |
ivec4Value | Data& | Visitor.cpp:157 | ConstVisitor.cpp:157 |
uivec4Value | Data& | Visitor.cpp:169 | ConstVisitor.cpp:169 |
mat4Value | Data& | Visitor.cpp:189 | ConstVisitor.cpp:189 |
dmat4Value | Data& | Visitor.cpp:193 | ConstVisitor.cpp:193 |
stringArray | Data& | Visitor.cpp:202 | ConstVisitor.cpp:202 |
ubyteArray | Data& | Visitor.cpp:210 | ConstVisitor.cpp:210 |
vec3Array | Data& | Visitor.cpp:242 | ConstVisitor.cpp:242 |
dvec3Array | Data& | Visitor.cpp:254 | ConstVisitor.cpp:254 |
bvec4Array | Data& | Visitor.cpp:270 | ConstVisitor.cpp:270 |
ivec4Array | Data& | Visitor.cpp:294 | ConstVisitor.cpp:294 |
usvec3Array | Data& | Visitor.cpp:314 | ConstVisitor.cpp:314 |
uivec4Array | Data& | Visitor.cpp:330 | ConstVisitor.cpp:330 |
mat4Array | Data& | Visitor.cpp:334 | ConstVisitor.cpp:334 |
block64Array | Data& | Visitor.cpp:342 | ConstVisitor.cpp:342 |
block128Array | Data& | Visitor.cpp:346 | ConstVisitor.cpp:346 |
ubyteArray2D | Data& | Visitor.cpp:359 | ConstVisitor.cpp:359 |
vec4Array2D | Data& | Visitor.cpp:395 | ConstVisitor.cpp:395 |
block128Array2D | Data& | Visitor.cpp:487 | ConstVisitor.cpp:487 |
vec3Array3D | Data& | Visitor.cpp:532 | ConstVisitor.cpp:532 |
block64Array3D | Data& | Visitor.cpp:564 | ConstVisitor.cpp:564 |
block128Array3D | Data& | Visitor.cpp:568 | ConstVisitor.cpp:568 |
这张表的用处是"定位"而不是"记忆":想在 vec3Array 上做特化,只要看它的降级目标是 Data&,就知道重写 apply(Data&) 能接住全部 127 个,而重写 apply(vec3Array&) 只接住它自己。
3.2.6 节点与命令:转型目标不等于继承父类
把"降级到谁"逐条读出来,会发现一个与直觉不符的事实:Switch、Layer、DepthSorted、QuadGroup、LOD、PagedLOD、RegionOfInterest 的 apply 都直接降级到 Node&,跳过了 Group&——尽管其中前四个都有 children。所以"重写 apply(Group&) 覆盖所有带子节点的类型"是错的。
| 类型 | 降级到 | Visitor.cpp | ConstVisitor.cpp |
|---|---|---|---|
QuadGroup | Node& | Visitor.cpp:593 | ConstVisitor.cpp:593 |
CullGroup | Group& | Visitor.cpp:609 | ConstVisitor.cpp:609 |
CullNode(同段 CullGroup 走 Group&) | Node& | Visitor.cpp:613 | ConstVisitor.cpp:613 |
DepthSorted | Node& | Visitor.cpp:641 | ConstVisitor.cpp:641 |
Layer | Node& | Visitor.cpp:645 | ConstVisitor.cpp:645 |
Switch | Node& | Visitor.cpp:653 | ConstVisitor.cpp:653 |
RegionOfInterest | Node& | Visitor.cpp:681 | ConstVisitor.cpp:681 |
InstanceNode | Compilable& | Visitor.cpp:685 | ConstVisitor.cpp:685 |
InstanceDraw | Command& | Visitor.cpp:689 | ConstVisitor.cpp:689 |
InstanceDrawIndexed | Command& | Visitor.cpp:693 | ConstVisitor.cpp:693 |
Joint | Node& | Visitor.cpp:751 | ConstVisitor.cpp:751 |
Vulkan 对象段(// Vulkan Objects):BufferInfo、ImageInfo | Object& | Visitor.cpp:760、Visitor.cpp:764 | ConstVisitor.cpp:760 |
StateSwitch | StateCommand& | Visitor.cpp:784 | ConstVisitor.cpp:784 |
BindDescriptorSets | StateCommand& | Visitor.cpp:800 | ConstVisitor.cpp:800 |
BindGraphicsPipeline | StateCommand& | Visitor.cpp:836 | ConstVisitor.cpp:836 |
DrawMeshTasks | Command& | Visitor.cpp:953 | ConstVisitor.cpp:953 |
DrawMeshTasksIndirect | Command& | Visitor.cpp:957 | ConstVisitor.cpp:957 |
DrawMeshTasksIndirectCount | Command& | Visitor.cpp:961 | ConstVisitor.cpp:961 |
ShaderCompileSettings | Object& | Visitor.cpp:1075 | ConstVisitor.cpp:1075 |
SecondaryCommandGraph | CommandGraph& | Visitor.cpp:1092 | ConstVisitor.cpp:1092 |
RenderGraph | Group& | Visitor.cpp:1096 | ConstVisitor.cpp:1096 |
LookAt | ViewMatrix& | Visitor.cpp:1112 | ConstVisitor.cpp:1112 |
Perspective | ProjectionMatrix& | Visitor.cpp:1132 | ConstVisitor.cpp:1132 |
Orthographic | ProjectionMatrix& | Visitor.cpp:1136 | ConstVisitor.cpp:1136 |
EllipsoidPerspective | ProjectionMatrix& | Visitor.cpp:1144 | ConstVisitor.cpp:1144 |
FrameStamp(// general classes 段,前一段是 ProjectionMatrix) | Object& | Visitor.cpp:1153 | ConstVisitor.cpp:1153 |
由此可以推出三条实操结论,都不需要读文档,只需要看表:
Switch/Layer/DepthSorted必须自己实现t_traverse,因为它们不在Group的降级链上,Group::t_traverse覆盖不到它们。Switch的t_traverse直接读visitor.traversalMask与visitor.overrideMask(include/vsg/nodes/Switch.h:60),Layer的三份traverse各带一次同样的判断(include/vsg/nodes/Layer.h:40)。Switch与Layer的父类都是Node而不是Group(include/vsg/nodes/Switch.h:24、include/vsg/nodes/Layer.h:22),所以"给子节点挂mask的容器"根本不是Group的子类——这与 3.5.2 节"掩码绑定在带掩码的容器上"是同一个事实的两面。Viewer不在Node链上:apply(Viewer&)降级到Object&,紧接着的ViewMatrix段也一样降级到Object&(src/vsg/core/Visitor.cpp:1104),所以重写apply(Node&)的访问者永远见不到两者。
3.3 双分派:为什么 accept 藏在 Inherit 里
Visitor 模式在 C++ 里的标准实现是"双分派"(double dispatch):操作的类型和对象的类型都要参与函数选择,而 C++ 只有单分派(虚函数按对象类型分派)。解法是把其中一个维度变成重载决议:
对象类型 → 虚函数 accept() → 静态类型已知,重载决议选中 apply(ConcreteType&)
accept 的函数体里,*this 的静态类型是具体子类(因为 Inherit 的模板参数 Subclass 就是它),所以 visitor.apply(static_cast<Subclass&>(*this)) 能在编译期选中正确的重载。这就是双分派的全部秘密:一个虚函数 + 一次重载决议。
3.3.1 三种实现路线的成本对比
| 方案 | 对象侧代码 | 访问者侧代码 | 每次访问的间址次数 | 新增类型的成本 |
|---|---|---|---|---|
手写 accept(每个类一份) | 每类 1 行 × 3 个 visitor 家族 | 每类 1 个 apply | 1 + 降级链 | 改 3 处(易漏) |
表驱动(type_index → std::function) | 0 | 注册函数 | 1 次哈希 + 1 次间接 | 运行时注册,无编译期检查 |
CRTP accept + 虚 apply 链(VSG) | 0(Inherit 一份) | 每类 1 个 apply | 1 + 降级链 | 改 2 处(Visitor/ConstVisitor),编译期可查 |
VSG 选第三种。收益:accept 的 267 份实现被压成 1 份模板,不可能漂移;对象的 accept 自动跟着 Inherit 的模板参数走,新增一个节点头文件时不需要碰 Object.h。代价:apply 仍需在 Visitor 和 ConstVisitor 两处各声明一次,且新增一节会同时破坏两个类的 ABI。
第一种方案(手写 accept)看起来更"显式",但 267 个类 × 3 个家族 = 801 个手写函数,其中任何一个写错(比如复制粘贴后忘了改 static_cast 的目标类型),症状是访问者收到错误的类型——一个 Group 被当成 Node 处理,通常不崩溃,只是行为诡异。CRTP 把这类错误从"运行期诡异"变成了"不可能发生"。
3.3.2 缺一个 apply 会怎样:静默降级
这是 Visitor 体系最危险的地方,必须单独说。
假设你写了一个自定义节点:
class MyNode : public vsg::Inherit<vsg::Group, MyNode>
{
public:
// 忘了在 Visitor 里加 apply(MyNode&)
};
编译通过。运行不报错。你的访问者如果重写了 apply(Object&),它会在 MyNode 上被调用,参数被当成 Object&——object.traverse(*this) 依然会遍历 MyNode 的 children(因为 traverse 是虚函数,走的是 Group::t_traverse),所以连"遍历中断"这种明显症状都没有。你只会发现"我明明写了 apply(MyNode&)……哦,我根本没写"。
对比一下 dynamic_cast 风格的实现:if (auto myNode = obj.cast<MyNode>()) 会返回空,你能立刻察觉。而 Visitor 的缺省降级把"类型不被认识"变成了"被当成父类处理",这是一种有意的、但会吞掉 bug 的设计。
VSG 自己的规避手段是:在需要精确定位的场合,用 cast<> 而不是靠 apply 的重载。WindowResizeHandler 里的 visit 去重、CompileTraversal 里的 obj.cast<Window>(),都是这个思路。
3.3.3 Object::accept 的三个重载与"非 Inherit 类"
Object.h 第 109–116 行——三对 accept/traverse 夹在 clone(靠 CopyOp 的 duplicates 表决定是否复制)与 read/write 之间:
// include/vsg/core/Object.h:109
virtual void accept(Visitor& visitor);
virtual void traverse(Visitor&) {}
virtual void accept(ConstVisitor& visitor) const;
virtual void traverse(ConstVisitor&) const {}
virtual void accept(RecordTraversal& visitor) const;
virtual void traverse(RecordTraversal&) const {}
注意三个细节。
第一,accept 不是纯虚函数。 它有定义(Object.cpp 第 124–137 行),做的事情就是 visitor.apply(*this)——把对象当成 Object 提交。所以一个不用 Inherit 派生的类,只要继承 Object,就能被访问,只是永远被当成 Object。RecordTraversal 正是这样:它继承 Object 但不用 Inherit,自己声明 create()、sizeofObject()、className(),因此它的 accept 是 Object 的默认实现(把 RecordTraversal 自己当成 Object 提交),而它自己作为访问者时用的是那 33 个非虚 apply。
第二,traverse 的默认实现是空的内联函数,而且是 virtual。空函数体 + virtual 看起来矛盾(为什么不省掉这个槽位?),但它是必需的:RecordTraversal::apply(const Object&) 的函数体是 object.traverse(*this),这条路径依赖 traverse 是虚函数,才能让 Group、Commands 等容器类被"通用兜底"正确处理。如果 traverse 不是虚函数,RecordTraversal 就必须为每个容器类型单独写 apply。
第三,三个家族各自有一套 accept/traverse,共 6 个虚函数槽位。 这是 Visitor 的 285 槽位里最容易被忽视的 6 个:它们让"同一个对象、三种访问语义"成为可能,代价是每个 Object 多 3 个槽位(48 字节的 vtable)。
3.4 traverse 与 accept 的分离:遍历为什么不是自动的
在 OSG 里,NodeVisitor::apply(osg::Node&) 的默认实现会调用 traverse();在 VSG 里,Visitor::apply(Node&) 的默认实现是降级,遍历完全由访问者决定。这个差异是三章内容里最影响写代码手感的一条。
3.4.1 为什么要分开
先看如果合并会失去什么。假设 apply(Group&) 默认遍历,那么:
- 无法实现"只访问不下降"。你想统计场景里有几个
Group,但不关心子节点结构?做不到,除非再写一个"不遍历"的开关。 - 无法在中途剪枝。视锥剔除需要在发现节点完全在视锥外时立刻返回,不进入子树。如果默认遍历,就必须先构造一个"禁止遍历"的状态再返回。
- 无法控制前序/后序。
traverse()只能插在apply的中间,你没法在"进入子树前"和"退出子树后"各做一件事(除非用栈 + 两个不同的apply,而这就是RecordTraversal的做法)。 - 无法重复遍历。同一个子树访问两遍(比如先算包围盒、再算变换)需要显式调用两次
traverse。
VSG 的答案是把两件事拆成两个虚函数:accept 决定"用哪个 apply",traverse 决定"下不下沉、下沉到谁"。默认 traverse 是空,所以默认不下沉;想下沉就自己写。
3.4.2 各节点族的 t_traverse
全库有 23 个头文件写了 static void t_traverse(grep -rn "static void t_traverse" include/ | wc -l)。它们不是同一个函数复制 23 次,而是同一套模板的四种写法,写法差异的每一处都对应一个语义约束。
grep -rn "static void t_traverse" include/ | wc -l # 23
第一种是标准 Group:模板函数 + 三个 traverse 重写,函数体只有五行。
// include/vsg/nodes/Group.h:48
template<class N, class V>
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children) child->accept(visitor);
}
void traverse(Visitor& visitor) override { t_traverse(*this, visitor); }
Commands 写出来一模一样,因为它的 children 也是"指针容器 + accept";区别只在元素类型是 ref_ptr<Command>,所以同一个模板实例化后命中的是 apply(Command&) 而不是 apply(Node&):
// include/vsg/commands/Commands.h:34
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children) child->accept(visitor);
}
第二种是"孩子外面还包一层"。LOD 的 children 元素是带屏幕占比与距离的 LOD::Child,所以要先取 node 再 accept——这一层间接不是笔误,它让 LOD 能在不改子节点类型的前提下附加元数据:
// include/vsg/nodes/LOD.h:56
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children) child.node->accept(visitor);
}
PagedLOD 与 LOD 同构,但多一个判空:分页加载完成前 child.node 是空的,accept 会直接解引用空指针:
// include/vsg/nodes/PagedLOD.h:65
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children)
{
if (child.node) child.node->accept(visitor);
}
}
第三种是"容器形状不同"。QuadGroup 只有 4 个孩子,用定长下标,连迭代器都不需要:
// include/vsg/nodes/QuadGroup.h:43
for (int i = 0; i < 4; ++i) node.children[i]->accept(visitor);
TileDatabase 只有一个 child,连循环都省了;判空仍然是必须的,因为瓦片库要异步加载:
// include/vsg/nodes/TileDatabase.h:93
static void t_traverse(N& node, V& visitor)
{
if (node.child) node.child->accept(visitor);
}
External 装的是 std::map<std::string, ref_ptr<Object>>,所以遍历键值对而不是数组——这是全库唯一一个容器是 map 的 t_traverse:
// include/vsg/core/External.h:38
static void t_traverse(O& object, V& visitor)
{
for (auto itr = object.entries.begin(); itr != object.entries.end(); ++itr)
{
// include/vsg/core/External.h:42
if (itr->second) itr->second->accept(visitor);
}
}
而它的第三个重写是空的:entries 里的东西在录制阶段一个都不用,连紧随其后的 custom 读写选项也与遍历无关。
// include/vsg/core/External.h:48
void traverse(RecordTraversal&) const override {}
第四种是"同一个类、两套子节点集合"。AnimationGroup 与 3.4.3 节的 StateGroup 是同一个套路:通用访问者走 animations 加 children,录制遍历只走 children。
// include/vsg/animation/AnimationGroup.h:36
static void t_traverse(N& node, V& visitor)
{
// include/vsg/animation/AnimationGroup.h:38
for (auto& animation : node.animations) animation->accept(visitor);
for (auto& child : node.children) child->accept(visitor);
}
void traverse(RecordTraversal& visitor) const override
{
for (auto& child : children) child->accept(visitor);
}
例外是 Layer:它没有 t_traverse,三个 traverse 各自把同一句掩码判断抄了一遍(include/vsg/nodes/Layer.h:38)。Switch 的 t_traverse 里带的是同一句判断,只不过作用对象是每个 child.mask(include/vsg/nodes/Switch.h:56):
// include/vsg/nodes/Switch.h:56
static void t_traverse(N& node, V& visitor)
{
for (auto& child : node.children)
{
if ((visitor.traversalMask & (visitor.overrideMask | child.mask)) != MASK_OFF) child.node->accept(visitor);
}
}
这 23 份模板函数还有第二个用途,藏在录制器里。RecordTraversal.cpp 顶部有一个开关:
// src/vsg/app/RecordTraversal.cpp:60
#define INLINE_TRAVERSE 0
它被 RecordTraversal::apply(const Group&) 用来二选一——打开时绕开虚函数直接调静态的 t_traverse,默认关闭(src/vsg/app/RecordTraversal.cpp:134):
// src/vsg/app/RecordTraversal.cpp:134
#if INLINE_TRAVERSE
vsg::Group::t_traverse(group, *this);
#else
group.traverse(*this);
#endif
也就是说,t_traverse 是为将来的非虚入口预留的中间层:价值是让三个 traverse 重写各自只有一行,代价是多一层调用——通常会被内联掉。
同一种"复制"还发生在 RecordTraversal 里:apply(const Switch&) 没有调 sw.traverse(*this),而是把 Switch::t_traverse 的掩码判断原样抄了一遍(src/vsg/app/RecordTraversal.cpp:291)。于是"改 Switch 的遍历语义"这件事必须改两处,而编译器不会提醒你漏了哪一处。
3.4.3 StateGroup:同一棵树,两套子节点集合
这是全章最值得记住的一个细节。include/vsg/nodes/StateGroup.h 第 67–78 行:
// include/vsg/nodes/StateGroup.h:67
static void t_traverse(N& node, V& visitor)
{
for (auto& sc : node.stateCommands) sc->accept(visitor);
// include/vsg/nodes/StateGroup.h:70
for (auto& child : node.children) child->accept(visitor);
}
void traverse(Visitor& visitor) override { t_traverse(*this, visitor); }
void traverse(ConstVisitor& visitor) const override { t_traverse(*this, visitor); }
void traverse(RecordTraversal& visitor) const override
{
for (auto& child : children) child->accept(visitor); // 注意:没有 stateCommands
}
同一个 StateGroup,对通用访问者会遍历"状态命令 + 子节点",对 RecordTraversal 只遍历"子节点"。 原因在 RecordTraversal::apply(const StateGroup&)(src/vsg/app/RecordTraversal.cpp 第 509–525 行):
// src/vsg/app/RecordTraversal.cpp:521
auto begin = stateGroup.stateCommands.begin();
auto end = stateGroup.stateCommands.end();
state->push(begin, end); // 状态在这里被压栈并录制
stateGroup.traverse(*this); // 只走 children
state->pop(begin, end); // 恢复
如果 traverse 也遍历 stateCommands,那么这些状态命令会被录制两遍:一次通过 state->push 内部的 record(),一次通过 accept 走到 RecordTraversal::apply(const Command&)。两遍的后果不是崩溃,而是每帧多出成百上千条冗余的 vkCmdBindPipeline/vkCmdBindDescriptorSets——命令缓冲区变大、GPU 前端多做无效工作。这类 bug 在性能分析里表现为"命令数比预期多一倍",而代码看起来完全正常。
这个细节教给我们一件事:traverse 的语义不是"遍历所有子对象",而是"遍历所有应该由这个访问者处理的对象"。子节点集合是访问者相关的。
3.4.4 遍历顺序与栈纪律
Group::t_traverse 是标准的前序深度优先:先处理自己(在 apply 里),再按 children 顺序递归。这意味着:
- 兄弟节点的访问顺序 ==
children数组顺序(确定性,对调试友好)。 - 父节点在子节点之前被
apply(前序),因此"进入子树前压栈、退出后弹栈"的写法天然成立。 - 没有后序钩子。想在子树访问完之后做事,必须自己写成:
void apply(vsg::Group& group) override
{
stack.push_back(computeSomething(group));
group.traverse(*this);
stack.pop_back(); // 这行就是"后序"
}
栈纪律是手动的,因此默认异常不安全。 如果 traverse 过程中抛异常(比如 Geometry 的 read 失败、cast 后解引用空指针),pop 不会执行,栈就永久偏移了。FindCameras、LoadPagedLOD 都是直接写 push/pop,没有保护——因为它们假设遍历不会抛异常。
Intersector 是全库唯一做了防护的访问者,用的是一种极简的 RAII(src/vsg/utils/Intersector.cpp 第 36–43 行):
// src/vsg/utils/Intersector.cpp:36
struct PushPopNode
{
Intersector::NodePath& nodePath;
PushPopNode(Intersector::NodePath& np, const Node* node) : nodePath(np) { nodePath.push_back(node); }
~PushPopNode() { nodePath.pop_back(); }
};
八行,构造压栈、析构弹栈,靠 C++ 的栈展开保证异常时也弹。每个 apply 的第一行就是 PushPopNode ppn(_nodePath, &node);。但它只保护了节点路径这一个栈,arrayStateStack、变换栈仍然是手工 emplace_back/pop_back。这是一处不一致:如果 statecommand->accept(*arrayState) 抛异常,路径会被正确弹出,arrayStateStack 却少弹一层,后续所有几何体的顶点数据都会用错的状态去解析。
如果你要写一个可能抛异常的访问者(比如在 apply 里读文件、解析 JSON),路径栈和所有状态栈都必须用 RAII guard,否则后续所有节点的路径/矩阵/状态都是错的。第 3.9 节给一个完整的写法。
3.4.5 apply(Object&) 两种流派
因为默认不遍历,所有"递归访问者"都必须自己写遍历。VSG 内部有两种流派,写法不同、适用场景不同。
流派 A:重写 apply(Object&) 作为默认遍历。 典型是 FindAnimations(src/vsg/animation/FindAnimations.cpp):
void FindAnimations::apply(Object& object)
{
object.traverse(*this); // 默认:继续往下走
}
void FindAnimations::apply(Animation& animation)
{
animations.emplace_back(&animation); // 命中:收集,不遍历(Animation 没有子节点)
}
void FindAnimations::apply(AnimationGroup& node)
{
animationGroups.emplace_back(&node);
node.traverse(*this); // 命中:收集后再遍历
}
优点:任何新类型都自动被兜底,不会漏。缺点:每个被访问的对象都要先在 apply(Object&) 里过一次虚分派,即使它的类型无关紧要。
流派 B:在具体类型上写遍历。 典型是 LoadPagedLOD(src/vsg/utils/LoadPagedLOD.cpp):
void LoadPagedLOD::apply(Node& node) { node.traverse(*this); }
void LoadPagedLOD::apply(Transform& transform)
{
modelviewMatrixStack.emplace(transform.transform(modelviewMatrixStack.top()));
pushFrustum();
transform.traverse(*this);
_frustumStack.pop();
modelviewMatrixStack.pop();
}
void LoadPagedLOD::apply(LOD& lod)
{
if (!intersect(_frustumStack.top(), lod.bound)) return;
// 只挑一个 child 访问,然后 return
for (auto& child : lod.children)
if (visible) { child.node->accept(*this); return; }
}
优点:每个类型的行为写在一起,读起来就是一棵树的结构;能精确控制"哪些类型需要特殊处理"。缺点:如果漏写一个容器类型的 apply,遍历就在那里断掉——LoadPagedLOD 重写了 apply(Node&) 作为兜底,所以任何没特化的节点都会走 Node::traverse(空),也就是说只有 Group 家族会继续下沉。这不是 bug,因为 LoadPagedLOD 只关心 Transform/LOD/PagedLOD/CullNode,其他节点不需要深入;但如果你照抄这个模式又漏了某个容器类型,就会得到"部分子树被跳过"的诡异结果。
选择建议:访问者需要"看到一切"(统计、打印、查找)用流派 A;需要"精确控制下沉条件"(剔除、分页、编译)用流派 B。VSG 自己也是这么分的:FindCameras、FindAnimations、CompileTraversal 用 A,LoadPagedLOD、RecordTraversal 用 B。
3.4.6 InstrumentationNode:traverse 里的插桩钩子
traverse 是访问者相关的,这句话最极端的证据是 InstrumentationNode(src/vsg/nodes/InstrumentationNode.cpp 第 64–77 行):
// src/vsg/nodes/InstrumentationNode.cpp:64
void InstrumentationNode::traverse(Visitor& visitor)
{
CpuInstrumentation cpuInst(visitor.getInstrumentation(), &_sl_Visitor, child.get());
child->accept(visitor);
}
void InstrumentationNode::traverse(ConstVisitor& visitor) const
{
CpuInstrumentation cpuInst(visitor.getInstrumentation(), &_sl_ConstVisitor, child.get());
child->accept(visitor);
}
void InstrumentationNode::traverse(RecordTraversal& rt) const
{
GpuInstrumentation cpuInst(rt.instrumentation, &_sl_RecordTraversal, *rt.getCommandBuffer(), child.get());
child->accept(rt);
}
三个 traverse,三种插桩方式,唯一共同点是"最后都调用 child->accept"。这就是 Visitor::getInstrumentation() 这个虚函数存在的唯一理由(Visitor.h 第 195 行):
// include/vsg/core/Visitor.h:195
virtual Instrumentation* getInstrumentation() { return nullptr; }
默认返回空——绝大多数访问者不插桩。CompileTraversal 重写了它(CompileTraversal.h 第 82 行),把 instrumentation 成员交出去;RecordTraversal 干脆不用这个虚函数,直接暴露 ref_ptr<Instrumentation> instrumentation 成员(所以上面第三段代码写的是 rt.instrumentation 而不是 rt.getInstrumentation())。
为什么 RecordTraversal 不用虚函数? 因为它不是 Visitor,没有那个虚函数可重写。
InstrumentationNode 的实用价值:它是唯一一个"能测量任意子树耗时"的节点类型。把子树包一层:
scene->addChild(vsg::InstrumentationNode::create(subtree));
然后在 Viewer 的 instrumentation 里就能看到这棵子树的 CPU/GPU 耗时,名字和颜色通过 setName/setColor 设置。插桩不是外部工具的事,是场景图的一部分——这是 VSG 与大多数引擎不同的设计取向,第 15 章讲 Viewer 时会展开。
3.5 掩码:Mask 的位运算语义与三个存储位置
include/vsg/core/Mask.h 只有 4 行有效代码:
// include/vsg/core/Mask.h:20
using Mask = uint64_t;
constexpr Mask MASK_OFF = 0ul;
constexpr Mask MASK_ALL = ~MASK_OFF;
uint64_t 意味着 64 个可用的层(layer)。这个数字不是随便选的:OSG 的 NodeMask 是 32 位,而 Vulkan 侧没有对应的"层"概念(VkPipelineViewportStateCreateInfo 管的是视口个数,不是层),所以 64 是纯粹的工程折中——够用,且仍在单个寄存器内,比较/与/或都是一条指令。
掩码在 VSG 里有一个统一的判断式,全文出现 12 处,一字不差:
if ((visitor.traversalMask & (visitor.overrideMask | mask)) != MASK_OFF)
3.5.1 真值表:这两个掩码到底各管什么
设 T = traversalMask(遍历者想看的层)、O = overrideMask(遍历者的"无视掩码"开关)、M = node.mask(这个节点在哪几层)。
T | O | M | T & (O | M) | 结果 | 场景 |
|---|---|---|---|---|---|
| ALL | OFF | ALL | ALL | 访问 | 默认情况,一切可见 |
| ALL | OFF | 0 | 0 | 跳过 | 节点被显式关闭(mask = MASK_OFF) |
1<<0 | OFF | 1<<1 | 0 | 跳过 | 只想看第 0 层,节点在第 1 层 |
1<<0 | OFF | 1<<0 | 1<<1 | 1<<0 | 访问 | 节点跨层,命中其一即可 |
1<<0 | ALL | 0 | 1<<0 | 访问 | override 打开,节点的 mask 被无视 |
0 | ALL | ALL | 0 | 跳过 | 陷阱:override 救不了 T == 0 |
0 | ALL | 0 | 0 | 跳过 | 同上 |
两条规律:
overrideMask是"忽略节点掩码",不是"强制遍历"。 它把M从表达式里"或"掉,但T仍在。所以traversalMask = 0时,无论overrideMask是什么,一个节点都不会被访问。这个细节决定了下面 3.5.3 的一个真实用法。M的语义是"或"而不是"与"。 节点只要在T的任意一层上,就会被访问。这和 OpenGL 的 stencil 测试(与)相反,是"层"(layer)语义的标准实现。
3.5.2 只有 5 种类型检查掩码
把那个判断式的 12 处出现位置列出来,会得到一个反直觉的结论:267 种类型里,只有 5 种会在遍历时检查掩码,另外 2 处检查发生在录制阶段(此时访问者已经不在了)。
| 位置 | 检查时机 | 检查对象 |
|---|---|---|
View::t_accept | accept 时 | View 自身的 mask,并收窄 traversalMask |
Switch::t_traverse | traverse 时 | 每个 child.mask |
Layer::traverse | traverse 时 | Layer 自身的 mask |
RegionOfInterest::accept | accept 时 | 自身 mask(三个 accept 都重写了) |
StateSwitch::t_traverse | traverse 时 | 每个 child.mask |
RecordTraversal::apply(const PagedLOD&) | 录制时 | child.mask |
StateSwitch::record | 录制时 | 从 CommandBuffer 读掩码 |
Group 不检查掩码。 因为 Group::children 是 vector<ref_ptr<Node>>,每个 child 没有 mask 字段——想按层开关子节点,必须用 Switch(vector<Child{mask, node}>)或 Layer。这是一个明确的分工:掩码能力绑定在"带掩码的容器"上,而不是绑定在"所有节点"上。
Node 自己也没有 mask 字段。 这一点常被 OSG 用户误解——OSG 的 osg::Node 有 setNodeMask(),任何节点都能被掩码过滤;VSG 里只有 View、Layer、RegionOfInterest、Switch::Child、StateSwitch::Child 这几处有 Mask mask 成员。想给任意子树加开关,包一层 Switch。
这个设计取舍的收益:每个节点省 8 字节(Node 从 24+8 变成 24,见第一章 1.4 节的字节账),百万节点省 8MB;遍历时省一次判断(Group::t_traverse 的循环体只有 accept 一次调用)。代价:老用户的心智迁移成本,以及"想给单个节点关掉"时必须改结构。
3.5.3 View::t_accept:唯一会改写 traversalMask 的地方
include/vsg/app/View.h 第 44–58 行是全库最特殊的 accept:
// include/vsg/app/View.h:45
template<class N, class V>
static void t_accept(N& node, V& visitor)
{
if ((visitor.traversalMask & (visitor.overrideMask | node.mask)) == MASK_OFF) return;
auto cached_traversalMask = visitor.traversalMask;
visitor.traversalMask = visitor.traversalMask & node.mask; // 收窄
visitor.apply(node);
visitor.traversalMask = cached_traversalMask; // 恢复
}
void accept(Visitor& visitor) override { t_accept(*this, visitor); }
注意三件事。
第一,它是 accept 而不是 traverse。 因为 View 是遍历的入口,掩码的收窄必须发生在 apply(View&) 之前(RecordTraversal::apply(const View&) 需要读到收窄后的值,把它写进 CommandBuffer)。如果放在 traverse 里,apply 已经执行完了。
第二,&= 是"累积"语义,| 判断是"命中"语义,两者混用是有意的。 判断用 |(节点在任意一层即可见),收窄用 &(子树只能在"视图的层 ∩ 节点的层"里)。这意味着嵌套 View 会进一步收窄:外层 View 的 mask 是 1<<0,内层是 1<<0 | 1<<1,进入内层后 T = 1<<0,内层子树里标在 1<<1 的节点不可见。这是 OSG setNodeMask 累积语义的等价物,但只发生在 View 上。
第三,收窄-恢复必须成对,且没有 RAII。 如果 visitor.apply(node) 抛异常,traversalMask 会永久停在收窄后的值上,后续所有节点都被过度过滤。这是 3.4.4 节"栈纪律"的同一个问题的第二个实例。
3.5.4 overrideMask = MASK_ALL 的四个使用者
全库只有四个地方把 overrideMask 设为 MASK_ALL:
| 使用者 | 位置 | 为什么必须无视掩码 |
|---|---|---|
CompileTraversal | 构造函数 + 3 处 | 隐藏的节点也要创建 GPU 资源,否则"打开开关"的瞬间会卡住(甚至第一帧就缺资源) |
CollectResourceRequirements | ResourceRequirements.h 第 104 行 | 资源统计必须覆盖全部节点,否则缓冲区会按"可见部分"分配,切换可见性时越界 |
WindowResizeHandler | 构造函数 | 窗口缩放时要重建所有 GraphicsPipeline 的视口,包括当前不可见的 |
UpdateGraphicsPipelines | 构造函数 | 同上,管线重建与可见性无关 |
这四个场景的共同点是:"可见性"是运行时概念,"资源/管线"是编译期概念,两者不能混。 overrideMask 就是这条边界的显式标记。反过来,如果你写了一个导出器、统计器、序列化器,也需要 overrideMask = MASK_ALL——否则导出的场景会缺少被 Switch 关掉的子树。
这四处都保持了 traversalMask = MASK_ALL(默认值);若事先设成具体层,overrideMask 就失效。CompileTraversal 的构造函数没有显式重置 traversalMask,这是一个可以改进的点。
3.5.5 掩码的第三个存储位置:CommandBuffer
StateSwitch 是一个"能按层开关状态命令"的 StateCommand。它的 record() 在录制阶段执行,此时访问者对象已经不在栈上了:
// src/vsg/state/StateSwitch.cpp:58
void StateSwitch::record(CommandBuffer& commandBuffer) const
{
for (auto& child : children)
{
if ((commandBuffer.traversalMask & (commandBuffer.overrideMask | child.mask)) != MASK_OFF)
child.stateCommand->record(commandBuffer);
}
}
掩码从 CommandBuffer 读。所以 RecordTraversal::apply(const View&) 必须在遍历前把掩码"灌"进去:
// src/vsg/app/RecordTraversal.cpp:567
auto cached_traversalMask = state->_commandBuffer->traversalMask;
state->_commandBuffer->traversalMask = traversalMask;
state->_commandBuffer->viewID = view.viewID;
于是 traversalMask 在系统里有三个副本:Visitor/RecordTraversal 的成员(遍历期)、CommandBuffer 的成员(录制期)、以及 View::t_accept 里那个临时收窄的值(入口期)。三者靠 apply(View&) 的保存/恢复保持同步。任何"在 View 之外改 traversalMask"的代码都在玩一个危险的游戏——你不知道下一帧的 CommandBuffer 会拿到哪个值。
3.6 三个并行的分派家族
Object 有三个 accept 重载,对应三个完全独立的访问者家族。它们不是"同一个东西的三个版本",而是三个针对不同场景设计的机制:
| 维度 | Visitor | ConstVisitor | RecordTraversal |
|---|---|---|---|
| 重载数量 | 267 | 267 | 33 |
| 参数形式 | T& | const T& | const T& |
apply 是否虚函数 | 是 | 是 | 否 |
| 未特化类型的兜底 | 逐级降级到 Object(空) | 同左 | 隐式转换到 const Object& → traverse |
| 自身状态 | traversalMask、overrideMask | 同左 | State*、Bin 列表、viewDependentState、regionsOfInterest |
是否继承 Visitor | — | 否(独立继承 Object) | 否(独立继承 Object,且不用 Inherit) |
| 典型用途 | 查询、修改、导出 | 拾取、测量、只读分析 | 逐帧录制命令 |
| 典型调用次数 | 加载时一次 | 交互时按需 | 每帧一次 |
3.6.1 ConstVisitor 为什么必须是独立的一套
C++ 的 const 是类型系统的一部分,但虚函数不能按 const 重载:virtual void apply(Group&) 和 virtual void apply(const Group&) 在同一个类里是合法的重载(参数不同),但它们会占据不同的虚表槽位。如果 VSG 想在同一个 Visitor 里同时支持两种,apply 的数量会从 267 变成 534,虚表从 2.3KB 变成 4.6KB。
更重要的是语义:一个 const Node* 不能传给 Visitor&,因为 Visitor::apply(Node&) 需要非 const 引用。想让"只读访问"在类型系统里成立,就必须有 accept(ConstVisitor&) const 和 ConstVisitor::apply(const T&) 这一整套。于是:
void apply(const Node& node) override; // ConstVisitor
void apply(Node& node) override; // Visitor
两个家族的函数签名、虚表、实现文件全部平行。代价是 1156 行的重复,收益是"只读访问者无法意外修改场景"这个编译期保证。
典型使用者是 Intersector(include/vsg/utils/Intersector.h 第 23 行):
class VSG_DECLSPEC Intersector : public Inherit<ConstVisitor, Intersector>
拾取只需要读顶点数据算射线求交,绝不能改场景。用 ConstVisitor 之后,apply(const Geometry&) 里拿到的 vertices 是 const ref_ptr<vec3Array>,(*vertices)[i] 是 const vec3&,任何写入都是编译错误。这比"约定不要改"强得多。
ComputeTransform(include/vsg/maths/transform.h 第 285 行)也是 ConstVisitor,但注意它的成员是可写的:
// include/vsg/maths/transform.h:285
struct VSG_DECLSPEC ComputeTransform : public ConstVisitor
{
dvec3 origin;
dmat4 matrix;
void apply(const Transform& transform) override; // matrix = transform.transform(matrix);
"const 对象"指的是被访问的场景,不是访问者自己。 访问者的累加器当然要可变,否则没法算东西。这个区分在第一次读源码时很容易搞混。
3.6.2 RecordTraversal 为什么只有 33 个重载
这是本章最值得追问的设计问题。答案有两层。
第一层:状态命令的录制被 State 栈接管了,不需要遍历去逐个录。
RecordTraversal 的 33 个重载里,与命令相关的只有两个:Command 和 Commands(Bin 是深度排序容器,不算命令)。而 BindGraphicsPipeline、BindDescriptorSet、VertexInputState 这些"状态命令"根本没有对应重载——它们不走遍历,走的是 State。
看 include/vsg/vk/State.h 第 348 行的 record():
// include/vsg/vk/State.h:348
inline void record()
{
if (dirty)
{
for (uint32_t slot = 0; slot <= activeMaxStateSlot; ++slot)
stateStacks[slot].record(*_commandBuffer);
activeMaxStateSlot = maxSlots.state;
projectionMatrixStack.record(*_commandBuffer);
modelviewMatrixStack.record(*_commandBuffer);
dirty = false;
}
}
stateStacks 是按 slot 分组的命令栈。StateGroup::traverse 里那句 state->push(begin, end) 把状态命令压栈并置 dirty = true;绘制时 state->record() 一次性把所有待生效的状态按 slot 顺序录进命令缓冲区。于是"状态切换"变成了"栈的差分",而不是"遍历到哪个命令就录哪个"。
这就是 Visitor 需要 47 个 Vulkan 重载、而 RecordTraversal 只需要 3 个的根本原因:通用访问者要能"看到每一个对象"(导出、统计、调试),必须认识全部类型;录制器只需要"知道哪些节点要出图、用哪个状态栈",状态由栈统一处理。职责不同,重载集合的大小就不同,这是设计的结果而不是偷懒。
第二层:热路径上不能付降级链的成本。
Visitor 的兜底路径是"逐级虚调用",最深 7 次。对每一帧、每个节点都要走一遍的 RecordTraversal 来说,这是不可接受的:
| 路径 | 一个 Group 的间址次数 | 一个 ViewportState 的间址次数 |
|---|---|---|
Visitor(只重写 apply(Object&)) | 4 | 8 |
RecordTraversal | 2(accept + traverse) | 2(accept + traverse,空) |
RecordTraversal 的 apply 是非虚的,靠 33 个重载在编译期做静态决议;未特化的类型(比如 BufferInfo、ImageInfo、Texture)隐式转换成 const Object&,零额外调用,落到 apply(const Object&) 里的 object.traverse(*this)——一次虚调用,通常还是空函数。最坏 2 次间址,与继承深度无关。 这是它敢每帧跑 10 万节点的底气。
有意思的是,RecordTraversal::apply(const Object&) 的兜底语义恰好依赖 Object::traverse 是虚函数。这解释了 3.3.3 节那个"看起来多余"的 virtual void traverse(RecordTraversal&) const {}:它不是给 Visitor 用的,是给这个兜底路径用的。
3.6.3 为什么它不继承 Visitor
一个"看起来更省事"的方案是 class RecordTraversal : public Visitor,复用 267 个 apply 的降级链,只重写需要的那些。VSG 没有这么做,理由有四条,按重要性排序:
- 性能:继承就意味着降级链,最坏 7 次间址 vs 2 次。每帧 10 万节点 × 5 次额外间址 ≈ 50 万次多余的间接分支,在 60fps 的 16.6ms 预算里是 3%–9%。
- 语义隔离:
RecordTraversal有强烈的副作用(写命令缓冲区、改State栈、往Bin里塞节点)。如果它is-aVisitor,任何接受Visitor&的函数都能拿到它并"顺手访问一下",后果是命令被录进错误的缓冲区。类型系统上不兼容,比文档上写"不要传"有效。 const语义:RecordTraversal的apply接受const T&(因为它只读场景、写命令缓冲区),而Visitor::apply接受T&。继承会让两套签名打架。- ABI 与演进:
Visitor的虚表是 285 槽的公共契约,任何改动都是 ABI 破坏;RecordTraversal的非虚重载不占虚表,加一个apply只影响源码兼容性。
反证:CompileTraversal 就继承了 Visitor(include/vsg/app/CompileTraversal.h 第 33 行),因为它只在加载/改场景时跑一次,性能不敏感,而且它需要"看到所有类型"(Compilable、Geometry、Commands、ShaderCompileSettings……)。同一个库里,编译遍历用 Visitor、录制遍历手写重载,这个对比就是上面四条理由最好的证据。
3.6.4 一个可以验证的坑:cast<RecordTraversal>() 永远失败
RecordTraversal 不用 Inherit,手写了 sizeofObject() 和 className(),却没有重写 is_compatible:
// include/vsg/app/RecordTraversal.h:87
std::size_t sizeofObject() const noexcept override { return sizeof(RecordTraversal); }
const char* className() const noexcept override { return type_name<RecordTraversal>(); }
而 Object::is_compatible 的默认实现是 typeid(Object) == type。Object::cast<T>() 在默认配置(VSG_USE_dynamic_cast=OFF)下是:
template<class T>
T* cast() { return is_compatible(typeid(T)) ? static_cast<T*>(this) : nullptr; }
于是对一个 RecordTraversal 实例调用 cast<RecordTraversal>(),is_compatible(typeid(RecordTraversal)) 返回 typeid(Object) == typeid(RecordTraversal) → false → 返回 nullptr。
这是一个真实的不一致:Visitor 和 ConstVisitor 都老老实实重写了 is_compatible(Visitor.h 第 491 行、ConstVisitor.h 第 491 行),只有 RecordTraversal 漏了。后果有限(没人会把 RecordTraversal 塞进 ref_ptr<Object> 再 cast 回来),但如果你写了一个通用工具,比如"从 Auxiliary 里取出某个 Object* 并判断它是不是访问者",就会踩到。修复只要一行:
bool is_compatible(const std::type_info& type) const noexcept override
{ return typeid(RecordTraversal) == type || Object::is_compatible(type); }
这类"手写 RTTI 样板漏一项"的问题,正是 3.3.1 节表格里"CRTP 收益"的具体兑现:用了 Inherit 的 267 个类全都没有这个问题。
3.6.5 33 个重载按函数体分七类
换一个角度看这 33 个重载:不看它们认识哪些类型,而看函数体在做什么。摊开之后只有七件事,每一件都能从"录制阶段要干什么"推出来,而不是从类型清单推出来。
第一类,纯转发。 函数体只有一句 traverse,一个字节的信息量:Object、Group、QuadGroup、TileDatabase、Bin 都属于这一类。
// src/vsg/app/RecordTraversal.cpp:262
void RecordTraversal::apply(const TileDatabase& tileDatabase)
{
GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "TileDatabase", COLOR_RECORD_L2, &tileDatabase);
// src/vsg/app/RecordTraversal.cpp:266
tileDatabase.traverse(*this);
}
这五个重载不能合并成"任意节点都转发":转发目标不同——Group 走模板 t_traverse,TileDatabase 走单个 child,Bin 走排序后的内容。apply 必须逐个认识它们,才能选中正确的 traverse(src/vsg/app/RecordTraversal.cpp:121 是公共兜底,它上面紧挨着的 clearBins 在每帧开头清空 bins,见 src/vsg/app/RecordTraversal.cpp:120)。
第二类,先剔除再转发。 CullGroup、CullNode 在 apply 里做视锥测试,测试不过就连 traverse 都不调;LOD/PagedLOD 的"只选一个孩子"和 Switch 的掩码判断同属这类条件转发,只是判据不同:
// src/vsg/app/RecordTraversal.cpp:269
void RecordTraversal::apply(const CullGroup& cullGroup)
{
GPU_INSTRUMENTATION_L2_NCO(instrumentation, *getCommandBuffer(), "CullGroup", COLOR_RECORD_L2, &cullGroup);
// src/vsg/app/RecordTraversal.cpp:273
if (state->intersect(cullGroup.bound))
{
// debug("Passed node");
cullGroup.traverse(*this);
}
}
第三类,入 bin 而不是下潜。 Layer 与 DepthSorted 把 child 连同一个排序键塞进 bin,真正的遍历发生在 bin 排完序之后:
// src/vsg/app/RecordTraversal.cpp:325
void RecordTraversal::apply(const Layer& layer)
{
CPU_INSTRUMENTATION_L2_NCO(instrumentation, "Layer", COLOR_RECORD_L2, &layer);
if ((traversalMask & (overrideMask | layer.mask)) != MASK_OFF)
{
// src/vsg/app/RecordTraversal.cpp:330
addToBin(layer.binNumber, layer.value, layer.child);
}
}
DepthSorted 的排序键要现算:把包围球中心投到视空间的 z 轴上(src/vsg/app/RecordTraversal.cpp:319)。这一步不能延后,因为 addToBin 之后 state 可能已经变了。
第四类,只往侧袋里记一笔。 RegionOfInterest 是极端的例子:整个函数体就是把当前 modelview 矩阵和节点指针成对存进 regionsOfInterest,一个字节的命令缓冲区都不碰:
// src/vsg/app/RecordTraversal.cpp:304
void RecordTraversal::apply(const RegionOfInterest& roi)
{
CPU_INSTRUMENTATION_L2_NCO(instrumentation, "RegionOfInterest", COLOR_RECORD_L2, &roi);
// src/vsg/app/RecordTraversal.cpp:308
regionsOfInterest.emplace_back(state->modelviewMatrixStack.top(), &roi);
}
第五类,落笔录制。 VertexDraw、VertexIndexDraw、Geometry、Command、Commands、InstanceDraw 走的是同一条三步曲:state->record() 把待生效状态刷进命令缓冲区,再调对象自己的 record():
// src/vsg/app/RecordTraversal.cpp:334
void RecordTraversal::apply(const VertexDraw& vd)
{
GPU_INSTRUMENTATION_L3_NCO(instrumentation, *getCommandBuffer(), "VertexDraw", COLOR_GPU, &vd);
//debug("Visiting VertexDraw");
// src/vsg/app/RecordTraversal.cpp:339
state->record();
vd.record(*(state->_commandBuffer));
}
Commands 是一个例外:它不把每个孩子交给 apply(const Command&),而是自己循环调 command->record(),绕过了 apply 上的插桩点(src/vsg/app/RecordTraversal.cpp:538)。于是同一条命令,单独挂在 StateGroup 下和装进 Commands 里,走的是两条代码路径——性能上没差别,但性能分析器给出的层级名不同,这是排查"某类 draw 的计时缺失"时容易迷路的地方。
// src/vsg/app/RecordTraversal.cpp:531
void RecordTraversal::apply(const Commands& commands)
{
GPU_INSTRUMENTATION_L3_NCO(instrumentation, *getCommandBuffer(), "Commands", COLOR_GPU, &commands);
// src/vsg/app/RecordTraversal.cpp:535
state->record();
// src/vsg/app/RecordTraversal.cpp:536
for (auto& command : commands.children)
{
command->record(*(state->_commandBuffer));
}
}
注意它连 apply(const Command&) 都不走,Command 的重载因此只在"命令直接挂在 StateGroup 下"时才被调用:
// src/vsg/app/RecordTraversal.cpp:542
void RecordTraversal::apply(const Command& command)
{
GPU_INSTRUMENTATION_L3_NCO(instrumentation, *getCommandBuffer(), "Command", COLOR_GPU, &command);
//debug("Visiting Command");
// src/vsg/app/RecordTraversal.cpp:547
state->record();
command.record(*(state->_commandBuffer));
}
第六类,只改访问者状态。 Light 与 Joint 什么也不做,连转发都没有;InstanceNode 记下当前实例节点再下潜,子节点据此把 instanceIndex 写进顶点着色器:
// src/vsg/app/RecordTraversal.cpp:487
void RecordTraversal::apply(const InstanceNode& instanceNode)
{
CPU_INSTRUMENTATION_L2_NCO(instrumentation);
if (instanceNode.child)
{
// src/vsg/app/RecordTraversal.cpp:493
state->_commandBuffer->instanceNode = &instanceNode;
instanceNode.child->accept(*this);
}
}
// src/vsg/app/RecordTraversal.cpp:361
void RecordTraversal::apply(const Light&)
{
CPU_INSTRUMENTATION_L2(instrumentation);
//debug("RecordTraversal::apply(Light) ", light.className());
}
注意 apply(const Light&) 连参数名都省了——它确实一个字都不需要,Joint 的注释更直白:"non op for RiggedJoint as it's designed not to have any renderable children"(src/vsg/app/RecordTraversal.cpp:484)。四个具体光源(AmbientLight、DirectionalLight、PointLight、SpotLight)则各自往 viewDependentState 的对应列表里塞一项,和 RegionOfInterest 同属"侧袋"一类。
七类的分布是 5(纯转发)/ 5(条件转发)/ 2(入 bin)/ 5(侧袋)/ 7(落笔)/ 6(只改状态)/ 3(结构性),合计 33。3 个结构性重载——StateGroup 压栈、View 切命令缓冲区、CommandGraph 重入录制——才是"33 个够用"的真正原因:类型清单可以短,因为结构性的工作只有三处。顺带一个可查的细节:CommandGraph 那行调用的方法名拼作 setInhertiedViewProjectionAndViewMatrix(多一个 t),这个拼写错误至今留在公开头文件里。
3.7 五个真实访问者,逐行解剖
理论讲完了,看代码。VSG 内部有 14 个公开的 Visitor 子类(另有 6 个源文件里的匿名 struct),每一个都在解决一个具体问题。挑五个最有代表性的。
3.7.1 FindCameras:带路径的收集器
// include/vsg/app/Camera.h:47
class VSG_DECLSPEC FindCameras : public Inherit<Visitor, FindCameras>
{
public:
std::map<RefObjectPath, ref_ptr<Camera>> cameras;
void apply(Object& object) override;
void apply(Camera& camera) override;
protected:
ObjectPath _objectPath;
};
实现(src/vsg/app/Camera.cpp 第 59–80 行):
void FindCameras::apply(Object& object)
{
_objectPath.push_back(&object);
object.traverse(*this);
_objectPath.pop_back();
}
void FindCameras::apply(Camera& camera)
{
_objectPath.push_back(&camera);
RefObjectPath convertedPath(_objectPath.begin(), _objectPath.end());
cameras[convertedPath] = &camera;
_objectPath.pop_back();
}
三个值得注意的点。
第一,两个路径类型不是重复设计。 ObjectPath 是 std::vector<Object*>(Object.h 第 211 行),RefObjectPath 是 std::vector<ref_ptr<Object>>(第 210 行)。遍历过程中用裸指针 ObjectPath——因为遍历期间节点一定活着(scene 的 ref_ptr 就在调用者的栈上),用裸指针省一次原子加/减,而这对每个节点都发生一次,100 万节点就是 200 万次原子操作。收集到 map 里时转成 RefObjectPath——因为 map 的键要长期持有,必须保证路径上的节点不被释放。
第二,map 的键是"路径",值才是相机。 同一个 Camera 可以通过多条路径到达(DAG,不是树),所以 cameras 是"路径 → 相机"而不是"相机集合"。这也解释了为什么用 std::map 而不是 std::unordered_map:RefObjectPath 没有 hash 特化,但有 operator<(ref_ptr::operator< 比较裸指针)。
第三,apply(Camera&) 不调用 traverse。 Camera 的继承链是 Camera → Node → Object,它没有子节点,traverse 是空函数。这里"不写"和"写了"等价,但不写省一次虚调用——在收集器里这是合理的微优化。前提是你确认这个类型是叶子;如果 Camera 将来加了子节点,这段代码就会静默漏掉子树。
3.7.2 FindAnimations:最短的完整访问者
void FindAnimations::apply(Object& object) { object.traverse(*this); }
void FindAnimations::apply(Animation& animation) { animations.emplace_back(&animation); }
void FindAnimations::apply(AnimationGroup& node) { animationGroups.emplace_back(&node); node.traverse(*this); }
三行代码,把 3.4.5 节的"流派 A"演示得淋漓尽致:
apply(Object&)是全局兜底:任何没被特化的类型都继续往下走。apply(Animation&)是终点:Animation不是节点(Inherit<Object, Animation>),没有子节点,收集完就结束。apply(AnimationGroup&)是中途站:收集 + 继续遍历。
注意 Animation 和 AnimationGroup 的语义差别:前者是"动画数据"(关键帧、时间轴),后者是"带子节点的组"。访问者的重载集合精确反映了这一点——如果只写 apply(Animation&),AnimationGroup 会被 apply(Object&) 接住,animationGroups 永远是空的。
3.7.3 WindowResizeHandler:为什么必须有去重集合
窗口缩放时要重建所有 GraphicsPipeline 的视口。实现里有一个不起眼但关键的成员(include/vsg/app/WindowResizeHandler.h 第 33 行):
// include/vsg/app/WindowResizeHandler.h:51
std::set<std::pair<const Object*, uint32_t>> visited;
配合一个 5 行的函数:
bool WindowResizeHandler::visit(const Object* object, uint32_t index)
{
decltype(visited)::value_type objectIndex(object, index);
if (visited.count(objectIndex) != 0) return false;
visited.insert(objectIndex);
return true;
}
为什么需要去重? 因为场景图是 DAG 而不是树。一个 GraphicsPipeline 可以被多个 View 共享,也可以被同一个 View 里的多条路径引用(比如两个 StateGroup 引用同一个 Commands)。窗口缩放时如果对同一个管线重建两次,第二次的 release 会释放掉第一次刚创建的资源,或者干脆双重释放。
为什么键里要带 viewID? 因为 GraphicsPipeline 是按 view 缓存的(context->viewID)。同一个管线对象在两个 View 里是两份不同的 VkPipeline(视口不同),所以"这个对象在这个 view 里处理过吗"必须按 (对象, viewID) 成对判断。
这个模式的通用价值:任何"遍历 + 修改共享资源"的访问者都需要去重。CompileTraversal 用的是同一套思路(Context::viewID + 内部去重),只是没有暴露成成员。
同一文件里还有一段漂亮的代码,用 ConstVisitor 当一次性谓词:
struct ContainsViewport : public ConstVisitor
{
bool foundViewport = false;
void apply(const ViewportState&) override { foundViewport = true; }
bool operator()(const GraphicsPipeline& gp)
{
for (auto& pipelineState : gp.pipelineStates)
pipelineState->accept(*this);
return foundViewport;
}
} containsViewport;
bool needToRegenerateGraphicsPipeline = !containsViewport(*graphicsPipeline);
它一次遍历都没做——只是手动把 pipelineStates 里的每个状态 accept 一遍,看有没有 ViewportState。这是访问者最轻量的用法:不用树,只用一个重载 + 一个 accept 循环,就把"类型检查"写成了类型安全的代码。对比 dynamic_cast<ViewportState*>(state.get()) 的写法,访问者版本在 -fno-rtti 下也能用,且不需要 VSG_USE_dynamic_cast。
3.7.4 Intersector:只读访问者与状态克隆
拾取(第 22 章详述)是 ConstVisitor 的旗舰用例。它的 apply(const StateGroup&) 揭示了一个重要模式:
// src/vsg/utils/Intersector.cpp:58
void Intersector::apply(const StateGroup& stategroup)
{
PushPopNode ppn(_nodePath, &stategroup);
auto arrayState = stategroup.prototypeArrayState
? stategroup.prototypeArrayState->cloneArrayState(arrayStateStack.back())
: arrayStateStack.back()->cloneArrayState();
for (auto& statecommand : stategroup.stateCommands)
statecommand->accept(*arrayState); // 关键:状态命令被交给 ArrayState 处理
arrayStateStack.emplace_back(arrayState);
stategroup.traverse(*this);
arrayStateStack.pop_back();
}
状态命令不是被"访问"的,是被"提交"给 ArrayState 的。 StateCommand::accept(*arrayState) 走的是第四个分发机制(ArrayState 也有 apply 重载),这与 RecordTraversal 把状态交给 State 栈是同一个思想:遍历负责"走到哪",状态系统负责"用哪套数据"。
cloneArrayState 而不是共享引用,是因为 DAG 的分叉:同一个 StateGroup 可以被两条路径到达,每条路径上的 ArrayState 可能已被修改(比如某个祖先压了一个不同的顶点布局)。用不可变克隆 + 写时复制,避免"一条路径改了状态,另一条路径看到脏数据"。
LOD 的处理也很直白:
// src/vsg/utils/Intersector.cpp:87
void Intersector::apply(const LOD& lod)
{
PushPopNode ppn(_nodePath, &lod);
if (intersects(lod.bound))
for (auto& child : lod.children)
if (child.node) { child.node->accept(*this); break; } // 只取第一个
}
break:LOD 只访问第一个子节点。这是"细节层次"的标准语义——第一个是最精细的,如果射线打中了它,就不必再测更粗的。但注意:这假设 children 是按精细度降序排列的,而 VSG 并不强制这个顺序(LOD 的 read/write 原样保留文件里的顺序)。如果你的 LOD 文件顺序反了,拾取会命中错误的层次。这是一个文档里没写、但代码依赖的约定。
3.7.5 LoadPagedLOD:四个栈与"选一个孩子"
// include/vsg/utils/LoadPagedLOD.h:24
class VSG_DECLSPEC LoadPagedLOD : public vsg::Visitor
{
MatrixStack projectionMatrixStack;
MatrixStack modelviewMatrixStack;
PolytopeStack _frustumStack;
Paths _pathStack;
四个栈,分别对应"投影矩阵"、"模型视图矩阵"、"世界空间视锥"、"文件路径"。它的 apply 是 3.4.5 节"流派 B"的典型:
void LoadPagedLOD::apply(Node& node) { node.traverse(*this); } // 兜底
void LoadPagedLOD::apply(Transform& transform)
{
modelviewMatrixStack.emplace(transform.transform(modelviewMatrixStack.top()));
pushFrustum();
transform.traverse(*this);
_frustumStack.pop();
modelviewMatrixStack.pop();
}
void LoadPagedLOD::apply(LOD& lod)
{
if (!intersect(_frustumStack.top(), lod.bound)) return;
auto [distance, rf] = computeDistanceAndRF(lod.bound);
for (auto& child : lod.children)
if (rf > (child.minimumScreenHeightRatio * distance))
{ child.node->accept(*this); return; } // 只加载第一个匹配的
}
三个细节:
apply(Node&)兜底为traverse,这保证任何未特化的容器节点都能继续下沉。如果漏了这行,遍历会在第一个Group(注意Group没有自己的apply,会走apply(Node&))就停住。pushFrustum()与_frustumStack.pop()成对,但modelviewMatrixStack用的是emplace+pop。两个栈的压栈方式不同(一个是"基于当前栈顶计算新视锥",一个是"直接压入新矩阵"),这是算法需要,不是笔误。apply(LOD&)里的return而不是break:找到第一个匹配的孩子后直接返回,不继续。与Intersector的break语义相同,但写法更明确。
LoadPagedLOD 直接写 public vsg::Visitor 而不是 Inherit<Visitor, LoadPagedLOD>。全库只有两个这样的类(另一个是 BuildAccelerationStructureTraversal)。代价是失去了 Inherit 提供的 create()、className()、is_compatible()——所以你没有 LoadPagedLOD::create() 可用,只能栈上构造(vsg::LoadPagedLOD loadPagedLOD(camera);)。这不是错误,但不一致,值得在代码评审时统一。
3.8 visit<V>():一行式访问者的 10 个重载
include/vsg/core/visit.h 只有 154 行,定义了 10 个 visit 重载,分成两组:
第一组(5 个):默认构造访问者,返回它的副本。
template<class V, typename I> V visit(I begin, I end); // 迭代器区间
template<class V, typename P> V visit(vsg::ref_ptr<P> ptr); // ref_ptr
template<class V, typename P> V visit(P* ptr); // 裸指针
template<class V, typename C> V visit(const C& container); // const 容器
template<class V, typename C> V visit(C& container); // 容器
第二组(5 个):接受已有访问者,返回它的引用。
template<class V, typename I> V& visit(V& visitor, I begin, I end);
template<class V, typename P> V& visit(V& visitor, vsg::ref_ptr<P> ptr);
template<class V, typename P> V& visit(V& visitor, P* ptr);
template<class V, typename C> V& visit(V& visitor, const C& container);
template<class V, typename C> V& visit(V& visitor, C& container);
3.8.1 为什么返回"值"而不是 ref_ptr
第一组返回 V(按值),意味着访问者对象在栈上构造、用完即弃。这带来一个重要的性能与安全特性:没有堆分配,没有引用计数。ComputeTransform 只有 152 字节(dvec3 origin 24 + dmat4 matrix 128),返回时走寄存器/隐藏指针,NRVO 之后通常零拷贝。
如果返回 ref_ptr<V>,每次调用都要 new + 原子加 + 原子减 + 可能的延迟删除(第一章 1.4 节的 _attemptDelete),代价比访问本身还大。"访问者是一次性函数对象,不是长期存在的对象" 是这个设计的前提。
但这也带来两个约束:
V必须可拷贝或可移动。Visitor有拷贝构造函数(Visitor(const Visitor& rhs, const CopyOp& copyop = {})),Object的拷贝构造把_referenceCount重置为 0(Object.cpp第 31–33 行),所以拷贝一个"引用计数为 1"的访问者不会导致双重释放。但如果你在访问者里放了std::mutex之类的不可拷贝成员,visit<V>就编译不过。- 不能在返回后继续使用。
auto m = visit<ComputeTransform>(path).matrix;是安全的(拷贝出dmat4);auto& m = visit<ComputeTransform>(path).matrix;是悬空引用(临时对象在分号处销毁)。这类错误编译器不会报。
3.8.2 ComputeTransform:visit<> 的旗舰用例
// include/vsg/maths/transform.h:283
/// visitor that computes a transform matrix, accumulating the result in order of objects visited
/// usage: auto matrix = vsg::visit<vsg::ComputeTransform>(nodePath).matrix;
struct VSG_DECLSPEC ComputeTransform : public ConstVisitor
{
dvec3 origin;
dmat4 matrix;
void apply(const Transform& transform) override; // matrix = transform.transform(matrix)
void apply(const MatrixTransform& mt) override; // matrix = matrix * mt.matrix
void apply(const CoordinateFrame& cf) override; // origin = cf.origin; matrix = rotate(cf.rotation)
void apply(const Camera& camera) override; // matrix = matrix * camera.viewMatrix->inverse()
};
这个访问者只重写了 4 个类型,其余 263 个类型全部被 apply(Object&) 的空实现接住——也就是说,如果 nodePath 里混进了一个 Group,它会被静默忽略,matrix 不变。这是正确的:Group 没有变换,忽略它等价于乘单位矩阵。
注意 apply(const Transform&) 用的是 transform.transform(matrix)(子类决定怎么乘),而 apply(const MatrixTransform&) 用的是 matrix * mt.matrix(固定的右乘)。Transform::transform(const dmat4&) 是纯虚函数,MatrixTransform 的实现是 return mv * matrix;。所以两者数学上一致,但前者多一层虚调用——ComputeTransform 为 MatrixTransform 单独写重载,正是为了跳过这层虚调用。
3.8.3 与手写循环的对比
visit<T>(container) 和手写循环完全等价:
// 等价写法 A
auto matrix = vsg::computeTransform(nodePath);
// 等价写法 B
vsg::ComputeTransform ct;
for (auto& node : nodePath) node->accept(ct);
auto matrix = ct.matrix;
// 等价写法 C(利用第二组重载,复用同一个访问者)
vsg::ComputeTransform ct;
vsg::visit(ct, nodePath);
三者生成的代码几乎相同。visit<> 的价值是表达意图:读代码的人一眼知道"这里要算一个值",而不是"这里在遍历"。VSG 内部有 20 多处使用 visit<>,集中在数学与工具函数里(computeTransform、computeBounds、findCameras)。
但要注意一个坑:visit<V>(container) 对每个元素调用 accept,不调用 traverse——它遍历的是"容器里的这些对象",不是"这些对象的子树"。想遍历子树,必须让 V::apply(Object&) 里调用 traverse(像 FindCameras 那样)。visit<ComputeTransform>(nodePath) 之所以对,是因为 nodePath 本身就是一条从根到叶的路径,逐段累加变换。
3.9 写一个正确的访问者:从模板到生产
前面九节都在读别人的代码。这一节反过来,从零写一个,并把所有坑踩一遍。目标很朴素:统计场景里的三角形总数(含实例化)。
3.9.1 五个必须回答的问题
写任何访问者之前,先回答这五个问题,答案决定代码结构:
| 问题 | 影响 |
|---|---|
| 1. 需要读还是写场景? | 读 → ConstVisitor;写 → Visitor |
| 2. 需要访问"所有类型"还是"少数类型"? | 所有 → 重写 apply(Object&) 兜底;少数 → 重写具体类型,自己控制下沉 |
| 3. 有需要在子树进出时维护的状态吗? | 有 → 栈 + RAII guard |
| 4. 场景是 DAG 吗(有共享子树)? | 是 → 去重(visited 集合)或接受重复计数 |
| 5. 会被多线程同时使用吗? | 会 → 每个线程一个实例,绝不共享 |
三角形计数器的答案:读(ConstVisitor)、少数类型(Geometry/Draw/DrawIndexed/VertexDraw/VertexIndexDraw/InstanceNode)、需要状态(实例数栈)、是 DAG(接受重复计数,但要说明)、单线程(viewer 的更新线程)。
3.9.2 第一版:能跑,但有三个 bug
struct TriangleCounter : public vsg::ConstVisitor
{
uint64_t geometries = 0;
uint64_t draws = 0;
uint64_t triangles = 0;
void apply(const vsg::Object& object) override { object.traverse(*this); }
void apply(const vsg::Geometry& geometry) override
{
++geometries;
for (auto& command : geometry.commands) command->accept(*this);
}
void apply(const vsg::VertexIndexDraw& vid) override
{
++draws;
triangles += vid.indexCount / 3;
}
void apply(const vsg::Draw& draw) override
{
++draws;
triangles += draw.vertexCount / 3;
}
};
// 用法
TriangleCounter counter;
scene->accept(counter);
std::cout << "geometries=" << counter.geometries
<< " draws=" << counter.draws
<< " triangles=" << counter.triangles << std::endl;
能跑。三个 bug:
Bug 1:apply(const Object&) 的兜底会让 Geometry 被访问两次吗? 不会——Geometry::accept 精确匹配 apply(const Geometry&),不会先经过 apply(const Object&)。但Geometry 的 commands 里如果还有 Geometry(嵌套),会重复计数。更重要的是:Geometry::commands 是 vector<ref_ptr<Command>>,里面的 Draw/DrawIndexed 会被 accept 到,而 Geometry 本身的 arrays(顶点数据)没有被访问——顶点数无法从 Draw 得到(Draw::vertexCount 是"要画多少个顶点",不是"缓冲区里有多少顶点")。这对三角形计数没影响,但对"顶点数统计"是致命的。
Bug 2:instanceCount 被完全忽略。 Draw::instanceCount 默认是 1,但实例化渲染时可能是 1000。triangles += vertexCount / 3 少算 999 倍。正确写法是 triangles += (uint64_t)vertexCount / 3 * instanceCount。
Bug 3:VertexDraw 没有单独处理。 VertexDraw 走 apply(const Command&) → apply(const Node&) → apply(const Object&) → traverse(空),于是 VertexDraw 的三角形完全没被统计。修法是加一个 apply(const VertexDraw&)。
3.9.3 第二版:加上实例栈与 RAII
struct TriangleCounter : public vsg::ConstVisitor
{
uint64_t geometries = 0;
uint64_t draws = 0;
uint64_t triangles = 0;
uint64_t instances = 0;
// 实例数栈:进入 InstanceNode 时乘上它的 instanceCount,退出时恢复
std::vector<uint64_t> instanceStack{1};
/// RAII:保证异常时也能弹栈
struct InstanceGuard
{
std::vector<uint64_t>& stack;
InstanceGuard(std::vector<uint64_t>& s, uint64_t count) : stack(s)
{ stack.push_back(stack.back() * std::max<uint64_t>(count, 1)); }
~InstanceGuard() { stack.pop_back(); }
uint64_t total() const { return stack.back(); }
};
void apply(const vsg::Object& object) override { object.traverse(*this); }
void apply(const vsg::InstanceNode& node) override
{
InstanceGuard guard(instanceStack, node.instanceCount);
++instances;
node.traverse(*this);
}
void apply(const vsg::Geometry& geometry) override
{
++geometries;
for (auto& command : geometry.commands) command->accept(*this);
}
void apply(const vsg::VertexDraw& vd) override
{
++draws;
triangles += (uint64_t)vd.vertexCount / 3 * vd.instanceCount * instanceStack.back();
}
void apply(const vsg::VertexIndexDraw& vid) override
{
++draws;
triangles += (uint64_t)vid.indexCount / 3 * vid.instanceCount * instanceStack.back();
}
void apply(const vsg::Draw& draw) override
{
++draws;
triangles += (uint64_t)draw.vertexCount / 3 * draw.instanceCount * instanceStack.back();
}
void apply(const vsg::DrawIndexed& di) override
{
++draws;
triangles += (uint64_t)di.indexCount / 3 * di.instanceCount * instanceStack.back();
}
};
四个改进点,每个都有理由:
InstanceGuard用 RAII 而不是手工 push/pop。ComputeBounds用裸指针instanceNode记录"最近的实例节点",没有恢复机制(src/vsg/utils/ComputeBounds.cpp第 154–161 行:instanceNode = ∈ in.traverse(*this);之后不恢复),所以嵌套InstanceNode时内层的计数会泄漏到外层兄弟节点。这是 VSG 现有代码里一个真实的不一致:matrixStack/arrayStateStack都是栈,只有instanceNode是裸指针。如果你的场景有嵌套实例化,不要用ComputeBounds的实例计数逻辑。instanceCount与栈相乘。 外层实例化 × 内层实例化是乘法关系,不是加法。std::max<uint64_t>(count, 1)。instanceCount = 0在 Vulkan 里是合法的(不画任何东西),但乘 0 会让整个子树变成 0——如果外层是 0,内层也不该被统计。这一点其实应该跳过遍历而不是乘 0,但乘 0 至少结果正确。真正的写法是在apply(const InstanceNode&)里判断if (node.instanceCount == 0) return;。ConstVisitor的四个apply签名都是const T&。 写成apply(vsg::Draw& draw)会编译失败(不是重写),如果忘了override就变成"新增一个重载",永远不会被调用——加override是必须的。
3.9.4 第三版:处理 DAG 重复计数
如果场景里有两个 StateGroup 共享同一个 Commands,上面的计数器会把那批三角形数两遍。视情况有两种处理:
// 方案 A:接受重复("渲染时会提交多少次"就是这个语义)
// 方案 B:去重("场景里唯一几何体有多少")
std::set<const vsg::Object*> visited;
void apply(const vsg::Geometry& geometry) override
{
if (!visited.insert(&geometry).second) return; // 已访问过,跳过
++geometries;
for (auto& command : geometry.commands) command->accept(*this);
}
必须先想清楚你要哪个语义。"三角形总数"在性能分析里通常指"每帧提交的三角形数"(方案 A,"draw call 视角"),而在资源统计里指"唯一几何体的三角形数"(方案 B,"内存视角")。同一个词,两个答案,差一个共享系数。VSG 的 ComputeBounds 用的是方案 B 的变体(useNodeBounds 时直接加节点包围盒,不深入子树),因为它要的是"空间范围"而不是"提交次数"。
3.9.5 文件组织与命名
VSG 对访问者的文件组织有一套不写在文档里的惯例:头文件放 include/vsg/<模块>/Xxx.h,声明写成 class VSG_DECLSPEC Xxx : public Inherit<Visitor, Xxx>,类外写 VSG_type_name(vsg::Xxx);,成员只用 ref_ptr(遍历期的临时路径除外,FindCameras::_objectPath 是唯一例外),构造参数用 ref_ptr<X> 而不是 X*(LoadPagedLOD(ref_ptr<Camera>, int))。
VSG_type_name 展开成 type_name<Xxx>() 的特化,供 className() 使用。漏写不会编译失败,但 className() 会返回 "unknown"——调试器里所有对象都叫 unknown。
3.9.6 线程安全:一个实例不能跨线程
访问者的状态(栈、累加器)是实例成员,所以:
- 同一个实例不能被两个线程同时
accept。会造成栈错乱、计数错乱,且不会崩溃(数据竞争是未定义行为,通常表现为"数少了")。 - 每线程一个实例是安全的,前提是场景本身不被修改(
ConstVisitor已经保证了这一点)。 - 跨线程遍历同一棵树是安全的,只要每个线程用自己的访问者,且没有别的线程在改树。
ref_ptr的原子计数保证了节点不会被提前释放(第一章 1.4 节的ref()/unref()内存序)。
VSG 自己就是这么用的:Viewer 的多个 RecordThread 各自持有 RecordTraversal(Viewer::recordAndSubmitTasks 里每个 task 一个),共享同一棵场景图。这是 RecordTraversal 不继承 Visitor 的第五条理由——它的状态(State*、bins)必须是每线程独立的,而 Visitor 的 traversalMask 是"看起来可以共享"的假象。
3.10 访问者的性能账
3.10.1 间接分支的真实成本
现代 x86 的间接跳转(call [rax+offset])成本取决于分支预测器能否猜中目标:
| 情况 | 周期数 | 说明 |
|---|---|---|
| 目标单一(单态) | 1–2 | 预测器直接命中 |
| 目标两种交替(双态) | 2–5 | 现代预测器能学 |
| 目标随机(多态) | 15–25 | 每次都是流水线冲刷 |
| 预测失败 + 缓存未命中 | 50–200 | 取指、解码全部重来 |
访问者的 apply 链目标类型稳定(如 apply(MatrixTransform&) 的下一跳永远是 apply(Transform&)),每一跳都是单态、1–2 周期;降级链是可预测的间接跳转。
真正昂贵的是 accept 那一跳:accept 的目标取决于当前节点的实际类型,在一棵混合树里是"多态"的(Group、MatrixTransform、Geometry……交替出现)。这一跳的预测失败是访问者模式的主要开销,而且任何访问者都逃不掉——RecordTraversal 也一样。
于是两者的差距可以精确描述:
| 开销来源 | Visitor | RecordTraversal |
|---|---|---|
accept(多态,易失败) | 1 次 | 1 次 |
apply 降级链(单态,易预测) | 1–7 次 × 1–2 周期 | 0 次 |
traverse(多态,中等) | 1 次 | 1 次(可能空) |
合计(Group 节点) | 约 6–12 周期 + 1 次失败风险 | 约 4–8 周期 |
这张表里只有"次数"是可复现的(数虚表调用),"周期"是估值:3GHz 下 10 万节点 × 5 周期差约 167 微秒/帧,在 8.3ms(120fps)预算里约 2%。对 ViewportState 这种 7 跳的类型,次数差是 7 倍而不是 2.6 倍——把次数换算成时间必须重新量,不能直接乘。
3.10.2 数据局部性:比间接分支更贵
比间接分支更影响性能的是缓存。遍历的访问模式是:
读 node->children(vector 的 begin/end 指针)→ 读 children[0](ref_ptr 的指针)→ 跳到子节点 → 读它的 vptr → 读它的 children ...
每一步都是一次指针追逐,每次跳转到一个新分配的对象。如果对象在内存里是随机分布的,每次都是一个 cache line 未命中(约 60–100ns)。这比所有间接分支加起来还贵一个数量级。
这就是第二章 IntrusiveAllocator 按类型分块存在的理由:MEMORY_AFFINITY_NODES_OBJECTS 让所有节点在连续的块里,按分配顺序紧密排列。遍历一棵刚加载的树时,硬件预取器(stride prefetcher)能识别出这种顺序访问模式,把未命中率从 ~100% 降到 ~10–20%。
访问者模式本身不改善局部性,但它不破坏局部性。 反例是"把遍历结果存进 std::map<Object*, X>"——std::map 的每个节点是一次独立的 malloc,后续按 map 顺序访问就是纯粹的随机跳转。FindCameras 用 std::map<RefObjectPath, ...> 就是这个模式,只在一次性查找时用,不要放在每帧的路径上。
3.10.3 与"在节点里加虚函数"的对比
另一个方案是给 Node 加一个虚函数 virtual void countTriangles(Counter&)。对比:
| 维度 | 访问者 | 节点虚函数 |
|---|---|---|
| 每次调用的间址次数 | 1(accept)+ 降级链 | 1 |
| 新增一种操作 | 加一个 Visitor 子类,不改任何节点类 | 改 Node 基类 + 所有 267 个类 |
| ABI 影响 | 不改节点(accept 已在) | 每个节点类加一个虚表槽,全部 ABI 破坏 |
| 类型安全 | 强(重载决议) | 强 |
| 可组合性 | 差(一个访问者一次只能做一件事,除非合并) | 好(可以调多个方法) |
| 代码分散度 | 集中在一个文件 | 散在 267 个文件 |
VSG 选访问者的决定性理由是第二条:accept 已经在 Object 里了,加操作不需要碰任何节点类。如果给 Node 加虚函数,每加一个功能就是一次全库重编译 + ABI 破坏,而这个库的 SOVERSION 已经到 17 了(第一章 1.1 节)。访问者模式在这里不是"设计模式教科书的选择",而是"二进制兼容性的必然"。
反过来说,如果你在写一个封闭的、不打算给别人扩展的库,虚函数方案更简单、更快(1 次间址 vs 1+N)。访问者的代价是"每次操作多几次跳转",收益是"操作可以无限加而不动数据类"。
3.10.4 编译期成本:285 槽的虚表乘以子类数量
每个 Visitor 子类都有一份 285 槽的虚表(2280 字节)。写 50 个访问者,.so 里多 114KB 只读数据,可以忽略。
真正需要注意的是增量编译:Visitor.h 被几乎所有头文件间接包含,改它一行会触发全库重编译。这就是为什么 apply 声明全部塞在一个头文件里,而不是拆成 VisitorNodes.h/VisitorCommands.h——拆开会让"加一个重载"变成"改三个头文件",反而更慢。
编译一个子类的开销是纯符号处理:为每个重写的 apply 生成虚表槽覆盖,为未重写的 260 多个槽保留基类指针,不涉及模板实例化,所以编译时间与重写数量近似线性。头文件解析才是大头——Visitor.h 加它的传递依赖(Object.h、ref_ptr.h、Data.h、Array.h、maths/)约 1.5 万行。
3.11 从 OSG 过来:五处必须改掉的手感
VSG 的作者就是 OSG 的作者,所以两者的骨架高度相似:accept/apply/traverse 三件套、ref_ptr、Group::children。但访问者这一层有五个地方会让 OSG 老手写出"能编译、行为不对"的代码。
3.11.1 掩码不在每个节点上
| OSG | VSG | |
|---|---|---|
osg::Node 有没有 node mask | 有(setNodeMask) | 没有 |
| 掩码检查在哪 | Node::accept 里,每个节点都查 | 只有 5 种类型查(View/Switch/Layer/RegionOfInterest/StateSwitch) |
| 想关掉一个子树 | node->setNodeMask(0) | 包一层 Switch,addChild(false, node) |
VSG 把"每个节点 8 字节的 mask + 每次遍历一次判断"换成了"要用就包一层"。如果你的移植代码里有大量 setNodeMask,需要逐个改写成 Switch,否则那些调用根本不存在(编译期就报错,算幸运的)。
3.11.2 NodePath 不再自动维护
OSG 的 NodeVisitor 在 accept 里自动 pushOntoNodePath/popFromNodePath,所以 getNodePath()、getNodePath().back() 随时可用。VSG 没有这个机制:Object::accept 只调 visitor.apply(*this),不碰任何路径栈。
想要路径,必须自己维护(FindCameras 的做法),而且要注意:
// 错误:忘了 pop,路径会一直增长
void apply(vsg::Object& object) override
{
_path.push_back(&object);
object.traverse(*this);
}
更隐蔽的错误是在 apply 里 push 而 traverse 在另一个重载里,导致路径与遍历不同步。正确做法是把 push/pop 放在同一个作用域,用 RAII(3.4.4 节的 PushPopNode)。
3.11.3 没有 _visitorType,也没有 setTraversalNumber
OSG 的 NodeVisitor 有 _visitorType(NODE_VISITOR/UPDATE_VISITOR/CULL_VISITOR/COLLECT_OCCLUDER_VISITOR),节点可以据此改变行为。VSG 取消了它,改用类型区分:更新是 Visitor,剔除是 RecordTraversal 内部的逻辑,拾取是 ConstVisitor。
好处是类型安全(不用 switch 一个枚举);代价是节点不能"感知自己被谁访问"。如果你需要这种行为,只能自己加成员(比如 RecordTraversal 有 frameStamp,节点可以从里面读帧号)。
3.11.4 apply(Node&) 默认不遍历(这点和 OSG 一样,但更容易踩)
OSG 的 NodeVisitor::apply(osg::Node&) 是空实现,遍历要靠访问者自己调 traverse(node),VSG 完全一致。但 VSG 多了一个坑:267 个重载意味着你重写哪个决定了能"接住"哪些类型(3.2.1 的降级链)。OSG 的重载只有十几个,所以"重写 apply(Group&) 覆盖所有组"的直觉在 OSG 里基本成立;在 VSG 里,Group 的直接子类有七个(AnimationGroup、CommandGraph、RenderGraph、View、CullGroup、StateGroup、Transform),而 Switch、Layer、DepthSorted 根本不是 Group 的子类(3.2.6 的表)。
3.11.5 没有"访问者基类 + 虚 apply 一个类型"的捷径
OSG 的很多工具函数接受 osg::NodeVisitor&,你可以传任何子类。VSG 有三个家族,函数签名必须明确写 Visitor& 还是 ConstVisitor&——没有共同基类。这不是疏忽:三个家族的 apply 签名不同(T& vs const T&),无法用同一个基类统一。
迁移时的实际影响:所有接受访问者的自定义函数,签名要重新选;调用处如果传错家族,会在编译期报"无法把 XxxVisitor& 转换为 ConstVisitor&"——这是好事。
3.11.6 迁移检查表
| 检查项 | OSG 写法 | VSG 改写 |
|---|---|---|
| 关子树 | setNodeMask(0) | Switch::addChild(false, node) |
| 按层过滤 | setNodeMask(1<<n) + setTraversalMask | Switch/Layer 的 mask + traversalMask |
| 取路径 | getNodePath() | 自己维护 ObjectPath + RAII |
| 拾取 | IntersectionVisitor | vsg::Intersector(ConstVisitor) |
| 更新回调 | NodeCallback::operator() | Animation/AnimationGroup,或自定义 Visitor |
| 统计节点数 | NodeVisitor 子类 + apply(Node&) | 同,但注意 apply(Node&) 收不到 Data/Command |
| 修改几何 | Geometry::setVertexArray | 直接改 BufferInfo::data,但要 dirty() 才会重传 |
最后一行值得展开:VSG 的 Data 有 ModifiedCount(第二章 2.5.3 节),改了内容必须调用 dirty(),否则 BufferInfo 认为数据没变,不会重新上传。访问者里改几何,最容易忘的就是这一步。
3.12 陷阱表:22 个可定位的坑
先给全表,每行的"源码坐标"都能直接 sed 出来;表后三条展开那些只看结论看不出成因的机制(名字隐藏、using 的作用域、StateGroup 的 stateCommands)。
| 陷阱 | 触发条件 | 后果 | 源码坐标 | 规避 |
|---|---|---|---|---|
| 忘记下沉 | 重写 apply(X&) 却没调 X.traverse(*this),典型是漏掉 stateCommands 那一轮 | 只有入口节点被访问,计数器偏小 | include/vsg/nodes/StateGroup.h:69 | 每个"中途站"重载都写 traverse;对照 StateGroup 的两轮循环 |
apply(Node&) 接不到数据对象 | 想用 apply(Node&) 收集 Data/MipmapLayout | 收集结果恒空 | include/vsg/core/Visitor.h:200 | 数据对象重写 apply(Data&),它和 MipmapLayout 一样只降级到 Object& |
apply(Geometry&) 漏 VertexDraw | 以为 Geometry 是"所有几何体" | 三角形统计漏掉一部分 | src/vsg/core/Visitor.cpp:641 | 改用 apply(Command&);VertexDraw/VertexIndexDraw/DepthSorted 都不经过 Geometry,后者甚至直接跳 Node& |
在 apply(Object&) 里手写向上转型 | 写成 apply(static_cast<Object&>(object)) | 无限递归,栈溢出 | src/vsg/core/Visitor.cpp:21 | 要调基类实现就写 Visitor::apply(...) 限定调用;Objects 分支同理会递归 |
派生类声明 apply 后基类重载被遮蔽 | 派生类写了任意一个 apply,又用派生类静态类型调用其它重载 | 编译报"没有匹配函数" | include/vsg/state/ArrayState.h:68 | 加一行 using ConstVisitor::apply;;它就写在 getAttributeDetails 声明之后,只影响源码查找 |
忘写 override | 参数写成 const T& 或少了 const,签名对不上 | 变成新增重载,永不执行且无警告 | src/vsg/core/ConstVisitor.cpp:629 | 所有重写一律加 override(同段 CoordinateFrame 用 const Transform&,签名必须逐字对齐) |
instanceCount 没乘 | 只算 vertexCount/3 | 实例化场景少算几个数量级 | include/vsg/nodes/InstanceNode.h:33 | 乘 instanceCount;InstanceNode 继承的是 Compilable 而不是 Group,嵌套实例化再乘实例栈累积值 |
traversalMask 只设不恢复 | 自己在访问者里改掩码,或复用同一实例跑第二遍 | 第二次遍历大面积丢节点 | include/vsg/app/View.h:52 | 照抄 View::t_accept 的保存/收窄/恢复三行 |
| 共享访问者实例跨线程 | 两个线程同时对同一实例 accept | 偶发崩溃或计数错乱,单线程不复现 | include/vsg/app/RecordTraversal.h:78 | 拷贝构造已被 = delete,构造时只能传 Slots,因此只能每线程一个实例 |
遍历中 delete 节点 | 直接 delete 裸指针 | 引用计数被破坏,几帧后崩 | include/vsg/core/Object.h:125 | 收集 ref_ptr 后统一 erase,或交给 DeleteQueue;_attemptDelete 才是正规释放路径 |
StateGroup 对录制器只走 children | 手动 stateGroup.traverse(recordTraversal) | 状态命令不生效 | src/vsg/app/RecordTraversal.cpp:526 | 走 accept,让 apply(const StateGroup&) 里的 state->push 处理 stateCommands |
cast<RecordTraversal>() 永远为空 | 对录制器做 RTTI 判断 | 类型判断永远失败 | include/vsg/app/RecordTraversal.h:87 | 该类的 sizeofObject/className 手写了,is_compatible 没写;不要 cast 到它 |
External 的录制期遍历是空 | 以为外部对象会被录制器走到 | 外部对象从不被录制 | include/vsg/core/External.h:48 | 它只遍历 entries 给前两个家族;录制前把对象挂进场景图 |
Layer 的掩码检查重复三份 | 改了一处以为全改 | 三个访问者家族行为不一致 | include/vsg/nodes/Layer.h:40 | 三份 traverse 必须同步改;Switch 只有一份模板,没有这个问题 |
| 录制期掩码来源不同 | 在 View 之外改 traversalMask | 录到的命令与预期不符 | src/vsg/state/StateSwitch.cpp:62 | 记住录制期读的是 CommandBuffer 的掩码副本,不是访问者的 |
| 只保护了路径栈 | 访问者里读了会失败的数据(文件、索引) | 路径正确、状态栈少弹一层 | src/vsg/utils/Intersector.cpp:42 | 每个栈都配 RAII;arrayStateStack 也要 guard |
ComputeBounds 的实例指针不恢复 | 场景里有嵌套 InstanceNode | 内层实例数泄漏到外层兄弟 | src/vsg/utils/ComputeBounds.cpp:157 | 用栈而不是裸指针;instanceNode 是唯一没有恢复的成员 |
拿 visit<V> 返回值取引用 | auto& m = visit<T>(path).matrix; | 悬空引用,编译器不报 | include/vsg/core/visit.h:36 | 按值取(auto m = ...);visit 返回的是栈上临时对象 |
LOD 只取第一个可见孩子 | 依赖 children 按精细度降序 | 拾取/录制命中错误层次 | src/vsg/app/RecordTraversal.cpp:174 | 自己排序,或用 minimumScreenHeightRatio 显式判断 |
PagedLOD 被剔除后仍入队 | 没检查 culledPagedLODs 是否为空 | 空指针解引用或漏清理 | src/vsg/app/RecordTraversal.cpp:191 | 判空后再 emplace_back;高分辨率子节点要跨帧计数 |
View 的收窄没有 RAII | visitor.apply(node) 抛异常 | traversalMask 永久停在收窄后的值 | include/vsg/app/View.h:56 | 用 guard 对象保存/恢复,别用裸赋值 |
| 拷贝访问者只复制掩码 | 以为拷贝会带走栈与累加器 | 副本的遍历结果与原对象无关 | include/vsg/core/Visitor.h:187 | 拷贝构造只带 traversalMask/overrideMask;状态要自己实现 |
三条需要展开机制的坑
名字隐藏导致自我递归。 在派生类成员函数里做名字查找时,只看派生类声明的 apply;apply(static_cast<Object&>(object)) 会命中你自己重写的 apply(Object&),于是无限递归——这与虚分派无关,是 C++ 的源码级名字查找规则。要调基类实现必须限定调用:Visitor::apply(static_cast<Object&>(object));,这一句是非虚调用。
using 只修源码查找,不修虚分派。 派生类声明任何一个 apply 之后,基类 267 个重载在源码级都不可见,myVisitor.apply(someObject) 会报"没有匹配函数",即使 someObject 是合法类型。加一行 using ConstVisitor::apply; 可解,VSG 自己在两个地方这么做(include/vsg/state/ArrayState.h:68、include/vsg/vk/ResourceRequirements.h:111)——后者在构造函数里就把 overrideMask 设成 MASK_ALL;但 accept 里那 267 次调用走的是基类引用,从来不受影响。
手动 traverse 会漏状态命令。 StateGroup::traverse(RecordTraversal&) 只走 children(include/vsg/nodes/StateGroup.h:75),stateCommands 由 apply(const StateGroup&) 里的 state->push 处理。绕过 accept 直接 traverse,stateCommands 就永远不进栈——症状是"我在 StateGroup 里放了状态,为什么没生效",而不是崩溃。
3.13 本章小结:十个结论与三条路线
3.13.1 十个结论
| # | 结论 | 一句话证据 |
|---|---|---|
| 1 | 267 个 apply 是一棵以继承关系为形状的责任链 | 266 个函数体只有一句 apply(static_cast<Parent&>(value)) |
| 2 | accept 是双分派的那一半 | Inherit 把 267 份 accept 压成 1 份模板(include/vsg/core/Inherit.h:70) |
| 3 | 降级链的长度 = 继承深度 | 典型节点 4–6 次间址,最坏 8 次(九个管线状态类) |
| 4 | traverse 与 accept 必须分离 | 默认不遍历;StateGroup 对两套访问者遍历不同子集 |
| 5 | 掩码不是每个节点都有的 | 只有 5 种类型有 mask 字段;traversalMask 存三份 |
| 6 | 三个分派家族各有分工 | 267 虚重载 / 267 虚重载 / 33 非虚重载 |
| 7 | RecordTraversal 只要 33 个重载,因为状态由 State 栈接管 | 状态切换变成"栈差分 + 一次录制",record 被 dirty 守住(include/vsg/vk/State.h:348) |
| 8 | 热路径与非热路径用不同机制 | CompileTraversal 继承 Visitor,RecordTraversal 手写重载 |
| 9 | 缺一个 apply 是静默降级,不是报错 | 靠 override + cast<> 双重防线 |
| 10 | 访问者的瓶颈不在间接分支,在缓存 | 间接分支单态可预测,指针追逐不可预测 |
3.13.2 三条阅读路线
路线 A(只想用):读 3.4(traverse 与 accept 的分离)→ 3.7(五个真实访问者)→ 3.9(写一个)→ 3.12(陷阱表),跳过 3.1–3.3 的实现细节。
路线 B(想改库):读 3.1(267 个重载的组织)→ 3.3(双分派)→ 3.6(三个家族)→ 3.13.1 结论 3 与 7。重点理解"加一个 apply 是 ABI 破坏"。
路线 C(想借鉴架构):读 3.0(七次跳转的账)→ 3.2(降级链)→ 3.6.2(为什么 33 个够用)→ 3.10(性能账)。四节合起来是一个"在 C++ 里做可扩展类型分派"的完整案例。
3.14 可复现验证
本章所有统计数字都可以用下面几条命令复现(在仓库根目录执行)。
1. apply 重载总数与分段数
grep -c "virtual void apply" include/vsg/core/Visitor.h # 267
grep -c "virtual void apply" include/vsg/core/ConstVisitor.h # 267
grep -c "void apply" include/vsg/app/RecordTraversal.h # 33
2. Visitor.cpp 里"纯转型"的函数个数
grep -c "apply(static_cast<" src/vsg/core/Visitor.cpp # 266
3. 按分段统计 apply 数量
awk '/^ *\/\/ /{sec=$0} /virtual void apply/{c[sec]++} END{for (s in c) print c[s], s}' \
include/vsg/core/Visitor.h | sort -rn
预期输出(前几行):47 // Vulkan nodes、37 // Values、37 // Arrays、34 // Array2Ds、30 // Nodes。
4. 到 Object 的继承边数分布
python3 - <<'EOF'
import re, glob
bases = {}
for f in glob.glob('include/vsg/**/*.h', recursive=True):
s = open(f, encoding='utf-8', errors='ignore').read()
for m in re.finditer(r'class\s+(?:VSG_DECLSPEC\s+)?(\w+)\s*(?:final\s*)?:\s*public\s+'
r'(?:Inherit<\s*(\w+)\s*,\s*\w+\s*>|(\w+))', s):
bases.setdefault(m.group(1), m.group(2) or m.group(3))
types = re.findall(r'virtual void apply\((\w+)&\);',
open('include/vsg/core/Visitor.h', encoding='utf-8').read())
from collections import Counter
hist = Counter()
for t in types:
d, c, seen = 0, t, set()
if c not in bases: c, d = 'Data', 1 # Value/Array 别名
while c != 'Object' and c in bases and c not in seen:
seen.add(c); c = bases[c]; d += 1
hist[d] += 1
print(sorted(hist.items())) # [(1, 30), (2, 157), (3, 27), (4, 36), (5, 8), (6, 9)]
EOF
((2, 157) 里包含 Object 自己——脚本把它误判成了 2 跳,实际是 0 跳。修正后是 1+30+156+27+36+8+9 = 267。)
5. 掩码检查点
grep -rn "traversalMask & (overrideMask\|traversalMask & (visitor.overrideMask\|traversalMask & (commandBuffer.overrideMask" \
include src | wc -l # 12
12 处分布在 5 个头文件(View/Layer×3/RegionOfInterest×3/Switch/StateSwitch)和 2 个 .cpp(RecordTraversal×2、StateSwitch×1)。
6. 验证"降级链"的实际行为
写一个最小程序,只重写 apply(vsg::Node&) 并打印 className(),用它遍历 vsg::Group 套 vsg::MatrixTransform 套 vsg::Geometry 的树。预期输出三行,说明 4 跳之后你的重写被命中:
struct Probe : public vsg::Visitor
{
void apply(vsg::Node& node) override
{
std::cout << node.className() << "\n"; // Group / MatrixTransform / Geometry
node.traverse(*this);
}
};
auto group = vsg::Group::create();
group->addChild(vsg::MatrixTransform::create());
group->addChild(vsg::Geometry::create());
Probe probe;
group->accept(probe);
如果只输出一行,说明 apply(Node&) 里漏了 traverse(陷阱 1)。
7. 验证降级链的方向:apply(Group&) 能接住 MatrixTransform
把上面的 apply(Node&) 改成 apply(Group&),同样的树。预期:Group 和 MatrixTransform 都被打印,Geometry 不被打印。
原因就是 3.2.1 节的机制:MatrixTransform::accept 选中 apply(MatrixTransform&),Visitor::apply(MatrixTransform&) 转型成 Transform& 并虚分派;Transform 没有自己的重写,走 Visitor::apply(Transform&),转型成 Group&;这一跳是虚分派,命中你的 apply(Group&)。
这个实验说明:重写 apply(X&) 覆盖的是"以 X 为祖先的全部类型",不是"恰好等于 X 的类型"。想只处理"纯 Group"(排除 Transform、StateGroup、View),只能在 apply(Group&) 里再判类型——而这正是访问者模式想避免的事,所以正确做法是为你真正关心的每个中间层写重载,别指望一个重载区分"精确类型"和"子类"。
8. 验证 StateGroup 对两套访问者的遍历差异
造一个 StateGroup,塞一个 Translate(状态命令)+ 一个子节点,用两个不同的访问者各遍历一次:
struct CountCommands : public vsg::Visitor
{
int visited = 0;
void apply(vsg::Object& o) override { ++visited; o.traverse(*this); }
};
auto sg = vsg::StateGroup::create();
sg->add(vsg::DepthStencilState::create()); // stateCommands(任何 StateCommand 都行)
sg->addChild(vsg::Group::create()); // children
CountCommands counter;
sg->accept(counter);
std::cout << counter.visited << "\n"; // 3:StateGroup + DepthStencilState + Group
预期输出 3(StateGroup 自己 + stateCommands 里的 DepthStencilState + children 里的 Group)。而 RecordTraversal 走同一棵树时只访问 2 个(跳过状态命令,因为它由 State::push 处理)。
9. 验证名字隐藏
struct Broken : public vsg::Visitor
{
void apply(vsg::Group& group) override { group.traverse(*this); }
};
Broken b;
vsg::ref_ptr<vsg::Object> obj = vsg::Group::create();
b.apply(*obj); // 编译错误:no matching function
Broken 只声明了 apply(Group&),基类的 267 个 apply 在源码级全部不可见,所以 b.apply(*obj) 找不到能接受 Object& 的重载。加上 using vsg::Visitor::apply; 之后编译通过——但注意这不改变运行期行为:obj->accept(b) 依然是虚分派,Object 会一路降级到 apply(Group&)(如果 *obj 真是 Group)。
10. 验证 MipmapLayout 从未被 accept
grep -rn "MipmapLayout.*accept\|accept.*MipmapLayout" include src | wc -l # 0
grep -rn "getMipmapLayout\|setMipmapLayout" include src | wc -l # 16
第一条为 0 说明"有 apply 重载但无 accept 调用"是事实而非推测;第二条的 16 处全是 Data 读写路径(src/vsg/core/Data.cpp:136、144、171、219 与 include/vsg/core/Data.h:224、227,其余是实现里的调用),它们只把 MipmapLayout 当元数据,不遍历。
11. 验证 RecordTraversal 缺 is_compatible
grep -c "is_compatible" include/vsg/app/RecordTraversal.h # 0
grep -c "is_compatible" include/vsg/core/Visitor.h # 1
RecordTraversal 手写了 sizeofObject 与 className(include/vsg/app/RecordTraversal.h:87、88),但没有 is_compatible;Visitor 有(第 491 行)。所以 cast<RecordTraversal>() 走 Object::cast 的 is_compatible(typeid(T)) 分支时恒为假。
12. 三对 accept/traverse 的声明
grep -n "virtual void accept\|virtual void traverse" include/vsg/core/Object.h | wc -l # 6
六行声明成三对出现,三个 traverse 的函数体都是空的 {}——这就是 3.3.3 节说的"默认不遍历"。
3.15 一次完整的调用追踪
场景是这样的五节点树:
root : Group
├── mt : MatrixTransform
│ └── geom : Geometry
└── sw : Switch
└── geo2 : Geometry
访问者只重写两个方法:
struct Probe : public vsg::Visitor
{
void apply(vsg::Object& object) override { object.traverse(*this); }
void apply(vsg::Geometry& geometry) override { /* 命中,不再 traverse */ }
};
root->accept(probe) 的完整序列(按发生顺序,→ 表示一次间址):
| # | 被调用的函数 | 由谁触发 | 说明 |
|---|---|---|---|
| 1 | Group::accept(Visitor&) | 用户代码 | 虚分派 |
| 2 | Visitor::apply(Group&) | accept 内部 | 你未重写 → 基类 |
| 3 | Visitor::apply(Node&) | 上一行 | 基类,继续降级 |
| 4 | Probe::apply(Object&) | 上一行 | 命中,压栈前先遍历 |
| 5 | Group::traverse(Visitor&) | apply(Object&) | 虚分派 |
| 6 | MatrixTransform::accept(Visitor&) | children[0] | 虚分派 |
| 7 | Visitor::apply(MatrixTransform&) | 上一行 | 基类 |
| 8 | Visitor::apply(Transform&) | 上一行 | 基类 |
| 9 | Visitor::apply(Group&) | 上一行 | 基类(Probe 只重写了 Object&) |
| 10 | Visitor::apply(Node&) | 上一行 | 基类 |
| 11 | Probe::apply(Object&) | 上一行 | 命中 |
| 12 | MatrixTransform::traverse(Visitor&) | 上一行 | 虚分派(继承 Group::t_traverse) |
| 13 | Geometry::accept(Visitor&) | children[0] | 虚分派 |
| 14 | Probe::apply(Geometry&) | 上一行 | 命中,不 traverse → 子树结束 |
| 15 | Switch::accept(Visitor&) | 回到第 5 步的循环 | 虚分派 |
| 16 | Visitor::apply(Switch&) | 上一行 | 基类 |
| 17 | Visitor::apply(Node&) | 上一行 | 基类 |
| 18 | Probe::apply(Object&) | 上一行 | 命中 |
| 19 | Switch::traverse(Visitor&) | 上一行 | 虚分派,带掩码检查 |
| 20 | Geometry::accept(Visitor&) | children[0](mask 命中) | 虚分派 |
| 21 | Probe::apply(Geometry&) | 上一行 | 命中 |
21 次调用全部是间接调用:accept 5 次(每个节点一次)+ apply 链 13 次 + traverse 3 次,平均每个节点 4.2 次间址。
换成 RecordTraversal 走同一棵树(Group/Transform/MatrixTransform/Geometry/Switch 五个重载它都有):
| 节点 | accept | apply | traverse |
|---|---|---|---|
root (Group) | 1 | 0(静态命中) | 1 |
mt (MatrixTransform) | 1 | 0(静态命中) | 1 |
geom (Geometry) | 1 | 0(静态命中) | 0 |
sw (Switch) | 1 | 0(静态命中) | 1 |
geo2 (Geometry) | 1 | 0 | 0 |
| 合计 | 5 | 0 | 3 = 8 次间址 |
21 比 8,2.6 倍。 这个比值只用间址计数就能验证,与 CPU 无关;换算成毫秒要另加微架构假设(见 3.18.4)。树的类型越杂,Visitor 侧的 apply 链越长,RecordTraversal 侧仍然是 0——33 个重载在编译期就选定了,从 Group 到 QuadGroup、TileDatabase 各有一份(include/vsg/app/RecordTraversal.h:119)。
3.16 三个不在场景图里的 apply:Objects、External、MipmapLayout
267 个 apply 里有三个类型不属于场景图,但它们的存在解释了访问者设计的边界。
Objects(include/vsg/core/Objects.h):Objects : Inherit<Object, Objects>,成员是 vector<ref_ptr<Object>>。它是"对象容器",不是节点——可以用来把一堆 Data、Image、BufferInfo 打包成一个可序列化的单元。它的 t_traverse 和 Group 一模一样(遍历 children 调 accept),但元素类型是 Object 而不是 Node。这说明遍历机制不依赖 Node,只依赖 accept 和 traverse 这两个虚函数。
External(include/vsg/core/External.h):保存 [文件名, 对象] 的映射,用于把"从外部文件加载的对象"与场景图建立引用关系,序列化时先加载外部对象再恢复内部引用。它的 t_traverse 遍历 entries 里的对象,并做 if (itr->second) 判空——值可能为空(文件存在但加载失败),这是三个容器里唯一做空检查的(Group::t_traverse 没有,因为 children 里理论上不该有空 ref_ptr)。
MipmapLayout(include/vsg/core/MipmapLayout.h):一个 vector<uivec4> 的包装,描述每个 mip 级别的偏移与尺寸。它被存在 Data 的 Auxiliary 里:
// src/vsg/core/Data.cpp:136
void Data::setMipmapLayout(MipmapLayout* mipmapLayout)
{
setObject("mipmapLayout", ref_ptr<MipmapLayout>(mipmapLayout));
}
const MipmapLayout* Data::getMipmapLayout() const
{
return getObject<MipmapLayout>("mipmapLayout");
}
全库没有任何地方对 MipmapLayout 调用 accept()。 它的 apply 重载是"预留接口":如果一个访问者想在遍历 Data 时顺便看到 mip 布局(比如自定义的纹理打包器、压缩器),可以通过 data->getMipmapLayout()->accept(visitor) 拿到。这是 267 个重载里少数的"当前无用"项——封闭访问者集合的代价:为了未来的对称性,现在就要付一个虚表槽位。
三个类型的共同点:apply 集合的边界是"作者认为值得被访问的类型宇宙",不是"场景图里有什么";这个宇宙一次性划定,之后只能加不能减(减就是 ABI 破坏)——这就是 267 的来源。
3.17 如果重写:四种分派方案的取舍
假如今天从零设计一个场景图库,类型分派有四种主流方案。把 VSG 的选择放进去对比,能看清它的位置。
| 方案 | 新增类型的成本 | 新增操作的成本 | 每次分派开销 | 二进制兼容 | 类型安全 |
|---|---|---|---|---|---|
| 虚函数(每操作一个) | 改基类 + 全部子类 | 改基类(ABI 破坏) | 1 次间址 | 差 | 强 |
| 访问者(VSG) | 加 1 个 apply(ABI 破坏) | 加 1 个子类(不动数据类) | 1 + 链长 | 中(加操作安全,加类型不安全) | 强 |
std::variant + std::visit | 改 variant 类型列表 | 加 1 个重载 | 1 次跳转表 + 可能的分支 | 差(类型列表是编译期常量) | 强 |
| 类型擦除 + 函数表 | 运行时注册 | 运行时注册 | 1 次哈希/索引 + 1 次间址 | 好 | 弱(无编译期检查) |
四个方案的关键差异在**"扩展的对称性"**:虚函数让"加类型容易、加操作难";访问者让"加操作容易、加类型难";std::variant 两者都难(加类型要改类型列表、加操作要改所有 visit);函数表两者都容易,但失去编译期检查、分派要过哈希。
VSG 选访问者,是因为它的演进模式是"类型相对稳定、操作不断新增":1.1.x 里 apply 只加了少数几个(DrawMeshTasks*、InstanceNode),访问者子类却一直在加。在这个模式下"加操作零成本"是决定性的,"加类型破坏 ABI"可以推到大版本。std::variant 在 2018 年还不成熟,且 267 个类型分属 13 个模块,一个全局类型列表会让编译时间爆炸——这是时代约束,不是设计优劣。
结论:VSG 的选择在它的约束下(C++17 早期、267 个类型跨 13 个模块、需要二进制兼容的插件生态)是合理的;代价就是 3.12 节那张表——降级链的隐式行为、名字隐藏、静默失败,都是"用继承关系表达类型族"的固有成本。
批判性结论
前面的节都在解释"它怎么工作"。这一节只谈"它哪里可疑、代价落在谁身上、哪些论断其实经不起复现"。每条都给出可 sed 的坐标,读者可以自行核对。
3.18.1 267 个重载是"类型宇宙",不是"需求清单"
MipmapLayout 是最好的证据:它有独立的类声明、Mipmaps 容器、uivec4 元素类型(include/vsg/core/MipmapLayout.h:23),Visitor 也为它留了重载,但全库没有任何一处对它调用 accept——grep -rn "MipmapLayout.*accept" include src 返回 0。唯一碰它的是 Data 的尺寸计算路径:computeValueCountIncludingMipmaps 与 getMipmapLayout(src/vsg/core/Data.cpp:171)只把它当作元数据读取,从不遍历它。
这不是疏忽,而是封闭访问者集合的定价方式:先把"未来可能需要的对称性"写进虚表,再让它一直空着。代价可量化(285 槽 × 8 字节 = 2280 字节/子类,外加 267 个函数的机器码),收益是"任何对象都能被任何访问者以类型安全方式接住"。可疑之处在于边界无人审计:既然 MipmapLayout 证明预留真的发生了,那么下一个预留由谁批准?仓库里没有答案,也没有任何测试断言这个重载会被调用。
同一段里还有一个更小的浪费:visitor.apply(*this) 是 MipmapLayout 唯一可能的入口(src/vsg/core/Visitor.cpp:40 把它降级到 Data&),而 Data& 再降级到 Object&(src/vsg/core/Visitor.cpp:35)。也就是说,真有人调用它,两跳之后仍然落在空函数里——除非访问者恰好重写了 apply(Data&)。
3.18.2 手写样板的三处缺口,全部可复现
第一处:is_compatible。 Visitor 重写了它(include/vsg/core/Visitor.h:491),Inherit 给所有 CRTP 派生类提供了实现(include/vsg/core/Inherit.h:50),Object 的默认实现只判 typeid(Object) == type(include/vsg/core/Object.h:86)。而 RecordTraversal 手写了 sizeofObject 和 className(include/vsg/app/RecordTraversal.h:88),偏偏漏了 is_compatible。于是 cast<RecordTraversal>() 恒为空:Object::cast 走的是 is_compatible(typeid(T)),返回 typeid(Object) == typeid(RecordTraversal),恒假。
第二处:插桩坐标。 InstrumentationNode 的三个 SourceLocation 在构造函数里写死了行号 42/48/54(src/vsg/nodes/InstrumentationNode.cpp:23),三个 traverse 实际在 64/70/76 行;三份名字字符串还都写成 InstrumentationNode::traverse(Visitor& rt)(src/vsg/nodes/InstrumentationNode.cpp:25),连 ConstVisitor 那份也没改。性能分析器会把这三段耗时归到错误的源码行与错误的方法名上,而没人会察觉——SourceLocation 只是统计标签,不是断点。
第三处:遍历顺序。 Intersector::apply(const Geometry&) 先把索引数组 accept 出去,再构造 PushPopNode(src/vsg/utils/Intersector.cpp:174);而 apply(const StateGroup&) 的第一句就是 guard(src/vsg/utils/Intersector.cpp:66,紧接 prototypeArrayState 的克隆)。同一个类里,_nodePath 的保护范围不一致。今天不出错,只因为索引数组的 apply 不读路径——这是一个靠调用者自律维持的不变式,不是编译器保证的。
这三处缺口的共同点是:它们都由"手写样板"产生,而手写样板的正确性没有任何自动化检查。Inherit 覆盖的 267 个类不会犯这类错,因为它们根本不写这些函数。
3.18.3 掩码的三副本是设计债,不是设计
View::t_accept 用 traversalMask 收窄再恢复(include/vsg/app/View.h:56),没有 RAII;RecordTraversal::apply(const View&) 又把它灌进命令缓冲区并缓存旧值(src/vsg/app/RecordTraversal.cpp:567);StateSwitch::record 在录制期从 commandBuffer 读同一对掩码(src/vsg/state/StateSwitch.cpp:62)。三份副本靠"保存—赋值—恢复"的裸赋值串联,任何一次异常都会留下偏斜值。
overrideMask = MASK_ALL 的写法也不统一:CompileTraversal 只在构造函数里设 overrideMask(include/vsg/app/CompileTraversal.h:36),没有把 traversalMask 复位;CollectResourceRequirements 同样只设 overrideMask(include/vsg/vk/ResourceRequirements.h:104);UpdateGraphicsPipelines 也是(src/vsg/app/WindowResizeHandler.cpp:24)。按 T & (O | M) 的语义,traversalMask = 0 时 overrideMask 完全无效——"无视掩码"这个命名只兑现了一半。
更麻烦的是录制期的读取者不是访问者本身:RecordTraversal::apply(const Layer&) 读的是自己的 traversalMask 与 overrideMask(src/vsg/app/RecordTraversal.cpp:328),而 StateSwitch::record 读的是 commandBuffer 上的副本。同一个概念,两条读取路径,靠 apply(const View&) 里那次赋值保持同步。谁在 View 之外改 traversalMask,就是在赌下一次同步的时机。
3.18.4 性能论证里,可证伪的是间址计数,不可证伪的是周期数
本章反复用"每次 2–5 周期""预测失败 15–25 周期"折算毫秒。这些数字来自微架构经验,随 CPU 代际漂移,无法用仓库内命令复现,属于叙述而非证据。可证伪的部分是间址次数:一棵五节点树,Visitor 侧 21 次、RecordTraversal 侧 8 次,这个比值与 CPU 无关,可以用 3.14 的 Probe 程序配合计数器验证。
真正决定帧时间的是缓存,而缓存行为由分配器决定:Group::children 用的是带亲和性的 allocator_affinity_nodes(include/vsg/nodes/Group.h:36),节点是否连续取决于加载顺序,不取决于访问者。所以"访问者慢 2.6 倍"应当限定为"间接调用多 2.6 倍"——把它读成"帧时间多 2.6 倍"是过度解读。
录制侧还有两个被忽略的常量:intensityMinimum 把弱光直接过滤在 CPU 侧(include/vsg/app/RecordTraversal.h:94),minimumBinNumber 决定哪些 bin 参与录制(include/vsg/app/RecordTraversal.h:183),RecordTraversal::apply(const View&) 还会把 cached_minimumBinNumber 存下来再恢复(src/vsg/app/RecordTraversal.cpp:573)。这两项对帧时间的影响远大于 apply 链长度,却不出现在任何"访问者 vs 虚函数"的对比表里。
3.18.5 录制路径真正的状态机是 State,不是 RecordTraversal
State::record() 只在 dirty 为真时把 stateStacks 逐槽录制(include/vsg/vk/State.h:348),而 push 的末尾把 dirty 置真(include/vsg/vk/State.h:374)。这解释了 RecordTraversal 只需要 33 个重载:状态切换被折叠成"栈顶变化 + 一次差分录制",遍历只需要知道"哪个节点要出图"。
代价是调试困难:一条 vkCmdBindPipeline 的来源不是某次 apply,而是"某个 StateGroup 的 stateCommands 被 push,然后某次 record 时栈顶变了"。断点打在 apply 上永远看不到它;能看到的只有 apply(const StateGroup&) 里那三行 push / traverse / pop(src/vsg/app/RecordTraversal.cpp:521)。
由此推论:RecordTraversal 的 33 个重载里,真正"做决策"的只有剔除、分箱、LOD 选择这几类,其余都是"把节点交给 state->record()"。把重载数当成"设计复杂度"来比较,会高估它的复杂度、低估 State 的复杂度。
3.18.6 三处"看起来该统一却没统一"的地方
External的录制期遍历是空实现。 前两个家族的traverse都遍历entries,RecordTraversal那份是空的(include/vsg/core/External.h:48)。这是有意的:录制阶段不需要外部引用。但接口里没有任何注释说明这一点,读者只能从空函数体反推。ComputeBounds用裸指针记实例节点。instanceNode = ∈之后不恢复(src/vsg/utils/ComputeBounds.cpp:157),而matrixStack、arrayStateStack都是栈。嵌套InstanceNode时,内层的实例数会泄漏到外层的兄弟节点。FindCameras的键类型带来每次命中的分配。 键是RefObjectPath(include/vsg/app/Camera.h:51),每命中一次相机都要把_objectPath拷成convertedPath再插入 map(src/vsg/app/Camera.cpp:71)。一次性工具无所谓;放进每帧路径就是每个相机一次 vector 分配。
FindCameras 还有一个顺序问题:cameras 是 std::map,键比较走 ref_ptr::operator<,即裸指针地址。同一批对象在单次运行内地址稳定,跨运行不可复现——任何"取第一个相机当主视角"的代码都在依赖堆布局。
3.18.7 如果只能改五处
- 给
RecordTraversal补is_compatible,照抄Inherit的两行形式(对照include/vsg/app/RecordTraversal.h:87相邻的sizeofObject)。 - 把
InstrumentationNode的三份SourceLocation换成__LINE__,并修正方法名字符串(src/vsg/nodes/InstrumentationNode.cpp:23)。 - 把
Intersector::apply(const Geometry&)的 guard 提到函数首行(src/vsg/utils/Intersector.cpp:174)。 - 把
View::t_accept的收窄—恢复改成 guard 对象(include/vsg/app/View.h:52)。 - 让
CompileTraversal构造时显式复位traversalMask(include/vsg/app/CompileTraversal.h:36)。
这五处都不碰虚表,因此都不破坏 ABI。反过来说:这套设计的 ABI 刚性只约束"类型集合",不约束"实现质量"。267 个槽位锁死了你能加什么类型,却锁不住你把 is_compatible 漏写、把行号写错、把 guard 放晚。前者是架构问题,后者是工程纪律问题——而本章列出的绝大多数真实故障,都属于后者。
源码索引
本章用到的文件按职责分四组:
- 分派骨架:
include/vsg/core/Visitor.h(267 个apply声明、traversalMask/overrideMask、is_compatible)、src/vsg/core/Visitor.cpp(266 句转型 + 1 个空实现)、include/vsg/core/ConstVisitor.h与src/vsg/core/ConstVisitor.cpp(同一套的const版本)、include/vsg/core/Inherit.h(CRTP 三个accept)、include/vsg/core/Object.h(accept/traverse三对虚函数、cast)、include/vsg/core/visit.h(10 个visit重载)。 - 遍历语义:
include/vsg/nodes/Group.h、include/vsg/nodes/StateGroup.h、include/vsg/nodes/Switch.h、include/vsg/nodes/Layer.h、include/vsg/nodes/RegionOfInterest.h、include/vsg/core/Objects.h、include/vsg/core/External.h(各自的t_traverse与掩码判断)。 - 录制链:
include/vsg/app/RecordTraversal.h(33 个非虚重载)、src/vsg/app/RecordTraversal.cpp(兜底、StateGroup压栈、掩码灌入)、include/vsg/vk/State.h(record/push的栈差分)、include/vsg/state/StateSwitch.h与src/vsg/state/StateSwitch.cpp(录制期掩码)。 - 具体访问者:
src/vsg/app/Camera.cpp(FindCameras)、src/vsg/animation/FindAnimations.cpp、src/vsg/utils/Intersector.cpp(PushPopNode)、src/vsg/utils/ComputeBounds.cpp(instanceNode)、src/vsg/utils/LoadPagedLOD.cpp(四个栈)、src/vsg/app/WindowResizeHandler.cpp(visited去重)、include/vsg/maths/transform.h与src/vsg/maths/maths_transform.cpp(ComputeTransform)。
下一章预告
第四章回到 core/ 的数学层:mat4/dmat4 的存储顺序(列主序还是行主序、与 GLSL 的对应关系)、quat 与 dquat 的乘法方向、plane/sphere/box 的几何语义、transform() 与 inverse() 的数值精度陷阱,以及为什么 VSG 默认 Z-up 而 Vulkan 的 NDC 是 Y-up——这个不一致导致所有初学者的第一张图都是上下颠倒的。
我们会用 include/vsg/maths/ 的 30 个头文件,把"一个 dmat4 从 CPU 内存里的 128 字节到顶点着色器里的 mat4 变量"这条路上的每一次转置、每一次坐标系翻转都标出来。