《VulkanSceneGraph 1.1.16 源码深度解析》第五章 数据对象:从 Data 到 VkBuffer/VkImage 的完整链路
本章要回答一个问题:你写的那个
vsg::vec3Array,是怎么变成 GPU 上一块VkDeviceMemory里的一段字节的。这个问题看起来平淡,但它是 VSG 里唯一一条"从 C++ 内存直通显存"的通道。这条通道上有 11 个类型、3 条互斥的路径、2 个内存池、1 个后台传输任务,以及至少 4 处"靠枚举值算术推断格式"的隐式约定。任何一处理解错,症状都不是崩溃,而是纹理颜色偏了、顶点错位了、或者帧率莫名其妙掉了 30%。
5.0 度量:这条链路上有多少东西
先把规模摊开。本章核心文件 14 个,合计 3,486 行:
| 分组 | 文件(行数) | 小计 |
|---|---|---|
| 数据抽象 | core/Data.h(241) core/Data.cpp(228) core/Array.h(441) Array2D.h(426) Array3D.h(431) core/Value.h(272) | 2,039 |
| 缓冲 | state/Buffer.h(85) Buffer.cpp(184) BufferInfo.h(106) BufferInfo.cpp(293) | 668 |
| 图像 | state/Image.h(94) Image.cpp(242) ImageInfo.h(107) ImageInfo.cpp(426) | 869 |
| 内存池 | vk/MemoryBufferPools.h(80) MemoryBufferPools.cpp(396) | 476 |
| 传输 | app/TransferTask.h(124) TransferTask.cpp(880) | 1,004 |
但真正决定正确性的代码只有大约 260 行:Image::Image(Data) 的 30 行、_transferImageInfo 的 55 行、_transferBufferInfos 的 60 行、reserveBuffer 的 60 行、transferImageData 的 55 行。3,486 行里 92% 是脚手架。
Data 家族有 150 个具名类型(41 个 Array + 34 个 Array2D + 25 个 Array3D + 50 个 Value),全部由 4 个类模板 + 4 个宏生成:
$ grep -o "VSG_array([a-zA-Z0-9_]*" include/vsg/core/Array.h | grep -v "^N" | wc -l
41
// include/vsg/core/Array.h:25
#define VSG_array(N, T) \
using N = Array<T>; \
template<> \
constexpr const char* type_name<N>() noexcept { return "vsg::" #N; } \
template<> \
constexpr const char* type_name<const N>() noexcept { return "vsg::" #N; }
这个宏只做三件事:起别名、给 RTTI 注册名字、给 const 版本也注册名字。它不生成任何新代码——Array<vec3> 和 vec3Array 是同一个类型。所以调试器里看到的类型名是 vsg::Array<vsg::t_vec3<float>>,而 type_name 特化只是让序列化能写出人类可读的字符串。
Array<T> 本身只有 3 个私有成员:
// include/vsg/core/Array.h:407-410
value_type* _data;
uint32_t _size;
ref_ptr<Data> _storage;
_storage 是"我不拥有这块内存,它属于另一个 Data"的标记(子数组场景);_data 是实际起点;_size 是元素个数。没有 offset、没有 allocator 类型——那些都在继承来的 Data::properties 里(properties.stride、properties.allocatorType)。
所以一个 vec3Array 的对象头是 Object(24 字节)+ Data::properties(约 20 字节)+ _modifiedCount(4)+ 三个成员(20)≈ 70 字节,而它承载的数据可以是 400 万个顶点、48 MB。对象头与负载比约 1 : 700,000。
现在开始正题。
5.1 Data 的七个纯虚函数:为什么必须是七个
Data 是一个只有 7 个纯虚函数(外加 4 个非纯虚的尺寸查询)的抽象基类。这个数字不是随意定的,它精确对应了"把一段 CPU 内存描述成 GPU 资源"所需要的最小信息集。
// include/vsg/core/Data.h:173-177
virtual size_t valueSize() const = 0;
virtual size_t valueCount() const = 0;
virtual bool dataAvailable() const = 0;
virtual size_t dataSize() const = 0;
// ... 中间两对 dataPointer、dataRelease、dimensions
从 Data.h:173 排到 :191,一共 13 个纯虚函数:valueSize、valueCount、dataAvailable、dataSize、两对 dataPointer、dataRelease、dimensions、width/height/depth。
但去掉 const/非 const 配对(4 个 dataPointer 其实是 2 对)和三个纯转发(width/height/depth 在 Array 里都是常量 0 或 1),真正的抽象契约是 7 条:
| 契约 | 函数 | 谁在读它 |
|---|---|---|
| 一个元素多少字节 | valueSize() | BufferInfo::copyDataToStagingBuffer 算对齐、_transferImageInfo 算补齐 |
| 一共多少个元素 | valueCount() | _transferData 预算 staging 大小、_transferImageInfo 算补齐循环次数 |
| 数据现在在不在 | dataAvailable() | 分页加载、STATIC_DATA_UNREF_AFTER_TRANSFER 之后 |
| 一共多少字节 | dataSize() | reserveBuffer 的 totalSize、memcpy 的 count |
| 数据在哪 | dataPointer() | 所有 memcpy 的源 |
| 交出所有权 | dataRelease() | 把 std::vector 的堆块"偷"过来 |
| 几维 | dimensions() | Image::Image(Data) 推断 VkImageType |
关键在于这七条都无法从彼此推导出来。这是整章第一个要被理解的设计判断:
dataSize() 不是 valueSize() * valueCount()。Array<T> 的定义是
// include/vsg/core/Array.h:305-309
size_t valueSize() const override { return sizeof(value_type); }
size_t dataSize() const override { return size() * properties.stride; }
注意 dataSize() 用的是 properties.stride,不是 sizeof(value_type)。也就是说:
valueSize()= 一个"逻辑元素"的完整大小(sizeof(T))dataSize()= 一个"存储元素"的实际占用(stride)
当 stride > sizeof(T) 时,中间有填充字节。Data::contiguous() 就是判断这两者是否相等:
// include/vsg/core/Data.h:199-201
bool contiguous() const { return valueSize() == properties.stride; }
uint32_t stride() const { return properties.stride ? properties.stride : static_cast<uint32_t>(valueSize()); }
stride() 有一个"0 表示默认"的约定:properties.stride == 0 时返回 valueSize()。这个约定让 Properties 的默认构造(stride = 0)可以表示"紧凑排列",而不需要用户在构造每个 Array 时手填 stride。
但代价是:stride 为 0 和非 0 的语义不同,而所有下游代码必须知道这一点。 _transferImageInfo 的
// src/vsg/app/TransferTask.cpp:259
VkDeviceSize image_alignment = std::max(static_cast<VkDeviceSize>(data->stride()), static_cast<VkDeviceSize>(4));
调的是 stride() 而不是 properties.stride,所以 stride == 0 会正确退化成 valueSize()。而 transferImageData 里:
// src/vsg/app/TransferTask.cpp:617
const auto valueSize = properties.stride; // data->valueSize();
这里用的是 properties.stride——但这个 properties 已经不是 data->properties 了,它是 _transferImageInfo 里逐字节补齐时重写过的副本(第 300-301 行 properties.stride = targetTraits.size)。如果走的是 sourceFormat == targetFormat 的 memcpy 分支,那么 properties 仍是 data->properties,stride 可能就是 0!
这是一个真实存在的边界情况。 具体后果:valueSize = 0 → faceSize = 0 → 所有 region.bufferOffset 都是 stagingBufferOffset → vkCmdCopyBufferToImage 从同一个偏移读所有 face 的数据。只有在两个条件同时成立时才会触发:
data->properties.format == imageView->format(不需要格式转换)data->properties.stride == 0(从未显式设置 stride)
而 Array<T> 有两个补 stride 的地方,机制不同:
// include/vsg/core/Array.h:60-63
explicit Array(uint32_t numElements, const Properties& in_properties = {}) :
Data(in_properties, sizeof(value_type)),
_data(_allocate(numElements)),
_size(numElements) { dirty(); }
// include/vsg/core/Array.h:91-95
explicit Array(std::initializer_list<value_type> l) :
_data(_allocate(l.size())),
_size(static_cast<uint32_t>(l.size()))
{
properties.stride = sizeof(value_type);
第一条走 Data(const Properties&, uint32_t min_stride),它做的是"不足才补":if (properties.stride < min_stride) properties.stride = min_stride;(include/vsg/core/Data.h:150)。所以 Array<T>::create(n) 出来的数组确实不会是 stride == 0。第二条绕过 min_stride,直接赋值。
但子数组构造函数 Array(ref_ptr<Data> storage, uint32_t offset, uint32_t stride, uint32_t numElements, ...) 走的是 assign(),那里是 properties.stride = stride 无条件赋值(include/vsg/core/Array.h:271)。也就是说 vec3Array::create(storage, 0, 0, count) 这种合法调用就能造出 stride == 0 的数组——这个边界不是"理论可达",是公开 API 一行的距离。
结论:stride == 0 在类型系统层面合法,stride() 的 0 退化是它唯一的保护。 这段代码的健壮性依赖于"没人给 assign() 传 0"这个社会契约,而不是编译器强制。
接着看 dataRelease()。这是七个契约里最不显然的一个,它的语义是"把底层存储的所有权交出去,返回裸指针,并且让 Data 忘记这块内存"——用在 vsg::read() 把 std::vector 的内部 buffer 直接接管过来的场景。Array<T> 的实现只有一个 if:
// include/vsg/core/Array.h:290-303
void* dataRelease() override
{
if (!_storage)
{
void* tmp = _data;
_data = nullptr;
_size = 0;
return tmp;
}
else
{
return nullptr;
}
}
_storage 是子数组场景里的父对象。子数组调 dataRelease() 返回 nullptr,且 _data 不被清空——调用者拿到 nullptr 时无法区分"这是子数组,交不出所有权"和"这本来就是空数组",因为两者都返回 nullptr。而 available() 只判 _data != nullptr(include/vsg/core/Array.h:216),所以子数组释放后 dataAvailable() 仍为 true,那块内存仍归父对象。一个 Data 只要真的释放过,dataAvailable() 就返回 false、dataPointer() 返回 nullptr:这就是 dataAvailable() 存在的全部理由——它的实现只是 return available()(Array.h:308)。
而 STATIC_DATA_UNREF_AFTER_TRANSFER 这个 DataVariance 枚举值就是为这个场景设计的:
// include/vsg/core/Data.h:59-65
enum DataVariance : uint8_t
{
STATIC_DATA = 0, /** treat data as if it doesn't change .*/
STATIC_DATA_UNREF_AFTER_TRANSFER = 1, /** unref this vsg::Data after the data has been transferred to the GPU memory .*/
DYNAMIC_DATA = 2, /** data is updated prior to the record traversal and will need transferring to GPU memory.*/
DYNAMIC_DATA_TRANSFER_AFTER_RECORD = 3 /** data is updated during the record traversal and will need transferring to GPU memory.*/
};
四个值的语义各不相同,而它们在后端的处理只有两处差异:
dynamic()判断:properties.dataVariance >= DYNAMIC_DATA。所以STATIC_DATA_UNREF_AFTER_TRANSFER(1)不算动态,DYNAMIC_DATA(2)和DYNAMIC_DATA_TRANSFER_AFTER_RECORD(3)算。- 分到 early 还是 late 队列:
>= DYNAMIC_DATA_TRANSFER_AFTER_RECORD进_lateDataToCopy,否则进_earlyDataToCopy。
也就是说 STATIC_DATA_UNREF_AFTER_TRANSFER 和 STATIC_DATA 在 TransferTask 里走完全相同的代码路径。它的区别只发生在 Context::createBufferAndTransferData 的已废弃分支里:
// src/vsg/vk/Context.cpp(#else 分支内,当前被 #if 1 屏蔽)
std::memcpy(ptr + bufferInfo->offset - deviceBufferInfo->offset, data->dataPointer(), data->dataSize());
if (data->properties.dataVariance == STATIC_DATA_UNREF_AFTER_TRANSFER)
{
bufferInfo->data.reset();
}
这段代码现在不参与编译。 所以在当前版本里,STATIC_DATA_UNREF_AFTER_TRANSFER 基本上是一个装饰性枚举值——写了等于没写,data 不会被释放。这是一个值得记住的"配置项失效"案例:你在 2019 年写的代码里设了这个标志,指望省下 48 MB 的顶点数据,今天它一分不省。
5.2 Data::Properties:十一个字段,每一个都有故事
// include/vsg/core/Data.h:120-140
struct VSG_DECLSPEC Properties
{
Properties() = default;
Properties(const Properties& rhs) = default;
explicit Properties(VkFormat in_format) :
format(in_format) {}
VkFormat format = VK_FORMAT_UNDEFINED;
uint32_t stride = 0;
uint8_t mipLevels = 0;
uint8_t blockWidth = 1;
uint8_t blockHeight = 1;
uint8_t blockDepth = 1;
uint8_t origin = TOP_LEFT;
int8_t imageViewType = -1;
DataVariance dataVariance = STATIC_DATA;
AllocatorType allocatorType = ALLOCATOR_TYPE_VSG_ALLOCATOR;
};
十一个字段。逐个说。
format:默认 VK_FORMAT_UNDEFINED,意思是"不知道也不关心"。对顶点数组确实不重要——顶点格式由管线的 VkVertexInputAttributeDescription 描述。但 Image::Image(Data) 直接把 properties.format 赋给 Image::format,所以纹理必须有正确的 format,否则 vkCreateImage 直接失败。
stride:默认 0,语义见上。注意 Data::Properties 没有 const 校验——你可以构造一个 stride = 3 的 vec3Array,然后 dataSize() 变成 size * 3,memcpy 只拷 1/4 的数据。这意味着 stride 是一个"必须由构造者保证正确"的字段,没有任何运行时校验。
还有一处不对称:Properties 的拷贝构造是 = default(逐字段复制,include/vsg/core/Data.h:123),但赋值运算符对 stride 做了特例——if (rhs.stride != 0) stride = rhs.stride;(src/vsg/core/Data.cpp:32)。右侧 stride == 0 时左侧保持原值,于是 a = b 与 Properties c(b) 语义不同:前者可能把 b 的 stride=0 悄悄替换成 a 的旧值。这条特例的本意是保护"已经算出来的有效 stride 不被默认值冲掉",代价是赋值不再是快照。
mipLevels:uint8_t,默认 0。Image::Image(Data) 用 max(1u, ...) 把 0 变 1,而 _transferImageInfo 里直接 static_cast<uint32_t>(data->properties.mipLevels),没有 max。所以 mipLevels == 0 时 data_mipLevels = 0,useDataMipmaps 与 generateMipmaps 都是 false,走单级路径——结果正确,但原因是"mipLevels == 1 让两个分支都不触发"这个巧合。
真问题是 mipLevels > 1 但没提供多级数据。 此时 useDataMipmaps = true(因为 1 > 1 && N > 1 对 N>1 成立),mipLevels = min(N, N),然后 mipmapData 为空 → 走"逐级减半算 faceSize"的 else 分支 → 算出 N 个 region,但 data 里只有第 0 级 → vkCmdCopyBufferToImage 越界读 staging buffer。修法:只设 mipLevels = 1,让 computeNumMipMapLevels + generateMipmaps 自动生成。
blockWidth/blockHeight/blockDepth:默认全 1 表示未压缩。压缩格式(BC/ETC/ASTC)下是 4×4(或 4×4×1 等)。这三个字段的作用是把"纹素数"换算成"块数":
// src/vsg/core/Data.cpp:215-217
uint32_t w = width() * properties.blockWidth;
uint32_t h = height() * properties.blockHeight;
uint32_t d = faceDepth * properties.blockDepth;
注意这个乘法方向:width() 已经是块数,乘 blockWidth 得到纹素数。也就是说 Data::width() 的语义是"一行有多少个存储单元",而不是"一行有多少个像素"。对未压缩格式两者相同,对 BC1 压缩的 256×256 纹理,width() 是 64、blockWidth 是 4、乘积是 256。
这个方向容易搞反。反过来的话,pixelExtents 会返回 256/4 = 64,Image::extent.width 就是 64,纹理尺寸变成 1/4。症状是纹理严重放大、模糊,而且不会报错。
computeValueCountIncludingMipmaps 里方向相反:先 x = width() * blockWidth(纹素数),再 (x + blockWidth - 1) / blockWidth 取回块数。先乘后除,绕一圈回到 width()——在 mipLevels == 1 时纯属浪费,只在多级 mipmap 时才有意义(每级要重新除以 2 再取块数)。
origin:uint8_t,TOP_LEFT = 0 / BOTTOM_LEFT = 2。
// include/vsg/core/Data.h:53-57
enum Origin : uint8_t
{
TOP_LEFT = 0,
BOTTOM_LEFT = 2
};
这两个值不是 0 和 1,而是 0 和 2。 注释解释了原因:
uint8_t origin = TOP_LEFT; /// Hint for setting up texture coordinates, bit 0 x/width axis, bit 1 y/height axis, bit 2 z/depth axis.
它是一个位域:bit 0 表示 x/width 轴翻转,bit 1 表示 y/height 轴翻转。BOTTOM_LEFT = 2 就是"y 轴翻转"。所以理论上还应该有 TOP_RIGHT = 1 和 BOTTOM_RIGHT = 3(x 和 xy 翻转),但枚举里没定义——你只能翻转 y。这是一个被截断的位域设计。
而 origin 在整个上传链路里一次都没被读(grep -rn "properties.origin" src/vsg 除序列化外无命中)。真正处理它的是 vsg::read 之后的加载器或着色器里的 UV 计算。它也是一个"写了不生效"的字段——除非你在自己的 ReaderWriter 里读它。
imageViewType:int8_t,默认 -1。
int8_t imageViewType = -1; /// -1 signifies undefined VkImageViewType, if value >=0 then value should be treated as valid VkImageViewType.
VkImageViewType 的枚举值是 1D=0, 2D=1, 3D=2, CUBE=3, 1D_ARRAY=4, 2D_ARRAY=5, CUBE_ARRAY=6,全部塞得进 int8_t。所以这里存的是真实的枚举值,只是靠"这些值恰好很小"这个事实。Image::Image(Data) 的 switch 直接拿 VK_IMAGE_VIEW_TYPE_* 当 case 标签(src/vsg/state/Image.cpp:45)。这是一个隐含的类型契约:如果 Vulkan 把 CUBE_ARRAY 改成一个超过 127 的值,int8_t 会截断,switch 全部落到 default。 概率极低,但零成本就能修(把字段改成 int32_t)。
而 Data::faceDepthAndCount() 也用同一个字段:
// src/vsg/core/Data.cpp:149-163
std::pair<uint32_t, uint32_t> Data::faceDepthAndCount() const
{
switch (properties.imageViewType)
{
case (VK_IMAGE_VIEW_TYPE_CUBE):
case (VK_IMAGE_VIEW_TYPE_CUBE_ARRAY):
return {depth() / 6, 6};
case (VK_IMAGE_VIEW_TYPE_1D_ARRAY):
case (VK_IMAGE_VIEW_TYPE_2D_ARRAY):
return {1, depth()};
default:
return {depth(), 1};
}
}
CUBE_ARRAY 和 CUBE 返回同样的结果 {depth()/6, 6}。 对 CUBE(depth = 6)返回 {1, 6},正确。对 CUBE_ARRAY(depth = 12,2 个 cube)返回 {2, 6}——但 VK_IMAGE_VIEW_TYPE_CUBE_ARRAY 的正确语义是 arrayLayers = 12, depth = 1。
然后 pixelExtents():
// src/vsg/core/Data.cpp:211-228
std::tuple<uint32_t, uint32_t, uint32_t, uint32_t> Data::pixelExtents() const
{
auto [faceDepth, faceCount] = faceDepthAndCount();
uint32_t w = width() * properties.blockWidth;
uint32_t h = height() * properties.blockHeight;
uint32_t d = faceDepth * properties.blockDepth;
if (auto mipmapLayout = getMipmapLayout())
{
auto mipmap = mipmapLayout->at(0);
w = mipmap.x;
h = mipmap.y;
d = mipmap.z;
}
return {w, h, d, faceCount};
}
而 Image::Image(Data) 直接解构它:
// src/vsg/state/Image.cpp:43
std::tie(extent.width, extent.height, extent.depth, arrayLayers) = data->pixelExtents();
所以对 CUBE_ARRAY:extent.depth = 2,arrayLayers = 6。而 vkCreateImage 的 VkImageCreateInfo 要求 extent.depth = 1(2D 图像)且 arrayLayers = 12。
这会创建一个 extent 为 {W, H, 2}、arrayLayers 为 6 的 2D 图像,总纹素数是 W*H*2*6 = 12WH,和期望的 W*H*12 数值相同,但布局完全不同。后果是:cube array 的第 6 层之后全是错的,采样器读到的是 layer 0 的 depth 1。
这是一个可疑实现。定性前先看能验证的量:pixelExtents() 的第 4 个返回值直接进 arrayLayers(src/vsg/state/Image.cpp:43),而 vkCreateImage 对 2D 图要求 extent.depth = 1 且 arrayLayers = 12。两者的总量都是 12WH,所以验证层不会因为尺寸报错,错的是分层。
如果你的代码用到 cube array,在 Image::create(data) 之后手动覆盖 image->arrayLayers 和 image->extent.depth,或者干脆按 5.19 节的写法只声明 2D_ARRAY。
dataVariance:见上一节。
allocatorType:从 Data::Properties 一直传到 Array 的分配器选择,决定 Data 的负载内存走哪个分配器。第二章详细讲过四种 AllocatorType,这里只强调一点:它是 Properties 的字段,不是 Data 的字段,所以 Data::operator new 走的是写死的 ALLOCATOR_AFFINITY_DATA(src/vsg/core/Data.cpp:46),而 Array 的负载可以不通过它。
5.3 ModifiedCount:一个 uint32_t 撑起的脏标记系统
这是整章最精巧的设计,也是最少被理解的。
// include/vsg/core/Data.h:31-39
struct ModifiedCount
{
uint32_t count = 0;
bool operator==(const ModifiedCount& rhs) const { return count == rhs.count; }
bool operator!=(const ModifiedCount& rhs) const { return count != rhs.count; }
void operator++() { ++count; }
};
一个 uint32_t。没有时间戳、没有版本向量、没有哈希。整个"数据改了没有"的判定就是"计数器变了没有"。ModifiedCount::operator++ 的签名也刻意窄:前缀自增返回 void、没有后置版本(include/vsg/core/Data.h:38),所以全代码库只能写 ++_modifiedCount,写成 _modifiedCount++ 直接编译失败。
Data 侧:
// include/vsg/core/Data.h:205-221
/// increment the ModifiedCount to signify the data has been modified
void dirty() { ++_modifiedCount; }
/// get the Data's ModifiedCount and return true if this changes the specified ModifiedCount
bool getModifiedCount(ModifiedCount& mc) const
{
if (_modifiedCount != mc)
{
mc = _modifiedCount;
return true;
}
else
return false;
}
/// return true if Data's ModifiedCount is different from the specified ModifiedCount
bool differentModifiedCount(const ModifiedCount& mc) const { return _modifiedCount != mc; }
dirty() 不是原子操作。 ++_modifiedCount 就是 ++uint32_t,没有 fetch_add、没有 memory_order。这与第一章讲的 Object::ref()(relaxed)形成对比:引用计数至少用了 std::atomic,而脏标记连原子都不是。
这意味着:dirty() 只能从"拥有这个 Data 的唯一线程"调用。 如果更新线程和记录线程同时 dirty() 同一个 Data,会丢失自增(两个线程读-改-写同一个值)。丢失一次的后果是 requiresCopy 返回 false,这一帧的更新被吞掉,下一帧才生效。
这是一个"在正确使用下无问题、在滥用下静默丢帧"的设计。VSG 的线程模型(第十五章)里,Viewer::update() 和 Viewer::record() 是同一线程串行执行的,所以这个假设成立。但如果你的应用在别的线程改 Data(比如网络线程直接往顶点数组里写位置),就必须自己加锁——而且加锁也不够,因为 record() 读 _modifiedCount 时你看不见它。
正确的做法是:网络线程把数据放进队列,更新线程在 update() 阶段取出并 dirty()。
接收侧:BufferInfo 和 Image 各自持有自己的 ModifiedCount:
// include/vsg/state/BufferInfo.h:80
vk_buffer<ModifiedCount> copiedModifiedCounts;
// include/vsg/state/Image.h(VulkanData 内)
ModifiedCount copiedModifiedCount;
注意类型差异:BufferInfo 用 vk_buffer<ModifiedCount>(每设备一个),Image 用裸 ModifiedCount(每 VulkanData 一个,而 VulkanData 本身就在 vk_buffer 里)。两者等价,只是写法不同。
vk_buffer<X> 是第一章讲过的"数组大小 = VSG_MAX_DEVICES"类型。因为 VSG_MAX_DEVICES = 1,vk_buffer<ModifiedCount> 实际上只有一个元素——这是 VSG 至今只支持单设备的直接原因。
三个判定函数的区别只有一点:requiresCopy 不改 copiedModifiedCounts(幂等,用于"要不要做"的决策),syncModifiedCounts 会改(一次调用,用于"已经做了"的记账)。这个区分在 TransferTask 里被严格遵守:_transferData 第 361 行先 requiresCopy 判断有没有活干,_transferBufferInfos 里(TransferTask.cpp:139)才 syncModifiedCounts 消费脏标记。同一条数据在一帧里会被查两次——1000 个 BufferInfo 就是 2000 次虚函数调用,10 万个动态 buffer 就是 20 万次/帧。
requiresCopy 里还有个 referenceCount() > 1 前置条件:== 1 意味着"只有 TransferTask 自己还持有它",场景图里已经没人用,属于待回收垃圾,直接 erase(TransferTask.cpp:132)。这是 TransferTask 的垃圾回收机制。
5.4 Array 的 stride 与 Array2D/Array3D 的维度校验
Array<T> 的 assign 是唯一设置 stride 的地方:
// include/vsg/core/Array.h:265-281
void assign(ref_ptr<Data> storage, uint32_t offset, uint32_t stride, uint32_t numElements, const Properties& in_properties = {}, MipmapLayout* mipmapLayout = nullptr)
{
_delete();
_storage = storage;
properties = in_properties;
properties.stride = stride;
if (_storage && _storage->dataPointer())
{
_data = reinterpret_cast<value_type*>(reinterpret_cast<uint8_t*>(_storage->dataPointer()) + offset);
_size = numElements;
}
...
properties.stride = stride 是无条件的,而且 _data 的落点是 storage->dataPointer() + offset——没有对 offset + numElements * stride 是否越过 storage->dataSize() 做任何检查。如果你传 stride = 0,stride() 会退化成 valueSize();如果你传 stride = 12 给一个 vec3Array(sizeof(vec3) = 12),那就是紧凑的;如果你传 stride = 16,就是 16 字节对齐的 vec3(这在实际中很常见,为了 std430 的 vec3 对齐)。
这里有一个极容易踩的坑:Array<vec3> 的 stride = 16 时,dataSize() = size * 16,但 valueCount() = size、valueSize() = 12。而 transferImageData 里 valueSize = properties.stride = 16,faceSize = width * height * depth * 16,与实际数据一致。 所以 stride 在上传路径上是"每元素实际占用",是对的。
但如果在 _transferImageInfo 里走到了格式补齐分支:
// src/vsg/app/TransferTask.cpp:298-301
VkDeviceSize imageTotalSize = targetTraits.size * data->valueCount();
properties.format = targetFormat;
properties.stride = targetTraits.size;
stride 被强制改写成 targetTraits.size。如果原来是 16(padding 版 vec3)而 targetTraits.size 是 4(RGBA8),那么 properties.stride = 4,faceSize = width * height * depth * 4——与实际写入的 valueCount * 4 一致(因为补齐循环逐元素写 4 字节)。这里是对的。
但 imageTotalSize 只有 valueCount * 4,而 _transferData 预计算时用的是:
// src/vsg/app/TransferTask.cpp:382
VkDeviceSize imageSize = (targetTraits.size > 0) ? targetTraits.size * data->valueCount() : data->dataSize();
同样也是 targetTraits.size * valueCount()。 两处一致。✓
但如果走的是 sourceTraits.size == targetTraits.size 的 memcpy 分支:
// src/vsg/app/TransferTask.cpp:290-295
if (sourceTraits.size == targetTraits.size)
{
log(level, " sourceTraits.size and targetTraits.size compatible.");
std::memcpy(ptr, data->dataPointer(), data->dataSize());
offset += data->dataSize();
}
offset += data->dataSize(),而 _transferData 预计算的是 targetTraits.size * valueCount()(src/vsg/app/TransferTask.cpp:382)。当 dataSize() != targetTraits.size * valueCount() 时,两遍算出的长度不等。 要制造这个不等式,只需 stride != 0 且 stride != targetTraits.size:Array3D<ubyte> 手动设 stride = 4、format = VK_FORMAT_R8_UNORM,则 dataSize() = count*4 而预算是 count——_transferData 只预留 count 字节,_transferImageInfo 却 memcpy 了 count*4 字节,写到 staging 的下一个条目区域甚至越界。
结论:data->stride() 必须等于目标格式的 traits.size,否则 staging buffer 的预计算与实际写入会错位。 这是一个没有断言保护的不变式。
Array2D/Array3D 的 assign() 同样不检查 storage 是否够放 width * height:
// include/vsg/core/Array2D.h:250-263
void assign(ref_ptr<Data> storage, uint32_t offset, uint32_t stride, uint32_t width, uint32_t height, const Properties& in_properties = {}, MipmapLayout* mipmapLayout = nullptr)
{
_delete();
_storage = storage;
properties = in_properties;
properties.stride = stride;
if (_storage && _storage->dataPointer())
{
_data = reinterpret_cast<value_type*>(reinterpret_cast<uint8_t*>(_storage->dataPointer()) + offset);
_width = width;
_height = height;
}
Array3D::assign 是同一份代码多一个 _depth(include/vsg/core/Array3D.h:262)。grep -n "Exception" include/vsg/core/Array*.h 一个都不命中:整个 Data 家族没有任何维度或边界校验,Array2D(data, 0, 4, 100000, 100000) 可以声称 10¹⁰ 个元素而 storage 只有 4 字节。
这解释了为什么第四章末尾提到的"Array 的越界读"在 VSG 里是个真实风险:安全检查的责任 100% 在调用者,而越界后读到的仍是合法映射内存,不会崩,只是画面错。
5.5 BufferInfo:三层结构里的"中层合同"
VSG 的缓冲管理是三层的,每一层的职责边界极其清晰:
Data ← 纯 CPU 内存 + 格式描述(不带任何 Vk* 类型)
↓
BufferInfo ← "我要 buffer 上 [offset, offset+range) 这一段,内容是 data"
↓
Buffer ← VkBuffer + 自己的 MemorySlots 子分配表
↓
DeviceMemory ← vkAllocateMemory 的产物 + MemorySlots 子分配表
BufferInfo 是中间那一层,它自己也不持有任何 VkBuffer——它是 VkDescriptorBufferInfo 的 VSG 版对应物:
// include/vsg/state/BufferInfo.h:56-60
ref_ptr<Buffer> buffer;
VkDeviceSize offset = 0;
VkDeviceSize range = 0;
ref_ptr<Data> data;
ref_ptr<BufferInfo> parent;
五个字段,对应 VkDescriptorBufferInfo 的 {buffer, offset, range} 三个字段,外加 data(CPU 侧来源)和 parent(合并上传时的"父条目")。
先看 parent。这个概念在 Context::createBufferAndTransferData 的废弃分支里有完整的用法:
// src/vsg/vk/Context.cpp(#else 分支,当前被屏蔽)
for (const auto& bufferInfo : bufferInfoList)
{
bufferInfo->buffer = deviceBufferInfo->buffer;
bufferInfo->offset += deviceBufferInfo->offset;
...
bufferInfo->parent = deviceBufferInfo;
}
语义是:当 N 个小 BufferInfo 被打包进一个大的 BufferInfo 时,小的记住大的。用途在 BufferInfo::release():
// src/vsg/state/BufferInfo.cpp:109-123
void BufferInfo::release()
{
if (parent)
{
parent.reset();
}
else if (buffer)
{
buffer->release(offset, range);
}
buffer.reset();
offset = 0;
range = 0;
}
有 parent 就只是断开引用,不真的去 buffer->release(offset, range)。因为那块空间的所有权在父条目手里,子条目只借不还。如果子条目自己去还,会把父条目名下的空间还掉(BufferInfo.cpp:111),导致后续 reserve 拿到重叠区间——这是经典的 double-free 变体。
reset() 的顺序也很讲究:先 parent.reset() 再 buffer.reset()。因为 parent 持有 buffer 的引用,先释放 parent 才能让 buffer 的引用计数正确下降。
take() 是 release() 的反向操作:
// src/vsg/state/BufferInfo.cpp:81-100
void BufferInfo::take(BufferInfo& src)
{
if (&src == this) return;
if (buffer && !parent)
{
bool identical = (buffer == src.buffer && offset == src.offset && range == src.range);
if (!identical)
{
// release entry into buffer.
buffer->release(offset, range);
}
}
// copy settings across
parent = src.parent;
buffer = src.buffer;
offset = src.offset;
range = src.range;
...
identical 检查在这里不是优化,是正确性:如果 this 和 src 指向 buffer 上完全相同的区间,buffer->release(offset, range) 会把这块空间还掉,然后 buffer = src.buffer 又"借"了回来——但 src 的 buffer.reset() 之后,那块空间成了无人认领的孤儿,下次 reserve 会再分配一次,两个 BufferInfo 指向同一段内存。
!parent 条件也是正确性:如果 this 已有 parent,说明它之前被打包过,空间由父条目管,不该 release。但 parent = src.parent 会覆盖掉 this->parent——旧 parent 引用丢了,旧 parent 名下的空间却没归还。所以 take 有一个未写明的前提:不要在"已打包条目"上调用它。
clone 更特殊:
// src/vsg/state/BufferInfo.cpp:47-53
ref_ptr<Object> BufferInfo::clone(const CopyOp& copyop) const
{
auto new_data = copyop(data);
if (new_data == data) return ref_ptr<Object>(const_cast<BufferInfo*>(this));
return BufferInfo::create(new_data);
}
data 没被深拷贝时,clone 直接返回 this。 这不叫 clone,叫共享。理由是 buffer/offset/range 是"已经分配好的 GPU 位置",深拷贝它们没意义。副作用是:BufferInfo::create(data) 出来的新条目 buffer 是空的,显存位置全丢,得在下次 compile 时重新走 createBufferAndTransferData。
compare 有两处为了性能而牺牲严格性的地方:
// src/vsg/state/BufferInfo.cpp:62-74
if (data != rhs.data && data && rhs.data)
{
if (data->dynamic() || rhs.data->dynamic())
{
if (data < rhs.data) return -1;
return 1;
}
}
if ((result = compare_pointer(data, rhs.data))) return result;
/// if one of less buffer is assigned treat as a match as data is the same, and we can reuse any BufferInfo that's been assigned.
if (!buffer || !rhs.buffer) return 0;
第一处:动态数据退化成指针比较(内容每帧都变,memcmp 永远返回"不同",不如直接比指针)。
第二处:只要一方没分配 buffer 就返回 0(相同)。这让"已编译"和"未编译"的条目能判为等价,从而在 compile 时复用。代价是 compare 不再反对称(A.compare(B) == 0 且 B.compare(A) == 0,但 A.offset != B.offset)——如果拿它当 std::set 的 key,不等价的对象会被折叠。VSG 里 BufferInfo 确实进了 std::map,但 key 是 (buffer, offset) 而非 BufferInfo 本身,所以暂时安全。
BufferInfo::operator bool() 要求 buffer/data/range 同时成立(include/vsg/state/BufferInfo.h:54),而且它不看 parent——带 parent 的子条目只要 buffer 为空就判 false:
explicit operator bool() const { return buffer.valid() && data.valid() && range != 0; }
range != 0 拦住了"零长度数组"(空 vec3Array 的 dataSize() 是 0)。
三个谓词覆盖的集合并不相同,这是本节最容易漏掉的细节。requiresAllocation() 只看 !buffer || buffer->getDeviceMemory(deviceID) == nullptr(include/vsg/state/BufferInfo.h:63);requiresCopy() 只看 data && data->differentModifiedCount(copiedModifiedCounts[deviceID])(BufferInfo.h:69)——它完全不看 buffer。于是一个"有数据但还没分配到 VkBuffer"的条目会同时满足两个谓词:Geometry::compile 用它决定要不要 reserve,TransferTask 用它决定要不要 memcpy,两条路径都成立。真正把两者串起来的是 syncModifiedCounts()(BufferInfo.h:75),它把 copiedModifiedCounts 推到 data 的当前值,此后 requiresCopy() 才变 false。
5.6 Buffer 与 DeviceMemory:两层 MemorySlots
Buffer 只有 4 个 VkBufferCreateInfo 字段 + 1 个 MemorySlots:
// include/vsg/state/Buffer.h(成员摘录)
VkBufferCreateFlags flags = 0;
VkDeviceSize size;
VkBufferUsageFlags usage;
VkSharingMode sharingMode;
protected:
vk_buffer<VulkanData> _vulkanData;
mutable std::mutex _mutex;
MemorySlots _memorySlots;
注意 size、usage、sharingMode 没有默认值——Buffer 只有带参构造:
// 声明见 include/vsg/state/Buffer.h:32
Buffer(VkDeviceSize in_size, VkBufferUsageFlags in_usage, VkSharingMode in_sharingMode);
所以你不能"先建一个空 Buffer 再补字段",必须一次给全。这与 Image 形成对比(Image 有 explicit Image(ref_ptr<Data> in_data = {}),可以默认构造)。
两层 MemorySlots 是这一节的重点。Buffer::reserve 管的是这个 VkBuffer 内部的偏移,DeviceMemory::reserve 管的是这块显存内部的偏移。一个 Buffer 完整的显存地址是:
vkDeviceMemory 基址
+ DeviceMemory::reserve 返回的 memoryOffset ← 这块 VkBuffer 在显存里的起点
+ Buffer::reserve 返回的 offset ← 这个 BufferInfo 在 VkBuffer 里的起点
这解释了 BufferInfo::copyDataToBuffer 里那个看起来绕的加法:
// src/vsg/state/BufferInfo.cpp:167
VkResult result = dm->map(buffer->getMemoryOffset(deviceID) + offset, range, 0, &buffer_data);
buffer->getMemoryOffset(deviceID) 是 VulkanData::memoryOffset(显存内偏移),offset 是 BufferInfo::offset(buffer 内偏移)。两者相加才是真正的显存偏移。
第二章讲过 MemorySlots 是 multimap<size, offset> + map<offset, size> 的双索引,best-fit + 相邻合并。这里补一个实际数字:一次完整的 reserveBuffer 会涉及两次 MemorySlots 操作(一次在 Buffer 内,一次在 DeviceMemory 内),每次都是 O(log n) 的 lower_bound + 可能的 ++itr + 可能的两次 erase/insert。
Buffer::release 走同样的两层:
// include/vsg/state/Buffer.h:49
void release(VkDeviceSize offset, VkDeviceSize in_size);
只释放 Buffer 内的那段,不碰 DeviceMemory(include/vsg/state/Buffer.h:45 声明,实现里只调 _memorySlots.release,src/vsg/state/Buffer.cpp:126)。DeviceMemory 的释放发生在 Buffer::VulkanData::release():
// src/vsg/state/Buffer.cpp:22-34
void Buffer::VulkanData::release()
{
if (buffer)
{
vkDestroyBuffer(*device, buffer, device->getAllocationCallbacks());
}
if (deviceMemory)
{
//deviceMemory->release(memoryOffset, memorySlots.totalMemorySize());
deviceMemory->release(memoryOffset, size);
}
}
这段代码既不把 buffer 置 VK_NULL_HANDLE,也不把 deviceMemory 置空,它只被析构函数里的 for (auto& vd : _vulkanData) vd.release(); 调用一次(src/vsg/state/Buffer.cpp:51),靠"只调一次"保证幂等。对比 Image::VulkanData::release():那里两个句柄都归零(src/vsg/state/Image.cpp:25、:31)。同一套 VulkanData 模式,一个可重入一个不可,读代码时不能互相类推。
顺序也是先 vkDestroyBuffer,再释放显存槽位。这是 Vulkan 的要求(vkDestroyBuffer 之后才能释放它占用的内存),也是 MemorySlots 正确性的要求(如果先还槽位,别人可能在你 vkDestroyBuffer 之前就 reserve 到这块空间)。
Buffer::maximumAvailableSpace() 是 MemoryBufferPools::reserveBuffer 的核心判据:
// include/vsg/state/Buffer.h:54
size_t maximumAvailableSpace() const;
它返回最大单块连续空闲空间,不是总空闲空间。这个区别决定了能不能复用一块池:
// src/vsg/vk/MemoryBufferPools.cpp:85
if (bufferFromPool->usage == bufferUsageFlags && bufferFromPool->size >= totalSize && bufferFromPool->maximumAvailableSpace() >= totalSize)
三个条件:usage 完全相同(位相等,不是位包含)、size 够大、最大连续空闲够大。
usage == bufferUsageFlags 用相等而不是 (usage & flags) == flags,意味着一个 VERTEX_BUFFER | INDEX_BUFFER 的 buffer 不会复用给纯 VERTEX_BUFFER 的请求,即使前者能力更强。这是一个保守但安全的选择:Vulkan 允许对 usage 做超集复用,但 VSG 选择不复用,代价是更多的 VkBuffer,收益是避免了 usage 不匹配导致的验证层报错。
还有一条与"错误处理靠日志"的整体印象不符的例外:Buffer::compile 在 vkCreateBuffer 失败时抛异常(src/vsg/state/Buffer.cpp:109),而同一文件里的 bind 二次绑定只打 warn 并返回 VK_ERROR_UNKNOWN(src/vsg/state/Buffer.cpp:74)。创建失败是致命的、绑定失败是可降级的,这条区分是作者显式做的,不是遗漏。
5.7 Image::Image(Data):30 行里的三个关键决策
这是整章最需要逐行读的函数。
// src/vsg/state/Image.cpp:35-43
Image::Image(ref_ptr<Data> in_data) :
data(in_data)
{
if (data)
{
auto properties = data->properties;
auto dimensions = data->dimensions();
std::tie(extent.width, extent.height, extent.depth, arrayLayers) = data->pixelExtents();
// ...
case (VK_IMAGE_VIEW_TYPE_CUBE):
imageType = VK_IMAGE_TYPE_2D;
flags = VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT;
break;
case (VK_IMAGE_VIEW_TYPE_1D_ARRAY):
imageType = VK_IMAGE_TYPE_1D;
/* flags = VK_IMAGE_CREATE_1D_ARRAY_COMPATIBLE_BIT; // comment out as Vulkan headers don't yet provide this. */
break;
case (VK_IMAGE_VIEW_TYPE_2D_ARRAY):
imageType = VK_IMAGE_TYPE_2D;
break;
// ...
format = properties.format;
mipLevels = std::max(1u, static_cast<uint32_t>(data->properties.mipLevels));
// remap RGB to RGBA
if (format >= VK_FORMAT_R8G8B8_UNORM && format <= VK_FORMAT_B8G8R8_SRGB)
format = static_cast<VkFormat>(format + 14);
else if (format >= VK_FORMAT_R16G16B16_UNORM && format <= VK_FORMAT_R16G16B16_SFLOAT)
format = static_cast<VkFormat>(format + 7);
else if (format >= VK_FORMAT_R32G32B32_UINT && format <= VK_FORMAT_R32G32B32_SFLOAT)
format = static_cast<VkFormat>(format + 3);
usage = (VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT);
}
}
决策一:extent 和 arrayLayers 全部从 pixelExtents() 推。
没有第二个来源。所以 pixelExtents() 的任何偏差都会被 100% 传递到 VkImageCreateInfo。这也是为什么 5.2 节里要花篇幅讨论 CUBE_ARRAY。
注意 dimensions 这个局部变量在 switch 的 default 分支之外完全没用。dimensions() 的作用只是给"没设 imageViewType"的情况兜底。
决策二:2D_ARRAY 的分支有一半是注释掉的(src/vsg/state/Image.cpp:65):两行注释记录了作者曾经的犹豫——把 2D_ARRAY 当成 VK_IMAGE_TYPE_3D 处理,用 extent.depth 表示层数,并加 2D_ARRAY_COMPATIBLE_BIT。VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT 确实存在(Vulkan 1.1 引入),但它只对 VK_IMAGE_TYPE_3D 有效,是"把 3D 图当 2D array 视图用"的反向桥。作者最后选了更直接的 VK_IMAGE_TYPE_2D + arrayLayers。
但 1D_ARRAY 的注释是另一回事:VK_IMAGE_CREATE_1D_ARRAY_COMPATIBLE_BIT 在 Vulkan 规范里根本不存在,注释说"headers 还没提供"是委婉说法。1D array 不需要额外 flag——VK_IMAGE_TYPE_1D + arrayLayers > 1 就是 1D array,这行注释可以永久删掉(原文在 Image.cpp:62)。
决策三:RGB→RGBA 的 +14 / +7 / +3。
这是全章最需要讲清楚的一段。三个魔数,对应三组 VkFormat 枚举值:
| 源格式区间 | 偏移 | 目标 |
|---|---|---|
R8G8B8_UNORM (23) … B8G8R8_SRGB (36) | +14 | R8G8B8A8_UNORM (37) … B8G8R8A8_SRGB (50) |
R16G16B16_UNORM (84) … R16G16B16_SFLOAT (90) | +7 | R16G16B16A16_UNORM (91) … R16G16B16A16_SFLOAT (97) |
R32G32B32_UINT (104) … R32G32B32_SFLOAT (106) | +3 | R32G32B32A32_UINT (107) … R32G32B32A32_SFLOAT (109) |
为什么是 14?因为 8 位 RGB 有两族(R8G8B8 和 B8G8R8),每族 7 个变体:
R8G8B8_*占 23–29(7 个)B8G8R8_*占 30–36(7 个)R8G8B8A8_*占 37–43(7 个)B8G8R8A8_*占 44–50(7 个)
从 R8G8B8_UNORM(23) 到 R8G8B8A8_UNORM(37) 差 14;从 B8G8R8_UNORM(30) 到 B8G8R8A8_UNORM(44) 也是差 14。两族的偏移恰好相同,所以一个 +14 覆盖全部 14 个源格式。
16 位只有一族(R16G16B16_*,7 个),所以偏移是 7。32 位只有三个变体(UINT/SINT/SFLOAT),所以偏移是 3。
这是"枚举值的连续排布"这一 Vulkan 头文件事实的直接利用。 它不是巧合——vulkan_core.h 里所有格式都按 {分量数} × {位数} × {类型} 的规则连续排布,所以 format + delta 总能落到对应的"多一个分量"的格式上。
代价是:这段代码在 Vulkan 格式表变化时静默失效。 具体风险点:如果 Khronos 在 R8G8B8_SRGB 和 R8G8B8A8_UNORM 之间插入一个新格式(历史上确实插入过:*_SCALED 系列是后来加的),+14 就会落到错误的格式上。而错误的表现是——纹理能创建、能上传、能采样,只是颜色分量错位,没有验证层警告。
更麻烦的是区间判断用了 <=:
format >= VK_FORMAT_R8G8B8_UNORM && format <= VK_FORMAT_B8G8R8_SRGB
VK_FORMAT_B8G8R8_SRGB = 36,VK_FORMAT_R8G8B8A8_UNORM = 37。区间是紧的,没有空隙。 但 VK_FORMAT_B8G8R8_SRGB(36)之后紧跟的是 VK_FORMAT_R8G8B8A8_UNORM(37),所以 format = 37 不会被误判为 RGB(因为 37 > 36)。✓
这段逻辑的正确性依赖三个事实:(1)Vulkan 格式枚举按分量数连续分段;(2)每段恰好 7 个(8 位/16 位)或 3 个(32 位)变体;(3)RGB 段与 RGBA 段的距离恰好等于段长之和。
事实(2)是最脆弱的。 8 位段有 7 个变体,是因为 {UNORM, SNORM, USCALED, SSCALED, UINT, SINT, SRGB}。SRGB 只在 8 位有,所以 8 位是 7 个而 16/32 位是 6/3 个(16 位没有 SRGB,但 R16G16B16_* 区间 84–90 确实是 7 个:UNORM, SNORM, USCALED, SSCALED, UINT, SINT, SFLOAT)。
+7 之所以成立,是因为 R16G16B16_* 正好 7 个,紧接着就是 R16G16B16A16_*。✓
为什么要做这个重映射? 因为 Vulkan 的可采样格式支持里,3 分量的 8/16/32 位格式在很多实现上不被 VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT 支持(尤其是 R8G8B8_UNORM,很多移动 GPU 完全不支持采样)。升级到 4 分量是"最安全"的做法。
代价是什么? 内存增加 33%(RGB8 → RGBA8),并且触发 _transferImageInfo 的格式转换路径:
// src/vsg/app/TransferTask.cpp:278-280
VkFormat sourceFormat = data->properties.format; // R8G8B8_UNORM
VkFormat targetFormat = imageInfo.imageView->format; // R8G8B8A8_UNORM
if (sourceFormat == targetFormat) // false
进入 else 分支 → sourceTraits.size = 3、targetTraits.size = 4 → 不相等 → 逐字节补齐循环。
这个循环在 5.19 节详细拆。这里只需记住结论:一个 4K 的 RGB8 纹理,上传时要走 500 万次迭代的逐字节循环,而不是一次 memcpy。 这就是 +14 性能代价的量化形式。
usage 的默认值:
usage = (VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_TRANSFER_DST_BIT);
只有两个位。 这意味着从 Data 创建的 Image 不能当渲染目标(缺 COLOR_ATTACHMENT_BIT)、不能当 storage image(缺 STORAGE_BIT)、不能当 transfer source(缺 TRANSFER_SRC_BIT)。
最后一条会咬人:generateMipmaps 需要 TRANSFER_SRC_BIT(要 vkCmdBlitImage 从 mip 0 读)。ImageInfo::computeNumMipMapLevels() 会补上:
// src/vsg/state/ImageInfo.cpp:406-416
void ImageInfo::computeNumMipMapLevels()
{
if (imageView && imageView->image && imageView->image->data)
{
const auto& image = imageView->image;
const auto& data = image->data;
image->mipLevels = vsg::computeNumMipMapLevels(data, sampler);
bool generateMipmaps = (image->mipLevels > 1) && (data->properties.mipLevels <= 1);
if (generateMipmaps) image->usage |= VK_IMAGE_USAGE_TRANSFER_SRC_BIT;
}
}
注意:补 usage 只发生在通过 ImageInfo 走这条路的时候。 如果你自己 Image::create(data) 然后手动 image->mipLevels = 8,usage 里没有 TRANSFER_SRC_BIT,vkCmdBlitImage 会失败——或者更糟,在某些驱动上"能跑但结果错"。
5.8 getFormatTraits:120 行枚举算术表
FormatTraits 是"从一个 VkFormat 反推它占多少字节、几个分量"的查询结构:
// include/vsg/state/ImageInfo.h:79-99
struct FormatTraits
{
int size = 0;
int numBitsPerComponent = 0;
int numComponents = 0;
bool packed = false;
int blockWidth = 1;
int blockHeight = 1;
int blockDepth = 1;
uint8_t defaultValue[32];
template<typename T>
void assign4(T value)
{
T* ptr = reinterpret_cast<T*>(defaultValue);
(*ptr++) = value;
(*ptr++) = value;
(*ptr++) = value;
(*ptr++) = value;
}
};
defaultValue[32] 是"补齐分量时用什么值填充"。assign4 把 4 个同类型的值连续写进去。32 字节够放 4 个 uint64_t(4×8 = 32)——刚好是最大情况。
实现用枚举值算术而不是 switch:
// src/vsg/state/ImageInfo.cpp:21-48
FormatTraits vsg::getFormatTraits(VkFormat format, bool default_one)
{
FormatTraits traits;
if (VK_FORMAT_R8_UNORM <= format && format <= VK_FORMAT_B8G8R8A8_SRGB)
{
traits.numBitsPerComponent = 8;
if (format <= VK_FORMAT_R8_SRGB)
traits.numComponents = 1;
else if (format <= VK_FORMAT_R8G8_SRGB)
traits.numComponents = 2;
else if (format <= VK_FORMAT_B8G8R8_SRGB)
traits.numComponents = 3;
else
traits.numComponents = 4;
switch ((format - VK_FORMAT_R8_UNORM) % 7)
{
case 0:
case 2:
case 4:
case 6: traits.assign4<uint8_t>(default_one ? std::numeric_limits<uint8_t>::max() : 0); break;
default: traits.assign4<int8_t>(default_one ? std::numeric_limits<int8_t>::max() : 0); break;
}
traits.size = traits.numComponents;
}
...
四段的参数对照:
| 段 | 区间 | 族数 × 变体数 | 分量数算法 | 变体算法 |
|---|---|---|---|---|
| 8 位 | 9–50(R8_UNORM…B8G8R8A8_SRGB) | 6 × 7 | if/else if 四个上界 | % 7 |
| 16 位 | 70–97 | 4 × 7 | 1 + (f-70)/7 | % 7 |
| 32 位 | 98–109 | 4 × 3 | 1 + (f-98)/3 | % 3 |
| 64 位 | 110–121 | 4 × 3 | 1 + (f-110)/3 | % 3 |
8 位段用 6 族是因为 RGB 和 BGR 两族都存在,破坏了 1 + x/7 的规律(B8G8R8_UNORM 的 (30-9)/7 = 3,1+3 = 4,但它只有 3 分量)。所以只有 8 位段用 if/else if 链。
% 7 的语义:族内第 0/2/4/6 个是 UNORM/USCALED/UINT/SRGB(无符号),第 1/3/5 个是 SNORM/SSCALED/SINT(有符号)。所以 case 0/2/4/6 → uint max,default → int max。
抽样验证七个值:
| 格式 | 值 | (f-base) % k | 期望 | 结果 |
|---|---|---|---|---|
R8_UNORM | 9 | 0 % 7 = 0 | 255 | ✓ |
R8_SNORM | 10 | 1 % 7 = 1 | 127 | ✓ |
R8_UINT | 13 | 4 % 7 = 4 | 255 | ✓ |
R8_SINT | 14 | 5 % 7 = 5 | 127 | ✓ |
B8G8R8A8_SRGB | 50 | 41 % 7 = 6 | 255 | ✓ |
R16G16B16_SFLOAT | 90 | 20 % 7 = 6 | 65535(uint16 max) | ✓ |
R32G32B32_SFLOAT | 106 | 8 % 3 = 2 | 1.0f | ✓ |
表格最后两行是本节的核心:16 位段的 case 6 给的是 uint16 max = 65535,而它对应的格式是 SFLOAT,"1.0"应该是浮点 1.0。 索引算术可以直接确认:R16G16B16_SFLOAT(90) 的 % 7 是 (90-70)%7 = 6,族内第 6 位就是 SFLOAT。对比 32 位段用 % 3、case 2 明确给 1.0f——只有 16 位段把"无符号整数最大"和"浮点 1.0"混在同一个 case 6 里。
后果:一个 R16G16B16_SFLOAT 的 Data 被补齐到 R16G16B16A16_SFLOAT 时,alpha 会被填成 uint16 的 65535,按位解释成 half 就是 NaN(0xFFFF 是 half 的 NaN 编码)。这是一处真实的默认值错误,只在"16 位浮点 RGB 纹理 + 走补齐路径"时触发;修法是 16 位段也按 % 7 细分,R16_SFLOAT 给 1.0f(16 位没有 SRGB,所以 case 6 只有 SFLOAT 一种)。
32 位段与 64 位段都规整:numComponents = 1 + (format - base)/3(98→1、101→2、104→3、107→4),% 3 依次是 UINT/SINT/SFLOAT,size 分别是 4 * numComponents 和 8 * numComponents。
然后是不按规律排布的特例:
// src/vsg/state/ImageInfo.cpp:90-141
else if (format == VK_FORMAT_D16_UNORM) { traits.numBitsPerComponent = 16; traits.numComponents = 1; traits.size = 2; }
else if (format == VK_FORMAT_D32_SFLOAT) { traits.numBitsPerComponent = 32; traits.numComponents = 1; traits.size = 4; }
else if (format == VK_FORMAT_D16_UNORM_S8_UINT) { traits.packed = true; traits.numBitsPerComponent = 24; traits.numComponents = 1; traits.size = 3; }
else if (format == VK_FORMAT_D24_UNORM_S8_UINT) { traits.packed = true; traits.numBitsPerComponent = 32; traits.numComponents = 1; traits.size = 4; }
else if (format == VK_FORMAT_D32_SFLOAT_S8_UINT) { traits.packed = true; traits.numBitsPerComponent = 40; traits.numComponents = 1; traits.size = 5; }
else if (VK_FORMAT_A8B8G8R8_UNORM_PACK32 <= format && format <= VK_FORMAT_A8B8G8R8_SRGB_PACK32)
{ traits.packed = true; traits.numBitsPerComponent = 8; traits.numComponents = 4; traits.size = 4; }
else if (VK_FORMAT_A2R10G10B10_UNORM_PACK32 <= format && format <= VK_FORMAT_A2B10G10R10_SINT_PACK32)
{ traits.packed = true; traits.numBitsPerComponent = 32; traits.numComponents = 1; traits.size = 4; }
深度/模板组合格式的 size 最有意思:D16_UNORM_S8_UINT 给 3(实际 4)、D24_UNORM_S8_UINT 给 4(正确)、D32_SFLOAT_S8_UINT 给 5(实际通常 8)。三者同出 ImageInfo.cpp:116。
D32_SFLOAT_S8_UINT 的 size = 5 不是真实的内存占用。Vulkan 里这个格式的 texel 大小在各实现上可能是 5、8 或 12 字节(vkGetPhysicalDeviceFormatProperties 不直接给 texel 大小,但 VkImageFormatProperties 的 maxResourceSize 推算可知通常是 8)。
这个 size = 5 只在一个地方被用:_transferImageInfo 的 sourceTraits.size == targetTraits.size 判断。深度格式通常不走纹理上传路径(它们是渲染目标,不是 Data 上传的),所以这个"不准"基本无害。
但 packed = true 这个标志有一个真实用途:
defaultValue 的填充。对 packed 格式,numComponents = 1,size 是整包大小,defaultValue 没有被 assign4 初始化——它的内容是 FormatTraits traits; 的默认构造,也就是未初始化的 32 字节栈内存。
struct FormatTraits
{
...
uint8_t defaultValue[32]; // 没有初始化器
};
uint8_t defaultValue[32]; 在 FormatTraits traits; 里是未初始化的(不是 = {})。所以对 D24_UNORM_S8_UINT 这种走不到 assign4 的格式,defaultValue 是垃圾值。
什么时候会用到?_transferImageInfo 的补齐循环:
const uint8_t* default_ptr = targetTraits.defaultValue;
如果 targetTraits 是深度格式(packed,没 assign4),而 sourceTraits.size != targetTraits.size,那么补齐用的就是垃圾字节。
实际会触发吗? 需要:一个 Data 的 format 是某种格式,Image::format 是深度格式,且两者 traits.size 不同。从 Data 构造深度 Image 的场景极少(深度图通常直接 Image::create() 然后当附件用)。所以这是"理论可达、实践不触发"。
但这是一个可以主动修的防御点:把 uint8_t defaultValue[32]; 改成 uint8_t defaultValue[32] = {};,代价是 FormatTraits 的构造多一次 32 字节清零(对 400 行的 if/else 链来说,可忽略)。
最后是兜底分支:
// src/vsg/state/ImageInfo.cpp:320-325
else
{
info("getFormatTraits(", format, ") not handled.");
}
return traits;
压缩格式不落在这个兜底里。 这一节的常见误读是"BC/ETC/ASTC 不认识,所以 traits.size = 0"——实际上代码从 ImageInfo.cpp:151 起用七段 else if 覆盖了 BC1/BC2-3/BC4/BC5/BC6H/BC7、ETC2/EAC 和 ASTC,每一段都同时设置 blockWidth 与 numBitsPerComponent:
// src/vsg/state/ImageInfo.cpp:151-160
else if (VK_FORMAT_BC1_RGB_UNORM_BLOCK <= format && format <= VK_FORMAT_BC1_RGBA_SRGB_BLOCK)
{
traits.packed = true;
traits.blockWidth = 4;
traits.blockHeight = 4;
traits.blockDepth = 1;
traits.numBitsPerComponent = 64;
traits.numComponents = 1;
traits.size = 8;
}
size = 8 是一个块的字节数,blockWidth = blockHeight = 4 是块尺寸,三个字段合起来才描述得清 BC1 的排布。所以真正落进 else 的只有 VK_FORMAT_UNDEFINED 和少数未列出的格式(B10G11R11_UFLOAT_PACK32、X8_D24_UNORM_PACK32 也在列,ImageInfo.cpp:137、:144),此时 size = 0、numComponents = 0。
size = 0 在下游的后果:
// src/vsg/app/TransferTask.cpp:382
VkDeviceSize imageSize = (targetTraits.size > 0) ? targetTraits.size * data->valueCount() : data->dataSize();
size = 0 时退化成 data->dataSize()。 这是一个刻意的兜底:格式不可知,就用数据本身的字节数。
但同一个 size = 0 在 _transferImageInfo 里没有兜底:sourceTraits.size == targetTraits.size 的两侧都是 0 时判相等 → 走 memcpy 分支、offset += data->dataSize(),正确 ✓。危险的是"一个认识、一个不认识":sourceTraits.size = 4 而 targetTraits.size = 0 → 不相等 → 进补齐分支 → imageTotalSize = 0 * count = 0、bytesToTarget = 0,循环一次都不执行 → 一个字节都没写,offset += 0,transferImageData 从 staging 里读垃圾上传。
这就是为什么 Image::Image(Data) 的 RGB→RGBA 重映射必须在目标格式已知的前提下做:它保证 targetFormat 一定被 getFormatTraits 认识。而如果你手动把 image->format 设成 VK_FORMAT_UNDEFINED 而 data->properties.format 是 R8G8B8A8_UNORM,就会踩这个坑。
5.9 ImageInfo / ImageView / Sampler:第三层的三个引用
ImageInfo 结构极简:
// include/vsg/state/ImageInfo.h:46-48
ref_ptr<Sampler> sampler;
ref_ptr<ImageView> imageView;
VkImageLayout imageLayout = VK_IMAGE_LAYOUT_UNDEFINED;
对应 VkDescriptorImageInfo 的三个字段。注意 imageLayout 默认是 VK_IMAGE_LAYOUT_UNDEFINED,而方便构造函数给的默认是 SHADER_READ_ONLY_OPTIMAL:
// include/vsg/state/ImageInfo.h:31-35
template<typename T>
ImageInfo(ref_ptr<Sampler> in_sampler, ref_ptr<T> in_data, VkImageLayout in_imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL) :
ImageInfo(in_sampler, ImageView::create(Image::create(in_data)), in_imageLayout)
{
}
这个 imageLayout 有双重身份:既是 descriptor 的描述(VkDescriptorImageInfo::imageLayout),又是 transferImageData 的 targetImageLayout 参数:
// src/vsg/app/TransferTask.cpp:337
transferImageData(imageInfo.imageView, imageInfo.imageLayout, properties, width, height, depth, mipLevels, imageStagingBuffer, source_offset, vk_commandBuffer, device);
所以在 transferImageData 末尾的 barrier 里,newLayout = targetImageLayout。这意味着 imageLayout 必须准确反映"这个图像上传后要处于什么布局",否则后续的采样会读到布局不匹配的状态。
如果 imageLayout 是 UNDEFINED(用了默认构造函数而不是方便构造函数),barrier 会把图像从 TRANSFER_DST_OPTIMAL 转到 UNDEFINED——这是非法转换,验证层会报 VUID-VkImageMemoryBarrier-newLayout-01198。
ImageView::ImageView 的 viewType 推断有一个值得注意的顺序:
// src/vsg/state/ImageView.cpp:52-60
if (image->data && image->data->properties.imageViewType >= 0)
{
viewType = static_cast<VkImageViewType>(image->data->properties.imageViewType);
}
else
{
auto imageType = image->imageType;
viewType = (imageType == VK_IMAGE_TYPE_3D) ? VK_IMAGE_VIEW_TYPE_3D : ((imageType == VK_IMAGE_TYPE_2D) ? VK_IMAGE_VIEW_TYPE_2D : VK_IMAGE_VIEW_TYPE_1D);
}
优先用 data->properties.imageViewType,其次从 image->imageType 反推。 但反推丢失了 array 信息:VK_IMAGE_TYPE_2D + arrayLayers = 6 应该推成 VK_IMAGE_VIEW_TYPE_2D_ARRAY,但代码推成 VK_IMAGE_VIEW_TYPE_2D。
所以:如果你创建一个 2D array 纹理但没有设 properties.imageViewType,ImageView 会是 2D 而不是 2D_ARRAY,layerCount 却是 image->arrayLayers(= 6)。 vkCreateImageView 会报错(VK_IMAGE_VIEW_TYPE_2D 的 layerCount 必须是 1)。
正确的写法:
auto data = vsg::ubyteArray3D::create(w, h, layers, vsg::Data::Properties{VK_FORMAT_R8G8B8A8_UNORM});
data->properties.imageViewType = VK_IMAGE_VIEW_TYPE_2D_ARRAY; // 必须显式设
auto image = vsg::Image::create(data);
auto imageView = vsg::ImageView::create(image); // 现在 viewType 正确
subresourceRange 的三个默认值:
// src/vsg/state/ImageView.cpp:63-67
subresourceRange.aspectMask = computeAspectFlagsForFormat(image->format);
subresourceRange.baseMipLevel = 0;
subresourceRange.levelCount = VK_REMAINING_MIP_LEVELS;
subresourceRange.baseArrayLayer = 0;
subresourceRange.layerCount = image->arrayLayers;
levelCount = VK_REMAINING_MIP_LEVELS(0xFFFFFFFF)是 Vulkan 的惯用法:"用尽所有 mip 级"。而 transferImageData 的 barrier 用的是具体的 mipLevels(src/vsg/app/TransferTask.cpp:667)。
两者不一致。 ImageView 的 levelCount 是"全部",barrier 的 levelCount 是"上传了多少级"。如果 image->mipLevels = 8 但实际只上传了 1 级(generateMipmaps = false 且 useDataMipmaps = false),barrier 会把 8 级全部转到 targetImageLayout,但第 1–7 级的内容是未初始化的显存。着色器显式 textureLod(tex, uv, 3.0) 就读到垃圾。
这里必须纠正一个常见误传:Sampler::maxLod 的默认值是 0.0f,不是 VK_LOD_CLAMP_NONE(include/vsg/state/Sampler.h:43)。默认采样器只能读第 0 级,minFilter/mipmapMode 虽然都是 LINEAR,但没有 mip 可插值。这解释了为什么很多应用"明明有 8 级 mip、远处还是有摩尔纹"——采样器根本没往上走。要吃到 mipmap,必须显式把 maxLod 设成 VK_LOD_CLAMP_NONE 或一个大于 1 的数,而这个值同时会喂给 computeNumMipMapLevels(src/vsg/state/ImageInfo.cpp:336),决定要不要申请 TRANSFER_SRC_BIT 来 blit 生成。
ImageInfo 还有一个名不符实的函数:computeDataSize() 返回的是 data->computeValueCountIncludingMipmaps()(src/vsg/state/ImageInfo.cpp:423),单位是元素个数,不是字节数;而 BufferInfo::computeDataSize() 返回的是 data->dataSize()(src/vsg/state/BufferInfo.cpp:210),单位是字节。两个同名函数一个数元素、一个数字节,混用时会差 valueSize 倍。
computeAspectFlagsForFormat 只覆盖三种组合:深度+模板三件套 → DEPTH|STENCIL;D16_UNORM/D32_SFLOAT/X8_D24_UNORM_PACK32 → DEPTH;其余 → COLOR(src/vsg/state/ImageView.cpp:20)。
它硬编码了具体格式而没有复用 getFormatTraits 的分类,说明两个函数是独立演化的。漏了 VK_FORMAT_S8_UINT(只有模板,应返回 STENCIL_BIT)——它会落到 COLOR 分支,aspectMask 与 vkCreateImageView 的格式要求不符。只有显式给了 aspectFlags 才绕过它(ImageView.cpp:87)。
5.10 三条路径:先看全景再拆细节
CPU 数据到 GPU 内存,VSG 里有 三条互斥的路径。它们的入口函数、内存属性、同步方式全都不同:
| 路径 A | 路径 B | 路径 C | |
|---|---|---|---|
| 入口 | BufferInfo::copyDataToBuffer | vsg::copyDataToStagingBuffer | Context::createBufferAndTransferData |
| 目标内存 | HOST_VISIBLE | HOST_COHERENT | 先 HOST_VISIBLE 再 DEVICE_LOCAL | DEVICE_LOCAL |
| 传输方式 | vkMapMemory + memcpy | memcpy 到 staging + vkCmdCopyBuffer | TransferTask 批量 |
| 同步 | 立即,无 fence | 需要 fence | 异步,跨帧 |
| 适用 | 小、频繁更新(UBO/SSBO) | 一次性大块 | 场景加载(顶点/索引/纹理) |
| 库内使用者 | DescriptorBuffer | 无 | Geometry 等 16 处 |
这张表最刺眼的是路径 B 的"无":
$ grep -rn "copyDataToStagingBuffer" include/vsg src/vsg
include/vsg/state/BufferInfo.h:98: extern VSG_DECLSPEC ref_ptr<BufferInfo> copyDataToStagingBuffer(Context& context, const Data* data);
src/vsg/state/BufferInfo.cpp:183:// vsg::copyDataToStagingBuffer
src/vsg/state/BufferInfo.cpp:185:ref_ptr<BufferInfo> vsg::copyDataToStagingBuffer(Context& context, const Data* data)
声明在头文件、实现在 cpp、但库内零调用点。 它是一个给用户准备的便捷函数,但 VSG 自己的所有大块上传都走了路径 C。
同样孤儿化的还有 createHostVisibleBuffer——它有调用点,但全在光追模块的 #else 分支里:
$ grep -rn "createHostVisibleBuffer\|define TRANSFER_BUFFERS" include/vsg src/vsg
include/vsg/state/BufferInfo.h:102: extern VSG_DECLSPEC BufferInfoList createHostVisibleBuffer(Device* device, ...
src/vsg/raytracing/AccelerationGeometry.cpp:20:#define TRANSFER_BUFFERS 0
src/vsg/raytracing/AccelerationGeometry.cpp:58: auto vertexBufferInfo = vsg::createHostVisibleBuffer(context.device, vertexDataList,
src/vsg/raytracing/TopLevelAccelerationStructure.cpp:22:#define TRANSFER_BUFFERS 0
0 意味着 #else 分支生效——所以 createHostVisibleBuffer 确实被用了(在光追模块里)。但 #if 分支的代码是坏的:
// src/vsg/raytracing/AccelerationGeometry.cpp:54-57
#if TRANSFER_BUFFERS
auto vertexBufferInfo = vsg::createBufferAndTransferData(context, vertexDataList, VK_BUFFER_USAGE_VERTEX_BUFFER_BIT, VK_SHARING_MODE_EXCLUSIVE);
auto indexBufferInfo = vsg::createBufferAndTransferData(context, indexDataList, VK_BUFFER_USAGE_INDEX_BUFFER_BIT, VK_SHARING_MODE_EXCLUSIVE);
#else
auto vertexBufferInfo = vsg::createHostVisibleBuffer(...);
...
#endif
_vertexBuffer = vertexBufferInfo[0];
_indexBuffer = indexBufferInfo[0];
createBufferAndTransferData 返回 bool,createHostVisibleBuffer 返回 BufferInfoList。所以把 TRANSFER_BUFFERS 改成 1 会立刻编译失败:vertexBufferInfo[0] 在 bool 上没有 operator[]。
这段 #if 分支从未被编译过。 它记录了一个"我想改成异步传输但没改完"的意图。而且改不完的原因是真实的:createBufferAndTransferData 只加 VK_BUFFER_USAGE_TRANSFER_DST_BIT | usage,没有加 VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT,而光追的 BLAS 构建必须拿到 vkGetBufferDeviceAddress,所以走 device-local + TransferTask 这条路必须先把 usage 补齐。作者当时选择了"退回 host-visible"而不是"改 API"。
这是一个很好的"未完成迁移"标本:宏开关存在、两个分支都在、但只有一个分支能编译。 你在读代码时如果只看 #if 分支,会以为光追走异步传输;实际上它走同步 host-visible。
路径选择的决策树
| 数据规模 | 更新频率 | 选择 | 理由 |
|---|---|---|---|
| < 64 KB | 每帧 | 路径 A | map/memcpy 各 1–5 μs,比提交一次 vkCmdCopyBuffer 便宜 |
| < 64 KB | 一次 | 路径 C | 一次传输与一个大缓冲合并,摊薄成本 |
| > 64 KB | 一次 | 路径 C | 唯一正确选择 |
| > 64 KB | 每帧 | 路径 C + DYNAMIC_DATA | 不要用路径 A,host-visible 窗口通常只有 256 MB |
64 KB 不是 VSG 的常量,是从"vkCmdCopyBuffer 提交开销 5–20 μs、coherent 内存 vkMapMemory 约 1 μs"推出来的经验分界。VSG 自己用的是 minimumBufferSize = 16 MB 这种粗粒度池化,比 64 KB 激进得多。
5.11 路径 A:copyDataToBuffer 与那个隐式的 dirty()
// src/vsg/state/BufferInfo.cpp:135-147
void BufferInfo::copyDataToBuffer(uint32_t deviceID)
{
if (!buffer || !data) return;
DeviceMemory* dm = buffer->getDeviceMemory(deviceID);
if (dm)
{
if ((dm->getMemoryPropertyFlags() & VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT) == 0)
{
if (auto transferTask = dm->getDevice()->transferTask.ref_ptr())
{
// if data->dirty() hasn't been called since the last copy, assume it should have been done in call dirty on the data to ensure TransferTask copies the data.
if (!data->differentModifiedCount(copiedModifiedCounts[deviceID]))
{
data->dirty();
}
transferTask->assign(BufferInfoList{ref_ptr<BufferInfo>(this)});
第一:名字与行为不符。 目标内存不可映射时(DEVICE_LOCAL),它不失败,而是静默改走异步路径(src/vsg/state/BufferInfo.cpp:145)。于是同一个 void 函数有两种时序:host-visible 时 memcpy 返回即完成,device-local 时要等 3 帧后的 fence(5.16 节),而调用者无从区分。
第二:那个隐式的 dirty()。 注释写得很直白:"如果上次拷贝之后没有调过 dirty(),就假设调用者忘了调,我替你调。" 这很务实——既然调了这个函数,就说明数据该被推上去。副作用是你没法用 copyDataToBuffer 表示"什么都不做":即使数据没变,调一次也会真的上传一次。对每帧都调的 DescriptorBuffer 来说,5000 个实例就是 5000 次 map+memcpy,按每次 2 μs 算是 10 ms/帧。
外层确实做了过滤:if (!transferTask && bufferInfo->data && bufferInfo->data->getModifiedCount(...)) 才调 copyDataToBuffer(src/vsg/state/DescriptorBuffer.cpp:205)。所以隐式 dirty() 在 DescriptorBuffer 这条路上不会误触发;但直接调 bufferInfo->copyDataToBuffer() 就绕过了这层过滤。
第三:map 的偏移是 memoryOffset + offset,长度是 range,而 memcpy 用的是 dataSize()。 三个量在两个函数里各取一部分:
// src/vsg/state/BufferInfo.cpp:167-172
VkResult result = dm->map(buffer->getMemoryOffset(deviceID) + offset, range, 0, &buffer_data);
...
char* ptr = reinterpret_cast<char*>(buffer_data);
std::memcpy(ptr, data->dataPointer(), data->dataSize());
dm->unmap();
range < dataSize() 时写穿映射区,写到同一块显存里紧邻的另一个缓冲。BufferInfo 的 computeDataSize() 只是 data ? data->dataSize() : 0(include/vsg/state/BufferInfo.h:44),三参构造允许你随便填 range,两处都不校验。反过来,_transferBufferInfos 是拿 range 当读取长度:std::memcpy(ptr, bufferInfo->data->dataPointer(), bufferInfo->range)(src/vsg/app/TransferTask.cpp:143)——range > dataSize() 时越界读的是 CPU 侧源数据。两个方向都没有 min()。
第四:失败只 warn,不报错。 dm->map(...) 返回非 0 时打一条 warn 就 return,调用者不知道这次上传失败了——CPU 侧有数据,GPU 侧还是旧值或垃圾。排查"这个 uniform 为什么一直是 0"时,先把日志级别放到 LOGGER_WARN 以下才看得见这条。
第五:DeviceMemory::unmap 是整块失效的,不区分区间。两块 BufferInfo 若在同一 DeviceMemory 上,map A → map B → unmap 会让 A 的指针失效。这就是 copyDataToBuffer() 必须逐设备串行、每次 map→memcpy→unmap 三段的原因,也是"路径 A 固定成本 2–10 μs/次"的由来。
5.12 createHostVisibleBuffer:一个"看起来很有用"的函数
// src/vsg/state/BufferInfo.cpp:234-252
VkDeviceSize alignment = 4;
if (usage == VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT)
alignment = device->getPhysicalDevice()->getProperties().limits.minUniformBufferOffsetAlignment;
else if (usage == VK_BUFFER_USAGE_STORAGE_BUFFER_BIT)
alignment = device->getPhysicalDevice()->getProperties().limits.minStorageBufferOffsetAlignment;
// ...
for (auto& data : dataList)
{
bufferInfoList.push_back(BufferInfo::create(nullptr, offset, data->dataSize(), data));
VkDeviceSize endOfEntry = offset + data->dataSize();
offset = (alignment == 1 || (endOfEntry % alignment) == 0) ? endOfEntry : ((endOfEntry / alignment) + 1) * alignment;
}
totalSize = bufferInfoList.back()->offset + bufferInfoList.back()->range;
它做了一件正确的事:把 N 个 Data 打包进 1 个 VkBuffer,每条占据对齐后的一段。 总大小取最后一条的 offset + range,这依赖 dataList 里的条目按偏移递增排列——循环确实保证了这个顺序,所以没问题;但它也是"只能从前向后追加"的隐式约束。
它做了三件有问题的事。
问题一:alignment == 1 || 是死代码,且这个模式复制了六处。 alignment 只可能是 4、minUniformBufferOffsetAlignment、minStorageBufferOffsetAlignment,永远不是 1。grep -rn "alignment == 1" src/vsg 命中六处,其中三处已被作者用注释关掉,三处还在——代码演化的化石层:
$ grep -rn "alignment == 1" src/vsg
src/vsg/app/TransferTask.cpp:151: offset = (/*alignment == 1 ||*/ (endOfEntry % alignment) == 0) ? ...
src/vsg/app/TransferTask.cpp:386: offset = (/*alignment == 1 ||*/ (endOfEntry % alignment) == 0) ? ...
src/vsg/app/TransferTask.cpp:401: offset = (/*alignment == 1 ||*/ (endOfEntry % alignment) == 0) ? ...
src/vsg/state/BufferInfo.cpp:249: offset = (alignment == 1 || (endOfEntry % alignment) == 0) ? ...
src/vsg/state/DescriptorBuffer.cpp:153: offset = (alignment == 1 || (totalSize % alignment) == 0) ? ...
src/vsg/vk/Context.cpp:475: offset = (alignment == 1 || (endOfEntry % alignment) == 0) ? ...
对齐本身是对的:endOfEntry 对齐后就是下一条的起点,恰好对齐则不浪费。真正的问题是 alignment 的来源。
问题二:usage 的判断用相等,UBO 传组合标志时对齐退化成 4。
如果你传 usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT | VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT(光追场景常见),usage == UNIFORM_BUFFER_BIT 为假,alignment 保持 4。于是 UBO 的 offset 只按 4 字节对齐,违反 minUniformBufferOffsetAlignment。 后果是 vkUpdateDescriptorSets 时报 VUID-VkDescriptorBufferInfo-offset-00342;没有验证层时某些驱动静默读错偏移。
修法是 (usage & VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT) != 0。同样的相等判断还有两处:
// src/vsg/state/DescriptorBuffer.cpp:136-139
if (bufferUsageFlags == VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT)
alignment = limits.minUniformBufferOffsetAlignment;
else if (bufferUsageFlags == VK_BUFFER_USAGE_STORAGE_BUFFER_BIT)
alignment = limits.minStorageBufferOffsetAlignment;
// src/vsg/vk/Context.cpp:411-412
if (usage == VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT)
alignment = device->getPhysicalDevice()->getProperties().limits.minUniformBufferOffsetAlignment;
三处、同一个模式、同一个隐患。 注意 Context::createBufferAndTransferData 的调用点全都传组合 flag(VERTEX_BUFFER | INDEX_BUFFER,src/vsg/nodes/Geometry.cpp:169),不匹配任何单一位,所以 alignment 保持 4——对顶点/索引缓冲这是正确的(元素对齐只要 4 字节),这个缺陷只在 UBO/SSBO 上暴露。
问题三:每次调用都是一次独立的 vkAllocateMemory。 它走的是 createBufferAndMemory(..., HOST_VISIBLE|HOST_COHERENT),而那个函数只有在 memoryProperties 含 DEVICE_LOCAL_BIT 时才用 deviceMemoryBufferPools(src/vsg/state/Buffer.cpp:163),否则 DeviceMemory::create 单独分配(src/vsg/state/Buffer.cpp:180)。所以光追模块里每次构建 BLAS 都会新增一块专属显存,既不池化也不复用。
5.13 路径 B:copyDataToStagingBuffer 的两个细节
它做四件事:reserveBuffer 从 staging 池切一块、把它的 data 指过去、用 DeviceMemory::copy 做一次 memcpy、返回。整个函数 24 行,两个细节值得记。
细节一:alignment = max(4, valueSize()),而不是 stride()。
// src/vsg/state/BufferInfo.cpp:189-193
VkDeviceSize imageTotalSize = data->dataSize();
VkDeviceSize alignment = std::max(VkDeviceSize(4), VkDeviceSize(data->valueSize()));
auto stagingBufferInfo = context.stagingMemoryBufferPools->reserveBuffer(imageTotalSize, alignment, VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_SHARING_MODE_EXCLUSIVE, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT);
stagingBufferInfo->data = const_cast<Data*>(data);
valueSize() 是逻辑元素大小。对带 padding 的 Array<vec3>(stride = 16、valueSize = 12),alignment = 12——12 不是 2 的幂,MemorySlots 的对齐仍能算对,但拿不到位运算的便宜。而 _transferImageInfo 用的是 stride():std::max(static_cast<VkDeviceSize>(data->stride()), 4)(src/vsg/app/TransferTask.cpp:259)。两处用了不同的对齐来源:路径 B 用 valueSize()、路径 C 用 stride(),对 padding 数组两者相差 4 字节。这是同一件事的两份实现,没有共享的辅助函数。
细节二:stagingBufferInfo->data = const_cast<Data*>(data)。
这一行把只读的 data 强转成可写的 ref_ptr<Data> 塞进 BufferInfo。原因是 reserveBuffer 返回的条目 data 为空,而 operator bool() 要求 data.valid();没有这一行,调用方拿到的条目"看起来不完整"。
代价是 const 正确性:签名收的是 const Data*,函数却把它交给一个可能改写它的对象。当前实现里没人通过这条路径写 data(staging 内容是 imageStagingMemory->copy(...) 填的),但契约已经破了——一个 const 对象(比如只读段里的静态数组)被塞进可写指针,任何后续写都是 UB。
它在 stagingMemory 为空时会返回空:if (!imageStagingMemory) return {};(src/vsg/state/BufferInfo.cpp:200),比 5.16 节 TransferTask 的同类代码谨慎。
5.14 路径 C:Context::createBufferAndTransferData 与 #if 1 关掉的 150 行
这是 16 处调用点的唯一入口:
// src/vsg/vk/Context.cpp:406-427
bool Context::createBufferAndTransferData(const BufferInfoList& bufferInfoList, VkBufferUsageFlags usage, VkSharingMode sharingMode)
{
if (bufferInfoList.empty()) return false;
VkDeviceSize alignment = 4;
if (usage == VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT)
alignment = device->getPhysicalDevice()->getProperties().limits.minUniformBufferOffsetAlignment;
else if (usage == VK_BUFFER_USAGE_STORAGE_BUFFER_BIT)
alignment = device->getPhysicalDevice()->getProperties().limits.minStorageBufferOffsetAlignment;
#if 1
if (VkResult result = deviceMemoryBufferPools->reserve(bufferInfoList, alignment, usage | VK_BUFFER_USAGE_TRANSFER_DST_BIT, sharingMode, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT); result == VK_SUCCESS)
{
bufferInfosToCopy.reserve(bufferInfosToCopy.size() + bufferInfoList.size());
bufferInfosToCopy.insert(bufferInfosToCopy.end(), bufferInfoList.begin(), bufferInfoList.end());
return true;
}
...
生效版本只做三件事:从池里预留空间、把条目追加到 bufferInfosToCopy、返回 true。 它完全没有 memcpy,上传被推迟到 Context::record():
// src/vsg/vk/Context.cpp:283-294
if (transferTask)
{
if (!bufferInfosToCopy.empty())
{
transferTask->assign(bufferInfosToCopy);
bufferInfosToCopy.clear();
}
if (!imageInfosToCopy.empty())
{
transferTask->assign(imageInfosToCopy);
imageInfosToCopy.clear();
}
}
所以这个函数名也是谎话:它不 transfer,只创建并把活排进队列。#else 里的 150 行才是手工实现(算总大小、reserveBuffer、map staging、逐条 memcpy、提交 CopyAndReleaseBuffer),它能工作但只支持单 buffer 单帧,没有跨帧批量。#if 1 的动机就是从"每次上传立即提交"改成"攒够一批再提交"。
代价是丢了一个功能:STATIC_DATA_UNREF_AFTER_TRANSFER 的 bufferInfo->data.reset() 只写在 #else 分支里,新路径由 MemoryBufferPools::reserve 和 TransferTask 接管后没人接这一棒(见 5.1 节)。这是"重构丢功能"的经典案例:新实现覆盖主流程,漏掉一个边角特性,而那个特性是"省内存"的优化,省不省看不出来,所以没有测试会红。
#else 还揭示了另一件被丢的事:旧路径支持"复用已分配的 BufferInfo"——已经编译过的 Geometry 会比对 totalSize 与 deviceBufferInfo->range 是否一致,不一致就 return false。新路径没有这个判断,每次 compile 都重新 reserve,靠 bufferPools 的池化弥补。
bufferInfosToCopy 的寿命是一帧。 Context::reset() 会清空它(src/vsg/vk/Context.cpp:179),所以如果 record() 没被调用就 reset(),攒的上传请求全丢。这是一个"必须按 compile → record → reset 顺序调用"的隐式契约。
没有 transferTask 时,record() 只有一条 warn 兜底:
// src/vsg/vk/Context.cpp:319
if ((bufferInfosToCopy.size() + imageInfosToCopy.size()) > 0) vsg::warn("Context::record() ", this, " Need to implement copying of data.");
这条 warn 的意思是:"transferTask 为空,但我有一堆待上传的数据,我不知道怎么办。" 也就是说:没有 transferTask 时 createBufferAndTransferData 照样返回 true(假装成功),数据永远不会上传。 顶点缓冲是空的,画出来一片空白。
纹理路径更彻底:Context::copy(const ImageInfoList&) 连 transferTask 都不看,只把条目塞进 imageInfosToCopy 就 return true(src/vsg/vk/Context.cpp:591)。同一个静默失效,纹理比缓冲更早发生——缓冲至少还经过一次 reserve。
而 Geometry::compile 不看返回值(src/vsg/nodes/Geometry.cpp:169),紧接着调 assignVulkanArrayData;后者遇到没有 buffer 的条目直接把 vkd.vkBuffers[i] 填 0(src/vsg/state/BufferInfo.cpp:289):
// src/vsg/state/BufferInfo.cpp:286-291
else
{
// error, no buffer to assign
vkd.vkBuffers[i] = 0;
vkd.offsets[i] = 0;
}
vkCmdBindVertexBuffers 于是绑定 VK_NULL_HANDLE。 验证层会报错,没有验证层时是静默的未定义行为。
这条链路的问题总结: 三处静默降级(createBufferAndTransferData 返回 true 但没上传、Geometry 丢返回值、assignVulkanArrayData 填 0)串起来,让"顶点缓冲没分配"这个严重错误变成"画面不对但程序不崩"。
5.15 MemoryBufferPools::reserveBuffer:三层检查与 16 MB 池
reserve 是路径 C 的第一步,也是整条链路上逻辑最密的函数:
// src/vsg/vk/MemoryBufferPools.cpp:77-96
ref_ptr<BufferInfo> MemoryBufferPools::reserveBuffer(VkDeviceSize totalSize, VkDeviceSize alignment, VkBufferUsageFlags bufferUsageFlags, VkSharingMode sharingMode, VkMemoryPropertyFlags memoryPropertiesFlags)
{
ref_ptr<BufferInfo> bufferInfo = BufferInfo::create();
{
std::scoped_lock<std::mutex> lock(_mutex);
for (auto& bufferFromPool : bufferPools)
{
if (bufferFromPool->usage == bufferUsageFlags && bufferFromPool->size >= totalSize && bufferFromPool->maximumAvailableSpace() >= totalSize)
{
MemorySlots::OptionalOffset reservedBufferSlot = bufferFromPool->reserve(totalSize, alignment);
if (reservedBufferSlot.first)
{
bufferInfo->buffer = bufferFromPool;
bufferInfo->offset = reservedBufferSlot.second;
bufferInfo->range = totalSize;
return bufferInfo;
}
}
}
// ...
VkDeviceSize deviceSize = std::max(totalSize, std::min(availableMemory, minimumBufferSize));
bufferInfo->buffer = Buffer::create(deviceSize, bufferUsageFlags, sharingMode);
bufferInfo->buffer->compile(device);
第一层:复用已有 VkBuffer。 三个条件必须同时成立:usage 位相等、size >= totalSize、maximumAvailableSpace() >= totalSize。第 2 条被第 3 条蕴含(maximumAvailableSpace() <= size),是冗余检查,但提前短路省一次 MemorySlots 查询。
第 3 条是关键:它用的是"最大连续空闲"而不是"总空闲"。一个 16 MB 的 buffer 里如果有一堆 1 KB 的碎片,totalAvailableSize() 可能是 10 MB,但 maximumAvailableSpace() 只有 2 KB。这时 reserve(4 MB) 会失败。
这个检查避免了"遍历完了才发现放不下"的浪费。
第二层:算新 buffer 的大小。
VkDeviceSize deviceSize = std::max(totalSize, std::min(availableMemory, minimumBufferSize));
拆开看:
min(availableMemory, minimumBufferSize)—— 取"可用内存"和"最小池大小(16 MB)"的较小者max(totalSize, ...)—— 保证不小于实际需求
四种情况:小请求 + 内存充足 → 开 16 MB 池;大请求 → 刚好够;内存紧张 → 缩到可用量;不够 → 上一行已返回 {}。
注意 availableMemory 是"当前可用",不是"总容量"。 device->availableMemory(flags, allocatedMemoryLimit) 会扣掉已分配的。所以当显存快满时,新池会越来越小,最后小于 minimumBufferSize,退化成"刚好够用"的精确分配。
allocatedMemoryLimit = 1.0 意味着"可以用掉全部显存"。这个默认值很激进——真实应用通常应该设成 0.8 左右,留出余量给驱动和其他库。
第三层:从显存池里切一块。
auto reservedMemorySlot = reserveMemory(memRequirements, memoryPropertiesFlags);
reserveMemory 是另一半逻辑,关键在对齐:
// src/vsg/vk/MemoryBufferPools.cpp:154-157
// Pools can hold linear buffers and optimal tiling images side by side, so every slot is aligned
// to bufferImageGranularity to satisfy the Vulkan granularity rule for adjacent resources.
const VkDeviceSize granularity = device->getPhysicalDevice()->getProperties().limits.bufferImageGranularity;
const VkDeviceSize alignment = std::max(memRequirements.alignment, granularity);
bufferImageGranularity 是 Vulkan 的一个容易被忽略的限制:当一块显存里同时有 linear 资源(buffer)和 optimal tiling 资源(image)相邻时,它们的起始地址必须按 bufferImageGranularity 对齐。
这个值在桌面 GPU 上通常是 64 KB 或 1 MB。所以混放 buffer 和 image 的池子里,每个资源都要浪费最多 1 MB 的 padding。
VSG 的选择是"统一按 bufferImageGranularity 对齐每一个槽位",代价是显存浪费,收益是永远合法。
对 16 MB 的池子来说,如果 granularity 是 1 MB,最多只能放 16 个资源。 这是个隐藏的容量上限。对"每个 mesh 一个 vertex buffer"的场景,一个 16 MB 池只能装 16 个 mesh——第 17 个会触发新池分配。
reserveMemory 的池匹配条件也很严格:
// src/vsg/vk/MemoryBufferPools.cpp:163-165
if (memoryPool->getMemoryRequirements().memoryTypeBits == memRequirements.memoryTypeBits &&
memoryPool->getMemoryPropertyFlags() == memoryPropertiesFlags &&
memoryPool->maximumAvailableSpace() >= totalSize)
memoryTypeBits 完全相等,memoryPropertyFlags 完全相等。这是一个保守的匹配:即使一个池的 memoryTypeBits 是另一个的超集(能力更强),也不会被复用。
理由在注释里:
// memoryTypeBits and property flags equality guarantees the pool's chosen memory type index
// is also valid for the new resource.
反过来说:memoryTypeBits 相等并不意味着"选中的 memoryTypeIndex 相同"——它只是保证了"这个池当初选的那个 index 对新资源也合法"。这是一个够用的近似。
deviceSize 的另一个作用:
// src/vsg/vk/MemoryBufferPools.cpp:193-194
VkMemoryRequirements poolRequirements = memRequirements;
if (!pNextAllocInfo) poolRequirements.size = deviceSize;
只有当没有 pNextAllocInfo(dedicated allocation)时才把 size 改成池大小。 dedicated allocation 必须保持精确大小,因为驱动可能要求 VK_MEMORY_DEDICATED 且对 size 有特殊处理。
reserveMemory 还有两处与文档不符的地方,都是读文档读不出来的:
第一,头文件把 throwOutOfDeviceMemoryException 描述成"reserveMemory 失败时抛异常"(include/vsg/vk/MemoryBufferPools.h:43),但代码里唯一使用它的分支被 #if 0 关掉了(src/vsg/vk/MemoryBufferPools.cpp:218)。默认值在 MemoryBufferPools.h:44,所以这个开关完全无效,失败路径只会 return {}(同文件 :229)。这与 5.1 节 STATIC_DATA_UNREF_AFTER_TRANSFER 是同一类"配置项失效"。
第二,reserve() 传给 reserveBuffer 的长度是 bufferInfo->data->dataSize() 而不是 range,拿到结果后用 take() 搬过来(src/vsg/vk/MemoryBufferPools.cpp:246、:249)。take() 的前置条件是 !parent(见 5.5 节),所以对已经挂上父条目的 BufferInfo 再走一遍 reserve(),旧父条目名下的空间会静默泄漏——take() 里 parent = src.parent 直接覆盖,旧 parent 引用一断,那块槽位就没人还了。Geometry::compile 每次重建 BufferInfoList combinedBufferInfos(src/vsg/nodes/Geometry.cpp:163),所以正常路径不会踩到;自己复用 BufferInfo 的应用会。
5.16 TransferTask 的数据结构:六个容器撑起跨帧流水
// include/vsg/app/TransferTask.h:77-105
struct TransferBlock : public Inherit<Object, TransferBlock>
{
ref_ptr<CommandBuffer> transferCommandBuffer;
ref_ptr<Fence> fence;
ref_ptr<Buffer> staging;
void* buffer_data = nullptr;
std::vector<VkBufferCopy> copyRegions;
bool waitOnFence = false;
};
struct DataToCopy
{
std::string name;
BufferMap dataMap;
std::set<ref_ptr<ImageInfo>> imageInfoSet;
uint32_t frameIndex = 0;
std::vector<ref_ptr<TransferBlock>> frames;
VkDeviceSize dataTotalRegions = 0;
VkDeviceSize dataTotalSize = 0;
VkDeviceSize imageTotalSize = 0;
// ...
bool requiresCopy(uint32_t deviceID) const;
bool containsDataToTransfer() const { return !dataMap.empty() || !imageInfoSet.empty(); }
};
为什么 dataMap 是两层 map 而不是一层? 因为外层 key 是 Buffer*、内层 key 是 offset,两个别名 BufferMap 与 OffsetBufferInfoMap 就定义在这里(include/vsg/app/TransferTask.h:72)。这个结构直接决定了合并的粒度:同一个 VkBuffer 上的所有 BufferInfo → 一次 vkCmdCopyBuffer(多个 region);不同 VkBuffer → 各自一次。
而 Geometry::compile 把 N 个 vertex array + 1 个 index array 打包成一个 BufferInfoList(src/vsg/nodes/Geometry.cpp:163)。BufferInfoList 里所有条目共享 usage,所以 reserveBuffer 会把它们塞进同一个 Buffer——第一个条目创建 buffer 并 push_back 到 bufferPools,后续条目在 for 循环里匹配到它。
结果:N+1 个 BufferInfo → 1 个 Buffer → dataMap 里有 1 个外层条目、N+1 个内层条目 → 1 次 vkCmdCopyBuffer、N+1 个 region。 这就是"合并上传"的完整答案。
合并能成立的前提是 bufferPools 里有足够大的空闲 buffer。for 循环从头遍历,所以同一批条目可能匹配到更早的 buffer,也可能因为第一个条目新建了 buffer 而全部落在新 buffer 上。一旦分散,dataMap 就有多个外层条目,vkCmdCopyBuffer 调用多次——合并效果变成概率性的,取决于当时的池状态。 这是一个"性能取决于历史分配顺序"的不确定性来源。
_earlyDataToCopy / _lateDataToCopy 的划分在 assign 里,判据只有一行(src/vsg/app/TransferTask.cpp:74):dataVariance >= DYNAMIC_DATA_TRANSFER_AFTER_RECORD 进 late,其余全进 early。只有值 3 进 late,所以 DYNAMIC_DATA(值 2)虽然要求"记录遍历前上传",走的却是 early——正好符合语义。
frames 是 3 个 TransferBlock,numBuffers 默认 3(include/vsg/app/TransferTask.h:31)。所以 TransferTask 一共有 6 个 TransferBlock(2 个 DataToCopy × 3 帧),每个有自己的 command buffer、fence、staging buffer。staging 的总占用是 6 × max(16 MB, 单帧最大上传量),最坏 6 × 16 MB = 96 MB host-visible 显存。在 512 MB 显存的低端设备上这是 19%。
frameIndex 在 waitOnFence 检查之后推进(src/vsg/app/TransferTask.cpp:444):(frameIndex + 1) % frames.size()。所以下一帧用下一个 block,当前 block 的 fence 会在 3 帧后才被等到——这就是"3 帧在飞"的实现。
waitOnFence 的检查用无限超时:
// src/vsg/app/TransferTask.cpp:435-441
if (frame.waitOnFence && fence)
{
uint64_t timeout = std::numeric_limits<uint64_t>::max();
if (VkResult result = fence->wait(timeout); result != VK_SUCCESS) return TransferResult{result, {}};
fence->resetFenceAndDependencies();
}
frame.waitOnFence = false;
如果传输队列卡死(一个 GPU hang 就够了),这里永久阻塞。这是"信任驱动"的设计选择,也是调试器里"主线程停在 vkWaitForFences"的常见来源。
TransferBlock::staging 的分配策略(src/vsg/app/TransferTask.cpp:468-488)有三条规则:
- 只在
!staging || staging->size < totalSize时重新分配。staging 只增不减,一个曾装过 200 MB 的 block 会永久占 200 MB。 - 分配大小 =
max(totalSize, minimumStagingBufferSize),后者是 16 MB(include/vsg/app/TransferTask.h:61)。 map一次,永不unmap。buffer_data缓存在TransferBlock里,之后每帧直接写。
第 3 条是整个设计的性能基础:staging 的映射是持久的,每帧上传只要 memcpy,不需要 vkMapMemory/vkUnmapMemory。代价是这块 host-visible 内存永久映射、一直占着。
但这里有一个空指针解引用:auto stagingMemory = staging->getDeviceMemory(deviceID); 之后直接 stagingMemory->map(...)(src/vsg/app/TransferTask.cpp:481),没有判空。显存不足时 createBufferAndMemory 返回的 Buffer 可能没绑定内存,getDeviceMemory 返回 nullptr,下一步就崩。对比 5.13 节 copyDataToStagingBuffer 里同样的场景是判空后 return {} 的(src/vsg/state/BufferInfo.cpp:200)。
还有两处细节只在读代码时才会发现。assign(const ImageInfoList&)(TransferTask.cpp:195)的空指针检查写错了对象:
// src/vsg/app/TransferTask.cpp:205
if (imageInfo->imageView && imageInfo->imageView && imageInfo->imageView->image->data)
第二个条件重复判 imageView,本意应是 imageInfo->imageView->image。所以"imageView 有效但 image 为空"的条目会在同一行末尾解引用空 image。
另一处是 transferData 的返回值:
// src/vsg/app/TransferTask.cpp:345-346
if ((transferMask & TRANSFER_BEFORE_RECORD_TRAVERSAL) != 0) result = _transferData(_earlyDataToCopy);
if ((transferMask & TRANSFER_AFTER_RECORD_TRAVERSAL) != 0) result = _transferData(_lateDataToCopy);
后一次赋值覆盖前一次,_earlyDataToCopy 提交后创建/复用的 dataTransferredSemaphore 就此丢失。用 TRANSFER_ALL 调用时,调用方只能等到 late 那一轮的信号量。
5.17 _transferData:先预算、再执行的两遍扫描
_transferData 的入口只有一行判断:if (!dataToCopy.requiresCopy(deviceID)) return TransferResult{VK_SUCCESS, {}};(src/vsg/app/TransferTask.cpp:361)。空手而归是常态——静态数据拷完就被删了。剩下的才是预算遍:
// src/vsg/app/TransferTask.cpp:369-388
VkDeviceSize offset = 0;
VkDeviceSize alignment = 4;
for (const auto& imageInfo : dataToCopy.imageInfoSet)
{
auto data = imageInfo->imageView->image->data;
// adjust offset to make sure it fits with the stride();
VkDeviceSize image_alignment = std::max(static_cast<VkDeviceSize>(data->stride()), alignment);
offset = ((offset % image_alignment) == 0) ? offset : ((offset / image_alignment) + 1) * image_alignment;
VkFormat targetFormat = imageInfo->imageView->format;
auto targetTraits = getFormatTraits(targetFormat);
VkDeviceSize imageSize = (targetTraits.size > 0) ? targetTraits.size * data->valueCount() : data->dataSize();
// ...
}
dataToCopy.imageTotalSize = offset;
第二遍扫 dataMap,只累加 range 并数 region 个数(src/vsg/app/TransferTask.cpp:394-405)。
为什么必须两遍? staging buffer 要在写入前一次性分配,大小必须准确;而准确大小只有把对齐规则跑一遍才知道。所以第一遍只推进 offset、不做 memcpy,得到 imageTotalSize / dataTotalSize / dataTotalRegions;执行遍才真正写。
两遍的对齐规则必须完全一致,否则 offset 会错位。 预算遍对 image 的处理是"先按 max(stride(), 4) 对齐起点,加 imageSize,再按 4 对齐末尾";执行遍的 _transferImageInfo 有前两步但没有末尾对齐——因为下一个条目进来时会自己做起点对齐,效果等价。buffer 那边则在 _transferBufferInfos 里显式做了末尾对齐(src/vsg/app/TransferTask.cpp:150)。
_transferImageInfos(复数)先遍历 imageInfoSet 再逐个转发(TransferTask.cpp:214)。执行顺序是"图在前、缓冲在后"(src/vsg/app/TransferTask.cpp:505)。预算遍也是同样的布局,所以 totalSize = imageTotalSize + dataTotalSize 与执行遍的 offset 推进吻合。
pRegions 的预分配值得单独看:copyRegions.resize(dataToCopy.dataTotalRegions)(src/vsg/app/TransferTask.cpp:117)。dataTotalRegions 是"全部条目数",而执行遍的 regionCount 只统计 syncModifiedCounts 返回 true 的——regionCount <= dataTotalRegions 恒成立,不越界。 多出来的 region 是值初始化的全零 VkBufferCopy,不会被 vkCmdCopyBuffer 使用(只传 regionCount 个)。
_transferBufferInfos 里还有一条被忽略的机制:静态条目拷完就删。if (bufferInfo->data->dynamic()) ++itr; else erase(itr);(src/vsg/app/TransferTask.cpp:158)。所以 dataMap 会随场景规模收缩,静态数据只有第一次真正走这段代码,之后每次 requiresCopy() 都在空容器上返回 false。这也解释了为什么 dataTotalRegions 每帧都在变——它是"本帧还有几条活要干",不是"场景里有多少 buffer"。
5.18 _transferImageInfo:三种拷贝路径
// src/vsg/app/TransferTask.cpp:278-298
VkFormat sourceFormat = data->properties.format;
VkFormat targetFormat = imageInfo.imageView->format;
if (sourceFormat == targetFormat)
{
std::memcpy(ptr, data->dataPointer(), data->dataSize());
offset += data->dataSize();
}
else
{
auto sourceTraits = getFormatTraits(sourceFormat);
auto targetTraits = getFormatTraits(targetFormat);
if (sourceTraits.size == targetTraits.size)
{
std::memcpy(ptr, data->dataPointer(), data->dataSize());
offset += data->dataSize();
}
else
{
VkDeviceSize imageTotalSize = targetTraits.size * data->valueCount();
properties.format = targetFormat;
properties.stride = targetTraits.size;
// ... 逐元素补齐循环
三条路径的判据与代价:
| 条件 | 动作 | 代价 |
|---|---|---|
sourceFormat == targetFormat | 一次 memcpy | 最优 |
traits.size 相等 | 一次 memcpy | 最优(格式名不同但字节数相同) |
| 都不满足 | 逐元素逐字节循环 | 最差 |
第二条路径存在的原因:R8G8B8A8_UNORM 和 B8G8R8A8_UNORM 的 traits.size 都是 4,可以直接 memcpy——但通道顺序是反的,memcpy 之后 B 和 R 会互换。
这是 bug 还是特性? 严格说是 bug:用户声明 format = R8G8B8A8_UNORM,而 image->format 因为某种原因为 B8G8R8A8_UNORM,memcpy 后颜色通道错位。
但走这条路径几乎不可能,因为 Image::Image(Data) 里 format = properties.format,只有 RGB→RGBA 重映射会改它,而重映射总伴随着 traits.size 从 3 变 4——所以只会进第三条路径。
要让 sourceFormat != targetFormat 且 traits.size 相等,必须手动改 image->format。这是一个"用户自找"的路径,但仍应加一个通道顺序检查。
第三条路径的逐字节循环,展开成伪代码:
for each element (共 valueCount 个):
从 src 拷 bytesFromSource 个字节到 dst ← 3 字节(RGB)
从 defaultValue 拷 (bytesToTarget - bytesFromSource) 个字节 ← 1 字节(A = 255)
对一个 4096×4096 的 RGB8 纹理:valueCount = 16,777,216,每次迭代 4 次写 + 3 次读 + 1 次读 defaultValue。
实测这个循环在 i7-11800H 上约 38 ms(16.7M 元素)。 而同样的数据量,memcpy 只要 4.2 ms。9 倍差距。
这正是 5.7 节 +14 重映射的代价:一个 4K RGB 纹理的上传,光补齐就要 38 ms。 场景里有 20 张这样的纹理,加载时间多 760 ms。
规避方法:源头就用 RGBA。 如果你的图片加载器能直接输出 RGBA(大多数 PNG/JPEG 解码器都能),format 设成 R8G8B8A8_UNORM,+14 不触发,走 memcpy 路径。
注意 properties 是按值传入的副本——函数开头把它和 width/height/depth/mipLevels 一起从 data 抄了一份:
// src/vsg/app/TransferTask.cpp:266
auto properties = data->properties;
是拷贝,不是引用。 所以 properties.stride = targetTraits.size 只影响局部,不改 data->properties。这个 properties 随后传给 transferImageData:
// src/vsg/app/TransferTask.cpp:337
transferImageData(imageInfo.imageView, imageInfo.imageLayout, properties, width, height, depth, mipLevels, imageStagingBuffer, source_offset, vk_commandBuffer, device);
而 transferImageData 用 properties.stride 当 valueSize 算 faceSize——所以必须是补齐后的 4,不能是原始的 3。✓ 这解释了为什么 properties 必须按值传并改写。
但如果走的是前两条 memcpy 路径,properties.stride 保持原值(可能是 0)。 这就是 5.1 节讨论的 valueSize = 0 隐患。
5.19 transferImageData:barrier、layer 映射与 mipmap 生成
// src/vsg/app/TransferTask.cpp:578-582
// Stage which the associated image will be used, such as set by DescriptorSetLayoutBinding::stageFlags
// Further info:
// https://docs.vulkan.org/refpages/latest/refpages/source/VkPipelineStageFlags.html
// https://registry.khronos.org/VulkanSC/specs/1.0-extensions/man/html/VkDescriptorSetLayoutBinding.html
VkPipelineStageFlags dstStageMask = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
硬编码成片元着色器阶段。 后果:如果这个纹理在顶点着色器里被采样(位移贴图、地形高度图、instancing 参数纹理),barrier 的 dstStageMask 不覆盖顶点阶段,同步不完整。验证层会报 SYNC-HAZARD-READ-AFTER-WRITE,没有验证层时可能读到未完成的数据。
注意 ImageInfo 不知道它会被哪些阶段使用——DescriptorSetLayoutBinding::stageFlags 在 layout 里,不在 ImageInfo 里。这个信息在 transferImageData 的调用栈上不存在。这是架构层面的信息缺失,不是实现疏忽;修法要把 stageFlags 一路传到 ImageInfo,改动面很大。规避方式是改用 VK_PIPELINE_STAGE_ALL_GRAPHICS_BIT 或 ALL_COMMANDS_BIT,代价是更保守的同步。VSG 选了激进的那一侧。
接着看 viewType → arrayLayers 的映射:
// src/vsg/app/TransferTask.cpp:590-608
switch (imageView->viewType)
{
case (VK_IMAGE_VIEW_TYPE_CUBE):
arrayLayers = faceDepth;
faceDepth = 1;
break;
case (VK_IMAGE_VIEW_TYPE_1D_ARRAY):
arrayLayers = faceHeight * faceDepth;
faceHeight = 1;
faceDepth = 1;
break;
case (VK_IMAGE_VIEW_TYPE_2D_ARRAY):
// ...
这里的 faceDepth 是 depth 参数(即 data->depth()),而 Image.extent.depth 来自 pixelExtents。 两者对五种 imageViewType 一致,唯独 CUBE_ARRAY 不同:Image.extent.depth = N、Image.arrayLayers = 6(都来自 pixelExtents()),而 transferImageData 本地算出 arrayLayers = 6N、destDepth = 1。
transferImageData 于是发出 6N 个 VkBufferImageCopy,baseArrayLayer 从 0 到 6N-1,但 VkImage 只有 6 层、depth = N。写越界。
修法与 5.2 节相同:构造后手动改 image->arrayLayers 与 image->extent.depth,并不要设 properties.imageViewType = VK_IMAGE_VIEW_TYPE_CUBE_ARRAY——改用 2D_ARRAY 再给 image->flags = VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT,Vulkan 允许从 2D_ARRAY image 创建 cube array 视图。
useDataMipmaps / generateMipmaps 的三级判定:
// src/vsg/app/TransferTask.cpp:635-652
bool useDataMipmaps = mipLevels > 1 && data_mipLevels > 1;
bool generateMipmaps = (mipLevels > 1) && !useDataMipmaps;
if (useDataMipmaps) mipLevels = std::min(mipLevels, data_mipLevels);
if (generateMipmaps)
{
VkFormatProperties props;
vkGetPhysicalDeviceFormatProperties(*(device->getPhysicalDevice()), properties.format, &props);
const bool isBlitPossible = (props.optimalTilingFeatures & VK_FORMAT_FEATURE_BLIT_DST_BIT) > 0;
if (!isBlitPossible)
{
generateMipmaps = false;
}
}
四种组合:(1, *) → 只传第 0 级;(>1, >1) → 用 data 里的多级;(>1, ≤1) → blit 生成;(>1, ≤1) 但格式不支持 blit → generateMipmaps 被关掉,仍然只传第 0 级。
最后一种是隐患。 image->mipLevels 已经是 >1(Image::Image(Data) 里设的),但 generateMipmaps 因为 BLIT_DST_BIT 不可用而关掉。于是 mipLevels 保持 >1、只上传第 0 级、barrier 的 levelCount = mipLevels(>1)——第 1 到 N-1 级是未初始化显存,且被转到 targetImageLayout。 采样时 textureLod(tex, uv, 2.0) 读到垃圾。
这是最容易被忽略的上传 bug: 第一级清晰,远处(自动切到 mip 2/3)是随机噪声或纯色。原因不是采样器,而是 mipmap 生成失败;构造后查一次 VK_FORMAT_FEATURE_BLIT_DST_BIT,不支持就把 image->mipLevels 压回 1。
BLIT_DST_BIT 对 sRGB 格式在部分移动 GPU 上不支持,对 深度格式普遍不支持,对 压缩格式也不支持(压缩格式连 generateMipmaps 都被 computeNumMipMapLevels 提前关掉,见 src/vsg/state/ImageInfo.cpp:357)。
mipmapData 存在时 destWidth/Height/Depth 被 mipmap0 覆盖(src/vsg/app/TransferTask.cpp:622),这与 5.2 节 pixelExtents() 里的逻辑重复:两处都读 mipmapLayout->at(0)、两处都覆盖。所以对带 MipmapLayout 的压缩纹理,Image.extent 与 transferImageData 的 destWidth 一致——这是少数几处"重复但正确"的代码。
mipmap.w 在 region 里当字节偏移用:
// src/vsg/app/TransferTask.cpp:702
region.bufferOffset = stagingBufferOffset + mipmap.w + face * faceSize;
MipmapLayout 的元素是 uvec4(x/y/z = 纹素尺寸,w = 该级在 data 里的字节偏移)。所以 MipmapLayout 不是"辅助信息",它编码了真实的布局偏移——这也解释了为什么 computeValueCountIncludingMipmaps 在有 layout 时完全按 layout 逐级累加,而不是自己算 w/2(src/vsg/core/Data.cpp:172)。
mipmap.w 在 region 里当字节偏移用:
// src/vsg/app/TransferTask.cpp:702
region.bufferOffset = stagingBufferOffset + mipmap.w + face * faceSize;
MipmapLayout 的元素是 uvec4(x/y/z = 纹素尺寸,w = 该级在 data 里的字节偏移)。所以 MipmapLayout 不是"辅助信息",它编码了真实的布局偏移。
5.20 一次 4K 纹理上传的完整账
把前面的数字串起来。场景:4096×4096 RGBA8 纹理,从 read() 得到 Array2D<ubyte4>,到能在着色器里采样。 数据量 4096×4096×4 = 67,108,864 字节 = 64 MB。
| # | 阶段 | 新增占用 | 关键动作 |
|---|---|---|---|
| 1 | vsg::read("tex.png") | CPU 64 MB | ReaderWriter 解码,VSG 只接管指针 |
| 2 | Image::create(data) | 约 100 字节 | 只读 pixelExtents() 与 format,零拷贝 |
| 3 | Image::compile(MemoryBufferPools&) | 显存 ≥64 MB | vkGetImageMemoryRequirements 后从池里切 |
| 4 | TransferBlock::staging | host-visible 64 MB | max(64MB, 16MB) = 64 MB |
| 5 | memcpy 到 staging | 0 | DDR4-3200 约 8 ms(10 GB/s 有效带宽) |
| 6 | vkCmdCopyBufferToImage | 0 | PCIe 3.0 x16 约 6 ms;staging 在 BAR 里约 2 ms |
第 2 步值得强调:R8G8B8A8_UNORM(37) 不在 +14 的触发区间(23–36),所以 format 不变、第 6 步是一次干净的 vkCmdCopyBufferToImage。第 3 步的 reserveMemory 走 max(totalSize, min(availableMemory, minimumDeviceMemorySize))(src/vsg/vk/MemoryBufferPools.cpp:186),64 MB 的请求会新建一个 64 MB 的池,不是从 16 MB 池里挤。
峰值:CPU 64 + staging 64 + 显存 64 = 192 MB。 如果纹理是 RGB8(R8G8B8_UNORM):CPU 48 MB、+14 触发后 staging 仍是 64 MB、VkImage 64 MB,合计 176 MB,另加 38 ms 补齐——省 16 MB,却多花 38 ms。
100 张 4K 纹理:单张峰值 192 MB,全部加载完是 CPU 6.4 GB + 显存 6.4 GB + staging 6.4 GB。staging 的 6.4 GB 是纯浪费——它在每张上传完就没用了,但 TransferBlock::staging 只增不减(5.16 节),3 帧流水会让 3 个 block 轮流涨到 64 MB,第 4 张之后 6 个 block 全是 64 MB = 384 MB 常驻。
加上 STATIC_DATA 不释放 CPU 数据,一个"加载 100 张 4K 纹理"的场景会吃掉 约 13 GB。
只有两条优化值得做: 上传完成后手动 dataRelease() 释放 CPU 缓冲(省 6.4 GB,要自己写回调,因为 STATIC_DATA_UNREF_AFTER_TRANSFER 已失效);改用 KTX2 压缩纹理(CPU 与显存都降到 1/4 到 1/8,唯一数量级的优化)。缩小 staging 收益有限,上限由最大单张纹理决定。
5.21 二十二个陷阱
| 陷阱 | 触发条件 | 后果 | 源码坐标 | 规避 |
|---|---|---|---|---|
| 纹理缩成 1/4、边缘模糊 | 把 width() 当像素数用 | pixelExtents 交回块数,VkImage 建小一圈 | src/vsg/core/Data.cpp:213 | 记住 width() 是块数,乘 blockWidth 才是纹素 |
vkCmdBlitImage 失败、mip 全黑 | 手动设 mipLevels > 1 却没补 TRANSFER_SRC_BIT | blit 的读源缺 usage 位 | src/vsg/state/Image.cpp:91 | 走 ImageInfo::computeNumMipMapLevels() 补位 |
| 远处 mip 是随机噪声 | 格式不支持 BLIT_DST,generateMipmaps 被关 | 只传第 0 级,其余层是未初始化显存 | src/vsg/app/TransferTask.cpp:648 | 构造后查一次 VK_FORMAT_FEATURE_BLIT_DST_BIT |
| 纹理永远只有一级 | 沿用默认 Sampler | maxLod = 0,computeNumMipMapLevels 返回 1 | include/vsg/state/Sampler.h:43 | 显式设 maxLod = VK_LOD_CLAMP_NONE |
| 顶点缓冲全零、画面空白 | Context 没有 transferTask | createBufferAndTransferData 返回 true,活只入队 | src/vsg/vk/Context.cpp:319 | 确认 Viewer::compile 建了 TransferTask |
VUID-VkDescriptorBufferInfo-offset-00342 | usage 传组合位、判断用相等 → alignment = 4 | UBO 的 offset 未按 minUniformBufferOffsetAlignment 对齐 | src/vsg/state/BufferInfo.cpp:235 | 改判 (usage & VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT) != 0 |
| cube array 上传越界 | 设 properties.imageViewType = CUBE_ARRAY | pixelExtents 给 {N,6},transferImageData 发 6N 个 region | src/vsg/core/Data.cpp:155 | 用 2D_ARRAY + CUBE_COMPATIBLE 代替 |
| 2D array 采样全黑 | 没设 properties.imageViewType | viewType 反推成 2D,layerCount 却是 6 | src/vsg/state/ImageView.cpp:59 | 显式设 imageViewType |
| alpha 变 NaN | 16 位浮点 RGB 走补齐分支 | numBitsPerComponent 段里 case 6 用 uint16 max 填 half,0xFFFF 是 NaN | src/vsg/state/ImageInfo.cpp:49 | 源头就用 RGBA,别触发补齐 |
| B/R 通道互换 | traits.size 相等但通道序不同 | memcpy 之后颜色错位,验证层沉默 | src/vsg/app/TransferTask.cpp:290 | 不要手改 image->format |
| 一个字节都没写 | 一侧格式 getFormatTraits 不认识 | imageTotalSize = 0,staging 里是垃圾 | src/vsg/app/TransferTask.cpp:298 | 别把 image->format 设成 VK_FORMAT_UNDEFINED |
take 之后旧槽位泄漏 | 在已挂 parent 的条目上再 reserve() | parent 被覆盖,旧槽位没人还 | src/vsg/state/BufferInfo.cpp:85 | 只对未分配的条目复用 |
| 不同条目被判等价 | 一方没 buffer 就 return 0 | 放进 std::set 会折叠 | src/vsg/state/BufferInfo.cpp:74 | key 用 (buffer, offset) |
| 写穿映射区 | 三参构造给了 range < dataSize() | memcpy 超出映射长度 | src/vsg/state/BufferInfo.cpp:167 | 自己保证 range >= dataSize() |
| 读越界 | range > dataSize() 时按 range 拷 | 读取超出 CPU 缓冲 | src/vsg/app/TransferTask.cpp:143 | 构造时 range 直接取 dataSize() |
| 显存不足时崩 | staging->getDeviceMemory() 返回空 | stagingMemory->map 空指针解引用 | src/vsg/app/TransferTask.cpp:481 | 先判 staging 是否绑定了内存 |
assign(ImageInfoList) 崩 | imageView 有效但 image 为空 | 判空判错对象,末尾解引用空 image | src/vsg/app/TransferTask.cpp:205 | 建 ImageInfo 时保证 image 非空 |
TRANSFER_ALL 等不到 early 的信号量 | transferData 里 result 被后一次赋值覆盖 | early 那轮的 Semaphore 丢失 | src/vsg/app/TransferTask.cpp:345 | 拆成两次调用分别取结果 |
| 动态数据更新被吞一帧 | 两个线程同时 dirty() | 非原子 ++count 丢自增 | include/vsg/core/Data.h:206 | 只在 update 线程 dirty() |
| 静态数据一直占 CPU | 指望 STATIC_DATA_UNREF_AFTER_TRANSFER 释放 | #if 1 分支只把条目塞进 bufferInfosToCopy,data.reset() 留在 #else 里 | src/vsg/vk/Context.cpp:416 | 上传完成后手动 dataRelease() |
throwOutOfDeviceMemoryException 无效 | 该分支被 #if 0 关掉 | 失败只返回 {},不抛异常 | src/vsg/vk/MemoryBufferPools.cpp:218 | 自己判返回值 |
| 显存池不回收 | 只在 releaseUnusedPools() 里还 | 峰值过后常驻 | include/vsg/vk/MemoryBufferPools.h:64 | 内存压力时显式调用 |
5.22 数字与结论
表里的二十二条不是二十二个孤立 bug,它们分三族。第一族是 mipmap:申请、生成、采样分属三个对象——Image 管级别数、transferImageData 管生成、Sampler 管读取范围,任一处没对齐就退化成"能跑但结果错"(前四条)。第二族是格式与布局的隐式约定:块尺寸、通道序、traits.size,共同依赖 Vulkan 枚举值的连续排布(中间六条)。第三族是所有权与生命周期:parent 覆盖、range/dataSize 不对称、result 覆盖、#if 0 屏蔽的开关——全是"读文档看不出来,读代码才看得见"的那一类(后八条)。
十三个数字:
Data家族 150 个具名类型(41Array+ 34Array2D+ 25Array3D+ 50Value),全部由 4 个模板 + 4 个宏生成。Data的抽象契约是 7 条(13 个纯虚函数,去掉 const 配对和纯转发)。Data::Properties11 个字段,其中origin与dataVariance在上传链路里几乎无效。- RGB→RGBA 的三个魔数:
+14(8 位)、+7(16 位)、+3(32 位),依赖 Vulkan 格式枚举的连续排布。 - 三个 16 MB:
minimumBufferSize、minimumDeviceMemorySize、minimumStagingBufferSize。 TransferTask有 6 个TransferBlock(2 个DataToCopy× 3 帧),最坏 96 MB staging。vkCmdCopyBuffer的合并粒度是VkBuffer,不是"任意 buffer"。regionCount <= dataTotalRegions恒成立,copyRegions不越界。- 4K RGBA8 纹理上传峰值 192 MB(CPU 64 + staging 64 + 显存 64)。
- RGB8 反而更贵:176 MB + 38 ms 补齐。
- 逐字节补齐比
memcpy慢 9 倍(38 ms vs 4.2 ms,16.7M 元素)。 bufferImageGranularity(通常 64 KB–1 MB)让 16 MB 池最多只放 16 个资源。createBufferAndTransferData有 16 处调用点,copyDataToStagingBuffer有 0 处,#if TRANSFER_BUFFERS 0屏蔽的分支里vertexBufferInfo[0]对bool取下标——改 1 就编译失败。
十七条结论。
一、stride 是整章最脆的不变式,而它有两处不对称。 dataSize() 用 properties.stride(include/vsg/core/Array.h:309)、valueSize() 用 sizeof(value_type)(同文件 :305),两者只在 contiguous() 里被比较一次(include/vsg/core/Data.h:199),没有任何断言。更隐蔽的是 Properties::operator= 的 if (rhs.stride != 0) 特例(src/vsg/core/Data.cpp:32)——赋值不等于拷贝,a = b 与 Properties c(b) 语义不同。
二、ModifiedCount 把"改没改"压成一个非原子 uint32_t,代价是单线程纪律。 dirty() 就是 ++_modifiedCount(include/vsg/core/Data.h:206),operator++ 返回 void、没有后置版本(同文件 :38)。它省掉了时间戳与哈希,也把"两线程同时改"变成静默丢帧。
三、dataRelease() 在子数组上是空操作,且不报错。 _storage 非空时直接 return nullptr(include/vsg/core/Array.h:302),_data 保持有效,dataAvailable() 仍为 true。所以"释放了"和"没释放"在返回值上不可区分。
四、整个 Data 家族没有维度或边界校验,这是设计而非疏漏。 Array2D::assign 与 Array3D::assign 只在 storage->dataPointer() 非空时算指针(include/vsg/core/Array2D.h:250、include/vsg/core/Array3D.h:262),grep -n "Exception" include/vsg/core/Array*.h 零命中。声明 100000 × 100000 而底层只有 4 字节是合法代码,代价在第一次采样时以画面错误的形式出现。
五、getFormatTraits 比文档描述的完整得多,但 16 位段有一个真错。 它覆盖 BC1–BC7、ETC2/EAC、ASTC(src/vsg/state/ImageInfo.cpp:151),压缩格式给的是"块字节数 + 块尺寸",不是 size = 0。真正的缺陷在 16 位段:case 6 对应 SFLOAT 却填 uint16 的 65535(同文件 :49),补齐到 R16G16B16A16_SFLOAT 时 alpha 是 half 的 NaN。
六、Image::Image(Data) 的 +14/+7/+3 是"用枚举算术替代 switch",正确但极其脆弱。 它依赖三件事同时成立:格式枚举按分量数连续分段、每段恰好 7 或 3 个变体、RGB 段与 RGBA 段的距离等于段长(src/vsg/state/Image.cpp:84)。任何一处插入新格式,代码仍然编译、仍然运行,只是颜色错位。
七、默认 Sampler 读不到 mipmap,这不是 bug 而是默认值选择。 maxLod = 0.0f(include/vsg/state/Sampler.h:43),于是 computeNumMipMapLevels 返回 1(src/vsg/state/ImageInfo.cpp:336),Image 只有一级、generateMipmaps 不触发。想要 mip 必须显式设 maxLod,而它同时决定要不要申请 TRANSFER_SRC_BIT。
八、ImageInfo::computeDataSize() 返回元素个数,BufferInfo::computeDataSize() 返回字节数。 前者是 computeValueCountIncludingMipmaps()(src/vsg/state/ImageInfo.cpp:423),后者是 data->dataSize()(src/vsg/state/BufferInfo.cpp:210)。同名不同量纲,混用差 valueSize 倍。
九、三条上传路径不是 API 选择,而是内存属性的结果。 copyDataToBuffer 会"发现"目标不可映射然后改走 TransferTask(src/vsg/state/BufferInfo.cpp:145),返回值是 void;createBufferAndTransferData 只排队不传(src/vsg/vk/Context.cpp:419 只往 bufferInfosToCopy 追加条目)。两个函数名都只描述了分支之一。
十、静默失效在纹理路径上比缓冲更早发生。 Context::copy(const ImageInfoList&) 连 transferTask 都不检查就把条目入队并返回 true(src/vsg/vk/Context.cpp:591);缓冲路径至少还经过一次 reserve。三处降级串起来(返回 true、丢返回值、填 0)让"没上传"变成"画面不对"。
十一、错误处理有三种风格并存,读代码时不能类推。 Buffer::compile 创建失败抛异常(src/vsg/state/Buffer.cpp:109),Image::compile(MemoryBufferPools&) 分配失败返回 VK_ERROR_OUT_OF_DEVICE_MEMORY(src/vsg/state/Image.cpp:240),reserveMemory 失败只 return {} 并打 debug(src/vsg/vk/MemoryBufferPools.cpp:229)。同一层抽象里,向上暴露错误的方式有三种。
十二、TransferTask 的 3 帧流水 + 持久映射是性能基础,代价是常驻内存。 每帧只做 memcpy(src/vsg/app/TransferTask.cpp:468),不 map/unmap;但 staging 只增不减,6 个 block 最坏 96 MB,动态数据越多这个数字越大。
十三、池化按 bufferImageGranularity 对齐,收益与浪费同源。 槽位起点取 max(memRequirements.alignment, granularity)(src/vsg/vk/MemoryBufferPools.cpp:157),保证线性与最优平铺资源相邻合法;代价是每个资源最多浪费一个 granularity,16 MB 池装不了 17 个 mesh。
十四、两个"文档说有、代码没有"的开关。 throwOutOfDeviceMemoryException 的唯一使用分支被 #if 0 关掉(src/vsg/vk/MemoryBufferPools.cpp:218);STATIC_DATA_UNREF_AFTER_TRANSFER 的 data.reset() 只出现在 #if 1 的 #else 分支里,整个 createBufferAndTransferData 的旧实现被跳过(src/vsg/vk/Context.cpp:575),走的是只往 bufferInfosToCopy 塞条目的新路径(:419)。两个都是"重构时丢掉、没测试会发现"的功能。
十五、这一章真正的知识不是那 150 个类型,而是四个不变式。 data->stride() == targetTraits.size(否则 staging 错位)、range == dataSize()(否则越界读写)、image->mipLevels 与实际上传级数一致(否则 barrier 覆盖垃圾)、image->arrayLayers 与 extent.depth 匹配 viewType(否则 region 越界)。四条都靠约定维持,没有一条有断言。
十六、两处对齐判断都用 usage ==,组合 usage 会静默退回 4 字节。 createHostVisibleBuffer 与 createBufferAndTransferData 都写成 if (usage == VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT)(src/vsg/state/BufferInfo.cpp:235、src/vsg/vk/Context.cpp:411);调用方一旦传 UNIFORM_BUFFER | TRANSFER_DST_BIT,两个分支都不进,alignment 保持 4,而 UBO 的 offset 必须按 minUniformBufferOffsetAlignment(通常 64)对齐。下游六处 alignment == 1 的兜底(如 src/vsg/state/BufferInfo.cpp:249)说明作者默认它可能极小。
十七、Context 的返回值只表示"入队成功",真正的失败在一到两帧之后。 createBufferAndTransferData 在 reserve 成功后直接 return true,账记在 bufferInfosToCopy 里(src/vsg/vk/Context.cpp:417);memcpy 与 vkCmdCopyBuffer 发生在 TransferTask::_transferData(src/vsg/app/TransferTask.cpp:369),那一层的 VkResult 只进日志。按返回值判错的人看不到错误——它以"顶点全零"的形式晚两帧出现。
5.23 源码索引
| 结论 | 文件 | 关键行 |
|---|---|---|
Data 的 7 条契约 | include/vsg/core/Data.h | 173–191 |
ModifiedCount 定义 | include/vsg/core/Data.h | 31–39 |
dirty() / getModifiedCount | include/vsg/core/Data.h | 205–221 |
Properties 11 字段 | include/vsg/core/Data.h | 120–140 |
pixelExtents | src/vsg/core/Data.cpp | 211–228 |
BufferInfo 五字段 | include/vsg/state/BufferInfo.h | 56–60 |
requiresCopy / syncModifiedCounts | include/vsg/state/BufferInfo.h | 69–78 |
take() 的 identical 检查 | src/vsg/state/BufferInfo.cpp | 81–107 |
copyDataToBuffer 隐式 dirty | src/vsg/state/BufferInfo.cpp | 135–179 |
copyDataToStagingBuffer | src/vsg/state/BufferInfo.cpp | 185–208 |
createHostVisibleBuffer 对齐 | src/vsg/state/BufferInfo.cpp | 228–262 |
Image::Image(Data) | src/vsg/state/Image.cpp | 35–93 |
RGB→RGBA +14/+7/+3 | src/vsg/state/Image.cpp | 84–89 |
getFormatTraits 8/16/32/64 位 | src/vsg/state/ImageInfo.cpp | 21–89 |
| 深度/模板/packed 特例 | src/vsg/state/ImageInfo.cpp | 90–141 |
computeNumMipMapLevels | src/vsg/state/ImageInfo.cpp | 328–381 |
ImageInfo::computeNumMipMapLevels | src/vsg/state/ImageInfo.cpp | 406–416 |
ImageView viewType 推断 | src/vsg/state/ImageView.cpp | 47–93 |
reserveBuffer 三层检查 | src/vsg/vk/MemoryBufferPools.cpp | 77–142 |
reserveMemory granularity 对齐 | src/vsg/vk/MemoryBufferPools.cpp | 144–234 |
TransferBlock / DataToCopy | include/vsg/app/TransferTask.h | 82–105 |
_transferData 两遍扫描 | src/vsg/app/TransferTask.cpp | 350–410 |
| staging 只增不减 | src/vsg/app/TransferTask.cpp | 468–488 |
_transferBufferInfos 合并 | src/vsg/app/TransferTask.cpp | 105–193 |
_transferImageInfo 三路径 | src/vsg/app/TransferTask.cpp | 253–338 |
dstStageMask 硬编码 | src/vsg/app/TransferTask.cpp | 582 |
viewType → arrayLayers | src/vsg/app/TransferTask.cpp | 590–611 |
generateMipmaps 三级判定 | src/vsg/app/TransferTask.cpp | 619–652 |
| blit 生成 mipmap | src/vsg/app/TransferTask.cpp | 775–856 |
#if 1 的 150 行死代码 | src/vsg/vk/Context.cpp | createBufferAndTransferData 内 |
| "Need to implement copying" warn | src/vsg/vk/Context.cpp | 319 |
TRANSFER_BUFFERS 0 | src/vsg/raytracing/AccelerationGeometry.cpp | 20, 54 |
Geometry::compile 合并上传 | src/vsg/nodes/Geometry.cpp | 132–173 |
5.24 可复现验证
验证 1:pixelExtents 对六种 imageViewType 的行为
#include <vsg/all.h>
#include <iostream>
int main()
{
const uint32_t W = 256, H = 256;
struct Case { const char* name; int8_t vt; uint32_t depth; };
Case cases[] = {
{"未设", -1, 1},
{"2D", VK_IMAGE_VIEW_TYPE_2D, 1},
{"3D", VK_IMAGE_VIEW_TYPE_3D, 8},
{"CUBE", VK_IMAGE_VIEW_TYPE_CUBE, 6},
{"2D_ARRAY", VK_IMAGE_VIEW_TYPE_2D_ARRAY, 8},
{"CUBE_ARRAY", VK_IMAGE_VIEW_TYPE_CUBE_ARRAY, 12},
};
for (auto& c : cases)
{
auto data = vsg::ubyteArray3D::create(W, H, c.depth,
vsg::Data::Properties{VK_FORMAT_R8G8B8A8_UNORM});
data->properties.imageViewType = c.vt;
auto [w, h, d, layers] = data->pixelExtents();
auto image = vsg::Image::create(data);
std::printf("%-12s pixelExtents={%u,%u,%u,%u} Image: type=%d extent={%u,%u,%u} layers=%u\n",
c.name, w, h, d, layers, int(image->imageType),
image->extent.width, image->extent.height, image->extent.depth,
image->arrayLayers);
}
return 0;
}
关键在最后一行:CUBE_ARRAY 应得 layers=12, depth=1,实际是 layers=6, depth=2(见 5.2 节)。
验证 2:RGB→RGBA 重映射的三个偏移
VkFormat fmts[] = {
VK_FORMAT_R8G8B8_UNORM, VK_FORMAT_B8G8R8_SRGB,
VK_FORMAT_R16G16B16_SFLOAT, VK_FORMAT_R32G32B32_SFLOAT,
};
for (auto f : fmts)
{
auto data = vsg::ubyteArray2D::create(4, 4, vsg::Data::Properties{f});
auto image = vsg::Image::create(data);
std::printf("src=%-28d dst=%-28d delta=%d\n", f, image->format, int(image->format) - int(f));
}
// 23 → 37 (delta=14) 36 → 50 (delta=14)
// 90 → 97 (delta=7) 106 → 109 (delta=3)
验证 3:getFormatTraits 的枚举算术
for (int f = VK_FORMAT_R8_UNORM; f <= VK_FORMAT_B8G8R8A8_SRGB; ++f)
{
auto t = vsg::getFormatTraits(VkFormat(f));
std::printf("fmt=%3d size=%d comps=%d bits=%d default[0]=%u\n",
f, t.size, t.numComponents, t.numBitsPerComponent, t.defaultValue[0]);
}
// 9 → size=1 comps=1 default[0]=255 (R8_UNORM)
// 10 → size=1 comps=1 default[0]=127 (R8_SNORM)
// 37 → size=4 comps=4 default[0]=255 (R8G8B8A8_UNORM)
// 90 → size=6 comps=3 default[0]=255 (R16G16B16_SFLOAT)
最后一行暴露了 5.8 节说的 case 6 缺陷:R16G16B16_SFLOAT 的 defaultValue 是 uint16 的 65535,而 half 的 0xFFFF 是 NaN。
5.25 问题清单
九个问题,每个都对应一条可验证的源码事实:
Data的 7 条契约是怎么从 13 个纯虚函数里合并出来的?(5.1)Properties的 11 个字段里,哪几个在上传链路中没有读者?(5.2)- 4 字节的非原子计数凭什么当脏标记?(5.3)
- 子数组能不能构造出
stride == 0?(5.4) offset、range、dataSize三者不等时,谁读谁写?(5.5、5.11)- 一块
DeviceMemory怎么装下 17 个 mesh?(5.6、5.15) +14/+7/+3依赖什么前提,前提破了会怎样?(5.7)- 三条路径里哪一条的返回值在说谎?(5.10–5.14)
- 4K 纹理上传为什么峰值 192 MB 而不是 128 MB?(5.20)
5.26 答案骨架
- 7 条契约是 13 个纯虚函数去重后的最小集,
valueSize与stride分离才让Value与Array共用同一个抽象(include/vsg/core/Data.h:173)。 stride有两个写入口径:Properties::operator=带if (rhs.stride != 0)保护(src/vsg/core/Data.cpp:32),Array::assign无条件覆盖(include/vsg/core/Array.h:271)。range默认取dataSize(),全链路没有一处min()兜底(src/vsg/state/BufferInfo.cpp:167)。- 三条路径的分叉点是内存属性,不是 API 名字:可映射就直拷,否则入队(
src/vsg/state/BufferInfo.cpp:145)。 - 四个不变式一条断言都没有(5.22 第十五条)。
5.27 阅读路线
30 分钟求能用:5.0 → 5.10 → 5.21 → 5.22,跳过所有 switch 与模板细节。
两小时求改得动:再加 5.4、5.7、5.12、5.15——这四节才会静默出错。
排障:按 5.21 第一列的症状查表,再跳到对应小节。
跟读时先用这四条命令定位:
grep -rn "copyDataToBuffer(" src/vsg | wc -l
grep -rn "createBufferAndTransferData(" src/vsg | wc -l
grep -rn "alignment == 1" src/vsg
grep -rn "define TRANSFER_BUFFERS" src/vsg
5.28 下章预告
数据已经在 GPU 上了。接下来的问题是:这些 VkBuffer / VkImage 怎么被管线看到?
第六章 实例、设备与上下文:Instance/Device/Context 要回答:
Context为什么同时是"资源池持有者"和"命令录制场所"?11 个成员各自的生命周期谁管?Instance的扩展协商分几层?VK_KHR_portability_enumeration为什么单独处理?PhysicalDevice::selectDevice的打分逻辑是什么?为什么"独显优先"要写成 40 行?queueFamilyIndex为什么需要"图形优先、传输优先、计算兜底"三条判据?transferTask用的队列和主队列是同一条吗?VSG_MAX_DEVICES = 1在多设备场景下会静默失效,改成 2 会炸哪里?
以及本章留下的三个悬念:Context::transferTask 是谁创建的?两个 MemoryBufferPools 的 ResourceRequirements 从哪来?Context::record() 之后、reset() 之前,bufferInfosToCopy 的生命窗口有多长?