编译期像素格式标签——让格式错误在编译期炸掉

上一章我们搭好了项目骨架，构建系统跑通了，测试也绿灯了。现在终于可以开始写"真正的"代码了。这一章要做的事情是 edgecv 类型安全的基石——编译期像素格式标签。在解释具体实现之前，我们先来聊聊为什么要做这个东西，因为只有理解了痛点，你才会觉得后面那些模板元编程的花活儿是值得的。

问题的根源：cv::Mat 的动态类型

OpenCV 用一个 int 来表示矩阵元素的类型，比如 CV_8UC3 表示 3 通道 8 位无符号整数、CV_32FC1 表示单通道 32 位浮点。这些常量本质上就是几个魔术数字的位运算组合。问题在于，cv::Mat 把这个类型信息藏在了运行时数据里——编译器在编译期完全不知道一个 cv::Mat 变量里存的是什么格式。

想象一个常见场景：你有一个函数接收 cv::Mat 参数，内部调用了 cvtColor 做 BGR 到灰度的转换。如果调用方不小心传了一张已经是灰度的图片，OpenCV 不会在编译期提醒你，而是在运行时抛一个异常或者默默返回一张错误的图。更糟糕的情况是格式恰好"兼容"但语义不对——比如把一张 RGB 图当 BGR 用——这种错误连运行时异常都不会触发，只会产生颜色诡异的结果，而且你可能要很久之后才会注意到。

我们想做的事情很简单：把像素格式变成 C++ 类型系统的一部分。当你声明一个函数接受 Image<BGR> 时，编译器就知道了——这个函数需要 3 通道 8 位的 BGR 数据。你传一个 Image<Gray> 进去，编译直接不过。这种错误从运行时搬到编译时，调试成本从"可能要花几个小时排查诡异现象"降到"编译器直接告诉你哪一行有问题"，这是巨大的效率提升。

从最简单的标签开始

那么问题来了：怎么在 C++ 类型里编码像素格式信息？我们的选择是用空结构体（empty struct）作为标签类型。来看看最基础的定义——以 BGR 为例：

cpp

struct BGR {
    static constexpr int channels = 3;
    using value_type = uint8_t;
};

就这么简单。一个结构体，里面没有任何数据成员，只有两个类型层面的属性：channels 告诉你有几个通道，value_type 告诉你每个通道的数据类型。这个结构体的大小是 1 字节（C++ 要求所有完整类型至少占 1 字节），但因为它从不会被实例化来存储数据——它只是作为模板参数出现——所以这个"1 字节"完全不会出现在运行时内存里。

你可能会问：为什么不直接用 enum 或者 int 常量？原因有两层。第一层是类型安全：用不同的空结构体类型（BGR vs Gray）意味着它们是不同的类型，编译器可以在函数重载、模板特化、concepts 约束里区分它们。如果你用 enum 值或 int 常量，所有的格式都是同一个类型（int），编译器无法在类型层面做区分。第二层是表达力：空结构体可以携带嵌套类型（using value_type = ...）和编译期常量（static constexpr int channels），这些信息在模板元编程里可以很自然地提取和使用，而 enum 值做不到这一点。

用宏消灭重复：MAKE_PIXEL_FORMAT

一个 BGR 标签的写法我们清楚了，但实际项目里常用的像素格式可不止一种。如果每种格式都手写一个结构体，那就要重复写很多结构相似的代码——这种重复不仅仅是打字辛苦的问题，更重要的是容易出错：你可能把某个格式的通道数写错了，而因为每个结构体都是独立的，编译器没办法帮你检查它们的一致性。

所以我们用一个简单的宏来生成这些标签结构体：

cpp

#define MAKE_PIXEL_FORMAT(_name_, _ch_, _type_) \
    struct _name_ {                             \
        static constexpr int channels = _ch_;   \
        using value_type = _type_;              \
    };

宏接收三个参数：格式名称、通道数、值类型。然后用这三个参数展开成一个结构体定义。接下来我们把常用的格式全部生成出来：

cpp

MAKE_PIXEL_FORMAT(BGR, 3, uint8_t)
MAKE_PIXEL_FORMAT(RGB, 3, uint8_t)
MAKE_PIXEL_FORMAT(BGRA, 4, uint8_t)
MAKE_PIXEL_FORMAT(RGBA, 4, uint8_t)
MAKE_PIXEL_FORMAT(Gray, 1, uint8_t)
MAKE_PIXEL_FORMAT(Gray16, 1, uint16_t)
MAKE_PIXEL_FORMAT(Float1, 1, float)
MAKE_PIXEL_FORMAT(Float3, 3, float)

