《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::record65 行:src/vsg/app/CommandGraph.cpp:76,函数体从CPU_INSTRUMENTATION_L1_NC起算。SecondaryCommandGraph::record89 行: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 ResetEvent | 15 |
2–8 行(一次 vkCmd* + 参数整理) | CopyImage BlitImage ResolveImage ClearImage CopyImageToBuffer BindIndexBuffer BindVertexBuffers ClearAttachments CopyQueryPoolResults CopyImageViewToWindow DrawIndirect DrawIndexedIndirect | 12 |
10–30 行(多次 vkCmd* 或多分支) | PipelineBarrier WaitEvents DrawIndexedIndirectCommand ExecuteCommands Commands CopyAndReleaseImage | 6 |
33 个类里 15 个的 record 只有一行。命令层不是"对 Vulkan 的抽象",而是"给 Vulkan 调用加了一个虚函数入口";抽象发生在上层(State / StateGroup / CommandGraph),不发生在命令层。
六个可以直接定位的缺陷,本章逐一给证据:
SecondaryCommandGraph::record的VkCommandBufferInheritanceInfo没有零初始化(src/vsg/app/SecondaryCommandGraph.cpp:127),device+family构造路径下framebuffer字段是未初始化栈值。StateStack::push是stack[++pos],而stack是std::array<const T*, STATESTACK_SIZE>(include/vsg/vk/State.h:64),同槽第 16 次 push 写到pos自己的内存上。CommandBuffer::reset()无条件清 CPU 侧缓存,却只在池带RESET_COMMAND_BUFFER_BIT时vkResetCommandBuffer(src/vsg/vk/CommandBuffer.cpp:45)。CommandGraph::record每需要新缓冲就CommandPool::create一个新池(src/vsg/app/CommandGraph.cpp:106),而_commandBuffers永不收缩(CommandGraph.cpp:108)。CopyAndReleaseBuffer::record一条屏障都不发(src/vsg/commands/CopyAndReleaseBuffer.cpp:69),CopyAndReleaseImage则在transferImageData里发2 + 2×(mips-1)条;上一章预告里"一次 vs 两次"的说法是错的。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 持有、被序列化) |
Node | accept(Visitor&) 三个重载、traverse、mask | 需要(能挂进场景图) |
Compilable | virtual void compile(Context&) {}(空实现) | 需要,但语义可疑 |
Command | virtual 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,大量实现改了对象内部状态:
| 类 | 被修改的成员 | 手段 |
|---|---|---|
PipelineBarrier | commandBuffer.scratchMemory(外部对象) | 不需要 mutable,只改参数 |
CopyAndReleaseImage | _pending、_completed、_readyToClear | mutable std::vector<CopyData>(include/vsg/commands/CopyAndReleaseImage.h:66) |
ExecuteCommands | _latch、_commandGraphsAndBuffers[i].cb | mutable std::mutex(include/vsg/commands/ExecuteCommands.h:48) |
Event::WaitEvents | commandBuffer.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* 上的虚调用链就断了。
这个谎言有三处实际代价:
- 线程安全靠约定,不靠类型。 两个线程同时
record同一个CopyAndReleaseImage不会编译报错,只靠_mutex兜住;PipelineBarrier没加锁,它只写commandBuffer.scratchMemory——不同命令缓冲是两份 scratch,安全;同一命令缓冲被两个线程录就不安全。 compare覆盖不到运行时状态。_pending里的待拷贝项不属于"对象身份",却决定record行为。序列化一个"还有待拷贝项"的CopyAndReleaseImage会丢掉它们,反序列化后它什么都不做。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() 都是一次虚跳转),而在两件事:
state->record()从 8 次变 1 次。dirty == false时每次几个纳秒;dirty == true时每次是activeMaxStateSlot + 1次槽位比较加可能的vkCmd*。- 少 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 的 Draw | Commands | 省 N-1 次 state->record() |
一批需要各自 BindDescriptorSet 的 draw | Group + StateGroup | Commands 装不下 StateCommand |
一批纯传输命令(CopyImage、PipelineBarrier) | Commands | 无状态,纯粹少一层 accept |
| 需要在 draw 之间切 pipeline | 拆成多个 StateGroup | Commands 不处理状态 |
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 四个状态
| 状态 | 进入方式 | 允许的操作 |
|---|---|---|
| Initial | vkAllocateCommandBuffers 之后 | vkBeginCommandBuffer |
| Recording | vkBeginCommandBuffer 成功后 | vkCmd*、vkEndCommandBuffer |
| Executable | vkEndCommandBuffer 成功后 | 提交、作为二级被 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 靠四条不变量:
- 新缓冲一定是 Initial——
CommandPool::allocate刚vkAllocateCommandBuffers出来(src/vsg/vk/CommandPool.cpp:54)。 - 复用缓冲一定先
reset()——CommandGraph.cpp:112的commandBuffer->reset()。 reset()一定成功——因为池带RESET_COMMAND_BUFFER_BIT。- 每个缓冲每帧只
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_BIT | CommandGraph::record(CommandGraph.cpp:127)、Context::record(Context.cpp:312) | 这个缓冲只被提交一次,之后会 reset |
RENDER_PASS_CONTINUE_BIT | SecondaryCommandGraph::record(SecondaryCommandGraph.cpp:124) | 二级缓冲在 render pass 内部执行 |
SIMULTANEOUS_USE_BIT | SecondaryCommandGraph::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 Bin | traverse |
| 剔除节点 | CullGroup CullNode Switch LOD PagedLOD | 判断后 traverse |
| 变换节点 | Transform MatrixTransform CoordinateFrame | 压矩阵栈 + traverse + 弹栈 |
| 叶子几何 | VertexDraw VertexIndexDraw Geometry | state->record() + record |
| 实例化 | InstanceNode InstanceDraw InstanceDrawIndexed | 设 instanceNode 后 state->record() + record |
| 状态 | StateGroup | push + traverse + pop |
| 命令 | Command Commands | state->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 的结果:
| 行号 | 上下文 |
|---|---|
| 339 | apply(const VertexDraw&) |
| 348 | apply(const VertexIndexDraw&) |
| 357 | apply(const Geometry&) |
| 502 | apply(const InstanceDraw&) |
| 510 | apply(const InstanceDrawIndexed&) |
| 535 | apply(const Commands&) |
| 547 | apply(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 / ROI | cached_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 | 接管 viewDependentState | clear() + LODScale = view.LODScale(:604) | 光照列表每帧重建 |
| 6 | push 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 等子树 |
| 10 | pop view 级状态 | state->popView(view)(:651) | — |
| 11 | 录 bin | for (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_firstSet | include/vsg/state/BindDescriptorSet.h:31 |
BindDescriptorSets(默认构造) | 1 | BindDescriptorSet.h:40 |
BindDescriptorSet(firstSet 版) | 1 + in_firstSet | BindDescriptorSet.h:98、117 |
BindDescriptorSet(默认构造) | 1 | BindDescriptorSet.h:107 |
ViewportState | 8 | src/vsg/state/ViewportState.cpp:21 |
BindViewDescriptorSets 的默认 slot 由基类构造传入 Inherit(2)(src/vsg/state/ViewDependentState.cpp:106)。其余 StateCommand 派生类(BindGraphicsPipeline、BindVertexBuffers、BindIndexBuffer、PushConstants……)都是 slot 0。
这揭示了一个没写进文档的编号方案:
| slot | 用途 |
|---|---|
| 0 | pipeline 绑定 + 顶点/索引缓冲绑定 + push constants |
| 1 | descriptor set 0 |
| 2 | view descriptor set(光照) |
| 3+ | descriptor set 1, 2, ... |
| 8 | viewport/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.cpp | 5 | 图像上传前后的布局转换(:670、799、834、851、874) |
PipelineBarrier.cpp | 1 | PipelineBarrier 命令本体(:116) |
Context.cpp | 1 | 光线追踪构建后的内存屏障(: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, ©Region);
}
// 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 里的显式屏障 | 被调用函数里的屏障 | 总计 |
|---|---|---|---|
| buffer | 0 | 0 | 0 |
| image(单 mip) | 0 | 2 | 2 |
| image(N mip,生成 mipmap) | 0 | 2 + 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 派生类 | 33 | include/vsg/commands/ 下 34 个头文件减 1 个基类 |
record 只有 1 行的类 | 15 | 逐个读头文件统计 |
RecordTraversal::apply 重载 | 33 | include/vsg/app/RecordTraversal.h:116–166 |
state->record() 调用点 | 7 | src/vsg/app/RecordTraversal.cpp 的 339/348/357/502/510/535/547 |
vkBeginCommandBuffer 调用点 | 4 | CommandGraph.cpp:130、SecondaryCommandGraph.cpp:152、TransferTask.cpp:498、Context.cpp:314 |
vkBeginCommandBuffer 返回值检查 | 0 | 同上四处 |
显式设定 slot 的位置 | 5 | BindDescriptorSet.h:31、40、98、107、117 |
vkCmdPipelineBarrier 调用点(全库) | 7 | TransferTask.cpp 5 处 + PipelineBarrier.cpp:116 + Context.cpp:75 |
7.12.2 关键常量
| 常量 | 值 | 位置 | 影响 |
|---|---|---|---|
STATESTACK_SIZE | 16 | include/vsg/vk/State.h:28 | 同槽 16 次 push 越界 |
POLYTOPE_SIZE | 5 | include/vsg/vk/State.h:27 | frustum 5 个面(无近平面,State.h:194) |
ScratchMemory 初始大小 | 4096 | src/vsg/vk/CommandBuffer.cpp:27 | 约 20 条带 pNext 的屏障 |
MatrixStack projection offset | 0 | include/vsg/vk/State.h:289 | 硬编码 |
MatrixStack modelview offset | 64 | include/vsg/vk/State.h:290 | 硬编码 |
ViewportState::slot | 8 | src/vsg/state/ViewportState.cpp:21 | 魔法数字 |
BindViewDescriptorSets::slot(默认) | 2 | src/vsg/state/ViewDependentState.cpp:106 | 与 descriptor set 1 抢编号 |
7.12.3 每帧的 CPU 开销估算(5,000 draw,单核)
| 阶段 | 操作数 | 单次成本 | 小计 |
|---|---|---|---|
accept 分发 | 5,000 | ~5 ns | 25 μs |
state->record()(dirty) | 5,000 | ~40 ns(9 槽比较) | 200 μs |
state->record()(clean) | 5,000 | ~2 ns | 10 μs |
Draw::record | 5,000 | ~30 ns | 150 μs |
StateGroup push/pop | 1,000 × 2 × 2 | ~20 ns | 80 μs |
vkCmdBindDescriptorSets | 1,000 | ~60 ns | 60 μs |
vkCmdBindVertexBuffers | 1,000 | ~50 ns | 50 μ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:29Command的基类是Compilable,不是Node——Command.h:22Compilable::compile默认空实现,是整个编译遍历的落点——include/vsg/nodes/Compilable.h:29Commands::children的元素类型被钉死为ref_ptr<Command>——include/vsg/commands/Commands.h:48Commands::record不调state->record(),只做转发——src/vsg/commands/Commands.cpp:60Commands::compile直接递归孩子,绕开accept——Commands.cpp:52Commands::compare比的是孩子指针容器,不是内容——Commands.cpp:35Draw::record内联在头文件里,一行vkCmdDraw——include/vsg/commands/Draw.h:39BindVertexBuffers::record只有一次vkCmdBindVertexBuffers,缓冲数组来自_vulkanData——src/vsg/commands/BindVertexBuffers.cpp:108
录制核心
RecordTraversal::apply(const View&)进门先dirtyStateStacks()——src/vsg/app/RecordTraversal.cpp:564apply(const StateGroup&)严格配对state->push与state->pop——RecordTraversal.cpp:524apply(const Command&)先state->record()再command.record(*(state->_commandBuffer))——RecordTraversal.cpp:547apply(const VertexDraw&)是state->record()的第一个调用点——RecordTraversal.cpp:339apply(const Bin&)只做bin.traverse(*this),排序发生在Bin内部——RecordTraversal.cpp:551apply(const CommandGraph&)在recordedCommandBuffers为空时退化成traverse——RecordTraversal.cpp:697addToBin用bins[binNumber - minimumBinNumber]裸下标,无边界检查——RecordTraversal.cpp:703RecordTraversal的 33 个apply从Object兜底到CommandGraph——include/vsg/app/RecordTraversal.h:116StateStack::record用stack[0]当"上次实录"记忆槽——include/vsg/vk/State.h:79StateStack::push是stack[++pos],pop是--pos——State.h:64State::record()只录到activeMaxStateSlot,然后把它回落成maxSlots.state——State.h:358State::reserve用maxSlots.max()决定stateStacks长度,只在变大时resize——src/vsg/vk/State.cpp:30State::connect只标脏不清栈,pos靠 push/pop 配对归零——State.cpp:50State::inherit先reserve再reset,然后整块拷stateStacks——State.cpp:79ViewportState::slot在构造函数里被赋成 8——src/vsg/state/ViewportState.cpp:21BindViewDescriptorSets的默认 slot 2 来自Inherit(2)——src/vsg/state/ViewDependentState.cpp:106
帧边界与缓冲
CommandGraph::record第一句是getOrCreateRecordTraversal()——src/vsg/app/CommandGraph.cpp:87CommandGraph::record用numDependentSubmissions() == 0挑空闲缓冲——CommandGraph.cpp:98- 每个
CommandBuffer配一个新CommandPool——CommandGraph.cpp:106 vkBeginCommandBuffer的返回值被丢弃——CommandGraph.cpp:130CommandGraph::reset是空函数体,重置语义全在record里——CommandGraph.cpp:61CommandBuffer::reset先清两个 CPU 缓存再判池标志——src/vsg/vk/CommandBuffer.cpp:45CommandBuffer::reset只取pushConstantRanges.front()的 stageFlags——CommandBuffer.cpp:68RecordedCommandBuffers::buffers用lower_bound(0)切出负/零/正三段——CommandBuffer.cpp:115CommandPool::allocate固定commandBufferCount = 1——src/vsg/vk/CommandPool.cpp:50CommandPool::reset是const且不加锁——CommandPool.cpp:72SecondaryCommandGraph::record按连接数决定SIMULTANEOUS_USE——src/vsg/app/SecondaryCommandGraph.cpp:125inheritanceInfo没有零初始化——SecondaryCommandGraph.cpp:127inheritanceInfo.framebuffer只有framebuffer/window两个分支——SecondaryCommandGraph.cpp:142- 二级图录完把缓冲交给每个
ExecuteCommands——SecondaryCommandGraph.cpp:161 ExecuteCommands::record在加锁前_latch->wait()——src/vsg/commands/ExecuteCommands.cpp:70ExecuteCommands::completed的count_down()在if之外——ExecuteCommands.cpp:65Fence::resetFenceAndDependencies用exchange(0)清依赖计数——src/vsg/vk/Fence.cpp:49RenderGraph::accept在录制路径上比较previous_extent并调resized——src/vsg/app/RenderGraph.cpp:114RenderGraph::accept末尾vkCmdEndRenderPass——RenderGraph.cpp:170Viewer::recordAndSubmit的 reset 循环只覆盖commandGraphs——src/vsg/app/Viewer.cpp:827Viewer直接赋值commandGraph->maxSlots,可能缩小——Viewer.cpp:365RecordAndSubmitTask::assignCompileResult用update合并maxSlots——src/vsg/app/RecordAndSubmitTask.cpp:315CollectResourceRequirements::apply(const StateCommand&)只取slot的最大值——src/vsg/vk/ResourceRequirements.cpp:161
屏障与传输
PipelineBarrier::record三次allocate后一次release——src/vsg/commands/PipelineBarrier.cpp:95PipelineBarrier::record结尾清空整块 scratch——PipelineBarrier.cpp:128ScratchMemory::allocate在装不下时通过next链扩容——include/vsg/core/ScratchMemory.h:69ScratchMemory::align用sizeof(p)当对齐值——ScratchMemory.h:47MemoryBarrier::assign的pNext走递归分配——PipelineBarrier.cpp:25WaitEvents::record复制了PipelineBarrier的三段分配结构——src/vsg/commands/Event.cpp:109CopyAndReleaseBuffer::record里零屏障——src/vsg/commands/CopyAndReleaseBuffer.cpp:69CopyAndReleaseImage::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 却用了 BindDescriptorSet | State 以 {0,0} 建出来,之后没再 reserve | stateStacks[1] 越界写 | include/vsg/state/BindDescriptorSet.h:107 | 保证 CompileTraversal 先跑;record 前必调 getOrCreateRecordTraversal |
ViewportState 放在 View 外面 | 手工把 ViewportState 塞进 StateGroup | activeMaxStateSlot 只到 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_READY | src/vsg/vk/CommandBuffer.cpp:50 | 只复用 CommandGraph 建的池,或显式带 flag |
SecondaryCommandGraph(device, family) 构造 | 既不设 framebuffer 也不设 window | inheritanceInfo.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:140 | subpass 保持 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 里再挂一个 View | setProjectionAndViewMatrix 覆盖外层投影,画面错但不崩 | include/vsg/vk/State.h:114 | 多视图用多个 CommandGraph,不嵌 View |
DepthSorted 的 binNumber 不在 view.bins 里 | 运行时加一个 binNumber = 5 的节点,而 view.bins 只有 0 与 -1 | bins[...] 越界;或命中的是空 ref_ptr 而解引用空指针 | src/vsg/app/RecordTraversal.cpp:703 | 用 ResourceRequirements 补齐 bin,或先 addChild 再编译 |
Commands 里塞了改状态的命令 | 把调 setCurrentPipelineLayout 的命令放进 Commands | 同批次后续命令用旧 pipeline layout | src/vsg/commands/Commands.cpp:60 | Commands 只装纯命令;改状态用 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 有多个 range | MatrixStack 仍按 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,每次泄漏一个 VkCommandBuffer | include/vsg/vk/SubmitCommands.h:31 | 换 TransferTask;该函数已标 deprecated |
改动 StateStack 的三个巧合 | 把 pos 初值改成 -1,或把 stack[0] 拆成独立成员 | 未初始化的 stack 从"安全"变成真 bug | include/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 答案骨架
如果只读这一节,应该带走以下九条。每条都能在上文找到证据,也都能在源码里复核。
- 命令类是薄壳。
Command只有一个纯虚函数(include/vsg/commands/Command.h:29),33 个派生类里 15 个record只有一行;抽象在State层。 Commands的收益是状态应用次数减 N-1。 代价是它只装ref_ptr<Command>(Commands.h:49),且嵌套时不再应用状态(Commands.cpp:62)。CommandBuffer是录制的唯一上下文。 17 个成员里 8 个是遍历上下文(include/vsg/vk/CommandBuffer.h:40),因为record只拿得到它。- 状态机不检查,靠分配策略。 4 处
vkBeginCommandBuffer、0 处检查(src/vsg/app/CommandGraph.cpp:130);正确性来自"新缓冲 Initial、复用先 reset、池带 flag、每帧只 begin 一次"。 StateStack是定长 16 的无检查栈。 第 16 次同槽 push 覆盖pos(include/vsg/vk/State.h:64),这是全章唯一会立刻段错误的地方。maxSlots决定stateStacks长度。 它经四跳传到State::reserve(src/vsg/vk/State.cpp:31),任何一环缺失都导致越界或静默失效。- 二级缓冲的
inheritanceInfo未零初始化。device+family构造路径下framebuffer是野值(src/vsg/app/SecondaryCommandGraph.cpp:127)。 - 多线程录制的唯一同步点是 latch。
wait()在锁外(src/vsg/commands/ExecuteCommands.cpp:70),异常会永久阻塞。 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 是谁在重置?