《VulkanSceneGraph 1.1.16 源码深度解析》第五章 数据对象:从 `Data` 到 `VkBuffer`/`VkImage` 的完整链路

2 阅读37分钟

《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 的数据。只有在两个条件同时成立时才会触发:

  1. data->properties.format == imageView->format(不需要格式转换)
  2. 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.*/
};

四个值的语义各不相同,而它们在后端的处理只有两处差异:

  1. dynamic() 判断:properties.dataVariance >= DYNAMIC_DATA。所以 STATIC_DATA_UNREF_AFTER_TRANSFER(1)不算动态,DYNAMIC_DATA(2)和 DYNAMIC_DATA_TRANSFER_AFTER_RECORD(3)算。
  2. 分到 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)+14R8G8B8A8_UNORM (37) … B8G8R8A8_SRGB (50)
R16G16B16_UNORM (84) … R16G16B16_SFLOAT (90)+7R16G16B16A16_UNORM (91) … R16G16B16A16_SFLOAT (97)
R32G32B32_UINT (104) … R32G32B32_SFLOAT (106)+3R32G32B32A32_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 × 7if/else if 四个上界% 7
16 位70–974 × 71 + (f-70)/7% 7
32 位98–1094 × 31 + (f-98)/3% 3
64 位110–1214 × 31 + (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_UNORM90 % 7 = 0255✓
R8_SNORM101 % 7 = 1127✓
R8_UINT134 % 7 = 4255✓
R8_SINT145 % 7 = 5127✓
B8G8R8A8_SRGB5041 % 7 = 6255✓
R16G16B16_SFLOAT9020 % 7 = 665535(uint16 max)✓
R32G32B32_SFLOAT1068 % 3 = 21.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::copyDataToBuffervsg::copyDataToStagingBufferContext::createBufferAndTransferData
目标内存HOST_VISIBLE | HOST_COHERENT先 HOST_VISIBLE 再 DEVICE_LOCALDEVICE_LOCAL
传输方式vkMapMemory + memcpymemcpy 到 staging + vkCmdCopyBufferTransferTask 批量
同步立即,无 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每帧路径 Amap/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)有三条规则:

  1. 只在 !staging || staging->size < totalSize 时重新分配。staging 只增不减,一个曾装过 200 MB 的 block 会永久占 200 MB。
  2. 分配大小 = max(totalSize, minimumStagingBufferSize),后者是 16 MB(include/vsg/app/TransferTask.h:61)。
  3. 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。

