《VulkanSceneGraph 1.1.16 源码深度解析》第十一章 描述符体系:Layout / Pool / Descriptor

0 阅读1小时+

《VulkanSceneGraph 1.1.16 源码深度解析》第十一章 描述符体系:Layout / Pool / Descriptor / BindDescriptorSet

11.0 先把规模和答案摆出来

第十章留下六个问题:ShaderSet::createDescriptorSetLayout(ShaderSet.cpp:536–556)产出的 VkDescriptorSetLayoutBinding 如何变成 vkCreateDescriptorSetLayout;DescriptorConfigurator::assignDefaults(GraphicsPipelineConfigurator.cpp:293–350)生成的 DescriptorImage/DescriptorBuffer 如何落到 GPU;BindDescriptorSet(s) 如何在 slot 1 + firstSet 上与 push/pop 配对;pDynamicOffsets 由谁收集、谁传给 vkCmdBindDescriptorSets;ViewDependentStateBinding::compatibleDescriptorSetLayout(ShaderSet.cpp:140–143)的深比较在字段增删后是否成立;Descriptor::compile 后改 Data 内容能否被 GPU 看到。六条线收束到:DescriptorBinding → DescriptorSetLayout → DescriptorSet → DescriptorPool → BindDescriptorSet → vkCmdBindDescriptorSets。

先给可复核的规模。include/vsg/state/ 有 36 个头文件、3,002 行,src/vsg/state/ 有 35 个实现文件、7,076 行,合计 10,078 行;这两个数字与第九章 9.0 完全一致,因为本章与第九章共享同一个目录,只是取的是其中描述符这一支。

11.0.0 实测规模表

下表逐个列出本章正面处理的文件。wc -l 在本仓库根目录执行,行数以 wc -l 输出为准;"本章角色"一列写明该文件被本章哪一节使用。include/vsg/state/ 与 src/vsg/state/ 下全部描述符相关文件单列在前两组,不掺入管线状态类(ColorBlendState.h 等九个 GraphicsPipelineState 子类已在第九章处理)。

文件(include/vsg/state/)行数本章角色
include/vsg/state/Descriptor.h51基类三字段、assignTo、getNumDescriptors,11.1
include/vsg/state/DescriptorSetLayout.h85四个类型别名、bindings/bindingFlags,11.2
include/vsg/state/DescriptorSet.h97setLayout/descriptors 与 Implementation,11.3
include/vsg/state/BindDescriptorSet.h166两个绑定命令、五个构造、VulkanData,11.10
include/vsg/state/DescriptorBuffer.h53BufferInfoList、四个构造,11.4
include/vsg/state/DescriptorImage.h59ImageInfoList、三个工厂函数,11.5
include/vsg/state/DescriptorTexelBufferView.h47texelBufferViews 与内联 getNumDescriptors,11.6
include/vsg/state/BufferInfo.h106VkDescriptorBufferInfo 的四个字段与脏标记,11.4、11.16
include/vsg/state/ImageInfo.h107VkDescriptorImageInfo 的三字段、FormatTraits,11.5
include/vsg/state/Sampler.h78VkSamplerCreateInfo 的 15 个字段,11.5
include/vsg/state/ViewDependentState.h182BindViewDescriptorSets、ViewDescriptorSetLayout,11.15
include/vsg/state/ResourceHints.h99descriptorPoolSizes/numDescriptorSets,11.9
include/vsg/state/StateCommand.h45slot 字段与默认 Inherit(0),11.10
include/vsg/state/Buffer.h85底层 VkBuffer 封装,11.4 上传路径
include/vsg/state/BufferView.h62纹素缓冲视图,11.6
include/vsg/state/Image.h94底层 VkImage,11.5 上传路径
include/vsg/state/ImageView.h70VkImageView,11.5
include/vsg/state/PipelineLayout.h74setLayouts[] 与 vk(deviceID),11.10、11.12

以上 18 个头文件合计 1,560 行。

文件(src/vsg/state/)行数本章角色
src/vsg/state/Descriptor.cpp71compare/read/write/assignTo,11.1
src/vsg/state/DescriptorSetLayout.cpp187addBinding、池大小累加、Implementation,11.2
src/vsg/state/DescriptorSet.cpp167vkAllocateDescriptorSets、vkUpdateDescriptorSets,11.3
src/vsg/state/BindDescriptorSet.cpp216两个类的 compile/record,11.10
src/vsg/state/DescriptorBuffer.cpp245缓冲上传与 pBufferInfo 填充,11.4
src/vsg/state/DescriptorImage.cpp184图像上传与 pImageInfo 填充,11.5
src/vsg/state/DescriptorTexelBufferView.cpp81pTexelBufferView 填充,11.6
src/vsg/state/BufferInfo.cpp293copyDataToBuffer、computeDataSize,11.4、11.16
src/vsg/state/ImageInfo.cpp426computeNumMipMapLevels、getFormatTraits,11.5
src/vsg/state/Sampler.cpp120vkCreateSampler 与序列化,11.5
src/vsg/state/ViewDependentState.cpp1060view 槽装配与 bindDescriptorSets,11.15
src/vsg/state/ResourceHints.cpp148hints 的 read/write,11.9
src/vsg/state/StateCommand.cpp45slot 的序列化,11.10
src/vsg/state/Buffer.cpp184reserve/compile/bind,11.4
src/vsg/state/BufferView.cpp85vkCreateBufferView,11.6
src/vsg/state/Image.cpp242VkImage 创建与 mipmap,11.5
src/vsg/state/ImageView.cpp205VkImageView 创建,11.5
src/vsg/state/PipelineLayout.cpp171vkCreatePipelineLayout、空布局写 0,11.12

以上 18 个实现文件合计 4,130 行。state 目录描述符相关合计 36 个文件、5,690 行。

文件(state 之外)行数本章角色
include/vsg/vk/DescriptorPool.h74单池四本账与 recyclingList,11.7
include/vsg/vk/DescriptorPools.h66扩容三参数与 reserve 累计量,11.8
include/vsg/vk/Context.h160reserve/allocateDescriptorSet 声明,11.9
include/vsg/vk/ResourceRequirements.h149计数容器与访问者声明,11.9
src/vsg/vk/DescriptorPool.cpp254vkCreateDescriptorPool、分配/回收/统计,11.7
src/vsg/vk/DescriptorPools.cpp251reserve、getDescriptorPoolSizesToUse,11.8
src/vsg/vk/Context.cpp599Context::reserve/allocateDescriptorSet 接线,11.9
src/vsg/vk/ResourceRequirements.cpp418registerDescriptor 与两个 compute,11.9
include/vsg/utils/ShaderSet.h228DescriptorBinding 九字段,11.12
include/vsg/utils/GraphicsPipelineConfigurator.h173DescriptorConfigurator 接口,11.13
include/vsg/utils/Builder.h165上层装配入口声明,11.14
src/vsg/utils/ShaderSet.cpp609createDescriptorSetLayout/createPipelineLayout,11.12
src/vsg/utils/GraphicsPipelineConfigurator.cpp1013装配、继承集判定、copyTo,11.13、11.14
src/vsg/utils/Builder.cpp1466面向用户的描述符创建入口,11.14
include/vsg/raytracing/DescriptorAccelerationStructure.h49第五个 Descriptor 子类,11.6
src/vsg/raytracing/DescriptorAccelerationStructure.cpp70pNext 链与 descriptorCount,11.6

以上 16 个文件合计 5,744 行。全章 52 个文件合计 11,434 行。

关于"以本机 SDK 为准"的部分:include/vsg/vk/vulkan.h:15 只是 #include <vulkan/vulkan.h> 的透传,紧随其后的 VK_DEFINE_NON_DISPATCHABLE_HANDLE 兼容宏才是仓库自己的补丁;VkDescriptorType 枚举个数、sizeof(VkDescriptorSetLayoutBinding)、sizeof(VkWriteDescriptorSet)、sizeof(VkDescriptorPoolSize)、VkDescriptorPoolCreateFlagBits 全部由本机 Vulkan SDK 头文件决定,仓库内没有这些定义,本章不编造字节数,11.11.3 给出测量程序。

仓库内自带的是 VkDescriptorBindingFlagBits 回退定义,摘录如下:

// include/vsg/vk/vulkan.h:420-426
    VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT = 0x00000001,
    VK_DESCRIPTOR_BINDING_UPDATE_UNUSED_WHILE_PENDING_BIT = 0x00000002,
    VK_DESCRIPTOR_BINDING_PARTIALLY_BOUND_BIT = 0x00000004,
    VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT = 0x00000008,
    VK_DESCRIPTOR_BINDING_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} VkDescriptorBindingFlagBits;

四个有效位(0x1/0x2/0x4/0x8)加一个 MAX_ENUM = 0x7FFFFFFF,是给旧 SDK 补的回退,不是 SDK 原值;11.11.3 会指出库内零使用。

11.0.1 本章的问题清单

六条继承问题加本章新拆问题:assignTo 为何只填四字段(11.1.2);getNumDescriptors() 与 descriptorCount 是否两套口径(11.1.3);addBinding 稀疏下标与 pBindingFlags 的 bindingCount 能否配上(11.2.2);memcmp 是否比 pImmutableSamplers(11.2.6);改 Data 后 GPU 能否看到(11.3.2);scratchMemory->release() 为何安全(11.3.4);available()/used() 能否信(11.7.4);共享 descriptor 是否重复计数(11.9.2);dynamicOffsets 有无生产者(11.11.1);VK_DESCRIPTOR_BINDING_* 有无被设置(11.11.3);空布局是什么(11.2.5);assigned 是否提前标记(11.13.1);end_set 有无上界(11.14.2);默认 slot 与 firstSet 是否配平(11.15.1);compare/read/write 错开到什么程度(11.15.2)。

11.0.2 答案骨架

先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对。标注【硬缺陷】的是有明确触发条件与后果的实现问题,标注【设计取舍】的是代价可接受但边界要写清的选择,标注【接口边界】的是容易被误读的语义。

#结论主要证据性质
1slot = 1 + firstSet 由五个构造点写死,BindViewDescriptorSets 默认构造却另用 Inherit(2) 且 firstSet = 0,同一个 firstSet 对应两个 slot,双份真相BindDescriptorSet.h:31/98/107/117、ViewDependentState.cpp:106/108【硬缺陷】
2DescriptorSet::compile 以 _implementation[deviceID] 是否为空为唯一失效判据,编译后改 descriptors 或 Data 都不会重分配、不会重写入,vkUpdateDescriptorSets 是名副其实的一次性DescriptorSet.cpp:72/84/85/154【设计取舍】
3基类 Descriptor::assignTo 用 wds = {} 清零后只填 sType/dstBinding/dstArrayElement/descriptorType,descriptorCount 由四个子类各自填;getNumDescriptors() 只服务池容量统计,与写入口径无一致性校验Descriptor.cpp:64–71、Descriptor.h:39、DescriptorBuffer.cpp:220【设计取舍】
4DescriptorPool::used() 把迭代器当整数累加:used_itr += usedDescriptorCount,本应写 used_itr->descriptorCount += ...,已有同类型条目永远不更新DescriptorPool.cpp:200【硬缺陷】
5DescriptorPool::available() 把成员 descriptorPoolSizes(初始全量)而非 _availableDescriptorPoolSizes(剩余)并入"可用",DescriptorPools::reserve 据此判断富余,结论偏乐观DescriptorPool.cpp:175/181、DescriptorPools.cpp:95/113【硬缺陷】
6回收复用判据只比 bindings,漏掉 createFlags 与 bindingFlags;compare_value_container 又是 memcmp,pImmutableSamplers 与 padding 一起进比较DescriptorPool.cpp:92、compare.h:80–87【硬缺陷】
7BindDescriptorSet/BindDescriptorSets 的 compare 不比 dynamicOffsets,read/write 却序列化它;全库 dynamicOffsets 只有 12 处出现,零处 push_back/resizeBindDescriptorSet.cpp:52/72/91/152/172/191【硬缺陷】
8两个 compile 的复用判据只判"句柄非零 + 容器 size",不比内容;替换 descriptorSet 或 descriptorSets[i] 后不重编译,帧期仍绑旧句柄BindDescriptorSet.cpp:100/200【硬缺陷】
9registerDescriptor 无条件先累加 descriptorTypeMap 再做 descriptors 去重;池容量按 descriptor 侧统计,分配扣减按 layout 侧 getDescriptorPoolSizes,两套口径不校验一致性ResourceRequirements.cpp:177/179、DescriptorPool.cpp:110、DescriptorSetLayout.cpp:63–81【硬缺陷】
10DescriptorSetLayout 的 compare 用 memcmp 横跨 VkDescriptorSetLayoutBinding,read/write 却只读写 4 字段不碰 pImmutableSamplers;addBinding 用 binding 编号当 bindingFlags 下标,稀疏编号会让 bindingFlagsCreateInfo.bindingCount 与 pBindings 的 bindingCount 不相等DescriptorSetLayout.cpp:58/91/105–112/158/170【硬缺陷】

十条里第 1、4、5、6、7、8、9、10 条是硬缺陷,第 2、3 条是设计取舍。createSampedImageDescriptor(DescriptorImage.cpp:180、DescriptorImage.h:58)、DescriptorPool::report(DescriptorPool.cpp:208)、DescriptorPools::report(DescriptorPools.cpp:159)与 VK_DESCRIPTOR_BINDING_*(仅 vulkan.h:419–426 有定义)都属"写好没接上",批判结论第四节展开。

11.0.3 阅读路线

阅读顺序按 compile 依赖排:DescriptorSetLayout → DescriptorSet → 五个 Descriptor 子类 → DescriptorPool/DescriptorPools → ResourceRequirements/Context → BindDescriptorSet(s) → ShaderSet/DescriptorConfigurator → BindViewDescriptorSets → copy/compare/read/write 总账与陷阱。

顺序按 compile 的依赖排:DescriptorSet.cpp:80–85 先 setLayout->compile,再逐个 descriptor->compile,最后 context.allocateDescriptorSet;而 DescriptorPool::allocateDescriptorSet(DescriptorPool.cpp:110)又调 getDescriptorPoolSizes 决定能否分。帧期只有一条直线:BindDescriptorSet::record(BindDescriptorSet.cpp:209–216)把编译期存好的 VulkanData 交给 vkCmdBindDescriptorSets。

// src/vsg/state/DescriptorSet.cpp:80-85
        setLayout->compile(context);
        for (auto& descriptor : descriptors) descriptor->compile(context);
        _implementation[context.deviceID] = context.allocateDescriptorSet(setLayout);
        _implementation[context.deviceID]->assign(context, descriptors);

11.1 对象链与 Descriptor 基类:四个字段撑起整个写入体系

把第九章 9.1 的对象链往描述符这一支展开,编译期的依赖是:

BindDescriptorSet / BindDescriptorSets        (StateCommand, slot = 1 + firstSet)
  └─ DescriptorSet                            (Object)
       ├─ DescriptorSetLayout                 (Object) → VkDescriptorSetLayout
       │    └─ DescriptorSetLayoutBindings   (vector<VkDescriptorSetLayoutBinding>)
       └─ Descriptors                        (vector<ref_ptr<Descriptor>>)
            ├─ DescriptorBuffer               → VkDescriptorBufferInfo[]
            ├─ DescriptorImage                → VkDescriptorImageInfo[]
            ├─ DescriptorTexelBufferView      → VkBufferView[]
            └─ DescriptorAccelerationStructure → VkWriteDescriptorSetAccelerationStructureKHR (pNext)

  编译产物(按 deviceID 索引,不在场景图里):
       VkDescriptorSetLayout   ← DescriptorSetLayout::Implementation
       VkDescriptorSet         ← DescriptorSet::Implementation(从 DescriptorPool 分配)
       VkBuffer/VkImage        ← 第五章上传路径
       VkSampler               ← Sampler::Implementation

与第九章那张图对照,差别在两处:管线的编译产物按 viewID 索引,描述符的编译产物按 deviceID 索引;VkPipeline 是若干 Vk*StateCreateInfo 的快照,VkDescriptorSet 是若干 VkWriteDescriptorSet 的快照,且后者写一次就不再改。这两点决定了本章后面所有的边界。

