《VulkanSceneGraph 1.1.16 源码深度解析》第七章 命令与命令图:Command / CommandBuffer /CommandGraph

3 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第七章 命令与命令图:Command / CommandBuffer / CommandGraph

第六章把对象造出来了:Instance、PhysicalDevice、Device、Queue、Context。但它们只是"能用的零件",还没有被组织成"一帧"。

这一章处理的是从零件到帧的那一段。它比前面任何一章都更接近 Vulkan 本体——因为这一层几乎就是 vkCmd* 的封装。但正因为如此,它也最容易写成"API 手册的中文翻译"。所以本章不按 Vulkan 的函数顺序讲,而按 VSG 自己的三段结构讲:

  • Command / Commands:什么是可以被录制的东西。
  • CommandBuffer / CommandPool / RecordTraversal / State:录制到底发生在哪一刻,谁在状态栈上做决定。
  • CommandGraph / SecondaryCommandGraph / ExecuteCommands:谁定义帧的边界,二级命令缓冲怎么被拼进主缓冲。

这三段之间有一条不太明显的分界线:编译期录制与帧期录制。Context::record() 属于前者,一次就够;CommandGraph::record() 属于后者,每帧都跑。VSG 把这两件事分得很开,但接口长得几乎一样——都是 record(CommandBuffer&)。这个"看起来一样"是后面几乎所有误解的来源。

7.0 度量

本章核心文件 52 个,合计 5,206 行:

分组文件(行数)小计
命令基类commands/Command.h(33) commands/Commands.h(64) Commands.cpp(66)163
帧边界app/CommandGraph.h(68) CommandGraph.cpp(149) app/SecondaryCommandGraph.h(62) SecondaryCommandGraph.cpp(177) app/RenderGraph.h(90) RenderGraph.cpp(230)776
录制核心app/RecordTraversal.h(191) RecordTraversal.cpp(704) vk/State.h(454) State.cpp(112) vk/Slots.h(46)1,507
命令缓冲vk/CommandBuffer.h(106) CommandBuffer.cpp(133) vk/CommandPool.h(57) CommandPool.cpp(75)371
屏障与事件commands/PipelineBarrier.h(159) PipelineBarrier.cpp(129) commands/Event.h(114) Event.cpp(151)553
传输命令commands/CopyAndReleaseImage.h(71) CopyAndReleaseImage.cpp(185) commands/CopyAndReleaseBuffer.h(55) CopyAndReleaseBuffer.cpp(83)394
二级缓冲commands/ExecuteCommands.h(55) ExecuteCommands.cpp(83)138
具体命令BindVertexBuffers(51+112) BindIndexBuffer(54+113) Draw(51+45) DrawIndexed(53+47) DrawIndirect(44+100) DrawIndexedIndirect(44+100) Dispatch(43+38) CopyImage(37+32) CopyImageToBuffer(39+31) BlitImage(38+33) ClearImage(51+32) ClearAttachments(41+75)1,304

这 5,206 行里真正决定"会不会踩坑"的只有 393 行,后文逐个拆:

  • CommandGraph::record 65 行:src/vsg/app/CommandGraph.cpp:76,函数体从 CPU_INSTRUMENTATION_L1_NC 起算。
  • SecondaryCommandGraph::record 89 行:src/vsg/app/SecondaryCommandGraph.cpp:77。
  • RecordTraversal::apply(const View&) 111 行:src/vsg/app/RecordTraversal.cpp:559,进门第一句是 dirtyStateStacks()(RecordTraversal.cpp:564)。
  • RecordTraversal::apply(const CommandGraph&) 29 行:src/vsg/app/RecordTraversal.cpp:671,recordedCommandBuffers 为空时退化成普通 traverse(RecordTraversal.cpp:697)。
  • StateStack 模板 55 行:include/vsg/vk/State.h:31。
  • State::record() 18 行:include/vsg/vk/State.h:348,循环上界是 activeMaxStateSlot(State.h:352)。
  • CommandBuffer::reset:src/vsg/vk/CommandBuffer.cpp:45,先清 _currentPushConstantStageFlags,再读池的 VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT(CommandBuffer.cpp:50)。
  • CommandBuffer::setCurrentPipelineLayout:src/vsg/vk/CommandBuffer.cpp:56,比较的是 newLayout 句柄(CommandBuffer.cpp:59)。

其余 90% 是结构体填充与重载转发:BindVertexBuffers::record 只有 4 行,一次 vkCmdBindVertexBuffers 加一次 _vulkanData 索引(src/vsg/commands/BindVertexBuffers.cpp:108);Draw::record 内联在头文件里,一行 vkCmdDraw(include/vsg/commands/Draw.h:39)。

include/vsg/commands/ 下 34 个头文件:1 个基类 Command.h,33 个派生类。它们的 record 长度分布极端不均匀:

record 长度命令类数量
1 行(单个 vkCmd*)Draw DrawIndexed Dispatch SetViewport SetScissor SetLineWidth SetDepthBias SetPrimitiveTopology NextSubPass BeginQuery EndQuery WriteTimestamp ResetQueryPool SetEvent ResetEvent15
2–8 行(一次 vkCmd* + 参数整理)CopyImage BlitImage ResolveImage ClearImage CopyImageToBuffer BindIndexBuffer BindVertexBuffers ClearAttachments CopyQueryPoolResults CopyImageViewToWindow DrawIndirect DrawIndexedIndirect12
10–30 行(多次 vkCmd* 或多分支)PipelineBarrier WaitEvents DrawIndexedIndirectCommand ExecuteCommands Commands CopyAndReleaseImage6

33 个类里 15 个的 record 只有一行。命令层不是"对 Vulkan 的抽象",而是"给 Vulkan 调用加了一个虚函数入口";抽象发生在上层(State / StateGroup / CommandGraph),不发生在命令层。

六个可以直接定位的缺陷,本章逐一给证据:

  1. SecondaryCommandGraph::record 的 VkCommandBufferInheritanceInfo 没有零初始化(src/vsg/app/SecondaryCommandGraph.cpp:127),device+family 构造路径下 framebuffer 字段是未初始化栈值。
  2. StateStack::push 是 stack[++pos],而 stack 是 std::array<const T*, STATESTACK_SIZE>(include/vsg/vk/State.h:64),同槽第 16 次 push 写到 pos 自己的内存上。
  3. CommandBuffer::reset() 无条件清 CPU 侧缓存,却只在池带 RESET_COMMAND_BUFFER_BIT 时 vkResetCommandBuffer(src/vsg/vk/CommandBuffer.cpp:45)。
  4. CommandGraph::record 每需要新缓冲就 CommandPool::create 一个新池(src/vsg/app/CommandGraph.cpp:106),而 _commandBuffers 永不收缩(CommandGraph.cpp:108)。
  5. CopyAndReleaseBuffer::record 一条屏障都不发(src/vsg/commands/CopyAndReleaseBuffer.cpp:69),CopyAndReleaseImage 则在 transferImageData 里发 2 + 2×(mips-1) 条;上一章预告里"一次 vs 两次"的说法是错的。
  6. Commands::record 与 RecordTraversal::apply(const Commands&) 是两份行为不同的实现(src/vsg/commands/Commands.cpp:60 对照 src/vsg/app/RecordTraversal.cpp:531)。

这六条大多不立刻崩,因为它们落在 CPU 侧簿记而不是 GPU 侧提交:未初始化字段可能被驱动当成"没有 framebuffer";清缓存清早了只是多绑一次资源;池多了只是多几次驱动调用;少一条屏障在集显上看不出问题。唯一致命的是第 2 条——它把 pos 本身写坏,之后任何 push 或 record 都解引用野地址。VSG 在这一层的策略是"让错误变慢,不让错误变响",第 2 条是唯一例外。

7.1 Command:33 行,一个纯虚函数

7.1.1 全部代码

include/vsg/commands/Command.h 去掉许可证头只有 18 行,核心是 4 行:

// include/vsg/commands/Command.h:22-30
class VSG_DECLSPEC Command : public Inherit<Compilable, Command>
{
public:
    Command() {}
    Command(const Command& rhs, const CopyOp& copyop = {}) :
        Inherit(rhs, copyop) {}

    virtual void record(CommandBuffer& commandBuffer) const = 0;
};

没有 compare、没有 read、没有 write、没有重写 compile、没有成员变量。基类注释只说了一句"封装 vkCmd* 调用及其设置"(Command.h:21)。

继承链 Command → Compilable → Node → Object,每层贡献一件事:

层贡献是否需要
Object引用计数、compare、read/write 接口需要(能被 ref_ptr 持有、被序列化)
Nodeaccept(Visitor&) 三个重载、traverse、mask需要(能挂进场景图)
Compilablevirtual void compile(Context&) {}(空实现)需要,但语义可疑
Commandvirtual void record(CommandBuffer&) const = 0核心

7.1.2 为什么继承 Compilable 而不是直接继承 Node

Compilable 只有一个成员函数,默认实现为空:

// include/vsg/nodes/Compilable.h:22-30
class VSG_DECLSPEC Compilable : public Inherit<Node, Compilable>
{
public:
    Compilable() {}
    Compilable(const Compilable& rhs, const CopyOp& copyop = {}) :
        Inherit(rhs, copyop) {}

    virtual void compile(Context& /*context*/) {};
};

代价是 Command 同时承担两件时机差很远的事:

  • compile(Context&):CompileTraversal 期间调用,可能只一次、可能多线程,结果写进 _vulkanData[deviceID]。
  • record(CommandBuffer&) const:每帧调用、单线程、名义上不改对象。

这条时间线分裂是 Command 里所有 mutable 与"const 函数改状态"的来源。BindDescriptorSets 是最干净的样本:

// src/vsg/state/BindDescriptorSet.cpp:95-120
void BindDescriptorSets::compile(Context& context)
{
    auto& vkd = _vulkanData[context.deviceID];

    // no need to compile if already compiled
    if (vkd._vkPipelineLayout != 0 && vkd._vkDescriptorSets.size() == descriptorSets.size()) return;

    layout->compile(context);
    vkd._vkPipelineLayout = layout->vk(context.deviceID);

    vkd._vkDescriptorSets.resize(descriptorSets.size());
    for (size_t i = 0; i < descriptorSets.size(); ++i)
    {
        descriptorSets[i]->compile(context);
        vkd._vkDescriptorSets[i] = descriptorSets[i]->vk(context.deviceID);
    }
}

void BindDescriptorSets::record(CommandBuffer& commandBuffer) const
{
    auto& vkd = _vulkanData[commandBuffer.deviceID];
    vkCmdBindDescriptorSets(commandBuffer, pipelineBindPoint, vkd._vkPipelineLayout, firstSet, ...);
}

record 是 const,读的却是 compile 写进 _vulkanData 的 _vkPipelineLayout 与 _vkDescriptorSets。正确性完全依赖"compile 已经跑过",这个前置条件在类型系统里毫无体现。 未编译就 record 的 BindDescriptorSets 会拿 VK_NULL_HANDLE 的 layout,validation 报 VUID,驱动可能直接崩。

注意 compile 自己的短路条件(BindDescriptorSet.cpp:100):_vkPipelineLayout != 0 且 set 数量对得上就 return。它比较的是句柄非零与数量,不比较 layout 对象是否换了。复用同一个命令节点、只替换 layout 指针,compile 会静默跳过——这是"编译一次就够"假设的第二个漏洞。

VSG 的对策不是检查而是流程:Viewer::compile() 先跑,CompileTraversal 遍历整棵图。本章 7.6 有一处例外,CommandGraph::record 可以脱离 compile 被调用,此时没有任何东西阻止未编译的命令进入录制。

7.1.3 为什么没有 compare / read / write

Command 不重写这三个,每个派生类自己写。Commands 三个都重写(src/vsg/commands/Commands.cpp:29 起是 compare、read、write),PipelineBarrier 也只重写这三个。

这是正确的分层:Object::compare 的默认实现只比较 std::type_index(typeid(*this)) 与 _auxiliary(src/vsg/core/Object.cpp:112),子类必须显式把成员塞进去,否则两个内容不同、类型相同的命令会被判为相等。序列化同理,基类不知道派生类有哪些字段。

真正的状态比较在 StateCommand:

// include/vsg/state/StateCommand.h:26-36
explicit StateCommand(uint32_t in_slot = 0) :
    slot(in_slot) {}
...
uint32_t slot = 0;

slot 进了 compare(compare_value(slot, rhs.slot),src/vsg/state/StateCommand.cpp:37),也进了 read/write(StateCommand.cpp:28、44)。这很关键:两个 slot 不同的 BindDescriptorSet 在状态栈上是两个不同的东西,不能被去重合并。

7.1.4 const 是谎言,但有用的谎言

record 的签名是 const,大量实现改了对象内部状态:

类被修改的成员手段
PipelineBarriercommandBuffer.scratchMemory(外部对象)不需要 mutable,只改参数
CopyAndReleaseImage_pending、_completed、_readyToClearmutable std::vector<CopyData>(include/vsg/commands/CopyAndReleaseImage.h:66)
ExecuteCommands_latch、_commandGraphsAndBuffers[i].cbmutable std::mutex(include/vsg/commands/ExecuteCommands.h:48)
Event::WaitEventscommandBuffer.scratchMemory同 PipelineBarrier

ExecuteCommands::record 是最不 const 的一个(src/vsg/commands/ExecuteCommands.cpp:68):

void ExecuteCommands::record(CommandBuffer& commandBuffer) const
{
    _latch->wait();

    std::scoped_lock lock(_mutex);
    std::vector<VkCommandBuffer> vk_commandBuffers;
    for (const auto& entry : _commandGraphsAndBuffers)
    {
        if (entry.cb) vk_commandBuffers.push_back(*entry.cb);
    }

    if (!vk_commandBuffers.empty())
    {
        vkCmdExecuteCommands(commandBuffer, static_cast<uint32_t>(vk_commandBuffers.size()), vk_commandBuffers.data());
    }
}

它做一件很重的事:_latch->wait() 阻塞录制线程,直到所有连进来的 SecondaryCommandGraph 都录完二级缓冲。这是全库唯一一处"在 record 里等别的线程"(7.7.3 展开)。

const 的语义不是"C++ 层面不可变",而是"这个对象在场景图里被视为不可变"。VSG 的所有遍历器都以 const 指针持有节点,record 必须是 const,否则 const Node* 上的虚调用链就断了。

这个谎言有三处实际代价:

  1. 线程安全靠约定,不靠类型。 两个线程同时 record 同一个 CopyAndReleaseImage 不会编译报错,只靠 _mutex 兜住;PipelineBarrier 没加锁,它只写 commandBuffer.scratchMemory——不同命令缓冲是两份 scratch,安全;同一命令缓冲被两个线程录就不安全。
  2. compare 覆盖不到运行时状态。 _pending 里的待拷贝项不属于"对象身份",却决定 record 行为。序列化一个"还有待拷贝项"的 CopyAndReleaseImage 会丢掉它们,反序列化后它什么都不做。
  3. compile 与 record 之间没有同步。 _vulkanData 是 std::vector,compile 上对 _vkDescriptorSets 做 resize(BindDescriptorSet.cpp:105),record 上 operator[](BindDescriptorSet.cpp:116)。CompileManager 保证编译结束后才开始录制(第六章 6.15),这是时序保证,不是同步保证。

7.2 Commands:为什么复数是一个 Command

7.2.1 一个反直觉的事实

vsg::Commands 本身是一个 Command,内部持有 Children 别名(std::vector<ref_ptr<Command>>,include/vsg/commands/Commands.h:48),构造函数的 numChildren 只是预留提示(Commands.h:32),同时有三个 traverse 重载分别对应 Visitor、ConstVisitor、RecordTraversal(Commands.h:34 的 t_traverse,:39–41 三个重写都只转交给它)。头文件注释把理由写在前面:

// include/vsg/commands/Commands.h:25-27
/// Commands is a command that acts as a container for other commands.
/// vsg::Commands is functionally equivalent to vsg::Group but is faster thanks to lower CPU overhead in applying
/// the state stack prior to vsg::Command calls.

"faster thanks to lower CPU overhead in applying the state stack" —— 这句话需要拆开验证。

7.2.2 两条路径的逐指令对比

Group 装 8 个 Draw:

Group::accept(rt)
  → apply(const Group&)                    // src/vsg/app/RecordTraversal.cpp:129
    → group.traverse(*this)
      → 8 × [ Draw::accept(rt)
              → apply(const Command&)      // 没有 apply(const Draw&)
                → state->record()          // :547
                → draw.record(cb) ]

Commands 装同样 8 个 Draw:

Commands::accept(rt)
  → apply(const Commands&)                 // src/vsg/app/RecordTraversal.cpp:531
    → state->record()                      // 只调一次,:535
    → 8 × [ draw->record(cb) ]             // 直接虚调用,不经过 accept

一个容易看漏的点:RecordTraversal 声明了 33 个 apply(include/vsg/app/RecordTraversal.h:116–166),头几个是 Group、quadGroup、LOD 这类组合节点(RecordTraversal.h:119、120、121),没有 apply(const Draw&)。Draw 系列走 apply(const Command&);有专门重载的只有 Geometry、VertexDraw、VertexIndexDraw、InstanceDraw、InstanceDrawIndexed(RecordTraversal.h:132–154)。

差异不在"少几次虚调用"(command->record() 与 command->accept() 都是一次虚跳转),而在两件事:

  1. state->record() 从 8 次变 1 次。dirty == false 时每次几个纳秒;dirty == true 时每次是 activeMaxStateSlot + 1 次槽位比较加可能的 vkCmd*。
  2. 少 8 次 GPU_INSTRUMENTATION_L3_NCO。该宏在 instrumentation == nullptr 时展开成判空分支,成本很低,但仍是 8 次分支加 8 个 apply 栈帧。

