《VulkanSceneGraph 1.1.16 源码深度解析》第十二章 编译遍历:CompileTraversal 与 CompileManager
12.0 先把规模和答案摆出来
第十一章收尾时把六个问题留在了桌面上,本章逐条作答,先把原问题抄在这里,读者可以对照着验收:
DescriptorSet::compile(src/vsg/state/DescriptorSet.cpp:70–87)在遍历中先编译setLayout再逐个descriptors的apply由谁调用;CompileTraversal的分派顺序如何保证"布局先于分配、描述符先于写入"。Context::reserve(src/vsg/vk/Context.cpp:212–224)与DescriptorPools::reserve(src/vsg/vk/DescriptorPools.cpp:73–136)何时被调用;CompileTraversal::add里的context->reserve(requirements)与CollectResourceRequirements(src/vsg/vk/ResourceRequirements.cpp:101–146)收集的是否同一份对象,多线程编译时每个Context拿副本还是共享引用。- 第十一章 11.7.2 空返回值链、11.8.3 兜底新建池、11.9.3 容量低估,在
CompileManager::compileTask(src/vsg/app/CompileManager.cpp:392)的多线程路径下会被并发allocateDescriptorSet放大吗;DescriptorPool::mutex与std::list descriptorPools的访问粒度是否配平。 - 第九章 9.12 两条 resize 重建路径、
WindowResizeHandler::release(viewID)与DescriptorSet::release(deviceID)如何配平;重建管线时描述符集是复用还是整批回收进_recyclingList。 BindViewDescriptorSets由ViewDependentState::traverse直接录制、不走StateGroup的 push(第八章 8.2.4),CompileTraversal的View分支如何准备viewDependentState与viewID;阴影贴图描述符的编译时机由谁驱动。- "一次性写入"与"池一次建够"在
CompileManager多帧在飞、PagedLOD 增量编译下如何维持;ResourceRequirements::containsPagedLOD与DynamicData是否让reserve被二次调用,"只增不减、用后清零"还配平吗。
先给可复核的规模。include/vsg/app/ 有 22 个头文件,include/vsg/vk/ 有 27 个头文件(ls include/vsg/app/*.h | wc -l 与 ls include/vsg/vk/*.h | wc -l 实测)。本章正面处理的 18 个文件共 5,303 行(下表逐行 wc -l 实测,末行 total 为 5303):
| 文件 | 行数 | 本章角色 |
|---|---|---|
include/vsg/app/CompileTraversal.h | 113 | 8 个 apply 声明、10 个 add 声明、contexts 容器、compile(T, bool) 模板 |
src/vsg/app/CompileTraversal.cpp | 479 | 8 个 apply 实现、10 个 add 实现、AddViews 内部 Visitor、record/waitForCompletion |
include/vsg/app/CompileManager.h | 119 | CompileResult、ResourceScavenger、CompileManager、ThreadSafeQueue 池 |
src/vsg/app/CompileManager.cpp | 447 | compile() 主流程、compileTask() 旁路、#if 0 多线程开关、异常兜底 |
include/vsg/vk/Context.h | 160 | 编译期总控全部字段:deviceID/viewID/mask/三层管线状态/拷贝队列 |
src/vsg/vk/Context.cpp | 599 | 构造注入 deviceID、reserve/copy/record/waitForCompletion 状态机、#if 1 死代码 |
include/vsg/vk/ResourceRequirements.h | 149 | ResourceRequirements 默认值、ViewDetails、26 处 void apply( 声明 |
src/vsg/vk/ResourceRequirements.cpp | 418 | 25 个 CollectResourceRequirements::apply 定义、createResourceHints、registerDescriptor |
src/vsg/app/Viewer.cpp | 892 | Viewer::compile/update/recordAndSubmit、updateViewer、编译屏障接合点 |
src/vsg/app/View.cpp | 127 | viewID 全局分配器、View::share 的 const_cast、camera 判空分支 |
src/vsg/app/RenderGraph.cpp | 230 | getRenderPass() 三级回退、accept(RecordTraversal&)、resize 分派 |
src/vsg/app/SecondaryCommandGraph.cpp | 177 | getRenderPass() 三级回退、level()、reset()/_connect |
include/vsg/app/RecordTraversal.h | 191 | 约 35 个 apply 声明,用于对照 CompileTraversal 不处理的节点 |
src/vsg/app/RecordTraversal.cpp | 704 | 帧期遍历实现,本章只取其分工边界 |
include/vsg/state/ResourceHints.h | 99 | 两个 hint 枚举、DynamicData、ResourceHints 全部默认字段 |
src/vsg/state/ResourceHints.cpp | 148 | read/write 的 18 组序列化字段 |
src/vsg/vk/DescriptorPools.cpp | 251 | reserve 累计量、四本账、available/used/allocated/report |
另有 8 个"边界文件"只取接口不展开实现,行数同批实测:include/vsg/utils/SharedObjects.h(213)、src/vsg/utils/SharedObjects.cpp(241)、include/vsg/io/ObjectFactory.h(64)、src/vsg/io/ObjectFactory.cpp(375)、include/vsg/io/Options.h(147)、include/vsg/threading/OperationQueue.h(156)、include/vsg/threading/ActivityStatus.h(42)、include/vsg/threading/Barrier.h(78)、include/vsg/threading/Latch.h(95)、include/vsg/io/DatabasePager.h(180)、src/vsg/io/DatabasePager.cpp(792)、include/vsg/app/TransferTask.h(124)、include/vsg/app/Viewer.h(174)、include/vsg/app/View.h(97)、include/vsg/app/RenderGraph.h(90)、include/vsg/app/SecondaryCommandGraph.h(62)。这些文件里,同步原语归第 16 章、分页器归第 19 章、IO 归第 17 章,本章只标注交接行号。
全库 ->compile( 共 64 处,compile(context 形态 47 处,compile(*context 形态 8 处,.compile( 形态 6 处(其中 1 处是 include/vsg/app/TransferTask.h:25 注释里的 viewer.compile(..),不是调用)。含 compile( 字样的源文件共 106 个。以上全部来自 grep -rn 实测,复现命令见"可复现验证"。真正决定本章结论的,是不到 900 行:src/vsg/app/CompileTraversal.cpp:291–457 的八个 apply(广播到 contexts),src/vsg/app/CompileManager.cpp:257–390 里重新 collectRequirements 的 compile,src/vsg/vk/Context.cpp:170–369 里对 copyImageCmd/bufferInfosToCopy 的状态机,以及 src/vsg/vk/ResourceRequirements.cpp:100–117/175–188 里 createResourceHints 的闭环两端。
12.0.1 本章的问题清单
apply 全重载按节点类型怎么分组(12.2);十个 add 声明为什么只有三条实做主线(12.3);RenderGraph/SecondaryCommandGraph/View 三处上下文切换各自保存恢复哪些字段、漏了哪些(12.4、12.5、12.6);CompileManager 池里到底有几个 CompileTraversal、#if 0 关掉的是什么(12.7);CompileResult::add 的合并语义与失败锁定(12.8);compileTask 为什么不走池(12.9);Context 的 deviceID 是常量还是注入值、reset 漏清什么(12.10、12.11);CollectResourceRequirements 25 个入口如何分派、viewDetailsStack 何时 push/pop(12.12);ResourceHints 与 ResourceRequirements 字段集是否同构、createResourceHints 丢了多少字段(12.13);Viewer::compile 三阶段与 update/recordAndSubmit 的屏障在哪一行接上(12.14);SharedObjects 去重在加载期还是编译期、Options/ObjectFactory 各管一段吗(12.15);多线程编译的线程数从哪来、Barrier/Latch 在哪一层用(12.16);DatabasePager 的编译队列在哪个函数交接(12.17);CompileTraversal 不处理哪些节点、为什么必须另有一个 RecordTraversal(12.18)。
12.0.2 答案骨架
先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对:
| # | 结论 | 主要证据 | 性质 |
|---|---|---|---|
| 1 | apply(View&) 直接解引用 view.camera->viewportState 而不判空,默认构造的 View 的 camera 为空指针,编译到该节点必崩 | src/vsg/app/CompileTraversal.cpp:443、对照 :126、src/vsg/vk/ResourceRequirements.cpp:245、src/vsg/app/View.cpp:70–75 | 硬缺陷 |
| 2 | apply(View&) 保存 5 个字段、恢复 5 个字段,却在第 435 行写入 viewDependentState 而保存/恢复清单里没有它,退出 View 后该裸指针泄漏给后续节点 | src/vsg/app/CompileTraversal.cpp:425–435、src/vsg/app/CompileTraversal.cpp:448–453、include/vsg/vk/Context.h:85 | 硬缺陷 |
| 3 | apply(RenderGraph&) 与 apply(SecondaryCommandGraph&) 临时替换 renderPass 却不改 viewID,与第九章 GraphicsPipeline::compile 只比 _pipelineStates 叠加,会把子图管线绑到错误的 renderPass | src/vsg/app/CompileTraversal.cpp:389–411、src/vsg/app/CompileTraversal.cpp:354–379、src/vsg/state/GraphicsPipeline.cpp:175–182 | 硬缺陷 |
| 4 | CompileManager 构造函数 #if 0 关闭 4 个 CompileTraversal 复制,实际 numCompileTraversals = 1;所谓"多线程编译"是外部多线程共享单个池、由 take_when_available 串行化,分页线程经 plod 的 requestStatus 切换进入编译 | src/vsg/app/CompileManager.cpp:138–145、src/vsg/app/CompileManager.cpp:273、src/vsg/io/DatabasePager.cpp:575 | 设计取舍 |
| 5 | CompileResult::add 合并 views 时用 break 而非 continue,遇到第一个 indices 与 bins 皆空的 view 就终止整轮合并,后续 view 的 bin 明细静默丢失 | src/vsg/app/CompileManager.cpp:48–55 | 硬缺陷 |
| 6 | Context::reset() 只清 commands/bufferInfosToCopy/copyImageCmd/copyBufferCmd,漏清 imageInfosToCopy、buildAccelerationStructureCommands、scratchBufferSize、requiresWaitForCompletion;第 174 行把 copyImageCmd 的值误打成 copyBufferCmd | src/vsg/vk/Context.cpp:170–183、src/vsg/vk/Context.cpp:290–293、src/vsg/vk/Context.cpp:595–596 | 硬缺陷 |
| 7 | Context::record() 对未走 transferTask 的拷贝只发一句 "Need to implement copying of data." 警告就返回,数据不上传;createBufferAndTransferData 的 #if 1 把 160 余行脏标记与暂存缓冲实现压成不可达代码 | src/vsg/vk/Context.cpp:319、src/vsg/vk/Context.cpp:416、src/vsg/vk/Context.cpp:428–588 | 硬缺陷 |
| 8 | registerDescriptor 在去重判断之前无条件累加 descriptorTypeMap,同一 Descriptor 被多条路径访问会重复计容量;而 apply(ref_ptr<BufferInfo>) 先查 bufferInfos、apply(ref_ptr<ImageInfo>) 先查 imageInfos 再去重累加,两套口径不一致 | src/vsg/vk/ResourceRequirements.cpp:175–188、src/vsg/vk/ResourceRequirements.cpp:373–393、src/vsg/vk/ResourceRequirements.cpp:395–418 | 硬缺陷 |
| 9 | createResourceHints 只回填 5 个字段,丢掉 numDatabasePagerReadThreads、allocatedMemoryLimit、三个 minimum*Size、两个 range、shadowMapSize 与两个 hint,收集→提示的闭环不闭合 | src/vsg/vk/ResourceRequirements.cpp:100–117、对照 include/vsg/state/ResourceHints.h:67–88、src/vsg/state/ResourceHints.cpp:39–146 | 硬缺陷 |
| 10 | CompileTraversal 只有 8 个 apply 特化,靠 apply(Object&) 的 object.traverse(*this) 通吃其余节点;RecordTraversal 约 35 个 apply(含 pagedLOD、TileDatabase)才承担视锥剔除与状态栈,两个遍历不是同一套分派表 | include/vsg/app/CompileTraversal.h:96–103、src/vsg/app/CompileTraversal.cpp:291–296、include/vsg/app/RecordTraversal.h:116–166 | 设计取舍 |
这十条里,第 1、2、3、5、6、7、8、9 条是本章的硬缺陷,第 4、10 条是设计取舍。硬缺陷集中在三处:上下文保存/恢复不对称(CompileTraversal.cpp)、状态清理不配平(Context.cpp)、统计与回填写不全(ResourceRequirements.cpp)。下面按"入口→遍历→池→状态机→闭环→外围"的顺序展开。
12.0.3 阅读路线
Viewer::compile → CollectResourceRequirements → CompileManager 池 → CompileTraversal::add → 八个 apply → Context 状态机 → Context::record/waitForCompletion → CompileResult → Viewer::update → DatabasePager 交接 → RecordTraversal 分工。
这个顺序不是随意排的,它正好是一次 CompileManager::compile() 里依赖被满足的顺序:src/vsg/app/CompileManager.cpp:259–260 先 object->accept(collectRequirements),src/vsg/app/CompileManager.cpp:285–288 再对每个 context->reset(),src/vsg/app/CompileManager.cpp:310–326 才 context->reserve(requirements),src/vsg/app/CompileManager.cpp:328 才 object->accept(*compileTraversal),最后 :331–334 才 record() 与 waitForCompletion()。
12.1 编译为什么必须是独立阶段:从 Viewer::compile 的三段式说起
第十一章反复出现的"一次性写入"与"池一次建够",根源不在描述符对象,而在编译被设计成一个有始有终的独立阶段:先统计容量,再统一分配,最后一次性上传。Viewer::compile 把这个三段式写得很直白。
源码摘录(src/vsg/app/Viewer.cpp:278–325)
CompileResult Viewer::compile(ref_ptr<ResourceHints> hints)
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer compile", COLOR_COMPILE);
if (recordAndSubmitTasks.empty())
{
return {};
}
CompileResult result;
bool containsPagedLOD = false;
ref_ptr<DatabasePager> databasePager;
struct DeviceResources
{
CollectResourceRequirements collectResources;
};
// find which devices are available and the resources required for them
using DeviceResourceMap = std::map<ref_ptr<vsg::Device>, DeviceResources>;
DeviceResourceMap deviceResourceMap;
for (auto& task : recordAndSubmitTasks)
{
auto& collectResources = deviceResourceMap[task->device].collectResources;
auto& resourceRequirements = collectResources.requirements;
if (hints) hints->accept(collectResources);
for (auto& commandGraph : task->commandGraphs)
{
commandGraph->accept(collectResources);
}
task->transferTask->minimumStagingBufferSize = resourceRequirements.minimumStagingBufferSize;
if (task->databasePager && !databasePager) databasePager = task->databasePager;
}
// allocate DescriptorPool for each Device
ResourceRequirements::Views views;
for (auto& [device, deviceResources] : deviceResourceMap)
{
auto& collectResources = deviceResources.collectResources;
auto& resourceRequirements = collectResources.requirements;
views.insert(resourceRequirements.views.begin(), resourceRequirements.views.end());
if (resourceRequirements.containsPagedLOD) containsPagedLOD = true;
}
逐字段/逐分支推导
第 282–285 行是短路:recordAndSubmitTasks 为空时返回默认 CompileResult,其 result 是 VK_INCOMPLETE(include/vsg/app/CompileManager.h:29),operator bool() 为假(include/vsg/app/CompileManager.h:36),但没有任何 message 说明原因——这是静默降级的第一处。
代价与边界
"两遍遍历"是这一章最贵的设计代价:第一遍 CollectResourceRequirements 按 deviceResourceMap 归并每设备的 minimumStagingBufferSize(src/vsg/app/Viewer.cpp:305–308),第二遍 compileManager->compileTask 里的 cg->accept(*compileTraversal)(src/vsg/app/CompileManager.cpp:425–428)。收益是编译期可以在动手创建任何 Vulkan 句柄之前,先知道要建多大的描述符池(descriptorTypeMap)、多大的暂存缓冲、多少个 slot(viewDetailsStack,include/vsg/vk/ResourceRequirements.h:71–73)。
交叉引用
第九章 9.12 的 resize 重建会重跑 Viewer::compile 统计段,commandGraph->maxSlots = resourceRequirements.maxSlots(src/vsg/app/Viewer.cpp:365)因此被重新赋值。
12.1.1 viewID 的分配与 bin 的补齐
源码摘录(src/vsg/app/Viewer.cpp:327–347)
// assign the viewID's to each View
for (auto& [const_view, binDetails] : views)
{
auto view = const_cast<View*>(const_view);
for (auto& binNumber : binDetails.indices)
{
bool binNumberMatched = false;
for (const auto& bin : view->bins)
{
if (bin->binNumber == binNumber)
{
binNumberMatched = true;
}
}
if (!binNumberMatched)
{
Bin::SortOrder sortOrder = (binNumber < 0) ? Bin::ASCENDING : ((binNumber == 0) ? Bin::NO_SORT : Bin::DESCENDING);
view->bins.push_back(Bin::create(binNumber, sortOrder));
}
}
}
逐字段/逐分支推导
注释写的是 "assign the viewID's to each View",但循环体里一行都没有给 viewID 赋值,只做 bin 补齐。viewID 实际在 View 构造时由 getUniqueViewID() 分配(src/vsg/app/View.cpp:70–75、src/vsg/app/View.cpp:25–42),用 const_cast 改它的唯一位置是 View::share(src/vsg/app/View.cpp:113–119)。
代价与边界
View::viewID 是 const uint32_t(include/vsg/app/View.h:70),全局分配器 s_ActiveViews(src/vsg/app/View.cpp:23)用 std::mutex 保护,析构时 releaseViewID 做 --s_ActiveViews[viewID](src/vsg/app/View.cpp:60–64)——没有边界检查,若 viewID 因 const_cast 被改成越界值就会写坏 vector。
交叉引用
_implementation[viewID] 槽位判空与 WindowResizeHandler::release(viewID) 都以这里固定的 viewID 为索引。
12.1.2 三段式的收尾:CompileManager 装配与分页器启动
源码摘录(src/vsg/app/Viewer.cpp:355–417,deviceResource 归并段)
// create the Vulkan objects
for (const auto& task : recordAndSubmitTasks)
{
const auto& deviceResource = deviceResourceMap[task->device];
const auto& resourceRequirements = deviceResource.collectResources.requirements;
bool task_containsPagedLOD = false;
for (const auto& commandGraph : task->commandGraphs)
{
commandGraph->maxSlots = resourceRequirements.maxSlots;
if (resourceRequirements.containsPagedLOD) task_containsPagedLOD = true;
}
if (task_containsPagedLOD)
{
if (!task->databasePager) task->databasePager = databasePager;
}
}
// set up the CompileManager
if (!compileManager)
{
compileManager = CompileManager::create(*this, hints);
if (instrumentation) compileManager->assignInstrumentation(instrumentation);
}
// assign CompileManager to DatabasePager
if (databasePager && !databasePager->compileManager)
{
databasePager->compileManager = compileManager;
compileManager->resourceScavenger = ResourceScavenger::create(databasePager);
}
for (auto& task : recordAndSubmitTasks)
{
if (hints)
{
if (auto deviceMemoryBufferPools = task->device->deviceMemoryBufferPools.ref_ptr())
{
deviceMemoryBufferPools->allocatedMemoryLimit = hints->allocatedMemoryLimit;
}
}
auto& deviceResource = deviceResourceMap[task->device];
auto& resourceRequirements = deviceResource.collectResources.requirements;
result.add(compileManager->compileTask(task, resourceRequirements));
task->transferTask->assign(resourceRequirements.dynamicData);
}
// start any DatabasePagers
for (const auto& task : recordAndSubmitTasks)
{
if (task->databasePager)
{
if (hints)
task->databasePager->start(hints->numDatabasePagerReadThreads);
else
task->databasePager->start();
}
}
return result;
}
逐字段/逐分支推导
第 365 行把统计出的 maxSlots 写回每个 commandGraph,这是"统计→帧期"的第二条出口(第一条是第 310 行的 minimumStagingBufferSize)。第 369–372 行:只有统计出 containsPagedLOD 的 task 才挂 databasePager,且第 349–353 行在没有任何 task 自带分页器时会 DatabasePager::create() 兜底。
代价与边界
result.add(compileManager->compileTask(...))(src/vsg/app/Viewer.cpp:401)是 CompileResult::add(src/vsg/app/CompileManager.cpp:37–58)的最大调用方,12.0.2 第 5 条的 break 缺陷会在这里按 task 逐个放大:某个 task 的 cr.views 里只要出现一个空 binDetails,后面所有 task 的 view 明细都可能被吞掉。
交叉引用
DatabasePager 生命周期从 src/vsg/app/Viewer.cpp:405–415 起步,本章 12.17 只讲编译队列交接。
12.2 八个 apply 的分组统计:CompileTraversal 只特化必要的节点
第九章 9.14、9.15 已经铺垫过 CompileTraversal 在 RenderGraph 与 SecondaryCommandGraph 下临时替换 context->renderPass,这里给全貌。先看声明与实现的完整清单。
源码摘录(include/vsg/app/CompileTraversal.h:95–110)
// implement compile of relevant nodes in the scene graph
void apply(Object& object) override;
void apply(Compilable& node) override;
void apply(Commands& commands) override;
void apply(Geometry& geometry) override;
void apply(CommandGraph& commandGraph) override;
void apply(SecondaryCommandGraph& secondaryCommandGraph) override;
void apply(RenderGraph& renderGraph) override;
void apply(View& view) override;
protected:
~CompileTraversal() override;
void add(ref_ptr<Context> context, Framebuffer& framebuffer, ref_ptr<TransferTask> transferTask, ref_ptr<View> view, const ResourceRequirements& resourceRequirements);
void addViewDependentState(ViewDependentState& viewDependentState, ref_ptr<Device> device, ref_ptr<TransferTask> transferTask, const ResourceRequirements& resourceRequirements);
grep -c "^void CompileTraversal::apply" src/vsg/app/CompileTraversal.cpp 实测为 8,与头文件 8 个 override 一一对应。按行为分成四组:
| 组 | apply | 是否 compile | 是否 traverse | 作用 |
|---|---|---|---|---|
| 通用递归 | Object(:291)、Compilable(:298)、Geometry(:320) | 后三者调用 compile(*context) | 三者都 traverse | 逐节点下沉 |
| 命令容器 | Commands(:310) | commands.compile(*context) | 不 traverse | 只编译容器自身 |
| 上下文切换 | CommandGraph(:331)、SecondaryCommandGraph(:343)、RenderGraph(:383)、View(:415) | 不直接 compile | 都 traverse | 改写 Context 后下沉 |
12.2.1 通用递归组:Object / Compilable / Geometry
源码摘录(src/vsg/app/CompileTraversal.cpp:291–329)
void CompileTraversal::apply(Object& object)
{
CPU_INSTRUMENTATION_L2_NC(instrumentation, "CompileTraversal Object", COLOR_COMPILE);
object.traverse(*this);
}
void CompileTraversal::apply(Compilable& node)
{
CPU_INSTRUMENTATION_L3_NC(instrumentation, "CompileTraversal Compilable", COLOR_COMPILE);
for (auto& context : contexts)
{
node.compile(*context);
}
node.traverse(*this);
}
void CompileTraversal::apply(Commands& commands)
{
CPU_INSTRUMENTATION_L3_NC(instrumentation, "CompileTraversal Commands", COLOR_COMPILE);
for (auto& context : contexts)
{
commands.compile(*context);
}
}
void CompileTraversal::apply(Geometry& geometry)
{
CPU_INSTRUMENTATION_L3_NC(instrumentation, "CompileTraversal Geometry", COLOR_COMPILE);
for (auto& context : contexts)
{
geometry.compile(*context);
}
geometry.traverse(*this);
}
逐字段/逐分支推导
apply(Object&)(:291–296)是兜底:object.traverse(*this) 让所有没有特化的节点类型继续下沉,这就是为什么 8 个 apply 能覆盖整棵场景图——Visitor 的分派表(include/vsg/core/Visitor.h)里没有特化的类型会回落到 Object。apply(Compilable&)(:298–308)先对每个 context 调一次 node.compile(*context),再 traverse;for (auto& context : contexts) 不是取一个,而是把同一份编译动作广播到池里所有 Context(include/vsg/app/CompileTraversal.h:47 的 std::list<ref_ptr<Context>>)。
instrumentation 的级别也有信息:apply(Object&) 用 L2_NC,Compilable/Commands/Geometry 用 L3_NC,四个上下文切换分支用 L1_NC(src/vsg/app/CompileTraversal.cpp:333/345/385/417),record/waitForCompletion 也用 L1_NC(:461/473)。级别越高越粗,说明作者把"进入一个渲染图/视图"当作可观测的大阶段,把"编译一个几何体"当作细粒度事件。
代价与边界
四处分派共同的前提是 contexts 非空。若用户直接 CompileTraversal ct; 用默认构造(include/vsg/app/CompileTraversal.h:36 只设 overrideMask),contexts 为空,遍历会完整跑一遍但一次 compile 都不发生,record() 返回 false(:463–468),compile(T, bool) 模板(:88–93)随后 waitForCompletion() 空转。这是一个没有断言、没有日志的静默空转路径。
交叉引用
Commands 在编译遍历中不继续下沉;StateGroup 没有 apply 特化,落到 apply(Object&) 直接 traverse;BindGraphicsPipeline::compile 则经 apply(Compilable&) 触发。
12.2.2 上下文切换组:CommandGraph 只更新 maxSlots
源码摘录(src/vsg/app/CompileTraversal.cpp:331–341)
void CompileTraversal::apply(CommandGraph& commandGraph)
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "CompileTraversal CommandGraph", COLOR_COMPILE);
for (const auto& context : contexts)
{
commandGraph.maxSlots.update(context->resourceRequirements.maxSlots);
}
commandGraph.traverse(*this);
}
逐字段/逐分支推导
CommandGraph 分支不保存也不恢复任何 Context 字段,只把 context->resourceRequirements.maxSlots 合并进 commandGraph.maxSlots(:337),然后 traverse。这与 12.4–12.6 的四个分支形成鲜明对比:后者都有"保存→改写→traverse→恢复"的对称结构,这里完全不对称,因为它不改写上下文。
代价与边界
const auto& 只约束 context 指针本身,context->resourceRequirements 被 update 读取但不改写,方向单一。边界是:CommandGraph 本身不 compile,因此命令图级别的资源(例如 CommandPool 的分配)必须在 CompileTraversal::add 阶段就由 Context 准备好(src/vsg/app/CompileTraversal.cpp:69/88/118/154/258),而不是在遍历中按需创建。
交叉引用
commandGraph->maxSlots = resourceRequirements.maxSlots(src/vsg/app/Viewer.cpp:365)在统计段先赋值,这里的 update 在编译段取最大,顺序不能颠倒。
12.3 十个 add 声明、三条实做主线:Context 注入点全解
用户提示里说的"三个 add() 注入点",实测之后需要更正为更精确的说法:grep -c "void add(" include/vsg/app/CompileTraversal.h 为 10,grep -c "^void CompileTraversal::add" src/vsg/app/CompileTraversal.cpp 为 11(其中 addViewDependentState 因前缀相同被计入,真正的 add 实现是 10 个)。十个声明按目标可归并为三条实做主线 + 一个大遍历入口,其余都是转调。
源码摘录(include/vsg/app/CompileTraversal.h:52–80,含 contexts 与 instrumentation 字段)
/// add a compile Context for device
void add(ref_ptr<Device> device, ref_ptr<TransferTask> transferTask, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for device
void add(ref_ptr<Device> device, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Window and associated viewport.
void add(Window& window, ref_ptr<TransferTask> transferTask, ref_ptr<ViewportState> viewport = {}, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Window and associated viewport.
void add(Window& window, ref_ptr<ViewportState> viewport = {}, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Window and associated View
void add(Window& window, ref_ptr<TransferTask> transferTask, ref_ptr<View> view, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Window and associated View
void add(Window& window, ref_ptr<View> view, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Framebuffer and associated View
void add(Framebuffer& framebuffer, ref_ptr<TransferTask> transferTask, ref_ptr<View> view, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for Framebuffer and associated View
void add(Framebuffer& framebuffer, ref_ptr<View> view, const ResourceRequirements& resourceRequirements = {});
/// add a compile Context for all the Views assigned to a Viewer
void add(const Viewer& viewer, const ResourceRequirements& resourceRequirements = {});
逐字段/逐分支推导
十个声明成对出现:每个"带 ref_ptr<TransferTask> 参数"的实做重载,都配一个"不带 transferTask"的便利重载,后者从 device->transferTask 或 framebuffer.getDevice() 取(src/vsg/app/CompileTraversal.cpp:75–78/102–108/140–146/182–188)。这解释了 10 = 5 组 × 2。
12.3.1 第一类:Device 注入(最简 Context)
源码摘录(src/vsg/app/CompileTraversal.cpp:64–78)
void CompileTraversal::add(ref_ptr<Device> device, ref_ptr<TransferTask> transferTask, const ResourceRequirements& resourceRequirements)
{
auto queueFamily = device->getPhysicalDevice()->getQueueFamily(queueFlags);
auto context = Context::create(device, resourceRequirements);
context->instrumentation = instrumentation;
context->commandPool = CommandPool::create(device, queueFamily, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT);
context->graphicsQueue = device->getQueue(queueFamily, queueFamilyIndex);
context->transferTask = transferTask;
contexts.push_back(context);
}
void CompileTraversal::add(ref_ptr<Device> device, const ResourceRequirements& resourceRequirements)
{
add(device, device->transferTask, resourceRequirements);
}
逐字段/逐分支推导
第 66 行 getQueueFamily(queueFlags),queueFlags 默认 VK_QUEUE_GRAPHICS_BIT(include/vsg/app/CompileTraversal.h:43)。第 67 行 Context::create(device, resourceRequirements) 触发 Context::Context(Device*, const ResourceRequirements&)(src/vsg/vk/Context.cpp:90–138),这一步把 deviceID、三个 MemoryBufferPools、descriptorPools 全部接好。
源码摘录(src/vsg/vk/Context.cpp:90,构造注入 deviceID 与三个共享池)
// src/vsg/vk/Context.cpp:90
Context::Context(Device* in_device, const ResourceRequirements& in_resourceRequirements) :
deviceID(in_device->deviceID),
device(in_device),
resourceRequirements(in_resourceRequirements),
scratchBufferSize(0)
{
//semaphore = vsg::Semaphore::create(device);
scratchMemory = ScratchMemory::create(4096);
deviceID 在初始化列表里由 in_device->deviceID 赋值,证明它是注入值;三个 MemoryBufferPools 与 descriptorPools 都先查 device 上的共享实例,为空才 create。
代价与边界
context->renderPass 在这一类注入里保持为空,因此用 CompileTraversal(device) 直接编译一个含 GraphicsPipeline 的子图时,GraphicsPipeline::compile(src/vsg/state/GraphicsPipeline.cpp:161)按 viewID 取 _implementation 槽时拿到的 context.renderPass 为空。这正是 CompileManager::compileTask(src/vsg/app/CompileManager.cpp:401)用的构造——它只传 task->device。
交叉引用
第九章 9.6 的三层管线状态里,defaultPipelineStates/overridePipelineStates 在这一类注入里也是空的,只在 Window/Framebuffer/View 入口才填(src/vsg/app/CompileTraversal.cpp:93–97/122–129/165–171);第十一章 11.8.3 的兜底新建池由 Context 构造(src/vsg/vk/Context.cpp:123–132)完成,与这里的 device->descriptorPools 共享。
12.3.2 第二类与第三类:Window/Framebuffer 注入的字段差异
源码摘录(src/vsg/app/CompileTraversal.cpp:80–99 与 :110–138)
void CompileTraversal::add(Window& window, ref_ptr<TransferTask> transferTask, ref_ptr<ViewportState> viewport, const ResourceRequirements& resourceRequirements)
{
auto device = window.getOrCreateDevice();
auto renderPass = window.getOrCreateRenderPass();
auto queueFamily = device->getPhysicalDevice()->getQueueFamily(queueFlags);
auto context = Context::create(device, resourceRequirements);
context->instrumentation = instrumentation;
context->renderPass = renderPass;
context->commandPool = CommandPool::create(device, queueFamily, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT);
context->graphicsQueue = device->getQueue(queueFamily, queueFamilyIndex);
context->transferTask = transferTask;
if (viewport)
context->defaultPipelineStates.emplace_back(viewport);
else
context->defaultPipelineStates.emplace_back(vsg::ViewportState::create(window.extent2D()));
if (renderPass->maxSamples != VK_SAMPLE_COUNT_1_BIT) context->overridePipelineStates.emplace_back(MultisampleState::create(renderPass->maxSamples));
contexts.push_back(context);
}
void CompileTraversal::add(Window& window, ref_ptr<TransferTask> transferTask, ref_ptr<View> view, const ResourceRequirements& resourceRequirements)
{
auto device = window.getOrCreateDevice();
auto renderPass = window.getOrCreateRenderPass();
auto queueFamily = device->getPhysicalDevice()->getQueueFamily(queueFlags);
auto context = Context::create(device, resourceRequirements);
context->instrumentation = instrumentation;
context->renderPass = renderPass;
context->commandPool = vsg::CommandPool::create(device, queueFamily, VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT);
context->graphicsQueue = device->getQueue(queueFamily, queueFamilyIndex);
context->transferTask = transferTask;
if (renderPass->maxSamples != VK_SAMPLE_COUNT_1_BIT) context->overridePipelineStates.emplace_back(vsg::MultisampleState::create(renderPass->maxSamples));
context->overridePipelineStates.insert(context->overridePipelineStates.end(), view->overridePipelineStates.begin(), view->overridePipelineStates.end());
if (view->camera && view->camera->viewportState)
context->defaultPipelineStates.emplace_back(view->camera->viewportState);
else
context->defaultPipelineStates.emplace_back(vsg::ViewportState::create(window.extent2D()));
context->view = view.get();
context->viewID = view->viewID;
context->viewDependentState = view->viewDependentState;
contexts.push_back(context);
if (view->viewDependentState) addViewDependentState(*(view->viewDependentState), device, transferTask, resourceRequirements);
}
逐字段/逐分支推导
两个重载前九行完全一致,差异只在管线状态的填法:Viewport 版只填 defaultPipelineStates(:92–97);View 版先填 MultisampleState,再 insert 整个 view->overridePipelineStates,viewport 优先取 view->camera->viewportState 且带判空(:126),最后写 view/viewID/viewDependentState 三字段并追加 addViewDependentState(:122–137)。
这里出现了本章最关键的一处对照::126 有 if (view->camera && view->camera->viewportState) 判空,而 apply(View&) 的 :443 没有。同一份 View 对象,在 add 路径被保护,在 apply 路径被裸解引用。默认构造 View(ViewFeatures)(src/vsg/app/View.cpp:70–75)不设置 camera,所以 CompileTraversal(viewer) 建出的 Context 走 :126 的 else 分支补一个 ViewportState,但随后 apply(View&) 到 :443 仍会崩。
context->viewDependentState = view->viewDependentState(:133)把一个 ref_ptr<ViewDependentState> 赋给 Context::viewDependentState,后者是裸指针 ViewDependentState*(include/vsg/vk/Context.h:85)。
代价与边界
:97 与 :122 的 MultisampleState 注入条件都是 maxSamples != VK_SAMPLE_COUNT_1_BIT,而 apply(SecondaryCommandGraph&) 的 :369–372 只判 if (renderPass) 就无条件 mergeGraphicsPipelineStates(..., MultisampleState::create(context->renderPass->maxSamples))——注入期的条件在遍历期被放宽了,单采样场景也会在 secondary 图下被塞一个 MultisampleState。
交叉引用
resize 重建时 add 会被 CompileManager::add 重新调用(src/vsg/app/CompileManager.cpp:201–209);Camera::viewportState 正是 :127 与 :443 争夺的对象。
12.3.3 第四入口:add(Viewer) 的内部 Visitor
源码摘录(src/vsg/app/CompileTraversal.cpp:190–249)
void CompileTraversal::add(const Viewer& viewer, const ResourceRequirements& resourceRequirements)
{
if (viewer.instrumentation) instrumentation = viewer.instrumentation;
struct AddViews : public Visitor
{
CompileTraversal* ct = nullptr;
const ResourceRequirements& resourceRequirements;
ref_ptr<TransferTask> transferTask;
AddViews(CompileTraversal* in_ct, const ResourceRequirements& in_rr) :
ct(in_ct), resourceRequirements(in_rr) {}
const char* className() const noexcept override { return "vsg::CompileTraversal::AddViews"; }
std::stack<ref_ptr<Object>> objectStack;
void apply(Object& object) override
{
object.traverse(*this);
}
void apply(RenderGraph& rg) override
{
if (rg.window)
objectStack.emplace(rg.window);
else
objectStack.emplace(rg.framebuffer);
rg.traverse(*this);
objectStack.pop();
}
void apply(View& view) override
{
if (!objectStack.empty())
{
auto obj = objectStack.top();
if (auto window = obj.cast<Window>())
ct->add(*window, transferTask, ref_ptr<View>(&view), resourceRequirements);
else if (auto framebuffer = obj.cast<Framebuffer>())
ct->add(*framebuffer, transferTask, ref_ptr<View>(&view), resourceRequirements);
}
}
} addViews(this, resourceRequirements);
for (const auto& task : viewer.recordAndSubmitTasks)
{
if (resourceRequirements.dataTransferHint == COMPILE_TRAVERSAL_USE_TRANSFER_TASK)
{
addViews.transferTask = task->transferTask;
}
for (auto& cg : task->commandGraphs)
{
cg->accept(addViews);
}
}
}
逐字段/逐分支推导
AddViews 是定义在函数体内的局部 Visitor(:194–235),只有三个 apply:Object 兜底 traverse、RenderGraph 压栈、View 出栈时按栈顶对象类型决定调 add(Window&, ...) 还是 add(Framebuffer&, ...)。objectStack(:205)用来把"当前 View 挂在哪个 Window/Framebuffer 下"这一上下文从 RenderGraph 传到 View:第 214–217 行优先压 rg.window,否则压 rg.framebuffer;第 219 行 rg.traverse(*this) 下沉;第 221 行 pop() 配平。
代价与边界
objectStack 只在 RenderGraph 分支压栈,若 View 直接挂在 CommandGraph 下而中间没有 RenderGraph,栈为空,View 被静默跳过,该视图对应的 Context 根本不会被创建,后续 apply(View&) 里的 :422–423 也无从匹配。第 230/232 行 ref_ptr<View>(&view) 把一个栈上/引用对象包成 ref_ptr,由于 View 由 ref_ptr 管理且此处只是借用,VSG 的侵入式引用计数会把引用计数 +1 再 -1,不会接管所有权,但这是易误读的写法。
交叉引用
View 的挂载位置决定 AddViews 能否找到它;12.9 的 compileTask 完全绕开 add(Viewer),改用 CompileTraversal::create(task->device, ...),两条路径的 Context 数量与字段集不同。
12.4 apply(RenderGraph&):保存、改写、恢复的三段式
源码摘录(src/vsg/app/CompileTraversal.cpp:383–413)
void CompileTraversal::apply(RenderGraph& renderGraph)
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "CompileTraversal RenderGraph", COLOR_COMPILE);
for (auto& context : contexts)
{
// save previous states to be restored after traversal
auto previousRenderPass = context->renderPass;
auto previousDefaultPipelineStates = context->defaultPipelineStates;
auto previousOverridePipelineStates = context->overridePipelineStates;
// enable dynamic viewport state handling if required.
renderGraph.viewportStateHint = context->resourceRequirements.viewportStateHint;
mergeGraphicsPipelineStates(context->mask, context->defaultPipelineStates, renderGraph.viewportState);
context->renderPass = renderGraph.getRenderPass();
if (context->renderPass)
{
mergeGraphicsPipelineStates(context->mask, context->overridePipelineStates, MultisampleState::create(context->renderPass->maxSamples));
}
renderGraph.traverse(*this);
// restore previous values
context->defaultPipelineStates = previousDefaultPipelineStates;
context->overridePipelineStates = previousOverridePipelineStates;
context->renderPass = previousRenderPass;
}
}
12.4.1 保存/恢复清单的字段级核对
逐字段/逐分支推导::390–392 保存 3 字段、:409–411 恢复,顺序 default→override→renderPass 与保存相反但互不依赖。
代价与边界:保存的是值拷贝(GraphicsPipelineStates 是 std::vector<ref_ptr<...>>),因此 merge 往 context->defaultPipelineStates 里追加的元素在恢复时被整体覆盖丢弃,不会泄漏到兄弟 RenderGraph。
12.4.2 与 GraphicsPipeline::compile 复用判据的叠加
// src/vsg/state/GraphicsPipeline.cpp:175
for (const auto& imp : _implementation)
{
if (imp && vsg::compare_pointer_container(imp->_pipelineStates, combined_pipelineStates) == 0)
{
_implementation[viewID] = imp;
return;
}
}
复用只比 _pipelineStates(compare_pointer_container),不比 renderPass/mask/stages/subpass;src/vsg/app/CompileTraversal.cpp:399 遍历期替换 context->renderPass,叠加即 12.4.2 绑错根因。
代价与边界:后一个 RenderGraph 绑错 VkRenderPass 属未定义行为;触发条件是一个 GraphicsPipeline 被两图共享且 getRenderPass() 不同。
这个复用判据还有第二个消费者:窗口 resize 后由 WindowResizeHandler 主动强制重编译,逐字实现如下。
// src/vsg/app/WindowResizeHandler.cpp:103
void WindowResizeHandler::apply(vsg::BindGraphicsPipeline& bindPipeline)
{
if (!context) return;
GraphicsPipeline* graphicsPipeline = bindPipeline.pipeline;
if (!visit(graphicsPipeline, context->viewID))
{
return;
}
它不信任 compile 的复用判定,而是先扫一遍管线状态里有没有 ViewportState;没有就 release(context->viewID) 再 compile(*context)(:130–134)。这与 12.4 的被动绑错 renderPass 互补:一个在最坏情况下漏判,一个靠外部事件兜底重编。
12.5 apply(SecondaryCommandGraph&):与 RenderGraph 分支的对称与不对称
源码摘录(src/vsg/app/CompileTraversal.cpp:343–381)
void CompileTraversal::apply(SecondaryCommandGraph& secondaryCommandGraph)
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "CompileTraversal SecondaryCommandGraph", COLOR_COMPILE);
auto renderPass = secondaryCommandGraph.getRenderPass();
for (auto& context : contexts)
{
secondaryCommandGraph.maxSlots.update(context->resourceRequirements.maxSlots);
// save previous states to be restored after traversal
auto previousRenderPass = context->renderPass;
auto previousDefaultPipelineStates = context->defaultPipelineStates;
auto previousOverridePipelineStates = context->overridePipelineStates;
context->renderPass = renderPass;
if (secondaryCommandGraph.window)
{
mergeGraphicsPipelineStates(context->mask, context->defaultPipelineStates, ViewportState::create(secondaryCommandGraph.window->extent2D()));
}
else if (secondaryCommandGraph.framebuffer)
{
mergeGraphicsPipelineStates(context->mask, context->defaultPipelineStates, ViewportState::create(secondaryCommandGraph.framebuffer->extent2D()));
}
if (renderPass)
{
mergeGraphicsPipelineStates(context->mask, context->overridePipelineStates, MultisampleState::create(context->renderPass->maxSamples));
}
secondaryCommandGraph.traverse(*this);
// restore previous values
context->defaultPipelineStates = previousDefaultPipelineStates;
context->overridePipelineStates = previousOverridePipelineStates;
context->renderPass = previousRenderPass;
}
}
12.5.1 三处 merge 与注入期条件不一致
逐字段/逐分支推导:与 12.4 相比多出第 351 行 secondaryCommandGraph.maxSlots.update(...)(把 slot 需求回写,语义同 apply(CommandGraph&) 的 :337),以及第 347 行把 getRenderPass() 提到循环外只算一次。
代价与边界:注入期(src/vsg/app/CompileTraversal.cpp:97/122)按 samples 决定是否加 MultisampleState,遍历期这里无条件加,单采样 secondary 图也会多一个状态对象;由于同类型后者替换前者(第九章 9.6),它会覆盖注入期可能已存在的 MultisampleState,把 rasterizationSamples 改成 1。
交叉引用:ExecuteCommands(src/vsg/app/SecondaryCommandGraph.cpp:44–58)由 RecordTraversal 处理,CompileTraversal 无对应 apply。
12.5.2 恢复顺序、循环作用域与两个分支的重复度
逐字段/逐分支推导::377–379 恢复顺序与 :409–411 完全一致,连注释都相同,是复制粘贴后改中间段。
代价与边界:N 个 Context 会把同一 renderPass 写 N 次;池里只有 1 个 CompileTraversal(src/vsg/app/CompileManager.cpp:144),N 等于 Context 数。
交叉引用:12.6 的 View 分支是唯一保存/恢复 viewID 与 mask 的分支,三者对照可见"上下文切换"这一模式在库里没有抽成统一的 RAII 守卫,全靠手写三行保存三行恢复,漏字段(12.0.2 第 2 条)正是这种写法的直接代价。
12.6 apply(View&):viewID、mask 与 viewDependentState 的状态机
源码摘录(src/vsg/app/CompileTraversal.cpp:415–457)
void CompileTraversal::apply(View& view)
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "CompileTraversal View", COLOR_COMPILE);
for (auto& context : contexts)
{
// if context is associated with a view make sure we only apply it if it matches with view, otherwise we skip this context
auto context_view = context->view.ref_ptr();
if (context_view && context_view.get() != &view) continue;
// save previous states
auto previous_view = context->view;
auto previous_viewID = context->viewID;
auto previous_mask = context->mask;
auto previous_overridePipelineStates = context->overridePipelineStates;
auto previous_defaultPipelineStates = context->defaultPipelineStates;
context->view = &view;
context->viewID = view.viewID;
context->mask = view.mask;
context->viewDependentState = view.viewDependentState.get();
if (view.viewDependentState)
{
view.viewDependentState->compile(*context);
}
// assign view specific pipeline states
mergeGraphicsPipelineStates(context->mask, context->defaultPipelineStates, view.camera->viewportState);
mergeGraphicsPipelineStates(context->mask, context->overridePipelineStates, view.overridePipelineStates);
view.traverse(*this);
// restore previous states
context->view = previous_view;
context->viewID = previous_viewID;
context->mask = previous_mask;
context->defaultPipelineStates = previous_defaultPipelineStates;
context->overridePipelineStates = previous_overridePipelineStates;
}
if (view.viewDependentState) view.viewDependentState->accept(*this);
}
12.6.1 空指针解引用的完整触发链
// src/vsg/app/CompileTraversal.cpp:421
// if context is associated with a view make sure we only apply it if it matches with view, otherwise we skip this context
auto context_view = context->view.ref_ptr();
if (context_view && context_view.get() != &view) continue;
:422–423 的 context->view.ref_ptr() 把 observer_ptr 提为强引用;仅当它非空且不匹配 &view 才 continue,空指针时所有 Context 都参与本 View。
保护性判空在库里出现三次,唯独这里缺席:src/vsg/app/CompileTraversal.cpp:126(view->camera && view->camera->viewportState)、src/vsg/vk/ResourceRequirements.cpp:245(同名判断)、src/vsg/app/View.cpp:84/122(拷贝构造与 share)。而 View::View(const View&) 第 84 行、View::share 第 122 行都判空,说明作者清楚 camera 可空。
交叉引用::432–435 是 viewDependentState 与 viewID 的准备位置,但 :443 之前就被空指针打断。
12.6.2 保存 5 个、恢复 5 个、写入 6 个:viewDependentState 的泄漏
// src/vsg/app/CompileTraversal.cpp:426
auto previous_view = context->view;
auto previous_viewID = context->viewID;
auto previous_mask = context->mask;
auto previous_overridePipelineStates = context->overridePipelineStates;
auto previous_defaultPipelineStates = context->defaultPipelineStates;
:426–430 保存 5 个字段、:449–453 恢复同 5 个;:432–435 写 4 个新值、:443–444 merge 改 2 个容器,合计 6 字段被改写。
代价与边界::439 的 compile(*context) 在循环内对每个匹配 Context 编一次,:456 的 accept(*this) 又在循环外编一次,且走普通 Visitor 分派,没有 :422 的 context_view 过滤,所有 Context 都会被再访问一遍。
交叉引用:BindViewDescriptorSets 不走 StateGroup push、由 ViewDependentState::traverse 直接录制;它在编译期由 :439 与 :456 驱动,阴影贴图入口还有 src/vsg/app/CompileTraversal.cpp:251–280 的 addViewDependentState。
12.6.3 mask 与 t_accept 的配合
逐字段/逐分支推导:View::accept 用模板 t_accept(include/vsg/app/View.h:45–57)在调用 visitor.apply(node) 前后保存并恢复 visitor.traversalMask,把 traversalMask & node.mask 作为子图的新掩码。
代价与边界:context->mask 与 visitor.traversalMask 是两套掩码,前者影响管线状态合并、后者影响是否遍历子节点;apply(View&) 只维护前者,后者由 t_accept 维护,嵌套时各自 push/pop,互不校验。
交叉引用:RecordTraversal::apply(const View&)(include/vsg/app/RecordTraversal.h:165)与 addToBin/clearBins 同段,掩码语义相同但状态栈不同。
12.7 CompileManager:池、队列与 compile() 主流程
源码摘录(src/vsg/app/CompileManager.cpp:130–166)
CompileManager::CompileManager(Viewer& viewer, ref_ptr<ResourceHints> hints)
{
compileTraversals = CompileTraversals::create(viewer.status);
ResourceRequirements requirements(hints);
auto ct = CompileTraversal::create(viewer, requirements);
compileTraversals->add(ct);
#if 0
compileTraversals->add(CompileTraversal::create(*ct));
compileTraversals->add(CompileTraversal::create(*ct));
compileTraversals->add(CompileTraversal::create(*ct));
numCompileTraversals = 4;
#else
numCompileTraversals = 1;
#endif
}
CompileManager::~CompileManager()
{
vsg::debug("CompileManager::~CompileManager() successfulCompileCount= ", successfulCompileCount, ", failedCompileCount = ", failedCompileCount);
}
CompileManager::CompileTraversals::container_type CompileManager::takeCompileTraversals(size_t count)
{
CompileTraversals::container_type cts;
while (cts.size() < count)
{
auto ct = compileTraversals->take_when_available();
if (ct)
cts.push_back(ct);
else
break;
}
return cts;
}
12.7.1 #if 0 关掉的到底是什么
逐字段/逐分支推导:CompileTraversals 是 ThreadSafeQueue<ref_ptr<CompileTraversal>>(include/vsg/app/CompileManager.h:111),构造时用 viewer.status(include/vsg/app/Viewer.h:129 的 ref_ptr<ActivityStatus>)初始化(:132)。
takeCompileTraversals(count)(:153–166)用 take_when_available() 循环取,取不到就 break,返回可能少于 count 的集合。所有 CompileManager::add(...) 重载(src/vsg/app/CompileManager.cpp:168–245)都先 takeCompileTraversals(numCompileTraversals)、逐个改完再 compileTraversals->add(ct) 放回,因此池的并发模型是"借出→修改→归还",借用期间其他线程取不到。
代价与边界:三条线程(主线程、DatabasePager 读线程 src/vsg/io/DatabasePager.cpp:575、用户 compile)都从同一池 take_when_available();池里只有 1 个 ct,后到者在 include/vsg/threading/OperationQueue.h:110–133 每 100ms wait_for,直到 cancel() 或有货。
交叉引用:编译池只以 viewer.status 依赖 ActivityStatus;12.16 给出线程数来源,12.17 讲 DatabasePager 线程如何撞上这个单元素池。
12.7.2 compile() 的六步与异常兜底
源码摘录(src/vsg/app/CompileManager.cpp:257–290)
CompileResult CompileManager::compile(ref_ptr<Object> object, ContextSelectionFunction contextSelection)
{
CollectResourceRequirements collectRequirements;
object->accept(collectRequirements);
auto& requirements = collectRequirements.requirements;
auto& viewDetailsStack = requirements.viewDetailsStack;
VkResult reserve_result = VK_INCOMPLETE;
CompileResult result;
result.maxSlots = requirements.maxSlots;
result.containsPagedLOD = requirements.containsPagedLOD;
result.views = requirements.views;
result.dynamicData = requirements.dynamicData;
result.message = "Nothing assigned yet.";
auto compileTraversal = compileTraversals->take_when_available();
// if no CompileTraversals are available abort compile
if (!compileTraversal)
{
debug("Unable to aquire compileTraversal.");
return result;
}
// src/vsg/app/CompileManager.cpp:257
CompileResult CompileManager::compile(ref_ptr<Object> object, ContextSelectionFunction contextSelection)
{
CollectResourceRequirements collectRequirements;
object->accept(collectRequirements);
每次 compile() 都新建 CollectResourceRequirements(:259)按子图重收,与 Viewer::compile 那份(:305–308)不是同一对象:前者喂 context->reserve,后者按设备去重后喂 compileTask。
源码摘录(src/vsg/app/CompileManager.cpp:282–348)
auto run_compile_traversal = [&]() -> void {
try
{
for (auto& context : compileTraversal->contexts)
{
context->reset();
}
for (auto& context : compileTraversal->contexts)
{
ref_ptr<View> view = context->view;
if (view)
{
result.views[view].add(viewDetailsStack.top());
if (view->viewDependentState)
{
for (auto& sm : view->viewDependentState->shadowMaps)
{
if (sm.view)
{
result.views[sm.view].add(requirements.viewDetailsStack.top());
}
}
}
}
}
for (auto& context : compileTraversal->contexts)
{
reserve_result = context->reserve(requirements);
if (reserve_result != VK_SUCCESS && resourceScavenger && resourceScavenger->scavenge(requirements))
{
reserve_result = context->reserve(requirements);
}
if (reserve_result != VK_SUCCESS)
{
result.message = vsg::make_string("Context::reserve() failed", reserve_result);
result.result = reserve_result;
return;
}
}
object->accept(*compileTraversal);
if (compileTraversal->record())
{
compileTraversal->waitForCompletion();
}
}
catch (const vsg::Exception& ve)
{
result.message = ve.message;
result.result = ve.result;
}
catch (...)
{
result.message = "Exception occurred during compilation.";
result.result = VK_ERROR_UNKNOWN;
}
debug("Finished waiting for compile ", object);
};
六个步骤依次是:context->reset()(:285–288)、按 view 补 result.views(:290–308)、context->reserve(requirements)(:310–326)、object->accept(*compileTraversal)(:328)、record()(:331)、waitForCompletion()(:333)。
代价与边界:N 个 Context 各调一次 context->reserve(src/vsg/vk/Context.cpp:212–225),descriptorPools->reserve 按 ++reserve_count 累加(src/vsg/vk/DescriptorPools.cpp:79),口径依赖 Context 数。
交叉引用:两条路径是否同一份对象、reserve 是否二次调用在此作答;Context::reserve 见 12.11,CompileResult 见 12.8,分页器交接见 12.17。
12.7.3 contextSelection 的两次 swap 与失败回滚
源码摘录(src/vsg/app/CompileManager.cpp:350–390)
// assume success, overwrite this on failures.
result.result = VK_SUCCESS;
if (contextSelection)
{
std::list<ref_ptr<Context>> activeContexts;
for (auto& context : compileTraversal->contexts)
{
if (contextSelection(*context)) activeContexts.push_back(context);
}
compileTraversal->contexts.swap(activeContexts);
run_compile_traversal();
compileTraversal->contexts.swap(activeContexts);
}
else
{
run_compile_traversal();
}
compileTraversals->add(compileTraversal);
if (result.result == VK_SUCCESS)
{
++successfulCompileCount;
}
else
{
++failedCompileCount;
for (auto& context : compileTraversal->contexts)
{
context->reset();
}
}
return result;
}
逐字段/逐分支推导::351 先"假定成功"设 VK_SUCCESS,失败/异常分支覆盖它;ContextSelectionFunction(include/vsg/app/CompileManager.h:91)在 :357–366 两次 swap 筛活跃 Context 并配平。
代价与边界:失败回滚(:383)发生在第二次 swap 之后、作用于完整 contexts;但 run_compile_traversal 内的 reset(:285)只作用于活跃 Context,非活跃者的残留命令整个借用期都没被清。
交叉引用:ThreadSafeQueue::add(include/vsg/threading/OperationQueue.h:46–54)负责 notify_one;compileTask 不走这段借还逻辑。
12.8 CompileResult:结果语义、合并与失败锁定
源码摘录(src/vsg/app/CompileManager.cpp:28–83)
void CompileResult::reset()
{
result = VK_INCOMPLETE;
maxSlots = {};
containsPagedLOD = false;
views.clear();
dynamicData.clear();
}
void CompileResult::add(const CompileResult& cr)
{
if (result == VK_INCOMPLETE || result == VK_SUCCESS)
{
result = cr.result;
}
maxSlots.update(cr.maxSlots);
if (!containsPagedLOD) containsPagedLOD = cr.containsPagedLOD;
for (auto& [src_view, src_binDetails] : cr.views)
{
if (src_binDetails.indices.empty() && src_binDetails.bins.empty()) break;
auto& binDetails = views[src_view];
binDetails.indices.insert(src_binDetails.indices.begin(), src_binDetails.indices.end());
binDetails.bins.insert(src_binDetails.bins.begin(), src_binDetails.bins.end());
}
dynamicData.add(cr.dynamicData);
}
bool CompileResult::requiresViewerUpdate(const Viewer* viewer) const
{
if (result == VK_INCOMPLETE) return false;
if (dynamicData) return true;
for (auto& [view, binDetails] : views)
{
if (!binDetails.indices.empty() || !binDetails.bins.empty()) return true;
}
if (viewer)
{
for (const auto& task : viewer->recordAndSubmitTasks)
{
for (const auto& commandGraph : task->commandGraphs)
{
if (commandGraph->maxSlots.requiresUpdate(maxSlots)) return true;
}
}
}
return false;
}
12.8.1 result 的失败锁定与 reset 的字段清单
// src/vsg/app/CompileManager.cpp:37
void CompileResult::add(const CompileResult& cr)
{
if (result == VK_INCOMPLETE || result == VK_SUCCESS)
{
result = cr.result;
}
result 只在 VK_INCOMPLETE/VK_SUCCESS 时被 cr.result 覆盖(:39–42),一旦置为 VK_ERROR_* 即锁定,后续成功无法洗掉。
代价与边界:reset() 漏清 message 是"只增不减"式残留;maxSlots = {} 清零,add 里 maxSlots.update(cr.maxSlots) 取最大,方向相反但时机不同。
交叉引用:最大调用方 result.add(compileTask(...))(src/vsg/app/Viewer.cpp:401);DatabaseQueue 累积→take_all(src/vsg/io/DatabasePager.cpp:389–395)闭环。
12.8.2 第 50 行的 break:整轮 views 合并被截断
// src/vsg/app/CompileManager.cpp:48
for (auto& [src_view, src_binDetails] : cr.views)
{
if (src_binDetails.indices.empty() && src_binDetails.bins.empty()) break;
遍历 cr.views 时某 view 的 indices 与 bins 皆空即用 break(src/vsg/app/CompileManager.cpp:50)而非 continue——整个循环被首个空 view 截断。
触发条件:多个 View 的结果被 add 合并,且按键排序靠前的某个 view 无 bin/index。后果:CompileResult::views 缺项 → requiresViewerUpdate(:66–69)可能返回 false → Viewer::update 不调 updateViewer(src/vsg/app/Viewer.cpp:808–811)→ 帧期 Bin 数组不补齐,透明物体排序失效且无报错。规避:把 break 改成 continue,并补 lights 的合并。
代价与边界:DatabasePager 每编译一个子图就往 _compileResult 累积(src/vsg/io/DatabasePager.cpp:394),调用越频繁越易撞"首个空 view"。
交叉引用:Viewer::compile 第 327–347 行的 bin 补齐依赖这里的 views,两者是同一份数据。
12.8.3 requiresViewerUpdate 的四道判据
// src/vsg/app/CompileManager.cpp:60
bool CompileResult::requiresViewerUpdate(const Viewer* viewer) const
{
if (result == VK_INCOMPLETE) return false;
if (dynamicData) return true;
requiresViewerUpdate 四道判据:src/vsg/app/CompileManager.cpp:62 INCOMPLETE→false、:64 dynamicData→true、:66–69 views 非空→true、:71–80 maxSlots.requiresUpdate→true。
代价与边界:第四道判据需要调用方传入 viewer;Viewer::update 传的是 this(src/vsg/app/Viewer.cpp:808),DatabasePager::updateSceneGraph 路径也传 viewer,因此常规路径能兜住。
交叉引用:updateTasks(src/vsg/app/Viewer.cpp:891)是 requiresViewerUpdate 为 true 后的动作。
12.9 compileTask:一条不走池的旁路
源码摘录(src/vsg/app/CompileManager.cpp:392–447)
CompileResult CompileManager::compileTask(ref_ptr<RecordAndSubmitTask> task, ResourceRequirements& resourceRequirements)
{
CompileResult result;
// assume success, overwrite this on failures.
result.result = VK_SUCCESS;
try
{
auto compileTraversal = CompileTraversal::create(task->device, resourceRequirements);
auto deviceMemoryBufferPools = task->device->deviceMemoryBufferPools.ref_ptr();
for (auto& context : compileTraversal->contexts)
{
context->reset();
}
for (const auto& context : compileTraversal->contexts)
{
if (resourceRequirements.dataTransferHint == COMPILE_TRAVERSAL_USE_TRANSFER_TASK)
{
context->transferTask = task->transferTask;
}
}
if (deviceMemoryBufferPools && deviceMemoryBufferPools->compileTraversalUseReserve)
{
for (auto& context : compileTraversal->contexts)
{
context->reserve(resourceRequirements);
}
}
for (auto& cg : task->commandGraphs)
{
cg->accept(*compileTraversal);
}
if (compileTraversal->record())
{
compileTraversal->waitForCompletion();
}
}
catch (const vsg::Exception& ve)
{
result.message = ve.message;
result.result = ve.result;
}
catch (...)
{
result.message = "Exception occurred during compilation.";
result.result = VK_ERROR_UNKNOWN;
}
return result;
}
12.9.1 新建遍历、不取池、不做收集
逐字段/逐分支推导::401 的 CompileTraversal::create 只建 1 个 Context(走 src/vsg/app/CompileTraversal.cpp:42–46 → :64–73),六字段全默认。
代价与边界:compileTask 是 Viewer::compile 初始化阶段(src/vsg/app/Viewer.cpp:389–403)按 task 调用的,此时分页器还没 start()(:405–415),通常单线程,绕过池是安全的。
交叉引用:并发 allocateDescriptorSet 在 src/vsg/app/CompileManager.cpp:425–428 与 src/vsg/vk/DescriptorPools.cpp:73–136;mutex 只保护单池,不保护 list 遍历(:95),粒度不配平。
12.9.2 reserve 的守卫与 transferTask 的注入条件
// src/vsg/app/CompileManager.cpp:417
if (deviceMemoryBufferPools && deviceMemoryBufferPools->compileTraversalUseReserve)
{
for (auto& context : compileTraversal->contexts)
:417 的 compileTraversalUseReserve 是 reserve 额外守卫,而 compile() 路径(src/vsg/app/CompileManager.cpp:312)无条件 context->reserve(requirements)。
代价与边界:compileTask 的 contexts 只有一个(Device 类注入),for 是单元素循环;compile() 的 contexts 可能有多个,reserve 被调用多次。
交叉引用:Viewer::compile 用 result.add 汇总时拿不到 compileTask 的 maxSlots/views:compileTask 用 Viewer 统计段那份,compile 用自己新建那份。
12.10 Context:编译期总控的字段与注入
源码摘录(include/vsg/vk/Context.h:75–110,含 reset 与 resourceRequirements)
const uint32_t deviceID = 0;
ref_ptr<Device> device;
ResourceRequirements resourceRequirements;
observer_ptr<View> view;
uint32_t viewID = 0;
Mask mask = MASK_ALL;
ViewDependentState* viewDependentState = nullptr;
/// get existing ShaderCompiler or create a new one when GLSLang is supported
ShaderCompiler* getOrCreateShaderCompiler();
ref_ptr<CommandBuffer> getOrCreateCommandBuffer();
/// reserve resources that may be needed during compile traversal.
VkResult reserve(ResourceRequirements& requirements);
ref_ptr<DescriptorSet::Implementation> allocateDescriptorSet(DescriptorSetLayout* descriptorSetLayout);
// used by GraphicsPipeline.cpp
ref_ptr<RenderPass> renderPass;
GraphicsPipelineStates defaultPipelineStates;
GraphicsPipelineStates overridePipelineStates;
12.10.1 deviceID 是注入值而非恒 0,但构造后不可变
// src/vsg/vk/Context.cpp:90
Context::Context(Device* in_device, const ResourceRequirements& in_resourceRequirements) :
deviceID(in_device->deviceID),
device(in_device),
resourceRequirements(in_resourceRequirements),
deviceID 在 :91 由 in_device->deviceID 注入(拷贝构造 :142 同理),:78 的 = 0 只是默认初始化器,并非恒为 0。
代价与边界:view(:82)是 observer_ptr 不持有引用计数,viewDependentState(:85)是裸指针,生命周期都靠 View 的 ref_ptr;12.6.2 已证恢复清单漏了它,泄漏没有第二道防线。
交叉引用:viewID 与 deviceID 分槽都以本节两个 ID 字段为索引,12.11 讲它们如何被 reset 清理。
12.10.2 三层管线状态与累积队列
逐字段/逐分支推导:renderPass(:98)、defaultPipelineStates(:102)、overridePipelineStates(:110)是第九章 9.6 三层合并的载体,注释(:100–109)明确写了 override 层是为避免 Vulkan 报错而必须设的 MultisampleState。
代价与边界:这些容器是"只增不减"设计,唯一清理点是 Context::reset() 与 waitForCompletion()(12.11.3),而前者漏清一半字段。多轮编译共用同一个 Context(CompileManager 池 activeContexts 复用,src/vsg/app/CompileManager.cpp:373)时,漏清字段会跨轮累积。
12.11 Context 状态机:reserve / copy / record / waitForCompletion
源码摘录(src/vsg/vk/Context.cpp:170–183 与 :212–225)
void Context::reset()
{
if ((commands.size() > 0) || bufferInfosToCopy.size() > 0 || copyImageCmd || copyBufferCmd)
{
vsg::info("Context::reset() commands.size() = ", commands.size(), ", bufferInfosToCopy.size() = ", bufferInfosToCopy.size(), ", copyImageCmd = ", copyBufferCmd, ", copyBufferCmd= ", copyBufferCmd);
}
commands.clear();
bufferInfosToCopy.clear();
copyImageCmd.reset();
copyBufferCmd.reset();
}
VkResult Context::reserve(ResourceRequirements& requirements)
{
CPU_INSTRUMENTATION_L2_NC(instrumentation, "Context reserve", COLOR_COMPILE)
VkResult result = VK_SUCCESS;
if (deviceMemoryBufferPools->compileTraversalUseReserve) result = deviceMemoryBufferPools->reserve(requirements);
resourceRequirements.maxSlots.update(requirements.maxSlots);
descriptorPools->reserve(requirements);
return result;
}
12.11.1 reserve 的三件事与返回值口径
逐字段/逐分支推导::218 仅当 compileTraversalUseReserve 为真时调 MemoryBufferPools::reserve,返回值是唯一可能被检查的 VkResult;:220 把 requirements.maxSlots 并入 resourceRequirements.maxSlots(供 apply(CommandGraph&) 的 :337 回写);:222 descriptorPools->reserve(requirements) 返回值被完全忽略,而 DescriptorPools::reserve 返回 void(src/vsg/vk/DescriptorPools.cpp:73),因此池容量不足在这里无法上报。
代价与边界:DescriptorPools::reserve 的累计逻辑逐字如下。
// src/vsg/vk/DescriptorPools.cpp:80
reserve_maxSets += maxSets;
for (auto& dps : descriptorPoolSizes)
{
auto itr = std::find_if(reserve_descriptorPoolSizes.begin(), reserve_descriptorPoolSizes.end(), [&dps](const VkDescriptorPoolSize& value) { return value.type == dps.type; });
if (itr != reserve_descriptorPoolSizes.end())
itr->descriptorCount += dps.descriptorCount;
reserve_maxSets 与 reserve_descriptorPoolSizes 按调用次数累加,被 N 个 Context 调用就放大 N 倍;getDescriptorPoolSizesToUse(:29)才用 minimum_maxSets 归一化,多 Context 场景没有断言保证调用次数等于预期。
交叉引用:容量低估在此与 reserve 调用次数耦合;12.9.2 已对比两条路径的守卫差异。
12.11.2 record 的未实现拷贝分支与 #if 1 死代码
源码摘录(src/vsg/vk/Context.cpp:283–297 与 :319)
if (transferTask)
{
if (!bufferInfosToCopy.empty())
{
transferTask->assign(bufferInfosToCopy);
bufferInfosToCopy.clear();
}
if (!imageInfosToCopy.empty())
{
transferTask->assign(imageInfosToCopy);
imageInfosToCopy.clear();
}
}
if (commands.empty() && buildAccelerationStructureCommands.empty()) return false;
if ((bufferInfosToCopy.size() + imageInfosToCopy.size()) > 0) vsg::warn("Context::record() ", this, " Need to implement copying of data.");
逐字段/逐分支推导:Context::record 对拷贝队列的收尾逐字如下。
// src/vsg/vk/Context.cpp:293
imageInfosToCopy.clear();
}
}
if (commands.empty() && buildAccelerationStructureCommands.empty()) return false;
两个队列只在 transferTask 分支里被 assign 并 clear;早退条件(第 297 行)只看 commands 与 buildAccelerationStructureCommands,不含 bufferInfosToCopy/imageInfosToCopy,所以无 transferTask 时拷贝队列保持非空却不被消费。
更彻底的是 createBufferAndTransferData(src/vsg/vk/Context.cpp:406–589):第 416 行 #if 1 只保留 deviceMemoryBufferPools->reserve(bufferInfoList, ...) 加 bufferInfosToCopy.insert(:417–423),从第 428 行 #else 到 :588 的 160 余行——含 getModifiedCount(bufferInfo->copiedModifiedCounts[deviceID]) 脏标记(:441)、多 parent 检查(:460–464)、对齐计算(:466–480)、staging buffer 映射与 memcpy(:551–583)——全部是不可达死代码。
代价与边界::350–357 的 semaphore 分支设置 pWaitDstStageMask 却把 waitSemaphoreCount 留 0(submitInfo 由 = {} 初始化,:346),而 semaphore 在构造函数里被注释掉(src/vsg/vk/Context.cpp:96),该分支恒不进入,又是一段死代码。
交叉引用:这些版本化死代码属于"写好未接上"一类;12.14 讲 transferTask 在帧循环里如何被 Viewer 驱动。
12.11.3 waitForCompletion 与 reset 的清理不配平
源码摘录(src/vsg/vk/Context.cpp:371–404)
void Context::waitForCompletion()
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "Context waitForCompletion", COLOR_COMPILE)
vsg::debug("Context::waitForCompletion() ", this);
if (!requiresWaitForCompletion || !commandBuffer || !fence)
{
return;
}
// we must wait for the queue to empty before we can safely clean up the commandBuffer
uint64_t timeout = 1000000000;
VkResult result;
while ((result = fence->wait(timeout)) == VK_TIMEOUT)
{
info("Context::waitForCompletion() ", this, " fence->wait() timed out, trying again.");
}
if (result != VK_SUCCESS)
{
info("Context::waitForCompletion() ", this, " fence->wait() failed with error. VkResult = ", result);
}
requiresWaitForCompletion = false;
commands.clear();
copyImageCmd = nullptr;
copyBufferCmd = nullptr;
}
// src/vsg/vk/Context.cpp:385
uint64_t timeout = 1000000000;
VkResult result;
while ((result = fence->wait(timeout)) == VK_TIMEOUT)
{
info("Context::waitForCompletion() ", this, " fence->wait() timed out, trying again.");
}
:377 提前返回不清理任何容器,commands 留到下一轮;:385 超时 1 秒但 VK_TIMEOUT 无限重试,实为"永不放弃的等待"。
把三处清理点并列看:reset()(:170–183)清 commands/bufferInfosToCopy/copyImageCmd/copyBufferCmd;record()(:288/293)清两个拷贝队列但只在 transferTask 分支;waitForCompletion()(:400–403)清 commands 与两个 cmd。
代价与边界:触发条件是一次 compile() 里 record() 返回 false 或 transferTask 为空,随后 reset() 被下一轮调用(src/vsg/app/CompileManager.cpp:285)。
交叉引用:compile() 六步第 1 步就是 context->reset(),本节的漏清决定第 4 步 record() 看到什么。
12.12 CollectResourceRequirements:25 个分派入口与栈式 view 明细
源码摘录(src/vsg/vk/ResourceRequirements.cpp:243–278)
void CollectResourceRequirements::apply(const View& view)
{
if (view.camera && view.camera->viewportState)
{
requirements.maxSlots.view = std::max(requirements.maxSlots.view, view.camera->viewportState->slot);
}
if (auto itr = requirements.views.find(&view); itr != requirements.views.end())
{
requirements.viewDetailsStack.push(itr->second);
}
else
{
requirements.viewDetailsStack.push(ResourceRequirements::ViewDetails{});
}
view.traverse(*this);
auto& viewDetails = requirements.viewDetailsStack.top();
for (auto& bin : view.bins)
{
viewDetails.bins.insert(bin);
}
requirements.views[&view] = viewDetails;
if (view.viewDependentState)
{
view.viewDependentState->init(requirements);
view.viewDependentState->accept(*this);
}
requirements.viewDetailsStack.pop();
}
12.12.1 入口分组与去重口径
逐字段/逐分支推导:apply 共 26 处(:38 非 Visitor),CollectResourceRequirements 有 23 个 override(:115–137)+2 个 virtual(:141–142),cpp 定义 25 个(:119–:395)。
registerDescriptor 是 12.0.2 第 8 条的证据,逐字如下。
// src/vsg/vk/ResourceRequirements.cpp:175
bool CollectResourceRequirements::registerDescriptor(const Descriptor& descriptor)
{
requirements.descriptorTypeMap[descriptor.descriptorType] += descriptor.getNumDescriptors();
if (requirements.descriptors.count(&descriptor) == 0)
{
requirements.descriptors.insert(&descriptor);
return true;
}
容量累加(第 177 行)位于 descriptors.count(&descriptor) == 0 去重判断之前且无条件执行,同一个 Descriptor 每被访问一次就重复累加一次;外层 apply(const DescriptorSet&) 的 set 级去重保护不到这个内层累加。
代价与边界:触发条件是同一 Descriptor 被多路径共享(SharedObjects 去重后更常见)。computeNumDescriptorSets()/computeDescriptorPoolSizes()(src/vsg/vk/ResourceRequirements.cpp:52)算出的池大小虚高,与容量低估同属"统计不可信",会让 DescriptorPools::reserve 多建池。
交叉引用:本节给出 25 个入口的实测数量;descriptorTypeMap 的三份口径第一份就来自这里。
12.12.2 viewDetailsStack 的 push/pop 与空 ViewDetails
逐字段/逐分支推导:ResourceRequirements 默认构造逐字如下。
// src/vsg/vk/ResourceRequirements.cpp:41
ResourceRequirements::ResourceRequirements()
{
viewDetailsStack.push(ResourceRequirements::ViewDetails{});
}
构造即压入一个空 ViewDetails{},保证 viewDetailsStack.top() 永远有效——这正是 CompileManager::compile 里 top() 不会越界的原因。
代价与边界:第 274 行 view.viewDependentState->accept(*this) 发生在 pop() 之前,阴影贴图相关的 View/Light 会写进当前 view 的栈顶,因此 ViewDetails 是"本视图 + 其 viewDependentState 子树"的合并结果。
12.13 闭环的两端:ResourceRequirements、ResourceHints 与 createResourceHints
源码摘录(src/vsg/vk/ResourceRequirements.cpp:100–117)
ref_ptr<ResourceHints> CollectResourceRequirements::createResourceHints(uint32_t tileMultiplier) const
{
auto resourceHints = vsg::ResourceHints::create();
resourceHints->maxSlots = requirements.maxSlots;
resourceHints->numDescriptorSets = static_cast<uint32_t>(requirements.computeNumDescriptorSets() * tileMultiplier);
resourceHints->descriptorPoolSizes = requirements.computeDescriptorPoolSizes();
for (auto& poolSize : resourceHints->descriptorPoolSizes)
{
poolSize.descriptorCount = poolSize.descriptorCount * tileMultiplier;
}
resourceHints->dynamicData = requirements.dynamicData;
resourceHints->containsPagedLOD = requirements.containsPagedLOD;
return resourceHints;
}
12.13.1 两份字段集不同构
逐字段/逐分支推导:ResourceHints 的字段默认值逐字如下。
// include/vsg/state/ResourceHints.h:63
Slots maxSlots;
uint32_t numDescriptorSets = 0;
DescriptorPoolSizes descriptorPoolSizes;
VkDeviceSize minimumBufferSize = 16 * 1024 * 1024;
VkDeviceSize minimumDeviceMemorySize = 16 * 1024 * 1024;
VkDeviceSize minimumStagingBufferSize = 16 * 1024 * 1024;
uivec2 numLightsRange = {8, 1024};
连同 numDatabasePagerReadThreads 4、dataTransferHint、viewportStateHint、dynamicData、containsPagedLOD、allocatedMemoryLimit 1.0 共 15 组,read/write 逐个序列化这些字段。
代价与边界:std::max(uivec2, uivec2) 对两个分量取最大,但 dataTransferHint 与 viewportStateHint 是覆盖而非合并,多份 hints 叠加时后者胜出且无警告。
交叉引用:本节给出两份字段清单的实测差异;12.12 的 25 个入口生产 requirements,本节讲它如何被压缩成 hints。
12.13.2 只回填 5 个字段的闭环
逐字段/逐分支推导:createResourceHints 的容量来源逐字如下。
// src/vsg/vk/ResourceRequirements.cpp:60
for (auto& [type, count] : descriptorTypeMap)
{
poolSizes.push_back(VkDescriptorPoolSize{type, count});
}
return poolSizes;
computeDescriptorPoolSizes 只从 descriptorTypeMap 造池大小;createResourceHints 仅写 maxSlots、numDescriptorSets、descriptorPoolSizes、dynamicData、containsPagedLOD 五项,丢掉 numDatabasePagerReadThreads、allocatedMemoryLimit、三个 minimum*Size、两个 range、shadowMapSize 与两个 hint。
交叉引用:12.1.2 的 start(hints->numDatabasePagerReadThreads)(src/vsg/app/Viewer.cpp:411)是丢字段后最直接的下游;12.16 讲线程数来源时会再引用这一行。
12.14 Viewer 帧循环与编译屏障
源码摘录(src/vsg/app/Viewer.cpp:793–818 与 :833–851,update 内 CompileResult 合并段)
void Viewer::update()
{
CPU_INSTRUMENTATION_L1_NC(instrumentation, "Viewer update", COLOR_UPDATE);
CompileResult cr;
// merge any updates from the DatabasePager
for (const auto& task : recordAndSubmitTasks)
{
if (task->databasePager)
{
task->databasePager->updateSceneGraph(_frameStamp, cr);
}
}
if (cr.requiresViewerUpdate(this))
{
updateViewer(*this, cr);
}
// run update operations
updateOperations->run();
// run aniamtions
animationManager->run(_frameStamp);
}
#if 1
if (_threading)
#else
if (_threading && _frameStamp->frameCount > 2)
#endif
{
_frameBlock->set(_frameStamp);
_submissionCompleted->arrive_and_wait();
}
12.14.1 update:编译结果回流帧期的唯一闸门
// src/vsg/app/Viewer.cpp:797
CompileResult cr;
// merge any updates from the DatabasePager
for (const auto& task : recordAndSubmitTasks)
{
Viewer::update 构造空 CompileResult(:797),逐 updateSceneGraph 并入(:800–806),requiresViewerUpdate 为真才 updateViewer(:808)。
代价与边界:cr 是局部对象,每帧重新构造,因此 CompileResult::reset() 漏清 message(12.8.1)在这里不会跨帧残留,只在 DatabaseQueue::_compileResult 上残留。
交叉引用:12.8.3 是判据实现,12.17 讲 CompileResult 从哪来,RecordAndSubmitTask 是 updateTasks 的作用对象。
12.14.2 recordAndSubmit:Barrier 与 #if 1 的另一处死代码
// src/vsg/app/Viewer.cpp:833
#if 1
if (_threading)
#else
recordAndSubmit() 先 commandGraph->reset()(:825–831),#if 1 生效 if (_threading)(src/vsg/app/Viewer.cpp:833);#else 带 frameCount > 2 为绕开 helgrind 误报。
代价与边界:这道 Barrier 是帧期提交屏障,不是编译屏障——CompileManager::compile 的等待用的是 Context::waitForCompletion() 的 fence 循环(src/vsg/vk/Context.cpp:371–404),两者不共享同步原语。
交叉引用:Barrier/Latch/FrameBlock 在这里只露接口;12.16 会列出 Latch 在编译路径上的零调用事实。
12.15 SharedObjects、ObjectFactory 与 Options 的装配边界
源码摘录(include/vsg/utils/SharedObjects.h:156–201)
template<class T>
void SharedObjects::share(ref_ptr<T>& object)
{
std::scoped_lock<std::recursive_mutex> lock(mutex);
if (suitableForSharing && !suitableForSharing->suitable(object.get())) return;
auto id = std::type_index(typeid(T));
auto& shared_objects = _sharedObjects[id];
if (auto itr = shared_objects.find(object); itr != shared_objects.end())
{
object = ref_ptr<T>(static_cast<T*>(itr->get()));
return;
}
shared_objects.insert(object);
}
template<class T, typename Func>
void SharedObjects::share(ref_ptr<T>& object, Func init)
{
{
std::scoped_lock<std::recursive_mutex> lock(mutex);
auto id = std::type_index(typeid(T));
auto& shared_objects = _sharedObjects[id];
if (auto itr = shared_objects.find(object); itr != shared_objects.end())
{
object = ref_ptr<T>(static_cast<T*>(itr->get()));
return;
}
}
init(object);
{
std::scoped_lock<std::recursive_mutex> lock(mutex);
auto id = std::type_index(typeid(T));
auto& shared_objects = _sharedObjects[id];
if (suitableForSharing && suitableForSharing->suitable(object.get()))
{
shared_objects.insert(object);
}
}
}
12.15.1 单参 share 与双参 share 的并发差异
// include/vsg/utils/SharedObjects.h:176
void SharedObjects::share(ref_ptr<T>& object, Func init)
{
{
std::scoped_lock<std::recursive_mutex> lock(mutex);
双参 share 把查重、init、插入拆成三段锁,init(object)(:190)在锁外执行:两线程同时未命中会各跑一次 init,set 只留一个但副作用重复。
代价与边界:触发条件:多线程 vsg::read 同一路径且共享 SharedObjects(DatabasePager 读线程正是这种拓扑,src/vsg/io/DatabasePager.cpp:746–750 会把 plod->options->sharedObjects 收进 sharedObjectsToPrune)。
交叉引用:本节补上 SharedObjects 去重在"加载期"与"编译期"的分界;12.12.1 的 registerDescriptor 重复累加在去重后更明显;12.17 讲分页器读线程如何撞上双参版。
12.15.2 Options 与 ObjectFactory 各管一段
// include/vsg/io/Options.h:56
ref_ptr<SharedObjects> sharedObjects;
ReaderWriters readerWriters;
ref_ptr<OperationThreads> operationThreads;
Options 持有 sharedObjects(:56)、findDynamicObjects(:101)、propagateDynamicObjects(:104);读/写分别用 input.readObject/output.writeObject 序列化。
// src/vsg/utils/SharedObjects.cpp:201
LoadedObject::LoadedObject(const Path& in_filename, ref_ptr<const Options> in_options, ref_ptr<Object> in_object) :
filename(in_filename),
options(Options::create_if(in_options, *in_options)),
object(in_object)
第 206 行 if (options) options->sharedObjects = {}; 主动切断反向引用,避免 Options↔SharedObjects 循环持有。
交叉引用:本章只标注 Options/ObjectFactory 与编译遍历的交接行号,不展开 IO 细节。
12.16 多线程编译:线程数、任务划分与同步原语的接口边界
源码摘录(include/vsg/threading/OperationQueue.h:110–133)
value_type take_when_available()
{
std::chrono::duration waitDuration = std::chrono::milliseconds(100);
std::unique_lock lock(_mutex);
// wait until the conditional variable signals that an operation has been added
while (_queue.empty() && _status->active())
{
// debug("Waiting on condition variable");
_cv.wait_for(lock, waitDuration);
}
// if the threads we are associated with should no longer be running go for a quick exit and return nothing.
if (_status->cancel())
{
return {};
}
// remove and return the head of the queue
auto operation = _queue.front();
_queue.erase(_queue.begin());
return operation;
}
12.16.1 线程数的三个来源与任务划分
// include/vsg/state/ResourceHints.h:76
uint32_t numDatabasePagerReadThreads = 4;
DataTransferHint dataTransferHint = COMPILE_TRAVERSAL_USE_TRANSFER_TASK;
编译线程数三源:numCompileTraversals(默认 0、构造置 1,#if 0 的 4 不可达)、:76 的 numDatabasePagerReadThreads = 4(由 Viewer::compile:411 传入)、start() 无参重载用默认。
任务划分因此是"按子图划分、不按 Context 划分":CompileManager::compile(object) 每次接一个 ref_ptr<Object> 子图,内部 CollectResourceRequirements + object->accept(*compileTraversal) 都是整图遍历,没有把场景切成 N 份交给 N 个线程。
代价与边界:实际并发度受限于池里 1 个 CompileTraversal。grep -rn "numCompileTraversals" src include 实测 9 处,其中 6 处是 takeCompileTraversals(numCompileTraversals),全部集中在 CompileManager.cpp:170/185/203/221/239/249;没有任何一处按 hardware_concurrency 或设备数设置线程数。
交叉引用:本节只给同步原语的接口与调用点;12.7.1 已给出 #if 0 的完整上下文。
12.16.2 编译路径上 Latch 与 Barrier 的零使用
逐字段/逐分支推导:grep -rn "Latch\|count_down\|arrive_and_drop" src/vsg include/vsg 实测,Latch 的用户只有 src/vsg/commands/ExecuteCommands.cpp:18/65(帧期 secondary 命令缓冲录制完成信号)与 src/vsg/io/read.cpp:141/150/160(批量异步读文件),CompileManager/CompileTraversal/Context 三个文件零引用。
代价与边界:ActivityStatus(include/vsg/threading/ActivityStatus.h:21–39)以 viewer.status 的形式进入 CompileTraversals::create(viewer.status)(src/vsg/app/CompileManager.cpp:132),是编译池唯一的线程同步依赖;set(false) 后 take_when_available 返回空,编译被静默放弃而非报错。
交叉引用:帧期 Barrier、分页器读线程、编译 fence 构成三套互不相通的同步机制。
12.17 DatabasePager 的编译队列交接点
源码摘录(src/vsg/io/DatabasePager.cpp:565–594)
if (subgraph && compare_exchange(plod->requestStatus, PagedLOD::Reading, PagedLOD::Compiling))
{
{
std::scoped_lock<std::mutex> lock(databasePager.pendingPagedLODMutex);
plod->pending = subgraph;
}
try
{
// compile plod
if (auto result = databasePager.compileManager->compile(subgraph))
{
plod->requestStatus.exchange(PagedLOD::MergeRequest);
// move to the merge queue;
databasePager._toMergeQueue->add(plod, result);
}
else
{
debug("DatabaserPager::start() unable to compile subgraph, discarding request ", subgraph);
databasePager.requestDiscarded(plod);
}
}
catch (...)
{
debug("DatabaserPager::start() compile threw exception, discarding request ", subgraph);
databasePager.requestDiscarded(plod);
}
}
12.17.1 交接点:后台线程直接调 CompileManager::compile
// src/vsg/io/DatabasePager.cpp:565
if (subgraph && compare_exchange(plod->requestStatus, PagedLOD::Reading, PagedLOD::Compiling))
{
{
std::scoped_lock<std::mutex> lock(databasePager.pendingPagedLODMutex);
:565 的 compare_exchange(Reading, Compiling) 是门槛,:575 compileManager->compile(subgraph) 是分页读线程与编译器的唯一交接点。
代价与边界:take_when_available() 因 status 关闭或池被借走超时,返回 VK_INCOMPLETE;整棵 PagedLOD 子图被 requestDiscarded 静默丢弃,无异常、message 仍是 "Nothing assigned yet."。
交叉引用:单元素池是这里等待的根因;CompileResult 经 _toMergeQueue 累积后由 take_all 交给 Viewer::update(12.14.1)回流帧期。
12.17.2 CompileResult 在 DatabaseQueue 里的累积
源码摘录(src/vsg/io/DatabasePager.cpp:389–395 与 :476–484)
void DatabaseQueue::add(ref_ptr<PagedLOD> plod, const CompileResult& cr)
{
std::scoped_lock lock(_mutex);
_queue.emplace_back(plod);
_cv.notify_one();
_compileResult.add(cr);
}
DatabaseQueue::Nodes DatabaseQueue::take_all(CompileResult& cr)
{
std::scoped_lock lock(_mutex);
Nodes nodes;
nodes.swap(_queue);
cr.add(_compileResult);
_compileResult.reset();
return nodes;
}
// src/vsg/io/DatabasePager.cpp:478
std::scoped_lock lock(_mutex);
Nodes nodes;
nodes.swap(_queue);
cr.add(_compileResult);
_compileResult.reset();
take_all 第 481 行 cr.add(_compileResult) 一次性交付、482 行 reset();叠加 add 的 break 截断与失败锁定,累积越多越易撞缺陷。
代价与边界:_compileResult 与队列共用 _mutex,add/take_all 的累积线程安全;但 CompileResult::add 本身无锁,两个队列共享同一结果对象(库里没有这种用法)才会竞争。
交叉引用:DatabasePager 状态机与 updateTasks 是两端;12.14.1 的闸门读的就是这里交出的 cr。
12.18 CompileTraversal 不处理哪些节点:与 RecordTraversal 的分工
源码摘录(include/vsg/app/RecordTraversal.h:116–166 节选,与 include/vsg/app/CompileTraversal.h:96–103 对照)
void apply(const Object& object);
void apply(const Group& group);
void apply(const QuadGroup& quadGroup);
void apply(const LOD& lod);
void apply(const PagedLOD& pagedLOD);
void apply(const TileDatabase& tileDatabase);
void apply(const CullGroup& cullGroup);
void apply(const CullNode& cullNode);
void apply(const DepthSorted& depthSorted);
void apply(const Layer& layer);
void apply(const Switch& sw);
void apply(const RegionOfInterest& roi);
void apply(const VertexDraw& vid);
void apply(const VertexIndexDraw& vid);
void apply(const Geometry& vid);
void apply(const Light& light);
void apply(const AmbientLight& light);
void apply(const DirectionalLight& light);
void apply(const PointLight& light);
void apply(const SpotLight& light);
void apply(const Transform& transform);
void apply(const MatrixTransform& mt);
void apply(const CoordinateFrame& cf);
void apply(const Joint& joint);
void apply(const InstanceNode& instanceNode);
void apply(const InstanceDraw& instanceDraw);
void apply(const InstanceDrawIndexed& instanceDrawIndexed);
void apply(const StateGroup& object);
void apply(const Commands& commands);
void apply(const Command& command);
void apply(const Bin& bin);
void apply(const View& view);
void apply(const CommandGraph& commandGraph);
12.18.1 8 个 apply 对 35 个 apply
// include/vsg/app/CompileTraversal.h:96
void apply(Object& object) override;
void apply(Compilable& node) override;
void apply(Commands& commands) override;
void apply(Geometry& geometry) override;
CompileTraversal 仅 8 个 apply(:96–103):Object/Compilable/Commands/Geometry/CommandGraph/SecondaryCommandGraph/RenderGraph/View。
代价与边界:编译期不处理 LOD/CullNode,所有层级与剔除分支全量编译;帧期切换免重编译,代价是显存按最坏情况计。
交叉引用:StateGroup 状态栈、三层管线状态都是 RecordTraversal 才用到的机制;12.2 的分组表是这 8 个 apply 的完整行为清单。
12.18.2 为什么必须另有一个 RecordTraversal
逐字段/逐分支推导:CompileTraversal 编译期建 Vulkan 对象按 deviceID/viewID 分槽;RecordTraversal 继承 Object(Slots/Bin)帧期录 VkCommandBuffer。
// include/vsg/app/RecordTraversal.h:73
class VSG_DECLSPEC RecordTraversal : public Object
{
public:
explicit RecordTraversal(const Slots& in_maxSlots = {}, const std::set<Bin*>& in_bins = {});
CompileTraversal 继承 Visitor(:33),RecordTraversal 直接继承 Object(:73)并收 Slots、做 culling;两者不同基类,分派表刻意独立。
交叉引用:本章解释编译遍历为何只需要 8 个特化;View/Camera 与 RecordAndSubmitTask 的帧期流水由后续章节展开。
数字表与源码索引
按文件分组,逐条给出实测 完整路径:行区间 与该处结论。所有行号以 grep -n / cat -n 为准,复现命令见下一节。
src/vsg/app/CompileTraversal.cpp(479 行)
src/vsg/app/CompileTraversal.cpp:36:overrideMask = MASK_ALL,遍历掩码不被清零。src/vsg/app/CompileTraversal.cpp:64–73:Device 类add只注入 device/commandPool/graphicsQueue/transferTask,renderPass留空。src/vsg/app/CompileTraversal.cpp:80–99:Window+Viewport 注入renderPass、defaultPipelineStates,:97按 samples 条件加MultisampleState。src/vsg/app/CompileTraversal.cpp:110–138:Window+View 注入view/viewID/viewDependentState,:126有 camera 判空。src/vsg/app/CompileTraversal.cpp:190–249:AddViews用objectStack传递 RenderGraph→View 的归属,栈空时静默跳过 View。src/vsg/app/CompileTraversal.cpp:291–329:四个通用apply,Commands(:310)是唯一不traverse的分支。src/vsg/app/CompileTraversal.cpp:331–341:apply(CommandGraph&)只maxSlots.update,不保存恢复上下文。src/vsg/app/CompileTraversal.cpp:343–381:apply(SecondaryCommandGraph&)保存恢复 3 字段,:371无条件加MultisampleState。src/vsg/app/CompileTraversal.cpp:383–413:apply(RenderGraph&)保存恢复 3 字段,:395单向写viewportStateHint,不改viewID。src/vsg/app/CompileTraversal.cpp:415–457:apply(View&)保存 5 恢复 5 写入 6,:443裸解引用view.camera,:456循环外二次 accept。src/vsg/app/CompileTraversal.cpp:459–479:record/waitForCompletion遍历所有contexts逐个转调。
src/vsg/app/CompileManager.cpp(447 行)
src/vsg/app/CompileManager.cpp:28–35:CompileResult::reset漏清message。src/vsg/app/CompileManager.cpp:37–58:add的失败锁定、:50的break截断、漏合并lights。src/vsg/app/CompileManager.cpp:60–83:requiresViewerUpdate四道判据。src/vsg/app/CompileManager.cpp:130–146:#if 0关闭 4 遍历复制,:144生效为numCompileTraversals = 1。src/vsg/app/CompileManager.cpp:153–166:takeCompileTraversals借出不足时break。src/vsg/app/CompileManager.cpp:257–390:compile()六步、:296共用viewDetailsStack.top()、:315–318scavenge 重试、:362/366两次 swap。src/vsg/app/CompileManager.cpp:392–447:compileTask新建遍历、:417双重 reserve 守卫、不检查 reserve 返回值。
src/vsg/vk/Context.cpp(599 行)与 include/vsg/vk/Context.h(160 行)
include/vsg/vk/Context.h:78/82/85:deviceIDconst、viewobserver_ptr、viewDependentState裸指针。src/vsg/vk/Context.cpp:90–138:构造注入deviceID、复用三个共享池、:134–137动态视口状态。src/vsg/vk/Context.cpp:170–183:reset()漏清imageInfosToCopy等四字段,:174日志变量错用。src/vsg/vk/Context.cpp:212–225:reserve三件事,descriptorPools->reserve返回被忽略。src/vsg/vk/Context.cpp:277–369:record,:297提前返回、:319未实现拷贝告警、:346–364semaphore 死分支与无返回值检查。src/vsg/vk/Context.cpp:371–404:waitForCompletionfence 无限重试,清理只 4 项。src/vsg/vk/Context.cpp:416/:428–588:#if 1把 160 余行脏标记与 staging 实现压成死代码。
src/vsg/vk/ResourceRequirements.cpp(418 行)与 include/vsg/vk/ResourceRequirements.h(149 行)
include/vsg/vk/ResourceRequirements.h:86–96:三个 16MB 默认值、两个 range、shadowMapSize、两个 hint。include/vsg/vk/ResourceRequirements.h:115–142:23 个applyoverride + 2 个 virtual 辅助。src/vsg/vk/ResourceRequirements.cpp:41–44:构造 push 空ViewDetails,保证top()有效。src/vsg/vk/ResourceRequirements.cpp:67–94:apply(ResourceHints)合并 12 组标量,两个 hint 直接覆盖。src/vsg/vk/ResourceRequirements.cpp:100–117:createResourceHints只回填 5 字段,uint32_t乘法无溢出检查。src/vsg/vk/ResourceRequirements.cpp:175–188:registerDescriptor去重前累加容量。src/vsg/vk/ResourceRequirements.cpp:243–278:apply(View&)的viewDetailsStackpush/pop 与空ViewDetails来源。src/vsg/vk/ResourceRequirements.cpp:373–418:BufferInfo/ImageInfo 先去重再累加,与描述符口径不一致。
src/vsg/app/Viewer.cpp(892 行)与 include/vsg/app/Viewer.h(174 行)
src/vsg/app/Viewer.cpp:278–325:Viewer::compile统计段,按 device 归并CollectResourceRequirements。src/vsg/app/Viewer.cpp:327–347:bin 补齐,注释与实现不符(不分配viewID)。src/vsg/app/Viewer.cpp:355–417:CompileManager 惰性装配、:401result.add(compileTask)、:402导出dynamicData、:411分页线程数。src/vsg/app/Viewer.cpp:793–818:update的requiresViewerUpdate闸门。src/vsg/app/Viewer.cpp:820–852:recordAndSubmit,:833–840另一处#if 1、:843Barrier。include/vsg/app/Viewer.h:94/129/166/167:compileManager/status/_frameBlock/_submissionCompleted字段。
其余实测锚点
src/vsg/app/View.cpp:25–42/60–64/70–75/113–119:getUniqueViewID、releaseViewID无边界检查、默认构造不设 camera、share的const_cast。src/vsg/app/RenderGraph.cpp:58–73与src/vsg/app/SecondaryCommandGraph.cpp:60–75:getRenderPass()逐行同构的三级回退。include/vsg/app/RecordTraversal.h:116–166:35 个apply,对照CompileTraversal的 8 个。include/vsg/state/ResourceHints.h:63–88与src/vsg/state/ResourceHints.cpp:31–146:maxSlots的 15 组默认字段、input.read/write的 18 组序列化。src/vsg/vk/DescriptorPools.cpp:29–70/73–136/159–234:reserve_*归一化、累计量、四本账的统计函数。include/vsg/threading/OperationQueue.h:110–133:take_when_available100ms 轮询与 cancel 短路。include/vsg/threading/ActivityStatus.h:21–39、include/vsg/threading/Barrier.h:35–67(arrive_and_wait)、include/vsg/threading/Latch.h:51–76(count_down/fetch_sub):同步原语接口,编译路径零用Latch。src/vsg/io/DatabasePager.cpp:389–395/476–484/565–594:CompileResult累积、take_all、后台线程调compileManager->compile(subgraph)并静默丢弃失败子图。include/vsg/utils/SharedObjects.h:157–201与src/vsg/io/read.cpp:76–98:单参share全程持锁、双参share的 TOCTOU 竞态。src/vsg/state/GraphicsPipeline.cpp:175–182:复用判据只比_pipelineStates,是 12.4.2 绑错 renderPass 的另一半。include/vsg/app/CompileTraversal.h:43–44:queueFlags = VK_QUEUE_GRAPHICS_BIT、queueFamilyIndex = 1。
可复现验证
以下命令均在仓库根目录 VulkanSceneGraph-1.1.16 直接运行,输出为 1.1.16 源码实测值。
# 期望:18 个正面处理文件合计 5303 行
wc -l include/vsg/app/CompileTraversal.h src/vsg/app/CompileTraversal.cpp \
include/vsg/app/CompileManager.h src/vsg/app/CompileManager.cpp \
include/vsg/vk/Context.h src/vsg/vk/Context.cpp \
include/vsg/vk/ResourceRequirements.h src/vsg/vk/ResourceRequirements.cpp \
src/vsg/app/Viewer.cpp src/vsg/app/View.cpp src/vsg/app/RenderGraph.cpp \
src/vsg/app/SecondaryCommandGraph.cpp include/vsg/app/RecordTraversal.h \
src/vsg/app/RecordTraversal.cpp include/vsg/state/ResourceHints.h \
src/vsg/state/ResourceHints.cpp src/vsg/vk/DescriptorPools.cpp | tail -1
# 期望:8(CompileTraversal 的 apply 定义数);11(含 addViewDependentState 的 add 前缀数)
grep -c "^void CompileTraversal::apply" src/vsg/app/CompileTraversal.cpp
grep -c "^void CompileTraversal::add" src/vsg/app/CompileTraversal.cpp
# 期望:第 443 行裸解引用、第 126 行有判空;第 50 行为 break
grep -n "view.camera->viewportState" src/vsg/app/CompileTraversal.cpp
grep -n "break;" src/vsg/app/CompileManager.cpp
# 期望:第 174 行日志把 copyImageCmd 打成 copyBufferCmd;reset 内无 imageInfosToCopy.clear()
grep -n "copyImageCmd = \", copyBufferCmd\|imageInfosToCopy" src/vsg/vk/Context.cpp | head
# 期望:第 144 行 numCompileTraversals = 1,第 142 行的 4 位于 #if 0 块内
sed -n '138,146p' src/vsg/app/CompileManager.cpp
# 期望:64 / 47 / 8 三种 compile 调用形态计数;.compile( 另有 6 处
grep -rn "\->compile(" src/vsg include/vsg | wc -l
grep -rn "compile(context" src/vsg include/vsg | wc -l
grep -rn "compile(\*context" src/vsg include/vsg | wc -l
# 期望:26 处 void apply( 声明;25 个 CollectResourceRequirements::apply 定义
grep -c "void apply(" include/vsg/vk/ResourceRequirements.h
grep -c "^void CollectResourceRequirements::apply" src/vsg/vk/ResourceRequirements.cpp
# 期望:编译三文件零 Latch;Barrier 仅在 Viewer.cpp 两处
grep -rn "Latch\|count_down" src/vsg/app/CompileManager.cpp src/vsg/app/CompileTraversal.cpp src/vsg/vk/Context.cpp
grep -rn "arrive_and_wait\|arrive_and_drop" src/vsg/app/Viewer.cpp
# 期望:DatabasePager 第 575 行是唯一 compileManager->compile 交接点
grep -n "compileManager->compile" src/vsg/io/DatabasePager.cpp
凡涉及 Vulkan SDK 头文件的字节数(如 VkDescriptorPoolSize、VkSubmitInfo 的 sizeof),仓库内 include/vsg/vk/vulkan.h 只是转发头,实际布局取决于本机 SDK 版本,以本机 SDK 为准;可用如下测量程序在已配置 SDK 的环境里取值,本章不臆造具体字节数:
# 期望:输出本机 SDK 下三个结构体的 sizeof,数值随 SDK 版本变化
cat > /tmp/vsg_sizeof.cpp <<'EOF'
#include <vulkan/vulkan.h>
#include <cstdio>
int main() {
std::printf("VkSubmitInfo=%zu VkDescriptorPoolSize=%zu VkViewport=%zu\n",
sizeof(VkSubmitInfo), sizeof(VkDescriptorPoolSize), sizeof(VkViewport));
return 0;
}
EOF
echo "用本机 Vulkan SDK 的编译器编译 /tmp/vsg_sizeof.cpp 后运行"
陷阱表与批判性结论
| # | 位置(函数 / 完整路径:行号) | 触发条件 | 后果 | 规避 |
|---|---|---|---|---|
| 1 | CompileTraversal::apply(View&) / src/vsg/app/CompileTraversal.cpp:443 | 默认构造或 camera 为空的 View 被编译遍历 | 空指针解引用崩溃,无异常无日志 | 所有 View 显式构造 Camera;在 :443 前补判空并跳过 merge |
| 2 | CompileTraversal::apply(View&) / src/vsg/app/CompileTraversal.cpp:425–435/448–453 | 遍历含 viewDependentState 的 View 后继续编译兄弟节点 | 裸指针泄漏给后续 compile,view/viewID 与状态对象不配平 | 把 viewDependentState 加入保存/恢复清单 |
| 3 | apply(RenderGraph&) / apply(SecondaryCommandGraph&) / src/vsg/app/CompileTraversal.cpp:389–411/354–379 | 同一 GraphicsPipeline 出现在两个不同 renderPass 的图下 | 按 viewID 复用旧实现,绑错 VkRenderPass | 不同 renderPass 用不同管线实例;把 renderPass 纳入复用键 |
| 4 | CompileManager::CompileManager / src/vsg/app/CompileManager.cpp:138–145 | 两个线程同时 compile() | 池里仅 1 个遍历,后者 100ms 粒度忙等,编译串行化 | 打开 #if 0 并验证 Context 拷贝对共享池安全 |
| 5 | CompileResult::add / src/vsg/app/CompileManager.cpp:48–55 | 多个 view 合并且首个 view 的 indices/bins 皆空 | break 截断整轮合并,lights 也未合并,bin 明细静默丢失 | 改 break 为 continue,补 lights 的 insert |
| 6 | Context::reset / src/vsg/vk/Context.cpp:170–183 | 上一轮 record() 返回 false 或 transferTask 为空 | imageInfosToCopy 等四字段跨轮累积,过期数据被重复上传 | 补齐四个字段的清理并修正 :174 日志变量 |
| 7 | Context::record / src/vsg/vk/Context.cpp:319 | dataTransferHint = COMPILE_TRAVERSAL_TRANSFER_DATA_AND_WAIT 或 transferTask 为空 | 只 warn 不上传,GPU 读未初始化数据 | 始终保证 transferTask 非空并使用 TRANSFER_TASK hint |
| 8 | Context::createBufferAndTransferData / src/vsg/vk/Context.cpp:416/428–588 | 期待编译后修改数据能被脏标记检测 | 160 余行脏标记/staging 实现是 #if 1 下的死代码 | 启用 #else 分支或删除死代码,明确一次性写入语义 |
| 9 | CollectResourceRequirements::registerDescriptor / src/vsg/vk/ResourceRequirements.cpp:175–188 | 同一 Descriptor 被多条路径共享 | 去重前累加 descriptorTypeMap,池容量虚高 | 把累加移入 count == 0 分支 |
| 10 | CollectResourceRequirements::createResourceHints / src/vsg/vk/ResourceRequirements.cpp:100–117 | 收集结果生成 hints 后再喂给 Viewer::compile | 10 组字段丢失;uint32_t 乘法可回绕 | 逐项回填并加溢出检查 |
| 11 | CompileManager::compile / src/vsg/app/CompileManager.cpp:276–280 | take_when_available() 拿不到遍历(status 关闭或池被借走) | 返回 VK_INCOMPLETE 且 message 仍是初始文本,静默降级 | 区分"池关闭"与"暂空",写明确 message |
| 12 | CompileManager::compileTask / src/vsg/app/CompileManager.cpp:419–423(compileTraversalUseReserve 守卫) | 守卫内 context->reserve 返回失败但不抛异常 | 不检查返回值,继续遍历并最终报 VK_SUCCESS | 与 compile() 一样检查 reserve_result |
| 13 | DatabasePager 编译循环 / src/vsg/io/DatabasePager.cpp:575–593 | 编译返回非成功或抛异常 | 整棵 PagedLOD 子图被 requestDiscarded 静默丢弃 | 把 CompileResult.message 上抛到日志/重试预算 |
| 14 | SharedObjects::share(ref_ptr<T>&, Func) / include/vsg/utils/SharedObjects.h:176–201 | 多线程读同一路径且共享 SharedObjects | 查重与 init 分离,两个线程都执行 init,重复 IO | 把 init 移入临界区或用双检锁 |
| 15 | View::share / releaseViewID / src/vsg/app/View.cpp:60–64/113–119 | const_cast 改写 viewID 或传入越界 ID | 修改 const 成员、--s_ActiveViews[viewID] 无边界检查 | 去掉 const 或加边界断言 |
| 16 | CompileTraversal::apply(Commands&) / src/vsg/app/CompileTraversal.cpp:310–318 | Commands 内部含需上下文注入的子节点 | 不 traverse,内部对象不经过 apply 特化 | 明确 Commands::compile 自行递归的契约 |
| 17 | CompileResult::requiresViewerUpdate / src/vsg/app/CompileManager.cpp:62 | 编译返回 VK_INCOMPLETE 但 views 已有编译好的 bin | :62 直接 return false,Viewer::update 不调用,已编译子集静默丢弃 | 区分完全失败与部分完成,按 views 决定是否更新 |
| 18 | CompileTraversal 基类 / include/vsg/app/CompileTraversal.h:33 | 想把 RecordTraversal 的 culling 复用到编译期 | 两者基类不同(Visitor vs Object),apply 分派表不通用 | 不混用两遍历的多态,各自扩展 |
| 19 | Context 拷贝构造 / src/vsg/vk/Context.cpp:142 | 打开 #if 0 复制含 defaultPipelineStates 的 Context | deviceID 拷贝值、三个池经 ref_ptr 共享,改一个影响全部 | 确认池共享语义后再启用 |
| 20 | SharedObjects::LoadedObject / src/vsg/utils/SharedObjects.cpp:206 | 反序列化场景时 Options 已带 sharedObjects | :206 主动清空 options->sharedObjects,后续加载不再复用该池 | 若需跨文件复用,加载前重新绑定 Options::sharedObjects |
三条批判性结论
第一,编译阶段的状态管理没有统一的所有权模型,是本章全部硬缺陷的共同根源。 Context 上并存三类字段:由构造函数注入且不可变的 deviceID(include/vsg/vk/Context.h:78、src/vsg/vk/Context.cpp:91)、由 apply(View&) 反复保存恢复的 view/viewID/mask(src/vsg/app/CompileTraversal.cpp:426–453)、以及只在 reset/record/waitForCompletion 三处被部分清理的累积队列(src/vsg/vk/Context.cpp:170–183/277–404)。三类字段的生命周期规则各不相同,却没有 RAII 守卫或状态机类来统一维护,于是"保存 5 个恢复 5 个写入 6 个"这种不对称(src/vsg/app/CompileTraversal.cpp:425–435 对比 :448–453)与"三处清理点各清一部分"的不配平(imageInfosToCopy 只在 record() 的 transferTask 分支被清)成为必然。更糟的是 viewDependentState 是裸指针(include/vsg/vk/Context.h:85),泄漏后没有任何第二道防线。库靠 CompileManager 池里只有一个 CompileTraversal(src/vsg/app/CompileManager.cpp:144)把并发压成串行,用部署拓扑替代代码正确性;一旦有人打开 #if 0 或并发调用 compileTask(src/vsg/app/CompileManager.cpp:392),这些不对称会立刻从"潜在"变成"可复现"。收敛方向是把上下文切换抽成作用域守卫、把累积队列收进一个可整体 clear() 的结构、把裸指针换成 observer_ptr。
第二,"统计—分配—上传"三段式缺少单一真相,容量与结果在每一跳都可能被改写。 第一跳:CollectResourceRequirements 的 registerDescriptor(src/vsg/vk/ResourceRequirements.cpp:177)在去重前无条件累加 descriptorTypeMap,而 apply(ref_ptr<BufferInfo>)(:380)与 apply(ref_ptr<ImageInfo>)(:397)都先去重再累加,同一次收集里两套口径并存。第二跳:Context::reserve(src/vsg/vk/Context.cpp:212–225)忽略 descriptorPools->reserve 的容量反馈,DescriptorPools::reserve(src/vsg/vk/DescriptorPools.cpp:79–80)又按调用次数累加 reserve_count/reserve_maxSets,多 Context 场景的累计量靠 getDescriptorPoolSizesToUse(:29–70)事后归一化,没有断言。第三跳:CompileResult::add(src/vsg/app/CompileManager.cpp:37–58)用 break 截断 views 合并、漏并 lights、失败后锁定 result,Viewer::compile(src/vsg/app/Viewer.cpp:401)按 task 逐个 add 把截断放大。第四跳:createResourceHints(src/vsg/vk/ResourceRequirements.cpp:100–117)只回填 5 组字段,闭环回不到起点。四跳各自维护一份"真相",任何一处偏差都会沿链传播到池大小、bin 补齐与帧期更新判定(src/vsg/app/Viewer.cpp:808),且因为 views 是按键地址排序的 std::map,缺陷表现为偶发而非稳定复现。修法不是逐处打补丁,而是让 ResourceRequirements 成为唯一数据源,其余都是它的视图或投影。
第三,"多线程编译如何收敛"的答案与直觉相反:当前版本并不并行,收敛靠的是单点串行与静默降级。 构造里 #if 0 关闭了 4 个 CompileTraversal 复制,生效的只有 numCompileTraversals = 1(src/vsg/app/CompileManager.cpp:138–145);takeCompileTraversals(:153–166)借出不足即 break,ThreadSafeQueue::take_when_available(include/vsg/threading/OperationQueue.h:110–133)以 100ms 轮询等待,第二个编译线程实际被阻塞到前者归还。于是 DatabasePager 读线程(src/vsg/io/DatabasePager.cpp:575)、Viewer::compile 主线程、用户手动编译共享同一个遍历对象,吞吐上限是 1;#if 0 里那段多遍历代码零调用,与第九章零 VkPipelineCache、零 validated_vk() 同属写好未接上的 API。收敛也不靠同步原语:编译路径零用 Latch(实测仅 src/vsg/commands/ExecuteCommands.cpp:18/65 与 src/vsg/io/read.cpp:141/160),vsg::Barrier 只在 src/vsg/app/Viewer.cpp:642/843 的帧期提交,编译等待完全由 Context::waitForCompletion 的 fence 无限循环(src/vsg/vk/Context.cpp:385–391)承担。失败路径更弱:take_when_available 返回空时 compile() 只 debug 一句就返回 VK_INCOMPLETE(src/vsg/app/CompileManager.cpp:276–280),分页器随后 requestDiscarded 整棵子图(src/vsg/io/DatabasePager.cpp:587),用户看不到任何错误。所谓"收敛",实质是把并发、错误与容量三件事都收敛成"不报错地少做一点",代价转移给了使用者的部署约束。
下章预告
本章结束。下一章精确对齐 README 第 13 章标题「视图与相机:View、Camera、投影与视矩阵」,要回答本章留下的六个具体问题:
CompileTraversal::apply(View&)在src/vsg/app/CompileTraversal.cpp:443裸解引用的view.camera->viewportState,Camera在什么构造路径下被赋值?ViewportState::slot与CollectResourceRequirements::apply(const View&)(src/vsg/vk/ResourceRequirements.cpp:245–248)更新的maxSlots.view是同一个值吗?View::viewID由src/vsg/app/View.cpp:25–42的全局分配器产生、View::share(:113–119)用const_cast改写,Camera的投影矩阵与视矩阵按什么键缓存?getUniqueViewID/releaseViewID(:60–64)的无边界检查在多视图共享时是否会被触发?apply(View&)保存/恢复清单漏掉的viewDependentState(src/vsg/app/CompileTraversal.cpp:435),在 12.6.2 里泄漏给后续节点;ViewDependentState::init(requirements)(src/vsg/vk/ResourceRequirements.cpp:272)与ViewDependentState::compile(*context)(:439)分别负责什么?BindViewDescriptorSets不走StateGrouppush(第八章 8.2.4)时,位置状态如何与相机矩阵对齐?addViewDependentState(src/vsg/app/CompileTraversal.cpp:251–280)里shadowMaps.front()的嵌套 framebuffer、view->camera->getRenderArea()(src/vsg/app/RenderGraph.cpp:44)与投影矩阵的关系是什么?多阴影贴图视图的编译时机为什么由三个入口而非一个驱动?Context::defaultPipelineStates在src/vsg/app/CompileTraversal.cpp:93–95/127–129/169–171被三处注入,其中DynamicState(VK_DYNAMIC_STATE_VIEWPORT, VK_DYNAMIC_STATE_SCISSOR)(src/vsg/vk/Context.cpp:136)由viewportStateHint决定;RenderGraph::viewportStateHint(:395)单向写回后,帧期动态/静态视口分派(第九章 9.12)与相机投影如何配合?- 第十三章的 headlight、
View::mask(include/vsg/app/View.h:78)与t_accept(:45–57)的掩码语义,和本章context->mask(src/vsg/app/CompileTraversal.cpp:434)影响的三层管线状态合并是否共用一套掩码?两套掩码不校验的边界在相机切换时会暴露吗?
编译遍历把 Vulkan 对象建出来之后,视图与相机才决定这些对象每一帧被怎样看见,这是第十三章的主线。