11.1.1 基类声明与三个字段

基类先把所有类型共享的 VkWriteDescriptorSet 定位信息收在一处,声明与三个公共字段摘录如下:

// include/vsg/state/Descriptor.h:25-34 / 47-49
    class VSG_DECLSPEC Descriptor : public Inherit<Object, Descriptor>
    {
    public:
        Descriptor(uint32_t in_dstBinding, uint32_t in_dstArrayElement, VkDescriptorType in_descriptorType);
        Descriptor(const Descriptor& rhs, const CopyOp& copyop = {});

        /// Common VkWriteDescriptorSet settings
        uint32_t dstBinding;
        uint32_t dstArrayElement;
        VkDescriptorType descriptorType;
    VSG_type_name(vsg::Descriptor);

    using Descriptors = std::vector<vsg::ref_ptr<vsg::Descriptor>>;

三个字段对应 Vulkan 同名字段;基类没有 descriptorCount 和 dstSet,compile 空实现、getNumDescriptors() 默认 1。第 150 行统一回填 dstSet:

// src/vsg/state/DescriptorSet.cpp:149-151
        in_descriptors[i]->assignTo(context, descriptorWrites[i]);
        descriptorWrites[i].dstSet = _descriptorSet;
    }

公共定位信息在基类,数据指针在子类。

Descriptors 是 std::vector<ref_ptr<Descriptor>>,不是 set,也不是按 binding 排序的 map。因此 DescriptorSet::Implementation::assign(DescriptorSet.cpp:147–151)里的 descriptorWrites[i] 下标就是 descriptors 的下标,写入顺序完全由用户 push_back 的顺序决定。Vulkan 允许同一次 vkUpdateDescriptorSets 里对同一个 binding 写多条,也允许乱序,所以这里没有排序是合法的;但一旦两个 Descriptor 写同一个 dstBinding 且 dstArrayElement 重叠,后写覆盖先写,库不做检测。

11.1.2 assignTo 的四个字段与 wds = {}

// src/vsg/state/Descriptor.cpp:64-71
void Descriptor::assignTo(Context& /*context*/, VkWriteDescriptorSet& wds) const
{
    wds = {};
    wds.sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
    wds.dstBinding = dstBinding;
    wds.dstArrayElement = dstArrayElement;
    wds.descriptorType = descriptorType;
}

逐分支推导:第一行 wds = {} 对整个结构体做零初始化,这一步同时把 pNext、descriptorCount、pImageInfo、pBufferInfo、pTexelBufferView、dstSet 全部置 0。后四行只覆盖 sType 与基类三字段。

代价与边界:如果某个自定义 Descriptor 子类覆写 assignTo 却忘了调用基类实现,wds 是 DescriptorSet.cpp:145 从 scratchMemory 分配出来的未初始化内存,sType 与 descriptorType 会是脏值。反过来,如果子类调用基类实现却忘了补 descriptorCount,wds = {} 已经把它置 0,vkUpdateDescriptorSets 会静默地写入 0 个描述符——不报错、不校验、不写数据。

11.1.3 getNumDescriptors() 的第二套口径

grep -rn "getNumDescriptors" 在本仓库 include/vsg 与 src/vsg 下命中 10 行:声明 5 处、定义 4 处、调用 1 处。

位置返回值用途
Descriptor.h:39常量 1基类默认
DescriptorBuffer.cpp:234–237bufferInfoList.size()池容量统计
DescriptorImage.cpp:163–166imageInfoList.size()池容量统计
DescriptorTexelBufferView.h:34texelBufferViews.size()池容量统计
DescriptorAccelerationStructure.cpp:67–70_accelerationStructures.size()池容量统计
ResourceRequirements.cpp:177唯一调用点累加 descriptorTypeMap

唯一调用点在 ResourceRequirements 的访问者里,编译与写入路径一次都不调用它。子类的返回值就是容器长度:

// src/vsg/state/DescriptorBuffer.cpp:234-237
uint32_t DescriptorBuffer::getNumDescriptors() const
{
    return static_cast<uint32_t>(bufferInfoList.size());
}

assign 却用 in_descriptors.size() 作 wds 长度、各 assignTo 用容器 size() 作 descriptorCount——两套并行实现恰好取同一个数,没有一致性校验。

DescriptorAccelerationStructure 把这种分离暴露得最清楚:

// src/vsg/raytracing/DescriptorAccelerationStructure.cpp:53-62 / 68-70
void DescriptorAccelerationStructure::assignTo(Context& context, VkWriteDescriptorSet& wds) const
{
    Descriptor::assignTo(context, wds);

    auto descriptorAccelerationStructureInfo = context.scratchMemory->allocate<VkWriteDescriptorSetAccelerationStructureKHR>(1);
    descriptorAccelerationStructureInfo->sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR;
    descriptorAccelerationStructureInfo->accelerationStructureCount = static_cast<uint32_t>(_vkAccelerationStructures.size());
    descriptorAccelerationStructureInfo->pAccelerationStructures = _vkAccelerationStructures.data();
    descriptorAccelerationStructureInfo->pNext = nullptr;

{
    return static_cast<uint32_t>(_accelerationStructures.size());
}

descriptorCount 取 _vkAccelerationStructures.size()(编译后由 compile 逐个 *accelstruct 填充,见 DescriptorAccelerationStructure.cpp:46–50),getNumDescriptors() 取 _accelerationStructures.size()(原始对象数组)。两个容器在 compile 全成功时长度相等;一旦某个 AccelerationStructure 的 compile 抛异常或返回空,两个数字就分叉,而池容量按后者算、写入按前者算。

11.1.4 compare / read / write 的版本门控

三个字段都进 compare,其中 descriptorType 的序列化被 version_greater_equal(1, 1, 11) 门控,源码如下:

// src/vsg/state/Descriptor.cpp:34-43 / 60-62
int Descriptor::compare(const Object& rhs_object) const
{
    int result = Object::compare(rhs_object);
    if (result != 0) return result;

    const auto& rhs = static_cast<decltype(*this)>(rhs_object);

    if ((result = compare_value(dstBinding, rhs.dstBinding))) return result;
    if ((result = compare_value(dstArrayElement, rhs.dstArrayElement))) return result;
    return compare_value(descriptorType, rhs.descriptorType);
    output.write("dstArrayElement", dstArrayElement);
    if (output.version_greater_equal(1, 1, 11)) output.write("descriptorType", descriptorType);
}

版本门控只包住 descriptorType,write 的三行里它是唯一条件项:

// src/vsg/state/Descriptor.cpp:59-61
    output.write("dstBinding", dstBinding);
    output.write("dstArrayElement", dstArrayElement);
    if (output.version_greater_equal(1, 1, 11)) output.write("descriptorType", descriptorType);

1.1.11 之前的文件没有 descriptorType,读回时它保留构造时的值;Descriptor 只有带参构造(Descriptor.cpp:19–24),旧文件读回的栈上对象因此拿到未初始化的 descriptorType,除非子类默认构造显式传了类型。

代价与边界:compare 是 SharedObjects 去重的序关系基础(第十章 10.x 讲过 SharedObjects 用 compare 判等),三个字段都进比较,没有漏项;但 getNumDescriptors() 不进比较、也不进序列化,它是纯派生的容器长度。Descriptor 这一层本身没有硬缺陷,问题全在子类的字段清单上。

11.1.5 与前面章节的交叉引用

DescriptorSet 封装 VkDescriptorSet 与 VkDescriptorSetAllocateInfo,是 Inherit<Object, DescriptorSet>,不进状态栈;BindDescriptorSet 进 stateCommands(BindDescriptorSet.h:91)。同一个 Bind 在本章多一层 Descriptors 容器,因此多出 descriptors 数组顺序问题。


11.2 DescriptorSetLayout:bindings 与 bindingFlags 的两条索引轴

11.2.1 四个类型别名与五个字段

// include/vsg/state/DescriptorSetLayout.h:23-32 / 33-33 / 47-50
    using DescriptorSetLayoutBindings = std::vector<VkDescriptorSetLayoutBinding>;
    using DescriptorSetLayoutBindingFlags = std::vector<VkDescriptorBindingFlags>;
    using DescriptorPoolSizes = std::vector<VkDescriptorPoolSize>;

    /// DescriptorSetLayout encapsulates VkDescriptorSetLayout and VkDescriptorSetLayoutCreateInfo settings used to set it up.
    class VSG_DECLSPEC DescriptorSetLayout : public Inherit<Object, DescriptorSetLayout>
    {
    public:
        DescriptorSetLayout();
        DescriptorSetLayout(const DescriptorSetLayout& rhs, const CopyOp& copyop = {});
        explicit DescriptorSetLayout(const DescriptorSetLayoutBindings& descriptorSetLayoutBindings);
        void addBinding(uint32_t binding, VkDescriptorType descriptorType, uint32_t descriptorCount, VkShaderStageFlags stageFlags, VkDescriptorBindingFlags flags = 0);

        /// map the descriptor bindings to the descriptor pool sizes that will be required to represent them.
        void getDescriptorPoolSizes(DescriptorPoolSizes& descriptorPoolSizes);

三个别名全是 std::vector,没有 set、没有 map,顺序即 binding 声明顺序。vk(deviceID)(DescriptorSetLayout.h:36)直接返回 _implementation[deviceID]->_descriptorSetLayout,不判空。createFlags 默认 0,对应 VkDescriptorSetLayoutCreateInfo::flags;bindings 对应 pBindings/bindingCount;bindingFlags 对应 VkDescriptorSetLayoutBindingFlagsCreateInfo::pBindingFlags/bindingCount,是 pNext 链上的扩展结构。

11.2.2 addBinding:flags 稀疏索引

// src/vsg/state/DescriptorSetLayout.cpp:46-55 / 59-61
void DescriptorSetLayout::addBinding(uint32_t binding, VkDescriptorType descriptorType, uint32_t descriptorCount, VkShaderStageFlags stageFlags, VkDescriptorBindingFlags flags)
{
    VkDescriptorSetLayoutBinding layoutBinding = {};
    layoutBinding.binding = binding;
    layoutBinding.descriptorType = descriptorType;
    layoutBinding.descriptorCount = descriptorCount;
    layoutBinding.stageFlags = stageFlags;
    layoutBinding.pImmutableSamplers = nullptr;
    bindings.push_back(layoutBinding);

        bindingFlags[binding] = flags;
    }
}

bindings 用 push_back,下标是"第几个 binding";bindingFlags 用 bindingFlags[binding],下标是 binding 编号,稀疏编号时 resize 补 0:

// src/vsg/state/DescriptorSetLayout.cpp:56-60
    if (flags != 0)
    {
        if (binding >= bindingFlags.size()) bindingFlags.resize(binding + 1, 0);
        bindingFlags[binding] = flags;
    }

flags 全为 0 时 bindingFlags 保持空,Implementation 不挂 pNext(:163–166)。

代价与边界:Vulkan 规范要求 VkDescriptorSetLayoutBindingFlagsCreateInfo::bindingCount 等于 VkDescriptorSetLayoutCreateInfo::bindingCount,且 pBindingFlags[i] 对应 pBindings[i]。Implementation 里这两个 count 是分别取的:

// src/vsg/state/DescriptorSetLayout.cpp:153-162 / 163-163 / 175-178
DescriptorSetLayout::Implementation::Implementation(Device* device, VkDescriptorSetLayoutCreateFlags createFlags, const DescriptorSetLayoutBindings& descriptorSetLayoutBindings, const DescriptorSetLayoutBindingFlags& descriptorSetLayoutBindingFlags) :
    _device(device)
{
    VkDescriptorSetLayoutCreateInfo layoutInfo = {};
    layoutInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO;
    layoutInfo.bindingCount = static_cast<uint32_t>(descriptorSetLayoutBindings.size());
    layoutInfo.pBindings = descriptorSetLayoutBindings.data();
    layoutInfo.flags = createFlags;

    VkDescriptorSetLayoutBindingFlagsCreateInfo bindingFlagsCreateInfo = {};
    if (descriptorSetLayoutBindingFlags.empty())
    if (VkResult result = vkCreateDescriptorSetLayout(*device, &layoutInfo, _device->getAllocationCallbacks(), &_descriptorSetLayout); result != VK_SUCCESS)
    {
        throw Exception{"Error: Failed to create DescriptorSetLayout.", result};
    }

第 158 行取 bindings.size(),第 170 行取 bindingFlags.size()。在 addBinding 的稀疏写法下两者可以不等:bindings 长度是声明个数,bindingFlags 长度是"最大 binding 编号 + 1"。

11.2.3 getDescriptorPoolSizes:按类型累加,不看 set 个数

// src/vsg/state/DescriptorSetLayout.cpp:63-81
void DescriptorSetLayout::getDescriptorPoolSizes(DescriptorPoolSizes& descriptorPoolSizes)
{
    for (auto& binding : bindings)
    {
        auto itr = descriptorPoolSizes.begin();
        for (; itr != descriptorPoolSizes.end(); ++itr)
        {
            if (itr->type == binding.descriptorType)
            {
                itr->descriptorCount += binding.descriptorCount;
                break;
            }
        }
        if (itr == descriptorPoolSizes.end())
        {
            descriptorPoolSizes.emplace_back(VkDescriptorPoolSize{binding.descriptorType, binding.descriptorCount});
        }
    }
}

逐字段推导:入参是输出兼累加器,函数不清空它,同类型的 descriptorCount 会叠加在已有条目上;不同类型追加新条目。注意它累加的是 binding.descriptorCount 而不是 1——数组描述符(descriptorCount > 1)会被完整计入。它不乘 DescriptorSet 的个数:一个 layout 被多少个 set 引用,是 ResourceRequirements::computeNumDescriptorSets() 与 DescriptorPools::reserve 负责放大(11.8.2、11.9.1)。

代价与边界:这个函数被调用两处,语义不同。DescriptorPool::allocateDescriptorSet(DescriptorPool.cpp:109–110)用它算"这一个 set 要从剩余池里扣多少",入参是局部空 vector,结果准确。ResourceRequirements::computeDescriptorPoolSizes()(ResourceRequirements.cpp:57–64)不调用它,而是直接把 descriptorTypeMap 倒出来,后者按 Descriptor 对象统计(11.9.3)。于是"池要建多大"与"分配时扣多少"用了两套不同的算法,前者不知道 layout 的 descriptorCount,后者不知道场景里有多少个 Descriptor。11.9.3 会把这条缝展开成一条硬结论。

11.2.4 compile / release 与按 deviceID 的缓存

// src/vsg/state/DescriptorSetLayout.cpp:144-147
void DescriptorSetLayout::compile(Context& context)
{
    if (!_implementation[context.deviceID]) _implementation[context.deviceID] = DescriptorSetLayout::Implementation::create(context.device, createFlags, bindings, bindingFlags);
}

判据只有"该 deviceID 槽位是否为空"。一旦编译过,改 createFlags、增删 bindings、改 bindingFlags 都不会重建 VkDescriptorSetLayout。

11.2.5 空布局:bindingCount = 0 的 VkDescriptorSetLayout

DescriptorSetLayout 的默认构造(DescriptorSetLayout.cpp:25–27)不填任何 binding,copy 构造复制的 createFlags、bindings、bindingFlags 三个字段此时全取空值。到了 Implementation(DescriptorSetLayout.cpp:153)里,layoutInfo.bindingCount = 0、pBindings 是空 vector 的 data()、pNext = nullptr,vkCreateDescriptorSetLayout 允许创建这样的空布局,它在 Vulkan 侧是合法句柄。ShaderSet::createPipelineLayout(ShaderSet.cpp:592–595)正是利用这一点给 firstSet > 0 的空洞补位:

// src/vsg/utils/ShaderSet.cpp:587-600
ref_ptr<PipelineLayout> ShaderSet::createPipelineLayout(const std::set<std::string>& defines, std::pair<uint32_t, uint32_t> range) const
{
    DescriptorSetLayouts descriptorSetLayouts;

    uint32_t set = 0;
    for (; set < range.first; ++set)
    {
        descriptorSetLayouts.push_back(DescriptorSetLayout::create());
    }

    for (; set < range.second; ++set)
    {
        descriptorSetLayouts.push_back(createDescriptorSetLayout(defines, set));
    }

range 来自 descriptorSetRange()(ShaderSet.cpp:498–512),末行决定返回值:

// src/vsg/utils/ShaderSet.cpp:511-512
    return {minimum, maximum + 1};
}

全在 set = 1 时 range = {1, 2},补一个空布局后 pSetLayouts[1] 才是实布局,firstSet = 1 才落对编号。

空布局对 Vulkan 规范有条件:pSetLayouts 前导空布局需启用 VK_PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT 才安全,否则部分驱动上 vkCmdBindDescriptorSets(firstSet=1) 走不通。PipelineLayout.cpp:147 把空布局写成句柄(第九章 9.15.2 的"写 0"是另一分支)。依赖链是:descriptorSetRange()(ShaderSet.cpp:498)决定补几个空布局,ShaderSet.cpp:594 往 descriptorSetLayouts push 空布局,是唯一补位生产点,firstSet 对应关系由 11.10.2 承接。

11.2.6 compare / read / write 三份字段清单不同步

compare 先比 createFlags,再用 compare_value_container 比 bindings 与 bindingFlags,源码摘录如下:

// src/vsg/state/DescriptorSetLayout.cpp:83-93 / 139-142
int DescriptorSetLayout::compare(const Object& rhs_object) const
{
    int result = Object::compare(rhs_object);
    if (result != 0) return result;

    const auto& rhs = static_cast<decltype(*this)>(rhs_object);

    if ((result = compare_value(createFlags, rhs.createFlags))) return result;
    if ((result = compare_value_container(bindings, rhs.bindings))) return result;

    return compare_value_container(bindingFlags, rhs.bindingFlags);
    {
        output.writeValues("bindingFlags", bindingFlags);
    }
}

三份清单的差别列成表:

字段comparereadwrite说明
createFlags比1.1.12+ 读1.1.12+ 写门控一致
bindings[i].binding比(memcmp 内)读写一致
bindings[i].descriptorType比(memcmp 内)读写一致
bindings[i].descriptorCount比(memcmp 内)读写一致
bindings[i].stageFlags比(memcmp 内)读写一致
bindings[i].pImmutableSamplers比(memcmp 内)不读不写分叉
bindings[i] 结构体 padding比(memcmp 内)不读不写分叉
bindingFlags比1.1.12+ 读1.1.12+ 写门控一致

compare_value_container(compare.h:80–87)最终落到 compare_region 的字节比较,末项多算一个 sizeof(E):

// include/vsg/core/compare.h:57-61
        size_t size = size_t(reinterpret_cast<const char*>(&end) - lhs_ptr) + sizeof(E);
        // use memcpy to compare the contents of the data
        return std::memcmp(lhs_ptr, rhs_ptr, size);
        }

于是 pImmutableSamplers 指针值与 padding 全进序关系。库内该字段恒为 nullptr(DescriptorSetLayout.cpp:53、GraphicsPipelineConfigurator.cpp:288 的聚合初始化末项),memcmp 恰好成立;反序列化或手工填结构体则分叉。

代价与边界:这就是第九章 9.11 与第十章对 memcmp 的同一处警告在描述符层的复现。任何来自反序列化(read 不写 pImmutableSamplers,bindings.resize() 对 POD 不做值初始化,字段是未初始化的)、来自用户手工填 VkDescriptorSetLayoutBinding、或者 SDK 版本改变 VkDescriptorSetLayoutBinding 布局导致 padding 变化的情况,compare 都会把两个语义相等的布局判成不等,或把两个语义不等的布局判成相等。

11.2.7 与前面章节的交叉引用

描述符布局没有第九章 9.10 那层缓存键比较,是同一设计哲学更彻底的版本;11.2.6 的三份清单表是第十章"字段清单写三遍"在描述符层的实例,多了一个 memcmp 变量。

11.3 DescriptorSet:一次性写入的边界

11.3.1 字段、遍历与判等

DescriptorSet 封装 VkDescriptorSet 与 VkDescriptorSetAllocateInfo 的设置,其声明摘录如下:

// include/vsg/state/DescriptorSet.h:25-35 / 55-58
    class VSG_DECLSPEC DescriptorSet : public Inherit<Object, DescriptorSet>
    {
    public:
        DescriptorSet();
        DescriptorSet(const DescriptorSet& rhs, const CopyOp& copyop = {});
        DescriptorSet(ref_ptr<DescriptorSetLayout> in_descriptorSetLayout, const Descriptors& in_descriptors);

        /// VkDescriptorSetAllocateInfo settings
        ref_ptr<DescriptorSetLayout> setLayout;
        Descriptors descriptors;

        }

        void traverse(Visitor& visitor) override { t_traverse(*this, visitor); }
        void traverse(ConstVisitor& visitor) const override { t_traverse(*this, visitor); }

逐字段看:setLayout 判空后遍历,descriptors 不判空直接 descriptor->accept(visitor)(第 54 行)。若 descriptors 里混入空 ref_ptr,遍历即崩;DescriptorSet::compile(DescriptorSet.cpp:82)同样不判空就 descriptor->compile(context)。

11.3.2 compile:短路即"一次性"

// src/vsg/state/DescriptorSet.cpp:70-79 / 100-102
void DescriptorSet::compile(Context& context)
{
    if (!_implementation[context.deviceID])
    {
        if (!setLayout)
        {
            throw Exception{"Error: invalid DescriptorSet as no setLayout assigned.", VK_INCOMPLETE};
        }

        // make sure all the contributing objects are compiled
{
    return _implementation[deviceID]->_descriptorSet;
}

逐分支推导:第 72 行是唯一的失效判据。已编译过就整个函数体跳过,包括 setLayout->compile、descriptor->compile、allocateDescriptorSet、assign。

脏标记比对写在 DescriptorBuffer::compile 里,但 DescriptorSet::compile 短路后连它都不会再被调用:

// src/vsg/state/DescriptorBuffer.cpp:205-208
            if (!transferTask && bufferInfo->data && bufferInfo->data->getModifiedCount(bufferInfo->copiedModifiedCounts[deviceID]))
            {
                bufferInfo->copyDataToBuffer(context.deviceID);
            }

"改 Data 后 GPU 能否看到"的答案是:没有第二次调用点。只有显式调 copyDataListToBuffers()(:239–245)或走 TransferTask 才刷新;descriptors 容器变化后 vk() 仍返回旧句柄,vk(deviceID)(第 99–102 行)也未判空。

11.3.3 vkAllocateDescriptorSets:一次只分一个

// src/vsg/state/DescriptorSet.cpp:108-117 / 118-118 / 136-139
DescriptorSet::Implementation::Implementation(DescriptorPool* descriptorPool, DescriptorSetLayout* descriptorSetLayout) :
    _descriptorPool(descriptorPool),
    _descriptorSetLayout(descriptorSetLayout)
{
    auto device = descriptorPool->getDevice();

    VkDescriptorSetLayout vkdescriptorSetLayout = descriptorSetLayout->vk(device->deviceID);

    VkDescriptorSetAllocateInfo descriptorSetAllocateInfo = {};
    descriptorSetAllocateInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO;
    descriptorSetAllocateInfo.descriptorPool = *descriptorPool;
        std::scoped_lock<std::mutex> lock(_descriptorPool->mutex);
        vkFreeDescriptorSets(*(_descriptorPool->getDevice()), *_descriptorPool, 1, &_descriptorSet);
    }
}

descriptorSetCount 硬编码为 1,pSetLayouts 指向栈上单个布局:

// src/vsg/state/DescriptorSet.cpp:119-120
    descriptorSetAllocateInfo.descriptorSetCount = 1;
    descriptorSetAllocateInfo.pSetLayouts = &vkdescriptorSetLayout;

全库 vkAllocateDescriptorSets 仅此一处;第 122–124 行注释说明构造不加锁,是因为调用方 allocateDescriptorSet 已持 mutex(DescriptorPool.cpp:82)——线程安全依赖调用约定。

析构(第 132–139 行)判了 _descriptorPool && _descriptorSet 才 vkFreeDescriptorSets,并加锁。这要求池带 VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT(DescriptorPool.cpp:56),否则单个 free 非法。recycle(DescriptorSet.cpp:160–167)是另一条路径:它不销毁 Implementation,而是把它放回池的 _recyclingList(DescriptorPool.cpp:145),_descriptorSet 句柄保持有效供复用。

11.3.4 assign:一次性 vkUpdateDescriptorSets 与 scratch memory

// src/vsg/state/DescriptorSet.cpp:141-150 / 165-167
void DescriptorSet::Implementation::assign(Context& context, const Descriptors& in_descriptors)
{
    if (in_descriptors.empty()) return;

    VkWriteDescriptorSet* descriptorWrites = context.scratchMemory->allocate<VkWriteDescriptorSet>(in_descriptors.size());

    for (size_t i = 0; i < in_descriptors.size(); ++i)
    {
        in_descriptors[i]->assignTo(context, descriptorWrites[i]);
        descriptorWrites[i].dstSet = _descriptorSet;
        dsi = {};
    }
}

逐字段推导:第 143 行空容器直接返回,VkDescriptorSet 分配出来但不写任何内容。第 145 行按 in_descriptors.size() 从 context.scratchMemory 分配 VkWriteDescriptorSet 数组;各子类 assignTo 又从同一块 scratch memory 分配 VkDescriptorBufferInfo[]/VkDescriptorImageInfo[](DescriptorBuffer.cpp:219、DescriptorImage.cpp:141),因此 wds 里的三个数据指针都指向 scratch。

代价与边界:vkUpdateDescriptorSets 是同步复制调用,返回时驱动已经读完 descriptorWrites 及其指向的 pImageInfo/pBufferInfo,所以第 157 行立即释放 scratch 是安全的——这与第九章 9.8.3 里 ScratchMemory 在 vkCreateGraphicsPipelines 后 release() 是同一个论证。边界是:整个 assign 只在 DescriptorSet::compile 里被调用一次(第 85 行),没有第二次、没有增量更新、没有 VK_DESCRIPTOR_BINDING_UPDATE_AFTER_BIND_BIT(11.11.3)。

11.3.5 与前面章节的交叉引用

第九章 9.8.3 的 ScratchMemory 释放论证在 11.3.4 复用;copyDataToBuffer(5.11)与 ModifiedCount(5.3)的脏标记判断依赖 DescriptorSet::compile 被再次调用,本章短路让它只在首次生效。


11.4 DescriptorBuffer 家族:VkDescriptorBufferInfo 的映射与上传

11.4.1 BufferInfo 的字段与 operator bool()

BufferInfo 封装映射到 VkDescriptorBufferInfo 的设置,其声明与 syncModifiedCounts 摘录如下:

// include/vsg/state/BufferInfo.h:26-36 / 77-80
    class VSG_DECLSPEC BufferInfo : public Inherit<Object, BufferInfo>
    {
    public:
        BufferInfo();
        explicit BufferInfo(Data* in_data);
        BufferInfo(Buffer* in_buffer, VkDeviceSize in_offset, VkDeviceSize in_range, Data* in_data = nullptr);

        BufferInfo(const BufferInfo&) = delete;
        BufferInfo& operator=(const BufferInfo&) = delete;

        ref_ptr<Object> clone(const CopyOp& copyop = {}) const override;
            return data && data->getModifiedCount(copiedModifiedCounts[deviceID]);
        }

        vk_buffer<ModifiedCount> copiedModifiedCounts;

VkDescriptorBufferInfo 的三字段映射是 buffer → buffer(取 vk(deviceID))、offset → offset、range → range,见 DescriptorBuffer.cpp:228–230。第五个字段 parent 不进 Vulkan 结构,用于 staging 场景里指向源 BufferInfo。

requiresAllocation 连 getDeviceMemory 一起判,而两个脏标记函数只判 data:

// include/vsg/state/BufferInfo.h:63-65
        bool requiresAllocation(uint32_t deviceID) const
        {
            return !buffer || buffer->getDeviceMemory(deviceID) == nullptr;
        }

requiresCopy(:69)与 syncModifiedCounts(:75)只看 data,ImageInfo 同类函数还多判 imageView;判空标准不对称,copiedModifiedCounts 按 deviceID 索引。

11.4.2 compile:usage、对齐、一次分配、逐个 reserve

// src/vsg/state/DescriptorBuffer.cpp:103-113 / 154-157
void DescriptorBuffer::compile(Context& context)
{
    if (bufferInfoList.empty()) return;

    auto transferTask = context.transferTask.get();

    VkBufferUsageFlags bufferUsageFlags = 0;
    switch (descriptorType)
    {
    case VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER:
    case VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC:
                    if (bufferInfo->data->dynamic() || transferTask) bufferUsageFlags |= VK_BUFFER_USAGE_TRANSFER_DST_BIT;
                }
            }
        }

switch 只认四种类型,default: break; 让 bufferUsageFlags 保持 0:

// src/vsg/state/DescriptorBuffer.cpp:112-120
    case VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER:
    case VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC:
        bufferUsageFlags = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT;
        ...
    default:
        break;
    }

用 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE 等类型构造(构造函数不限制,DescriptorBuffer.h:29–31)会得到 usage = 0 的 VkBuffer,验证层报错;alignment 也停在默认 4,跳过 minUniformBufferOffsetAlignment。

alignment 默认 4,uniform/storage 时改取设备 limits(第 136–139 行)。第 145–157 行两遍循环的第一遍算 totalSize:每个 data 的 dataSize() 累加并按 alignment 向上取整,data->dynamic() 或存在 transferTask 时补 VK_BUFFER_USAGE_TRANSFER_DST_BIT。

代价与边界:这是第五章 5.11(路径 A copyDataToBuffer)、5.15(deviceMemoryBufferPools->reserveMemory)、5.16(TransferTask)三条路径在描述符层的汇合点。它把 N 个 BufferInfo 合并进一个 VkBuffer,用 offset 区分;单个 reserve 失败只 warn(第 176 行)不抛,那个 BufferInfo 的 buffer 保持空。

11.4.3 assignTo:空指针与 descriptorCount