第 1 点是主要的。Commands 的真正价值是"把状态应用从 N 次压到 1 次",前提是这 N 个命令之间没有状态变化——这也正是它只能装 Command 不能装 StateGroup 的原因:Children 是 std::vector<ref_ptr<vsg::Command>>(Commands.h:49),类型系统直接堵死。

7.2.3 两份实现,两种行为

// src/vsg/commands/Commands.cpp:60-66
void Commands::record(CommandBuffer& commandBuffer) const
{
    for (auto& command : children)
    {
        command->record(commandBuffer);
    }
}
// src/vsg/app/RecordTraversal.cpp:531-540
void RecordTraversal::apply(const Commands& commands)
{
    GPU_INSTRUMENTATION_L3_NCO(instrumentation, *getCommandBuffer(), "Commands", COLOR_GPU, &commands);

    state->record();
    for (auto& command : commands.children)
    {
        command->record(*(state->_commandBuffer));
    }
}

第二份比第一份多一行 state->record(),带来两个后果。

其一,两条入口的状态语义不同。 走场景图(accept → apply)时状态被应用一次;直接调 commands->record(cb) 时状态完全不被应用。后者不是 bug:Context::record 就是这么用的,编译期的命令缓冲里没有 State 概念,只有 commands 循环与 bufferInfosToCopy / imageInfosToCopy 的一句"未实现"告警(src/vsg/vk/Context.cpp:323)。

其二,嵌套的 Commands 不会再次应用状态。

auto inner = vsg::Commands::create();
inner->addChild(drawA);
inner->addChild(drawB);

auto outer = vsg::Commands::create();
outer->addChild(inner);      // ref_ptr<Command> 装得下 Commands
outer->addChild(drawC);

外层 apply 调一次 state->record(),然后 inner->record(cb)(走 Commands::record,不再调 state->record()),再 drawC->record(cb)。三个 draw 只应用一次状态。

"所有 draw 共享同一状态"时这正确且更快,但它是隐式契约:Commands 假设"孩子都不改状态"。一旦某个孩子改了 CommandBuffer 的 _currentPipelineLayout,后续孩子就拿过期状态。唯一会改它的是 setCurrentPipelineLayout(src/vsg/vk/CommandBuffer.cpp:56),那里会 state->dirtyStateStacks() 标脏(CommandBuffer.cpp:62),但补救只发生在"下一次经过 RecordTraversal 的叶子"上;同一条 Commands::record 循环里的下一个孩子不经过 RecordTraversal,拿到的仍是旧状态。33 个内置命令类没有一个调 setCurrentPipelineLayout,所以这条漏洞在实践中不触发,但 Command 是公开可派生的,契约没有写进文档。

7.2.4 序列化与比较

// src/vsg/commands/Commands.cpp:38-43
void Commands::read(Input& input)
{
    Node::read(input);
    input.readObjects("children", children);
}

Node::read → Object::read(读 _objectID、mask 等),这条链上没有遗漏。compare 先比 Object::compare,再用 compare_pointer_container(children, rhs.children) 逐个比孩子指针(Commands.cpp:35)——比指针不比内容:两个内容相同但对象不同的 Draw 会让两个 Commands 判为不等。这是 Object::compare 的一贯语义(第二章讲过),不是本章的问题。

7.2.5 什么时候该用

场景推荐理由
一批共享同一 pipeline/descriptor 的 DrawCommands省 N-1 次 state->record()
一批需要各自 BindDescriptorSet 的 drawGroup + StateGroupCommands 装不下 StateCommand
一批纯传输命令(CopyImage、PipelineBarrier)Commands无状态,纯粹少一层 accept
需要在 draw 之间切 pipeline拆成多个 StateGroupCommands 不处理状态

CommandGraph 的继承是 CommandGraph : Inherit<Group, CommandGraph>(include/vsg/app/CommandGraph.h:27),不是 Commands。原因是它需要 addChild(ref_ptr<Node>)——RenderGraph、View 都是 Node 不是 Command。帧的边界是 Node 级的,不是 Command 级的(7.6 展开)。

7.2.6 compile:第二套递归

// src/vsg/commands/Commands.cpp:52-58
void Commands::compile(Context& context)
{
    for (auto& command : children)
    {
        command->compile(context);
    }
}

它直接遍历 children 调 compile,不走 accept。而 CompileTraversal 是 Visitor,通过 accept 调 apply(...) 重载;Compilable::compile(Context&) 是另一套接口(include/vsg/nodes/Compilable.h:29)。所以 Commands 有两条编译入口:作为 Node 被 CompileTraversal 访问,或作为容器被父节点的 compile 递归。两条都通向"孩子的 compile 被调用"。

compile 与 traverse 是两套并行递归,任何同时重写两者的类都必须覆盖同一批孩子。Commands 做到了(两个都遍历 children),Group 做到了(不重写 compile,全交给 apply)。StateGroup 需要单独检查,那是第八章的内容。

7.3 CommandBuffer:不只是 VkCommandBuffer 的壳

7.3.1 17 个成员,五类职责

CommandBuffer 有 17 个数据成员:10 个公开(include/vsg/vk/CommandBuffer.h:39–47、65),7 个受保护(CommandBuffer.h:73–80)。按职责分五类。

身份类(5 个):const uint32_t deviceID、VkCommandBuffer _commandBuffer、VkCommandBufferLevel _level、ref_ptr<Device> _device、ref_ptr<CommandPool> _commandPool。deviceID 是 const,构造时取 commandPool->getDevice()->deviceID(src/vsg/vk/CommandBuffer.cpp:26)——一个 CommandBuffer 永远属于一个设备。

遍历上下文类(8 个):viewID、traversalMask、overrideMask、viewDependentState、state、instanceNode、frameStamp、gpuStats(CommandBuffer.h:40–47)。它们描述"录制这一刻的上下文",不是"命令缓冲本身"。放这里的硬理由:Command::record(CommandBuffer&) 只能拿到 CommandBuffer,命令需要在 record 里知道当前 view 与 instance,这些信息只能挂在唯一参数上。

代价是 CommandBuffer 成了"什么都知道"的上下文对象。viewID 决定用哪套 pipeline,traversalMask 决定哪些节点被访问,frameStamp 供 PagedLOD 决定是否发请求。这是典型的上帝对象风险。

状态缓存类(2 个):VkPipelineLayout _currentPipelineLayout、VkShaderStageFlags _currentPushConstantStageFlags。它们是 State 的延伸,只被 MatrixStack::record 读:

// include/vsg/vk/State.h:158-176
inline void record(CommandBuffer& commandBuffer)
{
    if (dirty)
    {
        auto pipeline = commandBuffer.getCurrentPipelineLayout();
        auto stageFlags = commandBuffer.getCurrentPushConstantStageFlags();

        // don't attempt to push matrices if no pipeline is current or no stages are enabled for push constants
        if (pipeline == 0 || stageFlags == 0)
        {
            return;
        }

        // make sure matrix is a float matrix.
        mat4 newmatrix(matrixStack.top());
        vkCmdPushConstants(commandBuffer, pipeline, stageFlags, offset, sizeof(newmatrix), newmatrix.data());
        dirty = false;
    }
}

return 而不是 dirty = false:没有 pipeline 时保持脏,下一帧再试。所以 dirty 的语义是"未完成"而不是"已变更"。副作用是:从不设 push constant layout 的场景,modelviewMatrixStack.dirty 永远为 true,每次 state->record() 都走两遍比较。成本可忽略,语义值得记住。

内存类(1 个):ref_ptr<ScratchMemory> scratchMemory,构造时 ScratchMemory::create(4096)(src/vsg/vk/CommandBuffer.cpp:27)。只被 PipelineBarrier、WaitEvents、SampleLocations 使用。

依赖计数类(1 个):std::atomic_uint _numDependentSubmissions{0}(CommandBuffer.h:76)。名字很准:不是引用计数,是"还有多少次提交在用我"。

7.3.2 reset() 的两条路径不一致

// src/vsg/vk/CommandBuffer.cpp:45-54
void CommandBuffer::reset(VkCommandBufferResetFlags flags)
{
    _currentPipelineLayout = VK_NULL_HANDLE;
    _currentPushConstantStageFlags = 0;

    if ((_commandPool->flags & VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT) != 0)
    {
        vkResetCommandBuffer(_commandBuffer, flags);
    }
}

逻辑是:无条件清 CPU 侧两个缓存,有条件才真正 vkResetCommandBuffer。若池没带这个 flag:

  • CPU 侧认为"当前没有 pipeline layout",下一次 setCurrentPipelineLayout 会 dirtyStateStacks() 并重新绑定。
  • GPU 侧命令缓冲仍是上一帧的状态(Executable,不能重新 vkBeginCommandBuffer)。

结果是 CommandGraph::record 会在 Executable 缓冲上调 vkBeginCommandBuffer,规范上返回 VK_NOT_READY,而 VSG 不检查返回值(7.4 展开)。驱动行为未定义:有的隐式重置,有的静默失败并让后续 vkCmd* 全部丢失。

这个场景在标准流程里不会发生,因为 CommandGraph::record 建池时总带 flag(src/vsg/app/CommandGraph.cpp:106)。但 CommandPool 是公开 API,用户可以直接 CommandPool::create(device, family, 0) 再 allocate() 再 reset(),此时 reset() 静默什么都不做,而 CPU 缓存已经被清了。这是"防御性代码写了一半":reset 知道可能没有 flag,所以加了条件;它忘了在没有 flag 时该报警,而不是静默地只清一半。

顺带一个更细的顺序问题:_commandPool 是 ref_ptr<CommandPool>,CommandPool::free(this) 在 ~CommandBuffer() 体内调用(CommandBuffer.cpp:41),此时 _commandPool 的引用计数还没减(函数体先于成员析构),池一定存活。如果池先被用户 cp.reset(),CommandBuffer 的 _commandPool 会保住它,free 依然安全。这是 ref_ptr 的正确用法。

7.3.3 setCurrentPipelineLayout 的三件事

// src/vsg/vk/CommandBuffer.cpp:56-70
void CommandBuffer::setCurrentPipelineLayout(const PipelineLayout* pipelineLayout)
{
    VkPipelineLayout newLayout = pipelineLayout->vk(deviceID);
    if (_currentPipelineLayout != newLayout)
    {
        // have to assume that all DescriptorSets will need to be rebound.
        state->dirtyStateStacks();

        _currentPipelineLayout = newLayout;
        if (pipelineLayout->pushConstantRanges.empty())
            _currentPushConstantStageFlags = 0;
        else
            _currentPushConstantStageFlags = pipelineLayout->pushConstantRanges.front().stageFlags;
    }
}

第一件:发现布局变化。 比较的是 newLayout 句柄,不是 PipelineLayout* 对象指针。两个内容相同的 PipelineLayout 对象可能编译出两个不同句柄(PipelineLayout::compile 不去重),句柄比较会认为"变了"并重新绑定;同一个对象在两个设备上有两个句柄,句柄比较同样正确。

第二件:标脏状态栈。 注释写得很清楚:换布局意味着 set 编号的语义可能全变,所有 descriptor set 绑定作废。

第三件:推导 push constant stage flags。 这里有个真问题:只取 pushConstantRanges.front() 的 stageFlags(CommandBuffer.cpp:68)。如果布局有两个 range——顶点段 offset 0 长 64、片元段 offset 64 长 16——_currentPushConstantStageFlags 只有顶点位,MatrixStack::record 发往 offset 64 的 64 字节就会在片元段无效。

更麻烦的是 offset:MatrixStack 的 offset 是构造时传的固定值,projectionMatrixStack{0}、modelviewMatrixStack{64}(include/vsg/vk/State.h:289、290)。它硬编码了"projection 在 0,modelview 在 64",只在"所有 range 都覆盖顶点阶段且 offset 恰好是 0/64"时正确。这在 VSG 自己的 ShaderSet 生成的布局里成立,但没有文档、没有断言、没有运行时检查;自定义 shader 把 modelview 放到 offset 128,矩阵就写错位置。

7.3.4 numDependentSubmissions 的完整生命周期

// src/vsg/app/CommandGraph.cpp:116
commandBuffer->numDependentSubmissions().fetch_add(1);

// src/vsg/app/CommandGraph.cpp:98
if (cb->numDependentSubmissions() == 0) { commandBuffer = cb; break; }

// src/vsg/vk/Fence.cpp:49
commandBuffer->numDependentSubmissions().exchange(0);

加:每次 record 复用或新建缓冲时 +1。查:找空闲缓冲时判 0(SecondaryCommandGraph.cpp:95 同款)。清:Fence::resetFenceAndDependencies() 里 exchange(0)(Fence.cpp:47 遍历 _dependentCommandBuffers)。调用者是提交侧的等待逻辑:每次提交前 fence->wait(),完成后 resetFenceAndDependencies()。语义是"一个 CommandBuffer 被提交了多少次但还没确认完成"。

+1 而永不 -1 是设计的一部分:不需要精确递减,只要在这批提交全部完成时归零。用 exchange(0) 而不是 fetch_sub,是因为一个 Fence 可能关联多个命令缓冲,逐个减容易漏;清零错过一次的代价是"多分配一个缓冲",而不是"复用了还在飞的缓冲"。

副作用:GPU 永不完成(设备丢失)时计数器不归零,_commandBuffers 无限增长,每帧新建一个 CommandPool + CommandBuffer,直到 vkAllocateCommandBuffers 返回 VK_ERROR_OUT_OF_DEVICE_MEMORY(CommandPool.cpp:54 抛异常,这是罕见的"正确行为")。

7.4 录制状态机:Vulkan 规定四个状态,VSG 检查零个

7.4.1 四个状态

状态进入方式允许的操作
InitialvkAllocateCommandBuffers 之后vkBeginCommandBuffer
RecordingvkBeginCommandBuffer 成功后vkCmd*、vkEndCommandBuffer
ExecutablevkEndCommandBuffer 成功后提交、作为二级被 vkCmdExecuteCommands、vkResetCommandBuffer
Invalid任何一步失败vkResetCommandBuffer

合法转换只有四条:

Initial    --vkBeginCommandBuffer--> Recording
Recording  --vkEndCommandBuffer----> Executable
Executable --vkResetCommandBuffer--> Initial
Recording  --vkResetCommandBuffer--> Initial

非法转换的关键三条:Executable --begin--> 返回 VK_NOT_READY;Executable --vkCmd*--> 未定义(validation 报 VUID-vkCmdDraw-commandBuffer-00046);Initial --end--> 返回 VK_NOT_READY。

7.4.2 VSG 的隐式状态机

CommandGraph::record 里与状态转换相关的全部代码:

// src/vsg/app/CommandGraph.cpp:125-139
VkCommandBufferBeginInfo beginInfo = {};
beginInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
beginInfo.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
beginInfo.pInheritanceInfo = nullptr;

vkBeginCommandBuffer(vk_commandBuffer, &beginInfo);

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

vkEndCommandBuffer(vk_commandBuffer);

recordedCommandBuffers->add(submitOrder, commandBuffer);

两个返回值都被丢弃,函数返回 void,没有错误路径。SecondaryCommandGraph::record 同样(src/vsg/app/SecondaryCommandGraph.cpp:152、156),Context::record 同样(src/vsg/vk/Context.cpp:314、342),TransferTask::record 同样(src/vsg/app/TransferTask.cpp:498、509)。

全库 vkBeginCommandBuffer 共 4 处调用,返回值检查 0 处。 这不是疏忽,是统一风格。

7.4.3 状态机靠"分配策略"维护

既然不检查,正确性只能靠"永远不做非法转换"。VSG 靠四条不变量:

  1. 新缓冲一定是 Initial——CommandPool::allocate 刚 vkAllocateCommandBuffers 出来(src/vsg/vk/CommandPool.cpp:54)。
  2. 复用缓冲一定先 reset()——CommandGraph.cpp:112 的 commandBuffer->reset()。
  3. reset() 一定成功——因为池带 RESET_COMMAND_BUFFER_BIT。
  4. 每个缓冲每帧只 begin/end 一次——record 是线性代码,没有分支能跳到第二次 begin。

四条合起来把状态机压成一条直线,代价是任何一条被破坏,错误都是静默的:

场景 A:池没带 RESET_COMMAND_BUFFER_BIT。 reset() 不动 GPU 状态,缓冲停在 Executable,vkBeginCommandBuffer 返回 VK_NOT_READY,后续 vkCmd* 无效(VUID-vkBeginCommandBuffer-commandBuffer-00049)。画面表现:上一帧内容被重复提交,或黑屏。

场景 B:traverse 抛异常。 Command::record 里的 vkCmd* 不抛,但 ExecuteCommands::record 的 std::vector::push_back 可能抛 std::bad_alloc。一旦抛出,vkEndCommandBuffer 不执行,缓冲停在 Recording;下一帧 reset() 拉回 Initial,只丢一帧。异常持续(比如持续 OOM)就每帧都丢。

场景 C:recordedCommandBuffers 为空。 RecordTraversal::apply(const CommandGraph&) 里判空后走 else(src/vsg/app/RecordTraversal.cpp:697):CommandGraph 被当普通 Group 遍历,孩子 RenderGraph::accept 直接 vkCmdBeginRenderPass(src/vsg/app/RenderGraph.cpp:150)——此时没有 vkBeginCommandBuffer,等于在 Initial 缓冲上录 render pass。标准 Viewer 流程不会走到,因为 CommandGraph::record 自己设置了 recordTraversal->recordedCommandBuffers(CommandGraph.cpp:89);只有把 RecordTraversal 当"纯遍历器"复用时才会。

