《VulkanSceneGraph 1.1.16 源码深度解析》第一章 全景与底色:架构分层与四个奠基性决策

0 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第一章 全景与底色:架构分层与四个奠基性决策

源码基线:VulkanSceneGraph 1.1.16(VSG_SOVERSION 17) 本章对应模块:include/vsg/core/、include/vsg/vk/、CMakeLists.txt 源码索引见章末。

1.0 先做一次测量,再谈架构

谈架构最容易滑向空话。所以在讲"分层""解耦""高性能"之前,我们先对这个仓库做一次可复现的测量:

find include/vsg -name "*.h"  -exec cat {} + | wc -l     # 31982
find src/vsg   -name "*.cpp" -exec cat {} + | wc -l     # 111673
find include/vsg -name "*.h"  | wc -l                    # 305
find src/vsg   -name "*.cpp" | wc -l                     # 252
grep -c "virtual void apply" include/vsg/core/Visitor.h  # 267

把五个数字放在一起,能读出四件比任何宣传语都可靠的事实:

事实一:头文件很薄,实现文件很厚。 305 个头文件平均 105 行,252 个实现文件平均 443 行;而 105 行里还有约 20 行 MIT 许可证注释,头文件的"有效内容"平均只有 80 多行。这意味着 VSG 刻意避免把实现塞进头文件——模板和内联被限制在少数几个真正需要的地方(ref_ptr、Inherit、Array、visit),而不是像很多现代 C++ 库那样把整个库做成 header-only。

这个选择的收益是编译防火墙:改一个 .cpp 不会引发下游全量重编;代价是跨翻译单元的优化被切断。VSG 的补偿办法是:"每帧调用几百万次"的函数放头文件内联,"每次加载只调一次"的函数放 .cpp。Object::ref() 是前者的样板,一行 fetch_add 直接写在 include/vsg/core/Object.h:122;Object::clone() 是后者的样板,实现在 src/vsg/core/Object.cpp:102,函数体先查 copyop.duplicate->duplicates 再决定是否 const_cast 回传自己。这条界线划得非常清楚,你在阅读源码时会反复看到它。

事实二:类的粒度极细。 252 个 .cpp 对应 305 个头文件,接近"一个类一个实现文件"。没有 SceneGraph.cpp 这种几千行的巨石文件。src/vsg/nodes/ 下每个节点类型都有自己的 .cpp,src/vsg/state/ 下每个状态结构也各自独立。StateGroup 的全部状态就是一个 StateCommands stateCommands 成员(include/vsg/nodes/StateGroup.h:37),Camera 把 projectionMatrix、viewMatrix、viewportState 三个成员并排声明(include/vsg/app/Camera.h:34)。

这带来两个工程后果:其一,增量构建的并行度高,改 LOD.cpp 只重编一个文件;其二,每个类的职责边界在文件系统层面就是可见的——你想知道 DepthSorted 能做什么,只需要看一个 100 行左右的 .cpp,不需要在巨石文件里翻找。

事实三:访问者不是"设计模式示例",而是基础设施。 Visitor.h 里有 267 处 virtual void apply(...) 声明(这个数字同时覆盖 Visitor 和 ConstVisitor 两个类)。也就是说,这个库的类型系统有一半是"能被访问的类型列表"。这份列表摊开就是几百行连续的声明,比如 virtual void apply(DepthSorted&); 落在 include/vsg/core/Visitor.h:355。任何新增节点类型,都必须同时修改访问者接口——这是 VSG 最重要的耦合点,也是它性能的来源。第 3 章会专门拆解这套机制。

事实四:代码总量约 14.4 万行。 这个规模恰好落在"一个人可以通读"与"必须靠架构才能维持"的边界上。它没有小到可以靠记忆维护,也没有大到必须分层到官僚化。理解这一点,你就能理解后面很多"看起来过度设计"的地方,其实是在为 10 年后的可维护性付费。同样的规模也解释了 Object::operator new 为什么要绕道分配器:src/vsg/core/Object.cpp:236 把每次 new 转成 vsg::allocate(count, ALLOCATOR_AFFINITY_OBJECTS),让 24 字节的小对象成批落进内存池,而不是逐个走系统分配器。

1.0.1 本章的问题清单

这一章不追求把 305 个头文件讲全,只回答十个能在源码里定位到具体行的问题。后面每一节都对应其中之一。

  1. vsg::Object 的两个私有成员 _referenceCount 与 _auxiliary 为什么让对象在 LP64 下正好 24 字节(include/vsg/core/Object.h:190)?
  2. 为什么 ref() 用 memory_order_relaxed,unref() 却用 memory_order_seq_cst(include/vsg/core/Object.h:122)?
  3. cast<T>() 不走 dynamic_cast 时,靠什么函数保证转型合法(include/vsg/core/Object.h:96)?
  4. Inherit::compare() 凭什么敢对派生部分直接 memcmp(include/vsg/core/Inherit.h:67)?
  5. 元数据容器 userObjects 为什么挂在 Auxiliary 上,而不是做成 Object 的成员 map(include/vsg/core/Auxiliary.h:45)?
  6. 删除否决钩子 signalConnectedObjectToBeDeleted() 在 1.1.16 里究竟被谁实现(include/vsg/core/Auxiliary.h:96)?
  7. 一次 Viewer::recordAndSubmit() 怎样落到 vkCmdDrawIndexed(src/vsg/app/Viewer.cpp:820)?
  8. 编译一个子图时,CollectResourceRequirements 与 CompileTraversal 的先后顺序由谁保证(src/vsg/app/CompileManager.cpp:260)?
  9. RecordTraversal::apply(const View&) 为什么先 view.traverse(*this) 把内容排进 bin,再对 view.bins 逐个 accept 回放(src/vsg/app/RecordTraversal.cpp:654)?
  10. VertexIndexDraw 到底是节点还是命令,它有没有"三个子命令"(src/vsg/nodes/VertexIndexDraw.cpp:184)?

1.0.2 答案骨架:十条结论先行

先给结论,再给坐标,最后标性质。性质一列说明这条结论能不能改:锁死 表示改了要动 ABI,约定 表示靠调用方自律,死路 表示代码存在但当前无人使用。

#结论证据坐标性质
1Object 只有 atomic_uint 计数与 Auxiliary* 两个私有成员,虚表指针加上填充后为 24 字节include/vsg/core/Object.h:190锁死:布局变则 ABI 变
2ref() 加一用 relaxed,unref() 减一用 seq_cst,减法结果 <= 1 就调 _attemptDelete()include/vsg/core/Object.h:125锁死:放宽内存序会延长可见性窗口
3cast<T>() 的实现是 is_compatible(typeid(T)) ? static_cast<T*>(this) : nullptrinclude/vsg/core/Object.h:96约定:只在单继承下成立
4Inherit::compare() 从 sizeof(ParentClass) 偏移起比较派生字节,基类部分交给父类include/vsg/core/Inherit.h:57约定:要求 POD、无指针、零初始化
5Auxiliary::userObjects 是公开的 std::map,setObject() 里没有任何加锁动作include/vsg/core/Auxiliary.h:47约定:库内假定单线程写入
6signalConnectedObjectToBeDeleted() 在库内没有派生实现,默认实现在计数已归零时必然返回 truesrc/vsg/core/Auxiliary.cpp:58死路:钩子在,通路不在
7GPU 资源的延迟释放由 DeleteQueue 用帧号队列完成,retainForFrameCount 默认为 3include/vsg/threading/DeleteQueue.h:39可调:改成员值即可
8一条提交路径是 submit() → start() 等 fence → transferData → record() → finish()src/vsg/app/RecordAndSubmitTask.cpp:85锁死:任务类没有 run()
9VertexIndexDraw 继承 Command,record() 里连绑顶点/索引缓冲再调 vkCmdDrawIndexedsrc/vsg/nodes/VertexIndexDraw.cpp:184事实:不存在三个子命令
10Bin::add() 把排序用的深度值 static_cast<float> 后存成 _binElements 的键src/vsg/nodes/Bin.cpp:104代价:深度精度降到 float

1.1 从 CMakeLists.txt 读出的九个事实

顶级 CMakeLists.txt 只有两百多行,但它是整个库的"物理定律"。逐条读:

project(vsg
    VERSION 1.1.16
    DESCRIPTION "VulkanSceneGraph library"
    LANGUAGES CXX
)
set(VSG_SOVERSION 17)
SET(VSG_RELEASE_CANDIDATE 0)
set(Vulkan_MIN_VERSION 1.1.70.0)

set(VSG_MAX_DEVICES 1 CACHE STRING "Set maximum number of vk/vsg::Device that are supported.")
set(VSG_MAX_INSTRUMENTATION_LEVEL 1 CACHE STRING "...")
option(VSG_SUPPORTS_ShaderCompiler "Optional shader compiler support" ON)
option(VSG_SUPPORTS_Windowing "Optional native windowing support ..." ON)

1.1.1 SOVERSION 17 与 VERSION 1.1.16 的分离

项目版本是 1.1.16,共享库 ABI 版本却是 17。这两个数字不同步,是一个明确的承诺:1.1.x 系列保证二进制兼容。

为什么这件事重要?因为 VSG 的生态是"一个核心库 + 一堆独立仓库":vsgXchange(模型/图像加载)、vsgQt、vsgImGui、vsgPoints、osg2vsg。这些库都是动态链接 libvsg.so.17 的。如果每个补丁版本都提升 SOVERSION,那么用户升级核心库就必须重编所有插件;反之,保持 SOVERSION 不变,意味着你不能在补丁版本里给虚基类加虚函数、不能改类布局、不能改枚举值。

这条约束反过来解释了 VSG 很多设计:为什么新功能总是通过"新增类"而不是"给旧类加虚函数"实现?为什么 Visitor 的 apply 集合一旦发布就几乎不再增长,新类型宁可通过 apply(Object&) 兜底 + cast<> 处理?因为加一个 apply 重载就会改变 Visitor 的虚表布局,破坏 ABI。

实践建议:如果你要基于 VSG 做二次开发并发布二进制插件,把 SOVERSION 的变化当作"必须全量重编"的信号;反之,如果你只在应用内静态链接,这条约束与你无关,你可以随意扩展。

1.1.2 Vulkan_MIN_VERSION 1.1.70.0

要求 Vulkan 1.1.70 及以上。这个数字不是随手写的:1.1.70 是 Vulkan 1.1 系列中一个被广泛采用的头部版本,包含了 VK_KHR_swapchain、VK_KHR_maintenance1 等 VSG 依赖的扩展定义。

它的实际含义是:VSG 的基线是 Vulkan 1.1,不要求 1.2/1.3 的核心特性。诸如 vkCmdDrawIndexedIndirectCount(1.2 提升为核心)、VK_KHR_synchronization2、动态渲染(vkCmdBeginRendering,1.3)都不在必需路径上。VSG 的做法是"检测到就用,检测不到就走老路"——这正是 DeviceFeatures、DeviceExtensions 这两个类存在的理由(第 7 章)。

对读者的启示:如果你在教程里看到 VSG 用 VkRenderPass/VkFramebuffer 而不是动态渲染,不要以为是"过时",那是为了兼容 1.1 基线。想用新特性,走扩展协商,而不是改核心。

1.1.3 VSG_MAX_DEVICES 默认为 1:一个字节级的优化

这是全库最能体现"性能偏执"的一处。看 include/vsg/vk/vk_buffer.h:

#if VSG_MAX_DEVICES <= 1

    /// vk_buffer that manages a single logical device supported.
    template<class T>
    struct vk_buffer
    {
        T value;

        T& operator[](uint32_t) { return value; }
        const T& operator[](uint32_t) const { return value; }
        constexpr static uint32_t size() { return 1; }
        // ...
    };

#elif VSG_MAX_DEVICES <= 4
    template<class T>
    struct vk_buffer
    {
        std::array<T, VSG_MAX_DEVICES> buffer;
        // ...
    };
#endif

vk_buffer<T> 是"按设备 ID 索引的一份数据"。在支持多 GPU 的系统里,同一个 vsg::Buffer 对象需要在每个逻辑设备上有一份 VkBuffer。最直白的实现是 std::vector<T> 或 std::array<T, N>。

但 VSG 选择了编译期特化。分水岭是 include/vsg/vk/vk_buffer.h:24 的 #if VSG_MAX_DEVICES <= 1:这一支里 vk_buffer 只有一个 T value 成员(include/vsg/vk/vk_buffer.h:30),operator[] 收到设备号后直接丢掉、返回同一个 value,size() 是 constexpr 的 1。默认构建下,一个"多设备容器"被编译成了单值。

这个优化有多大意义?算一笔账:std::vector 在 libstdc++ 上是 24 字节(三个指针),std::array<T,1> 是 sizeof(T)。一个 VkBuffer 是 8 字节的 VkBuffer_T*(non-dispatchable handle 在 64 位下是指针大小)。于是:

实现每个 Buffer 的存储开销(单设备)
std::vector<VkBuffer>24 字节 + 堆分配(一次 malloc + 一次 free)
std::array<VkBuffer,1>8 字节
vk_buffer 特化8 字节,零额外分配

一个中等规模的场景有 1 万到 10 万个 vsg::Buffer(顶点、索引、uniform、存储缓冲)。用 std::vector 意味着 10 万次堆分配和 24 字节的常驻开销;特化之后是 0 次分配、8 字节。这不是"微优化",这是把"每个资源对象的固定成本"从 O(分配) 降到 O(1) 的内存写入。

