《VulkanSceneGraph 1.1.16 源码深度解析》第十二章 编译遍历:CompileTraversal 与 CompileManager

0 阅读59分钟

《VulkanSceneGraph 1.1.16 源码深度解析》第十二章 编译遍历:CompileTraversal 与 CompileManager

12.0 先把规模和答案摆出来

第十一章收尾时把六个问题留在了桌面上,本章逐条作答,先把原问题抄在这里,读者可以对照着验收:

  1. DescriptorSet::compile(src/vsg/state/DescriptorSet.cpp:70–87)在遍历中先编译 setLayout 再逐个 descriptors 的 apply 由谁调用;CompileTraversal 的分派顺序如何保证"布局先于分配、描述符先于写入"。
  2. 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 拿副本还是共享引用。
  3. 第十一章 11.7.2 空返回值链、11.8.3 兜底新建池、11.9.3 容量低估,在 CompileManager::compileTask(src/vsg/app/CompileManager.cpp:392)的多线程路径下会被并发 allocateDescriptorSet 放大吗;DescriptorPool::mutex 与 std::list descriptorPools 的访问粒度是否配平。
  4. 第九章 9.12 两条 resize 重建路径、WindowResizeHandler::release(viewID) 与 DescriptorSet::release(deviceID) 如何配平;重建管线时描述符集是复用还是整批回收进 _recyclingList。
  5. BindViewDescriptorSets 由 ViewDependentState::traverse 直接录制、不走 StateGroup 的 push(第八章 8.2.4),CompileTraversal 的 View 分支如何准备 viewDependentState 与 viewID;阴影贴图描述符的编译时机由谁驱动。
  6. "一次性写入"与"池一次建够"在 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.h1138 个 apply 声明、10 个 add 声明、contexts 容器、compile(T, bool) 模板