7.4.5 beginInfo.flags 的三种取值

flag用在哪含义
ONE_TIME_SUBMIT_BITCommandGraph::record(CommandGraph.cpp:127)、Context::record(Context.cpp:312)这个缓冲只被提交一次,之后会 reset
RENDER_PASS_CONTINUE_BITSecondaryCommandGraph::record(SecondaryCommandGraph.cpp:124)二级缓冲在 render pass 内部执行
SIMULTANEOUS_USE_BITSecondaryCommandGraph::record(条件)缓冲可能被同时提交多次

ONE_TIME_SUBMIT_BIT 不是"只能用一次"的硬约束,而是给驱动的优化提示:驱动可以假设它在下次 vkResetCommandBuffer 之前只被提交一次,从而不做重复提交的额外簿记。VSG 用它的前提是每次 record 都 reset()(复用)或新建(分配)——跨帧复用同一缓冲是允许的,因为每次复用前都 reset() 了,约束是"一次 submit 周期内"而不是"缓冲生命周期内"。

SIMULTANEOUS_USE_BIT 的条件是连接数:

// src/vsg/app/SecondaryCommandGraph.cpp:124-125
beginInfo.flags = VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT;
if (_executeCommands.size() > 1) beginInfo.flags |= VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT;

判断的是"有多少个 ExecuteCommands 节点连到我",因为每个 ExecuteCommands::record 都会 vkCmdExecuteCommands 一次。只有一个连接时缓冲只被引用一次,不需要 SIMULTANEOUS_USE。

但规范的真正要求是"同一二级缓冲被同一主缓冲引用多次,或被多个主缓冲同时引用"。两个 CommandGraph(两个窗口)共享一个 SecondaryCommandGraph 时 _executeCommands.size() == 2,flag 设上,正确。反过来,同一个 ExecuteCommands 节点被放进两个不同的 StateGroup(场景图里访问两次)时 size() 还是 1,但 vkCmdExecuteCommands 会被调两次——flag 没设,非法。条件是"连接的节点数",不是"被执行的次数",而后者在录制时才知道,beginInfo 必须在录制前填好。

7.4.6 二级缓冲的状态机更脆弱

二级缓冲多一个状态:必须在主缓冲的 render pass 内被执行。三条额外约束:pInheritanceInfo->renderPass 必须与执行时的 render pass 兼容;subpass 必须匹配;RENDER_PASS_CONTINUE_BIT 必须设,否则 validation 报错。SecondaryCommandGraph::record 填了这三样:

// src/vsg/app/SecondaryCommandGraph.cpp:127-150
VkCommandBufferInheritanceInfo inheritanceInfo;
inheritanceInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO;
inheritanceInfo.pNext = nullptr;
inheritanceInfo.occlusionQueryEnable = occlusionQueryEnable;
inheritanceInfo.queryFlags = queryFlags;
inheritanceInfo.pipelineStatistics = pipelineStatistics;
beginInfo.pInheritanceInfo = &inheritanceInfo;

if (const auto activeRenderPass = getRenderPass())
    inheritanceInfo.renderPass = *(activeRenderPass);
else
    inheritanceInfo.renderPass = VK_NULL_HANDLE;

inheritanceInfo.subpass = subpass;

if (framebuffer)
{
    inheritanceInfo.framebuffer = *framebuffer;
}
else if (window)
{
    //inheritanceInfo.framebuffer = *(window->framebuffer(window->nextImageIndex()));
    inheritanceInfo.framebuffer = VK_NULL_HANDLE;
}

7.4.7 inheritanceInfo 的三个问题

问题一:结构体没有零初始化。 同一函数里 beginInfo 是 = {}(SecondaryCommandGraph.cpp:122),inheritanceInfo 是裸声明(SecondaryCommandGraph.cpp:127)。逐字段赋值覆盖了 sType、pNext、occlusionQueryEnable、queryFlags、pipelineStatistics、renderPass(两分支)、subpass、framebuffer(两分支)——Vulkan 1.0 的该结构正好 8 个字段,除了 framebuffer 的第三个分支。

用 SecondaryCommandGraph(ref_ptr<Device>, int family) 构造时(SecondaryCommandGraph.cpp:24 framebuffer 与 window 都空,两个分支都不进,framebuffer 保持未初始化栈值。一个随机 VkFramebuffer 句柄被传给驱动:validation 报 "framebuffer must be VK_NULL_HANDLE",若值非零,驱动可能访问野指针。

问题二:renderPass 与 framebuffer 的一致性。 规范要求两者同为有效或同为 VK_NULL_HANDLE(1.1 起 VK_KHR_imageless_framebuffer 才允许 renderPass 有效而 framebuffer 为空)。window 分支恰好产生"有效 + 空"的组合(SecondaryCommandGraph.cpp:136 与 149)。被注释掉的那行(SecondaryCommandGraph.cpp:148)说明作者意图:用"下一个要用的 image 的 framebuffer"。问题是录制时无法知道执行时用哪个 framebuffer——image index 在 vkAcquireNextImageKHR 时才确定,而它发生在提交之前、录制之后,甚至可能在另一个线程。

所以 VSG 选 VK_NULL_HANDLE。这在 1.1 + VK_KHR_imageless_framebuffer(或 1.2 核心)下合法,但要求 VkPhysicalDeviceImagelessFramebufferFeatures::imagelessFramebuffer == VK_TRUE。VSG 没有启用它:DeviceFeatures.cpp 里没有 imagelessFramebuffer。也就是说这个组合依赖"驱动宽容",严格实现或开了同步验证的 layer 上会被报错。

问题三:subpass 的默认值。 subpass 是成员,默认 0(include/vsg/app/SecondaryCommandGraph.h:30)。getRenderPass() 三个分支(SecondaryCommandGraph.cpp:60):renderPass、framebuffer->getRenderPass()、window->getOrCreateRenderPass(),三者都没有时返回 nullptr。此时 renderPass = VK_NULL_HANDLE,subpass 用的是成员值;用户构造时传 in_subpass = 2 就是"renderPass 为空但 subpass 为 2",违反规范。更麻烦的是 getRenderPass() 的 window 分支会调 getOrCreateRenderPass()(SecondaryCommandGraph.cpp:72)——在录制路径上做可能的重资源分配,vkCreateRenderPass 通常要几十微秒。

7.5 CommandPool:75 行与一个致命的分配策略

7.5.1 三个公开方法

CommandPool 的公开面只有三样:reset(VkCommandPoolResetFlags)(include/vsg/vk/CommandPool.h:35)、allocate(VkCommandBufferLevel)(CommandPool.h:38)、getDevice()(CommandPool.h:40);free 是受保护的,只对 CommandBuffer 开放(CommandPool.h:46、49)。

构造时创建池,失败直接抛:

// src/vsg/vk/CommandPool.cpp:19-34
CommandPool::CommandPool(Device* device, uint32_t in_queueFamilyIndex, VkCommandPoolCreateFlags in_flags) :
    queueFamilyIndex(in_queueFamilyIndex),
    flags(in_flags),
    _device(device)
{
    VkCommandPoolCreateInfo poolInfo = {};
    poolInfo.sType = VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO;
    poolInfo.queueFamilyIndex = queueFamilyIndex;
    poolInfo.flags = flags;
    poolInfo.pNext = nullptr;

    if (VkResult result = vkCreateCommandPool(*device, &poolInfo, _device->getAllocationCallbacks(), &_commandPool); result != VK_SUCCESS)
    {
        throw Exception{"Error: Failed to create command pool.", result};
    }
}

allocate 每次只分配一个:allocateInfo.commandBufferCount = 1(CommandPool.cpp:50)。vkAllocateCommandBuffers 支持一次分配 N 个,批量在驱动内部通常更快(一次分配、一次元数据初始化)。VSG 选 1,因为分配是按需的——CommandGraph::record 发现没有空闲缓冲才分配一个。批量化需要预先知道峰值帧数,而那取决于 swapchain 的 image 数量(通常 2–3),不确定性太大。

7.5.2 每个 CommandBuffer 一个 CommandPool

看 CommandGraph::record 的分配分支:

// src/vsg/app/CommandGraph.cpp:104-113
if (!commandBuffer)
{
    ref_ptr<CommandPool> cp = CommandPool::create(device, queueFamily, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT);
    commandBuffer = cp->allocate(level());
    _commandBuffers.push_back(commandBuffer);
}
else
{
    commandBuffer->reset();
}

cp 是局部变量,函数结束时引用计数降到 0,但 commandBuffer 的 _commandPool 成员持有 ref_ptr<CommandPool>(include/vsg/vk/CommandBuffer.h:78),池被缓冲保住。结论:每个 CommandBuffer 独占一个 CommandPool。CommandGraph.h:59 的注释也承认了:

// include/vsg/app/CommandGraph.h:59
CommandBuffers _commandBuffers; // assign one per index? Or just use round robin, each has a CommandPool

这是一个 TODO,也是明确的"我知道这样不理想"。

7.5.4 RESET_COMMAND_BUFFER_BIT 为什么必须设

Vulkan 有两种重置方式:池级 vkResetCommandPool(pool, 0) 重置池里所有缓冲,不需要额外 flag;缓冲级 vkResetCommandBuffer(cb, 0) 重置单个缓冲,必须池带 VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT。

VSG 用第二种,因为它要"复用某一个空闲缓冲"而不是"重置整个池"。这要求池带 flag,CommandGraph::record 每次都带(CommandGraph.cpp:106)。不带就会掉进 7.4.3 的场景 A:CommandBuffer::reset 里的条件不成立(CommandBuffer.cpp:50),vkResetCommandBuffer 不执行,缓冲停在 Executable,下一次 vkBeginCommandBuffer 返回 VK_NOT_READY。

隐含代价:带这个 flag 会让驱动不能在池级别做整池优化。某些驱动在池不带 flag 时用更紧凑的分配方式(知道整个池会一起重置);带上之后每个缓冲都要独立可重置,驱动必须保留每个缓冲的独立状态。这个代价在 VSG 里不可避免——它需要"挑一个空闲的重置",不是"重置全部"。

7.5.5 free 的时机与幂等

// src/vsg/vk/CommandBuffer.cpp:37-43
CommandBuffer::~CommandBuffer()
{
    if (_commandBuffer)
    {
        _commandPool->free(this);
    }
}

free 做两件事:vkFreeCommandBuffers 加把 _commandBuffer 置 0(src/vsg/vk/CommandPool.cpp:62)。~CommandBuffer 里的 if (_commandBuffer) 让它幂等:free 已经把 commandBuffer->_commandBuffer 置 0,第二次调用会跳过。这是正确的设计。

CommandPool::free 里没有检查"这个缓冲是不是我的"(CommandPool.cpp:64)。把 A 池分配的缓冲传给 B 池的 free,vkFreeCommandBuffers 拿到的是 B 池句柄 + A 池缓冲句柄,规范要求缓冲必须属于该池(VUID-vkFreeCommandBuffers-commandPool-00057),validation 报错,驱动行为未定义(可能什么都不做,可能破坏内部链表)。

CommandPool 不记录自己分配过哪些缓冲,所以无法检查。这个取舍可以接受——free 是析构路径,而且它是 protected 加 friend CommandBuffer(CommandPool.h:46),普通用户拿不到;原文说它"public、可被误用"在 1.1.16 里不成立,但这恰恰说明防护是靠访问控制而不是靠检查:任何新增的 friend 都会让这条路径重新暴露。

7.5.6 reset 的 const 与线程安全

// src/vsg/vk/CommandPool.cpp:72-75
void CommandPool::reset(VkCommandPoolResetFlags reset_flags) const
{
    vkResetCommandPool(*_device, _commandPool, reset_flags);
}

const 方法,没有加锁;而 allocate 在 allocateInfo 填好之后、free 在判空之后,都加了 std::scoped_lock<std::mutex> lock(_mutex)(CommandPool.cpp:52、66)。vkResetCommandPool 会让池里所有缓冲失效,比 allocate 危险得多,却既不 const-correct(逻辑上修改对象状态)也不线程安全。

谁调用它?在 src/vsg/ 下搜不到调用者。这是一个纯 API 表面的方法,为外部用户准备。它的 const 让它可以被 const CommandPool* 调用,而内部的 vkResetCommandPool 会改设备状态——典型的"const 不等于线程安全"。

7.6 CommandGraph:帧的边界

7.6.1 类定义

// include/vsg/app/CommandGraph.h:27-60
class VSG_DECLSPEC CommandGraph : public Inherit<Group, CommandGraph>
{
public:
    CommandGraph();
    CommandGraph(ref_ptr<Device> in_device, int family);
    explicit CommandGraph(ref_ptr<Window> in_window, ref_ptr<Node> child = {});

    ref_ptr<Framebuffer> framebuffer;
    ref_ptr<Window> window;
    ref_ptr<Device> device;

    int queueFamily = -1;
    int presentFamily = -1;
    int submitOrder = 0;
    Slots maxSlots;

    ref_ptr<RecordTraversal> getOrCreateRecordTraversal();

    ref_ptr<RecordTraversal> recordTraversal;

    virtual VkCommandBufferLevel level() const;
    virtual void reset();
    virtual void record(ref_ptr<RecordedCommandBuffers> recordedCommandBuffers, ref_ptr<FrameStamp> frameStamp = {}, ref_ptr<DatabasePager> databasePager = {});

    /// hook for assigning Instrumentation to enable profiling of record traversal.
    ref_ptr<Instrumentation> instrumentation;

protected:
    ~CommandGraph() override;

    CommandBuffers _commandBuffers; // assign one per index? Or just use round robin, each has a CommandPool
};

9 个公开数据成员,3 个虚函数。继承 Group 是关键:CommandGraph 可以挂任意 Node 孩子,包括 RenderGraph(一个封装 vkCmdBeginRenderPass 的 Group)。

level()、reset()、record() 是虚函数,SecondaryCommandGraph 重写全部三个(include/vsg/app/SecondaryCommandGraph.h:41–43)。这是模板方法模式的变体:基类定义"帧"的骨架,子类替换"缓冲级别"与"录制细节"。

reset() 在基类里是空的(src/vsg/app/CommandGraph.cpp:61),紧随其后的 getOrCreateRecordTraversal()(:65)才有实体;只有子类重写 reset:

// src/vsg/app/SecondaryCommandGraph.cpp:44-47
void SecondaryCommandGraph::reset()
{
    for (auto& ec : _executeCommands) ec->reset();
}

这个空实现不是疏忽。基类的"重置"发生在 record() 内部(commandBuffer->reset()),不需要外部钩子;子类的"重置"要额外做一件事——重置所有 ExecuteCommands 的 latch。这个不对称说明 reset() 的语义其实是"帧开始时通知",不是"重置资源"。

Viewer::recordAndSubmit 就是按这个语义调的:

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

先 reset 所有图(让 ExecuteCommands 的 latch 就位),再并行 submit。顺序很重要:如果 reset 在 submit 之后,ExecuteCommands::record 的 _latch->wait() 会等到一个已经计完的 latch(立即返回),拿到上一帧的二级缓冲。

7.6.2 三个构造函数

默认构造全空:device 是空 ref_ptr,queueFamily 是 -1(CommandGraph.cpp:24)。它存在的唯一理由是 read()——反序列化时先默认构造再读字段。

CommandGraph(device, family) 直接指定设备与队列族,没有窗口(CommandGraph.cpp:29)。用于离屏渲染或传输队列。

CommandGraph(window, child) 最常用,从窗口推导一切:

// src/vsg/app/CommandGraph.cpp:37-49
CommandGraph::CommandGraph(ref_ptr<Window> in_window, ref_ptr<Node> child) :
    window(in_window),
    device(in_window->getOrCreateDevice())
{
    CPU_INSTRUMENTATION_L1(instrumentation);

    VkQueueFlags queueFlags = VK_QUEUE_GRAPHICS_BIT;
    if (window->traits()) queueFlags = window->traits()->queueFlags;

    std::tie(queueFamily, presentFamily) = device->getPhysicalDevice()->getQueueFamily(queueFlags, window->getOrCreateSurface());

    if (child) addChild(child);
}

device(in_window->getOrCreateDevice()) 在初始化列表里,先于函数体执行——构造 CommandGraph 会触发 Window 创建 Device。所以 CommandGraph::create(window) 不是轻量对象创建,它可能触发一整套 Vulkan 对象装配(第六章 6.2 那 118 行)。

getQueueFamily(queueFlags, surface) 返回 (queueFamily, presentFamily)。第六章 6.7 讲过"精确匹配优先 + TRANSFER→GRAPHICS 回退",这里补一点:返回值没有检查。返回 (-1, -1) 时 CommandGraph 会带着 queueFamily = -1 继续存在,直到 CommandPool::create(device, -1, ...) 让 vkCreateCommandPool 返回 VK_ERROR_INITIALIZATION_FAILED(或者更糟,创建一个无法提交的池)。

7.6.3 record() 的五个阶段

record 从 76 行到 140 行,可以切成 5 段。

阶段 1:可见性与上下文(第 80–93 行)

// src/vsg/app/CommandGraph.cpp:80-93
if (window && !window->visible())
{
    //vsg::info("CommandGraph::record() ", frameStamp->frameCount, " window not visible.");
    return;
}

// create the RecordTraversal if it isn't already created
getOrCreateRecordTraversal();

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

getOrCreateRecordTraversal() 里藏着 maxSlots → State::reserve 的整条链(7.9.4),是本章第三重要的隐式契约。clearBins() 与 apply(const View&) 里的 bin->clear() 重复,但 Bin::clear() 只是把 _matrices、_stateCommands、_elements、_binElements 四个容器清空(src/vsg/nodes/Bin.cpp:52),幂等,无害。

阶段 2:挑一个空闲缓冲(第 95–103 行)

// src/vsg/app/CommandGraph.cpp:95-103
ref_ptr<CommandBuffer> commandBuffer;
for (auto& cb : _commandBuffers)
{
    if (cb->numDependentSubmissions() == 0)
    {
        commandBuffer = cb;
        break;
    }
}

线性扫描取第一个空闲项。_commandBuffers 按分配顺序排列,所以这倾向复用最早分配的缓冲,对缓存友好。但"第一个空闲"不等于"最久没用":缓冲 0 每帧都能及时归还就永远被复用,缓冲 1、2 永远闲置。GPU 有余量时这是优点(活跃缓冲数最少),GPU 是瓶颈时退化成"每帧换一个缓冲"。

阶段 3:分配或重置(第 104–113 行):见 7.5.2 的摘录。level() 是虚函数(CommandGraph.cpp:56),二级图在这一行分配二级缓冲。池在这里创建而不是构造函数里,意味着"从未渲染过的 CommandGraph 不持池"——延迟分配,代价是首帧多 50–200 μs。

阶段 4:绑定上下文(第 115–118 行)

// src/vsg/app/CommandGraph.cpp:115-118
commandBuffer->frameStamp = frameStamp;
commandBuffer->numDependentSubmissions().fetch_add(1);

recordTraversal->getState()->connect(commandBuffer);

frameStamp 挂在命令缓冲上,因为 Command::record 只能拿到 CommandBuffer(PagedLOD 的加载决策需要帧号)。connect 会 dirtyStateStacks()(src/vsg/vk/State.cpp:50)——每帧的"忘记已绑定状态"。

阶段 5:begin / traverse / end(第 121–139 行):摘录见 7.4.2。CommandGraph 没有重写 traverse,走 Group::t_traverse 逐个 accept。记录逻辑全在 record 里,traverse 只把控制权交给孩子。

7.6.4 traverse 与 record 的关系

  • record() 创建或复用一个 VkCommandBuffer,begin,调 traverse(),再 end。
  • traverse() 把 RecordTraversal 传给每个孩子。

所以在 CommandGraph 这一层,record 是外壳,traverse 是内容。到 RenderGraph 就反过来了:RenderGraph::accept(RecordTraversal&) 直接 vkCmdBeginRenderPass 再 traverse,没有单独的 record(src/vsg/app/RenderGraph.cpp:105)。

为什么 CommandGraph 需要 record 而不是 accept 重载?因为它需要一个把 CommandBuffer 交给外部的钩子——recordedCommandBuffers->add(...) 必须在能拿到 commandBuffer 的地方执行。放在 accept 里,RecordTraversal 就得知道"当前是哪个图"。

7.6.5 submitOrder 与三路合并

RecordedCommandBuffers 按 submitOrder 分桶(include/vsg/vk/CommandBuffer.h:101):

// src/vsg/vk/CommandBuffer.cpp:94-101
void RecordedCommandBuffers::add(int submitOrder, ref_ptr<vsg::CommandBuffer> commandBuffer)
{
    std::scoped_lock<std::mutex> lock(_mutex);
    if (submitOrder == 0)
        _commandBuffers.push_back(commandBuffer);
    else
        getOrCreateRecordedCommandBuffers(submitOrder)->_commandBuffers.push_back(commandBuffer);
}

submitOrder == 0 走快路径,非 0 走 map——常见情况优化,绝大多数 CommandGraph 用默认值 0。

buffers() 把三部分拼成一个序列(CommandBuffer.cpp:109):

// src/vsg/vk/CommandBuffer.cpp:115-130
auto mid_itr = _orderedCommandBuffers.lower_bound(0);

CommandBuffers buffers;
for (auto itr = _orderedCommandBuffers.begin(); itr != mid_itr; ++itr)   // 负 key 先出
{
    auto nested_buffers = itr->second->buffers();
    buffers.insert(buffers.end(), nested_buffers.begin(), nested_buffers.end());
}

buffers.insert(buffers.end(), _commandBuffers.begin(), _commandBuffers.end());  // 0 在中间

for (auto itr = mid_itr; itr != _orderedCommandBuffers.end(); ++itr)     // 正 key 后出
{
    auto nested_buffers = itr->second->buffers();
    buffers.insert(buffers.end(), nested_buffers.begin(), nested_buffers.end());
}

lower_bound(0) 找第一个 >= 0 的 key,所以 [begin, mid) 是负区间,结果是"负数 → 0 → 正数"。实际用途:某些缓冲必须在主渲染之前提交(传输队列的上传),某些必须在之后(present 同步)。submitOrder 给了用户一个"不改代码结构就改提交顺序"的旋钮,但它只影响同一个 RecordedCommandBuffers 里的顺序,跨 RecordAndSubmitTask 的顺序由 Viewer 的循环决定。

buffers() 递归调用每个桶的 buffers(),理论上可以无限嵌套;但 add 只在顶层用 getOrCreateRecordedCommandBuffers,嵌套层要直接操作 _orderedCommandBuffers,而那是 protected。实际只有一层。

7.6.6 锁的边界

RecordedCommandBuffers 的 _mutex 保护 _commandBuffers 与 _orderedCommandBuffers,add、clear、empty、buffers 都加锁。但 getOrCreateRecordedCommandBuffers 不加锁:

// src/vsg/vk/CommandBuffer.cpp:87-92
ref_ptr<RecordedCommandBuffers> RecordedCommandBuffers::getOrCreateRecordedCommandBuffers(int submitOrder)
{
    auto& scb = _orderedCommandBuffers[submitOrder];
    if (!scb) scb = RecordedCommandBuffers::create();
    return scb;
}

这是"为内部调用优化而牺牲公开 API 安全性"的典型。正确做法是拆成两个:private 无锁版给 add 用,public 加锁版给外部用。VSG 选了一个方法两种用途。

7.6.8 RenderGraph:唯一在 accept 里发 vkCmd* 的节点

RenderGraph 不重写 record(它不是 Command),而是重写 accept:

// src/vsg/app/RenderGraph.cpp:109-150
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();
}