代价:VSG_MAX_DEVICES 是编译期常量,意味着它不能运行时改变,而且改变它需要重编整个库以及所有使用 vk_buffer 的代码。多设备的下一档在 include/vsg/vk/vk_buffer.h:46(#elif VSG_MAX_DEVICES <= 4),那里换成 std::array<T, VSG_MAX_DEVICES> buffer(include/vsg/vk/vk_buffer.h:52),size() 也从常量 1 变成常量 N。这是一个典型的"用灵活性换确定性"的决策。如果你要做多 GPU 渲染,必须在构建时把它设为 2 或 4。

更深一层的启示:VSG 的性能策略不是"到处用 fancy 算法",而是先消除每个对象的固定开销。百万级对象乘以 16 字节的浪费就是 16MB 的带宽,这在每帧都要遍历的路径上是致命的。第 4 章讲分配器时你会看到同一种思路的另一种表达。

1.1.4 VSG_MAX_INSTRUMENTATION_LEVEL:把 profiling 编译掉

默认值是 1(粗粒度),可选 0(关闭)、2(中)、3(细)。include/vsg/utils/Instrumentation.h 里用它控制一大组宏是否展开:

// include/vsg/utils/Instrumentation.h:170
#    define CPU_INSTRUMENTATION_L1(instrumentation) __CPU_INSTRUMENTATION(1, instrumentation, nullptr, COLOR_DEFAULT, nullptr)

// include/vsg/utils/Instrumentation.h:194
#    define CPU_INSTRUMENTATION_L1(instrumentation)

同一行宏在 VSG_MAX_INSTRUMENTATION_LEVEL >= 1 时展开成一个带 SourceLocation 的作用域对象,在 #else 分支里展开成空(include/vsg/utils/Instrumentation.h:194)。差别不是"运行时跳过",而是调用点连同 instrumentation 这个表达式一起从翻译单元里消失,连指针判空都没有了。

这里的设计哲学值得单独说:profiling 的成本必须在编译期可裁剪,而不是靠运行时 if (enabled)。因为记录一次时间戳是 clock_gettime 或 vkCmdWriteTimestamp,它的开销远大于一次分支预测;在百万节点的遍历里,"关闭但仍存在的分支"依然会污染指令缓存和流水线。

Instrumentation 本身是个虚基类,Viewer::assignInstrumentation() 可以在运行时挂载/卸载实现(第 26 章会讲 Profiler 与 TracyInstrumentation)。所以 VSG 提供了两级开关:编译期决定"能不能测",运行时决定"测不测"。这是一个很成熟的工程设计——很多库只做了后者,结果是在发布版里测不出真实性能,因为插桩代码本身改变了 cache 行为。

1.1.5 VSG_SUPPORTS_ShaderCompiler:为什么 shader 编译是"可选"的

option(VSG_SUPPORTS_ShaderCompiler "Optional shader compiler support" ON)
if (VSG_SUPPORTS_ShaderCompiler)
    find_package(glslang CONFIG QUIET)
    if (glslang_FOUND)
        ...
    else()
        message(WARNING "glslang not found. ShaderCompile support disabled.")
    endif()
endif()

VSG 支持在运行时把 GLSL 编译成 SPIR-V(vsg::ShaderCompiler,内部调用 glslang),也支持直接加载预编译的 .spv。前者方便开发(改 shader 不用离线工具),后者是部署必需:iOS、部分 Android 设备、以及很多嵌入式平台不允许在运行时进行 shader 编译,或者根本没有 glslang。

这条配置塑造了 VSG 的资源模型:ShaderStage 既可以持有源码字符串,也可以持有 SPIR-V 二进制;Options::shaderSets 是一个按 std::string 索引的映射,允许按名字替换整个着色器集合(include/vsg/io/Options.h:91,第 10 章)。编译器的实例挂在 Context::shaderCompiler 上(include/vsg/vk/Context.h:116),取用时走 getOrCreateShaderCompiler() 惰性创建(include/vsg/vk/Context.h:88)——没有 glslang 的构建里这个指针永远是空的。更微妙的是,它解释了为什么 CompileTraversal 要区分"编译"与"上传"两个阶段:shader 编译可能失败、可能耗时几百毫秒,它必须能被异步化、能被缓存(Options::fileCache,include/vsg/io/Options.h:74)。

1.1.6 VSG_SUPPORTS_Windowing:无窗口构建

关掉它可以构建一个不依赖任何原生窗口系统的 libvsg。这不是为了"精简",而是为了两个真实场景:

  1. 服务器端/离线渲染:用 VK_EXT_headless_surface 或者直接渲染到 VkImage,不需要 X11/Wayland/Win32。
  2. 嵌入到别人的窗口系统:比如你把 VSG 集成到一个自研引擎里,那个引擎已经管好了 VkSurfaceKHR,你只需要一个接受外部 VkSurfaceKHR 的窗口对象。

include/vsg/platform/ 下按平台分目录(win32、xcb、macos、ios、android、harmony),每个平台一个 *_Window.cpp,实现同一套 Window 接口。第 27 章会拆解这层抽象。

1.1.7 MSVC 的 /bigobj 与 macOS 的 .mm

if (MSVC)
    add_compile_options(/bigobj)
endif()

/bigobj 把 COFF 对象的节数上限从 65535 提高。触发它的原因通常是单个翻译单元里有海量模板实例化或海量函数——在 VSG 里罪魁祸首是 Visitor.h 的 267 个虚函数声明,加上 Array<T> 对几十种元素类型的实例化。这条选项是"接口面非常大"的侧面证据:它让类型安全做到极致(每个类型都有自己的 apply),也让编译时间和二进制体积付出代价。

顶层 project() 只声明 LANGUAGES CXX,但 src/vsg/platform/macos/ 下有 .mm(Objective-C++)文件。这是 CMake 的常规做法:.mm 由 clang 自动按 Objective-C++ 处理,不必在 project() 里声明 OBJCXX。它说明 macOS/iOS 的窗口层必须通过 Objective-C 运行时访问 MoltenVK 的 CAMetalLayer,C++ 无法直接调用。

1.1.8 平台条件编译的边界

src/vsg/CMakeLists.txt 里平台源文件是条件加入的:

if (ANDROID)
    set(SOURCES ${SOURCES} platform/android/Android_Window.cpp)
elseif (HARMONY)
    set(SOURCES ${SOURCES} platform/harmony/Harmony_Window.cpp)
elseif (WIN32)
    set(SOURCES ${SOURCES} platform/win32/Win32_Window.cpp)
elseif (APPLE)
    if (IOS)
        ...
    else()
        set(SOURCES ${SOURCES} platform/macos/MacOS_Window.mm)
    endif()
else()
    set(SOURCES ${SOURCES} platform/xcb/Xcb_Window.cpp)
endif()

注意最后的 else() 分支默认走 XCB。这意味着Linux 上默认依赖 XCB,而不是 Wayland。如果你的目标环境是纯 Wayland,需要自己实现或等待上游支持——这是实践中的一个坑,值得在选型时确认。

1.2 代码地形图:17 个模块的重量分布

include/vsg/ 下有 17 个子目录(外加聚合头 all.h)。按头文件数量排序:

模块头文件数职责一句话概括
state/36管线状态与资源描述把 Vulkan 的"创建信息结构体"变成可比较、可复用的对象
commands/34命令对象把 vkCmd* 变成可遍历、可排序、可序列化的节点
vk/27Vulkan 句柄封装Instance/Device/Context/ResourceRequirements 等
core/26对象模型与容器Object、ref_ptr、Visitor、Array、Allocator
nodes/26场景图节点Group、Transform、StateGroup、LOD、Geometry
io/26序列化与加载Options、ReaderWriter、Input/Output、Path
app/22应用框架Viewer、Window、View、CommandGraph、RecordTraversal
utils/19工具Builder、ShaderSet、Intersector、Instrumentation
maths/16数学vec*、mat*、quat、box、sphere、plane
ui/15事件UIEvent 家族、FrameStamp、Keyboard
animation/11动画Animation、Sampler、Joint
lighting/9光照阴影Light 家族、ShadowSettings
raytracing/9光追AccelerationStructure、RayTracingPipeline
text/9文本Font、Text、TextGroup
threading/9同步Barrier、Latch、FrameBlock、DeleteQueue
platform/7平台窗口各平台 Window 实现
meshshaders/3Mesh ShaderDrawMeshTasks* 三个命令

几个值得注意的失衡:

  • state/ 比 nodes/ 还多。这在 OSG 时代是不可想象的(OSG 的 State 只有几十个类)。原因是 Vulkan 把"管线状态"拆成了 8 个独立结构体(VertexInputState、InputAssemblyState、TessellationState、ViewportState、RasterizationState、MultisampleState、DepthStencilState、ColorBlendState),每个都需要一个 C++ 类来持有、比较、序列化。GraphicsPipeline 自己不关心有几个状态,它只存一个 GraphicsPipelineStates pipelineStates 列表(include/vsg/state/GraphicsPipeline.h:71),具体数量由场景决定。Vulkan 的复杂度直接反映在类数量上,这是任何封装层都躲不掉的。
  • meshshaders/ 只有 3 个头。这说明 VSG 对待新特性的策略是"最小侵入":Mesh Shader 只是三种新的绘制命令,不需要动场景图核心。这个模式在 raytracing/ 上也成立(9 个头,主要是加速结构与管线)。
  • core/ 只有 26 个头,但它是整个库的重力中心。Object.h、Visitor.h、ref_ptr.h、Inherit.h 这四份文件定义了后面 280 个头文件的写法:RasterizationState::cullMode 能默认成 VK_CULL_MODE_BACK_BIT(include/vsg/state/RasterizationState.h:31),前提就是 Inherit 已经替每个状态类写好了 create、compare、accept。

1.3 分层:目录结构会骗人

教科书式的分层假设是:目录 = 层次,依赖只能向下。VSG 不是这样。

看三个反例:

// include/vsg/vk/Context.h
#include <vsg/app/TransferTask.h>          // vk 依赖 app
#include <vsg/commands/Command.h>          // vk 依赖 commands
#include <vsg/state/BufferInfo.h>          // vk 依赖 state
#include <vsg/utils/ShaderCompiler.h>      // vk 依赖 utils
#include <vsg/utils/Instrumentation.h>

// include/vsg/app/CommandGraph.h
#include <vsg/nodes/Bin.h>                 // app 依赖 nodes
#include <vsg/vk/CommandBuffer.h>          // app 依赖 vk

// include/vsg/nodes/StateGroup.h:16
#include <vsg/state/ArrayState.h>          // nodes 依赖 state
#include <vsg/state/StateCommand.h>

如果按"依赖必须向下"来评判,这个代码库是"乱"的:vk/Context.h 依赖了 app/、commands/、state/、utils/ 四个"上层"模块。四条依赖各自占一行:TransferTask 在 include/vsg/vk/Context.h:18,Command 在 include/vsg/vk/Context.h:19,BufferInfo 在 include/vsg/vk/Context.h:24,ShaderCompiler 在 include/vsg/vk/Context.h:28。

但这不是错误,而是一个刻意的例外。理解这个例外,你就理解了 VSG 的整体形状。

1.3.1 真实的层次模型

去掉目录名的干扰,按"谁包含谁"和"谁在运行时调用谁"重新画,得到的是这样一个结构:

┌─────────────────────────────────────────────────────────────┐
│  L5 应用编排层                                                │
│     app/Viewer  app/Presentation  app/RecordAndSubmitTask    │
│     app/UpdateOperations  app/CompileManager                 │
├─────────────────────────────────────────────────────────────┤
│  L4 框架层                                                    │
│     app/Window  app/View  app/Camera  app/CommandGraph       │
│     app/RenderGraph  app/RecordTraversal  app/CompileTraversal│
├─────────────────────────────────────────────────────────────┤
│  L3 场景图层                                                  │
│     nodes/*  (Group/Transform/StateGroup/Geometry/LOD...)   │
├─────────────────────────────────────────────────────────────┤
│  L2 资源与命令层                                              │
│     state/*(管线状态、描述符、缓冲/图像描述)                 │
│     commands/*(Draw/Dispatch/Copy/Barrier...)               │
│     vk/*(Instance/Device/Context/ResourceRequirements)      │
├─────────────────────────────────────────────────────────────┤
│  L1 对象与数据层                                              │
│     core/Object ref_ptr Inherit Visitor Data Array Allocator  │
├─────────────────────────────────────────────────────────────┤
│  L0 数学层                                                    │
│     maths/vec* mat* quat box sphere plane                     │
└─────────────────────────────────────────────────────────────┘

横切关注点(可被任意层使用):
  io/(Options、ReaderWriter、Input/Output、Logger)
  utils/(Instrumentation、ShaderSet、Builder)
  threading/(Barrier、Latch、FrameBlock、DeleteQueue)
  ui/(事件、FrameStamp)

按这个模型,vk/Context.h 的"越界"就有了合理解释:Context 不属于 L2,它属于 L4。它虽然放在 vk/ 目录(因为它的命名空间是 vsg::,且主要与 Vulkan 资源打交道),但它做的事情是"把一个子图编译成 GPU 资源",这本质上和 CompileTraversal 是同一层的工作。

// include/vsg/vk/Context.h:66
class VSG_DECLSPEC Context : public Inherit<Object, Context>
{
public:
    ref_ptr<Device> device;                     // :79
    ResourceRequirements resourceRequirements;  // :80
    ref_ptr<DescriptorPools> descriptorPools;   // :113
    ref_ptr<CommandPool> commandPool;           // :123
    std::vector<ref_ptr<Command>> commands;     // :130
};

Context 需要 TransferTask(上传队列)、ShaderCompiler(运行时编译)、Instrumentation(计时),所以它必然依赖 app/ 与 utils/。头文件自己写的注释是"manages details about Device, View or other state during compile traversal"(include/vsg/vk/Context.h:64)——它把自己定义成编译遍历的上下文,而不是 Vulkan 句柄的包装。把它放进 vk/ 只是"文件归类的方便",不是"依赖层次的声明"。

这是阅读大型 C++ 库的通用教训:目录结构表达的是"作者希望你怎么找代码",不是"编译器看到的依赖图"。真正的分层要从 #include 和调用关系里反推。

1.3.2 为什么允许 L2 反向依赖 L4

如果强行把 Context 拆出去(比如放到 app/Context.h),会发生什么?

  • vk/ 目录会变成纯粹的"Vulkan 句柄 RAII 包装",这在概念上更干净。
  • 但 Window::getOrCreateDevice()、Device::create(...) 这些函数需要返回 Context 相关的类型,或者接受 ResourceRequirements,于是 vk/ 依然要依赖 state/。
  • 更麻烦的是,CompileTraversal 与 Context 是一一对应的:一个 Context 对应一个设备 + 一个传输队列 + 一套内存池。把它们分到两个目录,会让"编译一个子图"这件事的代码阅读路径变长。

VSG 选择了"概念纯度让位于操作局部性":你打开 Context.h 就能看到编译一个子图需要的全部东西。这是一个务实的取舍,代价是你不能用目录结构来自动检查分层违规。

1.3.3 依赖倒置的缺失是有意的

很多现代库会用接口(纯虚基类)来做依赖倒置,让 vk/ 依赖抽象的 ITransferTask 而不是具体的 TransferTask。VSG 没有这样做。

原因很直接:虚函数调用不是免费的,而这条路径在热循环里。Context::compile 会对每个 BufferInfo、每个 ImageInfo 调用一次传输逻辑;这两批待办在 Context 里是两条具体类型的列表——BufferInfoList bufferInfosToCopy(include/vsg/vk/Context.h:132)与 ImageInfoList imageInfosToCopy(include/vsg/vk/Context.h:133),不是两个抽象接口。如果每次都是一次间接跳转,CPU 的分支预测器会付出代价。VSG 宁愿接受"头文件耦合",也不愿在热路径上引入抽象层。

这与 1.1.3 的 vk_buffer 特化是同一种思维:在能被测量的地方,选择确定性的开销。

1.4 奠基性决策之一:Object 与侵入式引用计数

include/vsg/core/Object.h 是整个库的根。它的全部成员只有两个:

class VSG_DECLSPEC Object
{
public:
    Object();
    // ...
    inline void ref() const noexcept { _referenceCount.fetch_add(1, std::memory_order_relaxed); }
    inline void unref() const noexcept
    {
        if (_referenceCount.fetch_sub(1, std::memory_order_seq_cst) <= 1) _attemptDelete();
    }
    inline void unref_nodelete() const noexcept { _referenceCount.fetch_sub(1, std::memory_order_seq_cst); }
    inline unsigned int referenceCount() const noexcept { return _referenceCount.load(); }

protected:
    virtual ~Object();
    virtual void _attemptDelete() const;
    void setAuxiliary(Auxiliary* auxiliary);

private:
    mutable std::atomic_uint _referenceCount;
    Auxiliary* _auxiliary;
};

加上虚表指针,在 LP64(Linux/macOS 64 位)上 sizeof(Object) 是 24 字节:vptr(8) + atomic_uint(4) + padding(4) + Auxiliary*(8)。两个数据成员紧挨着声明,指针成员是 Auxiliary* _auxiliary(include/vsg/core/Object.h:192),它前面就是那个 mutable 的 atomic_uint 计数;4 字节填充正是 atomic_uint 到指针的对齐要求。

1.4.1 为什么不用 std::shared_ptr

这是面试级的经典问题,但 VSG 的答案不是"性能更好"这种空话,而是三个可以量化的点:

第一,尺寸。 std::shared_ptr<T> 是 16 字节(两个指针:对象指针 + 控制块指针);vsg::ref_ptr<T> 是 8 字节——它只有一个 T* _ptr 成员(include/vsg/core/ref_ptr.h:199)。在 libstdc++ 的实现里,ref_ptr 的注释写得很明白:

// include/vsg/core/ref_ptr.h:18
/// smart pointer that works with objects that have intrusive reference counting, such as all vsg::Object
/// broadly similar in role to std::shared_ptr<> but half size and faster thanks to lower memory footprint and better cache coherency

一半的尺寸意味着什么?场景图里到处是 std::vector<ref_ptr<Node>>(Group::children)。100 万个节点的父子关系,用 shared_ptr 需要 16MB 的指针数组,用 ref_ptr 需要 8MB。更重要的是缓存行利用率:一个 64 字节的缓存行能装 8 个 ref_ptr,只能装 4 个 shared_ptr。遍历子节点时,前者一次 miss 能取到 8 个指针,后者只能取到 4 个。

第二,控制块的额外分配。 std::make_shared<T> 会把控制块和对象放在一起分配(一次 malloc),但 std::shared_ptr<T>(new T) 是两次分配。VSG 的对象全部通过 create() 静态函数构造:

template<typename... Args>
static ref_ptr<Subclass> create(Args&&... args)
{
    return ref_ptr<Subclass>(new Subclass(std::forward<Args>(args)...));
}

引用计数直接放在对象内部,零额外分配。这个 create() 是 Inherit 给的,声明在 include/vsg/core/Inherit.h:35,实现只有 include/vsg/core/Inherit.h:37 那一行 return ref_ptr<Subclass>(new Subclass(...));Object 自身那个不带参的版本也同样只有一行。对于"每个节点都要 new 一次"的场景图,这省下的是 100 万次 malloc/free 以及随之而来的内存碎片。

第三,别名指针与所有权语义。 shared_ptr 的别名构造函数(aliasing constructor)允许"指向成员但共享控制块",这在场景图里很少需要,却让 shared_ptr 的实现必须携带控制块指针。VSG 不需要这个能力,于是省掉了它。

代价:侵入式引用计数要求对象必须继承 Object,无法把 ref_ptr 用于第三方类型(比如 ref_ptr<MyPOD>);也意味着你不能把栈对象交给 ref_ptr 管理——Object 的析构函数是 protected,正是为了在编译期阻止 delete obj; 和栈分配。

protected:
    virtual ~Object();

这一行 protected 是整库最重要的安全约束之一(include/vsg/core/Object.h:182)。它让"忘记用 ref_ptr"这种错误在编译期就失败,而不是在运行时双重释放。析构函数本身定义在 src/vsg/core/Object.cpp:74,函数体只做一件事:_auxiliary->unref()(src/vsg/core/Object.cpp:80),而不是 delete——因为 Auxiliary 可能被别的对象共享。

1.4.2 内存序:为什么 ref 用 relaxed,unref 用 seq_cst

这是 Object.h 里最值得逐字分析的两行:

inline void ref() const noexcept { _referenceCount.fetch_add(1, std::memory_order_relaxed); }
inline void unref() const noexcept
{
    if (_referenceCount.fetch_sub(1, std::memory_order_seq_cst) <= 1) _attemptDelete();
}

ref() 用 relaxed 的理由:增加引用计数不需要与任何其他内存操作建立顺序。你只是在告诉自己"我又多了一个持有者",这个操作不会让其他线程看到任何新数据。用 relaxed 可以避免在 x86 上产生 lock xadd 之外的额外屏障(实际上 x86 的 lock 前缀已经隐含 full barrier,但在 ARM 上 relaxed 的 ldaxr/stlxr 循环明显更轻)。

unref() 用 seq_cst 的理由:最后一个 unref 会触发 delete this。在 delete 之前,必须保证其他线程对这个对象的所有写入都已经完成并对当前线程可见——否则析构函数可能读到旧值,或者对象在被析构时还有别的线程在写它。

seq_cst 的 fetch_sub 同时具备 acquire 和 release 语义:它既是 release(保证本线程之前的写入对"看到这个减法的线程"可见),也是 acquire(保证本线程能看到"之前 release 过这个计数的线程"的写入)。这正好满足"最后一个离开的人负责关灯,并且能看到所有人留下的东西"这个语义。

更精细的做法是 acq_rel + 在计数归零后加一个 std::atomic_thread_fence(std::memory_order_acquire)(这是 boost::intrusive_ptr 和 std::shared_ptr 的经典实现):

if (_referenceCount.fetch_sub(1, std::memory_order_acq_rel) == 1)
{
    std::atomic_thread_fence(std::memory_order_acquire);
    delete this;
}

VSG 用了更简单的 seq_cst。在 x86 上两者生成的指令几乎一样(lock xadd + 条件跳转),在 ARM 上 seq_cst 会多一条 dmb ish。VSG 显然是认为"每帧几百万次 unref 里,真正走到 0 的是极少数",所以把正确性放在第一位,用最简单、最难写错的写法。

注意 <= 1 而不是 == 1。这看起来是防御性编程(计数已经为 0 还继续减,说明有 bug),但它也掩盖了双重释放:如果计数已经是 0,fetch_sub 返回 0,<= 1 成立,_attemptDelete() 会被再次调用。这是一个已知的、有意的宽松处理——在 debug 构建里 _attemptDelete 会打印日志,release 构建里则可能直接崩溃。它反映了一个取舍:不在热路径上加断言。

同一个头文件里还有第三种减法:unref_nodelete()(include/vsg/core/Object.h:127)只做 fetch_sub(1, seq_cst),不问结果,所以永远不会触发删除;它服务于 ref_ptr::release_nodelete()(include/vsg/core/ref_ptr.h:175)那种"放手但不销毁"的场景。而给人看的 referenceCount() 用的是无内存序参数的 load()(include/vsg/core/Object.h:128),即默认的 seq_cst 读——这条路径只在调试和 Auxiliary 的删除判断里出现,不在每帧的 ref/unref 上。

1.4.3 _attemptDelete:给"延迟删除"留的钩子

unref() 归零后调用的是 _attemptDelete() 而不是 delete this:

// src/vsg/core/Object.cpp:84
void Object::_attemptDelete() const
{
    // if there is an auxiliary attached signal to it we wish to delete, and give it an opportunity to decide whether a delete is appropriate.
    if (_auxiliary == nullptr || _auxiliary->signalConnectedObjectToBeDeleted())
    {
        delete this;
    }
    else
    {
        debug("Object::_delete() ", this, " choosing not to delete");
    }
}

这一层间接调用解决了一个真实问题:GPU 还在用这个对象,但 CPU 侧的引用计数已经归零了。

典型场景:你从场景图里移除了一个 StateGroup,它引用的 Buffer 引用计数归零。但这个 Buffer 对应的 VkBuffer 可能还在上一帧的命令缓冲区里被引用,GPU 还没执行完。如果立刻 delete,VkBuffer 被销毁,GPU 读到野句柄——验证层会报 VUID-vkDestroyBuffer-buffer-00922,驱动可能直接崩溃。

VSG 把"删除"这一步做成了虚函数,钩子名叫 signalConnectedObjectToBeDeleted()(include/vsg/core/Auxiliary.h:96)。但读代码会看到两件和直觉相反的事。

第一,这个钩子在整库没有任何派生实现。grep -rn "signalConnectedObjectToBeDeleted" include/ src/ 只返回三处:Auxiliary.h 的声明、Auxiliary.cpp 的定义、Object.cpp:90 的唯一调用点。

第二,默认实现被调用时计数已经是 0。它的判据是 _connectedObject->referenceCount() > 0 才返回 false(src/vsg/core/Auxiliary.cpp:58),而 _attemptDelete() 恰恰是在 fetch_sub 归零之后才进来的,所以它必然返回 true,也就是必然执行 delete this(src/vsg/core/Object.cpp:94)。

真正的延迟释放走的是另一条路。DeleteQueue 维护一个待删列表,每个条目记的是 frameCount + retainForFrameCount(include/vsg/threading/DeleteQueue.h:50),retainForFrameCount 默认 3(include/vsg/threading/DeleteQueue.h:39);advance() 每帧把 frameCount 推到当前帧(src/vsg/threading/DeleteQueue.cpp:36),列表头部到期才真正释放。它完全不碰 Auxiliary。

所以准确的表述是:_attemptDelete 提供了"删除可被否决"的接口,但 1.1.16 的 GPU 延迟回收没有用这个接口,用的是帧号队列。两条路的分工在第 17 章展开。

1.4.4 clone 与 CopyOp:为"动态对象"准备的写时复制

Object::clone 的默认实现非常克制:

ref_ptr<Object> Object::clone(const CopyOp& copyop) const
{
    if (copyop.duplicate)
    {
        auto itr = copyop.duplicate->duplicates.find(this);
        if (itr != copyop.duplicate->duplicates.end()) return itr->second;
    }
    return ref_ptr<Object>(const_cast<Object*>(this));   // 默认不克隆,返回自身
}

注意最后一行:默认行为是"返回自己",而不是"复制一份"——const_cast 之后直接包进 ref_ptr(src/vsg/core/Object.cpp:109),连 new 都没有。这意味着 clone() 不是"深拷贝",而是"按需拷贝":只有真正重写了 clone 的类(比如 Node、Group、StateGroup)才会产生新对象。声明处的注释也直说了这一点:"The default clone(CopyOp&) implementation simply returns ref_ptr<> to this object"(include/vsg/core/Object.h:103)。

CopyOp 则是一个"克隆上下文":

class CopyOp
{
public:
    mutable ref_ptr<Duplicate> duplicate;

    template<class T> ref_ptr<T> operator()(ref_ptr<T> ptr) const;
    template<class C> C operator()(const C& src) const;
    explicit operator bool() const noexcept { return duplicate.valid(); }
};

Duplicate 内部就是一个映射 DuplicateMap(include/vsg/core/Object.h:216),键是原对象地址、值是副本,记录"原对象 → 副本"的对应关系。这解决了图(而不是树)的克隆问题:如果两个节点共享同一个子节点,克隆后应该仍然共享同一个副本,而不是复制两份。

template<class T>
inline ref_ptr<T> CopyOp::operator()(ref_ptr<T> ptr) const
{
    if (ptr && duplicate)
    {
        if (auto itr = duplicate->find(ptr); itr != duplicate->end())
        {
            if (!itr->second) itr->second = ptr->clone(*this);   // 惰性克隆:第一次访问才复制
            if (itr->second) return itr->second.template cast<T>();
        }
    }
    return ptr;
}

这段代码有三个细节值得学:

  1. 惰性:itr->second 为空时才调用 clone(include/vsg/core/Object.h:249),避免克隆整棵树。第二次访问同一个指针时,映射里已经有值,直接返回。
  2. 自引用安全:ptr->clone(*this) 内部如果又访问到自己,duplicates 里已经有条目(值为空),不会无限递归。Object 的拷贝构造函数会把 this 写回 duplicate:
// src/vsg/core/Object.cpp:31
Object::Object(const Object& rhs, const CopyOp& copyop) :
    Object()
{
    // assign this copy constructed object to copyop.duplicate so that it can be lated referenced.
    if (copyop.duplicate)
    {
        if (auto itr = copyop.duplicate->find(&rhs); itr != copyop.duplicate->end())
        {
            itr->second = this;
        }
    }

关键是 src/vsg/core/Object.cpp:39 那一行:构造还没结束就把 this 塞进映射表,所以递归回来时能拿到"正在造的副本"而不是再进一次 clone。这条注释里 lated 是原作者的拼写,不是摘录错误。

  1. 类型安全:返回前用 cast<T>()(include/vsg/core/ref_ptr.h:193),实现是 ref_ptr<R>(_ptr ? _ptr->template cast<R>() : nullptr),空指针直接落成空指针。

用途在哪?Options::findDynamicObjects + PropagateDynamicObjects 这对组合(第 18 章):当场景图被多个 View 共享,而某个子树需要每帧修改时,VSG 会克隆那条路径,保证"动态部分不共享"。这就是写时复制在场景图上的应用。

1.4.5 read/write 放在基类:一切皆可序列化

Object 里还有两个虚函数,声明相邻:

virtual void read(Input& input);
virtual void write(Output& output) const;

把序列化协议放进根类,意味着任何 vsg::Object 都可以被写入 .vsgb(二进制)或 .vsgt(ASCII),包括你自己定义的子类(只要重写这两个函数)。这是 VSG 的 vsg::read/write 能做到"格式无关"的基础(第 18 章)。

默认实现也不是空的:Object::read 会读一个 userObjects 计数再逐条恢复键值(src/vsg/core/Object.cpp:139),Object::write 在没有 _auxiliary 时也照样写一个 0(src/vsg/core/Object.cpp:168)。这意味着"元数据"随对象一起被序列化,子类重写 read/write 时必须先调父类版本,否则元数据会静静丢掉。

代价是:Object 的虚表多了两个条目,每个对象多了 16 字节的虚表(其实虚表是每类一份,不是每对象)。这个代价可以忽略,收益是整个生态的可序列化性。

1.5 奠基性决策之二:Inherit CRTP 与自定义 RTTI

include/vsg/core/Inherit.h 全文 75 行,但它定义了全库 300 多个类的写法。类本身从 include/vsg/core/Inherit.h:26 开始,两个模板参数分别是父类和"自己的类型":

template<class ParentClass, class Subclass>
class Inherit : public ParentClass
{
public:
    template<typename... Args>
    Inherit(Args&&... args) : ParentClass(std::forward<Args>(args)...) {}

    template<typename... Args>
    static ref_ptr<Subclass> create(Args&&... args)
    {
        return ref_ptr<Subclass>(new Subclass(std::forward<Args>(args)...));
    }

    std::size_t sizeofObject() const noexcept override { return sizeof(Subclass); }
    const char* className() const noexcept override { return type_name<Subclass>(); }
    const std::type_info& type_info() const noexcept override { return typeid(Subclass); }
    bool is_compatible(const std::type_info& type) const noexcept override
    {
        return typeid(Subclass) == type || ParentClass::is_compatible(type);
    }

    int compare(const Object& rhs) const override { /* memcmp 派生部分 */ }

    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)); }
};