#阶段新增占用关键动作
1vsg::read("tex.png")CPU 64 MBReaderWriter 解码,VSG 只接管指针
2Image::create(data)约 100 字节只读 pixelExtents() 与 format,零拷贝
3Image::compile(MemoryBufferPools&)显存 ≥64 MBvkGetImageMemoryRequirements 后从池里切
4TransferBlock::staginghost-visible 64 MBmax(64MB, 16MB) = 64 MB
5memcpy 到 staging0DDR4-3200 约 8 ms(10 GB/s 有效带宽)
6vkCmdCopyBufferToImage0PCIe 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_BITblit 的读源缺 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
纹理永远只有一级沿用默认 SamplermaxLod = 0,computeNumMipMapLevels 返回 1include/vsg/state/Sampler.h:43显式设 maxLod = VK_LOD_CLAMP_NONE
顶点缓冲全零、画面空白Context 没有 transferTaskcreateBufferAndTransferData 返回 true,活只入队src/vsg/vk/Context.cpp:319确认 Viewer::compile 建了 TransferTask
VUID-VkDescriptorBufferInfo-offset-00342usage 传组合位、判断用相等 → alignment = 4UBO 的 offset 未按 minUniformBufferOffsetAlignment 对齐src/vsg/state/BufferInfo.cpp:235改判 (usage & VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT) != 0
cube array 上传越界设 properties.imageViewType = CUBE_ARRAYpixelExtents 给 {N,6},transferImageData 发 6N 个 regionsrc/vsg/core/Data.cpp:155用 2D_ARRAY + CUBE_COMPATIBLE 代替
2D array 采样全黑没设 properties.imageViewTypeviewType 反推成 2D,layerCount 却是 6src/vsg/state/ImageView.cpp:59显式设 imageViewType
alpha 变 NaN16 位浮点 RGB 走补齐分支numBitsPerComponent 段里 case 6 用 uint16 max 填 half,0xFFFF 是 NaNsrc/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:74key 用 (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 为空判空判错对象,末尾解引用空 imagesrc/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 屏蔽的开关——全是"读文档看不出来,读代码才看得见"的那一类(后八条)。

十三个数字:

  1. Data 家族 150 个具名类型(41 Array + 34 Array2D + 25 Array3D + 50 Value),全部由 4 个模板 + 4 个宏生成。
  2. Data 的抽象契约是 7 条(13 个纯虚函数,去掉 const 配对和纯转发)。
  3. Data::Properties 11 个字段,其中 origin 与 dataVariance 在上传链路里几乎无效。
  4. RGB→RGBA 的三个魔数:+14(8 位)、+7(16 位)、+3(32 位),依赖 Vulkan 格式枚举的连续排布。
  5. 三个 16 MB:minimumBufferSize、minimumDeviceMemorySize、minimumStagingBufferSize。
  6. TransferTask 有 6 个 TransferBlock(2 个 DataToCopy × 3 帧),最坏 96 MB staging。
  7. vkCmdCopyBuffer 的合并粒度是 VkBuffer,不是"任意 buffer"。
  8. regionCount <= dataTotalRegions 恒成立,copyRegions 不越界。
  9. 4K RGBA8 纹理上传峰值 192 MB(CPU 64 + staging 64 + 显存 64)。
  10. RGB8 反而更贵:176 MB + 38 ms 补齐。
  11. 逐字节补齐比 memcpy 慢 9 倍(38 ms vs 4.2 ms,16.7M 元素)。
  12. bufferImageGranularity(通常 64 KB–1 MB)让 16 MB 池最多只放 16 个资源。
  13. 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.h173–191
ModifiedCount 定义include/vsg/core/Data.h31–39
dirty() / getModifiedCountinclude/vsg/core/Data.h205–221
Properties 11 字段include/vsg/core/Data.h120–140
pixelExtentssrc/vsg/core/Data.cpp211–228
BufferInfo 五字段include/vsg/state/BufferInfo.h56–60
requiresCopy / syncModifiedCountsinclude/vsg/state/BufferInfo.h69–78
take() 的 identical 检查src/vsg/state/BufferInfo.cpp81–107
copyDataToBuffer 隐式 dirtysrc/vsg/state/BufferInfo.cpp135–179
copyDataToStagingBuffersrc/vsg/state/BufferInfo.cpp185–208
createHostVisibleBuffer 对齐src/vsg/state/BufferInfo.cpp228–262
Image::Image(Data)src/vsg/state/Image.cpp35–93
RGB→RGBA +14/+7/+3src/vsg/state/Image.cpp84–89
getFormatTraits 8/16/32/64 位src/vsg/state/ImageInfo.cpp21–89
深度/模板/packed 特例src/vsg/state/ImageInfo.cpp90–141
computeNumMipMapLevelssrc/vsg/state/ImageInfo.cpp328–381
ImageInfo::computeNumMipMapLevelssrc/vsg/state/ImageInfo.cpp406–416
ImageView viewType 推断src/vsg/state/ImageView.cpp47–93
reserveBuffer 三层检查src/vsg/vk/MemoryBufferPools.cpp77–142
reserveMemory granularity 对齐src/vsg/vk/MemoryBufferPools.cpp144–234
TransferBlock / DataToCopyinclude/vsg/app/TransferTask.h82–105
_transferData 两遍扫描src/vsg/app/TransferTask.cpp350–410
staging 只增不减src/vsg/app/TransferTask.cpp468–488
_transferBufferInfos 合并src/vsg/app/TransferTask.cpp105–193
_transferImageInfo 三路径src/vsg/app/TransferTask.cpp253–338
dstStageMask 硬编码src/vsg/app/TransferTask.cpp582
viewType → arrayLayerssrc/vsg/app/TransferTask.cpp590–611
generateMipmaps 三级判定src/vsg/app/TransferTask.cpp619–652
blit 生成 mipmapsrc/vsg/app/TransferTask.cpp775–856
#if 1 的 150 行死代码src/vsg/vk/Context.cppcreateBufferAndTransferData 内
"Need to implement copying" warnsrc/vsg/vk/Context.cpp319
TRANSFER_BUFFERS 0src/vsg/raytracing/AccelerationGeometry.cpp20, 54
Geometry::compile 合并上传src/vsg/nodes/Geometry.cpp132–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 问题清单

九个问题,每个都对应一条可验证的源码事实:

  1. Data 的 7 条契约是怎么从 13 个纯虚函数里合并出来的?(5.1)
  2. Properties 的 11 个字段里,哪几个在上传链路中没有读者?(5.2)
  3. 4 字节的非原子计数凭什么当脏标记?(5.3)
  4. 子数组能不能构造出 stride == 0?(5.4)
  5. offset、range、dataSize 三者不等时,谁读谁写?(5.5、5.11)
  6. 一块 DeviceMemory 怎么装下 17 个 mesh?(5.6、5.15)
  7. +14/+7/+3 依赖什么前提,前提破了会怎样?(5.7)
  8. 三条路径里哪一条的返回值在说谎?(5.10–5.14)
  9. 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 的生命窗口有多长?