VkRenderPassBeginInfo renderPassInfo = {};
renderPassInfo.sType = VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO;
...
recordTraversal.getState()->viewportStateHint = viewportStateHint;

VkCommandBuffer vk_commandBuffer = *(recordTraversal.getState()->_commandBuffer);
vkCmdBeginRenderPass(vk_command_buffer, &renderPassInfo, contents);

观察 1:窗口尺寸变化在录制路径上处理。 previous_extent 与当前 extent 的比较在 accept 里,变化时调 resized()(RenderGraph.cpp:117)。resized() 重建 Framebuffer、更新 clearValues、调 WindowResizeHandler(RenderGraph.cpp:173),全是重活——拖窗口的某一帧会比其他帧慢几十毫秒。if (imageIndex >= window->numFrames()) return(RenderGraph.cpp:131)只处理"swapchain 还没重建完",不处理重建本身的开销。

观察 2:viewportState 被 push 了两次。 apply(const View&) 里 state->pushView(view) 压入 view.camera->viewportState(slot 8,RecordTraversal.cpp:608);view.traverse 到达 RenderGraph 后,RenderGraph::accept 又 pushView(viewportState)(RenderGraph.cpp:157)。slot 8 上有两个 ViewportState:栈底是相机的(覆盖整个视口),栈顶是 RenderGraph 的(覆盖 renderArea)。StateStack::record 读 stack[pos] 即栈顶,所以实际生效的是 renderArea 那个。这是对的设计:一个 view 可以渲染到窗口的一部分(分屏)。代价是一个 View 里有 N 个 RenderGraph 时 slot 8 被 push/pop N 次,每次 record() 都认为 viewport 变了并重发 vkCmdSetViewport 加 vkCmdSetScissor。

观察 3:viewportStateHint 写进 State 且不恢复。 RenderGraph.cpp:147 直接赋值,函数结束不还原。State::pushView(const View&) 会检查 (viewportStateHint & DYNAMIC_VIEWPORTSTATE)(src/vsg/vk/State.cpp:68)。第一个 RenderGraph 设 DYNAMIC、第二个设 STATIC,后续所有 view 的 pushView 都不再压 viewportState——跨 RenderGraph 的状态泄漏,画面表现为"分屏第一块正确,后面全错"。

观察 4:viewportState->set(...) 无条件调用(RenderGraph.cpp:153)。即使 viewportStateHint 是 STATIC(viewport 由 pipeline 静态状态决定),accept 也改 ViewportState::viewports;由于不 push,这些修改不会被录制。如果这个 ViewportState 同时被某个 GraphicsPipeline 引用,set 会改正在被 pipeline 使用的静态 viewport,下一次 pipeline 重建就用新值——resize 时重建 pipeline 是期望行为,resize 但没重建就是静默错误。

观察 5:window->imageIndex() 在录制时读取(RenderGraph.cpp:130)。imageIndex 是上一帧 acquire 到的索引,用它填 framebuffer 是正确的(这一帧要渲染的就是那张 image)。但 acquire 与 record 不在同一线程、或 acquire 还没完成时,imageIndex() 返回旧值——那是第十一章(swapchain)的问题,这里只需记住:RenderGraph 在录制路径上读了一个由另一个阶段决定的值。

7.7 SecondaryCommandGraph:二级缓冲的六个坑

7.7.1 与主图的差异

SecondaryCommandGraph 只重写三个虚函数,加了 6 个成员:

成员用途
subpass传给 inheritanceInfo.subpass(include/vsg/app/SecondaryCommandGraph.h:30)
occlusionQueryEnable传给同名继承字段(SecondaryCommandGraph.h:31)
queryFlags传给同名继承字段(SecondaryCommandGraph.h:32)
pipelineStatistics传给同名继承字段(SecondaryCommandGraph.h:33)
renderPass覆盖 framebuffer/window 的 render pass(SecondaryCommandGraph.h:36)
_executeCommands连进来的 ExecuteCommands 裸指针列表(SecondaryCommandGraph.h:53)

record() 的整体结构与基类一致,关键差异有五处:beginInfo.flags 换成 RENDER_PASS_CONTINUE | (SIMULTANEOUS_USE if >1);填 pInheritanceInfo;不调 recordTraversal->regionsOfInterest.clear()(基类调了,见 src/vsg/app/CommandGraph.cpp:93);录完遍历 _executeCommands 调 completed()(src/vsg/app/SecondaryCommandGraph.cpp:159);池同样带 RESET_COMMAND_BUFFER_BIT(SecondaryCommandGraph.cpp:103)。

第三点是全章唯一"基类做了、子类没做"的行为差异。regionsOfInterest 是 RecordTraversal 的成员,被 RegionOfInterest 节点填充,用于阴影与环境光遮蔽的 ROI 收集。二级图不收集它,因为 ROI 是 view 级概念,二级图只是 view 的一部分。这不算 bug(ROI 在 apply(const View&) 里被 swap 保护,RecordTraversal.cpp:580),但它说明子类重写 record 是复制粘贴加修改,不是模板方法:基类 65 行、子类 89 行,其中约 50 行重复。任何基类修改都要同步到子类。

7.7.2 六个坑

坑 1:inheritanceInfo 未零初始化(7.4.7 问题一,SecondaryCommandGraph.cpp:127)。 坑 2:framebuffer 三分支缺一个(7.4.7 问题二,SecondaryCommandGraph.cpp:142)。 坑 3:getRenderPass() 在 window 分支每次调用都可能创建对象(SecondaryCommandGraph.cpp:72)。getOrCreateRenderPass() 意味着"没创建就创建",在 record 里调用等于在录制路径上做重资源分配(vkCreateRenderPass 通常几十微秒)。实际影响小(只在第一次创建),但违反了"录制路径不做分配"。 坑 4:_executeCommands 是裸指针容器。 ExecuteCommands::connect 时 commandGraph->_connect(this)(src/vsg/commands/ExecuteCommands.cpp:34),~ExecuteCommands 时 entry.cg->_disconnect(this)(ExecuteCommands.cpp:27)。ExecuteCommands 持 ref_ptr<SecondaryCommandGraph> 强引用,SecondaryCommandGraph 持 ExecuteCommands* 弱引用——元素持有容器,与"容器持有元素"的常规相反。生命周期由 ExecuteCommands 保证,所以手动 secondaryCommandGraph.reset() 不会让它悬垂。 坑 5:SIMULTANEOUS_USE 的条件是连接数而非执行数(7.4.5)。 坑 6:二级图不清 regionsOfInterest(7.7.1,影响小)。

坑 4 还有一个可重入漏洞。_disconnect 用 std::find 加 erase(SecondaryCommandGraph.cpp:54):

// src/vsg/app/SecondaryCommandGraph.cpp:54-58
void SecondaryCommandGraph::_disconnect(ExecuteCommands* ec)
{
    auto itr = std::find(_executeCommands.begin(), _executeCommands.end(), ec);
    if (itr != _executeCommands.end()) _executeCommands.erase(itr);
}

同一个 ExecuteCommands 若 connect 两次,列表里有两个相同指针,_disconnect 只删一个。之后 _executeCommands.size() > 1 会误判 SIMULTANEOUS_USE,而 reset() 会对同一个 latch 调两次 set。没有代码检查重复连接。

7.7.3 ExecuteCommands 的 latch:唯一的跨线程同步点

// src/vsg/commands/ExecuteCommands.cpp:37-47
void ExecuteCommands::reset()
{
    std::scoped_lock lock(_mutex);

    _latch->set(static_cast<int>(_commandGraphsAndBuffers.size()));

    for (auto& entry : _commandGraphsAndBuffers)
    {
        entry.cb = {};
    }
}

// src/vsg/commands/ExecuteCommands.cpp:49-66
void ExecuteCommands::completed(const SecondaryCommandGraph& commandGraph, ref_ptr<CommandBuffer> commandBuffer)
{
    if (commandBuffer)
    {
        std::scoped_lock lock(_mutex);

        for (auto& [cg, cb] : _commandGraphsAndBuffers)
        {
            if (cg == &commandGraph)
            {
                cb = commandBuffer;
                break;
            }
        }
    }

    _latch->count_down();
}

这是一个计数器屏障:reset() 把 latch 设为 N(连接数)并清空所有 cb;每个 SecondaryCommandGraph::record 完成后调 completed(),存 cb 再 count_down();ExecuteCommands::record 调 wait()(ExecuteCommands.cpp:70)等 N 次递减后继续。这就是 VSG 的多线程录制同步点:主图(主线程)在 ExecuteCommands 处等待,二级图(工作线程)并行录制。

三个脆弱点:

其一,wait() 必须在加锁之前(ExecuteCommands.cpp:70 在 72 的 scoped_lock 之前)。反过来会死锁:completed() 需要同一把锁才能写 cb。这个顺序没有任何注释说明,是"靠读代码才能发现的正确性"。

其二,count_down() 在 if (commandBuffer) 之外(ExecuteCommands.cpp:65)。即使二级图因窗口不可见提前 return、没录任何东西,latch 也会减——这是必要的(否则永久阻塞),但也意味着:SecondaryCommandGraph::record 若在 completed() 之前抛异常,latch 永远不减到 0,record() 永久阻塞。

其三,reset() 的覆盖范围。 Viewer::recordAndSubmit 的 reset 循环只遍历 recordAndSubmitTask->commandGraphs(src/vsg/app/Viewer.cpp:827),而 reset() 的重写在 SecondaryCommandGraph 上。二级图可以放进这个列表(它是 CommandGraph 派生类),但更常见的组织是"主图持有 ExecuteCommands,ExecuteCommands 持有二级图",二级图不在 commandGraphs 里。此时 reset() 不会被调用,latch 停在上一帧的值(通常是 0),wait() 立即返回,vkCmdExecuteCommands 拿到的是上一帧的二级缓冲。这不是必然发生的 bug,取决于 Viewer 怎么装配 commandGraphs,但它是本章唯一一处"正确性依赖用户没看到的装配约定"。

7.8 RecordTraversal:704 行把场景图变成命令流

7.8.1 33 个 apply 的分组

RecordTraversal 声明了 33 个 apply(include/vsg/app/RecordTraversal.h:116–166)。按语义分组:

组重载行为
结构节点Group QuadGroup TileDatabase Bintraverse
剔除节点CullGroup CullNode Switch LOD PagedLOD判断后 traverse
变换节点Transform MatrixTransform CoordinateFrame压矩阵栈 + traverse + 弹栈
叶子几何VertexDraw VertexIndexDraw Geometrystate->record() + record
实例化InstanceNode InstanceDraw InstanceDrawIndexed设 instanceNode 后 state->record() + record
状态StateGrouppush + traverse + pop
命令Command Commandsstate->record() + record
光照Light AmbientLight DirectionalLight PointLight SpotLight收集到 viewDependentState
视图View CommandGraph见 7.8.4
其他DepthSorted Layer RegionOfInterest Joint Object入 bin / 记录 ROI / 空操作

apply(const Object&) 是兜底:object.traverse(*this)(src/vsg/app/RecordTraversal.cpp:121);它上面的 clearBins() 只是对 bins 逐个 clear()(:113)。apply(const Group&) 只做 group.traverse(*this) 加一层 instrumentation(RecordTraversal.cpp:129)。

7.8.2 state->record() 的调用点统计

grep -n "state->record()" src/vsg/app/RecordTraversal.cpp 的结果:

行号上下文
339apply(const VertexDraw&)
348apply(const VertexIndexDraw&)
357apply(const Geometry&)
502apply(const InstanceDraw&)
510apply(const InstanceDrawIndexed&)
535apply(const Commands&)
547apply(const Command&)

7.8.3 stack[0] 作为记忆槽

// include/vsg/vk/State.h:76-84
inline void record(CommandBuffer& commandBuffer)
{
    const T* current = stack[pos];
    if (current != stack[0])
    {
        current->record(commandBuffer);
        stack[0] = current;
    }
}

stack[0] 不是状态,是"上次实际录制过的对象"。这是一个 memoization:用一次指针比较代替一次无条件重绑。

后果 1:stack[0] 不能当状态槽用。 reset() 与 dirty() 都把 stack[0] 置 nullptr(State.h:54、59)。pos 从 0 开始、push 先自增,所以 stack[1] 才是第一个真实状态;16 个元素里 1 个被征用为记忆槽。

后果 2:pop() 不回滚记忆,而这恰好正确。 pop() 只做 --pos(State.h:69)。从状态 B pop 回 A 后,stack[0] 还是 B,下一次 record() 比较 A 与 B 不等,重绑 A——正确。若 pop 回的是同一对象(A → A 的嵌套),stack[0] 仍是 A,比较相等跳过——也正确,因为中间没绑过别的东西。记忆的语义是"上次实际录制的对象",不是"上次栈顶的对象"。

后果 3:reset() 与 dirty() 的区别。

// include/vsg/vk/State.h:51-60
inline void reset()
{
    pos = 0;
    stack[0] = nullptr;
}

inline void dirty()
{
    stack[0] = nullptr;
}

State::reset() 是"回到空栈"(src/vsg/vk/State.cpp:36 遍历 stateStacks 逐个调它),帧开始时用;dirtyStateStacks() 是"忘记已绑定",换 pipeline layout 时用(State.h:311)。但 State::connect 只调 dirtyStateStacks(),不调 reset()(State.cpp:50)——每帧 connect 不清 pos。这依赖"上一帧结束时 pos 一定是 0",即 push/pop 严格配对;异常路径会破坏它(7.9.4)。

7.8.4 apply(const View&) 的十三个动作

这是 RecordTraversal 里最长的函数(111 行,RecordTraversal.cpp:559)。压成一张表:

#动作代码为什么
1标脏state->dirtyStateStacks()(:564)新相机、新 viewport,全部重绑
2缓存并设掩码cached_traversalMask = ...traversalMask、viewID = view.viewID、viewDependentState = ...(:567–570)遍历掩码与 view 绑定
3换出 bins / ROIcached_bins.swap(bins)、cached_regionsOfInterest.swap(regionsOfInterest)(:576、581)swap 而非赋值,避免复制 vector<ref_ptr>
4算 bin 范围并挂接min/max_binNumber → bins.resize(...) → bins[binNumber - min](:584–598)支持负数 bin 编号
5接管 viewDependentStateclear() + LODScale = view.LODScale(:604)光照列表每帧重建
6push view 级状态state->pushView(view)(:608)动态 viewport 时压 camera->viewportState(slot 8)
7设相机矩阵inheritViewForLODScaling、setProjectionAndViewMatrix(:612)重算 frustum,清空 frustum 栈
8同步 viewport 数据把 VkViewport 的 x/y/w/h 塞进 viewportData,变化时 dirty()(:619–635)供 shader 读屏幕空间尺寸
9遍历view.traverse(*this)(:639)进入 RenderGraph 等子树
10pop view 级状态state->popView(view)(:651)—
11录 binfor (bin : view.bins) bin->accept(*this)(:653)此时状态已 pop 回 view 外,bin 内容自带 StateGroup
12处理光照/阴影viewDependentState->traverse(*this)(:660)上传 lightData,可能递归 preRenderCommandGraph
13恢复缓存五步恢复,与 2/3/5 一一对应(:664–668)—

三个设计点值得展开,其余都是簿记。

其一,第 4 步的"负数索引"技巧。

// src/vsg/app/RecordTraversal.cpp:584-598
int32_t min_binNumber = 0;
int32_t max_binNumber = 0;
for (const auto& bin : view.bins)
{
    if (bin->binNumber < min_binNumber) min_binNumber = bin->binNumber;
    if (bin->binNumber > max_binNumber) max_binNumber = bin->binNumber;
}

minimumBinNumber = min_binNumber;
bins.resize(max_binNumber - min_binNumber + 1);
for (auto& bin : view.bins)
{
    bins[bin->binNumber - min_binNumber] = bin;
    bin->clear();
}

min_binNumber 与 max_binNumber 都初始为 0,不是 INT32_MAX/INT32_MIN。这个"错误"的初值起了保证作用:bin 0 永远在范围内。bin 0 是 DepthSorted 的默认值,所以即使 view.bins 里只有负 bin,bins 里也有一个给 0 用的空位——但那个位置是空 ref_ptr,addToBin(0, ...) 会解引用空指针(7.8.6)。

其二,第 11 步在 popView 之后。 bin 里的节点是 DepthSorted 收集的待排序子图,在 view.traverse 期间被 addToBin 加入但不立即录制(要先按深度排序)。view.traverse 结束后 popView 把 viewport 状态弹掉,然后才录 bin。这意味着 bin 里的 StateGroup 会重新 push 自己的状态(pipeline、descriptor set),但 viewport 不会被重新 push,因为 slot 8 已弹空。所以 bin 里的 draw 用一个"没有 viewport 命令"的状态,继承自 RenderGraph::accept 里 vkCmdSetViewport 的结果。这是正确的:viewport 是命令缓冲的全局状态,vkCmdSetViewport 之后所有 draw 都用它。

其三,第 12 步的递归。 ViewDependentState::traverse(RecordTraversal&) 在需要每帧更新阴影贴图时会调 preRenderCommandGraph->accept(rt),那是一个嵌套的 CommandGraph 录制:apply(const CommandGraph&) 会调 cg->record(...)(RecordTraversal.cpp:688),后者 vkBeginCommandBuffer 一个新的命令缓冲。也就是在一个正在录制的命令缓冲里开始录制另一个命令缓冲。合法(不同的 VkCommandBuffer 对象),但意味着 RecordTraversal 的 state、bins、viewDependentState、regionsOfInterest 全部被内层覆盖。

apply(const CommandGraph&) 里的 state->inherit(*state) 就是处理这个的:

// src/vsg/app/RecordTraversal.cpp:680
cg->getOrCreateRecordTraversal()->state->inherit(*state);

内层 CommandGraph 的 RecordTraversal 有自己的 State,inherit 把外层 State 拷过去。State::inherit 先 reserve(state.maxSlots) 再 reset()(src/vsg/vk/State.cpp:79、81),然后按 inheritanceMask 逐项复制 stateStacks、viewportStateHint、矩阵与 frustum(State.cpp:93–111)。这是一个"轻量上下文切换":State 继承,CommandBuffer 独立,其余靠各自的 RecordTraversal 隔离。

7.8.6 addToBin 的越界风险

// src/vsg/app/RecordTraversal.cpp:701-704
void RecordTraversal::addToBin(int32_t binNumber, double value, const Node* node)
{
    bins[binNumber - minimumBinNumber]->add(state, value, node);
}

两个隐患:bins 的索引没有边界检查(vector::operator[] 越界是未定义行为);bins[...] 可能是空 ref_ptr,->add 解引用空指针。

越界条件:apply(const DepthSorted&) 调 addToBin(depthSorted.binNumber, ...)(RecordTraversal.cpp:321),而 depthSorted.binNumber 是用户设的任意值,bins 的范围由 view.bins 决定。DepthSorted 的 binNumber 不在 view.bins 覆盖范围内就越界。正常 View 会包含所有用到的 bin(ResourceRequirements 收集 bin 编号,updateTasks 补齐缺失的 bin);用户动态添加一个 binNumber = 5 的 DepthSorted 而 view.bins 只有 0 与 -1 时,bins.resize(2),bins[5 - (-1)] = bins[6] 越界。

Bin::add 是线程安全的(mutable std::mutex,src/vsg/nodes/Bin.cpp:60),因为多线程录制时多个 RecordTraversal 可能往同一个 bin 里加。

7.9 State 的 slot 机制:16 个槽位与一次越界

7.9.1 谁在用 slot,用了几号

slot 是 StateCommand 的成员,默认 0(include/vsg/state/StateCommand.h:36),由构造函数写入(StateCommand.h:26)。全库只有 5 个显式赋值点:

类slot 值位置
BindDescriptorSets(firstSet 版)1 + in_firstSetinclude/vsg/state/BindDescriptorSet.h:31
BindDescriptorSets(默认构造)1BindDescriptorSet.h:40
BindDescriptorSet(firstSet 版)1 + in_firstSetBindDescriptorSet.h:98、117
BindDescriptorSet(默认构造)1BindDescriptorSet.h:107
ViewportState8src/vsg/state/ViewportState.cpp:21

BindViewDescriptorSets 的默认 slot 由基类构造传入 Inherit(2)(src/vsg/state/ViewDependentState.cpp:106)。其余 StateCommand 派生类(BindGraphicsPipeline、BindVertexBuffers、BindIndexBuffer、PushConstants……)都是 slot 0。

这揭示了一个没写进文档的编号方案:

slot用途
0pipeline 绑定 + 顶点/索引缓冲绑定 + push constants
1descriptor set 0
2view descriptor set(光照)
3+descriptor set 1, 2, ...
8viewport/scissor

slot 8 是一个魔法数字。它远离 descriptor set 的编号区间(1..N),所以不会冲突。但若一个 pipeline 有 8 个 descriptor set(firstSet = 7),slot = 8,与 ViewportState 撞车。Vulkan 保证至少 4 个 set(maxBoundDescriptorSets >= 4),常见实现是 8 或 32;在"8 个 set"的设备上,firstSet = 7 的 BindDescriptorSet 与 ViewportState 同槽。同槽意味着两者在同一个栈上 LIFO:ViewportState 在 View 层 push,BindDescriptorSet 在 StateGroup 层 push,嵌套时顺序正确(先进 viewport 后进 descriptor set,pop 反序),功能上不会错,但 record() 的 memoization 会失效——两个不同对象交替成为 stack[pos],每次都认为"变了"。

7.9.2 StateStack::push 的越界

// include/vsg/vk/State.h:38-70
using Stack = std::array<const T*, STATESTACK_SIZE>;
Stack stack;
size_t pos = 0;
...
inline void push(const T* value)
{
    stack[++pos] = value;
}

inline void pop()
{
    --pos;
}

没有边界检查。 std::array<const T*, 16> 占 128 字节(64 位),pos 紧跟其后(size_t,8 字节),所以 stack[15] 是最后一个合法元素,stack[16] 正好落在 pos 的内存上。第 16 次 push 的机器码等价于:

mov   128(%rdi), %rax        # 读 pos(偏移 128,紧跟 16×8 的 stack 之后)
inc   %rax                   # ++pos → 16
mov   %rax, 128(%rdi)        # 写回 pos
mov   %rsi, (%rdi,%rax,8)    # stack[16] = value → 落在 &pos 上

stack[16] 的地址 = stack 基址 + 128 = pos 的地址,所以第 16 次 push 把指针值写进了 pos。后果是链式的:pos 变成一个约 1.4 × 10^14 的地址值;下一次 push 的写地址 = 基址 + pos × 8,直接段错误;record() 读 stack[pos] 也是野地址;pop() 只减 1 仍是野值;size() / empty() 返回垃圾,不崩但结果全错。

这一次越界写会立刻或很快导致段错误,不是静默损坏。这是本章唯一一个"会崩"的缺陷。

7.9.4 State::push 的两层无检查

// include/vsg/vk/State.h:367-375
template<typename Iterator>
inline void push(Iterator begin, Iterator end)
{
    for (auto itr = begin; itr != end; ++itr)
    {
        stateStacks[(*itr)->slot].push((*itr));
    }
    dirty = true;
}

两层越界叠加:stateStacks[slot]——stateStacks 是 std::vector<StateCommandStack>,operator[] 无检查,越界条件是 slot >= stateStacks.size();stack[++pos]——定长 std::array,越界条件是同槽第 16 次 push。

第 1 层的防护完全依赖 State::reserve:

// src/vsg/vk/State.cpp:25-34
void State::reserve(const Slots& in_maxSlots)
{
    maxSlots = in_maxSlots;
    activeMaxStateSlot = maxSlots.max();

    size_t required_size = static_cast<size_t>(activeMaxStateSlot) + 1;
    if (required_size > stateStacks.size()) stateStacks.resize(required_size);

    //    info("State::reserve(", maxStateSlot, ", ", maxViewSlot, ")");
}

required_size = max(state, view) + 1,所以 stateStacks.size() 必须 >= 最大 slot + 1。若 maxSlots = {0, 0}(默认),size() == 1,任何 slot >= 1 的 StateCommand 都越界——而 BindDescriptorSet 的默认 slot 就是 1(BindDescriptorSet.h:107)。

maxSlots 的填充链是一条四跳的隐式契约:

CollectResourceRequirements::apply(const StateCommand&)        # src/vsg/vk/ResourceRequirements.cpp:159
  → requirements.maxSlots.state = max(..., stateCommand.slot)  # :161
  → RecordAndSubmitTask::assignCompileResult → maxSlots.update # src/vsg/app/RecordAndSubmitTask.cpp:315
  → CommandGraph::getOrCreateRecordTraversal()                 # src/vsg/app/CommandGraph.cpp:65
    → RecordTraversal::create(maxSlots) / reserve(maxSlots)    # :69 / :71
      → State::reserve()                                       # src/vsg/vk/State.cpp:25

关键在 getOrCreateRecordTraversal 的两个分支:

// src/vsg/app/CommandGraph.cpp:65-74
ref_ptr<RecordTraversal> CommandGraph::getOrCreateRecordTraversal()
{
    //CPU_INSTRUMENTATION_L1(instrumentation);
    if (!recordTraversal)
        recordTraversal = RecordTraversal::create(maxSlots);      // 第一次:用 maxSlots 建 State
    else
        recordTraversal->getState()->reserve(maxSlots);            // 之后:只扩容

    return recordTraversal;
}

第一次调用时 maxSlots 是什么,就决定了 State 的初始容量;之后每次调用都 reserve,而 reserve 只在变大时 resize,永远不会缩。

正常流程安全:Viewer::compile() → CompileTraversal 填 maxSlots → assignCompileResult 更新 commandGraph->maxSlots → 才 recordAndSubmit。但 RecordAndSubmitTask::assignInstrumentation 里也有一句 cg->getOrCreateRecordTraversal()->instrumentation = cg->instrumentation,若它在 compile 之前被调用(比如用户手动设 profiler),State 会以 {0,0} 建出来,stateStacks 只有 1 个元素。之后 compile 更新 maxSlots,下一次 getOrCreateRecordTraversal() 会扩容到正确大小——只要在 record 之前再调一次。CommandGraph::record 的第一句就是 getOrCreateRecordTraversal()(CommandGraph.cpp:87),所以补救一定发生。

结论:越界只发生在"maxSlots 已确定、但 reserve 没被再调一次"的窗口里,而这个窗口在 record 第一行就被关闭。真正的漏洞在另一条路径上——StateGroup 里放了 maxSlots 没覆盖到的 slot(7.9.5)。

第 2 层的定长数组还有两个附加问题。

pop() 的下溢。 pos 是 size_t,pos == 0 时 --pos 变成 SIZE_MAX。下一次 record() 读 stack[SIZE_MAX],地址是 基址 - 8(SIZE_MAX * 8 溢出回 -8),读到的是 stack 数组前面的内存——不是段错误,是读到相邻对象的字段,然后 current->record(...) 对野指针调用虚函数。

push 与 pop 的配对由 RecordTraversal::apply(const StateGroup&) 保证(src/vsg/app/RecordTraversal.cpp:524、528)。traverse 里若抛异常,pop 不执行,pos 永久偏高,下一次 push 从更高处开始,累积到 16 次就撞上 7.9.2 的越界写。异常路径是这两个 bug 的共同触发器。

Stack stack; 未初始化。 std::array<const T*, 16> 没有初始化器,默认构造后 16 个指针是未定义值。这看起来危险,实际安全,因为三个巧合叠在一起:pos 有默认成员初始化器 size_t pos = 0;(State.h:40);record() 读 stack[pos],pos == 0 时 current 与 stack[0] 是同一个元素,比较恒等跳过;stack[1..15] 在被读之前一定先被 push 写过。任何一个改动(pos 从 -1 起始、stack[0] 换成独立的 lastRecorded 成员)都会把"未初始化"变成真 bug。

7.9.5 activeMaxStateSlot 的两个值

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

        // reset the active maxslot to the minimum required
        activeMaxStateSlot = maxSlots.state;

        projectionMatrixStack.record(*_commandBuffer);
        modelviewMatrixStack.record(*_commandBuffer);

        dirty = false;
    }
}

activeMaxStateSlot 有两个值:reserve / pushView / popView / reset 设为 maxSlots.max()(src/vsg/vk/State.cpp:28、56、62、43);record() 完成后设为 maxSlots.state。设计意图是 view 槽(slot 8)只在 View 内部被录制:pushView 把 activeMaxStateSlot 提到 8,record() 录完 0..8 后回落到 maxSlots.state(比如 2),之后 view 外的 record() 只录 0..2。