这八种格式覆盖了图像处理中最常见的场景：BGR/RGB 是 OpenCV 和大多数摄像头原生输出的格式，BGRA/RGBA 带了 alpha 通道用于合成，Gray 和 Gray16 是灰度图的两个精度版本，Float1 和 Float3 用于存储归一化的特征数据或深度信息。每种格式的语义都是自解释的——看到 BGR 你就知道是 3 通道 8 位的 BGR 格式，不需要去查 CV_8UC3 对应什么。

用完宏之后有一件很重要的事情：

cpp

#undef MAKE_PIXEL_FORMAT // Tools Macro should be clean up!

#undef 掉这个宏。这是一个良好的 C++ 卫生习惯——宏不遵守命名空间，它在 #undef 之前会影响之后所有的代码。我们只在 pixel_format.hpp 里需要它，用完立刻清理掉，避免它"泄漏"到包含这个头文件的其他代码里。这种 #define + 使用 + #undef 的三段式模式在 C++ 里很常见，STL 的 <cassert> 里的 assert 宏也是这么处理的。

YUYV：需要特殊处理的格式

上面八种格式有一个共同的特点：每个像素的总字节数恰好等于 channels * sizeof(value_type)。但世界上总有例外——YUYV 格式就是这样一个例外。YUYV 是一种"打包"的像素格式，它用 4 个字节存储 2 个像素（每个像素有一个亮度 Y 和共享的色度 UV），所以从"通道"的角度看它有 2 个通道，每个通道的值类型是 uint8_t，但每个像素实际占 2 字节而不是 channels * sizeof(uint8_t) = 2——恰好数值上相等，但语义上不应该用 channels * sizeof 来推导，因为 YUYV 的打包方式和普通平面格式完全不同。

为了准确地表达这种差异，YUYV 没有使用宏生成，而是手写了一个独立的结构体，额外增加了 bytes_per_pixel 字段：

cpp

struct YUYV {
    static constexpr int channels = 2;
    using value_type = uint8_t;
    static constexpr int bytes_per_pixel = 2;
};

这样 YUYV 的每个像素字节数就直接由 bytes_per_pixel 给出，而不需要通过 channels * sizeof(value_type) 间接计算。这种"通用规则 + 特殊情况单独处理"的设计在实际工程里非常常见——与其为了追求统一抽象把特殊情况硬塞进通用框架，不如老老实实给特殊情况写几行独立代码。后面你会看到 bytes_size 模板对 YUYV 的处理也是按照 channels * sizeof 计算的，但 YUYV 自己还额外提供了 bytes_per_pixel 作为更精确的描述，供有需要的场景使用。

is_pixel_format：用 Concept 约束合法格式

现在我们有一堆格式标签了，但怎么保证传给模板的确实是一个合法的格式标签，而不是随便什么类型？C++20 给了我们一个很好的工具：Concepts。

cpp

template <typename format>
concept is_pixel_format = requires {
    { format::channels } -> std::convertible_to<int>;
    typename format::value_type;
};

（如不熟悉 C++20 Concepts，请参阅 primer/concepts.md。）

这个 concept 定义了一个约束：要满足 is_pixel_format，一个类型必须提供 channels 成员（且能转换为 int），以及 value_type 嵌套类型。注意这里用的是 requires 表达式而不是传统的 SFINAE——Concepts 的语法更简洁，编译器报错信息也更友好。如果某个类型不满足这个 concept，编译器会直接告诉你"约束不满足"以及具体是哪个 requires 子句失败，而不是像 SFINAE 时代那样给你吐一屏幕的模板展开错误。

有了这个 concept，我们就可以在模板参数上做约束了。比如后面定义 Image 类的时候会写 template <is_pixel_format F> class Image，这样你试图写 Image<int> 的时候编译器就会在模板实例化的地方直接报错，而不是延迟到某个深层模板调用里才爆炸。

bytes_size：编译期计算每个像素的字节数

最后一个拼图是 bytes_size——一个变量模板，在编译期计算指定格式每个像素占多少字节：

cpp