// src/vsg/state/DescriptorBuffer.cpp:215-224 / 235-237
void DescriptorBuffer::assignTo(Context& context, VkWriteDescriptorSet& wds) const
{
    Descriptor::assignTo(context, wds);

    auto pBufferInfo = context.scratchMemory->allocate<VkDescriptorBufferInfo>(bufferInfoList.size());
    wds.descriptorCount = static_cast<uint32_t>(bufferInfoList.size());
    wds.pBufferInfo = pBufferInfo;

    // convert from VSG to Vk
    for (size_t i = 0; i < bufferInfoList.size(); ++i)
{
    return static_cast<uint32_t>(bufferInfoList.size());
}

第 217 行先调基类清零,第 220 行补 descriptorCount,第 219/221 行分配并挂 pBufferInfo,第 228–230 行填三字段。这里 descriptorCount、getNumDescriptors()、bufferInfoList.size() 三者取同一个值,是 11.1.3 说的"两套口径恰好一致"的典型。

第 228 行把 buffer 的五字段填进 VkDescriptorBufferInfo,其中 data->buffer->vk(...) 没有判空:

// src/vsg/state/DescriptorBuffer.cpp:226-230
        auto& data = bufferInfoList[i];
        VkDescriptorBufferInfo& info = pBufferInfo[i];
        info.buffer = data->buffer->vk(context.deviceID);
        info.offset = data->offset;
        info.range = data->range;

totalSize == 0 或 reserve 失败走 warn(:176)都会让 buffer 留空,assign 照常调用即空指针解引用。

11.4.4 read 丢字段与版本门控

compare 用 compare_pointer_container 深比 bufferInfoList,而 read 只还原 data,两者不对称,源码如下:

// src/vsg/state/DescriptorBuffer.cpp:75-84 / 99-101
void DescriptorBuffer::read(Input& input)
{
    Descriptor::read(input);

    bufferInfoList.clear();

    bufferInfoList.resize(input.readValue<uint32_t>("dataList"));
    for (auto& bufferInfo : bufferInfoList)
    {
        bufferInfo = vsg::BufferInfo::create();
        output.writeObject("data", bufferInfo->data.get());
    }
}

read 遍历 bufferInfoList,把每条的 buffer 置空、offset/range 置 0,只反序列化 data:

// src/vsg/state/DescriptorBuffer.cpp:85-88
        bufferInfo->buffer = nullptr;
        bufferInfo->offset = 0;
        bufferInfo->range = 0;
        input.readObject("data", bufferInfo->data);

三个 Vulkan 字段里 offset/range 完全不落盘,buffer 是编译产物按设计不落盘,反序列化后必须重跑 compile 重建。共享缓冲的布局会丢失;而 compare(:65–73)深比 bufferInfoList,读回对象与原对象必不等,SharedObjects 不会合并。

11.4.5 与前面章节的交叉引用

copyDataToBuffer(5.11)、reserveMemory(5.15)、TransferTask(5.16)在 11.4.2 汇合;ModifiedCount(5.3)是第 205 行 getModifiedCount(copiedModifiedCounts[deviceID]) 的判据,也是"一次性写入"后脏标记失效的根源。


11.5 DescriptorImage 家族:VkDescriptorImageInfo 与三个工厂函数

11.5.1 ImageInfo / Sampler 的字段映射

ImageInfo 封装映射到 VkDescriptorImageInfo 的设置,其声明与 operator bool() 摘录如下:

// include/vsg/state/ImageInfo.h:22-31 / 46-48
    class VSG_DECLSPEC ImageInfo : public Inherit<Object, ImageInfo>
    {
    public:
        ImageInfo() :
            imageLayout(VK_IMAGE_LAYOUT_UNDEFINED) {}

        ImageInfo(ref_ptr<Sampler> in_sampler, ref_ptr<ImageView> in_imageView, VkImageLayout in_imageLayout = VK_IMAGE_LAYOUT_UNDEFINED);

        // Convenience constructor that creates a vsg::ImageView and vsg::Image to represent the data on the GPU.
        template<typename T>
        ref_ptr<Sampler> sampler;
        ref_ptr<ImageView> imageView;
        VkImageLayout imageLayout = VK_IMAGE_LAYOUT_UNDEFINED;

VkDescriptorImageInfo 的三字段来自 sampler、imageView、imageLayout(见 DescriptorImage.cpp:149–159);模板构造把默认布局设为 SHADER_READ_ONLY_OPTIMAL:

// include/vsg/state/ImageInfo.h:32-32
        ImageInfo(ref_ptr<Sampler> in_sampler, ref_ptr<T> in_data, VkImageLayout in_imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL) :

Sampler::vk(Sampler.h:48)直接返回 _implementation[deviceID]->_sampler 不判空,但 compile(DescriptorImage.cpp:114)先取 transferTask 再编译 sampler,正常路径安全;operator bool() 要求两者都有效,assignTo 却分别判空允许为 0,说明它只是便利判断。

11.5.2 compile:mipmap、脏标记与 Context::copy

// src/vsg/state/DescriptorImage.cpp:106-115 / 132-134
void DescriptorImage::compile(Context& context)
{
    if (imageInfoList.empty()) return;

    auto transferTask = context.transferTask.get();

    for (auto& imageInfo : imageInfoList)
    {
        if (imageInfo->sampler) imageInfo->sampler->compile(context);
        if (imageInfo->imageView)

    if (transferTask) transferTask->assign(imageInfoList);
}

无 transferTask 时走 context.copy,判据是 syncModifiedCount(deviceID):

// src/vsg/state/DescriptorImage.cpp:125-128
            if (!transferTask && imageView.image && imageView.image->syncModifiedCount(context.deviceID))
            {
                const auto& image = *imageView.image;
                context.copy(image.data, imageInfo, image.mipLevels);
            }

第 117 行 imageInfo->imageView->image->mipLevels 连解两层只判 imageView;三个工厂走模板构造不留空 image,用户手工构造把 image 留空则空指针解引用。

11.5.3 assignTo 的判空与 createSampedImageDescriptor

// src/vsg/state/DescriptorImage.cpp:136-145 / 146-146 / 181-184
void DescriptorImage::assignTo(Context& context, VkWriteDescriptorSet& wds) const
{
    Descriptor::assignTo(context, wds);

    // convert from VSG to Vk
    auto pImageInfo = context.scratchMemory->allocate<VkDescriptorImageInfo>(imageInfoList.size());
    wds.descriptorCount = static_cast<uint32_t>(imageInfoList.size());
    wds.pImageInfo = pImageInfo;
    for (size_t i = 0; i < imageInfoList.size(); ++i)
    {
        auto& imageInfo = imageInfoList[i];
{
    ref_ptr<ImageInfo> imageImageInfo = ImageInfo::create(nullptr, image, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
    return DescriptorImage::create(imageImageInfo, dstBinding, dstArrayElement, VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE);
}

assignTo 对 sampler/imageView 分别判空并写 0(第 149–157 行),与 DescriptorBuffer::assignTo 第 228 行的无判空形成对照:同为 Descriptor 子类,一个允许部分字段为空、另一个不允许。三个工厂函数里 createSampedImageDescriptor(第 180 行,注意函数名是 Samped 不是 Sampled)在 DescriptorImage.h:58 声明后,grep -rn "createSampedImageDescriptor" 全仓库只命中这两行——声明与定义,零调用。函数体本身可用(创建 VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE 的 descriptor),但名字拼错且没有任何上层引用,是一处写好没接上的 API。

11.5.4 read 硬编码 imageLayout

// src/vsg/state/DescriptorImage.cpp:66-76 / 101-104
void DescriptorImage::read(Input& input)
{
    imageInfoList.clear();

    Descriptor::read(input);

    imageInfoList.resize(input.readValue<uint32_t>("images"));
    for (auto& imageInfo : imageInfoList)
    {
        imageInfo = ImageInfo::create();

        output.writeObject("image", data.get());
    }
}

read 重建 Image/ImageView 时硬编码 usage 与布局:

// src/vsg/state/DescriptorImage.cpp:83-86
        image->usage |= VK_IMAGE_USAGE_TRANSFER_DST_BIT;

        imageInfo->imageView = ImageView::create(image);
        imageInfo->imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;

imageLayout 原值不落盘:shadow map 用的 DEPTH_STENCIL_READ_ONLY_OPTIMAL(ViewDependentState.cpp:358)读回后变成 SHADER_READ_ONLY_OPTIMAL,采样静默错。subresourceRange/format/mipLevels 也全丢。

11.5.5 与前面章节的交叉引用

11.5.1 是第五章 5.9 第三层引用在 VkDescriptorImageInfo 上的投影;5.18 的 transferImageData 是第 128 行 context.copy(...) 的下游。第十章"内置 ShaderSet 走反序列化"与本节 read 同属"格式只留最小信息、靠编译期重推导"。

11.6 DescriptorTexelBufferView 与第五个子类:pTexelBufferView 和 pNext

11.6.1 双重 compile 与 descriptorCount

// src/vsg/state/DescriptorTexelBufferView.cpp:58-67 / 79-81
void DescriptorTexelBufferView::compile(Context& context)
{
    if (texelBufferViews.empty()) return;

    for (auto& bufferView : texelBufferViews)
    {
        bufferView->compile(context);
    }
}

        vk_texelBufferViews[i] = texelBufferViews[i]->vk(context.deviceID);
    }
}

assignTo 里又逐个 compile 一次,于是同一 BufferView 一轮编译被 compile 两次:

// src/vsg/state/DescriptorTexelBufferView.cpp:76-80
    for (size_t i = 0; i < texelBufferViews.size(); ++i)
    {
        texelBufferViews[i]->compile(context);
        vk_texelBufferViews[i] = texelBufferViews[i]->vk(context.deviceID);
    }

第 79 行 vk(context.deviceID) 与 DescriptorBuffer::assignTo 同款无判空。read/write(:44–56)序列化整个 BufferViewList,是四个子类里最完整的;compare(:36–43)深比较,与之对称。

11.6.2 五个 assignTo 的 descriptorCount 对照

子类descriptorCount 来源数据指针基类清零后是否补 count
DescriptorBufferbufferInfoList.size()pBufferInfo是(DescriptorBuffer.cpp:220)
DescriptorImageimageInfoList.size()pImageInfo是(DescriptorImage.cpp:142)
DescriptorTexelBufferViewtexelBufferViews.size()pTexelBufferView是(DescriptorTexelBufferView.cpp:73)
DescriptorAccelerationStructure_vkAccelerationStructures.size()pNext是(DescriptorAccelerationStructure.cpp:63)
Descriptor(基类)无,保持 0无否(Descriptor.cpp:64–71)

第五个子类把数据挂在 VkWriteDescriptorSet::pNext 上(DescriptorAccelerationStructure.cpp:64),前四个挂在三个互斥的数据指针之一。四个子类都补了 descriptorCount,基类不补——11.1.2 说的"纯靠约定"在这张表里可视化:任何一个新子类漏补,写入就是静默的 0 个描述符。

11.6.3 与前面章节的交叉引用

五个 Descriptor 子类是"一个描述对应一个 VkWriteDescriptorSet 加 N 个数据项",11.6.2 的表汇总这种一对多关系;BufferView 与 ImageView/Sampler 同属第三层引用对象,但走 pTexelBufferView 而非 pImageInfo。


11.7 DescriptorPool:四本账与两个统计错误

11.7.1 构造、四本账与 FREE_DESCRIPTOR_SET_BIT

// include/vsg/vk/DescriptorPool.h:48-57 / 68-70
        const uint32_t maxSets = 0;
        const DescriptorPoolSizes descriptorPoolSizes;

        /// mutex used to ensure thread safe access of DescriptorPool resources.
        /// Locked automatically by allocateDescriptorSet(..), freeDescriptorSet(), available() and DescriptorSet:::Implementation
        /// to ensure thread safe operation. Normal VulkanSceneGraph usage will not require users to lock this mutex so treat as an internal implementation detail.
        mutable std::mutex mutex;

    protected:
        ~DescriptorPool() override;
        // updated incrementally by freeDescriptorSet() and allocateDescriptorSet().
        // available() reads this directly instead of walking the whole list.
        DescriptorPoolSizes _recycledDescriptorPoolSizes;
// src/vsg/vk/DescriptorPool.cpp:44-53 / 68-70
DescriptorPool::DescriptorPool(Device* device, uint32_t in_maxSets, const DescriptorPoolSizes& in_descriptorPoolSizes) :
    maxSets(in_maxSets),
    descriptorPoolSizes(in_descriptorPoolSizes),
    _device(device),
    _availableDescriptorSet(maxSets),
    _availableDescriptorPoolSizes(descriptorPoolSizes)
{
    VkDescriptorPoolCreateInfo poolInfo = {};
    poolInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO;
    poolInfo.poolSizeCount = static_cast<uint32_t>(descriptorPoolSizes.size());
    }
    vsg::debug("}");
}

四本账:maxSets/descriptorPoolSizes 是不可变初始容量(const 成员);_availableDescriptorSet 是剩余可分配 set 数,初始 maxSets;_availableDescriptorPoolSizes 是"从未分配出去过"的各类型描述符数,初始等于 descriptorPoolSizes;_recyclingList 是已释放待复用的 Implementation;_recycledDescriptorPoolSizes 是回收列表里各类型描述符的累计量。第 56 行的 FREE_DESCRIPTOR_SET_BIT 是必需的——DescriptorSet::Implementation::~Implementation(DescriptorSet.cpp:137)会 vkFreeDescriptorSets 单个 set;vkCreateDescriptorPool(DescriptorPool.cpp:59)在此调用,失败抛 Exception。

11.7.2 allocateDescriptorSet:兼容判据与异常不配平

// src/vsg/vk/DescriptorPool.cpp:80-90 / 134-137
ref_ptr<DescriptorSet::Implementation> DescriptorPool::allocateDescriptorSet(DescriptorSetLayout* descriptorSetLayout)
{
    std::scoped_lock<std::mutex> lock(mutex);

    if (_availableDescriptorSet == 0)
    {
        return {};
    }

    for (auto itr = _recyclingList.begin(); itr != _recyclingList.end(); ++itr)
    {
    auto dsi = DescriptorSet::Implementation::create(this, descriptorSetLayout);
    vsg::debug("DescriptorPool::allocateDescriptorSet(..) allocated new ", dsi);
    return dsi;
}

回收只比 bindings 是否相同,命中就从 _recycledDescriptorPoolSizes 扣减并复用:

// src/vsg/vk/DescriptorPool.cpp:92-92
        if (dsi->_descriptorSetLayout.get() == descriptorSetLayout || compare_value_container(dsi->_descriptorSetLayout->bindings, descriptorSetLayout->bindings) == 0)

漏掉 createFlags/bindingFlags,且 compare_value_container 就是 memcmp。更糟的是第 131–134 行先 swap/--_availableDescriptorSet 再构造,构造里 vkAllocateDescriptorSets 抛异常时计数不回滚;失败统一返回 {},经 Context::allocateDescriptorSet(Context.cpp:229)到 DescriptorSet::compile:85 直接解引用。

11.7.3 freeDescriptorSet 与 accumulateBindings

// src/vsg/vk/DescriptorPool.cpp:28-37 / 38-38 / 39-42 / 139-148 / 149-149 / 150-150
    void accumulateBindings(vsg::DescriptorPoolSizes& sizes, const vsg::DescriptorSetLayout* layout, int sign)
    {
        if (!layout) return;
        for (auto& binding : layout->bindings)
        {
            auto itr = std::find_if(sizes.begin(), sizes.end(),
                                    [&binding](const VkDescriptorPoolSize& v) { return v.type == binding.descriptorType; });
            if (itr != sizes.end())
                itr->descriptorCount = static_cast<uint32_t>(
                    static_cast<int64_t>(itr->descriptorCount) + sign * static_cast<int64_t>(binding.descriptorCount));
            else if (sign > 0)
                sizes.push_back(VkDescriptorPoolSize{binding.descriptorType, binding.descriptorCount});
        }
    }
} // namespace
void DescriptorPool::freeDescriptorSet(ref_ptr<DescriptorSet::Implementation> dsi)
{
    {
        // swap ownership so that DescriptorSet::Implementation' reference is reset to null and while this DescriptorPool takes a reference to it.
        // acquire lock within local scope so that subsequent dsi->_descriptorPool = {} call doesn't unref and (possibly) delete this DescriptorPool while lock still held.
        std::scoped_lock<std::mutex> lock(mutex);
        _recyclingList.push_back(dsi);
        ++_availableDescriptorSet;
        accumulateBindings(_recycledDescriptorPoolSizes, dsi->_descriptorSetLayout, +1);
    }
    dsi->_descriptorPool = {};
}

freeDescriptorSet(第 139–150 行)把 Implementation 放入回收列表、_availableDescriptorSet++、给 _recycledDescriptorPoolSizes 加回该布局的量,最后在锁外把 dsi->_descriptorPool 置空(第 149 行,注释解释了这是为了避免在持锁时析构池)。注意它不给 _availableDescriptorPoolSizes 加回任何量——回收的 set 的容量单独记在 _recycledDescriptorPoolSizes 里,与"从未分配过"的 _availableDescriptorPoolSizes 是两本互不往来的账。

代价与边界:四本账的语义是"可新分配的" _availableDescriptorPoolSizes 只减不增,"可回收复用的" _recycledDescriptorPoolSizes 随 free/allocate 增减。这要求 available()/used() 把两本账合并,而下一小节说明合并口径出了问题。

11.7.4 available() 的口径与 used() 的迭代器

// src/vsg/vk/DescriptorPool.cpp:152-162 / 203-206
bool DescriptorPool::available(uint32_t& numSets, DescriptorPoolSizes& availableDescriptorPoolSizes) const
{
    std::scoped_lock<std::mutex> lock(mutex);

    if (_availableDescriptorSet == 0) return false;

    numSets += _availableDescriptorSet;

    auto addDescriptorPoolSizes = [](const DescriptorPoolSizes& src, DescriptorPoolSizes& dest) -> void {
        for (auto& dps : src)
        {
        }
    }
    return true;
}

两处硬缺陷,逐行拆:

第一处,available() 第 175 行并入的是 descriptorPoolSizes——不可变的初始全量,而不是 _availableDescriptorPoolSizes(剩余量)。used() 第 194–197 行却用 _availableDescriptorPoolSizes 算差值。

第二处,第 200 行 used_itr += usedDescriptorCount;。used_itr 是 std::vector<VkDescriptorPoolSize>::iterator,这行把迭代器往后移动 usedDescriptorCount 个元素,而不是累加已有条目的 descriptorCount。

11.7.5 与前面章节的交叉引用

11.7.1 是第六章 6.x 那个 descriptorPools 池对象的内部账本;本章"可复现验证"沿用第九章 9.15.1 的表格法核 vkAllocateDescriptorSets 与 vkUpdateDescriptorSets 各只有一处。


11.8 DescriptorPools:扩容策略、reserve 与死代码

11.8.1 三个扩容参数与 getDescriptorPoolSizesToUse

// include/vsg/vk/DescriptorPools.h:31-38
        uint32_t minimum_maxSets = 0;    // minimum value of maxSets when allocating new DescriptoPool.
        uint32_t maximum_maxSets = 2048; // maximum value of minimum_maxSets can grow to.
        double scale_maxSets = 2.0;      // how to scale minimum_maxSets on each successive DescriptorPool allocation.

        // totals of all the calls to reserve(const ResourceRequirements& requirements), used to guide allocation of new DescritproPool
        uint32_t reserve_count = 0;
        uint32_t reserve_maxSets = 0;
        DescriptorPoolSizes reserve_descriptorPoolSizes;
// src/vsg/vk/DescriptorPools.cpp:29-39 / 68-71
void DescriptorPools::getDescriptorPoolSizesToUse(uint32_t& maxSets, DescriptorPoolSizes& descriptorPoolSizes)
{
    if (reserve_count > 0)
    {
        if (minimum_maxSets > reserve_maxSets)
        {
            for (auto& dps : reserve_descriptorPoolSizes)
            {
                dps.descriptorCount = static_cast<uint32_t>(std::ceil(static_cast<double>(dps.descriptorCount) * static_cast<double>(minimum_maxSets) / static_cast<double>(reserve_maxSets)));
            }
            reserve_maxSets = minimum_maxSets;
    reserve_count = 0;
    reserve_maxSets = 0;
    reserve_descriptorPoolSizes.clear();
}

逐分支推导:reserve_count > 0 时,第 33–40 行若 minimum_maxSets > reserve_maxSets,把累计的 reserve_descriptorPoolSizes 按比例放大到 minimum_maxSets / reserve_maxSets;第 42–45 行用 minimum_maxSets 抬高 maxSets;第 47–63 行把累计的各类型需求量合并进 descriptorPoolSizes(同类型取较大值)。第 66 行把 minimum_maxSets 更新为 min(2048, maxSets * 2.0),第 68–70 行清空三个累计量。

放大公式第 37 行在 reserve_maxSets == 0 时会除零,但 minimum_maxSets 初值 0(DescriptorPools.h:31),首次 reserve 不满足 > reserve_maxSets,该分支不进;第二次起分母已被第 39/66 行设为正数。allocateDescriptorSet(DescriptorPools.cpp:149–150)传 maxSets = 1,第 66 行把 minimum_maxSets 设为 min(2048, 1 * 2.0) = 2,即兜底池至少按 2 个 set 起。

11.8.2 reserve:富余判断与 available() 的连带影响

// src/vsg/vk/DescriptorPools.cpp:73-82 / 83-83 / 133-136
void DescriptorPools::reserve(const ResourceRequirements& requirements)
{
    auto maxSets = requirements.computeNumDescriptorSets();
    auto descriptorPoolSizes = requirements.computeDescriptorPoolSizes();

    // update the variables tracing all reserve calls.
    ++reserve_count;
    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; });
    // not enough descriptor resources available so allocator new DescriptorPool.
    getDescriptorPoolSizesToUse(required_maxSets, required_descriptorPoolSizes);
    descriptorPools.push_back(vsg::DescriptorPool::create(device, required_maxSets, required_descriptorPoolSizes));
}

reserve 逐池调 available() 汇总,这是 11.7.4 口径错误的输入端:

// src/vsg/vk/DescriptorPools.cpp:93-96
    for (auto& descriptorPool : descriptorPools)
    {
        descriptorPool->available(available_maxSets, available_descriptorPoolSizes);
    }

拿到的是各池初始全量 + 回收量,据此算差额(第 99–124 行)并新建池;available 虚高则新池容量不足。reserve 是 void、失败无信号,而 vkCreateDescriptorPool 失败抛异常(DescriptorPool.cpp:61)会穿透 Context::reserve。

11.8.3 allocateDescriptorSet 兜底与 report 死代码

// src/vsg/vk/DescriptorPools.cpp:138-147 / 155-157
ref_ptr<DescriptorSet::Implementation> DescriptorPools::allocateDescriptorSet(DescriptorSetLayout* descriptorSetLayout)
{
    for (auto itr = descriptorPools.rbegin(); itr != descriptorPools.rend(); ++itr)
    {
        auto dsi = (*itr)->allocateDescriptorSet(descriptorSetLayout);
        if (dsi) return dsi;
    }

    DescriptorPoolSizes descriptorPoolSizes;
    descriptorSetLayout->getDescriptorPoolSizes(descriptorPoolSizes);
    descriptorPools.push_back(descriptorPool);
    return dsi;
}

第 140 行倒序遍历(优先最新建的池),第 142–143 行命中即返回。全不命中则新建:DescriptorPools.cpp:149 的 maxSets = 1、第 150 行放大、第 152 行建池、第 153 行分配。第 153 行返回值没有判空就 push_back 并 return(第 155–156 行):若新池因 descriptorPoolSizes 不足或 vkAllocateDescriptorSets 失败返回空,空 dsi 一路回到 DescriptorSet::compile:85 的 ->assign(...)。这是 11.7.2 那条空返回值链的最上游。

DescriptorPools::report(DescriptorPools.cpp:159–212)里有一段编译期不可达的死代码:

// src/vsg/vk/DescriptorPools.cpp:181-192
#if 1
    out << indent << "descriptorPools " << descriptorPools.size() << std::endl;
#else
    out << indent << "descriptorPools " << descriptorPools.size() << " {" << std::endl;
    indent += 4;
    for (auto& dp : descriptorPools)
    {
        dp->report(out, indent);
    }
    indent -= 4;
    out << indent << "}" << std::endl;
#endif

#if 1 恒真,#else 分支不参与编译,于是 DescriptorPool::report(DescriptorPool.cpp:208–254)在全库零调用;DescriptorPools::report 自身也没有任何调用点(grep 验证见"可复现验证")。两个 report 加上 11.5.3 的 createSampedImageDescriptor、11.7.4 的 used() 数据,构成一组"能表达但没接上/没验过"的观测 API。

11.8.4 与前面章节的交叉引用

11.8.1 的 reserve_* 累计量是第六章"容量由 Context::reserve 动态决定"的具体实现;minimum_maxSets 翻倍只增不减,与第六章 6.11 std::max 只能上调同方向。


11.9 ResourceRequirements 里的 descriptor 计数与 Context 接线

11.9.1 两个 compute 与计数容器

// src/vsg/vk/ResourceRequirements.cpp:52-64
uint32_t ResourceRequirements::computeNumDescriptorSets() const
{
    return externalNumDescriptorSets + static_cast<uint32_t>(descriptorSets.size());
}

DescriptorPoolSizes ResourceRequirements::computeDescriptorPoolSizes() const
{
    DescriptorPoolSizes poolSizes;
    for (auto& [type, count] : descriptorTypeMap)
    {
        poolSizes.push_back(VkDescriptorPoolSize{type, count});
    }
    return poolSizes;
}

computeNumDescriptorSets() 是 externalNumDescriptorSets(来自 ResourceHints,ResourceRequirements.cpp:73)加 descriptorSets.size()(std::set<const DescriptorSet*>,按指针去重);computeDescriptorPoolSizes() 把 descriptorTypeMap(std::map<VkDescriptorType, uint32_t>)倒成 VkDescriptorPoolSize 数组。第六章 6.x 已给过这两个函数的调用面,本章只补它们与描述符的关系:前者数的是"有多少个 DescriptorSet 对象",后者数的是"每个 descriptor 类型一共多少个描述符",两者是独立累加的,不互相乘。

11.9.2 registerDescriptor:无条件累加与去重不对称

// src/vsg/vk/ResourceRequirements.cpp:159-169 / 228-231
void CollectResourceRequirements::apply(const StateCommand& stateCommand)
{
    if (stateCommand.slot > requirements.maxSlots.state) requirements.maxSlots.state = stateCommand.slot;
    stateCommand.traverse(*this);
}

void CollectResourceRequirements::apply(const DescriptorSet& descriptorSet)
{
    if (requirements.descriptorSets.count(&descriptorSet) == 0)
    {
        requirements.descriptorSets.insert(&descriptorSet);
        for (const auto& imageInfo : descriptorImage.imageInfoList) apply(imageInfo);
    }
}

registerDescriptor 先把计数加上去,去重判断放在后面:

// src/vsg/vk/ResourceRequirements.cpp:175-182
bool CollectResourceRequirements::registerDescriptor(const Descriptor& descriptor)
{
    requirements.descriptorTypeMap[descriptor.descriptorType] += descriptor.getNumDescriptors();

    if (requirements.descriptors.count(&descriptor) == 0)
    {
        requirements.descriptors.insert(&descriptor);
        return true;

descriptorTypeMap 在去重前无条件累加,共享 descriptor 被数两次,descriptorSets/bufferInfoList 只收一次——三套口径不一致,reserve 建的池偏大。规避是把第 177 行移进 if 成功分支;注意第 201–213 行的四类型 switch 与 DescriptorBuffer::compile:110–122 是两份独立代码,新类型必须同步改,没有机制保证。

11.9.3 两套池容量口径与 Context 接线

// src/vsg/vk/Context.cpp:212-230
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;
}

ref_ptr<DescriptorSet::Implementation> Context::allocateDescriptorSet(DescriptorSetLayout* descriptorSetLayout)
{
    return descriptorPools->allocateDescriptorSet(descriptorSetLayout);
}

Context::reserve(第 212 行)第 222 行把收集来的 requirements 交给 DescriptorPools::reserve;Context::allocateDescriptorSet(第 227 行)只是转调。第六章 6.x 已给过 CompileTraversal::add 里 context->reserve(requirements) 的调用面,本章补的是这条链的两套容量口径:

环节数据来源是否看 binding.descriptorCount是否乘 set 个数
ResourceRequirements::computeDescriptorPoolSizesdescriptorTypeMap(按 Descriptor 对象累加 getNumDescriptors())否否
DescriptorPool::allocateDescriptorSet 扣减getDescriptorPoolSizes(按 DescriptorSetLayout::bindings 累加 descriptorCount)是否
computeNumDescriptorSetsdescriptorSets.size()否—

DescriptorPools::reserve 用第一行决定"池要建多大",DescriptorPool::allocateDescriptorSet 用第二行决定"这次分配扣多少"。DescriptorBinding::descriptorCount(ShaderSet.h:47,默认 0)只进 layout 的 bindings,不进 descriptorTypeMap——而 DescriptorConfigurator 创建 DescriptorImage/DescriptorBuffer 时用的是 descriptorBinding.data 单份数据(GraphicsPipelineConfigurator.cpp:142/226),getNumDescriptors() 返回容器 size() 恒为 1。

11.9.4 与前面章节的交叉引用

第六章 6.11 的 std::max 与 6.x 的 Context::reserve 调用面是本节上游;CollectResourceRequirements 的 Visitor 语义见第三章 3.x,BufferInfo 在 11.9.2 第 219 行被逐个 apply(bufferInfo, properties) 收集。

11.10 BindDescriptorSet / BindDescriptorSets:slot 协议与帧期绑定

11.10.1 五个构造点与 slot = 1 + firstSet

// include/vsg/state/BindDescriptorSet.h:30-39 / 40-40 / 50-53 / 97-106 / 107-107 / 127-130
        BindDescriptorSets(VkPipelineBindPoint in_bindPoint, PipelineLayout* in_layout, uint32_t in_firstSet, const DescriptorSets& in_descriptorSets) :
            Inherit(1 + in_firstSet),
            pipelineBindPoint(in_bindPoint),
            layout(in_layout),
            firstSet(in_firstSet),
            descriptorSets(in_descriptorSets)
        {
        }

        BindDescriptorSets(VkPipelineBindPoint in_bindPoint, PipelineLayout* in_layout, const DescriptorSets& in_descriptorSets) :
            Inherit(1), // slot 1
        ref_ptr<PipelineLayout> layout;
        uint32_t firstSet;
        DescriptorSets descriptorSets;
        std::vector<uint32_t> dynamicOffsets;
        BindDescriptorSet(VkPipelineBindPoint in_bindPoint, PipelineLayout* in_pipelineLayout, uint32_t in_firstSet, DescriptorSet* in_descriptorSet) :
            Inherit(1 + in_firstSet),
            pipelineBindPoint(in_bindPoint),
            layout(in_pipelineLayout),
            firstSet(in_firstSet),
            descriptorSet(in_descriptorSet)
        {
        }

        BindDescriptorSet(VkPipelineBindPoint in_bindPoint, PipelineLayout* in_pipelineLayout, DescriptorSet* in_descriptorSet) :
            Inherit(1), // slot 1
        ref_ptr<PipelineLayout> layout;
        uint32_t firstSet;
        ref_ptr<DescriptorSet> descriptorSet;
        std::vector<uint32_t> dynamicOffsets;

五个构造点里三个用 Inherit(1 + in_firstSet)、两个用 Inherit(1) 且 firstSet(0);StateCommand 默认 Inherit(0) 即 slot = 0(StateCommand.h:26)。便捷构造把 firstSet 直接当容器下标,无边界检查:

// include/vsg/state/BindDescriptorSet.h:121-121
            descriptorSet(vsg::DescriptorSet::create(in_pipelineLayout->setLayouts[in_firstSet], in_descriptors))

越界即 UB;默认构造(BindDescriptorSet.cpp:126–130)走 slot 0,与带参的 slot 1 分叉,read 恢复的对象同 firstSet 可能不同 slot。

11.10.2 compile 短路与 record

// src/vsg/state/BindDescriptorSet.cpp:95-104 / 105-105 / 117-120 / 195-204 / 205-205 / 213-216
void BindDescriptorSets::compile(Context& context)
{
    auto& vkd = _vulkanData[context.deviceID];

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

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

    vkd._vkDescriptorSets.resize(descriptorSets.size());
    vkCmdBindDescriptorSets(commandBuffer, pipelineBindPoint, vkd._vkPipelineLayout, firstSet,
                            static_cast<uint32_t>(vkd._vkDescriptorSets.size()), vkd._vkDescriptorSets.data(),
                            static_cast<uint32_t>(dynamicOffsets.size()), dynamicOffsets.data());
}
void BindDescriptorSet::compile(Context& context)
{
    auto& vkd = _vulkanData[context.deviceID];

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

    layout->compile(context);
    descriptorSet->compile(context);

    vkd._vkPipelineLayout = layout->vk(context.deviceID);
    vkCmdBindDescriptorSets(commandBuffer, pipelineBindPoint, vkd._vkPipelineLayout, firstSet,
                            1, &(vkd._vkDescriptorSet),
                            static_cast<uint32_t>(dynamicOffsets.size()), dynamicOffsets.data());
}

逐分支推导:BindDescriptorSets::compile 第 100 行判据是"layout 句柄非零 且 _vkDescriptorSets.size() == descriptorSets.size()";BindDescriptorSet::compile 第 200 行是"两个句柄都非零"。两者都不比内容:把 descriptorSets[0] 或 descriptorSet 换成另一个对象(size 不变)后 compile 直接返回,record 仍绑旧 VkDescriptorSet。这与第九章 9.10 "GraphicsPipeline::compile 只比 _pipelineStates"是同一类缓存键不完整,且这里连一次容器比较都没有。

record(第 113–120、209–216 行)是 const,用 _vulkanData[commandBuffer.deviceID] 取缓存句柄,未编译就录制会把 0 句柄传给 vkCmdBindDescriptorSets。dynamicOffsets.size() 与 dynamicOffsets.data() 直接透传,库不校验它与布局里动态描述符数量是否相等(11.11.1)。

代价与边界:compare(BindDescriptorSet.cpp:42–53、142–153)比 pipelineBindPoint、layout、firstSet、descriptorSets/descriptorSet,不比 dynamicOffsets;而 read(第 72、172 行)与 write(第 91、191 行)序列化 dynamicOffsets。两个 dynamicOffsets 不同、其余字段相同的绑定命令会被 SharedObjects 判等合并,动态偏移静默丢失。

11.10.3 与前面章节的交叉引用

第八章 8.2.3/8.2.4 的 slot 协议是 11.10.1 的直接上游;与第九章 9.1.2 转发式 compile 相比,这里编译只取句柄快照,缓存键问题更严重。


11.11 动态偏移、数组描述符、VK_DESCRIPTOR_BINDING_* 与空布局

11.11.1 dynamicOffsets 全库零生产者

grep -rn "dynamicOffsets" --include=*.h --include=*.cpp . 在本仓库命中 12 行,全部在 BindDescriptorSet.h/.cpp:两个字段声明(BindDescriptorSet.h:53、BindDescriptorSet.h:130)、两个拷贝构造(.cpp:38、.cpp:138)、两处 read(.cpp:72、.cpp:172)、两处 write(.cpp:91、.cpp:191)、两处注释掉的 info(.cpp:115、.cpp:211)、两处 record 传参(.cpp:119、.cpp:215)。没有一处 push_back、resize、assign 或赋值(除拷贝构造与 readValues)。

结论:动态偏移在库内只有消费者(vkCmdBindDescriptorSets 的倒数两个参数)与序列化通道,没有任何生产者。DescriptorBinding::data(ShaderSet.h:50)是静态 ref_ptr<Data>,第十章预告问"它是静态内容还是运行期可变的动态缓冲"——答案是静态内容:DescriptorConfigurator::assignDescriptor(GraphicsPipelineConfigurator.cpp:241–242)用它构造 DescriptorBuffer,UNIFORM_BUFFER_DYNAMIC/STORAGE_BUFFER_DYNAMIC 只在 DescriptorBuffer.cpp:113/117 的 switch 里被当作普通 uniform/storage 处理,dynamicOffsets 从未被填。

11.11.2 descriptorCount 的四个来源与 pBindingFlags

来源位置数值
DescriptorBinding::descriptorCount(默认 0)ShaderSet.h:47进 layout 的 bindings
DescriptorConfigurator::assignDescriptor 的形参GraphicsPipelineConfigurator.cpp:263/288写进 VkDescriptorSetLayoutBinding
VkWriteDescriptorSet::descriptorCountDescriptorBuffer.cpp:220 等四处取各自容器 size()
池容量扣减DescriptorSetLayout.cpp:72/78累加 binding.descriptorCount

四者互不校验。getDescriptorPoolSizes(DescriptorSetLayout.cpp:63–81)按 binding.descriptorCount 累加,因此数组描述符(descriptorCount > 1)在池侧按 N 计,在写入侧按容器 size() 计。二者不等时,要么池扣多了(浪费),要么 vkUpdateDescriptorSets 写入数量少于布局声明且未启用 PARTIALLY_BOUND(读到未定义描述符)。

pBindingFlags 链路只有一条:DescriptorSetLayout::addBinding(DescriptorSetLayout.cpp:56–60)填 bindingFlags → Implementation(DescriptorSetLayout.cpp:163–173)挂 VkDescriptorSetLayoutBindingFlagsCreateInfo 到 pNext。库内 ShaderSet.cpp:550 与 GraphicsPipelineConfigurator.cpp:288 构造 binding 时都用 nullptr 收尾且从不填 bindingFlags,所以 pNext 在正常路径恒为 nullptr(DescriptorSetLayout.cpp:165)。

11.11.3 四个 flag、零使用与 SDK 测量程序

include/vsg/vk/vulkan.h:15 是 #include <vulkan/vulkan.h>,VkDescriptorType 枚举个数、sizeof(VkDescriptorSetLayoutBinding)、sizeof(VkWriteDescriptorSet)、sizeof(VkDescriptorPoolSize)、VkDescriptorPoolCreateFlagBits 全部以本机 SDK 为准,仓库内无定义,本章不编造字节数。仓库内自带的是 vulkan.h:419–426 的 VkDescriptorBindingFlagBits 回退定义,4 个有效位:UPDATE_AFTER_BIND_BIT = 0x1、UPDATE_UNUSED_WHILE_PENDING_BIT = 0x2、PARTIALLY_BOUND_BIT = 0x4、VARIABLE_DESCRIPTOR_COUNT_BIT = 0x8,加 FLAG_BITS_MAX_ENUM = 0x7FFFFFFF。

grep -rn "VK_DESCRIPTOR_BINDING_\|UPDATE_AFTER_BIND\|PARTIALLY_BOUND\|VARIABLE_DESCRIPTOR_COUNT" include/vsg src/vsg 只命中两组:vulkan.h:420–424 的定义,以及 DescriptorPool.cpp:56 注释里那句 "will we need VK_DESCRIPTOR_POOL_CREATE_UPDATE_AFTER_BIND_BIT_EXT later?"。库内零处设置这些 flag。

本机字节数用下面这段程序测量,编译需要本机 Vulkan SDK 的 vulkan/vulkan.h 与 VSG 的 include/:

// 测量程序:sizeof 取决于本机 Vulkan SDK,仓库内不提供这些定义
#include <vsg/vk/vulkan.h>
#include <cstdio>
int main()
{
    std::printf("VkDescriptorSetLayoutBinding = %zu\n", sizeof(VkDescriptorSetLayoutBinding));
    std::printf("VkWriteDescriptorSet        = %zu\n", sizeof(VkWriteDescriptorSet));
    std::printf("VkDescriptorPoolSize        = %zu\n", sizeof(VkDescriptorPoolSize));
    std::printf("VkDescriptorImageInfo       = %zu\n", sizeof(VkDescriptorImageInfo));
    std::printf("VkDescriptorBufferInfo      = %zu\n", sizeof(VkDescriptorBufferInfo));
    std::printf("VK_HEADER_VERSION           = %d\n", VK_HEADER_VERSION);
    return 0;
}

sizeof(VkDescriptorSetLayoutBinding) 直接决定 11.2.6 里 compare_value_container 的 memcmp 区间长度,也决定 pImmutableSamplers 与 padding 是否被比进去——这正是"以本机 SDK 为准"的理由:不同 SDK 版本的结构体布局可能变化,compare 的结果随之变化。

11.11.4 与前面章节的交叉引用

DescriptorBinding 九字段(第十章)在 11.11.2 成为 descriptorCount 第一来源;第十章陷阱表第 17 条补空布局的闭合点是 ShaderSet.cpp:594,空 bindings 让 getDescriptorPoolSizes 返回空 vector,不占池容量。第九章 9.15.1 的"随 SDK 而定"本节沿用并给出测量程序。


11.12 ShaderSet 的 DescriptorBinding 如何变成 DescriptorSetLayout

11.12.1 九字段与 define 门控

// include/vsg/utils/ShaderSet.h:40-55
    struct VSG_DECLSPEC DescriptorBinding
    {
        std::string name;
        std::string define;
        uint32_t set = 0;
        uint32_t binding = 0;
        VkDescriptorType descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
        uint32_t descriptorCount = 0;
        VkShaderStageFlags stageFlags = 0;
        CoordinateSpace coordinateSpace = CoordinateSpace::NO_PREFERENCE;
        ref_ptr<Data> data;

        int compare(const DescriptorBinding& rhs) const;

        explicit operator bool() const noexcept { return !name.empty(); }
    };

九个字段里 name/define 是约定,set/binding/descriptorType/descriptorCount/stageFlags 是布局参数,coordinateSpace 是 1.1.10 追加的字段(第十章讲过),data 是默认内容。descriptorCount 默认 0——addDescriptorBinding(ShaderSet.cpp:178–181)把实参原样写入,内置 ShaderSet 的 .vsgb 数据里每个 binding 都带非零值,但一个手工构造、忘记填 descriptorCount 的 DescriptorBinding 会生成 descriptorCount = 0 的 VkDescriptorSetLayoutBinding,Vulkan 规范不允许 0,属于错误默认值。

11.12.2 createDescriptorSetLayout 与兼容判定的 memcmp

// src/vsg/utils/ShaderSet.cpp:514-524 / 553-556
bool ShaderSet::compatibleDescriptorSetLayout(const DescriptorSetLayout& dsl, const std::set<std::string>& defines, uint32_t set) const
{
    for (auto& cdsb : customDescriptorSetBindings)
    {
        if (cdsb->set == set && cdsb->compatibleDescriptorSetLayout(dsl)) return true;
    }

    DescriptorSetLayoutBindings bindings;
    for (auto& binding : descriptorBindings)
    {
        if (binding.set == set)
    }

    return DescriptorSetLayout::create(bindings);
}

两个函数结构相同:先查 customDescriptorSetBindings(ViewDependentStateBinding 经 ShaderSet.cpp:145–148 返回 viewDescriptorSetLayout),再按 set 过滤,define 为空或在 defines 里才纳入,末项 pImmutableSamplers = nullptr。这是第十章预告第一问的答案:DescriptorBinding → DescriptorSetLayout::create(bindings) → compile(DescriptorSetLayout.cpp:146)→ vkCreateDescriptorSetLayout。

代价与边界:第 533 行 compare_value_container(dsl.bindings, bindings) == 0 是 11.2.6 的 memcmp 直接下游。ShaderSet::compatiblePipelineLayout(ShaderSet.cpp:558–585)逐个 set 调它,GraphicsPipelineConfigurator::_assignInheritedSets(GraphicsPipelineConfigurator.cpp:742/752/763)又调 compatiblePipelineLayout 决定哪些 set 算"继承"。

11.12.3 与前面章节的交叉引用

本节只取第十章 DescriptorBinding 到布局的投影;第十章陷阱表第 17 条与 11.2.5 是同一个 createPipelineLayout(ShaderSet.cpp:587–609)的两个视角,第九章 9.15.2 的 compare.h 索引在 11.12.2 第 533 行落到调用点。


11.13 DescriptorConfigurator:从约定到 DescriptorSet

11.13.1 assignDescriptor(set, ...) 的稀疏 vector 与重复短路

// src/vsg/utils/GraphicsPipelineConfigurator.cpp:263-272 / 289-291
bool DescriptorConfigurator::assignDescriptor(uint32_t set, uint32_t binding, VkDescriptorType descriptorType, uint32_t descriptorCount, VkShaderStageFlags stageFlags, ref_ptr<Descriptor> descriptor)
{
    if (auto currentSize = descriptorSets.size(); set >= currentSize)
    {
        descriptorSets.resize(set + 1);
    }

    auto& ds = descriptorSets[set];
    if (!ds)
    {

    return true;
}

逐分支推导:descriptorSets 按 set 编号索引(第 265–268 行 resize(set + 1)),编号稀疏时中间是空 ref_ptr;第 270–275 行按需创建 DescriptorSet 与空 DescriptorSetLayout;第 277–283 行检测同 binding 重复,命中直接 return false;第 285–288 行追加 descriptor 与 layout binding。注意它不用 DescriptorSetLayout::addBinding(11.2.2),而是直接 push_back 聚合初始化,因此 bindingFlags 始终为空——这解释了 11.2.2 的稀疏索引缺陷为何在正常路径不触发。

代价与边界:第 281 行返回 false 时,descriptor 与 layout binding 都没加,但所有调用方(enableTexture 第 134 行、assignTexture 第 151/182 行、enableDescriptor 第 219 行、assignDescriptor(name,...) 第 235/251 行)都已提前 assigned.insert(name)。于是 assigned 标记了"已分配"而实际未分配,assignDefaults(11.13.2)因此不会补默认值,用户得到一个缺 binding 的布局且无报错。这是状态不配平。

11.13.2 assignDefaults 忽略返回值与 compare

// src/vsg/utils/GraphicsPipelineConfigurator.cpp:293-303 / 347-350
bool DescriptorConfigurator::assignDefaults(const std::set<uint32_t>& inheritedSets)
{
    bool assignedDefault = false;
    if (shaderSet)
    {
        for (auto& descriptorBinding : shaderSet->descriptorBindings)
        {
            if (inheritedSets.count(descriptorBinding.set) != 0)
            {
                continue;
            }
    }

    return assignedDefault;
}

第 305 行只补 define 为空且未标记的 binding,第 316 行要求 descriptorBinding.data 非空,第 318–329 行按图像类型分派两个子类(dstBinding 取 descriptorBinding.binding)。第 333/338 行的 assignDescriptor 返回值被丢弃,第 342 行仍无条件 assigned.insert 并置 assignedDefault = true——与 11.13.1 的提前插入叠加成两处"标记先于结果"。compare(GraphicsPipelineConfigurator.cpp:108–121)比 shaderSet、two_sided、defines、descriptorSets 等字段,reset()(第 123–128 行)清空三个容器。

11.13.3 与前面章节的交叉引用

DescriptorBinding::define 门控在 11.13.2 第 305 行判"补不补默认值"、在 11.12.2 判"建不建 binding",两处布局必须逐字节一致才能通过兼容判定。第十章预告第二问的链路到此闭合:assignDefaults → DescriptorSet → compile → assignTo → vkUpdateDescriptorSets。

11.14 上层装配:GraphicsPipelineConfigurator 与 Builder

11.14.1 init() 的顺序与 copyTo 的连续段合并

// src/vsg/utils/GraphicsPipelineConfigurator.cpp:786-795 / 796-796 / 815-818 / 924-933 / 934-934 / 957-960
void GraphicsPipelineConfigurator::init()
{
    if (!vertexInputRates.empty())
    {
        if (const auto& descriptorBinding = shaderSet->getDescriptorBinding("vertexInputRates"))
        {
            auto vir = vsg::uintArray::create(vertexInputRates.rbegin()->first + 1, 0);
            for (auto [binding, rate] : vertexInputRates)
            {
                vir->set(binding, rate);
            }
    layout = shaderSet->createPipelineLayout(shaderHints->defines);
    graphicsPipeline = GraphicsPipeline::create(layout, shaderSet->getShaderStages(shaderHints), pipelineStates, subpass);
    bindGraphicsPipeline = vsg::BindGraphicsPipeline::create(graphicsPipeline);
}
        for (uint32_t set = 0; set < active.descritorSets.size();)
        {
            if (active.descritorSets[set])
            {
                uint32_t last = set + 1;
                for (; (last < active.descritorSets.size()) && active.descritorSets[last]; ++last) {}

                if ((last - set) == 1)
                {
                    auto bindDescriptorSet = BindDescriptorSet::create(VK_PIPELINE_BIND_POINT_GRAPHICS, layout, static_cast<uint32_t>(set), active.descritorSets[set]);

                    stateCommands.push_back(bindDescriptorSets);
                    stateAssigned = true;
                }

init()(第 786 行)顺序固定:assignDefaults(第 810 行)→ 合并 defines(第 812 行)→ createPipelineLayout(第 815 行,11.12.2)→ 建管线。copyTo 第 924–960 行把 descriptorConfigurator->descriptorSets 里连续非空的段扫描出来:单 set 生成 BindDescriptorSet(第 933 行),连续多 set 生成 BindDescriptorSets(第 951 行),firstSet 传 static_cast<uint32_t>(set),于是 11.10.1 的 slot = 1 + firstSet 在这里被实例化。

11.14.2 DisableInheritedState 的越界

// src/vsg/utils/GraphicsPipelineConfigurator.cpp:851-861 / 888-891
        struct DisableInheritedState : public Visitor
        {
            DescriptorSets descritorSets;

            explicit DisableInheritedState(DescriptorConfigurator& dc) :
                descritorSets(dc.descriptorSets.size())
            {
                for (size_t set = 0; set < dc.descriptorSets.size(); ++set)
                {
                    descritorSets[set] = dc.descriptorSets[set];
                }
                    }
                }
            }
        } active(*descriptorConfigurator);

前两个 apply 判了 firstSet < size(),唯独 apply(BindDescriptorSets&) 只判起点,循环无上界:

// src/vsg/utils/GraphicsPipelineConfigurator.cpp:884-887
                    uint32_t end_set = bds.firstSet + static_cast<uint32_t>(bds.descriptorSets.size());
                    for (uint32_t set = bds.firstSet; set < end_set; ++set)
                    {
                        descritorSets[set].reset();

end_set 超过本地 descriptorSets.size() 时 operator[] 越界写(UB);规避是循环条件补 && set < descritorSets.size()。

11.14.3 与前面章节的交叉引用

11.14.1 补全第九章 9.14 的 slot 1..N 这一半;第十章的 ShaderSet::createPipelineLayout 与 DescriptorConfigurator 是同一 init() 的前后两步(第 810/815 行),依赖 11.12.2 兼容判定保持一致。


11.15 view 槽与 copy / compare / read / write 四套语义

11.15.1 BindViewDescriptorSets:默认构造的 slot 与 firstSet 不配平

// src/vsg/state/ViewDependentState.cpp:105-114 / 152-154
BindViewDescriptorSets::BindViewDescriptorSets() :
    Inherit(2), // slot 2
    pipelineBindPoint(VK_PIPELINE_BIND_POINT_GRAPHICS),
    firstSet(0)
{
}

int BindViewDescriptorSets::compare(const Object& rhs_object) const
{
    int result = StateCommand::compare(rhs_object);
        commandBuffer.viewDependentState->bindDescriptorSets(commandBuffer, pipelineBindPoint, layout->vk(commandBuffer.deviceID), firstSet);
    }
}

带参构造(ViewDependentState.h:58–64)用 Inherit(1 + in_firstSet),默认构造用 Inherit(2) 且 firstSet(0)。同一个 firstSet = 0 在两条构造路径上分别落到 slot 1 与 slot 2,是"双份真相"硬缺陷;read(ViewDependentState.cpp:124–131)只读写 pipelineBindPoint/layout/firstSet,slot 由 StateCommand::read 单独恢复,序列化对象的 slot 与 firstSet 更易分叉。

// src/vsg/state/ViewDependentState.cpp:1056-1060
void ViewDependentState::bindDescriptorSets(CommandBuffer& commandBuffer, VkPipelineBindPoint pipelineBindPoint, VkPipelineLayout layout, uint32_t firstSet)
{
    auto vk = descriptorSet->vk(commandBuffer.deviceID);
    vkCmdBindDescriptorSets(commandBuffer, pipelineBindPoint, layout, firstSet, 1, &vk, 0, nullptr);
}

dynamicOffsets 参数恒 0, nullptr(第 1059 行),view 槽没有动态偏移。ViewDependentState.cpp:370–377 遍历 descriptorConfigurator->descriptorSets 把最后一个非空的赋给 descriptorSet/descriptorSetLayout,多个 set 时前面的被丢弃。

11.15.2 四套语义总账

类compare 覆盖read/write 覆盖分叉
Descriptor3 字段3 字段,descriptorType 门控 1.1.11(Descriptor.cpp:52/61)旧文件靠子类默认构造兜底
DescriptorSetLayoutcreateFlags + bindings(memcmp)+ bindingFlags(DescriptorSetLayout.cpp:90–93)4 字段门控 1.1.12,不读写 pImmutableSamplers(:105–142)memcmp 与序列化不同步
DescriptorBufferbufferInfoList 深比较(:72)只读写 data(:75–101)反序列化后 compare 必不等
DescriptorImageimageInfoList 深比较(:63)只读写 sampler+data,硬编码 imageLayout(:66–104)丢 layout 与重建 ImageView
DescriptorTexelBufferViewtexelBufferViews 深比较(:42)整个 list(:44–56)无
DescriptorSetsetLayout + descriptors(:50–51)两字段(:54–68)无
BindDescriptorSet(s)4 项,漏 dynamicOffsets(BindDescriptorSet.cpp:49–52/149–152)5 项,含 dynamicOffsets(:72/91/172/191)去重丢动态偏移
BindViewDescriptorSets3 项(ViewDependentState.cpp:119–121)3 项(:124–140)slot 不落 read 的本类字段
DescriptorConfigurator6 项(GraphicsPipelineConfigurator.cpp:115–120)无 read/write纯运行期装配对象

copy 语义分三类。

第一类是逐字段复制的子类拷贝构造:

  • Descriptor.cpp:26–32:Descriptor::Descriptor(const Descriptor& rhs, const CopyOp&) 逐字段复制 dstBinding、dstArrayElement、descriptorType
  • DescriptorBuffer.cpp:30–34:拷贝构造复制 bufferInfoList
  • DescriptorImage.cpp:29–33:拷贝构造复制 imageInfoList

第二类是禁用拷贝、改用 clone(const CopyOp&):

  • BufferInfo.h:33:BufferInfo(const BufferInfo&) = delete,同处还有带 in_offset/in_range 的四参数构造
  • ImageInfo.h:37:ImageInfo(const ImageInfo&) = delete,模板构造第 32 行带 in_imageLayout

第三类是 BindDescriptorSet(s) 的拷贝构造(.cpp:32–40、132–140),复制 dynamicOffsets 但不复制 _vulkanData 编译缓存,这是对的——缓存按 deviceID 重新 compile。第十章 10.x "字段清单被写了三遍"在 11.15.2 的表里得到描述符层的完整复现。

11.15.3 与前面章节的交叉引用

第八章 8.2.4/8.8.4 的 slot 2 与 view 槽采集是 11.15.1 的上游;第九章 9.11 的 compare 总账在 11.15.2 得到按类分组的对照表,第十章的三份字段清单问题是该表模板。


数字表与源码索引

本章核过的数字

数字值来源
include/vsg/state/ 头文件数 / 行数36 / 3,002wc -l include/vsg/state/*.h
src/vsg/state/ 实现文件数 / 行数35 / 7,076wc -l src/vsg/state/*.cpp
state 目录描述符相关文件 / 行数36 / 5,69018 头 1,560 + 18 实现 4,130
state 之外正面处理文件 / 行数16 / 5,744vk/ 8 个 1,971、utils/ 6 个 3,654、raytracing/ 2 个 119
全章正面处理文件 / 行数52 / 11,434wc -l 汇总
Descriptor 子类数(含基类)5Descriptor.h、DescriptorBuffer.h、DescriptorImage.h、DescriptorTexelBufferView.h、DescriptorAccelerationStructure.h
getNumDescriptors() 重写 / 调用4 / 1grep -rn;调用点仅 ResourceRequirements.cpp:177
assignTo 覆写数4(+ 基类默认)DescriptorBuffer.cpp:215、DescriptorImage.cpp:136、DescriptorTexelBufferView.cpp:68、DescriptorAccelerationStructure.cpp:53
全库 vkAllocateDescriptorSets / vkUpdateDescriptorSets 调用点1 / 1DescriptorSet.cpp:126、DescriptorSet.cpp:154
VkDescriptorSetAllocateInfo::descriptorSetCount1DescriptorSet.cpp:119
vkUpdateDescriptorSets 的 copyCount0DescriptorSet.cpp:154
dynamicOffsets 全库出现 / 生产者12 / 0grep -rn "dynamicOffsets"
VkDescriptorBindingFlagBits 有效位数4vulkan.h:420–423
全库 VK_DESCRIPTOR_BINDING_* 使用点0(不含定义与注释)grep -rn
DescriptorPool 池标志位1(FREE_DESCRIPTOR_SET_BIT)DescriptorPool.cpp:56
DescriptorPools 扩容默认值minimum_maxSets=0、maximum_maxSets=2048、scale_maxSets=2.0DescriptorPools.h:31–33
DescriptorBinding::descriptorCount 默认值0ShaderSet.h:47
ResourceRequirements 默认最小缓冲 / 设备内存 / staging各 16 MBResourceRequirements.h:86–89
numLightsRange / numShadowMapsRange / shadowMapSize{8,1024} / {0,64} / {2048,2048}ResourceRequirements.h:91–93
createSampedImageDescriptor 全库出现2(声明 + 定义,零调用)grep -rn
DescriptorPool::report / DescriptorPools::report 调用点0 / 0前者唯一调用在 #else 死代码 DescriptorPools.cpp:188
slot = 1 + firstSet 构造点5BindDescriptorSet.h:31/98/107/117、ViewDependentState.h:59 为同式另类
sizeof(Vk*Descriptor*) 系列以本机 SDK 为准vulkan.h:15 包含 <vulkan/vulkan.h>,11.11.3 给测量程序

源码索引(按文件分组,逐条 文件:行区间 + 该处结论)

include/vsg/state/Descriptor.h / src/vsg/state/Descriptor.cpp:h:25–49 基类三字段与 getNumDescriptors() 默认 1;cpp:19–32 两个构造;cpp:34–44 三字段 compare;cpp:46–62 descriptorType 的 1.1.11 门控;cpp:64–71 wds = {} 清零后只填四字段,不设 descriptorCount 与 dstSet。

include/vsg/state/DescriptorSetLayout.h / src/vsg/state/DescriptorSetLayout.cpp:h:23–25 三个类型别名;h:36 vk() 无判空;h:39–45 createFlags/bindings/bindingFlags;cpp:46–61 addBinding 用 binding 编号当 bindingFlags 下标;cpp:63–81 按类型累加池大小;cpp:83–94 compare 用 compare_value_container;cpp:96–142 read/write 只读写 4 字段、1.1.12 门控;cpp:144–147 compile 只判槽位空;cpp:153–179 Implementation 两个 bindingCount 独立取值、pNext 挂 flags;cpp:181–187 判空析构。

include/vsg/state/DescriptorSet.h / src/vsg/state/DescriptorSet.cpp:h:30–34 setLayout/descriptors;h:44 vk();h:67–85 Implementation;cpp:43–52 深比较;cpp:54–68 序列化两字段;cpp:70–87 compile 短路与四步顺序;cpp:89–102 release/vk() 无判空;cpp:108–130 vkAllocateDescriptorSets 唯一调用点、descriptorSetCount=1;cpp:132–139 vkFreeDescriptorSets 加锁;cpp:141–158 assign 与 vkUpdateDescriptorSets 唯一调用点、scratchMemory->release();cpp:160–167 recycle。

include/vsg/state/BindDescriptorSet.h / src/vsg/state/BindDescriptorSet.cpp:h:30–46、97–123 五个构造与 setLayouts[firstSet] 越界;h:48–53、125–130 字段与 dynamicOffsets;cpp:25–30、126–130 默认构造 slot;cpp:42–53、142–153 compare 漏 dynamicOffsets;cpp:55–93、155–193 read/write 含 dynamicOffsets 与 0.5.4 门控;cpp:95–111、195–207 compile 复用判据不完整;cpp:113–120、209–216 record 的 vkCmdBindDescriptorSets。

DescriptorBuffer / DescriptorImage / DescriptorTexelBufferView / DescriptorAccelerationStructure:DescriptorBuffer.cpp:103–213 上传(:110–122 四类型 switch + 静默 default、:134–139 alignment、:205–208 脏标记、:212 transferTask);:215–232 assignTo(:228 buffer 空指针);:234–237 getNumDescriptors;:75–101 read 丢 offset/range。DescriptorImage.cpp:106–134 compile(:117 连解两层无判空、:125 syncModifiedCount);:136–161 assignTo 判空对称;:163–166 getNumDescriptors;:168–184 三个工厂,:180 createSampedImageDescriptor 零调用;:66–104 read 硬编码 imageLayout。

include/vsg/state/BufferInfo.h:BufferInfo.h:48 的 copyDataToBuffer 与其第 52 行的重载把数据写进 VkBuffer;computeDataSize(:44)算尺寸。

同文件 BufferInfo.h:54 的 operator bool() 同时检查 buffer、data、range 三者;requiresCopy(:69)与 syncModifiedCounts(:75)只判 data。

include/vsg/state/ImageInfo.h:ImageInfo.h:26 默认 UNDEFINED,两个同类函数多判 imageView。

include/vsg/state/Sampler.h:Sampler.h:30 起是 VkSamplerCreateFlags 等 15 个字段,:48 的 vk() 直接取 _implementation[deviceID]->_sampler,无判空。

include/vsg/vk/DescriptorPool.h / src/vsg/vk/DescriptorPool.cpp:h:48–70 四本账;cpp:28–41 accumulateBindings;cpp:44–70 构造与 FREE_DESCRIPTOR_SET_BIT;cpp:80–137 allocateDescriptorSet(:92 兼容判据漏字段、:127–128 容量不足返回空、:131–134 异常不配平);cpp:139–150 freeDescriptorSet;cpp:152–184 available() 用全量 descriptorPoolSizes;cpp:186–206 used() 第 :200 行迭代器误用;cpp:208–254 report 零调用。

include/vsg/vk/DescriptorPools.h / src/vsg/vk/DescriptorPools.cpp:h:31–38 扩容三参数与 reserve 累计量;cpp:29–71 getDescriptorPoolSizesToUse;cpp:73–136 reserve;cpp:138–157 allocateDescriptorSet 空返回值未判;cpp:159–212 report,:181–192 #if 1 死代码;cpp:214–251 available/used/allocated。

src/vsg/vk/Context.cpp / src/vsg/vk/ResourceRequirements.cpp / 头文件:Context.cpp:90–138 构造与 descriptorPools 共享;:212–224 reserve;:227–230 allocateDescriptorSet 转调。ResourceRequirements.cpp:41–54 构造与 computeNumDescriptorSets;:57–64 computeDescriptorPoolSizes;:67–94 apply(ResourceHints);:159–163 采 slot;:165–173 set 去重;:175–188 registerDescriptor 无条件累加;:190–230 三个 apply 与四类型 switch。

include/vsg/utils/ShaderSet.h / src/vsg/utils/ShaderSet.cpp:h:40–55 DescriptorBinding 九字段;h:78–111 两个 CustomDescriptorSetBinding;cpp:140–153 ViewDependentStateBinding 三方法;cpp:498–512 descriptorSetRange;cpp:514–534 兼容判定 memcmp;cpp:536–556 createDescriptorSetLayout;cpp:558–585 compatiblePipelineLayout;cpp:587–609 createPipelineLayout 补空布局。

include/vsg/utils/GraphicsPipelineConfigurator.h / src/vsg/utils/GraphicsPipelineConfigurator.cpp:h:35–74 DescriptorConfigurator 接口;cpp:90–128 构造/compare/reset;cpp:130–261 六个 assign 入口,assigned 提前插入;cpp:263–291 assignDescriptor 稀疏 vector 与重复短路;cpp:293–350 assignDefaults 忽略返回值;cpp:730–784 FindInheritedState;cpp:786–818 init();cpp:849–960 copyTo(:851–891 DisableInheritedState 第 :885 行越界、:924–960 连续段合并)。src/vsg/utils/Builder.cpp:1466 是用户级装配入口的收尾:decorateAndCompileIfRequired 在第 1464 行完成装饰与编译后返回 subgraph。

include/vsg/state/ViewDependentState.h / src/vsg/state/ViewDependentState.cpp:h:50–93 BindViewDescriptorSets;cpp:71–101 ViewDescriptorSetLayout;cpp:105–110 默认构造 Inherit(2) 与 firstSet(0) 不配平;cpp:112–140 compare/read/write;cpp:142–154 compile/record;cpp:355–377 view 描述符装配只留最后一个 set;cpp:1056–1060 bindDescriptorSets 恒 0, nullptr 动态偏移。

include/vsg/core/compare.h / include/vsg/vk/vulkan.h / include/vsg/state/StateCommand.h:compare.h:46–50 compare_memory;:52–61 compare_region 的 memcmp;:63–77 compare_pointer_container;:80–87 compare_value_container。vulkan.h:15 包含系统头;:419–426 VkDescriptorBindingFlagBits 四个有效位。

可复现验证

以下命令都在仓库根目录执行,不依赖构建产物,输出可直接与本章表格核对。

验证 1:规模数字

wc -l include/vsg/state/*.h | tail -1          # 期望:3002 total
wc -l src/vsg/state/*.cpp | tail -1            # 期望:7076 total
wc -l include/vsg/vk/DescriptorPool.h include/vsg/vk/DescriptorPools.h src/vsg/vk/DescriptorPool.cpp src/vsg/vk/DescriptorPools.cpp
# 期望:74 / 66 / 254 / 251,合计 645

验证 2:两个 Vulkan 写入/分配调用点各自唯一

grep -rn "vkAllocateDescriptorSets\|vkUpdateDescriptorSets" src/vsg
# 期望:仅 DescriptorSet.cpp:126 与 DescriptorSet.cpp:154,各 1 行
grep -n "descriptorSetCount = 1\|0, nullptr" src/vsg/state/DescriptorSet.cpp
# 期望:119 行 descriptorSetCount=1;154 行 copyCount=0

验证 3:dynamicOffsets 零生产者、VK_DESCRIPTOR_BINDING_* 零使用

grep -rn "dynamicOffsets" --include=*.h --include=*.cpp . | grep -v docs/ | wc -l   # 期望:12
grep -rn "dynamicOffsets.push_back\|dynamicOffsets.resize\|dynamicOffsets =" --include=*.cpp src include
# 期望:0 行(拷贝构造与 read 之外没有赋值)
grep -rn "VK_DESCRIPTOR_BINDING_\|PARTIALLY_BOUND\|VARIABLE_DESCRIPTOR_COUNT" --include=*.h --include=*.cpp src include
# 期望:仅 vulkan.h:420-424 的定义 + DescriptorPool.cpp:56 的注释

验证 4:used() 的迭代器误用与 available() 的口径

sed -n '192,204p' src/vsg/vk/DescriptorPool.cpp
# 期望:第 200 行是 "used_itr += usedDescriptorCount;"(迭代器偏移,非字段累加)
grep -n "addDescriptorPoolSizes(descriptorPoolSizes\|addDescriptorPoolSizes(_recycled" src/vsg/vk/DescriptorPool.cpp
# 期望:175 / 181 两行,且没有 _availableDescriptorPoolSizes 出现在 available() 里

验证 5:零调用 API 与死代码

grep -rn "createSampedImageDescriptor" include src        # 期望:2 行(声明 + 定义)
grep -rn "report(" src/vsg/vk/DescriptorPool.cpp src/vsg/vk/DescriptorPools.cpp | head
# 期望:DescriptorPools.cpp:188 的 dp->report(...) 位于 #if 1 的 #else 分支
sed -n '181,192p' src/vsg/vk/DescriptorPools.cpp
# 期望:#if 1 ... #else ... dp->report(...) ... #endif
grep -rn "getNumDescriptors" --include=*.cpp src/vsg | wc -l   # 期望:5(4 定义 + 1 调用)

验证 6:slot 协议、越界与默认构造

grep -n "Inherit(1 + in_firstSet)\|Inherit(1), // slot 1\|Inherit(2), // slot 2" include/vsg/state/BindDescriptorSet.h src/vsg/state/ViewDependentState.cpp
# 期望:BindDescriptorSet.h:31/98/107/117 与 ViewDependentState.cpp:106
sed -n '880,890p' src/vsg/utils/GraphicsPipelineConfigurator.cpp
# 期望:循环 for (set = bds.firstSet; set < end_set; ++set) 无 descritorSets.size() 上界
grep -n "setLayouts\[in_firstSet\]" include/vsg/state/BindDescriptorSet.h   # 期望:121 行,无边界检查

验证 7:纹素视图的双重编译与数据指针

grep -c "compile(context)" src/vsg/state/DescriptorTexelBufferView.cpp
# 期望:2(compile 与 assignTo 各一次)
grep -n "pTexelBufferView" src/vsg/state/DescriptorTexelBufferView.cpp
# 期望:仅第 74 行 wds.pTexelBufferView 一处

验证 8:池的两本账各在何处读写

grep -n "accumulateBindings(_recycled\|accumulateBindings(_available" src/vsg/vk/DescriptorPool.cpp
# 期望:96 行扣减、147 行加回,均作用于 _recycledDescriptorPoolSizes
grep -n "_availableDescriptorPoolSizes" src/vsg/vk/DescriptorPool.cpp | head -3
# 期望:49 / 112 / 131,只减不增

验证 9:越界循环与模板构造默认布局

grep -n "end_set" src/vsg/utils/GraphicsPipelineConfigurator.cpp
# 期望:884 行计算、885 行循环只判 end_set
grep -n "in_imageLayout" include/vsg/state/ImageInfo.h | tail -2
# 期望:32/33 行模板构造默认 SHADER_READ_ONLY_OPTIMAL

陷阱表与批判性结论

五列陷阱表

#陷阱触发条件后果规避
1DescriptorSet::compile 按槽位是否为空短路编译后改 descriptors 或 Data 内容不重分配、不重 vkUpdateDescriptorSets,GPU 看旧值显式 release(deviceID) 后重编译,或走 TransferTask 刷数据
2DescriptorSetLayout::addBinding 用 binding 编号当 bindingFlags 下标binding 编号不连续且 flags != 0bindingFlagsCreateInfo.bindingCount 与 layoutInfo.bindingCount 不等,验证层报错binding 编号连续,或 bindingFlags 按 bindings 下标索引
3DescriptorBuffer::assignTo 第 228 行 data->buffer->vk() 无判空totalSize == 0 或 reserve 失败只 warn空指针解引用,编译期崩溃保证每个 BufferInfo 在 assignTo 前 buffer 非空
4BindDescriptorSet 便捷构造以 in_firstSet 索引 setLayouts[]firstSet >= setLayouts.size()越界读 ref_ptr,UB构造前判 firstSet < setLayouts.size()
5DescriptorImage::read 硬编码 imageLayout序列化 DEPTH_STENCIL_READ_ONLY_OPTIMAL 等布局读回变 SHADER_READ_ONLY_OPTIMAL,采样静默错序列化格式写入 imageLayout,或读回后手工复位
6DescriptorTexelBufferView 双重 compile每个 BufferView 经 DescriptorSet::compile 再经 assignTo一轮编译被 compile 两次,状态变更时两次结果可能不一致移除 assignTo 内的 compile,只保留基类路径
7DescriptorSetLayout::compare 用 memcmp 比整个结构体反序列化对象、手工填结构体、SDK 版本变化padding 与 pImmutableSamplers 进判等,兼容判定静默错read 里显式置 pImmutableSamplers = nullptr
8DescriptorPool::used() 第 200 行迭代器误用DescriptorPools::used 累加多个池同类型已用量永不累加,report 数据错改为 used_itr->descriptorCount += usedDescriptorCount
9available() 并入初始全量而非剩余量池已分配大量 set 后再次 reserve富余判断偏乐观,少建池,分配返回空available() 改用 _availableDescriptorPoolSizes
10回收判据只比 bindings两布局 bindings 相同但 createFlags/bindingFlags 不同复用不兼容的 VkDescriptorSet兼容判据补比两个字段
11池分配失败统一返回空 ref_ptr容量不足或 vkAllocateDescriptorSets 失败DescriptorSet.cpp:85 空指针解引用在 compile 判空抛异常,异常路径回滚计数
12registerDescriptor 无条件累加 descriptorTypeMap同一 Descriptor 被多个 set 共享池容量虚高,与 set 数口径不一致把累加移入 descriptors.insert 成功分支
13descriptorCount 三套口径无校验数组描述符 descriptorCount > 1 而只给一份数据layout 按 N 扣池、写入按 1,读未定义描述符保证容器 size() 等于 descriptorCount
14BindDescriptorSet(s)::compare 漏 dynamicOffsets两个仅动态偏移不同的命令进 SharedObjects判等合并,动态偏移静默丢失compare 补 compare_value_container
15两个 compile 只判非零与 size替换 descriptorSet 指针且 size 不变不重编译,record 仍绑旧句柄比对缓存指针或 release 后强制重编译
16dynamicOffsets 全库零生产者使用 UNIFORM_BUFFER_DYNAMIC 并期望库自动收集帧期传 0 个偏移,动态描述符读错位置用户自行 push_back 并对齐 minUniformBufferOffsetAlignment
17BufferInfo 与 ImageInfo 判空标准不对称requiresCopy/syncModifiedCounts 只判 data,operator bool() 多判字段DescriptorBuffer::assignTo 解引用空 buffer,而图像路径允许部分为空统一 Info 类的判空合同,写入前显式校验
18BindViewDescriptorSets 默认构造 Inherit(2) 配 firstSet(0)默认构造或从文件读回同 firstSet 对应 slot 1 与 slot 2统一走带参构造,read 后按 firstSet 重算 slot
19assignDefaults 忽略 assignDescriptor 返回值重复 binding 导致返回 false仍 assigned.insert 并置 assignedDefault = true,缺 binding 无报错判返回值后再标记
20DisableInheritedState::apply(BindDescriptorSets&) 循环无上界继承 set 范围末端超过本地 sizedescritorSets[set] 越界写,UB循环条件补 && set < descritorSets.size()

三条批判性结论

第一,"一次性写入"不是 Vulkan 的限制,而是编译拓扑自己造成的边界。 全库只有 DescriptorSet.cpp:154 一处 vkUpdateDescriptorSets,DescriptorSet::compile(DescriptorSet.cpp:72)以 _implementation[deviceID] 是否为空为唯一失效判据,assign 只在 compile 里被调一次;DescriptorPool.cpp:56 注释里提到却始终没有实现的 UPDATE_AFTER_BIND_BIT_EXT,以及库内零使用的 VK_DESCRIPTOR_BINDING_* 四个 flag,说明绑定后更新这条路没有打开。于是"改 Data 后 GPU 能否看到"的答案是"没有任何调用点会再去写":DescriptorBuffer.cpp:205 那套 getModifiedCount / copiedModifiedCounts[deviceID] 脏标记在首次编译后随 compile 短路一起失效。它与第九章 9.17.1 的 _implementation[viewID] 槽位判空同构,收益是编译期零比较、零脏标记,代价是所有"编译后修改"约束落在使用者自律上,库自己靠重建整条链绕开限制。

第二,两套容量口径与三份字段清单,暴露的是同一个问题:描述符体系没有"单一真相"。 池要建多大由 ResourceRequirements.cpp:57–64 按 Descriptor 的 getNumDescriptors() 累加 descriptorTypeMap;分配扣多少由 DescriptorPool.cpp:110 调 getDescriptorPoolSizes 按 bindings 的 descriptorCount 累加;写入多少由各 assignTo 取容器 size()。三份独立代码零一致性校验,registerDescriptor(ResourceRequirements.cpp:177)又在去重前无条件累加。与之平行的是 compare / read / write 三份清单:DescriptorSetLayout.cpp:91 用 memcmp 把 pImmutableSamplers 与 padding 一起比,read(:105–112)只读写四字段;BindDescriptorSet.cpp:52 不比 dynamicOffsets 而 read(:72)读它;DescriptorImage.cpp:86 硬编码 imageLayout。判等键不只服务 SharedObjects,还承担 ShaderSet.cpp:533 的兼容判定、DescriptorPool.cpp:92 的回收复用、GraphicsPipelineConfigurator.cpp:742 的继承集识别,一处 memcmp 偏差会沿三跳传播到结构性决策。修法是写逐字段比较器、让 read 初始化未序列化字段、把两个池大小函数合并。

第三,池的统计与复用层是本章最脆弱的一环,硬缺陷密集且互相掩盖。 DescriptorPool.h:48–70 的四本账里,available()(DescriptorPool.cpp:175)并入不可变初始全量而非剩余量,used()(:200)把迭代器当整数累加,allocateDescriptorSet(:92)回收判据只比 bindings 且用 memcmp,freeDescriptorSet(:145)只增 _availableDescriptorSet 不回补 _availableDescriptorPoolSizes,异常路径(:131–134)先扣计数再构造且不回滚。叠加后没有一层能给出可信容量:DescriptorPools::reserve(DescriptorPools.cpp:95)拿虚高值判富余,report(:202–203)拿错误值打印,而两个 report 一个在 #if 1 的 #else 死代码里、一个零调用。观测入口全部失效,只能等 allocateDescriptorSet 返回空 ref_ptr 才暴露,而空值又在 DescriptorSet.cpp:85 被直接解引用。收敛方向是把四本账减成两本、让三个统计共用一个数据源、把分配失败变成带回滚的异常。单窗口、set 数固定的常规场景里这些统计函数基本不触发,正确性依赖部署拓扑而非代码保证,与第九章 9.17.1 对管线复用的判语一致。

第四,未被接上的观测与便利 API 说明"能表达"与"可用"是两件事。 createSampedImageDescriptor(DescriptorImage.cpp:180,全库只有声明与定义两行,名字还把 Sampled 拼成 Samped)、DescriptorPool::report(DescriptorPool.cpp:208,唯一调用点在 DescriptorPools.cpp:188 的 #else 分支,被 :181 的 #if 1 挡掉)、DescriptorPools::report(DescriptorPools.cpp:159,无调用者)都有完整函数体却零调用。dynamicOffsets 同理:BindDescriptorSet.h:53/130 声明、.cpp:72/91/172/191 序列化、.cpp:119/215 透传给 vkCmdBindDescriptorSets,却没有任何 push_back/resize/assign 生产它——GraphicsPipelineConfigurator.cpp:241 用的是静态 descriptorBinding.data。数据模型允许表达动态偏移与导出池统计,但编译拓扑只接通了"描述→布局→一次性写入→帧期绑定"主干。代价是遇到池容量不可信、动态描述符读错位置时没有观测出口与配置入口;收益是主干零分支、编译期零比较。判断 API 是否可用,grep 调用点比阅读函数体可靠。


下章预告

本章结束。下一章精确对齐 README 第 12 章标题「编译遍历:CompileTraversal 与 CompileManager」,要回答本章留下的六个具体问题:

  • DescriptorSet::compile(DescriptorSet.cpp:70–87)由遍历中哪个 apply 调用?CompileTraversal 的分派顺序如何保证 11.3.2 给出的"布局先于分配、描述符先于写入"?
  • Context::reserve(Context.cpp:212–224)与 DescriptorPools::reserve(DescriptorPools.cpp:73–136)何时被调用?第六章 6.x 的 CompileTraversal::add 里 context->reserve(requirements) 与 CollectResourceRequirements(ResourceRequirements.cpp:101–146)收集的是同一份对象吗,多线程编译时每个 Context 拿副本还是共享引用?
  • 11.7.2 的空返回值链、11.8.3 的兜底新建池、11.9.3 的容量低估,在 CompileManager::compileTask(CompileManager.cpp:401)的多线程路径下会被并发 allocateDescriptorSet 放大吗?DescriptorPool::mutex(DescriptorPool.h:54)与 std::list descriptorPools 的访问粒度配平吗?
  • 第九章 9.12 的两条 resize 重建路径、WindowResizeHandler::release(viewID) 与 DescriptorSet::release(deviceID)(DescriptorSet.cpp:89–97)如何配平?重建管线时描述符集是复用还是整批回收进 _recyclingList(DescriptorPool.cpp:145)?
  • BindViewDescriptorSets(ViewDependentState.cpp:142–154)由 ViewDependentState::traverse 直接录制、不走 StateGroup 的 push(第八章 8.2.4),CompileTraversal 的 View 分支如何准备 viewDependentState 与 viewID?
  • 阴影贴图描述符的编译时机由谁驱动?ViewDependentState.cpp:355 处 depthImageView 的 subresourceRange 配好第 358 行的 VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL,第 370–377 行只把最后一个非空 set 留给 descriptorSet。
  • 反复出现的"一次性写入"与"池一次建够",在 CompileManager 的多帧在飞、PagedLOD 增量编译下如何维持?ResourceRequirements::containsPagedLOD(ResourceRequirements.h:73)与 DynamicData(:63)是否会让 reserve 被二次调用,11.8.1 的 reserve_* 累计量"只增不减、用后清零"还配平吗?

编译如何作为独立阶段收敛,是第十二章的主线。