正确性依赖"view 槽的命令只在 apply(const View&) 内部被 push"。pushView(viewportState) 确实只在 apply(const View&)(RecordTraversal.cpp:608)与 RenderGraph::accept(RenderGraph.cpp:157)里调。但有一个漏洞:用户在 View 外面放一个含 ViewportState 的 StateGroup(合法,ViewportState 是 StateCommand),push 会写 stateStacks[8],而 activeMaxStateSlot 是 maxSlots.state(比如 2),record() 只循环 0..2,slot 8 永远不会被录制。结果是 ViewportState 被 push 但从不生效,viewport 不会被设置——静默失败。ViewportState.h 的注释说它"enable ViewportState to be recorded via vkCmdSetScissor and vkCmdSetViewport",但它不在 View 里就录不到,文档与实现不符。

7.9.6 maxSlots 的三种来源

Slots 有三个来源:序列化,ResourceHints::read 读 maxSlots 两个整数(src/vsg/state/ResourceHints.cpp:31,旧字段名 maxSlot 走 :35 的兼容分支);编译期收集,CollectResourceRequirements::apply(const StateCommand&) 取 slot 最大值(src/vsg/vk/ResourceRequirements.cpp:161),view 槽取 viewportState->slot(ResourceRequirements.cpp:239、247);运行时赋值,Viewer.cpp:365 直接 commandGraph->maxSlots = resourceRequirements.maxSlots。

第三种是赋值不是 update。如果 resourceRequirements 是"重新收集过"的对象(只包含当前帧看到的节点),这个赋值会缩小 maxSlots。缩小后 reserve 不会收缩 stateStacks(if (required_size > size()) 才 resize),但 activeMaxStateSlot 会变小,导致高 slot 的命令不被录制。

聚合路径本身是"只增不减":ResourceRequirements::apply(const ResourceHints&) 用 maxSlots.update(resourceHints.maxSlots)(ResourceRequirements.cpp:69),收集时逐个取 max。只有 Viewer.cpp:365 这一处直接赋值可能缩小。这是一处不一致:同一份数据,有的路径 update(单调),有的路径 =(可缩)。

7.9.7 dirty 的粒度

State::dirty 是一个 bool(include/vsg/vk/State.h:275),一标就是一整个状态;改一个 BindDescriptorSet 会让所有槽位重录。但 StateStack::record 有 memoization,重录的代价是"每槽一次指针比较",不是"每槽一次 vkCmd*"。粗粒度标脏 + 细粒度记忆 = 等效的细粒度控制,这是常见的性能模式:标脏要便宜,录制要精确。

代价:dirty == true 时 state->record() 是 O(activeMaxStateSlot),9 次函数调用加 9 次比较。5,000 个 draw 各自在自己的 StateGroup 里(每帧都 dirty)就是 45,000 次比较——不大,但不是零。

7.10 屏障与事件:PipelineBarrier / Event

7.10.1 三类屏障的结构

// include/vsg/commands/PipelineBarrier.h:32-45
struct VSG_DECLSPEC MemoryBarrier : public Inherit<Object, MemoryBarrier>
{
    MemoryBarrier(VkAccessFlags in_srcAccessMask, VkAccessFlags in_dstAccessMask) :
        srcAccessMask(in_srcAccessMask),
        dstAccessMask(in_dstAccessMask) {}

    virtual void* assign(CommandBuffer& commandBuffer) const = 0;
    void assign(CommandBuffer& commandBuffer, VkMemoryBarrier& info) const;

    VkAccessFlags srcAccessMask = 0;
    VkAccessFlags dstAccessMask = 0;

    ref_ptr<VulkanInfo> next;
};

using MemoryBarriers = std::vector<ref_ptr<MemoryBarrier>>;

BufferMemoryBarrier(PipelineBarrier.h:49)多出 srcQueueFamilyIndex、dstQueueFamilyIndex、buffer、offset、size;ImageMemoryBarrier(PipelineBarrier.h:81)多出 oldLayout、newLayout、image、subresourceRange。三者都有 ref_ptr<VulkanInfo> next,用于构建 pNext 链——比如给 VkMemoryBarrier 接一个 VkSampleLocationsInfoEXT(SampleLocations,PipelineBarrier.h:116)。

PipelineBarrier 自己持有三个容器与三个阶段掩码:memoryBarriers、bufferMemoryBarriers、imageMemoryBarriers,加 srcStageMask、dstStageMask、dependencyFlags(PipelineBarrier.h:146–152)。

7.10.2 assign 的 pNext 递归

// src/vsg/commands/PipelineBarrier.cpp:22-28
void MemoryBarrier::assign(CommandBuffer& commandBuffer, VkMemoryBarrier& info) const
{
    info.sType = VK_STRUCTURE_TYPE_MEMORY_BARRIER;
    info.pNext = next ? next->assign(commandBuffer) : nullptr;
    info.srcAccessMask = srcAccessMask;
    info.dstAccessMask = dstAccessMask;
}

next->assign(commandBuffer) 返回 void*,指向一个在 commandBuffer.scratchMemory 里分配的结构体(SampleLocations::assign 是唯一这么做的实现,PipelineBarrier.cpp:71)。这意味着 pNext 链的每一环都占 scratch 空间,而且分配顺序是从外层到内层。

scratchMemory 初始 4096 字节(src/vsg/vk/CommandBuffer.cpp:27)。一条带 3 层 pNext 的屏障大约占 200 字节,20 条就满;满了之后 ScratchMemory::next 链式扩容(7.10.4)。

7.10.3 record 的三次分配

// src/vsg/commands/PipelineBarrier.cpp:95-129
void PipelineBarrier::record(CommandBuffer& commandBuffer) const
{
    auto& scratchMemory = *(commandBuffer.scratchMemory);

    auto vk_memoryBarriers = scratchMemory.allocate<VkMemoryBarrier>(memoryBarriers.size());
    for (size_t i = 0; i < memoryBarriers.size(); ++i)
    {
        memoryBarriers[i]->assign(commandBuffer, vk_memoryBarriers[i]);
    }

    auto vk_bufferMemoryBarriers = scratchMemory.allocate<VkBufferMemoryBarrier>(bufferMemoryBarriers.size());
    for (size_t i = 0; i < bufferMemoryBarriers.size(); ++i)
    {
        bufferMemoryBarriers[i]->assign(commandBuffer, vk_bufferMemoryBarriers[i]);
    }
    auto vk_imageMemoryBarriers = scratchMemory.allocate<VkImageMemoryBarrier>(imageMemoryBarriers.size());
    for (size_t i = 0; i < imageMemoryBarriers.size(); ++i)
    {
        imageMemoryBarriers[i]->assign(commandBuffer, vk_imageMemoryBarriers[i]);
    }

    vkCmdPipelineBarrier(
        commandBuffer,
        srcStageMask,
        dstStageMask,
        dependencyFlags,
        static_cast<uint32_t>(memoryBarriers.size()),
        vk_memoryBarriers,
        static_cast<uint32_t>(bufferMemoryBarriers.size()),
        vk_bufferMemoryBarriers,
        static_cast<uint32_t>(imageMemoryBarriers.size()),
        vk_imageMemoryBarriers);

    scratchMemory.release();
}

三次 allocate 加三次 assign 循环,一次 vkCmdPipelineBarrier,一次 release()。release() 在最后,清空整个 scratch,所以 PipelineBarrier::record 结束后之前所有从 scratchMemory 分配的东西都失效。没人会跨 record 持有 scratch 指针(每次都是"分配-使用-release"的完整周期),但嵌套会出问题:若 record 里调用了另一个也 release() 的函数,两次 release() 会把对方的分配清掉。Event::WaitEvents 是同样的模式(src/vsg/commands/Event.cpp:150),两者不会互相调用,所以目前安全——但这是"靠调用图保证"的安全。

7.10.4 ScratchMemory 的链式扩容

整个分配器只有一个边界判定:(ptr + allocate_size) <= (buffer + size)(include/vsg/core/ScratchMemory.h:59);放不下就顺着 next 链递归,没有锁,也不能跨线程共享。

// include/vsg/core/ScratchMemory.h:52-78
template<typename T>
T* allocate(size_t num = 1)
{
    if (num == 0) return nullptr;

    size_t allocate_size = sizeof(T) * num;

    if ((ptr + allocate_size) <= (buffer + size))
    {
        T* allocated_ptr = reinterpret_cast<T*>(ptr);

        // move the ptr to the alignment end
        ptr = align(ptr + allocate_size);

        return allocated_ptr;
    }

    if (!next) next = ScratchMemory::create(std::max(size, allocate_size));

    return next->allocate<T>(num);
}

void release()
{
    ptr = buffer;
    if (next) next->release();
}

三个要点:

其一,num == 0 返回 nullptr。 这很重要:PipelineBarrier::record 会传 0(没有 memory barrier 时),而 vkCmdPipelineBarrier 收到 count = 0, pXxx = nullptr 是合法的。

其二,扩容不释放旧内存。 next 链只增不减:某帧需要 20 KB scratch,next 链就保留 20 KB 直到命令缓冲销毁。release() 只重置 ptr,不销毁 next 节点——这是缓存设计,下次不用重新分配。

其三,align 是 8 字节对齐。

// include/vsg/core/ScratchMemory.h:45-50
static uint8_t* align(uint8_t* p)
{
    auto alignment = sizeof(p);
    uint8_t* new_p = reinterpret_cast<uint8_t*>(((reinterpret_cast<size_t>(p) + alignment - 1) / alignment) * alignment);
    return new_p;
}

sizeof(p) 是指针大小(8),不是"类型 T 的对齐要求"。这对所有 Vulkan 结构体都够(最大成员是 uint64_t 或指针,对齐要求不超过 8)。allocate<char>(3) 之后 allocate<uint32_t>(1),第一次 ptr = align(ptr+3) 已经对齐到 8,第二次返回对齐指针,正确。用除法加乘法实现向上取整,对 2 的幂等价于 (p + 7) & ~7,对非 2 的幂也正确——一个不必要但无害的通用性。

7.10.5 SetEvent / ResetEvent / WaitEvents

三个类共用 Event.h。前两个各一行:

// src/vsg/commands/Event.cpp:71-73
void SetEvent::record(CommandBuffer& commandBuffer) const
{
    vkCmdSetEvent(commandBuffer, *event, stageMask);
}
// src/vsg/commands/Event.cpp:90-92
void ResetEvent::record(CommandBuffer& commandBuffer) const
{
    vkCmdResetEvent(commandBuffer, *event, stageMask);
}

*event 是"解引用 ref_ptr<Event> 得到 Event&,再隐式转成 VkEvent"两次转换,operator VkEvent() 定义在 Event 上(include/vsg/commands/Event.h:26)。

WaitEvents::record(Event.cpp:109)与 PipelineBarrier::record 结构 95% 相同,只多一个 VkEvent[] 数组和一次 vkCmdWaitEvents。两份几乎逐字重复的代价是任何修复都要做两遍,而且改法必须一致。

7.10.6 屏障在 VSG 里的实际用量

grep -rn "vkCmdPipelineBarrier" src/ 的结果:

文件次数用途
TransferTask.cpp5图像上传前后的布局转换(:670、799、834、851、874)
PipelineBarrier.cpp1PipelineBarrier 命令本体(:116)
Context.cpp1光线追踪构建后的内存屏障(:75)

7.11 一次更正:CopyAndReleaseBuffer 与 CopyAndReleaseImage 的屏障数

7.11.1 上一章预告的错误

第六章结尾我写了:"为什么 CopyAndReleaseBuffer 的 record 里有一次 vkCmdPipelineBarrier,而 CopyAndReleaseImage 有两次?"

这句话是错的。 两个类的 record 里都是零次显式 vkCmdPipelineBarrier。

// src/vsg/commands/CopyAndReleaseBuffer.cpp:69-83
void CopyAndReleaseBuffer::record(CommandBuffer& commandBuffer) const
{
    std::scoped_lock lock(_mutex);

    _readyToClear.clear();

    _readyToClear.swap(_completed);

    for (const auto& copyData : _pending)
    {
        copyData.record(commandBuffer);
    }

    _pending.swap(_completed);
}

CopyAndReleaseImage::record 与它逐字相同,连 _readyToClear、_completed、_pending 三个容器的操作顺序都一样(src/vsg/commands/CopyAndReleaseImage.cpp:171),唯一差别是类名。真正的差异在 CopyData::record:

// src/vsg/commands/CopyAndReleaseBuffer.cpp:59-67
void CopyAndReleaseBuffer::CopyData::record(CommandBuffer& commandBuffer) const
{
    VkBufferCopy copyRegion = {};
    copyRegion.srcOffset = source->offset;
    copyRegion.dstOffset = destination->offset;
    copyRegion.size = source->range;
    vkCmdCopyBuffer(commandBuffer, source->buffer->vk(commandBuffer.deviceID), destination->buffer->vk(commandBuffer.deviceID), 1, &copyRegion);
}
// src/vsg/commands/CopyAndReleaseImage.cpp:166-169
void CopyAndReleaseImage::CopyData::record(CommandBuffer& commandBuffer) const
{
    transferImageData(destination->imageView, destination->imageLayout, layout, width, height, depth, mipLevels, source->buffer, source->offset, commandBuffer.vk(), commandBuffer.getDevice());
}

transferImageData 里有 5 处 vkCmdPipelineBarrier(src/vsg/app/TransferTask.cpp:670、799、834、851、874)。正确的说法是:

路径record 里的显式屏障被调用函数里的屏障总计
buffer000
image(单 mip)022
image(N mip,生成 mipmap)02 + 2(N-1)2N

上一章预告的方向对了一半(image 确实更多),但"一次 vs 两次"的数字是猜的。

7.11.3 CopyAndReleaseImage 的两条路径

copy() 有两个分支:源格式与目标格式相同(或元素大小相同)时直接 _copyDirectly(src/vsg/commands/CopyAndReleaseImage.cpp:145),否则逐字节循环填充(CopyAndReleaseImage.cpp:124)。

第一条把数据 memcpy 到 staging。第二条"格式不同但元素大小相同"(R8G8B8A8_UNORM vs R8G8B8A8_SRGB)也走 memcpy——这是错的,两者字节布局相同但语义不同,memcpy 会把 SRGB 数据当 UNORM 用。这是第五章讨论过的"formatsCompatible 判据太宽"。第三条(RGB8 → RGBA8)逐字节循环,第五章量化过:4K RGB8 → RGBA8 需要 38 ms,而 memcpy 是 4.2 ms。

7.11.4 两者都是死代码

两个头文件第一行注释就是判决:

// include/vsg/commands/CopyAndReleaseBuffer.h:23
/// Deprecated - use vsg::Data dataVariance and Data::dirty() to signal vsg::TransferTask to transfer data.