src/vsg/app/CompileTraversal.cpp4798 个 apply 实现、10 个 add 实现、AddViews 内部 Visitor、record/waitForCompletion
include/vsg/app/CompileManager.h119CompileResult、ResourceScavenger、CompileManager、ThreadSafeQueue 池
src/vsg/app/CompileManager.cpp447compile() 主流程、compileTask() 旁路、#if 0 多线程开关、异常兜底
include/vsg/vk/Context.h160编译期总控全部字段:deviceID/viewID/mask/三层管线状态/拷贝队列
src/vsg/vk/Context.cpp599构造注入 deviceID、reserve/copy/record/waitForCompletion 状态机、#if 1 死代码
include/vsg/vk/ResourceRequirements.h149ResourceRequirements 默认值、ViewDetails、26 处 void apply( 声明
src/vsg/vk/ResourceRequirements.cpp41825 个 CollectResourceRequirements::apply 定义、createResourceHints、registerDescriptor
src/vsg/app/Viewer.cpp892Viewer::compile/update/recordAndSubmit、updateViewer、编译屏障接合点
src/vsg/app/View.cpp127viewID 全局分配器、View::share 的 const_cast、camera 判空分支
src/vsg/app/RenderGraph.cpp230getRenderPass() 三级回退、accept(RecordTraversal&)、resize 分派
src/vsg/app/SecondaryCommandGraph.cpp177getRenderPass() 三级回退、level()、reset()/_connect
include/vsg/app/RecordTraversal.h191约 35 个 apply 声明,用于对照 CompileTraversal 不处理的节点
src/vsg/app/RecordTraversal.cpp704帧期遍历实现,本章只取其分工边界
include/vsg/state/ResourceHints.h99两个 hint 枚举、DynamicData、ResourceHints 全部默认字段
src/vsg/state/ResourceHints.cpp148read/write 的 18 组序列化字段
src/vsg/vk/DescriptorPools.cpp251reserve 累计量、四本账、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 答案骨架

先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对:

#结论主要证据性质
1apply(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硬缺陷
2apply(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硬缺陷
3apply(RenderGraph&) 与 apply(SecondaryCommandGraph&) 临时替换 renderPass 却不改 viewID,与第九章 GraphicsPipeline::compile 只比 _pipelineStates 叠加,会把子图管线绑到错误的 renderPasssrc/vsg/app/CompileTraversal.cpp:389–411、src/vsg/app/CompileTraversal.cpp:354–379、src/vsg/state/GraphicsPipeline.cpp:175–182硬缺陷
4CompileManager 构造函数 #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设计取舍
5CompileResult::add 合并 views 时用 break 而非 continue,遇到第一个 indices 与 bins 皆空的 view 就终止整轮合并,后续 view 的 bin 明细静默丢失src/vsg/app/CompileManager.cpp:48–55硬缺陷
6Context::reset() 只清 commands/bufferInfosToCopy/copyImageCmd/copyBufferCmd,漏清 imageInfosToCopy、buildAccelerationStructureCommands、scratchBufferSize、requiresWaitForCompletion;第 174 行把 copyImageCmd 的值误打成 copyBufferCmdsrc/vsg/vk/Context.cpp:170–183、src/vsg/vk/Context.cpp:290–293、src/vsg/vk/Context.cpp:595–596硬缺陷
7Context::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硬缺陷
8registerDescriptor 在去重判断之前无条件累加 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硬缺陷
9createResourceHints 只回填 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硬缺陷
10CompileTraversal 只有 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–318 scavenge 重试、: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:deviceID const、view observer_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–364 semaphore 死分支与无返回值检查。
  • src/vsg/vk/Context.cpp:371–404:waitForCompletion fence 无限重试,清理只 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 个 apply override + 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&) 的 viewDetailsStack push/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 惰性装配、:401 result.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、:843 Barrier。
  • 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_available 100ms 轮询与 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 后运行"

陷阱表与批判性结论

#位置(函数 / 完整路径:行号)触发条件后果规避
1CompileTraversal::apply(View&) / src/vsg/app/CompileTraversal.cpp:443默认构造或 camera 为空的 View 被编译遍历空指针解引用崩溃,无异常无日志所有 View 显式构造 Camera;在 :443 前补判空并跳过 merge
2CompileTraversal::apply(View&) / src/vsg/app/CompileTraversal.cpp:425–435/448–453遍历含 viewDependentState 的 View 后继续编译兄弟节点裸指针泄漏给后续 compile,view/viewID 与状态对象不配平把 viewDependentState 加入保存/恢复清单
3apply(RenderGraph&) / apply(SecondaryCommandGraph&) / src/vsg/app/CompileTraversal.cpp:389–411/354–379同一 GraphicsPipeline 出现在两个不同 renderPass 的图下按 viewID 复用旧实现,绑错 VkRenderPass不同 renderPass 用不同管线实例;把 renderPass 纳入复用键
4CompileManager::CompileManager / src/vsg/app/CompileManager.cpp:138–145两个线程同时 compile()池里仅 1 个遍历,后者 100ms 粒度忙等,编译串行化打开 #if 0 并验证 Context 拷贝对共享池安全
5CompileResult::add / src/vsg/app/CompileManager.cpp:48–55多个 view 合并且首个 view 的 indices/bins 皆空break 截断整轮合并,lights 也未合并,bin 明细静默丢失改 break 为 continue,补 lights 的 insert
6Context::reset / src/vsg/vk/Context.cpp:170–183上一轮 record() 返回 false 或 transferTask 为空imageInfosToCopy 等四字段跨轮累积,过期数据被重复上传补齐四个字段的清理并修正 :174 日志变量
7Context::record / src/vsg/vk/Context.cpp:319dataTransferHint = COMPILE_TRAVERSAL_TRANSFER_DATA_AND_WAIT 或 transferTask 为空只 warn 不上传,GPU 读未初始化数据始终保证 transferTask 非空并使用 TRANSFER_TASK hint
8Context::createBufferAndTransferData / src/vsg/vk/Context.cpp:416/428–588期待编译后修改数据能被脏标记检测160 余行脏标记/staging 实现是 #if 1 下的死代码启用 #else 分支或删除死代码,明确一次性写入语义
9CollectResourceRequirements::registerDescriptor / src/vsg/vk/ResourceRequirements.cpp:175–188同一 Descriptor 被多条路径共享去重前累加 descriptorTypeMap,池容量虚高把累加移入 count == 0 分支
10CollectResourceRequirements::createResourceHints / src/vsg/vk/ResourceRequirements.cpp:100–117收集结果生成 hints 后再喂给 Viewer::compile10 组字段丢失;uint32_t 乘法可回绕逐项回填并加溢出检查
11CompileManager::compile / src/vsg/app/CompileManager.cpp:276–280take_when_available() 拿不到遍历(status 关闭或池被借走)返回 VK_INCOMPLETE 且 message 仍是初始文本,静默降级区分"池关闭"与"暂空",写明确 message
12CompileManager::compileTask / src/vsg/app/CompileManager.cpp:419–423(compileTraversalUseReserve 守卫)守卫内 context->reserve 返回失败但不抛异常不检查返回值,继续遍历并最终报 VK_SUCCESS与 compile() 一样检查 reserve_result
13DatabasePager 编译循环 / src/vsg/io/DatabasePager.cpp:575–593编译返回非成功或抛异常整棵 PagedLOD 子图被 requestDiscarded 静默丢弃把 CompileResult.message 上抛到日志/重试预算
14SharedObjects::share(ref_ptr<T>&, Func) / include/vsg/utils/SharedObjects.h:176–201多线程读同一路径且共享 SharedObjects查重与 init 分离,两个线程都执行 init,重复 IO把 init 移入临界区或用双检锁
15View::share / releaseViewID / src/vsg/app/View.cpp:60–64/113–119const_cast 改写 viewID 或传入越界 ID修改 const 成员、--s_ActiveViews[viewID] 无边界检查去掉 const 或加边界断言
16CompileTraversal::apply(Commands&) / src/vsg/app/CompileTraversal.cpp:310–318Commands 内部含需上下文注入的子节点不 traverse,内部对象不经过 apply 特化明确 Commands::compile 自行递归的契约
17CompileResult::requiresViewerUpdate / src/vsg/app/CompileManager.cpp:62编译返回 VK_INCOMPLETE 但 views 已有编译好的 bin:62 直接 return false,Viewer::update 不调用,已编译子集静默丢弃区分完全失败与部分完成,按 views 决定是否更新
18CompileTraversal 基类 / include/vsg/app/CompileTraversal.h:33想把 RecordTraversal 的 culling 复用到编译期两者基类不同(Visitor vs Object),apply 分派表不通用不混用两遍历的多态,各自扩展
19Context 拷贝构造 / src/vsg/vk/Context.cpp:142打开 #if 0 复制含 defaultPipelineStates 的 ContextdeviceID 拷贝值、三个池经 ref_ptr 共享,改一个影响全部确认池共享语义后再启用
20SharedObjects::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 不走 StateGroup push(第八章 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 对象建出来之后,视图与相机才决定这些对象每一帧被怎样看见,这是第十三章的主线。