template <is_pixel_format pixel_format> constexpr size_t bytes_size =
    pixel_format::channels * sizeof(typename pixel_format::value_type);

（如不了解 constexpr 变量模板的用法，请参阅 primer/constexpr-and-consteval.md。）

这里有几个要点。首先，模板参数用了 is_pixel_format 约束——只有满足 concept 的类型才能实例化这个模板。其次，constexpr 保证了计算结果在编译期就可用的常量。最后，计算公式就是朴素的 channels * sizeof(value_type)——3 通道的 BGR 每像素 3 字节，单通道 float 每像素 4 字节，等等。

你可以在编译期直接 static_assert 来验证这些值：

cpp

static_assert(bytes_size<BGR> == 3);
static_assert(bytes_size<BGRA> == 4);
static_assert(bytes_size<Gray> == 1);
static_assert(bytes_size<Float3> == 12);
static_assert(bytes_size<Gray16> == 2);

如果某个格式的 bytes_size 计算结果和你预期的不一样，编译直接不过。这种编译期断言让我们对格式定义的正确性有了极高的信心——不需要等到运行时才发现 Gray16 每像素应该是 2 字节而不是 1 字节。

把它们放在一起：完整的 pixel_format.hpp

现在我们把上面讨论的所有部分组合起来，看看完整的头文件长什么样。整个 include/cvw/pixel_format.hpp 加起来不到 40 行：

cpp

#pragma once
#include <concepts>
#include <cstddef>
#include <cstdint>

namespace cvw {
#define MAKE_PIXEL_FORMAT(_name_, _ch_, _type_) \
    struct _name_ {                             \
        static constexpr int channels = _ch_;   \
        using value_type = _type_;              \
    };

MAKE_PIXEL_FORMAT(BGR, 3, uint8_t)
MAKE_PIXEL_FORMAT(RGB, 3, uint8_t)
MAKE_PIXEL_FORMAT(BGRA, 4, uint8_t)
MAKE_PIXEL_FORMAT(RGBA, 4, uint8_t)
MAKE_PIXEL_FORMAT(Gray, 1, uint8_t)
MAKE_PIXEL_FORMAT(Gray16, 1, uint16_t)
MAKE_PIXEL_FORMAT(Float1, 1, float)
MAKE_PIXEL_FORMAT(Float3, 3, float)

#undef MAKE_PIXEL_FORMAT

struct YUYV {
    static constexpr int channels = 2;
    using value_type = uint8_t;
    static constexpr int bytes_per_pixel = 2;
};

template <typename format>
concept is_pixel_format = requires {
    { format::channels } -> std::convertible_to<int>;
    typename format::value_type;
};

template <is_pixel_format pixel_format> constexpr size_t bytes_size =
    pixel_format::channels * sizeof(typename pixel_format::value_type);

} // namespace cvw

代码量很小，但信息密度很高：8 种常用格式 + 1 种特殊格式 + 1 个 concept 约束 + 1 个编译期字节数计算。这些组件在后续的 Image、ImageView、算法模板里会反复出现，是整个库的类型安全基础。

编写测试

有了实现就该写测试了。edgecv 的像素格式测试覆盖了三个维度：concept 约束、编译期字节数计算、运行时通道数和值类型的正确性。

首先是 concept 检查——我们用 static_assert 确认所有 9 种格式都满足 is_pixel_format：

cpp

static_assert(is_pixel_format<BGR>);
static_assert(is_pixel_format<RGB>);
static_assert(is_pixel_format<BGRA>);
static_assert(is_pixel_format<RGBA>);
static_assert(is_pixel_format<Gray>);
static_assert(is_pixel_format<Gray16>);
static_assert(is_pixel_format<Float1>);
static_assert(is_pixel_format<Float3>);
static_assert(is_pixel_format<YUYV>);

这些断言全部在编译期执行。如果某个格式标签不小心少了 channels 或者 value_type，对应的 static_assert 就会失败，编译器直接告诉你哪个格式的 concept 检查没过。

然后是编译期的字节数验证：

cpp

static_assert(bytes_size<BGR> == 3);
static_assert(bytes_size<BGRA> == 4);
static_assert(bytes_size<Gray> == 1);
static_assert(bytes_size<Float3> == 12);
// ... 其他格式类似

除了编译期断言，我们也写了运行时的 Google Test 测试用例。运行时测试主要检查 channels 的值和 value_type 的类型身份：