CopyAndReleaseImage.h:23 是同一句话。更关键的是没有 in-tree 调用者:搜 context->copy( 零结果;Context::copy 只有定义没有调用;CopyAndReleaseBuffer 只出现在 Context.h 的成员声明、Context.cpp 的创建、以及 BufferInfo.cpp 的一句注释警告里。

BufferInfo::copyDataToBuffer 的警告写得很明白:设备内存不支持直接映射,要么用 vsg::TransferTask 的动态更新,要么自己按"分配 staging、拷到 staging、从 staging 传到 device local"三步走,最后一步"use CopyAndReleaseBuffer"。即"VSG 自己不用,你写的时候可以参考"。

所以这一整条路径(Context::copy → copyImageCmd/copyBufferCmd → record)是为外部用户保留的兼容层,1.1.16 的内部流程全部走 TransferTask。这是本章最重要的一个更正:不要按 CopyAndRelease* 理解 VSG 的传输路径。真正的路径是 TransferTask(第五章 5.16、第六章 6.10),它在 transferQueue 上录一个独立的命令缓冲(src/vsg/app/TransferTask.cpp:498),用 TRANSFER_BEFORE_RECORD_TRAVERSAL / TRANSFER_AFTER_RECORD_TRAVERSAL 两个时机插入帧的录制流程。

7.11.5 三缓冲的引用生命周期

_pending / _completed / _readyToClear 的流转(以一次拷贝 A 为例):

帧 N:  _readyToClear.clear() → swap(_completed) → 录 _pending 里的 A → _pending.swap(_completed)
        结果:_completed = [A]
帧 N+1:clear() → swap(_completed)
        结果:_readyToClear = [A],A 的 ref_ptr 仍持有 staging buffer
帧 N+2:clear() → 释放 A 的 ref_ptr → staging buffer 归还池

所以 A 的 staging buffer 在帧 N+1 结束时仍活着,在帧 N+2 的 record 开始时被释放,即"录制后存活约 1 帧"。

这个时长够不够?命令缓冲在帧 N 提交,GPU 可能在帧 N+1 还没执行完(队列积压)。若 staging buffer 在帧 N+2 被释放并复用,而 GPU 还在帧 N 的 transfer 上读它,就是数据竞争。这依赖 DeviceMemory::release 的实现:它把内存块还给 MemoryBufferPools,池可能立刻复用。若池的复用策略是 LIFO,刚释放的块最先被复用——最坏情况。这是 CopyAndRelease* 死代码身份之外的第二个问题:即使被使用,引用生命周期也不足以保证安全。

7.12 数字

7.12.1 规模

项数量依据
Command 派生类33include/vsg/commands/ 下 34 个头文件减 1 个基类
record 只有 1 行的类15逐个读头文件统计
RecordTraversal::apply 重载33include/vsg/app/RecordTraversal.h:116–166
state->record() 调用点7src/vsg/app/RecordTraversal.cpp 的 339/348/357/502/510/535/547
vkBeginCommandBuffer 调用点4CommandGraph.cpp:130、SecondaryCommandGraph.cpp:152、TransferTask.cpp:498、Context.cpp:314
vkBeginCommandBuffer 返回值检查0同上四处
显式设定 slot 的位置5BindDescriptorSet.h:31、40、98、107、117
vkCmdPipelineBarrier 调用点(全库)7TransferTask.cpp 5 处 + PipelineBarrier.cpp:116 + Context.cpp:75

7.12.2 关键常量

常量值位置影响
STATESTACK_SIZE16include/vsg/vk/State.h:28同槽 16 次 push 越界
POLYTOPE_SIZE5include/vsg/vk/State.h:27frustum 5 个面(无近平面,State.h:194)
ScratchMemory 初始大小4096src/vsg/vk/CommandBuffer.cpp:27约 20 条带 pNext 的屏障
MatrixStack projection offset0include/vsg/vk/State.h:289硬编码
MatrixStack modelview offset64include/vsg/vk/State.h:290硬编码
ViewportState::slot8src/vsg/state/ViewportState.cpp:21魔法数字
BindViewDescriptorSets::slot(默认)2src/vsg/state/ViewDependentState.cpp:106与 descriptor set 1 抢编号

7.12.3 每帧的 CPU 开销估算(5,000 draw,单核)

阶段操作数单次成本小计
accept 分发5,000~5 ns25 μs
state->record()(dirty)5,000~40 ns(9 槽比较)200 μs
state->record()(clean)5,000~2 ns10 μs
Draw::record5,000~30 ns150 μs
StateGroup push/pop1,000 × 2 × 2~20 ns80 μs
vkCmdBindDescriptorSets1,000~60 ns60 μs
vkCmdBindVertexBuffers1,000~50 ns50 μs
排序(Bin::sort)5,000~50 ns(std::sort)250 μs
合计~0.8 ms

这个量级与实测吻合(vsgprofiler 在典型场景上报 0.6–1.5 ms 的 CPU 录制时间):占 60 fps 预算的 5%,占 144 fps 预算的 11%。排序那一行最容易被忽略——Bin::traverse 每次都要 std::sort 整批 _binElements(src/vsg/nodes/Bin.cpp:118),而 Bin 的内容在录制期间每帧重建,排序无法跨帧缓存。

7.13 源码索引

按"一句话结论 + 坐标"排列,每条都能单独核对。

命令层

  • Command::record 是唯一纯虚函数,形参只有 CommandBuffer&——include/vsg/commands/Command.h:29
  • Command 的基类是 Compilable,不是 Node——Command.h:22
  • Compilable::compile 默认空实现,是整个编译遍历的落点——include/vsg/nodes/Compilable.h:29
  • Commands::children 的元素类型被钉死为 ref_ptr<Command>——include/vsg/commands/Commands.h:48
  • Commands::record 不调 state->record(),只做转发——src/vsg/commands/Commands.cpp:60
  • Commands::compile 直接递归孩子,绕开 accept——Commands.cpp:52
  • Commands::compare 比的是孩子指针容器,不是内容——Commands.cpp:35
  • Draw::record 内联在头文件里,一行 vkCmdDraw——include/vsg/commands/Draw.h:39
  • BindVertexBuffers::record 只有一次 vkCmdBindVertexBuffers,缓冲数组来自 _vulkanData——src/vsg/commands/BindVertexBuffers.cpp:108

录制核心

  • RecordTraversal::apply(const View&) 进门先 dirtyStateStacks()——src/vsg/app/RecordTraversal.cpp:564
  • apply(const StateGroup&) 严格配对 state->push 与 state->pop——RecordTraversal.cpp:524
  • apply(const Command&) 先 state->record() 再 command.record(*(state->_commandBuffer))——RecordTraversal.cpp:547
  • apply(const VertexDraw&) 是 state->record() 的第一个调用点——RecordTraversal.cpp:339
  • apply(const Bin&) 只做 bin.traverse(*this),排序发生在 Bin 内部——RecordTraversal.cpp:551
  • apply(const CommandGraph&) 在 recordedCommandBuffers 为空时退化成 traverse——RecordTraversal.cpp:697
  • addToBin 用 bins[binNumber - minimumBinNumber] 裸下标,无边界检查——RecordTraversal.cpp:703
  • RecordTraversal 的 33 个 apply 从 Object 兜底到 CommandGraph——include/vsg/app/RecordTraversal.h:116
  • StateStack::record 用 stack[0] 当"上次实录"记忆槽——include/vsg/vk/State.h:79
  • StateStack::push 是 stack[++pos],pop 是 --pos——State.h:64
  • State::record() 只录到 activeMaxStateSlot,然后把它回落成 maxSlots.state——State.h:358
  • State::reserve 用 maxSlots.max() 决定 stateStacks 长度,只在变大时 resize——src/vsg/vk/State.cpp:30
  • State::connect 只标脏不清栈,pos 靠 push/pop 配对归零——State.cpp:50
  • State::inherit 先 reserve 再 reset,然后整块拷 stateStacks——State.cpp:79
  • ViewportState::slot 在构造函数里被赋成 8——src/vsg/state/ViewportState.cpp:21
  • BindViewDescriptorSets 的默认 slot 2 来自 Inherit(2)——src/vsg/state/ViewDependentState.cpp:106

帧边界与缓冲

  • CommandGraph::record 第一句是 getOrCreateRecordTraversal()——src/vsg/app/CommandGraph.cpp:87
  • CommandGraph::record 用 numDependentSubmissions() == 0 挑空闲缓冲——CommandGraph.cpp:98
  • 每个 CommandBuffer 配一个新 CommandPool——CommandGraph.cpp:106
  • vkBeginCommandBuffer 的返回值被丢弃——CommandGraph.cpp:130
  • CommandGraph::reset 是空函数体,重置语义全在 record 里——CommandGraph.cpp:61
  • CommandBuffer::reset 先清两个 CPU 缓存再判池标志——src/vsg/vk/CommandBuffer.cpp:45
  • CommandBuffer::reset 只取 pushConstantRanges.front() 的 stageFlags——CommandBuffer.cpp:68
  • RecordedCommandBuffers::buffers 用 lower_bound(0) 切出负/零/正三段——CommandBuffer.cpp:115
  • CommandPool::allocate 固定 commandBufferCount = 1——src/vsg/vk/CommandPool.cpp:50
  • CommandPool::reset 是 const 且不加锁——CommandPool.cpp:72
  • SecondaryCommandGraph::record 按连接数决定 SIMULTANEOUS_USE——src/vsg/app/SecondaryCommandGraph.cpp:125
  • inheritanceInfo 没有零初始化——SecondaryCommandGraph.cpp:127
  • inheritanceInfo.framebuffer 只有 framebuffer/window 两个分支——SecondaryCommandGraph.cpp:142
  • 二级图录完把缓冲交给每个 ExecuteCommands——SecondaryCommandGraph.cpp:161
  • ExecuteCommands::record 在加锁前 _latch->wait()——src/vsg/commands/ExecuteCommands.cpp:70
  • ExecuteCommands::completed 的 count_down() 在 if 之外——ExecuteCommands.cpp:65
  • Fence::resetFenceAndDependencies 用 exchange(0) 清依赖计数——src/vsg/vk/Fence.cpp:49
  • RenderGraph::accept 在录制路径上比较 previous_extent 并调 resized——src/vsg/app/RenderGraph.cpp:114
  • RenderGraph::accept 末尾 vkCmdEndRenderPass——RenderGraph.cpp:170
  • Viewer::recordAndSubmit 的 reset 循环只覆盖 commandGraphs——src/vsg/app/Viewer.cpp:827
  • Viewer 直接赋值 commandGraph->maxSlots,可能缩小——Viewer.cpp:365
  • RecordAndSubmitTask::assignCompileResult 用 update 合并 maxSlots——src/vsg/app/RecordAndSubmitTask.cpp:315
  • CollectResourceRequirements::apply(const StateCommand&) 只取 slot 的最大值——src/vsg/vk/ResourceRequirements.cpp:161

屏障与传输

  • PipelineBarrier::record 三次 allocate 后一次 release——src/vsg/commands/PipelineBarrier.cpp:95
  • PipelineBarrier::record 结尾清空整块 scratch——PipelineBarrier.cpp:128
  • ScratchMemory::allocate 在装不下时通过 next 链扩容——include/vsg/core/ScratchMemory.h:69
  • ScratchMemory::align 用 sizeof(p) 当对齐值——ScratchMemory.h:47
  • MemoryBarrier::assign 的 pNext 走递归分配——PipelineBarrier.cpp:25
  • WaitEvents::record 复制了 PipelineBarrier 的三段分配结构——src/vsg/commands/Event.cpp:109
  • CopyAndReleaseBuffer::record 里零屏障——src/vsg/commands/CopyAndReleaseBuffer.cpp:69
  • CopyAndReleaseImage::CopyData::record 全部委托 transferImageData——src/vsg/commands/CopyAndReleaseImage.cpp:168
  • 两个类的 Deprecated 注释指向 TransferTask——include/vsg/commands/CopyAndReleaseBuffer.h:23
  • TransferTask 自己 vkBeginCommandBuffer 一个独立缓冲——src/vsg/app/TransferTask.cpp:498

7.14 可复现验证

以下命令都在仓库根目录执行,输出应与注释一致。

验证 1:命令类的规模。

ls include/vsg/commands/*.h | wc -l          # 34:1 个基类 + 33 个派生
grep -L "state->record()" include/vsg/commands/*.h | wc -l

验证 2:state->record() 只出现在 7 个叶子 apply 里。

grep -n "state->record()" src/vsg/app/RecordTraversal.cpp
# 339 348 357 502 510 535 547,没有一处出现在 apply(const StateGroup&) 里

验证 3:Commands 与 RecordTraversal 的两份实现差一行。

sed -n '60,66p' src/vsg/commands/Commands.cpp
sed -n '531,540p' src/vsg/app/RecordTraversal.cpp

第二段多出 state->record()(:535),这是"8 个 draw 应用 1 次还是 8 次状态"的全部差别。

验证 4:vkBeginCommandBuffer 的返回值无人检查。

grep -rn "vkBeginCommandBuffer(" src --include=*.cpp     # 4 处调用
grep -rn "VkResult.*vkBeginCommandBuffer" src | wc -l    # 0

四处调用分别在 CommandGraph.cpp:130、SecondaryCommandGraph.cpp:152、TransferTask.cpp:498、Context.cpp:314。

验证 5:StateStack 的定长数组与 pos 的内存相邻。

sed -n '27,41p' include/vsg/vk/State.h     # STATESTACK_SIZE 16,std::array 与 size_t pos 相邻
sed -n '62,70p' include/vsg/vk/State.h     # push 是 stack[++pos],pop 是 --pos

std::array<const T*, 16> 是 128 字节,pos 紧随其后,所以 stack[16] 与 &pos 同址。用一个小程序可以复现:

vsg::State state(vsg::Slots{0, 0});                    // stateStacks.size() == 1
auto cmds = std::vector<vsg::ref_ptr<vsg::StateCommand>>(17);
for (int i = 0; i < 17; ++i) cmds[i] = vsg::BindGraphicsPipeline::create();

state.push(cmds.begin(), cmds.begin() + 15);           // pos == 15,安全
std::printf("pos=%zu\n", state.stateStacks[0].pos);
state.push(cmds.begin() + 15, cmds.begin() + 16);      // stack[16] == &pos
std::printf("pos=%zu\n", state.stateStacks[0].pos);   // 一个巨大的地址值

验证 6:inheritanceInfo 没有零初始化。

sed -n '122,128p' src/vsg/app/SecondaryCommandGraph.cpp   # beginInfo = {},inheritanceInfo 裸声明
sed -n '142,150p' src/vsg/app/SecondaryCommandGraph.cpp   # framebuffer 只有两个分支

用 SecondaryCommandGraph(device, family) 构造、在 record 里 printf("%p", (void*)inheritanceInfo.framebuffer),多次运行的输出不一致即为未初始化。

验证 7:每个 CommandBuffer 配一个新池。

grep -rn "CommandPool::create" src/vsg/app/CommandGraph.cpp   # :106,位于 if (!commandBuffer) 分支内
grep -rn "CommandPool::create" src/vsg/app/CompileTraversal.cpp  # 5 处,每个 Context 一套

CompileTraversal.cpp:69、88、118、154、258 各建一个池,说明"每 Context 一池"是全局约定,不只 CommandGraph 如此。

验证 8:ExecuteCommands 的 latch 顺序。

sed -n '68,73p' src/vsg/commands/ExecuteCommands.cpp   # wait() 在 scoped_lock 之前
sed -n '37,47p' src/vsg/commands/ExecuteCommands.cpp   # reset() 把 latch 设成连接数

把 wait() 挪到 scoped_lock 之后,任何多线程录制都会死锁——这是可以本地改一行验证的。

验证 9:屏障的真实数量。

grep -rn "vkCmdPipelineBarrier(" src --include=*.cpp    # 7 处
grep -rn "vkCmdPipelineBarrier(" src/vsg/app/TransferTask.cpp

TransferTask.cpp 占 5 处,PipelineBarrier.cpp:116 一处,Context.cpp:75 一处。整个命令层只有 1 处能发屏障,说明同步策略压在 render pass 上。

验证 10:Window 的一次性上传路径不带 RESET_COMMAND_BUFFER_BIT。

sed -n '404,407p' src/vsg/app/Window.cpp          # CommandPool::create(_device, graphicsFamily),flags 为 0
sed -n '29,43p' include/vsg/vk/SubmitCommands.h   # 每次 allocate 一个新缓冲,从不 reset

submitCommandsToQueue 每次调用都 commandPool->allocate()(SubmitCommands.h:31),却不 reset();由于池没带 RESET_COMMAND_BUFFER_BIT,这些缓冲也无法被缓冲级重置。它们只随池销毁而回收——每次窗口 resize 都往池里多留一个 VkCommandBuffer。这段代码自己标了 deprecated: use CommandGraph/Viewer instead(SubmitCommands.h:25)。

7.15 陷阱清单

陷阱触发条件后果源码坐标规避
同槽嵌套 16 层 StateCommand一个 StateGroup 放 8 个 GraphicsPipelineState 加 BindGraphicsPipeline,再嵌套两层pos 被指针值覆盖,随后段错误include/vsg/vk/State.h:64拆 StateGroup;别把 GraphicsPipelineState 放进 stateCommands
maxSlots 为 0 却用了 BindDescriptorSetState 以 {0,0} 建出来,之后没再 reservestateStacks[1] 越界写include/vsg/state/BindDescriptorSet.h:107保证 CompileTraversal 先跑;record 前必调 getOrCreateRecordTraversal
ViewportState 放在 View 外面手工把 ViewportState 塞进 StateGroupactiveMaxStateSlot 只到 maxSlots.state,slot 8 永不录制,viewport 静默失效include/vsg/vk/State.h:358只在 View 内或 RenderGraph 上用 viewport
池不带 RESET_COMMAND_BUFFER_BIT自己 CommandPool::create(device, family, 0) 再复用缓冲reset() 只清 CPU 缓存,缓冲停在 Executable,vkBeginCommandBuffer 返回 VK_NOT_READYsrc/vsg/vk/CommandBuffer.cpp:50只复用 CommandGraph 建的池,或显式带 flag
SecondaryCommandGraph(device, family) 构造既不设 framebuffer 也不设 windowinheritanceInfo.framebuffer 是未初始化栈值src/vsg/app/SecondaryCommandGraph.cpp:127改用窗口构造,或直接设 renderPass
窗口路径的 renderPass/framebuffer 组合用 window 分支且未启用 imagelessFramebuffer"renderPass 有效 + framebuffer 为空",严格实现报错SecondaryCommandGraph.cpp:149显式设 framebuffer,或启用 imageless 特性
subpass 传给空 renderPass 的二级图构造时 in_subpass != 0 但三者皆空违反 VUID,validation 报错SecondaryCommandGraph.cpp:140subpass 保持 0,除非确实在 renderPass 内
SIMULTANEOUS_USE 只在连接数 >1 时设同一个 ExecuteCommands 节点在场景图里被访问两次二级缓冲被引用多次却没设 flag,非法SecondaryCommandGraph.cpp:125让一个 ExecuteCommands 只挂一处
二级图 record 抛异常录制中途 bad_alloc 或设备丢失completed() 不执行,latch 不减到 0,主线程永久阻塞src/vsg/commands/ExecuteCommands.cpp:65在 record 外包 try/catch 并手工 count_down
二级图不在 commandGraphs 里主图持 ExecuteCommands、ExecuteCommands 持二级图reset() 不被调用,vkCmdExecuteCommands 用上一帧的缓冲src/vsg/app/Viewer.cpp:827把二级图也放进 recordAndSubmitTask->commandGraphs
viewportState 被多个 RenderGraph 共用同一个 ViewportState 既作 pipeline 静态状态又被 accept 调 set静态 viewport 被录制路径改动src/vsg/app/RenderGraph.cpp:153每个 RenderGraph 用独立 ViewportState
viewportStateHint 跨 RenderGraph 泄漏第一个图 DYNAMIC、第二个 STATIC后续 view 不再 push viewport,分屏后半段全错src/vsg/vk/State.cpp:68在 accept 结束处还原 hint
嵌套 View一个 View 里再挂一个 ViewsetProjectionAndViewMatrix 覆盖外层投影,画面错但不崩include/vsg/vk/State.h:114多视图用多个 CommandGraph,不嵌 View
DepthSorted 的 binNumber 不在 view.bins 里运行时加一个 binNumber = 5 的节点,而 view.bins 只有 0 与 -1bins[...] 越界;或命中的是空 ref_ptr 而解引用空指针src/vsg/app/RecordTraversal.cpp:703用 ResourceRequirements 补齐 bin,或先 addChild 再编译
Commands 里塞了改状态的命令把调 setCurrentPipelineLayout 的命令放进 Commands同批次后续命令用旧 pipeline layoutsrc/vsg/commands/Commands.cpp:60Commands 只装纯命令;改状态用 StateGroup
把 CopyAndRelease* 当主传输路径照 Context::copy 写上传代码零屏障 + staging 引用只活 1 帧,可能数据竞争src/vsg/commands/CopyAndReleaseBuffer.cpp:69用 TransferTask 与 Data::dirty()
跨 record 持有 scratch 指针在 PipelineBarrier::record 之后继续用 scratchMemory 里的结构体release() 已清空整块内存,指针悬垂src/vsg/commands/PipelineBarrier.cpp:128只在一次 record 内使用 scratch
自定义 shader 挪动 push constant offset把 modelview 放到 offset 128,或让 layout 有多个 rangeMatrixStack 仍按 0/64 发常量,矩阵写错位置src/vsg/vk/CommandBuffer.cpp:68保持 projection=0、modelview=64,且 range 覆盖顶点段
重复 connect 同一个 ExecuteCommands对同一对图调两次 connect_disconnect 只删一个,SIMULTANEOUS_USE 误判,latch 被 set 两次src/vsg/app/SecondaryCommandGraph.cpp:56连接关系只建一次,改图时先断开
用 submitCommandsToQueue 做周期上传每帧或每次 resize 调一次池不带 RESET bit 且从不 reset,每次泄漏一个 VkCommandBufferinclude/vsg/vk/SubmitCommands.h:31换 TransferTask;该函数已标 deprecated
改动 StateStack 的三个巧合把 pos 初值改成 -1,或把 stack[0] 拆成独立成员未初始化的 stack 从"安全"变成真 buginclude/vsg/vk/State.h:40改结构时同步给 stack 加 {} 初始化
Scan 阶段把 Commands 当 Group 用想给 Commands 挂 StateGroup 孩子编译不过(Children 是 ref_ptr<Command>),退化成手工展开include/vsg/commands/Commands.h:49需要状态就换 Group + StateGroup

7.16 批判性结论

把这一层从头读到尾,可以得到十二条可以独立验证的判断。它们不是复述前文,而是把前文的证据压成结论,并指出每条结论的代价落在谁身上。

一、命令层不是抽象层,是虚函数入口层。 33 个命令类里 15 个的 record 只有一行,Draw::record 直接在头文件里展开成一次 vkCmdDraw(include/vsg/commands/Draw.h:41),BindVertexBuffers::record 只做一次 _vulkanData 索引加一次 vkCmdBindVertexBuffers(src/vsg/commands/BindVertexBuffers.cpp:111)。真正的状态抽象在 State、StateGroup、CommandGraph,不在 vsg::commands 命名空间。这个分层的收益是命令类可以被机械生成、序列化、比较;代价是"读命令类"几乎学不到任何渲染知识——想知道一帧怎么组织,必须跳到 7.6 与 7.9。

二、同一个 Commands 有两条语义不同的入口,而没有任何机制阻止混用。 Commands::record 不应用状态(src/vsg/commands/Commands.cpp:62),RecordTraversal::apply(const Commands&) 应用一次(src/vsg/app/RecordTraversal.cpp:535)。编译期走前者是对的(那里没有 State),帧期走后者也是对的;但两者都叫 record,签名兼容,嵌套时后者退化成的正是前者。这个设计把"我是否在 RecordTraversal 里"变成了一个隐式参数,读代码的人必须靠调用栈判断。

三、"不检查返回值"在这层是系统性的,而且后果被转移给了 validation layer。 全库 4 处 vkBeginCommandBuffer、4 处 vkEndCommandBuffer,零处检查(src/vsg/app/CommandGraph.cpp:130、src/vsg/app/SecondaryCommandGraph.cpp:152、src/vsg/app/TransferTask.cpp:498、src/vsg/vk/Context.cpp:314)。状态机的正确性完全由四条分配不变量维持,其中最脆弱的是"池一定带 RESET_COMMAND_BUFFER_BIT"——这条不变量在 CommandGraph::record 里成立(CommandGraph.cpp:106),在 Window 的一次性上传路径里不成立(src/vsg/app/Window.cpp:406)。后者之所以没出事,只是因为 submitCommandsToQueue 从不复用缓冲,而是每次新分配一个(include/vsg/vk/SubmitCommands.h:31)。同一套 API 里,一条不变量在一处被违反却没被发现,说明它不是不变量,只是巧合。

四、StateStack 是全章唯一会立刻崩的地方,而它的安全性建立在三个巧合上。 push 是 stack[++pos](include/vsg/vk/State.h:64),stack 是 16 元素定长数组,pos 紧随其后。第 16 次同槽 push 把指针写进 pos,下一次访问就是野地址。更微妙的是"未初始化也安全"的论证:pos 初值 0(State.h:40)、record 用 stack[0] 兼作记忆槽(State.h:79)、push 先自增后写。三者任意一个被"整理",都会把安全变成未定义行为。这类代码的问题不在于它错了,而在于它对了却没有留下任何理由。

五、maxSlots 的四跳传播链是这一层最脆弱的隐式契约。 CollectResourceRequirements::apply(const StateCommand&) 取最大 slot(src/vsg/vk/ResourceRequirements.cpp:161),RecordAndSubmitTask 用 update 合并(src/vsg/app/RecordAndSubmitTask.cpp:315),CommandGraph::getOrCreateRecordTraversal 用它建或扩 State(src/vsg/app/CommandGraph.cpp:69),State::reserve 决定 stateStacks 长度(src/vsg/vk/State.cpp:31)。任何一环断了,高 slot 命令要么静默不录(activeMaxStateSlot 回落),要么越界写。而 Viewer.cpp:365 用赋值而不是 update,让"只增不减"的聚合在最后一跳变成"可能缩小"。契约本身没错,错在它跨了四个文件却只靠一条注释维系。

六、二级缓冲的三个问题里,只有第一个是真 bug,另外两个是"依赖驱动宽容"。 inheritanceInfo 未零初始化(SecondaryCommandGraph.cpp:127)是确定的未定义行为;renderPass 有效而 framebuffer 为空依赖 VK_KHR_imageless_framebuffer,而 VSG 没有启用该特性(DeviceFeatures.cpp 里搜不到 imagelessFramebuffer);subpass 非 0 配空 renderPass 只在用户显式传参时发生(SecondaryCommandGraph.h:30)。后两者之所以"能用",是因为主流驱动对 VK_NULL_HANDLE 宽容。把"能跑"当成"正确",是这一层最常见的自我欺骗。

七、ExecuteCommands 的 latch 是唯一跨线程同步点,它的正确性依赖三条不成文的约定。 wait() 必须在加锁之前(src/vsg/commands/ExecuteCommands.cpp:70),count_down() 必须在 if 之外(ExecuteCommands.cpp:65),reset() 必须每帧先于 submit 执行(src/vsg/app/Viewer.cpp:829)。第三条还依赖"二级图在 commandGraphs 列表里",而常见装配方式恰好不满足。三条约定里没有一条写进注释,任意一条被"整理"都会变成死锁或读到上一帧的缓冲。

八、每缓冲一池是可测量浪费,但真正的问题不是内存。 CommandGraph.h:59 的注释自己写了 "assign one per index? Or just use round robin, each has a CommandPool",说明作者清楚。4 窗口 16 图的配置下 32–48 个池(CommandGraph.cpp:106),每个池带独立锁与 chunk。浪费几 MB 不致命,致命的是池数随图数线性增长而 _commandBuffers 只增不减(CommandGraph.cpp:108):在飞帧数从 3 涨到 8 之后,8 个缓冲与 8 个池会永久保留。

九、传输路径的正名是本章最重要的一次纠正。 CopyAndReleaseBuffer 与 CopyAndReleaseImage 的 record 都是零显式屏障(CopyAndReleaseBuffer.cpp:69),差异全在 transferImageData 的 2N 条屏障(src/vsg/app/TransferTask.cpp:670)。而这两个类都已标 Deprecated(include/vsg/commands/CopyAndReleaseBuffer.h:23),in-tree 无调用者。真正的路径是 TransferTask,它有自己的命令缓冲、自己的 begin/end(TransferTask.cpp:498)。任何按 CopyAndRelease* 理解 VSG 同步策略的推论都会错。

十、屏障只有 7 处,是把同步押在 render pass 上,而不是"同步做得好"。 TransferTask.cpp 5 处、PipelineBarrier.cpp:116 一处、Context.cpp:75 一处。render pass 的隐式布局转换确实更快,但代价是:render pass 之外的任何跨阶段依赖都要手写屏障,而 VSG 没有提供"忘记写屏障"的检测。CopyAndReleaseBuffer 零屏障能活到今天,正是因为它是死代码——没被运行的错误代码不是安全,是未验证。

十一、State::dirty 的粗粒度是刻意的,代价落在按槽比较上。 一个 bool 标脏全部槽位(include/vsg/vk/State.h:275),record() 循环到 activeMaxStateSlot(State.h:352),每槽靠 stack[0] 记忆去重。5,000 draw 的帧里约 200 μs 花在这里(7.12.3)。若改成按槽的脏位,比较次数能从 9 次降到 1 次,但标脏路径会从一次赋值变成一次位运算加一次边界检查——省下的是比较,付出的是每条 StateCommand 的写入成本。VSG 选了"标脏便宜、录制精确",这个取舍在命令数远大于槽数的场景里是对的。

十二、这一层的设计哲学可以一句话概括:薄封装 + 强约定 + 零检查。 薄到 15 个类只有一行 record;强到只要按 Viewer 的流程走就不会出事;零检查到所有错误都表现为"画面不对"而不是"报错退出"。它的收益是 API 面积小、编译期开销低、易序列化;代价是所有正确性知识都只存在于源码里,不存在于类型、断言或文档中。这一章写的每一条坐标,本质上都是在替这份缺失的文档补页。

如果要给这一层打分:作为"Vulkan 命令的薄封装"它合格,甚至优雅;作为"可被第三方安全扩展的框架",它不合格——Command 是公开可派生的,但派生者需要的全部契约(compile 先行、record 不改状态、StateGroup 内 slot 不越界、maxSlots 要报备)都没有任何机制强制。VSG 把复杂度从 API 转移到了使用者的记忆里,这对框架作者是效率,对框架用户是负债。

帧与帧之间还有三条调度层判断。

十三、提交层逐步检查 VkResult,录制层却丢弃返回值——同一条链上两种相反的错误文化。 RecordAndSubmitTask::submit 把 start()、传输、record()、finish() 每步的 VkResult 接住,!= VK_SUCCESS 就返回(src/vsg/app/RecordAndSubmitTask.cpp:91、RecordAndSubmitTask.cpp:111);它调用的 CommandGraph::record 却是 void,vkBeginCommandBuffer 的返回值当场丢掉(src/vsg/app/CommandGraph.cpp:130)。提交层的码只覆盖任务级错误,帧内 vkCmd* 的状态错误在 void 签名处被抹掉——一次 begin 失败在日志里表现为"录制成功",只能靠画面异常反推。

十四、帧槽用 numBuffers 自身当"尚未 advance"的哨兵。 RecordAndSubmitTask 构造把 _currentFrameIndex 与 _indices 每个元素都填成 numBuffers(src/vsg/app/RecordAndSubmitTask.cpp:26、RecordAndSubmitTask.cpp:29),首帧判据是 _currentFrameIndex >= _indices.size()(RecordAndSubmitTask.cpp:52)。合法槽号是 0..numBuffers-1,所以 numBuffers 天然非法——它既表示"没开始"又等于数组长度。同类哨兵见于 ExecuteCommands:latch 初值 0(src/vsg/commands/ExecuteCommands.cpp:18)让未连接时 record 的 wait() 不阻塞。

十五、ExecuteCommands 的析构主动注销反向指针,让"元素持有容器"安全落地。 ~ExecuteCommands 遍历 _commandGraphsAndBuffers,逐项调 entry.cg->_disconnect(this)(src/vsg/commands/ExecuteCommands.cpp:27)。这是 7.7.2 坑 4 里"二级图只存裸 ExecuteCommands*"不悬垂的原因:容器持强 ref_ptr,元素靠析构主动注销。这里没有 weak_ptr,安全全靠 connect 与 _disconnect 对称;漏掉一处注销就留下悬垂裸指针,而该类公开可派生,对称性没有类型保护。

7.17 答案骨架

如果只读这一节,应该带走以下九条。每条都能在上文找到证据,也都能在源码里复核。

  1. 命令类是薄壳。 Command 只有一个纯虚函数(include/vsg/commands/Command.h:29),33 个派生类里 15 个 record 只有一行;抽象在 State 层。
  2. Commands 的收益是状态应用次数减 N-1。 代价是它只装 ref_ptr<Command>(Commands.h:49),且嵌套时不再应用状态(Commands.cpp:62)。
  3. CommandBuffer 是录制的唯一上下文。 17 个成员里 8 个是遍历上下文(include/vsg/vk/CommandBuffer.h:40),因为 record 只拿得到它。
  4. 状态机不检查,靠分配策略。 4 处 vkBeginCommandBuffer、0 处检查(src/vsg/app/CommandGraph.cpp:130);正确性来自"新缓冲 Initial、复用先 reset、池带 flag、每帧只 begin 一次"。
  5. StateStack 是定长 16 的无检查栈。 第 16 次同槽 push 覆盖 pos(include/vsg/vk/State.h:64),这是全章唯一会立刻段错误的地方。
  6. maxSlots 决定 stateStacks 长度。 它经四跳传到 State::reserve(src/vsg/vk/State.cpp:31),任何一环缺失都导致越界或静默失效。
  7. 二级缓冲的 inheritanceInfo 未零初始化。 device+family 构造路径下 framebuffer 是野值(src/vsg/app/SecondaryCommandGraph.cpp:127)。
  8. 多线程录制的唯一同步点是 latch。 wait() 在锁外(src/vsg/commands/ExecuteCommands.cpp:70),异常会永久阻塞。
  9. CopyAndRelease* 是死代码,真正的传输路径是 TransferTask。 前者零屏障(CopyAndReleaseBuffer.cpp:69),后者自带命令缓冲与 5 处屏障(src/vsg/app/TransferTask.cpp:670)。

一句话版本:先看 CommandGraph::record,再看 State::record,最后看 RecordTraversal::apply(const View&);其余 5,000 行都是这三处的外围。

7.18 阅读路线

按目的分三条路线,字数按中文字符估。

路线 A:15 分钟,只要结论。 读 7.0 的六个缺陷清单,再读 7.17 的九条,最后读 7.15 的表格。跳过所有代码块。收获是"知道哪里会踩",代价是不知道"为什么"。

路线 B:两小时,读实现。 顺序是 7.1.1(Command 的全部代码)→ 7.2.3(两份 record 的差异)→ 7.3.2(reset 的两条路径)→ 7.4.2(begin/end 不检查)→ 7.6.3(record 五阶段)→ 7.8.3(stack[0] 记忆槽)→ 7.9.2(第 16 次 push)。这条线走完,能独立回答"为什么复用缓冲前必须 reset"与"为什么 Commands 里不能塞状态命令"。

路线 C:半天,改代码前必读。 在上面基础上加 7.5.2(每缓冲一池)、7.7.3(latch 三约定)、7.9.4(maxSlots 四跳)、7.9.6(Viewer.cpp:365 可缩)、7.11.4(CopyAndRelease* 死代码)。这五处是"改动会出事"的高危区:它们都由跨文件的隐式约定维持,改一处而不改另一处,症状是黑屏或数据竞争,而不是编译错误。

三条路线都不读的部分:7.10.4(ScratchMemory 对齐细节)、7.12(数字汇总)、7.13(索引表)。它们只在需要引用具体数字或坐标时查。

7.19 下章预告

命令层结束了。下一个问题是:这些命令从哪来?

Commands 里的 Draw 不是手写的,它们由 StateGroup + Geometry + VertexIndexDraw 组成,而这些节点由 Builder / 加载器生成。第八章 状态与状态图:StateGroup / StateCommand / Pipeline 要回答:

  • StateGroup 的 stateCommands 为什么是 vector<ref_ptr<StateCommand>> 而不是 vector<ref_ptr<Command>>?
  • StateCommand::slot 的 5 个赋值点之外,还有谁在改 slot?
  • Pipeline 的 compile 为什么要按 viewID 建多个实现?GraphicsPipeline::_implementation 是一个 vector,索引是什么?
  • DescriptorSet 的 compile 在 context.scratchMemory 里分配 VkWriteDescriptorSet 数组,然后 release()——如果同一个 Context 里有两个 DescriptorSet 要编译,第二次的分配会覆盖第一次吗?
  • ResourceHints 的 maxSlots 与 ResourceRequirements 的 maxSlots 是什么关系?为什么前者是"提示"后者是"需求"?
  • StateSwitch 怎么在运行时切换状态?

以及本章留下的三个悬念:

  • ExecuteCommands::record 的 _latch->wait() 在 std::scoped_lock 之前——如果重排会死锁,这个顺序有没有被文档化?
  • StateStack 的 stack[0] 记忆槽在 pop() 后不更新,这个"恰好正确"的依赖链有多长?
  • Viewer::recordAndSubmit 的 reset 循环只覆盖 commandGraphs,二级图不在里面——那 ExecuteCommands 的 latch 是谁在重置?