一个类只要写 class Node : public Inherit<Object, Node>,就自动获得了:

  • Node::create(...):完美转发的工厂函数,返回 ref_ptr<Node>
  • sizeofObject():返回真实类型的大小(用于自定义分配器计算池大小)
  • className():返回可读的类型名
  • type_info() / is_compatible():类型检查
  • compare():逐字节比较派生部分
  • 三个 accept() 重载:把 this 静态转型后交给访问者

1.5.1 为什么不直接用 dynamic_cast

Object.h 里有一段条件编译,闸门是 include/vsg/core/Object.h:88 的 #if VSG_USE_dynamic_cast:走真的 dynamic_cast(include/vsg/core/Object.h:90),或者走"先问 is_compatible 再 static_cast"(include/vsg/core/Object.h:96)。

#if VSG_USE_dynamic_cast
    template<class T> T* cast() { return dynamic_cast<T*>(this); }
#else
    template<class T> T* cast() { return is_compatible(typeid(T)) ? static_cast<T*>(this) : nullptr; }
#endif

默认走 is_compatible 路径。这不是"重复造轮子",而是三个具体问题:

问题一:dynamic_cast 的代价。 在 Itanium ABI(GCC/Clang)下,dynamic_cast 需要遍历 __si_class_type_info 链,对于深层继承(vsg::Node 在 VSG 里有 4-5 层,用户代码可能到 8 层)是 O(depth) 的内存访问,且无法内联。而 is_compatible 是一个虚函数,每层一次 typeid 比较,编译器无法优化但至少可以走虚表预测。

问题二:二进制体积。 每个多态类都会生成 type_info 对象和 type_info 名字符串。VSG 有 300 多个类,加上模板实例化(Array<T> 对 30 多种元素类型),RTTI 数据能占到几百 KB。在移动端这是真实成本。

问题三:跨 DSO 的 type_info 比较。 在 Linux 上,如果主程序和插件各自静态链接了一份 libvsg,typeid 返回的 std::type_info 地址不同,dynamic_cast 会失败(除非用 -fvisibility + 正确的符号导出,或者比较 name() 字符串)。is_compatible 用的是 typeid(T) == type,同样有这个问题——但它至少可以被替换(VSG_USE_dynamic_cast 就是给这种场景准备的)。

实践提示:如果你把 VSG 静态链接进多个 DSO,并且在这些 DSO 之间传递 ref_ptr<Object>,务必保证只有一个 DSO 拥有 libvsg 的实现(其他 DSO 动态链接它),否则 cast<> 与 dynamic_cast 都可能失效。这是 C++ RTTI 的固有问题,不是 VSG 的 bug。

1.5.2 is_compatible 的递归链

// include/vsg/core/Inherit.h:50
bool is_compatible(const std::type_info& type) const noexcept override { return typeid(Subclass) == type || ParentClass::is_compatible(type); }

这是一个编译期展开的链式检查——注意它整条只有一行,|| 的右半边就是父类的同名虚函数。对于 class Perspective : public Inherit<ProjectionMatrix, Perspective>,调用 perspective->is_compatible(typeid(ProjectionMatrix)) 会展开成:

typeid(Perspective) == type            // false
|| typeid(ProjectionMatrix) == type    // true → 返回

最坏情况是继承深度次比较。VSG 的继承深度通常不超过 5,所以这是常数时间。

注意 static_cast<Subclass*>(this) 的安全性:is_compatible 返回 true 只保证"这个对象的动态类型是 T 或 T 的派生类",而 static_cast 从基类转到派生类需要基类子对象位于偏移 0(单继承成立)。VSG 全部使用单继承,所以这个转换是安全的。如果你在自己的类里引入多继承,这套机制会失效——这是使用 VSG 时必须知道的约束。

1.5.3 compare 的 memcmp 技巧

// include/vsg/core/Inherit.h:52
int compare(const Object& rhs) const override
{
    int result = ParentClass::compare(rhs);
    if (result != 0) return result;

    size_t startOfSubclass = sizeof(ParentClass);
    size_t size = sizeof(Subclass) - startOfSubclass;
    if (size == 0) return 0;

    const char* lhs_ptr = reinterpret_cast<const char*>(this);
    const char* rhs_ptr = reinterpret_cast<const char*>(&rhs);
    return std::memcmp(lhs_ptr + startOfSubclass, rhs_ptr + startOfSubclass, size);
}

这段代码假设:派生类新增的成员在内存中从 sizeof(ParentClass) 开始,连续排布。偏移量在 include/vsg/core/Inherit.h:57 由 sizeof(ParentClass) 算出,size == 0 的空派生类在 include/vsg/core/Inherit.h:61 直接返回 0,真正的比较落在 include/vsg/core/Inherit.h:67 的 std::memcmp。在单继承、非虚继承、无 [[no_unique_address]] 的情况下,这个假设成立(Itanium ABI 与 MSVC ABI 都保证基类子对象在前)。

它被用来做什么?状态去重。GraphicsPipeline::compare 声明在 include/vsg/state/GraphicsPipeline.h:75,实现却不是 memcmp:它按 stages(src/vsg/state/GraphicsPipeline.cpp:133)、pipelineStates(src/vsg/state/GraphicsPipeline.cpp:134)、layout、subpass(src/vsg/state/GraphicsPipeline.cpp:136)逐项比。原因是它持有 ref_ptr,一旦交给 memcmp 就变成了比地址。如果两个 RasterizationState 的所有字段都相同,它们的 compare 返回 0,state/ 层就可以复用同一个 VkPipeline。

这个技巧的坑:

  • padding 未初始化会导致误判。如果 struct { float a; char b; } 有 3 字节 padding,而两个对象的 padding 值不同,memcmp 会认为它们不等。VSG 的对策是:所有状态结构体都用 {} 初始化(值初始化会把 padding 也清零,实际上标准只保证成员被零初始化,padding 是实现定义的——但主流编译器会清零),或者显式写 compare 覆盖。
  • 指针成员会被比较地址。如果状态结构体里存了 ref_ptr<Sampler>,memcmp 比较的是指针值,不是对象内容。所以 VSG 的状态类要么用 compare 显式实现,要么保证不存指针。
  • 虚表指针被跳过:sizeof(ParentClass) 已经包含了 vptr,所以 memcmp 从派生类新增部分开始,不会比较 vptr。这是正确的——同一类型的对象 vptr 相同,比较它没有意义。

阅读源码时的技巧:看到某个类重写了 compare,说明它不能用 memcmp(因为有指针或需要语义比较);没重写的,说明它的成员都是 POD 且 padding 可控。这条规律能帮你快速判断一个状态类的"值语义"强度。

1.5.4 type_name:从 typeid().name() 到可读名

template<typename T>
constexpr const char* type_name() noexcept { return typeid(T).name(); }

