《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.h | 51 | 基类三字段、assignTo、getNumDescriptors,11.1 |
include/vsg/state/DescriptorSetLayout.h | 85 | 四个类型别名、bindings/bindingFlags,11.2 |
include/vsg/state/DescriptorSet.h | 97 | setLayout/descriptors 与 Implementation,11.3 |
include/vsg/state/BindDescriptorSet.h | 166 | 两个绑定命令、五个构造、VulkanData,11.10 |
include/vsg/state/DescriptorBuffer.h | 53 | BufferInfoList、四个构造,11.4 |
include/vsg/state/DescriptorImage.h | 59 | ImageInfoList、三个工厂函数,11.5 |
include/vsg/state/DescriptorTexelBufferView.h | 47 | texelBufferViews 与内联 getNumDescriptors,11.6 |
include/vsg/state/BufferInfo.h | 106 | VkDescriptorBufferInfo 的四个字段与脏标记,11.4、11.16 |
include/vsg/state/ImageInfo.h | 107 | VkDescriptorImageInfo 的三字段、FormatTraits,11.5 |
include/vsg/state/Sampler.h | 78 | VkSamplerCreateInfo 的 15 个字段,11.5 |
include/vsg/state/ViewDependentState.h | 182 | BindViewDescriptorSets、ViewDescriptorSetLayout,11.15 |
include/vsg/state/ResourceHints.h | 99 | descriptorPoolSizes/numDescriptorSets,11.9 |
include/vsg/state/StateCommand.h | 45 | slot 字段与默认 Inherit(0),11.10 |
include/vsg/state/Buffer.h | 85 | 底层 VkBuffer 封装,11.4 上传路径 |
include/vsg/state/BufferView.h | 62 | 纹素缓冲视图,11.6 |
include/vsg/state/Image.h | 94 | 底层 VkImage,11.5 上传路径 |
include/vsg/state/ImageView.h | 70 | VkImageView,11.5 |
include/vsg/state/PipelineLayout.h | 74 | setLayouts[] 与 vk(deviceID),11.10、11.12 |
以上 18 个头文件合计 1,560 行。
文件(src/vsg/state/) | 行数 | 本章角色 |
|---|---|---|
src/vsg/state/Descriptor.cpp | 71 | compare/read/write/assignTo,11.1 |
src/vsg/state/DescriptorSetLayout.cpp | 187 | addBinding、池大小累加、Implementation,11.2 |
src/vsg/state/DescriptorSet.cpp | 167 | vkAllocateDescriptorSets、vkUpdateDescriptorSets,11.3 |
src/vsg/state/BindDescriptorSet.cpp | 216 | 两个类的 compile/record,11.10 |
src/vsg/state/DescriptorBuffer.cpp | 245 | 缓冲上传与 pBufferInfo 填充,11.4 |
src/vsg/state/DescriptorImage.cpp | 184 | 图像上传与 pImageInfo 填充,11.5 |
src/vsg/state/DescriptorTexelBufferView.cpp | 81 | pTexelBufferView 填充,11.6 |
src/vsg/state/BufferInfo.cpp | 293 | copyDataToBuffer、computeDataSize,11.4、11.16 |
src/vsg/state/ImageInfo.cpp | 426 | computeNumMipMapLevels、getFormatTraits,11.5 |
src/vsg/state/Sampler.cpp | 120 | vkCreateSampler 与序列化,11.5 |
src/vsg/state/ViewDependentState.cpp | 1060 | view 槽装配与 bindDescriptorSets,11.15 |
src/vsg/state/ResourceHints.cpp | 148 | hints 的 read/write,11.9 |
src/vsg/state/StateCommand.cpp | 45 | slot 的序列化,11.10 |
src/vsg/state/Buffer.cpp | 184 | reserve/compile/bind,11.4 |
src/vsg/state/BufferView.cpp | 85 | vkCreateBufferView,11.6 |
src/vsg/state/Image.cpp | 242 | VkImage 创建与 mipmap,11.5 |
src/vsg/state/ImageView.cpp | 205 | VkImageView 创建,11.5 |
src/vsg/state/PipelineLayout.cpp | 171 | vkCreatePipelineLayout、空布局写 0,11.12 |
以上 18 个实现文件合计 4,130 行。state 目录描述符相关合计 36 个文件、5,690 行。
| 文件(state 之外) | 行数 | 本章角色 |
|---|---|---|
include/vsg/vk/DescriptorPool.h | 74 | 单池四本账与 recyclingList,11.7 |
include/vsg/vk/DescriptorPools.h | 66 | 扩容三参数与 reserve 累计量,11.8 |
include/vsg/vk/Context.h | 160 | reserve/allocateDescriptorSet 声明,11.9 |
include/vsg/vk/ResourceRequirements.h | 149 | 计数容器与访问者声明,11.9 |
src/vsg/vk/DescriptorPool.cpp | 254 | vkCreateDescriptorPool、分配/回收/统计,11.7 |
src/vsg/vk/DescriptorPools.cpp | 251 | reserve、getDescriptorPoolSizesToUse,11.8 |
src/vsg/vk/Context.cpp | 599 | Context::reserve/allocateDescriptorSet 接线,11.9 |
src/vsg/vk/ResourceRequirements.cpp | 418 | registerDescriptor 与两个 compute,11.9 |
include/vsg/utils/ShaderSet.h | 228 | DescriptorBinding 九字段,11.12 |
include/vsg/utils/GraphicsPipelineConfigurator.h | 173 | DescriptorConfigurator 接口,11.13 |
include/vsg/utils/Builder.h | 165 | 上层装配入口声明,11.14 |
src/vsg/utils/ShaderSet.cpp | 609 | createDescriptorSetLayout/createPipelineLayout,11.12 |
src/vsg/utils/GraphicsPipelineConfigurator.cpp | 1013 | 装配、继承集判定、copyTo,11.13、11.14 |
src/vsg/utils/Builder.cpp | 1466 | 面向用户的描述符创建入口,11.14 |
include/vsg/raytracing/DescriptorAccelerationStructure.h | 49 | 第五个 Descriptor 子类,11.6 |
src/vsg/raytracing/DescriptorAccelerationStructure.cpp | 70 | pNext 链与 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 答案骨架
先把结论列在这里,后面逐条用源码展开,读者可以带着结论去核对。标注【硬缺陷】的是有明确触发条件与后果的实现问题,标注【设计取舍】的是代价可接受但边界要写清的选择,标注【接口边界】的是容易被误读的语义。
| # | 结论 | 主要证据 | 性质 |
|---|---|---|---|
| 1 | slot = 1 + firstSet 由五个构造点写死,BindViewDescriptorSets 默认构造却另用 Inherit(2) 且 firstSet = 0,同一个 firstSet 对应两个 slot,双份真相 | BindDescriptorSet.h:31/98/107/117、ViewDependentState.cpp:106/108 | 【硬缺陷】 |
| 2 | DescriptorSet::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 | 【设计取舍】 |
| 4 | DescriptorPool::used() 把迭代器当整数累加:used_itr += usedDescriptorCount,本应写 used_itr->descriptorCount += ...,已有同类型条目永远不更新 | DescriptorPool.cpp:200 | 【硬缺陷】 |
| 5 | DescriptorPool::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 | 【硬缺陷】 |
| 7 | BindDescriptorSet/BindDescriptorSets 的 compare 不比 dynamicOffsets,read/write 却序列化它;全库 dynamicOffsets 只有 12 处出现,零处 push_back/resize | BindDescriptorSet.cpp:52/72/91/152/172/191 | 【硬缺陷】 |
| 8 | 两个 compile 的复用判据只判"句柄非零 + 容器 size",不比内容;替换 descriptorSet 或 descriptorSets[i] 后不重编译,帧期仍绑旧句柄 | BindDescriptorSet.cpp:100/200 | 【硬缺陷】 |
| 9 | registerDescriptor 无条件先累加 descriptorTypeMap 再做 descriptors 去重;池容量按 descriptor 侧统计,分配扣减按 layout 侧 getDescriptorPoolSizes,两套口径不校验一致性 | ResourceRequirements.cpp:177/179、DescriptorPool.cpp:110、DescriptorSetLayout.cpp:63–81 | 【硬缺陷】 |
| 10 | DescriptorSetLayout 的 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–237 | bufferInfoList.size() | 池容量统计 |
DescriptorImage.cpp:163–166 | imageInfoList.size() | 池容量统计 |
DescriptorTexelBufferView.h:34 | texelBufferViews.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);
}
}
三份清单的差别列成表:
| 字段 | compare | read | write | 说明 |
|---|---|---|---|---|
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 |
|---|---|---|---|
DescriptorBuffer | bufferInfoList.size() | pBufferInfo | 是(DescriptorBuffer.cpp:220) |
DescriptorImage | imageInfoList.size() | pImageInfo | 是(DescriptorImage.cpp:142) |
DescriptorTexelBufferView | texelBufferViews.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::computeDescriptorPoolSizes | descriptorTypeMap(按 Descriptor 对象累加 getNumDescriptors()) | 否 | 否 |
DescriptorPool::allocateDescriptorSet 扣减 | getDescriptorPoolSizes(按 DescriptorSetLayout::bindings 累加 descriptorCount) | 是 | 否 |
computeNumDescriptorSets | descriptorSets.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::descriptorCount | DescriptorBuffer.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 覆盖 | 分叉 |
|---|---|---|---|
Descriptor | 3 字段 | 3 字段,descriptorType 门控 1.1.11(Descriptor.cpp:52/61) | 旧文件靠子类默认构造兜底 |
DescriptorSetLayout | createFlags + bindings(memcmp)+ bindingFlags(DescriptorSetLayout.cpp:90–93) | 4 字段门控 1.1.12,不读写 pImmutableSamplers(:105–142) | memcmp 与序列化不同步 |
DescriptorBuffer | bufferInfoList 深比较(:72) | 只读写 data(:75–101) | 反序列化后 compare 必不等 |
DescriptorImage | imageInfoList 深比较(:63) | 只读写 sampler+data,硬编码 imageLayout(:66–104) | 丢 layout 与重建 ImageView |
DescriptorTexelBufferView | texelBufferViews 深比较(:42) | 整个 list(:44–56) | 无 |
DescriptorSet | setLayout + descriptors(:50–51) | 两字段(:54–68) | 无 |
BindDescriptorSet(s) | 4 项,漏 dynamicOffsets(BindDescriptorSet.cpp:49–52/149–152) | 5 项,含 dynamicOffsets(:72/91/172/191) | 去重丢动态偏移 |
BindViewDescriptorSets | 3 项(ViewDependentState.cpp:119–121) | 3 项(:124–140) | slot 不落 read 的本类字段 |
DescriptorConfigurator | 6 项(GraphicsPipelineConfigurator.cpp:115–120) | 无 read/write | 纯运行期装配对象 |
copy 语义分三类。
第一类是逐字段复制的子类拷贝构造:
Descriptor.cpp:26–32:Descriptor::Descriptor(const Descriptor& rhs, const CopyOp&)逐字段复制dstBinding、dstArrayElement、descriptorTypeDescriptorBuffer.cpp:30–34:拷贝构造复制bufferInfoListDescriptorImage.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,002 | wc -l include/vsg/state/*.h |
src/vsg/state/ 实现文件数 / 行数 | 35 / 7,076 | wc -l src/vsg/state/*.cpp |
| state 目录描述符相关文件 / 行数 | 36 / 5,690 | 18 头 1,560 + 18 实现 4,130 |
| state 之外正面处理文件 / 行数 | 16 / 5,744 | vk/ 8 个 1,971、utils/ 6 个 3,654、raytracing/ 2 个 119 |
| 全章正面处理文件 / 行数 | 52 / 11,434 | wc -l 汇总 |
Descriptor 子类数(含基类) | 5 | Descriptor.h、DescriptorBuffer.h、DescriptorImage.h、DescriptorTexelBufferView.h、DescriptorAccelerationStructure.h |
getNumDescriptors() 重写 / 调用 | 4 / 1 | grep -rn;调用点仅 ResourceRequirements.cpp:177 |
assignTo 覆写数 | 4(+ 基类默认) | DescriptorBuffer.cpp:215、DescriptorImage.cpp:136、DescriptorTexelBufferView.cpp:68、DescriptorAccelerationStructure.cpp:53 |
全库 vkAllocateDescriptorSets / vkUpdateDescriptorSets 调用点 | 1 / 1 | DescriptorSet.cpp:126、DescriptorSet.cpp:154 |
VkDescriptorSetAllocateInfo::descriptorSetCount | 1 | DescriptorSet.cpp:119 |
vkUpdateDescriptorSets 的 copyCount | 0 | DescriptorSet.cpp:154 |
dynamicOffsets 全库出现 / 生产者 | 12 / 0 | grep -rn "dynamicOffsets" |
VkDescriptorBindingFlagBits 有效位数 | 4 | vulkan.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.0 | DescriptorPools.h:31–33 |
DescriptorBinding::descriptorCount 默认值 | 0 | ShaderSet.h:47 |
ResourceRequirements 默认最小缓冲 / 设备内存 / staging | 各 16 MB | ResourceRequirements.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 构造点 | 5 | BindDescriptorSet.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
陷阱表与批判性结论
五列陷阱表
| # | 陷阱 | 触发条件 | 后果 | 规避 |
|---|---|---|---|---|
| 1 | DescriptorSet::compile 按槽位是否为空短路 | 编译后改 descriptors 或 Data 内容 | 不重分配、不重 vkUpdateDescriptorSets,GPU 看旧值 | 显式 release(deviceID) 后重编译,或走 TransferTask 刷数据 |
| 2 | DescriptorSetLayout::addBinding 用 binding 编号当 bindingFlags 下标 | binding 编号不连续且 flags != 0 | bindingFlagsCreateInfo.bindingCount 与 layoutInfo.bindingCount 不等,验证层报错 | binding 编号连续,或 bindingFlags 按 bindings 下标索引 |
| 3 | DescriptorBuffer::assignTo 第 228 行 data->buffer->vk() 无判空 | totalSize == 0 或 reserve 失败只 warn | 空指针解引用,编译期崩溃 | 保证每个 BufferInfo 在 assignTo 前 buffer 非空 |
| 4 | BindDescriptorSet 便捷构造以 in_firstSet 索引 setLayouts[] | firstSet >= setLayouts.size() | 越界读 ref_ptr,UB | 构造前判 firstSet < setLayouts.size() |
| 5 | DescriptorImage::read 硬编码 imageLayout | 序列化 DEPTH_STENCIL_READ_ONLY_OPTIMAL 等布局 | 读回变 SHADER_READ_ONLY_OPTIMAL,采样静默错 | 序列化格式写入 imageLayout,或读回后手工复位 |
| 6 | DescriptorTexelBufferView 双重 compile | 每个 BufferView 经 DescriptorSet::compile 再经 assignTo | 一轮编译被 compile 两次,状态变更时两次结果可能不一致 | 移除 assignTo 内的 compile,只保留基类路径 |
| 7 | DescriptorSetLayout::compare 用 memcmp 比整个结构体 | 反序列化对象、手工填结构体、SDK 版本变化 | padding 与 pImmutableSamplers 进判等,兼容判定静默错 | read 里显式置 pImmutableSamplers = nullptr |
| 8 | DescriptorPool::used() 第 200 行迭代器误用 | DescriptorPools::used 累加多个池 | 同类型已用量永不累加,report 数据错 | 改为 used_itr->descriptorCount += usedDescriptorCount |
| 9 | available() 并入初始全量而非剩余量 | 池已分配大量 set 后再次 reserve | 富余判断偏乐观,少建池,分配返回空 | available() 改用 _availableDescriptorPoolSizes |
| 10 | 回收判据只比 bindings | 两布局 bindings 相同但 createFlags/bindingFlags 不同 | 复用不兼容的 VkDescriptorSet | 兼容判据补比两个字段 |
| 11 | 池分配失败统一返回空 ref_ptr | 容量不足或 vkAllocateDescriptorSets 失败 | DescriptorSet.cpp:85 空指针解引用 | 在 compile 判空抛异常,异常路径回滚计数 |
| 12 | registerDescriptor 无条件累加 descriptorTypeMap | 同一 Descriptor 被多个 set 共享 | 池容量虚高,与 set 数口径不一致 | 把累加移入 descriptors.insert 成功分支 |
| 13 | descriptorCount 三套口径无校验 | 数组描述符 descriptorCount > 1 而只给一份数据 | layout 按 N 扣池、写入按 1,读未定义描述符 | 保证容器 size() 等于 descriptorCount |
| 14 | BindDescriptorSet(s)::compare 漏 dynamicOffsets | 两个仅动态偏移不同的命令进 SharedObjects | 判等合并,动态偏移静默丢失 | compare 补 compare_value_container |
| 15 | 两个 compile 只判非零与 size | 替换 descriptorSet 指针且 size 不变 | 不重编译,record 仍绑旧句柄 | 比对缓存指针或 release 后强制重编译 |
| 16 | dynamicOffsets 全库零生产者 | 使用 UNIFORM_BUFFER_DYNAMIC 并期望库自动收集 | 帧期传 0 个偏移,动态描述符读错位置 | 用户自行 push_back 并对齐 minUniformBufferOffsetAlignment |
| 17 | BufferInfo 与 ImageInfo 判空标准不对称 | requiresCopy/syncModifiedCounts 只判 data,operator bool() 多判字段 | DescriptorBuffer::assignTo 解引用空 buffer,而图像路径允许部分为空 | 统一 Info 类的判空合同,写入前显式校验 |
| 18 | BindViewDescriptorSets 默认构造 Inherit(2) 配 firstSet(0) | 默认构造或从文件读回 | 同 firstSet 对应 slot 1 与 slot 2 | 统一走带参构造,read 后按 firstSet 重算 slot |
| 19 | assignDefaults 忽略 assignDescriptor 返回值 | 重复 binding 导致返回 false | 仍 assigned.insert 并置 assignedDefault = true,缺 binding 无报错 | 判返回值后再标记 |
| 20 | DisableInheritedState::apply(BindDescriptorSets&) 循环无上界 | 继承 set 范围末端超过本地 size | descritorSets[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_*累计量"只增不减、用后清零"还配平吗?
编译如何作为独立阶段收敛,是第十二章的主线。