cpp

TEST(PixelFormat, BGR_Channels) { EXPECT_EQ(BGR::channels, 3); }
TEST(PixelFormat, BGR_BytesSize) { EXPECT_EQ(bytes_size<BGR>, 3u); }
TEST(PixelFormat, BGR_ValueType) {
    EXPECT_TRUE((std::is_same_v<BGR::value_type, uint8_t>));
}
// ... 每种格式都有对应的三组测试

你可能会觉得编译期 static_assert 和运行时 EXPECT_EQ 检查同样的东西有些冗余。确实，从"验证正确性"的角度看运行时测试没有提供编译期断言以外的信息。但运行时测试的价值在于它是 CTest 流程的一部分——CI 脚本只需要 ctest，不需要单独处理 static_assert。而且运行时测试也验证了头文件在不同编译单元中的行为一致性，这在使用 header-only 库的时候并非理所当然。

编写示例程序

示例程序在 examples/base/pixel_format.cpp 里，它做的事情很简单：打印每种格式的属性并做编译期断言。这是给用户看的第一个 edgecv 代码示例，所以我们让它尽量直观：

cpp

int main() {
    std::cout << cvw::example::Banner<>::make_banner("Pixel Format Example");

    std::cout << "BGR:   channels=" << cvw::BGR::channels
              << ", value_type=uint8_t, bytes_size="
              << cvw::bytes_size<cvw::BGR> << '\n';
    // ... 其他格式类似

    static_assert(cvw::is_pixel_format<cvw::BGR>);
    static_assert(cvw::is_pixel_format<cvw::Gray>);
    // ...

    static_assert(cvw::bytes_size<cvw::BGR> == 3);
    static_assert(cvw::bytes_size<cvw::Float3> == 12);
    // ...
}

验证

运行构建和测试：

bash

cmake -B build && cmake --build build
cd build && ctest --test-dir build -R pixel_format

如果一切正常，你会看到 pixel_format 测试全部通过。示例程序也可以直接运行：

bash

./build/examples/base/pixel_format_example

它会打印出所有格式的属性信息，证明编译期计算和运行时输出是一致的。

真正的验证是反向的：试试用一个不满足 concept 的类型来实例化模板。比如你在测试文件里加上这行：

cpp

static_assert(cvw::is_pixel_format<int>); // 编译失败！

编译器会立即报错，告诉你 int 不满足 is_pixel_format 约束——因为它既没有 channels 也没有 value_type。这正是我们想要的行为：不合法的格式在编译期就被拦住了，而不是在运行时给你一个莫名其妙的 segfault。

⚠️ 一个容易踩的坑：如果你在 #include <cvw/pixel_format.hpp> 之前包含了其他定义了 BGR、RGB 等名字的头文件（比如某些图形库的宏定义），可能会产生命名冲突。edgecv 把所有格式标签放在 cvw 命名空间里来降低这种风险——使用时需要写 cvw::BGR 而不是裸 BGR。如果你在自己的代码里也有同名的标识符，用命名空间限定符就不会冲突。

小结

这一章我们实现了 edgecv 的第一个真正功能模块。编译期像素格式标签看起来只是几个空结构体，但它们把像素格式信息从运行时的魔术数字提升到了 C++ 类型系统里。配合 concept 约束和 constexpr 变量模板，我们实现了格式的编译期校验和计算——任何格式不匹配的错误都会在构建阶段就被发现，而不是等到程序跑起来才爆炸。这个模块是后续 Image 容器、算法模板的基础设施，在后续的章节里你会频繁看到 is_pixel_format 和 bytes_size 出现在模板参数列表和 static_assert 里。

下一章我们将基于这些格式标签构建 Expected 错误处理框架——有了编译期的格式安全，我们还需要一套不用异常的错误处理机制，来让整个库在嵌入式场景下也能安全使用。

编译期像素格式标签——让格式错误在编译期炸掉 ​

问题的根源：cv::Mat 的动态类型 ​

从最简单的标签开始 ​

用宏消灭重复：MAKE_PIXEL_FORMAT ​

YUYV：需要特殊处理的格式 ​

is_pixel_format：用 Concept 约束合法格式 ​

bytes_size：编译期计算每个像素的字节数 ​

把它们放在一起：完整的 pixel_format.hpp ​

编写测试 ​

编写示例程序 ​

验证 ​

小结 ​