#define VSG_type_name(T) \
    template<> constexpr const char* type_name<T>() noexcept { return #T; } \
    template<> constexpr const char* type_name<const T>() noexcept { return "const "#T; }

默认实现是 include/vsg/core/type_name.h:24 那一行 return typeid(T).name(),在 GCC/Clang 上是 mangled name(N3vsg4NodeE),在 MSVC 上是 class vsg::Node。两者都不可移植、不可读。

反转这个默认行为的宏以 #T 把类型名拼成字符串,同时给 const T 生成一个带前缀的版本;基类的 className() 就是靠它返回可读名字(include/vsg/core/Object.h:82)。于是每个类文件末尾都有一行:

VSG_type_name(vsg::Node);

它把 type_name<vsg::Node>() 特化为字符串 "vsg::Node"。这个字符串被 className() 使用,也被序列化使用(Output::writeObject 写入类型名,Input::readObject 按名字查找工厂)。

这解释了 VSG 的一个编码规范:每个新类必须在 .cpp 里写 VSG_type_name,否则 className() 返回 mangled name,序列化会写出不可读的类型名,跨编译器不兼容。这是新手最容易漏的一步,而且编译器不会报错——只会在运行时表现为"文件能写不能读"。

1.6 奠基性决策之三:Auxiliary——把"可选"赶出对象

Object 的第二个成员是 Auxiliary* _auxiliary,默认 nullptr。这个指针背后是一整套"可选元数据"机制。

// include/vsg/core/Auxiliary.h:42
using ObjectMap = std::map<std::string, vsg::ref_ptr<Object>>;

/// container for all user objects
ObjectMap userObjects;

void setObject(const std::string& key, ref_ptr<Object> object)
{
    userObjects[key] = object;
}

这个 setObject 是本仓库里最容易被误读的十行之一:它没有加锁。_mutex 确实存在(include/vsg/core/Auxiliary.h:105),但只被 signalConnectedObjectToBeDeleted()(src/vsg/core/Auxiliary.cpp:56)和 resetConnectedObject()(src/vsg/core/Auxiliary.cpp:73)用 scoped_lock 拿过,保护的是 _connectedObject 这个反向指针,不是 userObjects。头文件把锁暴露成 std::mutex& getMutex()(include/vsg/core/Auxiliary.h:28),等于把"要加锁"的责任交给了调用者。

1.6.1 为什么不在 Object 里直接放一个 std::map

算一笔账。libstdc++ 的 std::map 对象本身是 48 字节(比较器、三个指针、节点计数)。如果每个 Object 都内建一个 std::map,sizeof(Object) 就从 24 涨到 72 字节——三倍;100 万个节点意味着 72MB 常驻内存,其中 48MB 是空 map 的壳,而且每个对象的构造/析构都要过一次 map 的构造/析构。而实际上绝大多数对象根本不需要元数据:Group 不需要,Transform 不需要,只有被 DatabasePager 标记的 PagedLOD、被序列化器附加了额外信息的对象、用户自己挂载的自定义数据才需要。

于是 VSG 用了惰性分配 + 一级间接:

Auxiliary* Object::getOrCreateAuxiliary()
{
    if (!_auxiliary)
    {
        _auxiliary = new Auxiliary(this);
        _auxiliary->ref();          // Auxiliary 自己也是引用计数的
    }
    return _auxiliary;
}

代价是访问元数据多一次指针解引用 + 一次判空;收益是不需要元数据的对象只付出 8 字节。这就是 cold data separation:把很少访问的元数据从每帧遍历的热对象里分离出去,让热对象保持紧凑。

1.6.2 setValue/getValue:类型安全的元数据

// include/vsg/core/Value.h:172
void Object::setValue(const std::string& key, const T& value)
{
    using ValueT = Value<T>;
    setObject(key, ValueT::create(value));
}

// include/vsg/core/Value.h:179
bool Object::getValue(const std::string& key, T& value) const
{
    using ValueT = Value<T>;
    const Object* object = getObject(key);
    if (object && (typeid(*object) == typeid(ValueT)))
    {
        const ValueT* vo = static_cast<const ValueT*>(getObject(key));
        value = *vo;
        return true;
    }
    else
    {
        return false;
    }
}

两个细节只有对着代码才能发现。第一,判定用的是 typeid(*object) == typeid(ValueT) 的精确相等,不是 is_compatible,所以 Value<Base> 不能把 Value<Derived> 读出来——多一层派生就查不到。第二,getObject(key) 被调了两次(include/vsg/core/Value.h:182 与 include/vsg/core/Value.h:185),第二次是为了拿到具体类型指针,代价是两次 std::map 查找。

vsg::Value<T> 是 Data 的子类,包装一个标量。于是:

node->setValue("lodScale", 2.5);
double scale = 1.0;
if (node->getValue("lodScale", scale)) { /* ... */ }

这套机制的好处是不需要为每种类型写一个成员变量,也不需要在 Object 里放 void* + 类型标签。代价是:字符串键的比较(每次访问一次 std::map 查找,O(log n))、Value<T> 的堆分配、以及没有编译期检查(键名拼错不会报错,只会静默返回 false)。

VSG 在内部尽量少用这套机制,只在"跨模块传递信息"时使用(比如 Options 把着色器集合名传给加载器)。如果你在自己的代码里大量使用 setValue,说明你的类型设计有问题——应该定义一个子类。

1.6.3 三个同步原语,各自锁什么

Auxiliary 里有三样与并发相关的东西,分工和名字给人的印象不一致:

原语实际保护什么谁在用它
std::atomic_uint _referenceCount(include/vsg/core/Auxiliary.h:103)Auxiliary 自身的生命周期Auxiliary::ref() 与 Auxiliary::unref()
std::mutex _mutex(include/vsg/core/Auxiliary.h:105)_connectedObject 这个反向指针signalConnectedObjectToBeDeleted() 与 resetConnectedObject()
Object* _connectedObject(include/vsg/core/Auxiliary.h:106)不保护任何东西,它是被保护的数据删除判定时读它

换句话说:userObjects 这张 map 没有任何锁保护。Auxiliary::setObject 直接下标赋值,getObject 直接 find(include/vsg/core/Auxiliary.h:52),并发写就是数据竞争。锁只在"接没接对象"这个布尔判断上生效。

注意 getObject 返回的是裸指针,而 getRefObject 返回 ref_ptr。这是一个刻意的 API 分层:

Object* getObject(const std::string& key);            // 快,但调用者必须保证对象存活
ref_ptr<Object> getRefObject(const std::string& key); // 安全,但多一次原子加/减

在热路径上(比如每帧查询某个标记),用 getObject;在跨线程传递时,用 getRefObject。这个选择权交给调用者,而不是库替你做决定——因为库不知道你的使用场景。

1.6.4 删除否决钩子:接口在,实现不在

回到 1.4.3 提到的钩子。Auxiliary 提供:

// include/vsg/core/Auxiliary.h:96
bool signalConnectedObjectToBeDeleted();

它在 protected: 区,只有 Object 是 friend(include/vsg/core/Auxiliary.h:100),所以外部代码连调用都做不到。默认实现拿锁、看重连对象的计数、把 _connectedObject 置空、返回真假(src/vsg/core/Auxiliary.cpp:54)。

问题是:库内没有任何类重写它。1.4.3 已经说过它必然返回 true,这里补上另一半——本来该重写它的 DeleteQueue 并没有继承 Auxiliary,它自己维护 std::list<ObjectToDelete>,靠帧号到期释放(include/vsg/threading/DeleteQueue.h:50)。所以这条"钩子"在 1.1.16 里是接口完整、通路空缺。

这不影响正确性,因为延迟删除由帧号队列兜住了;但它影响你读代码时的预期。看到一个虚函数就假设"一定有人重写",在这里会落空。

三层解耦的设计意图是清楚的:

  • Object 不知道 GPU 的存在,只知道"删除前问一下 Auxiliary"。
  • Auxiliary 不知道 DeleteQueue 的存在,只知道"有人问我能不能删"。
  • 真正做延迟删除的组件不需要改 Object 的引用计数逻辑。

三层各自独立演化,通过一个 bool 返回值连接。这种设计在大型 C++ 库里非常典型:用最小的接口连接两个本来不该互相知道的模块。代价是接口可以长期空转而没人发现——因为空转时行为仍然"正确"。

1.6.5 代价与陷阱

  1. Auxiliary 的引用计数与 Object 的引用计数是独立的。Object::~Object() 里调的是 _auxiliary->unref()(src/vsg/core/Object.cpp:80),不是 delete。如果某个 Auxiliary 被多个 Object 共享(克隆时可能发生),它的生命周期会超过单个 Object。
  2. getOrCreateAuxiliary 不是线程安全的。它没有任何锁(src/vsg/core/Object.cpp:228),两个线程同时进入 if (!_auxiliary) 会各造一个,后者覆盖前者、前者泄漏。VSG 的约定是:元数据的创建只在单线程阶段进行(加载、构建场景图时)。读取侧也不是线程安全的——锁保护的是 _connectedObject,不是那张 map。
  3. userObjects 是 public 的(include/vsg/core/Auxiliary.h:45,类型就是那个 ObjectMap)。这意味着你可以绕过一切约定直接操作 map——Object::operator= 就是这么干的(src/vsg/core/Object.cpp:67),但那是库内代码的特权。不要在自己的代码里直接访问它。

1.7 中途小结:四个决策如何塑造后面的 27 章

把这一章的内容压缩成四句话:

  1. Object + ref_ptr 决定了"一切皆对象、一切皆引用计数",这让场景图可以自由共享子树,代价是所有权的推理必须靠约定(谁在什么时候持有)。
  2. Inherit CRTP 决定了"类型信息在编译期已知",这让 cast<> 比 dynamic_cast 快,也让新增类必须遵守一套模板化的仪式(create、VSG_type_name、accept)。
  3. Auxiliary 决定了"可选能力外挂",这让核心对象保持紧凑,也让 VSG 可以在不修改 Object 的前提下扩展功能(延迟删除的备选接口、动态标记、序列化附加信息)。
  4. Visitor 决定了"操作与数据分离"(下一章展开),这是场景图能在不修改节点类的情况下增加新遍历行为(剔除、记录、编译、求交、序列化)的根本原因。

后面的章节会反复回到这四个决策:第 12 章的 RecordTraversal 用 apply 重载做视锥剔除,第 13 章的 CompileTraversal 用同一套 accept 创建 GPU 资源,第 17 章的 DeleteQueue 用帧号队列推迟释放——它们都建立在这一章的 24 字节对象和 8 字节指针之上。

1.8 一次最小的完整运行:从 main 到 vkQueuePresentKHR

前面讲的都是静态结构。现在把它们串起来:一个能真正打开窗口、加载模型、响应鼠标的最小 VSG 程序长什么样,以及这 40 行代码背后发生了什么。

#include <vsg/all.h>
#include <iostream>

int main(int argc, char** argv)
{
    if (argc < 2) { std::cout << "usage: minimal model.vsgb" << std::endl; return 1; }

    // 1. IO 配置
    auto options = vsg::Options::create();
    options->paths = vsg::getEnvPaths("VSG_FILE_PATH");
    options->sharedObjects = vsg::SharedObjects::create();

    // 2. 窗口与设备
    auto windowTraits = vsg::WindowTraits::create();
    windowTraits->windowTitle = "Minimal VSG";
    windowTraits->width = 1280;
    windowTraits->height = 1024;

    auto window = vsg::Window::create(windowTraits);
    if (!window) { std::cout << "could not create window" << std::endl; return 1; }

    // 3. 场景图
    auto scenegraph = vsg::read_cast<vsg::Node>(argv[1], options);
    if (!scenegraph) { std::cout << "could not read " << argv[1] << std::endl; return 1; }

    // 4. 相机
    auto camera = vsg::Camera::create(
        vsg::Perspective::create(60.0,
                                 double(windowTraits->width) / double(windowTraits->height),
                                 0.1, 10000.0),
        vsg::LookAt::create(vsg::dvec3(0.0, -10.0, 1.0),
                            vsg::dvec3(0.0, 0.0, 0.0),
                            vsg::dvec3(0.0, 0.0, 1.0)),
        vsg::ViewportState::create(window->extent2D()));

    // 5. 命令图
    auto commandGraph = vsg::CommandGraph::create(window);
    commandGraph->addChild(vsg::createRenderGraphForView(window, camera, scenegraph));

    // 6. Viewer 装配
    auto viewer = vsg::Viewer::create();
    viewer->addWindow(window);
    viewer->addEventHandler(vsg::Trackball::create(camera));
    viewer->assignRecordAndSubmitTaskAndPresentation({commandGraph});
    viewer->compile();          // 关键:显式编译

    // 7. 主循环
    while (viewer->advanceToNextFrame())
    {
        viewer->handleEvents();
        viewer->update();
        viewer->recordAndSubmit();
        viewer->present();
    }
    return 0;
}

这段代码里,每一个 create 都对应 Inherit 提供的静态工厂(第 1.5 节),每一个对象都是 ref_ptr 管理的(第 1.4 节)。但真正值得讲的是七步之间的依赖关系,以及为什么顺序不能乱。

1.8.1 第一步:Options 是"加载上下文",不是"配置"

auto options = vsg::Options::create();
options->paths = vsg::getEnvPaths("VSG_FILE_PATH");
options->sharedObjects = vsg::SharedObjects::create();

Options 在 include/vsg/io/Options.h 里,但它不只是"路径列表"。它包含:

字段作用为什么放在 Options 里
paths(include/vsg/io/Options.h:69)文件搜索路径加载器需要它来解析相对路径
readerWriters(include/vsg/io/Options.h:57)格式处理器列表read() 遍历它,找到能处理该扩展名的 ReaderWriter
sharedObjects(include/vsg/io/Options.h:56)共享对象容器(着色器集合、纹理池等)多个加载器/多个场景图之间共享 GPU 资源
operationThreads(include/vsg/io/Options.h:58)后台加载线程池异步加载
fileCache(include/vsg/io/Options.h:74)单个文件的缓存路径同一文件只加载一次
shaderSets(include/vsg/io/Options.h:91)按名字替换着色器集合让 pbr/phong/flat 可替换
sceneCoordinateConvention(include/vsg/io/Options.h:80)Z-up 还是 Y-up模型坐标系转换
inheritedState(include/vsg/io/Options.h:95)父级状态命令让加载器避免重复设置状态
instrumentation(include/vsg/io/Options.h:98)记录遍历的插桩加载期也能 profile

这里的设计精髓是:Options 是"加载期间可变的上下文",而不是"不可变的配置"。加载器可以在加载过程中给它加东西(比如把新发现的纹理路径加进 paths),也可以从中读取共享资源。

vsg::SharedObjects 特别值得说。它是一个"按类型分组的对象池",类声明在 include/vsg/utils/SharedObjects.h:31,取用靠 shared_from() 这组模板(include/vsg/utils/SharedObjects.h:36):

auto sharedObjects = vsg::SharedObjects::create();
auto shaderSet = sharedObjects->shared_from(vsg::createPhongShaderSet(options));

同一个模型里如果有 100 个材质都用同一套 PBR 着色器,sharedObjects 保证它们共享同一个 ShaderSet 对象,从而共享同一个 VkPipelineLayout。这是"资源去重"的第一道防线(第二道是 state/ 层的 compare 去重,第 9 章)。

1.8.2 第二步:Window::create 背后是一次完整的 Vulkan 初始化

auto window = vsg::Window::create(windowTraits);

入口是 include/vsg/app/Window.h 里的静态函数 create(ref_ptr<WindowTraits>),返回一个 ref_ptr<Window>。看起来只是一行,实际上它触发了:

vsg::Window::create(traits)
  └─ 平台相关:创建原生窗口(Win32 HWND / XCB window / CAMetalLayer)
  └─ vsg::Instance::create(...)         // VkInstance + 扩展/层
  └─ vsg::Surface::create(...)          // VkSurfaceKHR
  └─ vsg::PhysicalDevice::create(...)   // 选择 GPU
  └─ vsg::Device::create(...)           // VkDevice + 队列
  └─ vsg::Swapchain::create(...)        // VkSwapchainKHR + 图像视图

这条链的每一步都可能失败,而且失败原因往往很隐蔽(没有可用的队列族、缺少 VK_KHR_swapchain、表面格式不支持)。Window::create 返回 nullptr 而不是抛异常,是因为在移动端和嵌入式上,"没有窗口"是一种正常状态(比如后台恢复),不应该导致进程终止。

WindowTraits 里默认 width = 1280(include/vsg/app/WindowTraits.h:49)、height = 1024(include/vsg/app/WindowTraits.h:50),注意不是常见的 1920×1080。这个默认值来自 OSG 时代的习惯,也暗示了 VSG 的目标用户是"工作站上的工程可视化"而不是"游戏"。窗口标题的默认值同样是中性的 windowTitle = "vsg window"(include/vsg/app/WindowTraits.h:58)。

值得单独提的是 instanceExtensionNames(include/vsg/app/WindowTraits.h:86)与 requestedLayers(include/vsg/app/WindowTraits.h:87)。VSG 不会替你打开所有扩展——它只打开必需的最小集合,其余靠你显式请求。选物理设备时的偏好也写死在 traits 里:独显优先于集显、集显优先于虚拟 GPU(src/vsg/app/WindowTraits.cpp:145)。这与你直接写 Vulkan 时的体验一致,也是 VSG 的哲学:封装不隐藏,抽象不剥夺控制权。

1.8.3 第三步:read_cast<Node> 与类型安全的加载

auto scenegraph = vsg::read_cast<vsg::Node>(argv[1], options);

read_cast<T> 定义在 include/vsg/io/read.h:37,实现比预想的短:

// include/vsg/io/read.h:37
ref_ptr<T> read_cast(const Path& filename, ref_ptr<const Options> options = {})
{
    auto object = read(filename, options);
    return vsg::ref_ptr<T>(dynamic_cast<T*>(object.get()));
}

注意最后一行用的是 dynamic_cast,不是第 1.5 节讲的 cast<T>()。这是一个有意的例外:read() 返回的是磁盘上任意类型,T 由调用方指定,这里必须走标准 RTTI 才能安全;而 cast<T>() 依赖 is_compatible 的虚函数链,只适合"已经知道对方在 VSG 类型体系里"的场合。

它返回 nullptr 有两种可能:文件读不了,或者读出来的不是 Node(比如你传了一个纹理文件)。这两种情况在调用方看来是一样的,因为 dynamic_cast 失败同样返回空指针:错误信息被吞掉了。调试时应该先用 vsg::read() 拿到 Object,打印 className(),再决定转型。

1.8.4 第四步:相机的三个组成部分

auto camera = vsg::Camera::create(projectionMatrix, viewMatrix, viewportState);

Camera 只持有三个东西,三个都是 ref_ptr(include/vsg/app/Camera.h:34、include/vsg/app/Camera.h:35、include/vsg/app/Camera.h:36):

ref_ptr<ProjectionMatrix> projectionMatrix;
ref_ptr<ViewMatrix> viewMatrix;
ref_ptr<ViewportState> viewportState;

构造函数把这三个按顺序接住(include/vsg/app/Camera.h:31),并且 viewportState 允许缺省——缺省时 getViewport() 返回一个零值的 VkViewport(include/vsg/app/Camera.h:38),这就是"相机可以先建、窗口后到"的机制。

注意这三个都是对象而不是值。这意味着:

  • Perspective 可以在运行时被替换(比如切换广角/长焦),只需要改 camera->projectionMatrix。
  • LookAt 可以被 Trackball 修改(Trackball 持有 ref_ptr<Camera>,直接改 camera->viewMatrix)。
  • ViewportState 与窗口尺寸解耦,支持"渲染到纹理"时用不同的视口;getRenderArea() 直接取 viewportState->getScissor()(include/vsg/app/Camera.h:39)。

这是 VSG 与"把矩阵塞进 uniform buffer"的写法最大的区别:相机是场景图里的一等公民,它可以被遍历、被记录、被动画驱动(CameraSampler,第 21 章)。

Perspective 的构造函数签名是 Perspective(double fov, double ar, double nd, double fd)——注意全是 double。VSG 内部的矩阵运算默认用 double(dmat4),只在传给 GPU 时转成 float。这是为了在大尺度场景(地理坐标、天文坐标)里避免精度灾难(第 5 章详述)。

1.8.5 第五步:CommandGraph 取代了"渲染器"

auto commandGraph = vsg::CommandGraph::create(window);
commandGraph->addChild(vsg::createRenderGraphForView(window, camera, scenegraph));

在 OSG 里,你把场景图和相机交给 osgViewer::Viewer,剩下的它帮你做。在 VSG 里,你必须显式搭一棵"命令图"。命令图的类声明是 class CommandGraph : public Inherit<Group, CommandGraph>(include/vsg/app/CommandGraph.h:27),它就是一个 Group:

CommandGraph(继承 Group)
  └─ RenderGraph(继承 Group)
       ├─ ClearAttachments(清屏命令)
       ├─ View(继承 Group)
       │    ├─ 相机相关状态
       │    └─ 你的场景图
       └─ ...

createRenderGraphForView 是一个便利函数,帮你把"清屏 → 设置视口 → 设置相机 → 画场景"这套固定流程装好。它的声明在 include/vsg/app/RenderGraph.h:88:

ref_ptr<RenderGraph> createRenderGraphForView(ref_ptr<Window> window,
                                              ref_ptr<Camera> camera,
                                              ref_ptr<Node> scenegraph,
                                              VkSubpassContents contents = VK_SUBPASS_CONTENTS_INLINE,
                                              bool assignHeadlight = true);

最后两个参数的默认值不是随手写的:

  • contents:默认 VK_SUBPASS_CONTENTS_INLINE,与 RenderGraph::contents 成员自己的默认值一致(include/vsg/app/RenderGraph.h:69)。这个值表示命令直接录在主命令缓冲区;换成 VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS 则录到二级命令缓冲区(支持多线程并行录制,第 15 章)。
  • assignHeadlight:默认 true,自动加一盏跟随相机的头灯。大多数模型没有光照就是一片黑,这也解释了为什么很多人第一次跑 VSG 觉得"光照不对"——你看到的是头灯,不是场景里的灯。

为什么要显式搭命令图? 因为 Vulkan 的渲染过程本身就是显式的:VkRenderPass → VkFramebuffer → vkCmdBeginRenderPass → 绘制 → vkCmdEndRenderPass。VSG 没有把这套东西藏进"渲染器",而是让它成为场景图的一部分。好处是:多视图、多窗口、后处理、计算管线,全部可以用"往命令图里加节点"的方式表达,不需要改引擎代码。

1.8.6 第六步:viewer->compile() 为什么必须显式调用

viewer->assignRecordAndSubmitTaskAndPresentation({commandGraph});
viewer->compile();

compile() 声明在 include/vsg/app/Viewer.h:107:

virtual CompileResult compile(ref_ptr<ResourceHints> hints = {});

它做的是把场景图里的"描述"变成真实的 Vulkan 对象:创建 VkBuffer、分配设备内存、上传数据、创建 VkImageView、创建 VkPipeline、分配 VkDescriptorSet。真正干活的是 Viewer::compileManager(include/vsg/app/Viewer.h:94),它为每个 Device 准备一个 Context,然后交给 CompileManager::compile(include/vsg/app/CompileManager.h:97)。

为什么不让 Viewer 自动在第一次 advanceToNextFrame() 时做?三个理由:

  1. 耗时不可控。编译一个复杂场景可能需要几秒到几分钟(创建上千个管线)。如果藏在主循环里,你会看到一个"卡住"的窗口。
  2. 需要可重入。加载新模型后需要再编译一次;已编译的资源会被跳过(CompileResult::result 为 VK_INCOMPLETE 时表示没有新东西)。
  3. 需要可放弃。CompileManager::compile 取不到空闲的 CompileTraversal 就直接返回,不阻塞(src/vsg/app/CompileManager.cpp:276)。

CompileResult 的字段很少(include/vsg/app/CompileManager.h:27):result(VkResult,初值 VK_INCOMPLETE,include/vsg/app/CompileManager.h:29)、message、maxSlots、containsPagedLOD、views、dynamicData,外加一个 operator bool() 判断是否等于 VK_SUCCESS(include/vsg/app/CompileManager.h:36)。没有 compiled 或 maxTime 这样的字段——编译耗时得自己用 Instrumentation 测。生产代码应该检查它:

auto result = viewer->compile();
if (!result) std::cout << "compile failed: " << result.message << std::endl;

1.8.7 第七步:主循环的四段式

while (viewer->advanceToNextFrame())
{
    viewer->handleEvents();
    viewer->update();
    viewer->recordAndSubmit();
    viewer->present();
}

这四步对应四个阶段,缺一不可,顺序也不能换:

阶段做什么如果跳过会怎样
advanceToNextFrame轮询事件、acquireNextFrame、造新的 FrameStamp,再让每个 task advance()帧号不前进,动画/帧同步失效
handleEvents把平台事件转成 vsg::UIEvent 并分发给 EventHandler鼠标键盘无响应
update合并 DatabasePager 的结果、跑 UpdateOperations、跑 AnimationManager动画不动,PagedLOD 不加载
recordAndSubmit遍历命令图,录制命令缓冲区,提交到队列黑屏
present逐个 Presentation::present()画面不显示(但 GPU 可能已经在渲染)

advanceToNextFrame() 返回 bool,false 表示窗口关闭。源码里这个判断在很前面:if (!active()) return false;(src/vsg/app/Viewer.cpp:162),所以"关闭窗口"是循环的自然出口,而不是靠异常或全局标志。

update() 不是只跑回调。它先让每个 task 的 databasePager 合并已加载的子图(src/vsg/app/Viewer.cpp:804),再跑 updateOperations->run()(src/vsg/app/Viewer.cpp:814),最后跑 animationManager->run(_frameStamp)(src/vsg/app/Viewer.cpp:817)。三者顺序固定:先让新数据进图,再改节点,最后推进动画。

注意 recordAndSubmit 是多线程的。默认情况下 _threading = false(include/vsg/app/Viewer.h:165),所有工作在调用线程执行;一旦调用 setupThreading()(include/vsg/app/Viewer.h:132),recordAndSubmit() 只做两件事:把本帧的 FrameStamp 塞进 _frameBlock(src/vsg/app/Viewer.cpp:842),然后在 _submissionCompleted 上等所有任务干完(src/vsg/app/Viewer.cpp:843)。真正的录制发生在别处。第 16 章会完整拆解这套线程模型。

1.8.8 五个最常见的启动失败

把新手最常踩的坑列在这里,每个都对应源码里的一个具体位置:

坑一:Window::create 返回 nullptr。 最常见的原因是 Vulkan SDK 没装好,或者 VK_ICD_FILENAMES 指向了不存在的驱动。VSG 不会打印详细错误(错误在 vsg::Instance 创建时就发生了),需要自己开 VSG_DEBUG 或者用 VK_LOADER_DEBUG=all。

坑二:模型一片黑。 assignHeadlight 默认 true,但如果模型的法线朝向错误(很多 OBJ 文件的法线是反的),头灯照上去就是黑的。也可能是 Options::sceneCoordinateConvention 与模型实际坐标系不符(Z-up vs Y-up),导致模型躺倒 + 光照方向错误。

坑三:compile() 之后仍然崩溃在 record。 通常是 ShaderSet 与 GraphicsPipeline 不匹配:比如自定义了 VertexInputState 但着色器的 location 对不上。CompileTraversal 创建管线时会调用 vkCreateGraphicsPipelines,失败会返回 VK_ERROR_...,但 VSG 默认只打印一行日志。开启验证层(windowTraits->debugLayer = true)能看到完整的 VUID 信息。

坑四:窗口能开,但 resize 后画面拉伸。 ViewportState 是用 window->extent2D()(include/vsg/app/Window.h:64)创建的,窗口大小变了它本不会自动更新。RenderGraph 每帧比较 previous_extent 与当前 extent(src/vsg/app/RenderGraph.cpp:114),不一致就调 resized()(src/vsg/app/RenderGraph.cpp:117),默认挂着的 windowResizeHandler(include/vsg/app/RenderGraph.h:75)会重算 viewport 与裁剪框。但你自己手搭的 ViewportState 不在这个机制里——它只覆盖 RenderGraph 持有的那一个。

坑五:程序退出时崩溃。 这是最典型的"销毁顺序"问题。Viewer、Window、Device、Instance 之间有严格的销毁顺序(VkDevice 必须在所有 VkBuffer/VkPipeline 之后销毁)。VSG 的 Viewer::~Viewer() 先 stopThreading() 再 deviceWaitIdle()(src/vsg/app/Viewer.cpp:45),前提是销毁时 _windows 里的设备还活着。正确做法:让 viewer 和 window 在同一个作用域,且先 viewer->close()(include/vsg/app/Viewer.h:59)再让作用域结束;不要在主线程之外还攥着 ref_ptr<Window>。

1.9 与 OpenSceneGraph 的对照:五条必须换掉的心智模型

VSG 的作者就是 OSG 的作者,两者概念高度对应、实现几乎完全不同。带着 OSG 经验读 VSG,最容易在下面五处翻车。

1.9.1 类型对照表

OpenSceneGraphVulkanSceneGraph差异要点
osg::Objectvsg::Object都是引用计数根类;VSG 多了 Auxiliary
osg::ref_ptr<T>vsg::ref_ptr<T>都是侵入式;VSG 的 ref_ptr 更小(8 字节)
osg::Node / osg::Groupvsg::Node / vsg::Group基本同构
osg::MatrixTransformvsg::MatrixTransform同构,但 VSG 用 dmat4
osg::Geode + osg::Geometryvsg::VertexIndexDraw / vsg::GeometryVSG 把"几何 + 绘制"合并了
osg::StateSetvsg::StateGroup + GraphicsPipeline最大的差异:状态不是"键值对集合",而是"管线对象"
osg::Programvsg::ShaderStage + vsg::ShaderSetVSG 显式管理 SPIR-V 与描述符布局
osg::Drawablevsg::Command绘制是命令,不是"可绘制物"
osgViewer::Viewervsg::Viewer + CommandGraph渲染流程从"引擎内部"变成"场景图的一部分"
osg::Cameravsg::Camera + vsg::View相机与视图分离
.osgb / .osgt.vsgb / .vsgt格式不同,不能互读(需 osg2vsg 转换)
更新回调 NodeCallbackvsg::UpdateOperations / Visitor没有"回调挂在节点上"的机制
osg::State(运行时状态机)vsg::State(记录遍历的状态栈)名字相同,职责不同

1.9.2 心智转变一:状态不是"模式",是"对象"

OSG 的 StateSet 是一个"状态模式集合":

// OSG
stateset->setAttributeAndModes(program, osg::StateAttribute::ON);
stateset->setMode(GL_DEPTH_TEST, osg::StateAttribute::ON);

它描述的是"渲染这个子树时,状态机应该处于什么模式"。运行时,osg::State 会做状态排序、冗余消除。

VSG 没有"模式"这个概念。状态被拆成不可变的对象:

// VSG
auto rasterizationState = vsg::RasterizationState::create();
rasterizationState->cullMode = VK_CULL_MODE_BACK_BIT;
rasterizationState->polygonMode = VK_POLYGON_MODE_FILL;

auto pipeline = vsg::GraphicsPipeline::create(pipelineLayout, shaderStages,
                                              {vertexInputState, rasterizationState});
auto stateGroup = vsg::StateGroup::create();
stateGroup->add(pipeline);
stateGroup->addChild(child);

GraphicsPipeline 的构造参数是"布局 + 着色器阶段 + 状态列表 + 子通道号"(include/vsg/state/GraphicsPipeline.h:61),状态本身装在一个 GraphicsPipelineStates 容器里(include/vsg/state/GraphicsPipeline.h:71),不是一个个具名字段。

StateGroup 里的状态是有序的 StateCommand 列表(include/vsg/nodes/StateGroup.h:37),压栈发生在 RecordTraversal::apply(const StateGroup&):state->push(begin, end) → 遍历子节点 → state->pop(begin, end)(src/vsg/app/RecordTraversal.cpp:524)。真正发出 vkCmdBindPipeline 的不是压栈,而是下一个 Command 到来时的 state->record()。

这里有一个容易被说反的细节:VSG 有冗余消除,但粒度是"脏标记"不是"值比较"。State::record() 只在 dirty 为真时才遍历所有槽位发绑定命令(include/vsg/vk/State.h:350),而 push/pop 每次都会把 dirty 置真(include/vsg/vk/State.h:374)。所以两个相邻的 StateGroup 即使管线相同,中间夹着的 pop/push 也会让状态重发一次——真正省掉重复绑定的是"同一层内多个 Command 共享一次 state->record()"。

这意味着:你在 VSG 里不能用"设置一个模式,后面自动生效"的思路。每个 StateGroup 必须完整地描述它需要的管线状态。好处是行为可预测(所见即所得),代价是场景图会变大(每个 StateGroup 携带完整状态)。

VSG 的补偿手段是状态对象复用:GraphicsPipeline 实现了 compare,编译阶段会把相同的管线归并成一个 VkPipeline。所以你写 100 个 StateGroup,只要它们的管线参数相同,最终只有一个 VkPipeline。

1.9.3 心智转变二:绘制是命令,不是"可绘制物"

OSG 的 Drawable 是"可以被绘制的东西",它自己知道怎么画(drawImplementation)。VSG 的 Command 是"一条 Vulkan 命令",它只持有参数:

class VSG_DECLSPEC DrawIndexed : public Inherit<Command, DrawIndexed>
{
public:
    DrawIndexed() {}

    DrawIndexed(uint32_t in_indexCount, uint32_t in_instanceCount, uint32_t in_firstIndex, uint32_t in_vertexOffset, uint32_t in_firstInstance) :
        indexCount(in_indexCount),
        instanceCount(in_instanceCount),
        firstIndex(in_firstIndex),
        vertexOffset(in_vertexOffset),
        firstInstance(in_firstInstance) {}

    int compare(const Object& rhs_object) const override;

    void read(Input& input) override;
    void write(Output& output) const override;

    void record(CommandBuffer& commandBuffer) const override
    {
        vkCmdDrawIndexed(commandBuffer, indexCount, instanceCount, firstIndex, vertexOffset, firstInstance);
    }

    uint32_t indexCount = 0;
    uint32_t instanceCount = 0;
    uint32_t firstIndex = 0;
    uint32_t vertexOffset = 0;
    uint32_t firstInstance = 0;
};

注意它继承的是 Inherit<Command, DrawIndexed>,而 Command 继承 Compilable:

class VSG_DECLSPEC Command : public Inherit<Compilable, Command>
{
public:
    Command() {}
    virtual void record(CommandBuffer& commandBuffer) const = 0;
};

Command 的声明在 include/vsg/commands/Command.h:22,整个类只有一个纯虚函数(include/vsg/commands/Command.h:29)。所以每个命令都有两套接口:来自 Compilable 的 compile(Context&)(创建它需要的 GPU 资源),以及自己的纯虚 record(CommandBuffer&)(录制)。DrawIndexed 的 record 只有一行 vkCmdDrawIndexed(include/vsg/commands/DrawIndexed.h:40),它没有重写 compile,因为它不需要创建任何资源——它的全部状态就是 5 个整数,第一个的默认值是 0(include/vsg/commands/DrawIndexed.h:45),忘了赋值就是"画 0 个索引"。这是"命令对象尽量轻"的直接体现。

这套接口极其统一——commands/ 下的 34 个头文件全部遵循"继承 Command、实现 record、按需实现 compile"的模式。这种一致性让"换一种绘制方式"变成纯替换操作。

于是"绘制一个模型"变成了"往场景图里放一个 VertexIndexDraw 节点":

auto draw = vsg::VertexIndexDraw::create();
draw->assignArrays({vertices, normals, texcoords});
draw->assignIndices(indices);
draw->indexCount = indices->valueCount();
draw->instanceCount = 1;

VertexIndexDraw 的类声明是 class VertexIndexDraw : public Inherit<Command, VertexIndexDraw>(include/vsg/nodes/VertexIndexDraw.h:24)——它就是一条命令,虽然住在 nodes/ 目录里。它把"绑顶点缓冲、绑索引缓冲、画"三步压进一个 record():先 vkCmdBindVertexBuffers(src/vsg/nodes/VertexIndexDraw.cpp:184),再 vkCmdBindIndexBuffer(src/vsg/nodes/VertexIndexDraw.cpp:186),最后 vkCmdDrawIndexed(src/vsg/nodes/VertexIndexDraw.cpp:188)。头文件注释写明这是"higher performance equivalent to use of individual BindVertexBuffers, BindIndexBuffer and DrawIndexed commands"(include/vsg/nodes/VertexIndexDraw.h:22)。

所以"VertexIndexDraw 内部持有三条子命令"是 OSG 时代的记忆,在 1.1.16 里不成立:它只有 5 个 uint32_t、两个缓冲列表和一个 _vulkanData(include/vsg/nodes/VertexIndexDraw.h:58),没有 children。

这个设计的价值:绘制调用可以被自由组合。想做 instancing?把 DrawIndexed 换成 DrawIndexedIndirect。想做 multi-draw?换成 DrawIndirect。想做 mesh shader?换成 DrawMeshTasks。场景图结构不变,只换命令对象。

1.9.4 心智转变三:渲染流程是"图",不是"引擎"

OSG 的 Viewer 内部是固定流程(cull → sort → draw),只能用 Camera 的 setRenderOrder、setPreRenderCallback 微调。

VSG 把这个流程展开成场景图:

CommandGraph
  ├─ RenderGraph(对应一个 VkRenderPass)
  │    ├─ View(对应一个相机)
  │    ├─ View
  │    └─ ...
  └─ RenderGraph(另一个 pass,比如后处理)

CommandGraph::record() 会遍历这棵树:traverse(*recordTraversal)(src/vsg/app/CommandGraph.cpp:134)。遇到 RenderGraph 就 vkCmdBeginRenderPass(src/vsg/app/RenderGraph.cpp:150),遇到 View 就设置相机状态,遇到 Command 就录制。

这带来三个能力:

  1. 多视图共享一个 pass:两个 View 放在同一个 RenderGraph 下,共享深度缓冲,可以做分屏、VR 双眼、画中画。
  2. 多 pass 串联:后处理、阴影贴图、G-Buffer,都是往 CommandGraph 里加 RenderGraph。
  3. 多线程录制:每个 RenderGraph 可以分配给一个 RecordAndSubmitTask,并行录制(第 15 章)。

代价是:你必须理解 VkRenderPass 的附件依赖。createRenderGraphForView 帮你建了一个"颜色 + 深度"的默认 pass,但如果你想做延迟渲染,需要自己创建 RenderPass 和 Framebuffer。

1.9.5 心智转变四:没有"更新回调"

OSG 允许你把 NodeCallback 挂在节点上,每帧调用。VSG 没有这个机制,取而代之的是三条路:

  1. UpdateOperations:Viewer::addUpdateOperation(op, runBehavior),在 update() 阶段执行。适合"每帧改一个变换"这种简单逻辑。
  2. 自定义 Visitor:写一个 class MyUpdater : public vsg::Visitor,重写 apply(MatrixTransform&),然后 scene->accept(updater)。适合"批量更新一类节点"。
  3. 动画系统:vsg::Animation + AnimationGroup + AnimationManager,由 FrameStamp 驱动(第 21 章)。

去掉回调的理由是生命周期耦合(回调持有节点指针,节点删除后悬空)和线程安全(回调在哪个线程执行?)。VSG 把更新逻辑集中到 Viewer 的 update 阶段,用显式遍历代替隐式回调。

1.9.6 心智转变五:编译是显式阶段

这是最容易被低估的一条。OSG 在第一次绘制时"懒编译"(Drawable::compile),你几乎感觉不到。VSG 把编译抽成独立阶段,原因在 1.8.6 讲过:耗时可控、可重入、可并行。

但它带来一个使用上的强约束:任何修改了场景图结构(新增节点、改状态、换着色器)的操作,都必须重新 compile()。忘记这一步的典型症状是:新加的模型不显示(因为 VkBuffer 还没创建),或者显示成上一帧的内容。

Viewer::compile() 的返回值 CompileResult 可以用 operator bool() 判断成败(include/vsg/app/CompileManager.h:36),但它不告诉你"有没有新资源被创建"——result 初值是 VK_INCOMPLETE,成功编译后变成 VK_SUCCESS,没有第三种"跳过"状态。想知道"有没有新东西",只能比较编译前后的 slot 数或自己计数:

auto result = viewer->compile();
if (!result) { std::cerr << result.message << std::endl; }

1.10 一帧的纵切面:从 Viewer 到 vkCmdDrawIndexed

前九节是横切面(模块、类型、决策)。这一节换成纵切面:当 viewer->recordAndSubmit() 被调用时,控制流如何穿过五层抽象,最终落到一个 vkCmd* 调用。

这 17 步每一步都能在源码里找到对应函数;读懂它,就有了阅读后面所有章节的坐标系。

1.10.1 第 1–3 步:从主循环进入录制任务

// src/vsg/app/Viewer.cpp:820
void Viewer::recordAndSubmit()
{
    // reset connected ExecuteCommands
    for (const auto& recordAndSubmitTask : recordAndSubmitTasks)
    {
        for (auto& commandGraph : recordAndSubmitTask->commandGraphs)
        {
            commandGraph->reset();
        }
    }

    if (_threading)
    {
        _frameBlock->set(_frameStamp);
        _submissionCompleted->arrive_and_wait();
    }
    else
    {
        for (auto& recordAndSubmitTask : recordAndSubmitTasks)
        {
            recordAndSubmitTask->submit(_frameStamp);
        }
    }
}

第一件事不是录制,而是把上一帧挂在 ExecuteCommands 上的连接清掉(src/vsg/app/Viewer.cpp:829)。然后是一个二选一:单线程直接调 submit()(src/vsg/app/Viewer.cpp:849),多线程只把帧号推给 _frameBlock(src/vsg/app/Viewer.cpp:842),再在 _submissionCompleted 这个 Barrier 上等所有工作线程(src/vsg/app/Viewer.cpp:843)。

submit() 本身是一条四段流水线:

// src/vsg/app/RecordAndSubmitTask.cpp:85
VkResult RecordAndSubmitTask::submit(ref_ptr<FrameStamp> frameStamp)
{
    if (VkResult result = start(); result != VK_SUCCESS) return result;

    if (transferTask)
    {
        if (auto transfer = transferTask->transferData(TransferTask::TRANSFER_BEFORE_RECORD_TRAVERSAL); transfer.result == VK_SUCCESS)
        ...
    }

    auto recordedCommandBuffers = RecordedCommandBuffers::create();

    if (VkResult result = record(recordedCommandBuffers, frameStamp); result != VK_SUCCESS) return result;

    return finish(recordedCommandBuffers);
}

注意这个类没有 run() 方法。start() 做的是等 fence:只有当 current_fence->hasDependencies() 为真才 wait,超时参数是 std::numeric_limits<uint64_t>::max()(src/vsg/app/RecordAndSubmitTask.cpp:134)——一个无上界的阻塞等待。record() 才是遍历命令图的地方(src/vsg/app/RecordAndSubmitTask.cpp:155),finish() 负责把命令缓冲区提交到队列。

RecordAndSubmitTask 构造时给定 numBuffers = 3(include/vsg/app/RecordAndSubmitTask.h:30),据此预分配 3 个 Fence(src/vsg/app/RecordAndSubmitTask.cpp:32)——这就是"在飞帧数"的物理来源。信号量也是成对的复数成员:waitSemaphores 与 signalSemaphores(include/vsg/app/RecordAndSubmitTask.h:40),而不是各一个。多线程模式下,每个 task 在独立线程里被 FrameBlock::wait_for_change() 唤醒(include/vsg/threading/FrameBlock.h:57),与主线程同步(第 16 章)。

1.10.2 第 4–6 步:CommandGraph::record 的三件准备

// src/vsg/app/CommandGraph.cpp:76
void CommandGraph::record(ref_ptr<RecordedCommandBuffers> recordedCommandBuffers, ref_ptr<FrameStamp> frameStamp, ref_ptr<DatabasePager> databasePager)
{
    ...
    // create the RecordTraversal if it isn't already created
    getOrCreateRecordTraversal();

    recordTraversal->recordedCommandBuffers = recordedCommandBuffers;
    recordTraversal->setFrameStamp(frameStamp);
    recordTraversal->setDatabasePager(databasePager);
    recordTraversal->clearBins();
    recordTraversal->regionsOfInterest.clear();

    ref_ptr<CommandBuffer> commandBuffer;
    for (auto& cb : _commandBuffers)
    {
        if (cb->numDependentSubmissions() == 0)
        {
            commandBuffer = cb;
            break;
        }
    }
    ...
    vkBeginCommandBuffer(vk_commandBuffer, &beginInfo);

    {
        COMMAND_BUFFER_INSTRUMENTATION(instrumentation, *commandBuffer, "CommandGraph record", COLOR_RECORD)
        traverse(*recordTraversal);
    }

    vkEndCommandBuffer(vk_commandBuffer);

三个要点:

  • RecordTraversal 是复用的。getOrCreateRecordTraversal() 只在指针为空时 create(maxSlots),否则调 getState()->reserve(maxSlots) 扩容(src/vsg/app/CommandGraph.cpp:68)。它内部的 State、bins、viewDependentState 都是持久的——这意味着跨帧的内存复用,避免每帧重新分配 std::vector<ref_ptr<Bin>>(include/vsg/app/RecordTraversal.h:184)。
  • 帧号与 pager 是注入的,不是全局量。setFrameStamp 之后,所有需要"当前帧号/时间"的节点(Animation、PagedLOD)都从遍历器取。clearBins() 在注入之后立刻调用(src/vsg/app/CommandGraph.cpp:92),清的是上一帧塞进 bin 的节点指针。
  • 命令缓冲区是从池里挑的。挑选条件是 numDependentSubmissions() == 0(src/vsg/app/CommandGraph.cpp:98)——即"上一帧提交的那批已经完成";挑不到才新建 CommandPool 并 allocate(src/vsg/app/CommandGraph.cpp:106)。整个缓冲区按 VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT 录制(src/vsg/app/CommandGraph.cpp:127)。

最后进入遍历用的是 traverse(*recordTraversal)(src/vsg/app/CommandGraph.cpp:134),不是 accept——CommandGraph 自己不需要被 apply 一次,它只负责把自己的孩子交给遍历器。

1.10.3 第 7–9 步:RenderGraph::accept 的 begin render pass

RenderGraph 重写了 accept(RecordTraversal&),这是全库少数几个绕过 Inherit 默认 accept 的地方(include/vsg/app/RenderGraph.h:39):

using Group::accept;

/// execute vkCmdBeginRenderPass and then traverse the RenderGraph subgraph
void accept(RecordTraversal& recordTraversal) const override;

using Group::accept;(include/vsg/app/RenderGraph.h:36)保留了 Visitor/ConstVisitor 的默认版本,只对 RecordTraversal 特化。函数体的骨架是:

// src/vsg/app/RenderGraph.cpp:105
void RenderGraph::accept(RecordTraversal& recordTraversal) const
{
    auto extent = getExtent();
    if (previous_extent.width == invalid_dimension || previous_extent.height == invalid_dimension || !windowResizeHandler)
    {
        previous_extent = extent;
    }
    else if (previous_extent.width != extent.width || previous_extent.height != extent.height)
    {
        auto this_renderGraph = const_cast<RenderGraph*>(this);
        this_renderGraph->resized();
    }
    ...
    vkCmdBeginRenderPass(vk_commandBuffer, &renderPassInfo, contents);

    // sync the viewportState and push
    viewportState->set(renderArea.offset.x, renderArea.offset.y, renderArea.extent.width, renderArea.extent.height);

    if ((viewportStateHint & DYNAMIC_VIEWPORTSTATE))
    {
        recordTraversal.getState()->pushView(viewportState);
        traverse(recordTraversal);
        recordTraversal.getState()->popView(viewportState);
    }
    ...
    vkCmdEndRenderPass(vk_commandBuffer);
}

VkRenderPassBeginInfo 的字段直接映射到 RenderGraph 的成员:renderPass(或从 framebuffer/window 取)、framebuffer、renderArea、clearValueCount/pClearValues(src/vsg/app/RenderGraph.cpp:144 与 src/vsg/app/RenderGraph.cpp:145,来自 clearValues)、contents。

这段代码里有个必须注意的提前返回:走窗口路径时先取 imageIndex,越界就 return(src/vsg/app/RenderGraph.cpp:131)。此时 vkCmdBeginRenderPass 还没发,所以不需要补 vkCmdEndRenderPass——但也意味着这一帧什么都不画、日志里什么都没有。窗口最小化、swapchain 重建中的那一两帧就落在这条路径上。

这就是"渲染图是场景图的一部分"的具体含义:vkCmdBeginRenderPass 不是一个"引擎内部调用",而是一个节点的 accept 行为。你可以在 RenderGraph 下面随意插入命令(比如 vkCmdClearAttachments、vkCmdNextSubPass),因为它们都是 Command 子类。

1.10.4 第 10–13 步:apply(const View&) 的两阶段遍历

这是整个记录过程最精妙的一段。RecordTraversal::apply(const View&)(src/vsg/app/RecordTraversal.cpp:559)的第一句就是 state->dirtyStateStacks(),不是"遍历并绘制",而是先剔除、后绘制:

// src/vsg/app/RecordTraversal.cpp:559
void RecordTraversal::apply(const View& view)
{
    // dirty the state stacks to ensure state is newly applied for the View.
    state->dirtyStateStacks();

    // cache the previous bins
    int32_t cached_minimumBinNumber = minimumBinNumber;
    decltype(bins) cached_bins;
    cached_bins.swap(bins);
    ...
    minimumBinNumber = min_binNumber;
    bins.resize(max_binNumber - min_binNumber + 1);
    for (auto& bin : view.bins)
    {
        bins[bin->binNumber - min_binNumber] = bin;
        bin->clear();
    }
    ...
    state->pushView(view);

    if (view.camera)
    {
        state->inheritViewForLODScaling = (view.features & INHERIT_VIEWPOINT) != 0;
        state->setProjectionAndViewMatrix(view.camera->projectionMatrix->transform(), view.camera->viewMatrix->transform());
        ...
            view.traverse(*this);
    }
    ...
    state->popView(view);

    for (auto& bin : view.bins)
    {
        bin->accept(*this);
    }

    if (viewDependentState)
    {
        viewDependentState->traverse(*this);
    }
    ...
}

这段代码里有四个必须理解的设计:

(1)两阶段:剔除与绘制分离。

view.traverse(*this) 阶段(src/vsg/app/RecordTraversal.cpp:639)前一步刚比对过 viewportData 里的视口值。进入遍历后,遍历器走到每个 VertexIndexDraw 时不会立刻 vkCmdDraw,而是:

  • 用视锥体测试包围球/包围盒(state->isVisible(bound))
  • 如果可见,把节点指针 + 排序键 push 进对应的 Bin

然后 bin->accept(*this) 阶段(src/vsg/app/RecordTraversal.cpp:655),才真正遍历 bin 里的节点并录制命令;viewDependentState 的遍历还压在它后面。

为什么要分两阶段?因为排序需要全局信息。透明物体必须从后往前画,不透明物体必须按状态/材质排序以减少管线切换。你在遍历过程中不可能知道"所有可见物体里哪个最远",所以必须先收集、再排序、再绘制。

(2)state->dirtyStateStacks() 的作用。

State 里维护着"当前已绑定的管线/描述符/顶点缓冲"的栈。切换 View 时,新的 View 可能用完全不同的相机矩阵和视口,之前绑定的状态全部失效。dirtyStateStacks()(include/vsg/vk/State.h:311)把 dirty 与每个槽位的脏标记一起置真,下一次 record() 时会强制重新绑定,而不是相信"上次绑的就是这个"。

这是一个正确性优先的设计:它放弃了跨 View 的状态复用,换来了"不会因为状态残留导致渲染错误"。在多视图(VR 双眼、分屏)场景里,这个代价是值得的——两个 View 的相机矩阵不同,本来也无法复用。

(3)pushView / popView 与 INHERIT_VIEWPOINT。

state->pushView(view)(src/vsg/app/RecordTraversal.cpp:608)不只是压栈,它还处理 INHERIT_VIEWPOINT 特性:如果某个 View 声明"继承上一个 View 的视点"(用于阴影贴图、反射渲染这类"从光源/镜像相机看场景"的 pass),那么它的视矩阵不是自己的,而是继承来的。

state->inheritViewForLODScaling = (view.features & INHERIT_VIEWPOINT) != 0;

这一行在 src/vsg/app/RecordTraversal.cpp:612。inheritViewForLODScaling 影响 LOD 节点的选择:当从光源视角渲染阴影贴图时,LOD 应该按主相机的距离选择细节,而不是按光源的距离——否则阴影的精度会和主视图不匹配。

(4)ViewDependentState 的延迟遍历。

注意 viewDependentState->traverse(*this) 在 bin 回放之后才执行(src/vsg/app/RecordTraversal.cpp:660)。这是因为 ViewDependentState 里装的是"这一帧收集到的光源列表、阴影相机、裁剪平面"等数据,它们必须先由场景遍历填充(Light 节点的 apply 会往里面 push),然后才能上传到 GPU、发起阴影 pass。

这个"先收集、后使用"的模式,和 ResourceRequirements(第 8 章)是同一个思想:把"发现需求"和"满足需求"分成两个阶段,因为满足需求往往需要全局视角。

1.10.5 第 15–16 步:Bin 的排序与 StateGroup 的状态绑定

RecordTraversal::apply(const Bin& bin) 只有一行实质代码——把 bin 交回给它自己:

// src/vsg/nodes/Bin.cpp:109
void Bin::traverse(RecordTraversal& rt) const
{
    auto state = rt.getState();

    switch (sortOrder)
    {
    case (ASCENDING):
        std::sort(_binElements.begin(), _binElements.end(), [](const KeyIndex& lhs, const KeyIndex& rhs) { return lhs.first < rhs.first; });
        break;
    case (DESCENDING):
        std::sort(_binElements.begin(), _binElements.end(), [](const KeyIndex& lhs, const KeyIndex& rhs) { return rhs.first < lhs.first; });
        break;
    case (NO_SORT):
        break;
    }
    ...
}

这里有两个和流行说法不符的事实。第一,排序键只有深度一个分量:KeyIndex 是 std::pair<float, uint32_t>(include/vsg/nodes/Bin.h:69),第二个分量是元素在 _elements 里的下标,不是状态哈希;比较函数只看 .first(src/vsg/nodes/Bin.cpp:118)。所以 VSG 的 bin 不会按材质/管线排序,它只解决"前到后、后到前"。

第二,深度被压成了 float。Bin::add 里的入队语句是 _binElements.emplace_back(static_cast<float>(value), ...)(src/vsg/nodes/Bin.cpp:104),而 value 是 double。大尺度场景里两个相距 1 毫米的物体在 10 公里外可能拿到同一个 float,排序退化成稳定顺序——这不会画错,但会让透明物体的叠放顺序看上去"随机"。

Bin 还会在回放时省掉重复的矩阵压栈:相邻元素如果共用同一个 matrixIndex(src/vsg/nodes/Bin.cpp:137),就不重新 applyFrustum。这是 _matrices 去重表(include/vsg/nodes/Bin.h:56)的用途。

排序完成后,遍历到每个 StateGroup:

// src/vsg/app/RecordTraversal.cpp:515
void RecordTraversal::apply(const StateGroup& stateGroup)
{
    auto begin = stateGroup.stateCommands.begin();
    auto end = stateGroup.stateCommands.end();

    state->push(begin, end);

    stateGroup.traverse(*this);

    state->pop(begin, end);
}

注意 stateGroup.traverse(*this) 走的是 StateGroup 特化的版本:它只遍历 children,不遍历 stateCommands(include/vsg/nodes/StateGroup.h:75)。原因在 RecordTraversal::apply(StateGroup) 已经手动 push 过了;而面向普通 Visitor 的 t_traverse 会把 stateCommands 也访问一遍(include/vsg/nodes/StateGroup.h:69)。同一棵树,两套访问者看到的东西不一样——这是"遍历策略属于访问者"最直接的证据。

state->push 只改栈顶并把 dirty 置真(include/vsg/vk/State.h:368),不发任何命令。绑定发生在下一个 Command 到达时的 state->record()。所以"连续两个 StateGroup 管线相同就不会重复绑定"这个说法是错的:pop 会把 dirty 再置真(include/vsg/vk/State.h:389),同一个 StateGroup 出栈时必然触发一次重发。

1.10.6 第 17 步:VertexIndexDraw 到 vkCmdDrawIndexed

最后一步最短,整个函数就两行有效代码:

// src/vsg/app/RecordTraversal.cpp
void RecordTraversal::apply(const VertexIndexDraw& vid)
{
    ...
    state->record();
    vid.record(*(state->_commandBuffer));
}

state->record() 先把攒下的绑定命令发出去,vid.record(*(state->_commandBuffer)) 再发自己的绘制(src/vsg/app/RecordTraversal.cpp:343)。没有 children,没有子命令遍历——VertexIndexDraw::record 是另一个函数(src/vsg/nodes/VertexIndexDraw.cpp:178),它先从 _vulkanData 里取出本设备的句柄(src/vsg/nodes/VertexIndexDraw.cpp:180),再连续三调 vkCmdBindVertexBuffers(src/vsg/nodes/VertexIndexDraw.cpp:184)、vkCmdBindIndexBuffer(src/vsg/nodes/VertexIndexDraw.cpp:186)、vkCmdDrawIndexed(src/vsg/nodes/VertexIndexDraw.cpp:188)。

单独看 DrawIndexed 这条最纯粹的路径,就是一行:

void DrawIndexed::record(CommandBuffer& commandBuffer) const
{
    vkCmdDrawIndexed(commandBuffer, indexCount, instanceCount, firstIndex, vertexOffset, firstInstance);
}

到这里,一帧的纵切面结束。把它压缩成一张时序表:

步骤层关键函数产物
1–3应用/ViewerViewer::recordAndSubmit唤醒录制任务
4–6CommandGraphCommandGraph::record分配 VkCommandBuffer,开始录制
7–9RenderGraphRenderGraph::acceptvkCmdBeginRenderPass
10–12ViewRecordTraversal::apply(View)压入相机状态,开始剔除
13BinBin::traverse按深度排序后逐个回放
14StateGroupRecordTraversal::apply(StateGroup)压栈,dirty 置真
15ViewDependentStatetraverse光源/阴影数据上传
16VertexIndexDrawRecordTraversal::apply(VertexIndexDraw)state->record() 发出绑定
17CommandDrawIndexed::recordvkCmdDrawIndexed

1.10.7 编译阶段的同一条链路

同样一条场景图,在 viewer->compile() 时的路径完全不同:

步骤层关键函数产物
1CompileManagercompile(object, ...)object->accept(collectRequirements) 收集需求
2ContextContext::reserve一次性预留 descriptor/command buffer 等池
3CompileTraversalobject->accept(*compileTraversal)进入遍历
4BufferInfoBufferInfo::compile(Context&)vkCreateBuffer + 分配内存
5ImageInfoImageInfo::compile(Context&)vkCreateImage + vkBindImageMemory
6GraphicsPipelineGraphicsPipeline::compile(Context&)vkCreateGraphicsPipelines
7DescriptorSetDescriptorSet::compile(Context&)分配 + 更新描述符集
8Contextcommands / fencevkQueueSubmit + 等待,GPU 资源就绪

第 1 步的顺序不是可选的:CompileManager::compile 先 object->accept(collectRequirements)(src/vsg/app/CompileManager.cpp:260),拿到 ResourceRequirements 之后才逐个 context->reserve(requirements)(src/vsg/app/CompileManager.cpp:312),最后才 object->accept(*compileTraversal)(src/vsg/app/CompileManager.cpp:328)。预留失败时还有一次 resourceScavenger->scavenge() 的补救(src/vsg/app/CompileManager.cpp:315)。

对比两张表,你会发现一个重要的对称性:记录阶段只"用"资源,编译阶段只"造"资源。这条界线是整个 VSG 架构的脊柱——它让"资源创建"可以离线、可以并行、可以缓存,也让"每帧录制"变成纯粹的命令拼装,不做任何分配(除了命令缓冲本身)。

第 12 章和第 13 章会分别把这两条链路拆到每一行代码。

1.11 构建、验证与观测:把抽象库变成可实验的系统

结构图不能替代实验。这一节讲三件事:怎么构建不同形态的库、怎么让验证层替你抓错、怎么用二十行代码看清一棵场景图。

1.11.1 六个开关构成的构建矩阵

CMakeLists.txt 里的选项不是装饰,每一个都会改变运行期行为。把它们组合起来,能得到至少六种"不同形态"的 VSG:

开关默认关闭后的后果适用场景
VSG_SUPPORTS_WindowingON没有 Window::create(traits) 的默认实现,必须自己提供 VkSurfaceKHR服务器端离线渲染、嵌入自研引擎
VSG_SUPPORTS_ShaderCompilerON(需 glslang)只能加载预编译 .spv,不能运行时编译 GLSLiOS/Android 发布包、无 glslang 的交叉编译环境
VSG_SUPPORTS_ShaderOptimizerON(需 SPIRV-Tools-opt)不做 SPIR-V 优化,shader 体积和寄存器压力变大编译时间敏感的开发迭代
VSG_MAX_INSTRUMENTATION_LEVEL10 = 完全无插桩;3 = 每次状态切换都计时发布版用 0/1,性能分析用 2/3
VSG_MAX_DEVICES11 = vk_buffer 退化为裸值;>1 = 每资源按设备存一份多 GPU(SLI/CrossFire 已死,但专业卡多设备仍存在)
BUILD_SHARED_LIBS视 CMake 默认静态链接时 ABI 问题消失,但二进制变大、多 DSO 共享 RTTI 需谨慎单可执行文件分发 vs 插件生态

一个实用的组合建议:

# 开发期:全功能 + 细粒度插桩,方便定位
cmake -S . -B build-dev \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DVSG_MAX_INSTRUMENTATION_LEVEL=2 \
  -DVSG_SUPPORTS_ShaderCompiler=ON

# 发布期:关插桩、静态链接、预编译 shader
cmake -S . -B build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DVSG_MAX_INSTRUMENTATION_LEVEL=0 \
  -DBUILD_SHARED_LIBS=OFF

注意 VSG_MAX_INSTRUMENTATION_LEVEL=0 与"运行时把 instrumentation 设为 nullptr"不是一回事:前者把插桩代码从二进制里删掉,后者只是不执行。想在发布版里保留"临时开 profiling"的能力,用 1;想彻底消除开销,用 0。

1.11.2 验证层:三个开关,三种代价

WindowTraits 里有三个布尔值(include/vsg/app/WindowTraits.h:77):

bool debugLayer = false;           // VK_LAYER_KHRONOS_validation
bool synchronizationLayer = false; // VK_LAYER_KHRONOS_synchronization2
bool apiDumpLayer = false;         // VK_LAYER_LUNARG_api_dump

它们最终被 WindowTraits::validate()(include/vsg/app/WindowTraits.h:45)翻译成 requestedLayers(src/vsg/app/WindowTraits.cpp):

if (apiDumpLayer) requestedLayers.push_back("VK_LAYER_LUNARG_api_dump");
if (debugLayer) requestedLayers.push_back("VK_LAYER_KHRONOS_validation");
if (synchronizationLayer) requestedLayers.push_back("VK_LAYER_KHRONOS_synchronization2");

推入的顺序是 api_dump → validation → synchronization2(src/vsg/app/WindowTraits.cpp:158、src/vsg/app/WindowTraits.cpp:159、src/vsg/app/WindowTraits.cpp:160)。但推入不等于生效:紧接着的一行把它们丢给 validateInstanceLayerNames(src/vsg/app/WindowTraits.cpp:162),这个函数会逐个查 vkEnumerateInstanceLayerProperties 的结果(src/vsg/vk/Instance.cpp:62),不在列表里的名字只打一行 warn 就被丢掉(src/vsg/vk/Instance.cpp:87)。

这意味着一个很常见的误判:你写了 windowTraits->debugLayer = true,机器上却没装 validation layer,程序照常运行、画面照常出,验证层实际是关的。日志里唯一的线索是那句 requested invalid layer。

三个层的定位完全不同,别混用:

VK_LAYER_KHRONOS_validation(debugLayer) 是"正确性警察":检查参数合法性、对象生命周期、描述符绑定、渲染通道兼容性。代价是 CPU 侧开销 2–10 倍(每次 vkCmd* 都要校验),还会持有大量对象引用、改变内存行为——它适合功能开发期,不适合性能调优期,因为开销会掩盖真实瓶颈。

VK_LAYER_KHRONOS_synchronization2(synchronizationLayer) 是"竞态侦探":检测读写同一张图没有 barrier、两个队列访问同一资源没有信号量。VSG 的多线程录制 + 多帧在飞架构最容易出这类问题,而它是唯一能在开发期抓住这些 hazard 的手段。

VK_LAYER_LUNARG_api_dump(apiDumpLayer) 是"录音机":把每个 vkCmd* 打印出来。回答"VSG 到底发了哪些命令"时,它比断点更有效。

排错顺序也就固定了:功能不对看 VUID,闪烁花屏看 hazard,命令数对不上就数 vkCmdDraw*。

1.11.3 命令行:CommandLine 把开关变成参数

VSG 自带一个极简命令行解析器(include/vsg/utils/CommandLine.h:43),WindowTraits::readOptions 用它:

// src/vsg/app/WindowTraits.cpp:34
debugLayer = arguments.read({"--debug", "-d"});
apiDumpLayer = arguments.read({"--api", "-a"});
synchronizationLayer = arguments.read("--sync");

三个开关的读取位置在 src/vsg/app/WindowTraits.cpp:34、src/vsg/app/WindowTraits.cpp:35、src/vsg/app/WindowTraits.cpp:36。于是你的程序只要在 main 里加两行:

vsg::CommandLine arguments(&argc, argv);
windowTraits->readOptions(arguments);

就能在运行时决定开不开验证层:

./app model.vsgb --debug
./app model.vsgb --sync --api

Options::readOptions 也接受自己的参数(--paths、--file-cache 等)。设计意图是:让调试配置成为运行参数,而不是编译期开关——不该为了开验证层重新编译一次。

1.11.4 二十行代码看清一棵场景图

Visitor 的第一个用途不是剔除、不是记录,而是打印。写一个最小的 PrintVisitor:

#include <vsg/all.h>
#include <iostream>

class PrintVisitor : public vsg::Visitor
{
public:
    void apply(vsg::Object& object) override
    {
        for (int i = 0; i < _depth; ++i) std::cout << "  ";
        std::cout << object.className() << std::endl;
    }

    void apply(vsg::Group& group) override
    {
        apply(static_cast<vsg::Object&>(group));   // 打印自己
        ++_depth;
        group.traverse(*this);                     // 递归子节点
        --_depth;
    }

private:
    int _depth = 0;
};

// 用法
PrintVisitor printer;
scenegraph->accept(printer);

输出类似:

vsg::Group
  vsg::MatrixTransform
    vsg::StateGroup
      vsg::VertexIndexDraw
  vsg::MatrixTransform
    vsg::StateGroup
      vsg::VertexIndexDraw

这二十行代码里藏着三个必须讲清的机制,它们是第 3 章的地基。

机制一:apply 的委托链。

Visitor 为每个类型声明了一个 apply 重载,默认实现全部"向上转型后调用父类重载":

// src/vsg/core/Visitor.cpp
void Visitor::apply(Object&)
{
}

void Visitor::apply(Objects& value)
{
    apply(static_cast<Object&>(value));
}

void Visitor::apply(Data& value)
{
    apply(static_cast<Object&>(value));
}

apply(Object&) 的函数体是空的(src/vsg/core/Visitor.cpp:21),它就是整条链的终点;apply(Objects&)、apply(External&) 与 apply(Data&) 都把参数 static_cast 成 Object& 再转手(src/vsg/core/Visitor.cpp:24、src/vsg/core/Visitor.cpp:29、src/vsg/core/Visitor.cpp:34)。整份 .cpp 就是几十个这样的小函数,没有一个做实际工作。

这意味着:只重写 apply(Object&) 的访问者,能看到所有类型(因为每个类型的默认实现最终都会走到 Object);只重写 apply(Group&) 的访问者,只能看到 Group 及其派生类(Switch、LOD、StateGroup 的默认实现会向上走到 Group;apply(Group&) 声明在 include/vsg/core/Visitor.h:342,与 apply(Node&)(include/vsg/core/Visitor.h:339)、apply(Compilable&)(include/vsg/core/Visitor.h:340)、apply(Commands&)(include/vsg/core/Visitor.h:341)同处 // Nodes 分节)。

机制二:static_cast 是"选择回退版本"的开关。

注意 apply(static_cast<vsg::Object&>(group)) 这一行。如果写成 apply(group),静态类型是 Group&,虚分派会再次进入 PrintVisitor::apply(Group&),无限递归。加上 static_cast<Object&> 之后,静态类型变成 Object&,虚分派查的是 Object 的槽位,落到 apply(Object&)——这才是"打印基类信息"的正确写法。

这个坑的症状很隐蔽:栈溢出,但调用栈看起来"很正常"。规则是:在 apply 内部想调用父类版本,必须显式 static_cast 到父类引用。

机制三:traverse 与 accept 的分工。

accept 是"我被访问了",traverse 是"我去访问孩子"。Group 的遍历体只有一个 for 循环:

// include/vsg/nodes/Group.h
template<class N, class V>
static void t_traverse(N& node, V& visitor)
{
    for (auto& child : node.children) child->accept(visitor);
}

基类的 traverse 默认是空函数体——virtual void traverse(Visitor&) {},所以"没有孩子"和"不遍历孩子"在代码里长得一样。

PrintVisitor 手动调用 group.traverse(*this),意味着遍历是显式控制的。如果你重写 apply(Group&) 但忘了调 traverse,子节点就不会被访问——这不是 bug,这是设计:访问者可以选择"只看这一层"或"看整棵子树"。

同样的机制让 RecordTraversal 在 apply(LOD&) 里"只遍历选中的那个孩子",让 ComputeBounds 在 apply(Switch&) 里"只算可见分支"。遍历策略是访问者的职责,不是节点的职责。

1.11.5 用 RenderDoc 对照源码

VSG 的抽象层很厚,在 GPU 上留下的痕迹却很薄。RenderDoc 抓一帧看到的序列是:

vkCmdBeginRenderPass
  vkCmdBindPipeline(VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline_0)
  vkCmdBindDescriptorSets(...)
  vkCmdBindVertexBuffers(0, 1, {vb_0}, {0})
  vkCmdBindIndexBuffer(ib_0, 0, VK_INDEX_TYPE_UINT32)
  vkCmdDrawIndexed(36, 1, 0, 0, 0)
  vkCmdBindPipeline(VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline_1)   // ← 状态切换
  ...
vkCmdEndRenderPass

把这段序列和 1.10 节的 17 步对照,每一行都能找到来源:

RenderDoc 里的命令VSG 里的来源
vkCmdBeginRenderPassRenderGraph::accept(RecordTraversal&)
vkCmdBindPipelineGraphicsPipeline::record(由 StateGroup 的 state->record() 触发)
vkCmdBindDescriptorSetsBindDescriptorSet::record
vkCmdBindVertexBuffersVertexIndexDraw::record 的第一句
vkCmdDrawIndexedDrawIndexed::record / VertexIndexDraw::record 的末句

如果某个 vkCmdBindPipeline 出现了两次而你觉得应该只有一次,先别怀疑 compare():按 1.10.5,StateGroup 出栈时 pop 会把 dirty 置真,下一帧的第一个 Command 必然重发绑定。真正值得查的是"同一个 StateGroup 内部是否重发了两次"——那说明 pipelineStates 列表里混进了两个逻辑相同但字节不同的状态对象,去看那个状态类有没有未初始化字段(1.5.3 节的 memcmp 陷阱)。

如果某个 draw 完全没出现,按这个顺序排查:

  1. 节点是否被视锥剔除了?(RecordTraversal::apply(VertexIndexDraw&) 里的可见性判断)
  2. Bin 是否被清空了?(View::bins 没配置时,节点不会入桶)
  3. StateGroup 的管线是否编译失败?(viewer->compile() 返回的 CompileResult::result 不是 VK_SUCCESS)
  4. VertexIndexDraw 的 indexCount 是否为 0?(默认值是 0,忘了赋值就是"画了 0 个索引")

1.12 九个取舍的批判性评价

到这一节,你已经看到了 VSG 的骨架。现在换个立场:如果让你重写,这些决策哪些该保留,哪些该改? 这一节不是挑刺,而是训练"读代码时能看出代价"的能力。

1.12.1 取舍一:封闭的访问者集合 vs 开放的扩展

现状:Visitor 有 267 个 apply 重载,新增节点类型必须修改 Visitor.h/ConstVisitor.h,这违反开闭原则。

为什么这么做:双分派是场景图性能的核心。accept 是内联的,apply 是通过虚表的单次间接调用,没有 dynamic_cast、没有哈希查找、没有 std::function。Inherit 里的 accept 只有一句 visitor.apply(static_cast<Subclass&>(*this))(include/vsg/core/Inherit.h:70),编译器能把静态转型和虚调用一起展开。如果改成"注册回调表",每次访问就是一次哈希查找 + 一次间接调用,在百万节点的遍历上是灾难。

代价:

  • 第三方无法在不修改 VSG 的前提下增加"一等公民"节点类型。你只能继承已有的节点(比如 Group),然后重写 apply(Group&) 的访问者会把你当成 Group 处理——这通常够用,但你就失去了类型特有的优化。
  • Visitor.h 成了一个巨大的头文件,任何新增类型都会触发全库重编。

如果重写:我会保留双分派,但把 apply 集合拆成多个"访问者接口"(NodeVisitor、StateVisitor、CommandVisitor),让不同类型的访问者只依赖自己关心的那部分。VSG 实际上已经在做类似的事——RecordTraversal 就是独立于 Visitor 的第二套分派,它的类声明是 class RecordTraversal : public Object(include/vsg/app/RecordTraversal.h:73),自己维护一个 std::vector<ref_ptr<Bin>> bins(include/vsg/app/RecordTraversal.h:184)和 minimumBinNumber(include/vsg/app/RecordTraversal.h:183)。这说明作者也意识到了"一个 Visitor 装不下所有东西"。

1.12.2 取舍二:memcmp 比较的脆弱性

现状:Inherit::compare 用 memcmp 比较派生类新增的字节(include/vsg/core/Inherit.h:67)。

代价:

  • padding 未初始化会导致"逻辑相等但比较不等",进而导致状态无法复用、管线数量爆炸。
  • 结构体里一旦出现指针成员,比较的是地址而不是内容,语义错误且难以发现。GraphicsPipeline 就是因此改手写比较的例子(src/vsg/state/GraphicsPipeline.cpp:134 用 compare_pointer_container 比 pipelineStates)。
  • 编译器升级、ABI 变化(比如 [[no_unique_address]] 被更激进地使用)可能改变布局,sizeof(ParentClass) 的假设就崩了。
  • 跨编译器/跨平台的文件格式如果依赖 compare 的排序结果,会出现"同一个文件在不同平台上序列化出不同顺序"的问题。

为什么还这么做:手写 compare 对 36 个状态类、26 个节点类逐个字段比较,是巨大的维护负担,而且极易漏字段。memcmp 用一行代码覆盖所有字段,只要遵守"POD + 无指针 + 零初始化"的约定就是正确的。

如果重写:我会用编译期反射(C++20 的聚合初始化 + std::tuple 折叠,或者 boost::pfr)自动生成字段级比较。这样既不用手写,也不依赖内存布局。VSG 选择 memcmp 是因为它要支持 C++17 且不愿引入依赖——这是一个"工程约束下的合理妥协",但确实是技术债。

1.12.3 取舍三:VSG_MAX_DEVICES 是编译期常量

现状:单设备时 vk_buffer<T> 特化为裸 T,多设备需重编整个库。

代价:一个想在"笔记本单 GPU"和"工作站双 GPU"上都跑的应用,必须分发两个二进制,或者永远付多设备的开销。

更现实的评价:这个取舍在 2019 年合理(多 GPU 渲染基本消亡),却把"未来支持多设备"的路堵死了:若要在一个进程里用多个独立 VkDevice(比如同时预览两个驱动),这个设计就是障碍。

如果重写:用 std::variant<T, std::array<T,N>> 或者一个 8 字节的 union + 运行期标志。多 4 字节,换来运行期灵活性。但要注意:这会让 vk_buffer 的访问多一次分支,在热路径上不划算。所以更可能的演进是保持编译期常量,但提供"多设备版本"的独立构建目标。

1.12.4 取舍四:单继承约束

现状:is_compatible + static_cast 的正确性依赖"基类子对象在偏移 0"。

代价:你不能写 class MyNode : public vsg::Group, public MyMixin。一旦多继承,cast<MyNode>() 可能返回错误指针(指向 Group 子对象而不是 MyNode 起始地址),而且不会报错——只会在运行时读到垃圾。

为什么可以接受:多继承在场景图里几乎没有正当用途。要"给节点加功能",正确做法是组合(在 Auxiliary 里挂一个对象)而不是继承。

如果重写:我会在 Inherit 里加一个 static_assert(std::is_same_v<...>) 或者用 offsetof 检查,把"多继承"变成编译错误而不是运行时炸弹。目前 VSG 没有这个保护,这是一个可以低成本修复的缺陷。

1.12.5 取舍五:Auxiliary 的创建不是线程安全的

现状:getOrCreateAuxiliary() 没有加锁,两个线程同时调用会创建两个 Auxiliary,其中一个泄漏(甚至可能两个都被挂上,导致未定义行为)。

为什么可以接受:VSG 的线程模型规定"构建/加载单线程完成、录制阶段只读",此时 getOrCreateAuxiliary 不会被并发调用。文档没明说,代码里处处体现这个假设。

风险:这个假设既没有编译期也没有运行期检查。在 record 阶段给节点 setValue(比如统计信息)就会触发,而且是偶发的,压测时才暴露。

如果重写:把 _auxiliary 改成 std::atomic<Auxiliary*> + CAS 创建,代价是有 Auxiliary 时每次访问多一次原子读;或者在 debug 构建里检查 std::thread::id,跨线程创建就断言。

1.12.6 取舍六:operator T* 的隐式转换

现状:

// include/vsg/core/ref_ptr.h:164
// potentially dangerous automatic type conversion, could cause dangling pointer if ref_ptr<> assigned to C pointer and ref_ptr<> destruction causes an object delete.
operator T*() const noexcept { return _ptr; }

注释自己都承认危险(include/vsg/core/ref_ptr.h:164)。对照一下同一份文件里的显式版本:explicit operator bool() 在 include/vsg/core/ref_ptr.h:162,取裸指针的显式出口是 get()(include/vsg/core/ref_ptr.h:173)——安全路径一直存在,只是隐式那扇门没关。

危险在哪:

vsg::Node* raw = vsg::Node::create();   // 临时 ref_ptr 在这里析构 → 对象被删 → raw 悬空
raw->accept(visitor);                    // 未定义行为

这段代码能编译、能通过大多数静态检查,然后在运行时随机崩溃。这是 C++ 智能指针设计里最经典的陷阱,std::shared_ptr 用 explicit operator bool + 无隐式转换避免了它。

为什么 VSG 还保留:因为大量代码依赖它:

if (auto node = vsg::read_cast<vsg::Node>(filename)) { ... }   // 需要 operator bool
visitor.apply(*node);                                          // 需要 operator*
someFunction(node);                                            // 需要隐式转 Node*

去掉隐式转换会让几乎所有 API 调用都要写 .get(),破坏源码兼容性。在一个已经发布 17 个 ABI 版本的库上,这个改动不可能做。

如果重写:explicit operator T*() + 显式 .get()。短期痛苦,长期安全。

1.12.7 取舍七:<= 1 的计数判断

现状:

if (_referenceCount.fetch_sub(1, std::memory_order_seq_cst) <= 1) _attemptDelete();

用 <= 而不是 ==,在计数已为 0 时仍会调用 _attemptDelete,可能双重释放。

为什么:防御"计数下溢"这种更隐蔽的 bug(比如某处多调了一次 unref)。用 <= 至少能保证对象被删一次,而不是永远泄漏。

评价:这是一个"用崩溃换泄漏"的选择,在 debug 场景下合理(崩溃比静默泄漏更容易发现),在 release 场景下有风险(双重释放可能被利用)。更好的做法是:debug 构建断言 == 1,release 构建用 <= 并记录日志。

1.12.8 取舍八:目录分层的名实不符

现状:vk/Context.h 依赖 app/、commands/、state/、utils/,目录结构不反映依赖层次。

代价:新人无法通过目录理解架构;工具(比如 include-what-you-use、模块化重构)会报出大量"循环依赖";想抽取"纯 Vulkan 封装"子集(比如只想要 vk/ 不要 app/)时发现做不到。

为什么:见 1.3.2 的分析——Context 本质上是 L4,放在 vk/ 只是命名归属。

如果重写:把 Context 移到 app/ 或新建 compile/ 目录;vk/ 只保留纯句柄封装。这会立刻让"能否只用 vk 层"这个问题有明确答案。

1.12.9 取舍九:平台默认走 XCB

现状:Linux 上 else() 分支默认编译 XCB 窗口,Wayland 没有原生支持。

代价:纯 Wayland 环境(比如某些嵌入式 Linux、最新的 Fedora 默认会话)需要 XWayland 才能跑;容器里没有 X11 时无法创建窗口(只能用 headless surface)。

评价:历史惯性加维护成本。XCB 实现成熟稳定,Wayland 协议复杂(xdg-shell、wl_surface、wl_seat 一堆对象),VSG 核心团队规模又小;用户可以用 vsgSDL(社区项目)绕开。

如果重写:把窗口后端做成插件(Window::create 从注册表查找),核心库只定义接口。这样 XCB/Wayland/headless 都可以独立演进,不必改核心。这也是 VSG_SUPPORTS_Windowing 这个选项本该走的方向。

1.12.10 取舍总表

九条取舍的收益与代价可以压成一句话:每一项"缺点"都是被明确选择过的收益。封闭访问者换零查找双分派,memcmp 换一行覆盖所有字段,编译期常量换单设备零开销,单继承换 static_cast,无锁 Auxiliary 换访问速度,隐式 operator T* 换源码兼容,<= 1 判断换防下溢,目录名实不符换代码局部性,默认 XCB 换成热路径的稳定。读源码时能同时看到收益和代价,才算真正读懂。

1.13 从结论到路线:三条阅读路径

1.0.2 的十条结论不再重复,只补一件它没给的事:不同目的的读者按什么顺序读。后面 27 章按依赖排列,跳读会踩空——第 12 章的 RecordTraversal 默认你读过第 3 章的 Visitor。

1.13.1 三条阅读路线

不同目的的读者,可以走不同的路径:

路线 A:想用 VSG 做应用 1.1 → 1.8 → 1.9 → 第 14–18 章 → 第 28 章(实战)。跳过内存序与 memcmp 的细节。

路线 B:想改 VSG 或写扩展 1.4 → 1.5 → 1.6 → 第 2/3/9 章 → 第 12/13 章(两种遍历)。要求你理解每一个字节。

路线 C:想借鉴架构 1.0–1.3 → 1.12 → 第 8/13/16 章。关注"如何把复杂系统切成可并行的阶段"。

1.14 从哪读起:一条 12 小时的源码路线

300 多个头文件从哪读起?大部分人从 Object.h 开始,读三页就迷失在 Auxiliary、CopyOp、Duplicate 里。这一节给一条有明确产出的路线:每读一个文件,回答一个具体问题。

1.14.1 四个阶段与 22 个文件

阶段文件读完能回答
词汇(2h,7 个)core/Object.h、core/ref_ptr.h、core/Inherit.h、core/Auxiliary.h、core/Visitor.h(前 300 行)、src/vsg/core/Visitor.cpp(前 60 行)、nodes/Node.h+Group.h一个对象最小是什么样?create()/accept() 从哪来?默认 apply 为什么是空的?
一次绘制(3h,6 个)commands/Command.h、commands/DrawIndexed.h、nodes/VertexIndexDraw.h、nodes/StateGroup.h、state/GraphicsPipeline.h、src/vsg/app/RecordTraversal.cpp 的 apply(View&)一条绘制命令有几个字段?剔除和绘制为什么分两阶段?
资源(3h,5 个)state/BufferInfo.h、vk/ResourceRequirements.h、vk/Context.h、app/CompileTraversal.h、app/TransferTask.h为什么先收集再分配?上传为什么单独一个队列?
一帧(4h,4 个)app/CommandGraph.h、app/RenderGraph.h、app/Viewer.h+src/vsg/app/Viewer.cpp、threading/FrameBlock.h+Barrier.h命令图凭什么"自己录制自己"?vkCmdBeginRenderPass 藏在哪?

读完这 22 个文件(约 6000 行),本系列 60% 的问题你都能自己回答;剩下 40% 在 io/、text/、animation/、lighting/、raytracing/ 里按需深入。

1.14.2 五个用 grep 回答问题的套路

读源码时,80% 的困惑可以用五条命令解决:

# 1. 谁调用了这个函数?(反向查找调用点)
grep -rn "getOrCreateRecordTraversal" include/ src/ | grep -v "\.h:"

# 2. 这个基类有哪些派生类?(找继承关系)
grep -rn "public Inherit<Group," include/vsg/nodes/

# 3. 这个类型在访问者里怎么处理?(找 apply 重载)
grep -n "apply(const LOD&" -A 20 src/vsg/app/RecordTraversal.cpp

# 4. 这个字段在哪被赋值?(找写入点)
grep -rn "traversalMask =" include/vsg/ src/vsg/

# 5. 平台差异在哪?(找条件编译)
grep -rn "#if.*WIN32\|#ifdef _WIN32" include/vsg/app/ | head -20

第 2 条特别有用:继承全部写成 public Inherit<Parent, Self>,一条 grep 就能列出某父类的所有子类。

读完每个模块只需自检三件事:所有权边界(持 ref_ptr 还是裸指针、析构做什么)、线程边界(谁创建、谁读、有没有锁)、失败边界(返回 bool、nullptr 还是抛异常,失败后对象处于什么状态)。这三条对应 VSG 的三条主线——生命周期、并发、错误处理。

1.15 术语表:本系列反复出现的 9 个词

有几个词在不同上下文含义不同,先统一口径。

术语精确定义易混淆点
访问者(Visitor)实现 apply(T&) 重载的类,通过 accept 被调用RecordTraversal 不是 Visitor 的子类,是独立分派体系
状态(state)Vulkan 管线状态的 C++ 对象表示与运行期 vsg::State(记录遍历的状态栈)不同
编译(compile)把描述性对象变成真实 Vulkan 资源的过程不是"编译 C++",也不是"编译 shader"
记录(record)把命令写入 VkCommandBuffer 的过程与"提交(submit)"不同
提交(submit)vkQueueSubmit,把命令缓冲区交给 GPU与"呈现(present)"不同
在飞帧(frame in flight)已经提交但 GPU 还没执行完的帧数量由 swapchain 图像数决定
槽(slot)状态在状态栈里的索引,StateCommand::slot不是"描述符槽位"
桶(Bin)按排序键收集可见节点的容器不是"线程池队列"
动态对象(dynamic object)需要在运行时修改、因而不能共享的子树由 FindDynamicObjects 标记

两个词必须在脑子里分成两半:vsg::State 在 state/ 里指管线状态对象,在 vk/State.h 里指记录遍历的状态栈;"编译"在 CompileTraversal 里是创建 GPU 资源,在 ShaderCompiler 里是 GLSL→SPIR-V。

1.16 陷阱表:二十二条能从源码读出来的坑

每一行都对应一处具体代码,不是经验之谈;坐标列给的是"你该打开的那一行"。

陷阱触发条件后果源码坐标规避
Auxiliary::setObject 直接下标赋值两个线程同时读写 userObjects这张 map 的数据竞争,可能丢键或崩include/vsg/core/Auxiliary.h:45写入只放在加载期
getOrCreateAuxiliary 对 _auxiliary 判空但不加锁在 record 阶段调 setValue造出两个 Auxiliary,前一个泄漏src/vsg/core/Object.cpp:228进主循环前把元数据建好
删除否决钩子没有任何派生实现指望 signalConnectedObjectToBeDeleted() 挡住 GPU 在用对象计数归零即 delete this,VkBuffer 可能提前销毁src/vsg/core/Auxiliary.cpp:58由 DeleteQueue 兜底
DeleteQueue 只保留 3 帧资源被更早的在飞帧引用提前释放,验证层报对象已销毁include/vsg/threading/DeleteQueue.h:39调大 retainForFrameCount
unref() 的判据是 <= 1某处多减了一次计数下溢后仍走 _attemptDelete,双重释放include/vsg/core/Object.h:125只用 ref_ptr 管所有权
compare() 对派生部分做 memcmp状态类有未初始化的 padding逻辑相等却比较不等,管线膨胀include/vsg/core/Inherit.h:57所有状态对象用 {} 初始化
operator T* 是隐式转换写成 Node* p = Node::create()临时 ref_ptr 析构,p 变成 dangling 指针include/vsg/core/ref_ptr.h:164显式调 get()
Bin 的排序键被压成 float场景尺度到几十公里不同深度撞同一个键,透明顺序抖动src/vsg/nodes/Bin.cpp:104按区域拆多个 bin
Bin 只按深度排序期待它顺带按材质排序管线切换数一点没降src/vsg/nodes/Bin.cpp:118自己分 binNumber
StateGroup 出栈会把 dirty 置真两个相邻 StateGroup 管线相同仍会重复 vkCmdBindPipelineinclude/vsg/vk/State.h:389合并 stateCommands 减少层数
RenderGraph 取不到 imageIndex 就返回swapchain 重建中整帧不录,日志空白src/vsg/app/RenderGraph.cpp:131容忍空帧,别在这里断言
窗口不可见时 record 提前返回窗口最小化,window->visible() 为 false帧号照走,内容不更新src/vsg/app/CommandGraph.cpp:80属正常行为,不要在外部重试
start() 等 fence 没有超时驱动挂死主线程永久阻塞在 hasDependencies 分支src/vsg/app/RecordAndSubmitTask.cpp:134外部 watchdog 或超时封装
请求的层不存在会被静默丢弃机器上没装 validation layer验证层实际关闭,debugLayer = true 形同虚设src/vsg/vk/Instance.cpp:87看到 requestedName 警告就补装
read_cast 里用的是 dynamic_cast多个 DSO 各自静态链接一份库转型失败返回空指针,文件"读不出来"include/vsg/io/read.h:40保证只有一份 libvsg
getValue 比较 typeid 精确相等存 Value<基类> 取 Value<派生>静默返回 falseinclude/vsg/core/Value.h:183键与 ValueT 严格同型
VSG_MAX_DEVICES 是编译期常量想在运行时切多设备设置无效,必须重编整个库include/vsg/vk/vk_buffer.h:46构建两套二进制
Object::compare 先比 type_index拿两个不同类比较结果只反映类型序,不代表内容src/vsg/core/Object.cpp:115只在同类型之间比较
CompileManager::compile 拿不到空闲遍历器并发调用 compile直接返回未编译的结果src/vsg/app/CompileManager.cpp:276串行化编译,或检查返回值重试
View 的 bins 为空自建 View 忘了配 bin节点不入桶,画面上什么都没有include/vsg/app/View.h:84至少配一个默认 bin
resized 只在 extent 变化时触发自己另建 viewportState窗口拉伸后画面比例错src/vsg/app/RenderGraph.cpp:114自己同步视口
类里引入多继承想用 mixin 给节点加功能cast<T>() 返回错位指针,不报错include/vsg/core/Object.h:96用组合或 Auxiliary

这些坑的根子相同:VSG 把"确保正确"的责任推给调用方。锁不加、帧数不调、层不装、bin 不配,代码都不拦你,只在特定场景下异常。

1.16.1 五条把上表钉死的复现命令

# 1. 引用计数的两种内存序与 <= 1 判据,一眼可见
grep -n "memory_order\|<= 1" include/vsg/core/Object.h
# 2. 删除否决钩子全库只有声明、定义、一个调用点,没有派生实现
grep -rn "signalConnectedObjectToBeDeleted" include/ src/
# 3. DeleteQueue 走的是帧号队列,与 Auxiliary 无关
grep -n "retainForFrameCount\|_objectsToDelete" include/vsg/threading/DeleteQueue.h src/vsg/threading/DeleteQueue.cpp
# 4. RecordAndSubmitTask 没有 run(),只有 start/record/finish/submit
grep -n "RecordAndSubmitTask::" src/vsg/app/RecordAndSubmitTask.cpp
# 5. VertexIndexDraw 是 Command,record 内联三调,没有 children
grep -n "class VertexIndexDraw\|children\|vkCmdBindVertexBuffers\|vkCmdBindIndexBuffer\|vkCmdDrawIndexed" include/vsg/nodes/VertexIndexDraw.h src/vsg/nodes/VertexIndexDraw.cpp

第 5 条最值得跑:它同时否掉两个流传很广的说法——"VertexIndexDraw 是节点"和"它内部有三个子命令"。输出里 class VSG_DECLSPEC VertexIndexDraw : public Inherit<Command, VertexIndexDraw> 那一行就是答案。

补两个支撑上表的短摘录。第一个是 Bin::add 的入队语句,说明深度在哪一步被降精度:

// src/vsg/nodes/Bin.cpp:104
    _binElements.emplace_back(static_cast<float>(value), static_cast<uint32_t>(_elements.size()));

第二个是 State::record 的闸门,说明"绑定是否重发"由 dirty 决定,而不是由两次状态值是否相等决定:

// include/vsg/vk/State.h:350
            if (dirty)
            {
                for (uint32_t slot = 0; slot <= activeMaxStateSlot; ++slot)
                {
                    stateStacks[slot].record(*_commandBuffer);
                }

dirty 一旦被 push 或 pop 置真,整个 activeMaxStateSlot 范围内的槽位都会重发一遍——这是"层数越少、绑定越省"的物理原因,也是第 9 章状态优化的出发点。


源码索引

结论文件关键位置
版本与 ABICMakeLists.txtproject(vsg VERSION 1.1.16)、set(VSG_SOVERSION 17)
单设备特化include/vsg/vk/vk_buffer.h#if VSG_MAX_DEVICES <= 1
插桩分级include/vsg/utils/Instrumentation.h#if VSG_MAX_INSTRUMENTATION_LEVEL >= 1/2/3
引用计数与内存序include/vsg/core/Object.href()、unref()、_referenceCount
删除钩子src/vsg/core/Object.cppObject::_attemptDelete()
CRTP 类型系统include/vsg/core/Inherit.hcreate、is_compatible、compare、accept
分层反例include/vsg/vk/Context.h对 app/、commands/、state/、utils/ 的包含
元数据include/vsg/core/Auxiliary.hObjectMap、setObject、signalConnectedObjectToBeDeleted
命令接口include/vsg/commands/Command.hclass Command : public Inherit<Compilable, Command>、纯虚 record
绘制命令细节include/vsg/commands/DrawIndexed.h五个 uint32_t 字段、内联 record
视图两阶段src/vsg/app/RecordTraversal.cppapply(const View&)、apply(const CommandGraph&)
状态栈脏化src/vsg/app/RecordTraversal.cppstate->dirtyStateStacks()、pushView/popView
访问者委托链src/vsg/core/Visitor.cppapply(Objects&)、apply(Data&)、apply(stringValue&)
验证层src/vsg/app/WindowTraits.cppVK_LAYER_KHRONOS_validation、VK_LAYER_KHRONOS_synchronization2、VK_LAYER_LUNARG_api_dump

下一章预告

第二章进入 core/ 的其余部分:Data/Array 的内存布局、Allocator 的四种亲和性、MemorySlots 的空闲链表、ScratchMemory 的栈式分配。我们会用具体的字节数回答一个问题:为什么一个 100 万节点的场景图,VSG 能在 200ms 内加载完,而一个朴素的 new/delete 实现需要 3 秒。