《VulkanSceneGraph 1.1.16 源码深度解析》第四章 数学库:列主序、Z-up 与精度的三重代价
4.0 一个只有 478 行实现文件的模块
先看一组对比数字。include/vsg/maths/ 有 16 个头文件,合计 2888 行;src/vsg/maths/ 只有 2 个 .cpp,合计 478 行。其中 common.cpp 只有 22 行,真正的实现只有 maths_transform.cpp 的 456 行。
这个比例(2888 : 456 ≈ 6.3 : 1)在整个库里是极端的。第一章统计过全库是 31,982 行头文件对 111,673 行实现,比例 1 : 3.5——实现远多于声明。数学模块完全反过来:几乎所有的算术都在头文件里,以 constexpr 内联函数的形式存在。
// include/vsg/maths/mat4.h:169
template<typename T>
t_mat4<T> operator*(const t_mat4<T>& lhs, const t_mat4<T>& rhs)
{
return t_mat4<T>(dot(lhs, rhs, 0, 0), dot(lhs, rhs, 0, 1), ...);
}
operator* 没有 constexpr(因为 dot 是普通函数,虽然它本可以),但 translate/scale/rotate(quat)/perspective 全都是 constexpr:
// include/vsg/maths/transform.h:66
template<typename T>
constexpr t_mat4<T> translate(T x, T y, T z)
{
const T zero(numbers<T>::zero());
const T one(numbers<T>::one());
return t_mat4<T>(one, zero, zero, zero,
zero, one, zero, zero,
zero, zero, one, zero,
x, y, z, one);
}
constexpr 在这里不是为了"编译期算矩阵"(虽然 constexpr auto m = translate(1.0, 2.0, 3.0); 确实可以),而是为了两个更实际的目的:
第一,让编译器看到常量。 当 translate(0.0, 0.0, 0.0) 出现在代码里(这在构建节点的默认变换里很常见),constexpr 让编译器把 16 个元素全部折叠成字面量,t_mat4 的构造函数里那一堆 numbers<T>::zero() 调用全部消失。没有 constexpr,这 16 次函数调用在 -O0 下是真实的调用。
第二,保证头文件里的定义是"纯"的。 一个 constexpr 函数不能有副作用、不能分配内存、不能有未定义行为(严格来说 UB 在常量求值中会导致编译错误)。这条约束在 C++17 之后变松(constexpr 函数可以有 if、循环),但 VSG 的数学库全部写成单表达式或无分支形式,正好落在最严格的子集里。
这解释了为什么 maths_transform.cpp 只有 456 行:放进去的都是"必须有循环或必须查表"的东西——inverse(三个变体)、determinant、decompose、computeFrustumBound、坐标约定转换、ComputeTransform 访问者。除此之外的一切都在头文件里。
4.0.1 为什么不用 glm
这是每个读源码的人都会问的问题。三个理由,按权重排序:
constexpr的覆盖度。 2018 年 VSG 立项时,glm 的constexpr支持是残缺的(glm 0.9.9 只有部分函数标了GLM_CONSTEXPR,且依赖GLM_FORCE_CXX14之类的宏)。VSG 需要constexpr来支撑 4.0 节说的常量折叠。- 类型必须能被
vsg::Value<T>直接持有并序列化。vsg::vec3必须是一个可平凡复制、有固定内存布局、能memcmp的结构体(第一章 1.5 节的is_compatible用typeid,但Data::compare用逐字节比较)。glm 的vec3在开启 SIMD 时是 16 字节对齐、可能带 padding 的类型,sizeof(glm::vec3)在不同编译选项下不同——这对二进制序列化是灾难。VSG 的t_vec3<T>是union { T value[3]; struct { T x, y, z; }; ... },sizeof恒等于3 * sizeof(T),永远 12 或 24 字节。 - 坐标系约定。 glm 默认 Y-up、右手、
lookAt返回标准 GL 视矩阵。VSG 需要 Z-up(4.6 节)、reverse-Z(4.5 节)、Y 翻转的投影矩阵。这些都要自己写,用 glm 反而要包一层。
代价是什么都自己写:t_vec3 的四个 union 成员(x,y,z / r,g,b / s,t,p / value[3])在 GCC 下需要 -Wno-pedantic(quat.h 顶部有 #pragma GCC diagnostic ignored "-Wpedantic"),MSVC 需要 #pragma warning,这些都是匿名 struct 在 union 里的可移植性代价。
4.0.2 这一章要回答的五个问题
数学库的坑不在"公式对不对"(公式基本都是抄的标准实现),而在约定。五个问题,每一个都能让一个能编译、能跑、但结果错的程序诞生:
| 问题 | 错误的表现 | 本章位置 |
|---|---|---|
矩阵是行主序还是列主序?m[0] 是行还是列? | 转置错,光照全黑或全亮 | 4.1 |
A * B 是先 A 后 B,还是先 B 后 A? | 变换顺序反了,绕原点转而不是绕自身转 | 4.2 |
四元数乘法的手性?q * v 是旋转 v 还是 v 的逆? | 旋转方向反了 | 4.4 |
| 投影矩阵为什么 Y 是负的、Z 是反的? | 画面上下颠倒 / 深度测试全过或全不过 | 4.5 |
| 世界坐标到 10 万米,float 还够吗? | 远处顶点抖动(z-fighting 的兄弟) | 4.11 |
这五个问题全部有源码依据,不是"一般性建议"。
4.0.3 答案骨架
先给结论,再给坐标,最后给性质。十二行覆盖本章全部硬结论;"性质"一列只有三种取值——约定(改了就破坏 ABI 或图像)、缺陷(在特定输入下错且不报错)、取舍(换来了别的东西)。后面每一节都是对其中某一行的展开,读完全章可以回来核对这张表。
| # | 结论 | 证据坐标 | 性质 |
|---|---|---|---|
| 1 | t_mat4::value 是 t_vec4 的数组,m[0] 是第一列 | include/vsg/maths/mat4.h:30 | 约定:与 GLSL 一致,可直接 memcpy 进 UBO |
| 2 | t_mat4::operator() 先列后行,与数学记号 A(i,j) 相反 | include/vsg/maths/mat4.h:86 | 约定:所有调用点都要按 (c, r) 读 |
| 3 | dot(lhs, rhs, c, r) 用 lhs[k][r] * rhs[c][k] 累加,就是标准 lhs × rhs | include/vsg/maths/mat4.h:163 | 约定:A * B 先作用 B |
| 4 | t_quat::operator* 把 lhs 与 rhs 对调,a * b 算的是 rhs ⊗ lhs | include/vsg/maths/quat.h:205 | 约定:反 Hamilton,OSG 遗产 |
| 5 | t_quat 的 inverse 除 length(v) 而不是 dot(v,v) | include/vsg/maths/quat.h:263 | 缺陷:仅非单位四元数暴露 |
| 6 | inverse 对奇异矩阵返回 quiet_NaN 填充的整矩阵 | src/vsg/maths/maths_transform.cpp:137 | 取舍:响亮失败,但零诊断 |
| 7 | perspective 的 -f 与 1 → 0 深度范围是一对,不能拆 | include/vsg/maths/transform.h:147 | 约定:与 Vulkan NDC + GREATER 配套 |
| 8 | t_plane 是 n·x = -p,distance 用 dot(pl.n, v) + pl.p | include/vsg/maths/plane.h:145 | 约定:法线正向侧为正距离 |
| 9 | t_decompose 只在 scale[i] == 0.0 时返回 false,其余输入一律 true | src/vsg/maths/maths_transform.cpp:250 | 缺陷:负缩放与 skew 都不设防 |
| 10 | t_computeFrustumBound 的球心由 (b2 + c2 - a2)/(2c) 在 near_center、far_center 之间插值 | src/vsg/maths/maths_transform.cpp:342 | 取舍:数学最优,但深度范围硬编码 |
| 11 | opaque_white() 返回 color_cast<T>(0, 0, 1, 1),是蓝色 | include/vsg/maths/color.h:76 | 缺陷:CPU 软采样与 GPU 不一致 |
| 12 | 精度唯一损失点是 mat4 newmatrix(matrixStack.top()) | include/vsg/vk/State.h:172 | 取舍:矩阵链误差不累积,顶点数据救不回 |
读这张表要注意第 5、9、11 行的共性:三者都在"最常见输入"下完全正确,所以单元测试、示例程序、日常开发全都碰不到;只有把未归一化的四元数、镜像矩阵、VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE 这三样东西凑齐,才会看到它们。第 6 行是唯一"故意让错误可见"的设计——NaN 让物体消失,比返回单位阵更容易被发现。
4.1 存储布局:m[0] 是第一列
include/vsg/maths/mat4.h 第 24 行:
// include/vsg/maths/mat4.h:23
template<typename T>
struct t_mat4
{
public:
using value_type = T;
using column_type = t_vec4<T>;
column_type value[4];
value[4] 的类型是 t_vec4<T>,也就是 4x4 矩阵被存成 4 个 vec4。 这四个 vec4 是列,不是行。证据在构造函数里:
// include/vsg/maths/mat4.h:44
constexpr t_mat4(value_type v0, value_type v1, value_type v2, value_type v3, /* column 0 */
value_type v4, value_type v5, value_type v6, value_type v7, /* column 1 */
value_type v8, value_type v9, value_type v10, value_type v11, /* column 2 */
value_type v12, value_type v13, value_type v14, value_type v15) /* column 3 */
注释写得很清楚:前四个数是第 0 列。这是 column-major(列主序) 存储,和 GLSL 的 mat4 完全一致。
4.1.1 内存里的 64 字节长什么样
拿 vsg::translate(1, 2, 3) 举例。它是一个"沿 xyz 平移"的矩阵,数学上写成行主序是:
| 1 0 0 1 |
| 0 1 0 2 |
| 0 0 1 3 |
| 0 0 0 1 |
但 VSG 在内存里存的是转置的:
| 偏移 | 元素 | 数学含义 |
|---|---|---|
| 0 | 1 | m(0,0) |
| 4 | 0 | m(0,1) |
| 8 | 0 | m(0,2) |
| 12 | 0 | m(0,3) |
| 16 | 0 | m(1,0) |
| 20 | 1 | m(1,1) |
| 24 | 0 | m(1,2) |
| 28 | 0 | m(1,3) |
| 32 | 0 | m(2,0) |
| 36 | 0 | m(2,1) |
| 40 | 1 | m(2,2) |
| 44 | 0 | m(2,3) |
| 48 | 1 | m(3,0) ← 平移 x |
| 52 | 2 | m(3,1) ← 平移 y |
| 56 | 3 | m(3,2) ← 平移 z |
| 60 | 1 | m(3,3) |
注意最后一行:平移量存在偏移 48–56,也就是第 3 列的前三个元素。 在行主序的直觉里,"平移在最后一列";在列主序的存储里,第 3 列在内存的最后 16 字节,所以平移到内存末尾——两种说法不矛盾,只是"列"这个词的指向不同。
这 64 字节原封不动地传给 GPU 时,Vulkan 的 mat4 按相同规则解释:mat4[3] 是第 3 列,mat4[3].xyz 是平移。所以 memcpy(ubo_data, &matrix, 64) 是正确的,不需要转置——t_mat4::data() 给出的正是这 64 字节的首地址(include/vsg/maths/mat4.h:119)。这是列主序存储带来的最大好处:CPU 侧和 GPU 侧零转换。
4.1.2 t_mat4::operator() 的参数顺序是 (列, 行)
// include/vsg/maths/mat4.h:85
value_type& operator()(std::size_t c, std::size_t r) { return value[c][r]; }
第一个参数是列,第二个是行。 这和数学教科书的 A(i,j)(第 i 行第 j 列)相反。源码里所有 m(c, r) 的调用点都必须按这个顺序读,否则会悄悄转置。
这个设计是刻意的:value[c][r] 直接对应成员访问,不做任何重排。如果写成 operator()(r, c) { return value[c][r]; } 也能工作,但每次调用都要做一次参数交换的心智负担,而且和 operator[](返回列)的直觉冲突——m[1][2] 到底是"第 1 列第 2 行"还是"第 1 行第 2 列"?既然 operator[] 返回的是 vec4,它必然是列(因为存储是列),所以 operator() 也统一成列优先。
4.1.3 t_mat4::data() 返回的是首元素地址,可以直接喂给 Vulkan
// include/vsg/maths/mat4.h:118
T* data() { return value[0].data(); }
value[0] 是第一个 vec4,它的 data() 是自己的 value 数组首地址。因为 t_vec4 也是 union 无 padding(sizeof(vec4) == 4 * sizeof(float) == 16),所以 value[0].data() 就是整个矩阵的首地址,data() 之后的 64 字节是连续的。
这条链依赖于三个"无 padding"假设:
sizeof(t_vec4<float>) == 16alignof(t_vec4<float>) == 4(不是 16!因为t_vec4里没有alignas,也没有 SIMD 类型)- 数组
value[4]的元素之间无间隙
第 2 条值得单独说:alignof(vec4) == 4。这意味着 t_mat4<float> 的对齐要求只有 4 字节,而不是 16。std::vector<t_mat4> 的元素之间是紧密排列的 64 字节,没有 16 字节对齐保证。把这样的数组首地址 reinterpret_cast 成 float* 传给 vkCmdUpdateBuffer 没问题(Vulkan 只要求 4 字节对齐),但如果你的代码用 SSE/AVX intrinsics 读写它,_mm_load_ps 会因为未对齐而崩溃。
对比 glm:glm::mat4 在 SSE 开启时是 alignas(16),std::vector<glm::mat4> 会按 16 字节对齐分配——这正是 VSG 不敢用 glm 的理由之一(4.0.1 节第三条之外的隐含理由:对齐要求会影响所有持有它的容器)。
4.1.4 t_mat3 只有 36 字节,和 std140 不兼容
// include/vsg/maths/mat3.h:21
template<typename T>
struct t_mat3
{
using column_type = t_vec3<T>;
column_type value[3]; // 3 * 12 = 36 字节(float)
sizeof(mat3) == 36。而 GLSL 的 mat3 在 std140 布局下占 48 字节(每列补到 16 字节),在 std430 下也是 48(矩阵的列总是按 vec4 对齐)。所以不能把 vsg::mat3 直接塞进 UBO/SSBO。
同样的坑在 vec3 上:sizeof(vec3) == 12,而 std140/std430 里 vec3 的步长是 16。
这不是 VSG 的 bug,是设计选择:CPU 侧的类型为"紧凑"优化(省内存、缓存友好),GPU 侧的类型要另外定义。VSG 的做法是让用户在用 UBO 时自己写 vec4 或显式 padding,需要注意,改用 layout(std430, set=0, binding=0) buffer { vec3 data[]; } 并不能解决:std430 下 vec3 数组元素的步长同样是 16 字节。
正确的做法有三种:
- 着色器里用
float data[],CPU 侧也传float数组(最省心)。 - 用
vec4存 xyz + padding(浪费 25%,但对齐天然正确)。 - 用
layout(scalar)扩展(Vulkan 1.2+ 的VK_EXT_scalar_block_layout),此时 vec3 步长 12,和vsg::vec3完全一致。
第 3 种是唯一能做到"零拷贝"的方案,VSG 的 raytracing 和部分 meshshaders 代码依赖它。但它是扩展,不是核心特性。
4.2 乘法:A * B 意味着"先 B 后 A"
include/vsg/maths/mat4.h 第 161 行:
// include/vsg/maths/mat4.h:160
template<typename T>
T dot(const t_mat4<T>& lhs, const t_mat4<T>& rhs, int c, int r)
{
return lhs[0][r] * rhs[c][0] +
lhs[1][r] * rhs[c][1] +
lhs[2][r] * rhs[c][2] +
lhs[3][r] * rhs[c][3];
}
dot(lhs, rhs, c, r) 计算的是结果矩阵的 (c, r) 元素。看它的展开:lhs[0][r] 是 lhs 的第 0 列第 r 行,rhs[c][0] 是 rhs 的第 c 列第 0 行。四项相加,是 lhs 的第 r 行 · rhs 的第 c 列——标准的矩阵乘法 (lhs * rhs)(r, c)。参数名叫 (c, r) 但计算的是 (r, c) 的公式,只是因为结果的存储顺序是列优先,写入时按 (c, r) 索引更自然。
// include/vsg/maths/mat4.h:170
t_mat4<T> operator*(const t_mat4<T>& lhs, const t_mat4<T>& rhs)
{
return t_mat4<T>(dot(lhs, rhs, 0, 0), dot(lhs, rhs, 0, 1), dot(lhs, rhs, 0, 2), dot(lhs, rhs, 0, 3),
dot(lhs, rhs, 1, 0), dot(lhs, rhs, 1, 1), ...);
}
构造函数的 16 个参数按"列 0 的 4 个元素、列 1 的 4 个元素…"排列,所以前四个 dot(lhs, rhs, 0, 0..3) 是在算结果的列 0(即 (0,0)...(0,3))。乘法本身是标准的 lhs × rhs,没有任何转置。
4.2.1 列向量约定
operator*(mat4, vec4):
// include/vsg/maths/mat4.h:179
t_vec4<T> operator*(const t_mat4<T>& lhs, const t_vec4<T>& rhs)
{
return t_vec4<T>(lhs[0][0] * rhs[0] + lhs[1][0] * rhs[1] + lhs[2][0] * rhs[2] + lhs[3][0] * rhs[3],
lhs[0][1] * rhs[0] + lhs[1][1] * rhs[1] + lhs[2][1] * rhs[2] + lhs[3][1] * rhs[3],
...);
}
结果是 lhs 的第 0 行 · rhs、lhs 的第 1 行 · rhs……即 M * v,v 是列向量。这和 GLSL 的 M * v 一致。
于是链式变换的读法是从右往左:
auto mvp = projectionMatrix * viewMatrix * modelMatrix; // 等价于 P * (V * (M * p))
auto clip = mvp * vec4(position, 1.0); // 先 M,再 V,最后 P
translate(10,0,0) * rotate(angle, axis) 的含义是"先旋转,再平移"——绕自身旋转然后移动到 (10,0,0)。反过来写 rotate * translate 是"先平移再旋转",物体会绕世界原点转圈。这是 4.0.2 表格第二行那个坑。
4.2.2 左乘行向量:v * M 是转置乘
// include/vsg/maths/mat4.h:201
/* Left multiplication of a row vector. Equivalent to multiplying the column vector by the
matrix transpose. */
template<typename T>
t_vec4<T> operator*(const t_vec4<T>& lhs, const t_mat4<T>& rhs)
{
return t_vec4<T>(lhs[0] * rhs[0][0] + lhs[1] * rhs[0][1] + lhs[2] * rhs[0][2] + lhs[3] * rhs[0][3],
lhs[0] * rhs[1][0] + lhs[1] * rhs[1][1] + ...);
}
结果是 lhs · rhs 的第 0 列、lhs · rhs 的第 1 列……即 vᵀ * M,数学上等于 (Mᵀ * v)ᵀ。
VSG 同时提供了两种乘法,这在图形库里不常见(glm 也提供,但通过不同的类型)。它的用途是处理行主序的外部数据:某些格式(DirectX 的 .x、部分 CAD 导出)存的是行主序矩阵,读进来后逐元素填进 vsg::mat4 会得到转置矩阵。此时用 v * M 而不是 M * v 就能得到正确结果,不必显式转置 64 字节。
陷阱在于它是隐式可用的:mat4 * vec4 和 vec4 * mat4 都能编译,结果却差一个转置。写 auto p = m * v; 和 auto p = v * m; 编译器都不会警告。
4.2.3 vec3 的乘法带透视除法
// include/vsg/maths/mat4.h:226
template<typename T>
t_vec3<T> operator*(const t_mat4<T>& lhs, const t_vec3<T>& rhs)
{
T inv = numbers<T>::one() / (lhs[0][3] * rhs[0] + lhs[1][3] * rhs[1] + lhs[2][3] * rhs[2] + lhs[3][3]);
return t_vec3<T>((lhs[0][0] * rhs[0] + lhs[1][0] * rhs[1] + lhs[2][0] * rhs[2] + lhs[3][0]) * inv, ...);
}
lhs[0][3]、lhs[1][3]、lhs[2][3]、lhs[3][3] 是矩阵第 3 行的四个元素(因为 [c][r],r=3 是第 4 行)。除以它,就是齐次坐标的 w 分量——做了透视除法。
vec4 h = M * vec4(v, 1.0);
vec3 result = h.xyz / h.w;
对于 lookAt 和 perspective 之外的仿射矩阵(第 3 行为 (0,0,0,1)),除法是除以 1,无影响。但对于投影矩阵乘世界坐标(跳过视矩阵),透视除法是必需的。
副作用:如果 w == 0(点在相机平面上),结果是 inf/NaN。而 t_vec3 的乘法没有零检查。这是 4.0.2 表格第四行坑的来源之一。
4.2.4 平面乘矩阵:右乘与左乘的两个版本
mat4.h 里有两个 operator* 处理 t_plane,注释写得很详细:
// include/vsg/maths/mat4.h:187
/* Right multiplication of a matrix and a plane. This can't be used directly to transform a
plane from one coordinate system to another using the coordinate system's matrix; the inverse
transpose of the matrix should be used. */
template<typename T, typename R>
t_plane<R> operator*(const t_mat4<T>& lhs, const t_plane<R>& rhs)
{
t_plane<R> transformed(lhs[0][0] * rhs[0] + lhs[1][0] * rhs[1] + lhs[2][0] * rhs[2] + lhs[3][0] * rhs[3], ...);
T inv = static_cast<R>(1.0) / length(transformed.n);
return t_plane<T>(transformed[0] * inv, transformed[1] * inv, transformed[2] * inv, transformed[3] * inv);
}
两个关键点:
第一,注释在警告你"这不能直接用来做坐标系变换"。 平面方程是 n·x + p = 0。变换 x' = Mx 后,新的平面方程要把 x = M⁻¹x' 代入:n·M⁻¹x' + p = 0,即 (M⁻ᵀn)·x' + p = 0。所以平面的法线要用 M⁻ᵀ(逆转置)变换,不是 M。
但代码里乘的是 lhs,不是 lhs⁻ᵀ。所以这个 operator* 只有在 lhs 本身就是 M⁻ᵀ 时才对。注释里说"the inverse transpose of the matrix should be used"——意思是调用者负责传逆转置。
第二,乘完之后重新归一化法线。 inv = 1 / length(n),四项全除。这不是多余的:M⁻ᵀn 的长度一般不是 1(除非 M 是纯旋转),而归一化后 p 才是真正的"到原点的距离"。如果不归一化,distance(plane, v) 返回的是"距离 × 法线长度",判断 distance < -radius 时就会错。
这个设计有个隐蔽的代价:每变换一个平面要开一次平方根。视锥剔除每帧要对 6 个平面 × N 个包围球做测试,如果平面每帧都重新变换,就是 6 次 sqrt——可以忽略。但如果你的代码在循环里反复变换同一个平面,应该缓存结果。
operator*(plane, mat4) 是左乘版本,注释说明了它的适用场景:
// include/vsg/maths/mat4.h:212
/* Left multiplication of a plane and a matrix. If the matrix is the inverse of the
local-to-world transform i.e., the world-to-local transform, then this can be used directly
to transform a plane from a coordinate system's local coordinates to world coordinates. */
当矩阵是 world-to-local(即 local-to-world 的逆)时,plane * M 直接把平面从局部坐标变到世界坐标。 这句话看着绕,推导一遍就清楚了:设 L 是 local-to-world,W = L⁻¹ 是 world-to-local。想求世界空间的平面 n_w,需要 (L⁻ᵀ) n_l = (Wᵀ) n_l。而 n_lᵀ · W 就是 (Wᵀ n_l)ᵀ——左乘 W,等价于右乘 Wᵀ,也就是右乘 L⁻ᵀ。所以 plane * W 得到世界空间平面。✓
这条规则在 ComputeBounds 和 Intersector 里被反复使用:遍历时栈上压的是 world-to-local 矩阵(因为要反向走),剔除时又要用它把局部包围球/平面变到世界空间。
4.3 构造:三个基础变换的逐元素对照
4.3.1 translate
// include/vsg/maths/transform.h:67
constexpr t_mat4<T> translate(T x, T y, T z)
{
return t_mat4<T>(one, zero, zero, zero, // column 0
zero, one, zero, zero, // column 1
zero, zero, one, zero, // column 2
x, y, z, one); // column 3
}
第 3 列是 (x, y, z, 1)。在列主序存储里这是内存最后 16 字节,对应数学上的"第 4 列"。M * v 时,v = (0,0,0,1) 得到 (x,y,z,1)——原点被搬到 (x,y,z)。✓
4.3.2 scale
// include/vsg/maths/transform.h:98
constexpr t_mat4<T> scale(T sx, T sy, T sz)
{
return t_mat4<T>(sx, zero, zero, zero,
zero, sy, zero, zero,
zero, zero, sz, zero,
zero, zero, zero, one);
}
对角矩阵。注意单参 scale(T s) 是等比缩放,三参版本才按轴分别给(include/vsg/maths/transform.h:86)——两个重载都在源码里,只差一个参数,容易看错。
4.3.3 rotate(quat):2(xy ± wz) 的展开
// include/vsg/maths/transform.h:20
template<typename T>
constexpr t_mat4<T> rotate(const t_quat<T>& q)
{
T qxx(q.x * q.x), qyy(q.y * q.y), qzz(q.z * q.z);
T qxy(q.x * q.y), qxz(q.x * q.z), qyz(q.y * q.z);
T qwx(q.w * q.x), qwy(q.w * q.y), qwz(q.w * q.z);
const T zero(numbers<T>::zero());
const T one(numbers<T>::one());
const T two(numbers<T>::two());
return t_mat4<T>(one - two * (qyy + qzz), two * (qxy + qwz), two * (qxz - qwy), zero,
two * (qxy - qwz), one - two * (qxx + qzz), two * (qyz + qwx), zero,
two * (qxz + qwy), two * (qyz - qwx), one - two * (qxx + qyy), zero,
zero, zero, zero, one);
}
逐个对照数学公式。四元数 q = (x, y, z, w) 对应的旋转矩阵(列主序,value[c][r]):
| 位置 | 代码 | 数学公式 |
|---|---|---|
| (0,0) | 1 - 2(y² + z²) | 1 - 2y² - 2z² ✓ |
| (0,1) | 2(xy + wz) | 第 0 列第 1 行 = 2(xy + wz) ✓ |
| (0,2) | 2(xz - wy) | 2(xz - wy) ✓ |
| (1,0) | 2(xy - wz) | 2(xy - wz) ✓ |
| (1,1) | 1 - 2(x² + z²) | ✓ |
| (1,2) | 2(yz + wx) | ✓ |
| (2,0) | 2(xz + wy) | ✓ |
| (2,1) | 2(yz - wx) | ✓ |
| (2,2) | 1 - 2(x² + y²) | ✓ |
这是标准的"单位四元数→旋转矩阵"公式。注意它假设 q 是单位四元数:公式里的 1 - 2(y²+z²) 是从 w² + x² - y² - z²(在 w²+x²+y²+z²=1 时化简而来)。如果 q 没归一化,矩阵会带上 |q|² 的缩放。
rotate(const t_quat<T>&) 不检查长度,也不归一化(include/vsg/maths/transform.h:21)。这是 4.4 节"四元数必须自己归一化"的第一条依据。
4.3.4 rotate(angle, axis):不归一化轴向
// include/vsg/maths/transform.h:44
template<typename T>
t_mat4<T> rotate(T angle_radians, T x, T y, T z)
{
const T c = std::cos(angle_radians);
const T s = std::sin(angle_radians);
const T one_minus_c = one - c;
return t_mat4<T>(x * x * one_minus_c + c, y * x * one_minus_c + z * s, x * z * one_minus_c - y * s, zero,
x * y * one_minus_c - z * s, y * y * one_minus_c + c, y * z * one_minus_c + x * s, zero,
x * z * one_minus_c + y * s, y * z * one_minus_c - x * s, z * z * one_minus_c + c, zero,
zero, zero, zero, one);
}
这是 Rodrigues 公式的矩阵形式。它假设 (x, y, z) 是单位向量——公式里的 x*x*(1-c) + c 只在 x²+y²+z²=1 时才给出正确的对角项。
对照 rotate(quat):同一个位置 (1,2) 是 two*(qyz + qwx),展开成 2(yz + wx);而 rotate(angle, axis) 的 (1,2) 是 y*z*(1-c) + x*s。代入 q = (x·sin(θ/2), y·sin(θ/2), z·sin(θ/2), cos(θ/2)):
2(yz·sin²(θ/2) + x·sin(θ/2)cos(θ/2))=2yz·sin²(θ/2) + x·sin(θ)- 而
y*z·(1-cos θ) + x·sin θ=2yz·sin²(θ/2) + x sin θ✓
两者一致。但前提是 (x,y,z) 单位长——因为 q 的构造会用 sinhalfangle 乘上归一化的轴(set(angle, axis) 里有 inversenorm = 1/len),而 rotate(angle, x, y, z) 直接用传入的 x,y,z。
一个具体的错误示例:
// 想绕 (0, 0, 2) 转 45°
auto m = vsg::rotate(vsg::radians(45.0f), 0.0f, 0.0f, 2.0f);
// 得到的是绕 z 轴转 45° 且整体放大 4 倍的矩阵(主轴项变成 4*(1-c)+c)
正确写法是 vsg::rotate(angle, vsg::vec3(0,0,1)),或用 vsg::rotate(vsg::quat(angle, vsg::vec3(0,0,1)))。后者安全,因为 quat::set(angle, axis) 内部做了 1/len。
这是一个"能编译、能跑、不崩溃、只是结果错"的坑,而且错误的表现是"物体被拉伸",不是"旋转角度不对",很难第一时间归因到轴的归一化。
4.3.5 transpose
// include/vsg/maths/transform.h:126
constexpr t_mat4<T> transpose(const t_mat4<T>& m)
{
return t_mat4<T>(m[0][0], m[1][0], m[2][0], m[3][0], // 结果的 column 0 = m 的 row 0
m[0][1], m[1][1], m[2][1], m[3][1], // 结果的 column 1 = m 的 row 1
m[0][2], m[1][2], m[2][2], m[3][2],
m[0][3], m[1][3], m[2][3], m[3][3]);
}
结果的 value[0](第 0 列)= (m[0][0], m[1][0], m[2][0], m[3][0]),也就是 m 的第 0 行。所以 result(c, r) = m(r, c) ✓。
t_mat3 的转置是同样的写法,在 transform.h 第 117 行。没有 t_mat2 的转置(mat2.h 里没有)——因为 2x2 的转置在实践中没有调用点。
4.4 四元数:五个约定与三个真实的 bug
include/vsg/maths/quat.h 302 行,是全库注释最少、坑最多的文件之一。先看布局。
4.4.1 布局:x, y, z, w 与 GLSL 的 vec4
// include/vsg/maths/quat.h:33
template<typename T>
struct t_quat
{
union
{
value_type value[4];
struct { value_type x, y, z, w; };
};
constexpr t_quat() :
value{zero(), zero(), zero(), one()} {}
默认构造是 (0,0,0,1)——单位四元数(模长 1,对应"旋转 0 度")。这和很多库的 (0,0,0,0) 不同:glm 的 quat 默认构造是未初始化,Eigen 的 Quaterniond 默认是 (1,0,0,0) 的 w-first 顺序。
顺序是 x, y, z, w(w 最后),和 GLSL 里 vec4(x,y,z,w) 的约定一致,也和大多数论文的写法一致。对比 Eigen:Eigen 内部存 (x,y,z,w) 但构造函数是 (w,x,y,z)——传参顺序和内存顺序相反。VSG 的 t_quat(x, y, z, w) 构造和内存顺序一致,读起来不别扭。
sizeof(t_quat<float>) == 16,alignof == 4(include/vsg/maths/quat.h:68 的 size() 返回 4,即四个 value_type)。可以塞进 vec4Array 当实例属性用(比如骨骼动画的旋转数组),此时每个四元数占 16 字节,正好是 std430 的 vec4 stride。
4.4.2 set(angle, axis):零轴的静默重置
// include/vsg/maths/quat.h:94
void set(value_type angle_radians, const t_vec3<value_type>& axis)
{
value_type len = length(axis);
if (len < numbers<value_type>::epsilon())
{
// ~zero length axis, so reset rotation to zero.
*this = {};
return;
}
value_type inversenorm = numbers<value_type>::one() / len;
value_type coshalfangle = cos(numbers<value_type>::half() * angle_radians);
value_type sinhalfangle = sin(numbers<value_type>::half() * angle_radians);
x = axis.x * sinhalfangle * inversenorm;
y = axis.y * sinhalfangle * inversenorm;
z = axis.z * sinhalfangle * inversenorm;
w = coshalfangle;
}
三个细节:
第一,零轴被静默重置为单位四元数。 len < epsilon() 时 *this = {},即 (0,0,0,1)。不报错、不警告。 这个行为在"轴向来自用户输入或法线计算"时很危险:如果轴是零向量(比如两个面完全重合导致叉积为零),你期望的是"报错"或"用默认轴",得到的是"忽略这次旋转"。
第二,epsilon() 是相对容差,但这里当绝对容差用。 numbers<T>::epsilon() 是 std::numeric_limits<T>::epsilon():float 是 1.19e-7,double 是 2.22e-16。用它判断"轴是否为零"意味着只有长度小于 1e-7 的轴才被当作零。一个长度 1e-6 的轴(在数值上已经完全不靠谱)会被正常归一化,方向完全由浮点噪声决定。正确做法是用一个业务相关的阈值(比如 1e-6),而不是机器 epsilon。
第三,cos/sin 是 std::cos/std::sin(在 cmath 里,通过 ADL 或全局命名空间),不是 constexpr——coshalfangle 与 sinhalfangle 都是运行期调用(include/vsg/maths/quat.h:105)。** 所以 set(angle, axis) 不是 constexpr 函数,尽管 t_quat(angle, axis) 的构造函数声明成 constexpr 了(constexpr t_quat(value_type angle_radians, const t_vec3<value_type>& axis))。这在 C++17 下是合法的(constexpr 构造函数可以调用非 constexpr 函数,只要不在常量求值中使用),但意味着不能写 constexpr vsg::quat q(vsg::radians(45.0), vsg::vec3(0,0,1));——编译器会报"不是常量表达式"。
4.4.3 set(from, to):三个隐患
// include/vsg/maths/quat.h:114
void set(const t_vec3<value_type>& from, const t_vec3<value_type>& to)
{
value_type dot_pd = vsg::dot(from, to);
value_type div = std::sqrt(length2(from) * length2(to));
vsg::dvec3 axis;
if (div - std::abs(dot_pd) < numbers<value_type>::epsilon())
{
axis = orthogonal(from);
}
else
{
axis = cross(from, to);
}
value_type len = length(axis);
double angle_radians = acos(dot_pd / div);
...
}
这个函数算"把 from 转到 to 的最短旋转"。三个隐患,按严重程度排序:
隐患 1:from 或 to 为零向量时,全部 NaN。
div = sqrt(0) = 0,dot_pd / div = 0/0 = NaN,acos(NaN) = NaN,于是 q = (NaN, NaN, NaN, NaN)。没有零检查。 一个 NaN 四元数传给 rotate(q) 会得到全 NaN 矩阵,再传给 GPU 会让整个物体消失(NaN 的顶点被裁剪掉)——而 CPU 侧一切正常,没有任何断言。
隐患 2:acos(dot_pd / div) 没有 clamp。
数学上 |dot_pd| ≤ div(柯西-施瓦茨),但浮点运算会让比值略微超过 1。比如 from == to == (1,0,0):dot_pd = 1,div = sqrt(1*1) = 1,比值恰好 1,acos(1) = 0 ✓。但如果 from == to 且分量有误差,dot_pd 可能算出 1.0000001,acos 返回 NaN。
实践中的触发条件:from 和 to 都是单位向量、且夹角极小(< 1e-4 弧度)。此时 dot_pd/div 极易超过 1。
正确写法是 acos(std::min<T>(1.0, std::max<T>(-1.0, dot_pd / div)))。VSG 没这么做。
隐患 3:axis 声明成 vsg::dvec3,在 T = float 时存在精度混合。
// include/vsg/maths/quat.h:118
vsg::dvec3 axis; // 永远是 double
axis = orthogonal(from); // from 是 vec3f,隐式转换成 dvec3
value_type len = length(axis); // len 是 float,长度在 double 里算完再截断
对 T = float 来说,axis 用 double 存 float 数据没有任何精度收益(from 本来就是 float),反而让 cross(from, to) 的结果先从 float 提升到 double、length(axis) 再降回 float。这段代码不会错,但它暴露了一个更普遍的现象:VSG 的标量类型参数化(template<typename T>)在实现细节上并不严格——mat4.h 的 operator*(mat4, plane) 里甚至有 T inv = static_cast<R>(1.0) / length(...),把 R 类型的值赋给 T 变量。
4.4.4 operator*:反过来的乘法顺序
这是全章最重要的一节。
// include/vsg/maths/quat.h:201
// Rotate a quaternion by another quaternion
template<typename T>
constexpr t_quat<T> operator*(const t_quat<T>& lhs, const t_quat<T>& rhs)
{
t_quat<T> q(rhs[3] * lhs[0] + rhs[0] * lhs[3] + rhs[1] * lhs[2] - rhs[2] * lhs[1],
rhs[3] * lhs[1] - rhs[0] * lhs[2] + rhs[1] * lhs[3] + rhs[2] * lhs[0],
rhs[3] * lhs[2] + rhs[0] * lhs[1] - rhs[1] * lhs[0] + rhs[2] * lhs[3],
rhs[3] * lhs[3] - rhs[0] * lhs[0] - rhs[1] * lhs[1] - rhs[2] * lhs[2]);
return q;
}
标准的 Hamilton 积 p ⊗ q(p 左乘 q)的 x 分量是:
(p ⊗ q).x = p.w·q.x + p.x·q.w + p.y·q.z - p.z·q.y
而代码写的是:
rhs.w·lhs.x + rhs.x·lhs.w + rhs.y·lhs.z - rhs.z·lhs.y
把 lhs 和 rhs 对调,正好是 rhs ⊗ lhs。 也就是说:
auto c = a * b; // c == b ⊗ a(Hamilton 积里 b 在左)
这不是笔误。OSG 的 osg::Quat::operator* 也是这个顺序,VSG 直接继承了这个约定。
先把结论写在前面:
vsg::quat的a * b表示"先做 a,再做 b"(从左往右读);vsg::mat4的A * B表示"先做 B,再做 A"(从右往左读)。两者的阅读顺序相反。
推导分三步。
第一步:Hamilton 积 p ⊗ q 对应旋转矩阵 R(p) R(q)。 作用于列向量 v 时是 R(p)(R(q) v)——先 q 后 p。这是 Hamilton 积的教科书性质。
第二步:operator*(lhs, rhs) 算的是 rhs ⊗ lhs。 所以 a * b 对应 R(b) R(a),作用于 v 时是 R(b)(R(a) v)——先 a 后 b。反 Hamilton 的定义,正好把"从右往左"翻成"从左往右"。
第三步:数值验证。 取 q1 = R_x(90°)、q2 = R_z(90°)、v = (1,0,0):
- 四元数路线:
q = q1 * q2↔R(q2) R(q1) = R_z(90°) R_x(90°)。- 先
R_x(90°)(1,0,0) = (1,0,0) - 再
R_z(90°)(1,0,0) = (0,1,0) - 结果
(0,1,0)
- 先
- 矩阵路线:
M = rotate(q1) * rotate(q2) = R_x(90°) R_z(90°)。- 先
R_z(90°)(1,0,0) = (0,1,0) - 再
R_x(90°)(0,1,0) = (0,0,1) - 结果
(0,0,1)
- 先
两个结果不同,于是:
vsg::rotate(q1 * q2) == vsg::rotate(q2) * vsg::rotate(q1) ✓
vsg::rotate(q1 * q2) == vsg::rotate(q1) * vsg::rotate(q2) ✗
OSG 为什么要反转? 因为场景图的变换链是"从父到子"写的:world = parent ∘ local。用矩阵时自然写成 M_world = M_parent * M_child;如果四元数按 Hamilton 约定,同一个链要写成 q_world = q_child ⊗ q_parent——两者的书写顺序相反。把 operator* 反过来,两者就统一成 parent * child 了。
代价是它与所有教科书公式的手性相反。 任何从论文、教材、其他引擎(Unity 的 Quaternion 是标准 Hamilton,Unreal 也是)搬过来的四元数公式,直接套用都会得到"反着转"的结果。
迁移时的铁律:
// 四元数版本:从左往右 = 从父到子
vsg::quat q = q_parent * q_child;
// 等价的矩阵版本:顺序必须反过来
vsg::dmat4 m = vsg::rotate(q_child) * vsg::rotate(q_parent);
Transform 家族有三个子类,它们的乘法顺序完全一致:
// include/vsg/nodes/MatrixTransform.h:32
dmat4 transform(const dmat4& mv) const final { return mv * matrix; }
dmat4 CoordinateFrame::transform(const dmat4& mv) const
{
return mv * translate(dvec3(origin)) * rotate(rotation);
}
两个都是 mv * 自身——左乘,把节点自身的变换放在右边,"先应用自身,再应用祖先"。
CoordinateFrame 是唯一在热路径上存四元数的节点(dquat rotation + dvec3 origin,为天文尺度坐标设计,4.11 节展开)。它每帧都要把四元数转成矩阵(rotate(rotation),21 次乘加),但转换之后仍然走矩阵乘法——四元数只负责"存储紧凑 + 插值方便",不参与累加。这个分工消除了"每次累加都要推理一次顺序"的问题。
4.4.5 q * v:nVidia SDK 的三次叉积
// include/vsg/maths/quat.h:213
// Rotate a vector by a quaternion
template<typename T>
constexpr t_vec3<T> operator*(const t_quat<T>& q, const t_vec3<T>& v)
{
// nVidia SDK implementation
t_vec3<T> uv, uuv;
t_vec3<T> qvec(q[0], q[1], q[2]);
uv = cross(qvec, v);
uuv = cross(qvec, uv);
uv *= (numbers<T>::two() * q[3]);
uuv *= numbers<T>::two();
return v + uv + uuv;
}
这是 v' = v + 2w(q_vec × v) + 2 q_vec × (q_vec × v),等价于 q v q* 的展开形式。
代价:两次 cross(各 6 乘 3 减)+ 两次标量乘 + 两次向量加 = 约 24 次浮点乘加。而"转成矩阵再乘"是 9 次乘加 + 1 次矩阵构建(那次构建要 20 多次乘加)。所以单次旋转向量,四元数路线更快;批量旋转 N 个向量,矩阵路线更快(构建一次,每次 9 乘加)。
切换点在 N ≈ 3–5。VSG 的 ComputeBounds 和 Intersector 里,包围盒的 8 个角点变换用的是矩阵(因为 dmat4 已经在栈上了),单个法线变换用四元数或 mat3。这个选择是被数据规模驱动的,不是风格。
注意 q * v 没有归一化 q,也没有检查 q 是否单位。非单位四元数会让结果带上缩放和错切。这是 4.4.4 节"必须自己归一化"的第二条依据。
4.4.6 inverse:除以 length 而不是 length²——一个真实的 bug
// include/vsg/maths/quat.h:259
template<typename T>
constexpr t_quat<T> inverse(const t_quat<T>& v)
{
t_quat<T> c = conjugate(v);
T inverse_len = numbers<T>::one() / length(v);
return t_quat<T>(c[0] * inverse_len, c[1] * inverse_len, c[2] * inverse_len, c[3] * inverse_len);
}
四元数的逆是 q⁻¹ = q* / |q|²(共轭除以模长的平方)。代码里是 q* / |q|——少了一次。
对单位四元数(|q| = 1),两者都对(都等于共轭)。所以这个 bug 在 99% 的用法里不会暴露:vsg::quat 的默认构造是单位四元数,set(angle, axis) 产生单位四元数,normalize() 之后是单位四元数。
它只在两种情况下错:
- 从外部数据读入未归一化的四元数(比如从 glTF/FBX 读进来,文件里写的是
(0.1, 0.2, 0.3, 0.9),模长 0.98)。 - 对四元数做了线性插值/累加(
q1 + q2之后模长不是 1)。
第 2 种在动画系统里很常见:vsg::mix(q1, q2, t) 返回的是归一化的四元数吗?看 mix 的实现:
// include/vsg/maths/quat.h:280
if ((numbers<T>::one() - cosomega) > numbers<T>::epsilon())
{
T omega = acos(cosomega);
T sinomega = sin(omega);
T scale_from = sin((numbers<T>::one() - r) * omega) / sinomega;
T scale_to = sin(r * omega) / sinomega;
return (from * scale_from) + (to * scale_to);
}
slerp 的结果模长是 1(数学上精确,浮点上差几个 ULP)✓。所以动画路径上通常是安全的。
但如果有人写 auto q = (q1 + q2) * 0.5; 再做 inverse,得到的是错的结果。表现是"逆变换不是逆变换",物体位置偏一点点——很难查。
修复只需要一个字符:T inverse_len = numbers<T>::one() / length2(v);。但注意 length2(quat) 不存在——quat.h 只定义了 length、dot、normalize,没有 length2。所以修复要么加一个 length2,要么写成 1 / (length(v) * length(v))(多一次乘法,但省一次 sqrt 的精度损失……实际上 length(v)*length(v) 和 dot(v,v) 差一个开方再平方,前者有额外舍入)。
正确的修复是 1 / dot(v, v)——一次四项乘加,零开方,零舍入。这也解释了为什么原代码写成 1/length(v) 可能是"从 normalize 复制过来"的产物:normalize 里确实是 1/length。
4.4.7 mix:最短路径与原地修改
// include/vsg/maths/quat.h:267
template<typename T>
constexpr t_quat<T> mix(const t_quat<T>& from, t_quat<T> to, T r)
{
T cosomega = dot(from, to);
if (cosomega < numbers<T>::zero())
{
cosomega = -cosomega;
to.x = -to.x;
to.y = -to.y;
to.z = -to.z;
to.w = -to.w;
}
...
}
to 是按值传递的(没有 &),所以那四行 to.x = -to.x 修改的是副本,不影响调用者。这是正确的做法,但读代码时容易误以为在改实参。
取反的意义:四元数 q 和 -q 表示同一个旋转(双重覆盖,double cover)。如果 dot(from,to) < 0,说明两个四元数在 4D 球面上隔了"半个大圆",直接插值会走远路——表现为物体旋转 350° 而不是 10°。取反后走短弧。
这个判断是 slerp 的必要条件,不是充分条件。 如果 dot 恰好为 0(夹角 90°),两条路径等长,代码走 cosomega >= 0 的分支,结果正确但可能不连续(相邻帧的符号可能跳变)。标准做法是在 dot == 0 时也要有个确定的选择(比如统一取正),VSG 没有特殊处理。
mix 的第二个分支(1 - cosomega <= epsilon,两个四元数极近)退化成线性插值 from*(1-r) + to*r。这个结果不归一化,模长略小于 1。在 r 很小的时候误差可忽略,但如果连续调用(比如 q = mix(q, target, 0.1) 每帧一次),误差会累积——这是"每帧朝目标插值 10%"这种写法的经典问题,与四元数本身无关。
4.5 投影矩阵:两个必需的"错误"
include/vsg/maths/transform.h 第 140 行的 perspective:
// include/vsg/maths/transform.h:134
/// create a 4x4 matrix for a Reverse depth perspective matrix,
/// Reverse depth convention: 1 to 0 depth range. Y NDC coordinates are inverted in Vulkan.
template<typename T>
constexpr t_mat4<T> perspective(T fovy_radians, T aspectRatio, T zNear, T zFar)
{
const T zero(numbers<T>::zero());
const T one(numbers<T>::one());
T f = static_cast<T>(one / std::tan(fovy_radians * numbers<T>::half()));
T r = static_cast<T>(one / (zFar - zNear));
return t_mat4<T>(f / aspectRatio, zero, zero, zero,
zero, -f, zero, zero,
zero, zero, zNear * r, -one,
zero, zero, (zFar * zNear) * r, zero);
}
注释已经点明了两件事:reverse depth(1 到 0)、Vulkan 的 NDC Y 轴向下。这两个都是"和 OpenGL 直觉相反"的地方,而且都是必需的。
4.5.1 把这 16 个数还原成矩阵
按列主序展开(value[c][r]),写成行主序的矩阵是:
| f/aspect 0 0 0 |
| 0 -f 0 0 |
| 0 0 zNear·r zFar·zNear·r |
| 0 0 -1 0 |
其中 f = 1/tan(fovy/2)、r = 1/(zFar - zNear)。
作用于视空间点 (x, y, z, 1)(右手系,相机看向 -Z):
x' = (f/aspect) · x
y' = -f · y
z' = zNear·r·z + zFar·zNear·r = r·zNear·(z + zFar)
w' = -z
4.5.2 第一个"错误":y' = -f·y
如果照抄 OpenGL 的 gluPerspective,y' 这一项应该是 f·y(正号)。VSG 写成 -f,是故意翻 Y。
原因在 Vulkan 的 NDC:VkViewport 描述的是"从 NDC 到屏幕"的映射,而 Vulkan 的 NDC 里 y = -1 是屏幕顶部,y = +1 是底部(OpenGL 相反)。如果投影矩阵不翻 Y,一个视空间里 y > 0 的点会被映射到 NDC 的 y > 0,也就是屏幕底部——整个画面上下颠倒。
所以 -f 抵掉了 Vulkan NDC 的方向。如果你把这个矩阵原样搬到 OpenGL,画面会颠倒;如果你把 GL 的矩阵搬到 VSG,画面也会颠倒。 两边都对,错的只有"混用"。
这就是 4.0.2 表格第四行的第一个来源。
4.5.3 第二个"错误":z' 的符号与 reverse-Z
算一下 NDC 的 z:
ndc.z = z' / w' = r·zNear·(z + zFar) / (-z)
代入近平面 z = -zNear:
r·zNear·(-zNear + zFar) / zNear = r·(zFar - zNear) = 1
代入远平面 z = -zFar:
r·zNear·(-zFar + zFar) / zFar = 0
近平面 → NDC z = 1,远平面 → NDC z = 0。 这就是注释里说的 "Reverse depth convention: 1 to 0 depth range"。
标准 OpenGL 是"近 → -1,远 → +1"(或者配合 glDepthRange(0,1) 变成"近 → 0,远 → 1")。VSG 把它反过来:近处深度值大,远处深度值小。
这个反转要求整条深度管线配合,三处必须一致:
| 环节 | 值 | 源码位置 |
|---|---|---|
| 投影矩阵 | 近 → 1,远 → 0 | include/vsg/maths/transform.h 第 140 行 |
| 深度比较 | VK_COMPARE_OP_GREATER | include/vsg/state/DepthStencilState.h 第 30 行 |
| 深度清除值 | 0.0f | include/vsg/app/RenderGraph.h 第 66 行 |
三个默认值是一套的。DepthStencilState 的成员声明:
// include/vsg/state/DepthStencilState.h:30
VkCompareOp depthCompareOp = VK_COMPARE_OP_GREATER;
不是 LESS。如果只改投影矩阵的符号(比如手写了一个标准透视矩阵),深度测试会全部失败——所有片元都被判定为"比已有深度更远",画面只剩清屏色。反过来只改 depthCompareOp 而不改矩阵,结果是"远的遮住近的"。
RenderGraph::setClearValues 的默认参数:
// include/vsg/app/RenderGraph.h:66
void setClearValues(VkClearColorValue clearColor = {{0.2f, 0.2f, 0.4f, 1.0f}},
VkClearDepthStencilValue clearDepthStencil = {0.0f, 0});
clearDepthStencil.depth = 0.0f——清成"最远"。在 reverse-Z 里 0 就是无穷远,所以新画的片元深度 > 0 一定通过 GREATER 测试。标准 Z 的清除值是 1.0,因为在标准 Z 里 1.0 才对应最远。
这四行代码构成的闭环,是初学 Vulkan 时最容易踩的坑之一:任何一环用了教科书上的 OpenGL 值,画面就会全黑或全白。
4.5.4 为什么值得做 reverse-Z
float32 的尾数是 24 位。在 [0.5, 1.0) 区间里,相邻可表示值的间隔是 2⁻²⁴ ≈ 6e-8;在 [2⁻²⁰, 2⁻¹⁹) 区间里,间隔是 2⁻⁴³。
标准 Z(近 → 0,远 → 1)的 NDC 深度分布是:
ndc.z = (f + n)/(f - n) - 2fn/((f - n)·|z|) (OpenGL 的 -1..1 形式,平移后是 0..1)
它随 1/|z| 变化,但带一个很大的常数偏移 (f+n)/(f-n)。当 f >> n(比如 n=1、f=10000)时,这个偏移接近 1,于是 z 从 1km 到 10km 的所有几何体都挤在 ndc.z ∈ [0.999, 1.0] 这个区间里。这个区间只有 2⁻²⁴ 的分辨率可用,10km 范围内能分辨的深度层数只有约 2⁻²⁴ / 0.001 ≈ 每层几百米——远处的两个相交面必然 z-fighting。
reverse-Z(近 → 1,远 → 0)的 NDC 深度是:
ndc.z = (n/(f - n))·(f/|z| - 1)
没有常数偏移,正比于 1/|z|。 而 float 的对数分布恰好与 1/|z| 的分布匹配:远处的 ndc.z 落在很小的数值区间(比如 0.001),那里 float 的绝对间隔极小(2⁻³³ 量级),相对精度仍然是 24 位。于是远近两端的分辨率被拉平了。
世界空间厚度与 NDC 精度的关系,在两种映射下 dz_ndc/d|z| 的推导结果完全相同:
Δz_world = Δndc · (f - n)·|z|² / (f·n)
差别只在 Δndc——NDC 值所在位置的 float 间隔(ULP)。取 n = 0.1、f = 10000((f-n)/(f·n) ≈ 10),算四组:
| 距离 |z| | 标准 Z 的 ndc | 该处 ULP | 世界空间厚度 | reverse-Z 的 ndc | 该处 ULP | 世界空间厚度 |
|---|---|---|---|---|---|---|
| 1 m | 0.90000 | 6.0e-8 | 0.6 μm | 0.09999 | 7.5e-9 | 0.075 μm |
| 100 m | 0.99900 | 6.0e-8 | 6 mm | 9.9e-4 | 1.2e-10 | 12 μm |
| 1000 m | 0.99990 | 6.0e-8 | 0.60 m | 9.0e-5 | 7.3e-12 | 73 μm |
| 5000 m | 0.99998 | 6.0e-8 | 15 m | 1.0e-5 | 9.1e-13 | 0.23 mm |
读这张表要抓住一件事:标准 Z 的 ndc 全都挤在 [0.9, 1.0] 这个 binade 里,ULP 恒为 2⁻²⁴;而 reverse-Z 的 ndc 随距离跨越了十几个 binade,越远 ULP 越小。 于是 1km 处的深度分辨率从 60 cm 提高到 73 μm,差了约 8000 倍;5km 处从 15 m 提高到 0.23 mm,差了约 65000 倍。
这就是为什么 f/n = 10⁵(0.1 到 10000)这种"看起来很不健康"的远近比,在 reverse-Z 下不再需要靠"把 zNear 调大"来救。标准 Z 在这个比例下的经典建议是"zNear 不要小于 0.1",而 reverse-Z 让 zNear 可以小到毫米级而不牺牲远处精度。
结论:在 f/n = 10⁵ 的配置下,reverse-Z 把 1km 外的深度分辨率提高了三到四个数量级。 代价是必须让深度比较、清除值、以及任何在 CPU 侧读深度做判断的代码(比如软粒子、SSAO 的重建)都记住"1 近 0 远"。
VSG 的注释在最后一行还给了建议:
/// For best precision we recommend setting up windows with windowTraits->depthFormat = VK_FORMAT_D32_SFLOAT;
D32_SFLOAT 是 32 位浮点深度(而不是 24 位定点的 D24_UNORM_S8_UINT)。reverse-Z 的全部收益建立在"深度缓冲用浮点"这个前提上——D24_UNORM 是均匀量化的定点格式,它不区分 ndc.z 的数值大小,任何非线性映射都会浪费它的分辨率。用了 reverse-Z 却用 D24 深度格式,等于白做。
4.5.5 对称视锥版本与 changeExtent 的漂移
// include/vsg/maths/transform.h:153
template<typename T>
constexpr t_mat4<T> perspective(T left, T right, T bottom, T top, T zNear, T zFar)
{
return t_mat4<T>(two * zNear / (right - left), zero, zero, zero,
zero, two * zNear / (bottom - top), zero, zero,
(right + left) / (right - left), (bottom + top) / (bottom - top),
zNear / (zFar - zNear), -one,
zero, zero, zNear * zFar / (zFar - zNear), zero);
}
同样是 reverse-Z + Y 翻转:(bottom + top)/(bottom - top) 里分母是 bottom - top(负的,因为 bottom < top),这等价于把 Y 翻了过来。
vsg::Perspective(include/vsg/app/ProjectionMatrix.h 第 52 行)的默认值:
// include/vsg/app/ProjectionMatrix.h:52
Perspective() :
fieldOfViewY(60.0),
aspectRatio(1.0),
nearDistance(1.0),
farDistance(10000.0)
fieldOfViewY 是垂直视角(Y 方向),水平视角由 aspectRatio 推出。transform() 里的调用是:
// include/vsg/app/ProjectionMatrix.h:79
dmat4 transform() const override { return perspective(radians(fieldOfViewY), aspectRatio, nearDistance, farDistance); }
注意 radians(...)——fieldOfViewY 存的是度,矩阵要的是弧度。这个转换只在 transform() 里做一次,所以每次求投影矩阵都多一次乘法。对 ProjectionMatrix::transform() 这种"每帧每视图调用一次"的函数来说,开销可忽略,但它意味着 fieldOfViewY = 60 和 fieldOfViewY = 60.0 * PI / 180 会得到差 57 倍的结果——赋值时不要顺手把角度转成弧度。
changeExtent 是一个容易被忽视的函数:
// include/vsg/app/ProjectionMatrix.h:81
void changeExtent(const VkExtent2D& prevExtent, const VkExtent2D& newExtent) override
{
double oldRatio = static_cast<double>(prevExtent.width) / static_cast<double>(prevExtent.height);
double newRatio = static_cast<double>(newExtent.width) / static_cast<double>(newExtent.height);
aspectRatio *= (newRatio / oldRatio);
}
窗口缩放时,aspectRatio 乘以"新旧宽高比之比"。这是相对更新,不是绝对设定:如果调用方传错 prevExtent(比如传了缩放后的尺寸),aspectRatio 会漂移,而且每次缩放都乘一次,误差复利累积。
正确用法是由 WindowResizeHandler(第三章 3.7.3 节)在收到 ConfigureEvent 时调用,prevExtent 是上一次的 VkExtent2D。如果你在自己的代码里手动调 changeExtent,务必保证 prevExtent 是当前的、newExtent 是目标的。
4.5.6 正交投影:同样的 reverse-Z
// include/vsg/maths/transform.h:166
template<typename T>
constexpr t_mat4<T> orthographic(T left, T right, T bottom, T top, T zNear, T zFar)
{
return t_mat4<T>(two / (right - left), zero, zero, zero,
zero, two / (bottom - top), zero, zero,
zero, zero, one / (zFar - zNear), zero,
-(right + left) / (right - left), -(bottom + top) / (bottom - top),
zFar / (zFar - zNear), one);
}
验证 translate 部分:z = -zNear 时 z' = -zNear/(zFar-zNear) + zFar/(zFar-zNear) = 1;z = -zFar 时 z' = (-zFar+zFar)/(zFar-zNear) = 0。和透视一样是 1→0,因为两个系数就是 one / (zFar - zNear) 与 zFar / (zFar - zNear)(include/vsg/maths/transform.h:174)。
注意 w' = 1(最后一列是 (0,0,1,1) 的第 3 行……按列主序看是 value[3] = (0,0,1,1),第 3 行第 3 列为 1),所以正交投影不做透视除法。
正交投影的一个细节:zFar/(zFar - zNear) 在 zNear = 0 时等于 1,zNear 极小时接近 1——这个数在 float 下会丢掉精度。当 zNear = 0.001、zFar = 10000 时,zFar/(zFar-zNear) = 1.0000001,float 表示它需要 24 位有效数字,实际只保留到 1.0000001 附近就饱和了。于是所有深度值被量化到极少的层。正交投影应该用尽量大的 zNear(比如负数,把相机放在包围盒外),不要为了"保险"设成 0.001。
4.6 lookAt 与 Z-up:为什么第一张图是歪的
4.6.1 lookAt 逐元素
// include/vsg/maths/transform.h:178
template<typename T>
constexpr t_mat4<T> lookAt(const t_vec3<T>& eye, const t_vec3<T>& center, const t_vec3<T>& up)
{
vec_type forward = normalize(center - eye);
vec_type up_normal = normalize(up);
vec_type side = normalize(cross(forward, up_normal));
vec_type u = normalize(cross(side, forward));
return t_mat4<T>(side[0], u[0], -forward[0], zero,
side[1], u[1], -forward[1], zero,
side[2], u[2], -forward[2], zero,
zero, zero, zero, one) *
vsg::translate(-eye.x, -eye.y, -eye.z);
}
先看构造出来的矩阵(列主序)。value[0] = (side[0], u[0], -forward[0], 0),所以写成行主序:
| side.x side.y side.z 0 |
| u.x u.y u.z 0 |
| -fwd.x -fwd.y -fwd.z 0 |
| 0 0 0 1 |
这个矩阵的三行分别是 side、u、-forward。 它是一个旋转矩阵,把世界坐标的三个基向量投影到相机的三个轴上:
- 世界点
p在相机 x 轴上的坐标 =side · p - 在相机 y 轴上的坐标 =
u · p - 在相机 z 轴上的坐标 =
-forward · p
因为相机看向 -Z,所以要取负。这正是标准 GL 视矩阵的形状。
然后右乘 translate(-eye):先平移(把眼睛移到原点),再旋转(把世界轴对齐到相机轴)。因为矩阵乘法是"右边的先作用",所以写出来是 rotate * translate——先平移后旋转 ✓。
4.6.2 默认值是 Z-up
include/vsg/app/ViewMatrix.h 第 56 行:
// include/vsg/app/ViewMatrix.h:56
LookAt() :
eye(0.0, 0.0, 0.0),
center(0.0, 1.0, 0.0),
up(0.0, 0.0, 1.0)
{
}
眼睛在原点,看向 +Y,头顶朝 +Z。 这是 Z-up、Y-forward 的坐标系——和 OSG 一致,和 Blender/CAD/GIS 一致,和游戏引擎不一致(Unity 是 Y-up、Z-forward;Unreal 是 Z-up 但 X-forward,即"前"是 X 而不是 Y)。
代入 lookAt 算一下这个默认相机看到的世界:
forward = normalize((0,1,0) - (0,0,0)) = (0,1,0)
up_normal = (0,0,1)
side = normalize(cross((0,1,0), (0,0,1))) = normalize((1*1-0*0, 0*0-0*1, 0*0-1*0)) = (1,0,0)
u = normalize(cross((1,0,0), (0,1,0))) = (0,0,1)
矩阵是:
| 1 0 0 0 |
| 0 0 1 0 |
| 0 -1 0 0 |
| 0 0 0 1 |
于是相机坐标 (x_c, y_c, z_c) = (x_w, z_w, -y_w):
- 世界的 +Z 变成相机的 +Y(屏幕上的"上")→ 世界是 Z-up ✓
- 世界的 +Y 变成相机的 -Z(相机的"前方")→ 世界 Y 是"前" ✓
- 世界的 +X 保持为相机的 +X(屏幕右)✓
这就是"第一张图是歪的"的根源。 如果你按 Y-up 的习惯往场景里放了一个"站在地面上"的模型(脚在 y=0,头在 y=2),默认相机看到的是从脚底往上看、模型躺倒——因为相机的"上"是世界的 Z,而模型的"上"是世界的 Y。模型在画面里被旋转了 90°。
两种修法:
// 修法 1:把相机改成 Y-up
camera->viewMatrix = vsg::LookAt::create(
vsg::dvec3(0.0, -10.0, 0.0), // eye
vsg::dvec3(0.0, 0.0, 0.0), // center
vsg::dvec3(0.0, 0.0, 1.0)); // up = Z
// 修法 2:把场景转成 Z-up(在读入模型时)
auto transform = vsg::MatrixTransform::create();
vsg::dmat4 m;
if (vsg::transform(vsg::CoordinateConvention::Y_UP, vsg::CoordinateConvention::Z_UP, m))
transform->matrix = m;
第 2 种用的是 transform.h 里的坐标约定转换,4.6.4 节展开。
4.6.3 up 与 forward 共线时:NaN
side = normalize(cross(forward, up))。如果 up 和 forward 平行(比如相机竖直向上看,forward = (0,0,1),up = (0,0,1)),叉积是零向量,normalize 除以 0 → side 全 NaN,整个视矩阵 NaN,画面全黑。
normalize 没有任何保护:
// include/vsg/maths/vec3.h:250
constexpr t_vec3<T> normalize(const t_vec3<T>& v)
{
return v / length(v);
}
length(0) = 0,v / 0 得到 (0/0, 0/0, 0/0) = NaN(不是 inf,因为分子也是 0)。
这是 Trackball 在极点附近会突然黑屏的原因:当用户把相机拖到正上方俯视时,up 和视线方向几乎共线,side 的模长趋近 0,方向由浮点噪声决定,画面开始绕视线轴乱转,最终在完全共线时崩溃。
工业级相机控件会在 |cross| < ε 时给 up 加一个微小的偏移(比如 up += vec3(1e-4, 0, 0)),或者切换到另一根轴。VSG 的 Trackball 用四元数累加旋转,不做 lookAt,所以避开了这个奇点——但如果你自己写 LookAt 并允许用户自由旋转,必须处理。
4.6.4 CoordinateConvention:三种约定的显式转换
// include/vsg/maths/transform.h:219
/// Hint on axis, using Collada conventions, all Right Hand
enum class CoordinateConvention
{
NO_PREFERENCE,
X_UP, // x up, y left/west, z out/south
Y_UP, // x right/east, y up, z out/south
Z_UP // x right/east, y forward/north, z up
};
transform(source, destination, matrix) 返回 bool——是否需要转换。如果 source == destination 或者任一是 NO_PREFERENCE,返回 false 且不改 matrix:
// src/vsg/maths/maths_transform.cpp:378
if (source == destination || source == CoordinateConvention::NO_PREFERENCE || destination == CoordinateConvention::NO_PREFERENCE) return false;
这个 bool 返回值很重要:它让调用方能区分"不需要转换"和"转换矩阵是单位阵"(后者不会发生,但语义上 false 明确表示"别改")。
X_UP → Y_UP 的矩阵是:
// src/vsg/maths/maths_transform.cpp:384
matrix.set(0.0, -1.0, 0.0, 0.0,
1.0, 0.0, 0.0, 0.0,
0.0, 0.0, 1.0, 0.0,
0.0, 0.0, 0.0, 1.0);
按列主序读:value[0] = (0,-1,0,0)、value[1] = (1,0,0,0)。写成行主序:
| 0 1 0 0 |
| -1 0 0 0 |
| 0 0 1 0 |
| 0 0 0 1 |
作用于 (1,0,0)(X-up 的"上"):结果是 (0,-1,0)。X 轴的上变成了 Y 轴的负方向——这与直觉上"X_UP 的 y 是 left/west、Y_UP 的 y 是 up"的注释读法相冲突,必须回到坐标轴定义才能判定谁错。
坐标轴定义写在注释里:X_UP: x up, y left/west, z out/south。Y_UP: x right/east, y up, z out/south。两者的 z 相同(都是 out/south)。所以转换只发生在 xy 平面内:X_UP 的 x(up)要变成 Y_UP 的 y(up),X_UP 的 y(left/west)要变成 Y_UP 的 -x(left = -right)。
于是:x_new = -y_old、y_new = x_old。矩阵应该是:
| 0 -1 0 |
| 1 0 0 |
而代码给的是 matrix.set(0.0, -1.0, 0.0, 0.0, 1.0, 0.0, ...) → 列 0 = (0,-1,0),行主序第 0 行 = (0, 1, 0)。所以 x_new = y_old、y_new = -x_old。
代入 (1,0,0)(X-up 的上):得到 (0,-1,0)。也就是说,原来的"上"变成了"下"。
这可能是一个符号错误,也可能是"右手系 + 翻转"的有意选择。判断依据是右手性:X_UP 的基是 (x=up, y=west, z=south),Y_UP 的基是 (x=east, y=up, z=south)。
X_UP:up × west = ?。地理坐标里east × north = up。设 east=(1,0,0)、north=(0,1,0)、up=(0,0,1)。那么 west=(-1,0,0)、south=(0,-1,0)。up × west = (0,0,1)×(-1,0,0) = (0·0-1·0, 1·(-1)-0·0, 0·0-0·(-1)) = (0,-1,0) = south✓ 右手。Y_UP:east × up = (1,0,0)×(0,0,1) = (0·1-0·0, 0·0-1·1, 0) = (0,-1,0) = south✓ 右手。- 转换矩阵
M必须满足M·up_X = up_Y,即M·(0,0,1) = (0,0,1)(z 不变 ✓),M·west_X = west_Y,即M·(-1,0,0) = (-1,0,0)→M·(1,0,0) = (1,0,0)。但代码给的M·(1,0,0) = (0,-1,0)。
所以代码里 X_UP → Y_UP 的矩阵会把 east 映射成 south,这与注释不符。 这是一个可疑的实现,但由于 CoordinateConvention 在实际代码里几乎没有调用点(VSG 的模型加载器大多直接用 Z_UP),这个 bug 大概率没被触发过。如果你的资产是 X-up 的 Collada 文件,不要相信这个函数,自己写转换矩阵。
这个例子说明一件事:坐标约定转换是"看起来简单、实际上极易搞错符号"的代码,而错的方式非常隐蔽——转换后的场景仍然"看起来像个人",只是朝向错了 90° 或镜像了。
4.7 plane、sphere、box:三种"无效值"的约定
这三个类型是视锥剔除、包围体计算、空间查询的基础。它们的共同设计是:用一个哨兵值表示"空",而不是用一个独立的 bool valid 成员。
4.7.1 t_plane:Hessian 形式 n·x = -p
// include/vsg/maths/plane.h:30
/** plane template class representing the plane in Hessian Normal Form : n.x = -p.*/
template<typename T>
struct t_plane
{
union
{
value_type value[4];
vec_type vec; // t_vec4
// Hessian Normal Form
struct { normal_type n; value_type p; };
};
四个 float 同时是 (nx, ny, nz, p) 和 vec4。vec 这个别名不是装饰:UBO 里的 vec4 需要 16 字节对齐,plane.vec 让"把平面塞进 UBO"变成一次 memcpy。
Hessian 形式的符号约定是 n·x = -p,不是 n·x = p。 所以点到平面的距离是:
// include/vsg/maths/plane.h:142
template<typename T>
constexpr T distance(const t_plane<T>& pl, const t_vec3<T>& v)
{
return dot(pl.n, v) + pl.p;
}
+ p 而不是 - p。对平面上的点,dot(n,v) = -p,和为 0 ✓。法线指向的空间是 distance > 0 的一侧。
默认构造是全零:
// include/vsg/maths/plane.h:52
constexpr t_plane() :
value{zero(), zero(), zero(), zero()} {}
bool valid() const { return n.x != zero() || n.y != zero() || n.z != zero(); }
n = (0,0,0) 时 valid() 返回 false。一个"无效平面"的距离函数返回 p(0),任何点都被判定为"在平面上"——这会让剔除逻辑把一切都判为可见(或都判为不可见,取决于符号),是个静默的失败模式。
从点和法线构造:
// include/vsg/maths/plane.h:69
constexpr t_plane(const normal_type& position, const normal_type& normal) :
value{normal.x, normal.y, normal.z, -dot(position, normal)} {}
注意参数顺序是 (position, normal),不是 (normal, position)。 两个都是 vec3,编译器不会报错,传反了会得到一个完全不同的平面(法线变成位置)。这是本章最阴险的一个坑——因为 t_plane(vec3, vec3) 的两种解释都"看起来合理"。
4.7.2 视锥剔除的正确写法
// include/vsg/maths/plane.h:155
/** return true if bounding sphere wholly or partially intersects with convex polytope defined by a list of planes with normals pointing inwards towards center of the polytope. */
template<class PlaneItr, typename T>
constexpr bool intersect(PlaneItr first, PlaneItr last, const t_sphere<T>& s)
{
auto negative_radius = -s.radius;
for (auto itr = first; itr != last; ++itr)
{
if (distance(*itr, s.center) < negative_radius) return false;
}
return true;
}
这是**球 vs 凸多面体(视锥)**的标准测试:
- 球心到某个平面的距离
< -radius,说明整个球都在这个平面外侧,剔除 ✓ - 否则继续检查下一个平面
- 全部通过 → 球与视锥相交(可能完全在内,也可能跨越边界)
negative_radius 提到循环外(include/vsg/maths/plane.h:159),是一个正确的小优化:6 个平面共享同一个 -radius。编译器本来也能做这个提升(s.radius 不变),但显式写出来更清楚。
这个测试有两个在文档里没写的假设:
- 平面法线指向视锥内部。 如果某个平面的法线朝外,测试会反过来——所有物体都被判为"在外侧"而全部剔除(画面全空),或者全部保留(剔除完全失效)。视锥平面的法线方向是
Frustum构造时定的,View::ViewDependentState里生成。 s.radius >= 0。 如果球是reset()过的(radius = -1),-radius = +1,测试变成"球心到平面距离 < 1 就剔除"——一个无效球会被当作"半径为 1 的球",几乎总是被剔除。这在ComputeBounds返回空包围球时会发生(场景里没有几何体)。
4.7.3 点在凸多面体内:inside
// include/vsg/maths/plane.h:174
template<class PlaneItr, typename T>
constexpr bool inside(PlaneItr first, PlaneItr last, const t_vec3<T>& v, T epsilon = 1e-10)
{
const auto negative_epsilon = -epsilon;
for (auto itr = first; itr != last; ++itr)
{
if (distance(*itr, v) < negative_epsilon) return false;
}
return true;
}
和 intersect 结构相同,但容差是 -epsilon 而不是 -radius。默认 1e-10:
- 对
double来说,1e-10是一个合理的绝对容差(地球尺度下 0.1 纳米)。 - 对
float来说,1e-10远小于 float 的分辨率。在坐标 1000 附近,float 的 ULP 是6e-5,1e-10的容差等于零——任何浮点误差都会让边界上的点被判定为"在外"。
所以 inside<float> 的默认 epsilon 是无意义的。 用 float 时必须显式传一个业务相关的值(比如 1e-4)。
4.7.4 t_sphere:radius = -1 是"无效"
// include/vsg/maths/sphere.h:57
constexpr t_sphere() :
value{zero(), zero(), zero(), minus_one()} {}
bool valid() const { return radius >= numbers<value_type>::zero(); }
默认球是 (0,0,0,-1)——半径 -1。valid() 检查 radius >= 0。
这和 box 的"空盒"约定不同(box 用 min > max 表示空)。两种约定各有道理:
- 球:半径必须非负,所以负数天然可以当哨兵。好处是"无效"的表示只有一个数。
- 盒:min/max 都可能合法,所以用"min > max"表示空。这允许
add()在空盒上正常工作(第一次add会把 min/max 都设成那个点)。
reset() 把球恢复成 (0,0,0,-1):
// include/vsg/maths/sphere.h:116
void reset()
{
center.set(zero(), zero(), zero());
radius = minus_one();
}
center 被清成原点,不是"垃圾值"。 这是有意的:一个无效球的中心仍然是合法的坐标,只有半径标记了无效。
4.7.5 t_box:空盒的 min/max 是"反的极值"
// include/vsg/maths/box.h:22
template<typename T>
struct t_box
{
vec_type min = vec_type(std::numeric_limits<value_type>::max(), ...);
vec_type max = vec_type(std::numeric_limits<value_type>::lowest(), ...);
bool valid() const { return min.x <= max.x; }
初始状态:min = (+FLT_MAX, +FLT_MAX, +FLT_MAX)、max = (-FLT_MAX, -FLT_MAX, -FLT_MAX)。于是 min.x > max.x,valid() 返回 false。
t_box::add() 之后自然变成有效——t_vec3 重载转手就把分量交给标量重载:
// include/vsg/maths/box.h:69
void add(value_type x, value_type y, value_type z)
{
if (x < min.x) min.x = x;
if (y < min.y) min.y = y;
if (z < min.z) min.z = z;
if (x > max.x) max.x = x;
if (y > max.y) max.y = y;
if (z > max.z) max.z = z;
}
第一次 add(p):p.x < +FLT_MAX ✓ 所以 min.x = p.x;p.x > -FLT_MAX ✓ 所以 max.x = p.x。空盒直接变成"只包含 p 的退化盒",不需要特判"这是第一次添加吗"。
这个技巧的前提是:+FLT_MAX 大于任何会被添加的坐标,-FLT_MAX 小于任何会被添加的坐标。如果坐标真的等于 FLT_MAX(比如从外部文件读入的极端值),盒会保持无效。 实践中不会遇到,但这是"用极值当哨兵"的固有代价。
valid() 只检查 min.x <= max.x,不检查 y 和 z。因为 add() 总是同时更新三个轴,所以三个轴的"有效性"是同步的——只要一个轴有效,另两个必然有效。
t_box::operator[] 通过 data() 访问:
// include/vsg/maths/box.h:47
value_type& operator[](std::size_t i) { return data()[i]; }
T* data() { return min.data(); }
box[0..2] 是 min,box[3..5] 是 max。这个展平顺序是序列化格式的一部分——box 在 vsg::Value<box> 里存成 6 个连续的 float,读写都依赖这个顺序。
4.8 inverse:三个变体与 NaN 的传播
transform.h 声明了六个函数:
// include/vsg/maths/transform.h:233
extern VSG_DECLSPEC mat3 inverse_3x3(const mat4& m); // 左上 3x3
extern VSG_DECLSPEC mat4 inverse_4x3(const mat4& m); // 仿射(快速)
extern VSG_DECLSPEC mat4 inverse_4x4(const mat4& m); // 通用
extern VSG_DECLSPEC mat4 inverse(const mat4& m); // 自动选择
(另有 double 版本,以及 determinant、decompose、computeFrustumBound。)
4.8.1 自动选择的判据
// src/vsg/maths/maths_transform.cpp:170
mat4 vsg::inverse(const mat4& m)
{
if (m[0][3] == 0.0f && m[1][3] == 0.0f && m[2][3] == 0.0f && m[3][3] == 1.0f)
{
return t_inverse_4x3(m);
}
else
{
return t_inverse_4x4(m);
}
}
判据是矩阵第 4 行是否等于 (0,0,0,1)(m[c][3] 是第 c 列第 3 行,四个合起来就是第 4 行)。这正是"仿射变换"的定义:没有投影分量,且 w 保持 1。命中时转手调用 t_inverse_4x3(src/vsg/maths/maths_transform.cpp:174)。
这是精确的浮点比较,没有 epsilon。 一个 m[3][3] = 0.9999999 的矩阵会走通用路径——正确的选择(虽然慢一点)。而一个 m[0][3] = 1e-30 的矩阵(数值上等价于 0)也会走通用路径。方向是安全的:模糊时选慢的、正确的那条路。
4.8.2 inverse_4x3 为什么快
t_inverse_4x3 只算左上 3x3 的行列式和伴随矩阵,然后用"仿射矩阵的逆"公式:
M = [ A t ] M⁻¹ = [ A⁻¹ -A⁻¹t ]
[ 0 1 ] [ 0 1 ]
左上 3x3 的逆需要:1 次 3x3 行列式(约 12 次乘加)+ 9 个代数余子式(各约 2 乘 1 加)+ 9 次乘 inv_det,共约 40 次浮点乘加 + 1 次除法。平移部分的逆 -A⁻¹t 是 9 次乘加。
t_inverse_4x4 需要算 6 个 2x2 余子式、4 个 3x3 余子式,再展开成 16 个元素,约 200 次乘加。
5 倍的差距。 而场景图里的矩阵 99% 是仿射的(MatrixTransform、lookAt、translate/rotate/scale 的组合),所以这个快速路径几乎总是命中。
4.8.3 行列式为 0 时返回 NaN 矩阵
// src/vsg/maths/maths_transform.cpp:135
value_type det = ...;
if (det == value_type(0.0)) return T(std::numeric_limits<value_type>::quiet_NaN());
返回一个"所有元素都是 NaN"的矩阵,而不是单位矩阵,也不抛异常——t_inverse_4x3 与 t_inverse_4x4 都是同一句 quiet_NaN 返回(src/vsg/maths/maths_transform.cpp:81)。
这个选择的后果:
NaN会传播:任何乘以它的向量都是 NaN,任何用它算出的包围盒都是 NaN。- 顶点着色器收到 NaN 的 MVP 矩阵 → 所有顶点被裁剪 → 物体消失。
- 没有任何日志、断言或错误码。
为什么不用单位矩阵?因为单位矩阵会"看起来正常"——物体会停在原点,你不会意识到矩阵求逆失败了。NaN 至少能让物体消失,是一种"响亮的失败"。
为什么不用异常?因为 VSG 的 Settings 里有 VSG_REPORT_FUNCTION 之类的开关,但数学函数是 extern 的普通函数,抛异常会让热路径带上异常表。而且 inverse 在遍历中被调用,抛异常会打断整个 accept 链(第三章 3.4.4 节说的栈纪律问题)。
实践中的处理:在调用 inverse 之前自己检查行列式:
if (std::abs(vsg::determinant(m)) < 1e-12) { /* 处理退化矩阵 */ }
auto inv = vsg::inverse(m);
determinant 也是一次约 40 次乘加的开销,但对"每帧只调几次"的场景无所谓。
4.8.4 inverse_3x3:给法线矩阵用的
// include/vsg/maths/transform.h:232
/// invert the top left 3x3 portion of a float 4x4 matrix.
extern VSG_DECLSPEC mat3 inverse_3x3(const mat4& m);
法线变换需要 (M⁻¹)ᵀ 的左上 3x3。先 inverse_3x3 再转置:
auto normalMatrix = vsg::transpose(vsg::inverse_3x3(modelMatrix));
为什么不直接 transpose(inverse(modelMatrix)) 然后取 3x3? 因为 inverse(mat4) 会算完整的 4x4(包括平移部分的逆),而法线只需要 3x3 的旋转/缩放部分。inverse_3x3 少算 7 个元素,约省 60%。
注意 inverse_3x3 返回 mat3(36 字节),而着色器里的 mat3 要 48 字节(std140/std430)。 上传时要么填进 mat4 的前 3 列(第 4 列留空),要么手动补齐每列的第 4 个分量。VSG 的 ShaderSet 生成的 UBO 布局里,mat3 一律按 mat4 处理——这是 4.1.4 节那个"CPU 紧凑、GPU 对齐"原则的又一个实例。
4.8.5 inverse 的精度:float 还是 double
inverse(const dmat4&) 和 inverse(const mat4&) 是两个独立实现,没有"从 double 降到 float"的桥接。如果你有一个 dmat4 的模型矩阵,一定要用 dmat4 的 inverse:
vsg::dmat4 m = ...;
auto inv = vsg::inverse(m); // ✓ double 精度
auto bad = vsg::mat4(inv); // 这里才降精度
反过来,把一个 mat4 转成 dmat4 再求逆不会提高精度(浮点误差已经在 float 里产生了),只会让计算慢一倍。精度是数据本身的属性,不是计算过程的属性。
这条在 4.11 节会展开:VSG 用 dmat4 存 MatrixTransform::matrix,正是为了让累加过程保持 double;如果中途有任何一步用 float,后面的 double 都是"带着误差的高精度"。
4.9 decompose:把一个矩阵拆回 TRS
// include/vsg/maths/transform.h:262
/// decompose float matrix into translation, rotation and scale components.
/// maps to TRS form: vsg::translate(translation) * vsg::rotate(rotation) * vsg::scale(scale);
/// assumes matrix has no skew or perspective components
extern VSG_DECLSPEC bool decompose(const mat4& m, vec3& translation, quat& rotation, vec3& scale);
注释里那一行 translate * rotate * scale 是全部约定的浓缩。因为矩阵乘法是"右边的先作用",所以这个顺序是:先缩放,再旋转,最后平移——标准的 TRS。
4.9.1 平移和缩放:直接从列里读
// src/vsg/maths/maths_transform.cpp:241
translation = m[3].xyz;
scale[0] = length(m[0].xyz);
scale[1] = length(m[1].xyz);
scale[2] = length(m[2].xyz);
if (scale[0] == 0.0 || scale[1] == 0.0 || scale[2] == 0.0) return false;
m[3] 是第 3 列,.xyz 是它的前三个分量——就是平移(4.1.1 节的字节账)。
t_decompose 里 scale[i] 取第 i 列的长度(src/vsg/maths/maths_transform.cpp:245)。这是"TRS 矩阵的列 = 旋转后的基向量 × 缩放"的直接推论:M = R·S 的第 i 列是 R 的第 i 列 × s_i,而 R 的列是单位向量,所以列长就是 s_i。
注意 length() 永远返回非负,所以这个分解无法表示负缩放。一个沿 x 镜像的矩阵(scale(-1,1,1))会被分解成 scale = (1,1,1) 加上一个"旋转"——但那个"旋转"的行列式是 -1,不是旋转。下一节会看到这会导致什么。
scale[i] == 0.0 的检查是精确比较。一个 1e-30 的缩放会通过检查,然后在 m[0].xyz / scale[0] 里产生 1e30 量级的数——后面的四元数提取会溢出成 inf。
4.9.2 提取旋转:两个分支
// src/vsg/maths/maths_transform.cpp:253
t_mat3<T> rm(m[0].xyz / scale[0],
m[1].xyz / scale[1],
m[2].xyz / scale[2]);
auto trace = rm[0][0] + rm[1][1] + rm[2][2]; // 对角线之和
if (trace > 0.0)
{
auto root = sqrt(trace + 1.0);
auto half_inv_root = 0.5 / root;
rotation.set(half_inv_root * (rm[1][2] - rm[2][1]),
half_inv_root * (rm[2][0] - rm[0][2]),
half_inv_root * (rm[0][1] - rm[1][0]),
0.5 * root);
}
rm 是"去掉缩放后的矩阵",纯旋转。trace = R₀₀ + R₁₁ + R₂₂。
分支 1(trace > 0):用 w 优先的公式:
w = 0.5·√(1 + trace)
x = (R₂₁ - R₁₂) / (4w)
y = (R₀₂ - R₂₀) / (4w)
z = (R₁₀ - R₀₁) / (4w)
代码里 rm[1][2] 是"第 1 列第 2 行"= R₂₁,rm[2][1] = R₁₂。所以 x = (R₂₁ - R₁₂)/(4w) ✓ 标准公式(列向量约定下的旋转矩阵)。
half_inv_root = 0.5/root = 0.5/(2w) = 1/(4w) ✓。
分支 2(trace <= 0):w 接近 0(旋转接近 180°),4w 会让 x/y/z 的公式数值不稳定,所以改用"最大对角元优先":
// src/vsg/maths/maths_transform.cpp:270
int i = 0;
if (rm[1][1] > rm[0][0]) i = 1;
if (rm[2][2] > rm[i][i]) i = 2;
const int next[3] = {1, 2, 0};
int j = next[i];
int k = next[j];
auto root = sqrt(rm[i][i] - rm[j][j] - rm[k][k] + 1.0);
auto half_inv_root = 0.5 / root;
rotation[i] = 0.5 * root;
rotation[j] = half_inv_root * (rm[i][j] + rm[j][i]);
rotation[k] = half_inv_root * (rm[i][k] + rm[k][i]);
rotation[3] = half_inv_root * (rm[j][k] - rm[k][j]);
next[] 是一个循环置换表:i=0 → j=1, k=2;i=1 → j=2, k=0;i=2 → j=0, k=1。这样"取最大对角元的轴、另外两个轴"就写成了一个数组,不需要三分支。
rotation[i] 的 i 是 0/1/2,对应 x/y/z;rotation[3] 是 w。这里用的是 operator[] 而不是具名成员,因为轴是运行期决定的。t_quat 的 operator[] 返回 value[i],而 value 是 union 的第一个成员——所以 rotation[0] 和 rotation.x 是同一个位置 ✓。
4.9.3 三个无法处理的输入
注释写得很诚实:
/// assumes matrix has no skew or perspective components
三种输入会静默出错:
| 输入 | 结果 | 检测手段 |
|---|---|---|
| 含 skew(非正交的旋转部分) | 返回一个"最接近的"旋转,skew 被丢弃 | 分解后重组,比较与原矩阵的差 |
含透视分量(m[3] != (0,0,0,1)) | 平移和缩放的读取全错 | 检查 m[0][3] == m[1][3] == m[2][3] == 0 |
| 负缩放(镜像) | scale 全正,rotation 不是旋转(det = -1) | determinant(m) < 0 |
第三种最危险,因为返回 true。一个 scale(-1, 1, 1) 的矩阵:
scale = (1, 1, 1)(长度永远是正的)rm的行列式 = -1trace = -1 + 1 + 1 = 1 > 0,走分支 1w = 0.5·√2 ≈ 0.707x = (R₂₁ - R₁₂)/(4w),对diag(-1,1,1)来说这两个都是 0 →x = 0- 同理
y = z = 0 - 得到
q = (0, 0, 0, 0.707)——模长 0.707,不是单位四元数
把这个 q 传给 rotate(q),得到的矩阵是 diag(1,1,1)·0.5(因为公式里的 1 - 2(...) 在非单位四元数下退化成 0.5)——一个整体缩小一半的单位阵。和原矩阵 diag(-1,1,1) 完全不同。
这就是 4.4 节反复强调的那条:rotate(q) 和 q*v 都假设 q 是单位四元数,而没有任何一个函数会帮你归一化或检查。
修复方式:在 decompose 里检查 determinant(m) < 0,把最小的缩放分量取负(或约定取 x 为负)。这也解释了为什么"负缩放"在场景图里应该尽量避免——它不是"TRS 的一种",而是"TRS + 镜像",需要额外的信息才能表示。
4.9.4 往返验证
正确的用法永远是"分解完立刻重组,比较差":
vsg::vec3 t, s;
vsg::quat r;
if (vsg::decompose(m, t, r, s))
{
auto rebuilt = vsg::translate(t) * vsg::rotate(r) * vsg::scale(s);
double err = 0.0;
for (int c = 0; c < 4; ++c)
for (int rr = 0; rr < 4; ++rr)
err += std::abs(rebuilt[c][rr] - m[c][rr]);
if (err > 1e-6) { /* 有 skew / 镜像 / 数值问题 */ }
}
这段代码的成本是 2 次矩阵乘(约 130 次乘加)+ 16 次减法。对"导入资产时跑一次"的场景完全值得,对每帧都跑的路径不值得。
4.10 computeFrustumBound:一个被 TODO 标注的失效函数
这一节是本章最值得读的部分,因为它展示了一个**"注释承认了问题、但从没修"**的真实案例,而且失效的幅度可以用数值算出来。
4.10.1 函数本体
// src/vsg/maths/maths_transform.cpp:309
template<typename T>
t_sphere<T> t_computeFrustumBound(const t_mat4<T>& m)
{
auto inv_m = inverse(m);
auto update_radius2 = [&](value_type& r, const vec_type& center, const vec_type& corner) -> void {
auto new_r = length2(corner - center);
if (new_r > r) r = new_r;
};
//
// TODO : depth range should probably be 0 to 1 for Vulkan, rather than -1 to 1 for OpenGL.
//
// compute a2, the radius squared of the near plane relative to the near planes mid point
vec_type near_center = inv_m * vec_type(0.0, 0.0, -1.0);
value_type a2 = length2(inv_m * vec_type(-1.0, -1.0, -1.0) - near_center);
...
// compute b2, the radius squared of the far plane relative to the far planes mid point
vec_type far_center = inv_m * vec_type(0.0, 0.0, 1.0);
它把 NDC 的近平面当成 z = -1、远平面当成 z = +1。 near_center 与 a2 就是这样算出来的(src/vsg/maths/maths_transform.cpp:327),这是 OpenGL 的约定。而 4.5 节刚证明 VSG 的投影矩阵是 近 → 1、远 → 0。
那行 TODO 就是在说这件事:"深度范围对 Vulkan 来说应该是 0 到 1,而不是 OpenGL 的 -1 到 1"。
4.10.2 算一下它到底错成什么样
取一个典型配置:fovy = 60°、aspect = 16/9、zNear = 0.1、zFar = 100。用 vsg::perspective 生成矩阵,求逆,把 8 个 NDC 角点变回视空间:
| NDC 点 | 视空间 z | 实际含义 |
|---|---|---|
(0,0,-1) | +0.1002 | 相机后方 10 cm(Vulkan 里根本没有这个平面) |
(0,0,+1) | -0.1 | 真正的近平面 |
(0,0,0) | -100 | 真正的远平面 |
函数以为的"近平面的中点"在相机背后,以为的"远平面"其实就是近平面。 于是它算出的球是:
center = (0, 0, 0.0002)
radius = 0.1546
一个半径 15 厘米、包住相机的球。
正确的球(近平面取 NDC z=+1、远平面取 z=0)是:
center = (0, 0, -100)
radius = 117.76
半径差了 762 倍。 如果拿这个球去做视锥剔除的粗筛("物体在不在这个球里,不在就整批跳过"),那么离开相机 15 厘米之外的一切都会被剔除——画面只剩贴脸的东西。
4.10.3 为什么没人发现:它没有调用点
$ grep -rn "computeFrustumBound" include src
include/vsg/maths/transform.h:278: extern VSG_DECLSPEC sphere computeFrustumBound(const mat4& m);
include/vsg/maths/transform.h:281: extern VSG_DECLSPEC dsphere computeFrustumBound(const dmat4& m);
src/vsg/maths/maths_transform.cpp:310: t_computeFrustumBound(...)
src/vsg/maths/maths_transform.cpp:366: sphere vsg::computeFrustumBound(const mat4& m)
src/vsg/maths/maths_transform.cpp:373: dsphere vsg::computeFrustumBound(const dmat4& m)
五个结果全是声明和定义,零调用点。 它是一个公开 API,但库内部从未使用。
那库内部用的是什么?src/vsg/state/ViewDependentState.cpp 第 572 行有一个同名但正确的 lambda:
// src/vsg/state/ViewDependentState.cpp:572
auto computeFrustumBounds = [&](double n, double f, const dmat4& clipToWorld) -> dbox {
dbox bounds;
bounds.add(clipToWorld * dvec3(-1.0, -1.0, n));
...
bounds.add(clipToWorld * dvec3(1.0, 1.0, f));
return bounds;
};
深度范围是参数 n / f,不是硬编码的 ±1。 调用点在 849 行和 860 行:
// src/vsg/state/ViewDependentState.cpp:843
dvec3 eye_near(0.0, 0.0, -n);
dvec3 eye_far(0.0, 0.0, -f);
auto clip_near = projectionMatrix * eye_near;
auto clip_far = projectionMatrix * eye_far;
updateCamera(clip_near.z, clip_far.z, clipToWorld);
它把眼睛空间的 (0,0,-n) 和 (0,0,-f) 用投影矩阵投影,取结果的 .z。 因为 operator*(mat4, vec3) 会做透视除法,所以 .z 就是 NDC 深度——对 reverse-Z 是 1 和 0,对 OpenGL 是 -1 和 +1,对 DX 是 0 和 1。无论什么约定,代码都自动正确。
这一段的写法值得抄:
// 通用:从投影矩阵反推近/远平面的 NDC 深度
auto ndcDepth = [](const dmat4& proj, double eyeZ) {
return (proj * dvec3(0.0, 0.0, eyeZ)).z;
};
double n = ndcDepth(proj, -zNear);
double f = ndcDepth(proj, -zFar);
这是"不要在几何代码里硬编码 NDC 范围"的教科书示范。 而 computeFrustumBound 恰恰是反面:它硬编码了 ±1,在 reverse-Z 下失效,然后用一行 TODO 把问题记录下来——六年没修。
4.10.4 这段代码里的数学是对的
公平地说,computeFrustumBound 的算法本身写得很漂亮(除了深度范围):
目标是:求一个球,包住一个"截锥"(两个平行的四边形面片 + 四条棱)。最优球的球心一定在中轴线上(对称性),所以问题降成一维:沿轴线找到一点 d,使得到"近平面四个角"和"远平面四个角"的最大距离最小。
解法:
near_center、far_center是两个面的中点,c = |far_center - near_center|是轴线长度。a2是近平面角点到near_center的最大距离平方(近平面"半径")。b2是远平面角点到far_center的最大距离平方。- 在轴线上参数化球心
P(d)(d是到near_center的距离)。到近角点的距离是√(a2 + d²),到远角点是√(b2 + (c-d)²)。 - 令两者相等:
a2 + d² = b2 + (c-d)²→d = (b2 + c² - a2)/(2c)。
后面三个分支处理边界:
if (d > c) { d = c; radius = sqrt(b2); } // 远平面"更宽",球心退到远平面
else if (d < 0) { d = 0; radius = sqrt(a2); } // 近平面更宽,球心退到近平面
else { radius = sqrt(a2 + d*d); } // 球心在两平面之间
这三行是必要的:d 落在 [0, c] 之外时,等距解在那个区间里不存在,最优解在端点。漏掉它们会出现"球心跑到截锥外面、半径反而是错的"。
update_radius2 那个 lambda 用 > 而不是 max,作用一样:遍历四个角点取最大。它初始化成"第一个角点"的距离,而不是 0——因为 0 会让"退化截锥"(两个面重合)得到半径 0。
4.10.5 正确的实现只要改两行
// 修正版:深度范围参数化
template<typename T>
t_sphere<T> t_computeFrustumBound(const t_mat4<T>& m, T n, T f)
{
auto inv_m = inverse(m);
vec_type near_center = inv_m * vec_type(0.0, 0.0, n);
vec_type far_center = inv_m * vec_type(0.0, 0.0, f);
...
}
调用处传 n = 1.0, f = 0.0(Vulkan reverse-Z)或 n = -1.0, f = 1.0(OpenGL)。更彻底的做法是像 ViewDependentState 那样,直接在内部用 projectionMatrix * eye_near 推出来,不信任调用者。
这个案例的教训不在数学,在工程:一个函数可以在数学上完全正确、在注释里承认自己有已知缺陷、在 API 上公开可用——然后因为没有人调用而一直错下去。TODO 不是待办事项,它是"这个函数不能信"的标记。
4.11 精度:float 的 24 位在一万米外意味着什么
4.11.1 三个位数的口径
| 类型 | 尾数位(含隐含位) | 相对精度 | 在 1.0 附近的 ULP |
|---|---|---|---|
float | 24 | ≈ 5.96e-8 | 1.19e-7 |
double | 53 | ≈ 1.11e-16 | 2.22e-16 |
long double(x86-64) | 64 | ≈ 5.4e-20 | 1.08e-19 |
long double(MSVC) | 53(= double) | 同 double | 同 double |
long double 在 Windows 上就是 double。 这正是 vsg::native_long_double_bits() 存在的理由(4.12.5 节)。
4.11.2 世界坐标的 ULP
float 的绝对精度 = 2^(e-23),其中 2^e ≤ |x| < 2^(e+1)。换成好记的说法:
| 坐标量级 | float 的 ULP | 直观感受 |
|---|---|---|
| 1 m | 1.2e-7 m | 0.12 微米 |
| 100 m | 7.6e-6 m | 7.6 微米 |
| 1 km | 6.1e-5 m | 0.06 毫米 |
| 10 km | 9.8e-4 m | 1 毫米 |
| 100 km | 7.8e-3 m | 8 毫米 |
| 1000 km | 0.0625 m | 6 厘米 |
| 10000 km | 1 m | 1 米 |
地球半径 6371 km。 在地心坐标系(ECEF)里存一个城市的位置,float 的精度是几十厘米——足以让建筑物的墙面抖动、让共面的两个三角形出现 z-fighting。
double 在同样的量级下是 1e-10 量级——float 精度的 200 万倍。这就是为什么 vsg::dmat4 和 vsg::dvec3 不是"可选的精度升级",而是大世界应用的必需品。
4.11.3 VSG 里的 double 从哪开始
Transform::transform(const dmat4&) 的签名就是答案:遍历时累加的是 dmat4,不是 mat4。
MatrixStack(include/vsg/vk/State.h 第 101 行)的成员:
// include/vsg/vk/State.h:99
using value_type = double;
std::stack<dmat4> matrixStack;
栈里全是 dmat4。 每个 MatrixTransform::push 做一次 matrixStack.top() * transform.matrix(64 次乘加,全在 double 里),所以 100 层嵌套变换之后,误差仍然在 1e-16 量级。
然后——整个流程只有一次降到 float:
// include/vsg/vk/State.h:158
inline void record(CommandBuffer& commandBuffer)
{
if (dirty)
{
...
// make sure matrix is a float matrix.
mat4 newmatrix(matrixStack.top());
vkCmdPushConstants(commandBuffer, pipeline, stageFlags, offset, sizeof(newmatrix), newmatrix.data());
dirty = false;
}
}
mat4 newmatrix(matrixStack.top()) 逐元素 static_cast<float>,然后64 字节直接推进 push constant。
这就是全流程精度损失的确切位置:vkCmdPushConstants 那 64 字节是 float,之前的每一步都是 double。
这个设计的效果是:矩阵链的误差不累积。100 层变换的 float 误差和 1 层一样(都是最后一次舍入的 1e-7),而不是 100 × 1e-7。
但它救不了顶点数据:
- 顶点缓冲里存的是
vec3(float)还是dvec3(double)?Vulkan 的顶点格式支持R64G64B64_SFLOAT,但几乎没有硬件为它优化(吞吐减半)。 - 如果顶点坐标本身就是
1e7量级的 float,那么在读进顶点着色器的那一刻,精度就只剩 ~1 米。之后再怎么用 double 的 MVP 都没用——误差已经在数据里。
4.11.4 CoordinateFrame:把大平移挪进双精度
// include/vsg/nodes/CoordinateFrame.h:21
/// CoordinateFrame provides support for astronomically large coordinates
class VSG_DECLSPEC CoordinateFrame : public Inherit<Transform, CoordinateFrame>
{
public:
std::string name;
dvec3 origin;
dquat rotation;
dmat4 transform(const dmat4& mv) const override;
// src/vsg/nodes/CoordinateFrame.cpp:63
dmat4 CoordinateFrame::transform(const dmat4& mv) const
{
return mv * translate(dvec3(origin)) * rotate(rotation);
}
用法是:顶点存"相对于 origin 的局部坐标"(小数值,float 精度足够),把巨大的绝对位置放在 origin(double)里。
这样一个"在 ECEF 里位于 (4.2e6, 1.3e6, 4.7e6) 的建筑",它的顶点坐标是几十米量级的小数,float 精度 1e-6 米。而 origin 在 double 里,精度 1e-10 米。
但最后一步仍然是 float。 translate(dvec3(origin)) 生成的 dmat4 在 record() 里被转成 mat4,4.7e6 变成一个 float——ULP 约 0.5 米。
所以 CoordinateFrame 解决的是"相对位置的精度"(物体内部的形状、物体之间的相对关系),没有解决"绝对位置的精度"(物体在世界里的位置)。后者需要相机相对渲染:
// 伪代码:camera-relative rendering
dvec3 cameraPos = viewMatrix->eye; // double
dmat4 cameraRelativeModel = translate(-cameraPos) * modelMatrix; // 先减掉相机位置
dmat4 mvp = projection * viewRotationOnly * cameraRelativeModel; // 不含平移的视矩阵
这样 float 矩阵里的数值都是"到相机的距离",几十米到几公里量级,ULP 是微米到毫米——精度回到了可用范围。
VSG 的 ViewMatrix::transform(const dvec3& offset = {}) 里那个 offset 参数就是为这件事准备的:
// include/vsg/app/ViewMatrix.h:40
virtual dmat4 transform(const dvec3& offset = {}) const = 0;
virtual dmat4 inverse(const dvec3& offset = {}) const
{
return vsg::inverse(transform(offset));
}
传 offset = cameraPos 可以让视矩阵"少减一次平移",配合预先平移的模型矩阵,就得到相机相对的 MVP。这是 VSG 里唯一一处为大世界精度留下显式钩子的地方,而它藏在默认参数里,文档里没提。
4.11.5 一个具体的精度账
场景:地球表面,ECEF 坐标,一个 100 米宽的建筑,用 float 顶点。
| 方案 | 顶点坐标的量级 | float ULP | 相邻顶点的最小可分辨距离 |
|---|---|---|---|
| 顶点存 ECEF 绝对坐标 | 6.4e6 | 0.5 m | 0.5 m → 100 米的建筑只有 200 个可分辨位置,墙面呈阶梯状 |
CoordinateFrame + 局部顶点 | 100 | 7.6e-6 m | 7.6 μm |
CoordinateFrame + 相机相对 MVP | 100 | 7.6e-6 m | 7.6 μm,且矩阵也无大数 |
第一行的"0.5 米"不是理论极限——它还会抖动:相邻两帧相机移动了几厘米,但顶点坐标的浮点舍入结果不变,于是物体在屏幕上"跳"0.5 米的格子。这种抖动比静态的精度损失更难忍,因为它让整个画面在动的时候"沙沙"响。
这就是为什么大世界引擎一定要做相机相对渲染,而 float 顶点缓冲 + double 矩阵只是必要条件,不是充分条件。
4.12 常量与工具:三个 bug 和一堆边界情况
maths/ 里除了几何类型,还有五个"工具"头文件:numbers.h、common.h、clamp.h、color.h、sample.h。它们加起来不到 350 行,但藏着三个真实的 bug(本章另外两个在 quat.h 和 maths_transform.cpp 里)。
4.12.1 numbers<T>:一个"没有常量"的常量表
// include/vsg/maths/numbers.h:19
template<typename T>
struct numbers
{
static constexpr T zero() { return static_cast<T>(0.0); }
static constexpr T half() { return static_cast<T>(0.5); }
static constexpr T one() { return static_cast<T>(1.0); }
static constexpr T two() { return static_cast<T>(2.0); }
static constexpr T three() { return static_cast<T>(3.0); }
static constexpr T minus_one() { return static_cast<T>(-1.0); }
static constexpr T epsilon() { return std::numeric_limits<T>::epsilon(); }
static constexpr T PI() { return static_cast<T>(3.14159265358979323846); }
static constexpr T degrees_to_radians() { return PI() / static_cast<T>(180.0); }
static constexpr T radians_to_degrees() { return static_cast<T>(180.0) / PI(); }
};
全部写成函数,不是 static constexpr 变量。 原因是 C++17 之前,类内的 static constexpr 成员如果被 ODR-use(比如取地址、绑定到 const 引用),需要类外定义——这在头文件里是灾难(多个翻译单元重复定义)。写成 static constexpr 函数就绕开了这个问题。
代价是每个调用点都是一次函数调用(在 -O0 下)。numbers<float>::zero() 在 mat4.h 里出现了几十次,构造一个矩阵在 -O0 下是几十次调用。这也是"数学库要开优化编译"的实际理由之一。
PI() 用 3.14159265358979323846(21 位有效数字)而不是 M_PI(M_PI 不是标准 C++,MSVC 需要 _USE_MATH_DEFINES)。对 float 来说,static_cast<float>(3.14159...) 得到 3.14159274f(最接近的 float),误差 8.7e-8——和 float 的 ULP 同量级,已经是最优。
4.12.2 smoothstep:返回值不是 0 和 1
// include/vsg/maths/common.h:42
/// Hermite interpolation between edge0 and edge1
template<typename T>
T smoothstep(T edge0, T edge1, T x)
{
if (x <= edge0)
return edge0; // ← GLSL 的 smoothstep 这里返回 0
else if (x >= edge1)
return edge1; // ← GLSL 这里返回 1
T r = (x - edge0) / (edge1 - edge0);
return edge0 + (r * r * (numbers<T>::three() - numbers<T>::two() * r)) * (edge1 - edge0);
}
GLSL 的 smoothstep(edge0, edge1, x) 在 x <= edge0 时返回 0,在 x >= edge1 时返回 1。 VSG 返回 edge0 和 edge1。
对 smoothstep(0, 1, x) 这个最常见的情况,两者完全等价(0 和 1 就是 0 和 1)。所以这个 bug 在 99% 的用法里不出现。
但对 smoothstep(2.0, 5.0, x):
| x | GLSL | VSG |
|---|---|---|
| 1.0 | 0.0 | 2.0 |
| 2.0 | 0.0 | 2.0 |
| 3.5 | 0.5 | 3.5 |
| 5.0 | 1.0 | 5.0 |
| 6.0 | 1.0 | 5.0 |
VSG 的版本是把 [edge0, edge1] 映射到 [edge0, edge1],也就是"在两端值之间做 Hermite 过渡"。这在数学上是合理的(可以叫 smoothstep_between),但它不是 GLSL 的 smoothstep,而名字完全一样。
后果:任何从着色器代码"翻译"到 CPU 侧的 smoothstep 都会得到差一个 edge0 + (edge1-edge0)·t 的结果。在雾效、抗锯齿宽度、软粒子淡出这些地方,参数通常就是 0..1,所以看不出来;一旦用了非 0..1 的边界(比如"距离 10 米到 100 米之间淡出"),结果就完全错了——不是"淡出曲线不对",而是"颜色值变成 10 到 100"。
第二个重载是对的(include/vsg/maths/common.h:56):
// include/vsg/maths/common.h:55
template<typename T>
T smoothstep(T r)
{
if (r <= 0) return 0;
else if (r >= 1) return 1;
return r * r * (numbers<T>::three() - numbers<T>::two() * r);
}
同名函数,一个符合 GLSL 语义,一个不符合。 单参数版本是"把 [0,1] 映射到 [0,1]",双参数版本是"把 [e0,e1] 映射到 [e0,e1]"——它们只在 e0=0, e1=1 时一致。
用 smoothstep 时优先用单参数版本,或者在调用处自己写 smoothstep(0, 1, t) 的等价形式。
4.12.3 repeat:整数边界返回 1.0,不是 0.0
clamp.h 实现了四个 VkSamplerAddressMode 的坐标变换,用于 CPU 侧的软件采样(sample.h):
// include/vsg/maths/clamp.h:28
/// clamp value between 0 and 1, implementing VK_SAMPLER_ADDRESS_MODE_REPEAT
template<typename T>
constexpr T repeat(T value)
{
T result = value - std::floor(value);
if (result != T(0.0)) return result;
return (value > T(0.0)) ? T(1.0) : T(0.0);
}
对一个非整数的 value,value - floor(value) 就是标准的小数部分 ✓。
对整数的 value(小数部分恰好为 0),代码返回 1.0(如果 value > 0)或 0.0。
这和 fract() 的行为不同:fract(3.0) = 0.0,而这里返回 1.0。Vulkan 规范里 VK_SAMPLER_ADDRESS_MODE_REPEAT 的坐标变换是 fract(coord),所以 coord = 3.0 应该映射到 0.0(第 0 个纹素的左边缘),而不是 1.0(右边缘)。
为什么这么写? 因为在双线性过滤里,coord = 1.0 会采到"最后一个纹素的右边界",而 coord = 0.0 采到"第一个纹素的左边界"。对一个闭合的重复纹理,这两个位置的纹素值相同(因为是同一个纹理的环绕点),所以视觉上没有差别。但在数值上,1.0 会让 sample() 里的 tc_index = coord * (width-1) 得到 width-1,而 0.0 得到 0——两者是不同的纹素。
对 CLAMP_TO_BORDER,clamp 返回 false 表示"越界",而 repeat、mirror_repeat 两个分支永远返回 true(include/vsg/maths/clamp.h:61):
// include/vsg/maths/clamp.h:60
case (VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER):
if (coord < 0.0f) return false;
if (coord > 1.0f) return false;
return true;
返回 false 时,sample() 直接返回边框颜色:
// include/vsg/maths/sample.h:27
if (image.size() == 0 || !clamp(sampler.addressModeU, coord.x) || !clamp(sampler.addressModeV, coord.y))
{
return color_cast<value_type>(sampler.borderColor);
}
!clamp(...) 的写法依赖"clamp 的返回值表示'坐标有效'"这个约定,但其他三个模式的 clamp 永远返回 true——所以 !clamp(...) 只在 CLAMP_TO_BORDER 越界时为真。这个"用返回值兼作有效性标志"的设计很紧凑,但读代码时必须知道另外三个模式不会返回 false。
4.12.4 color.h:opaque_white() 返回蓝色
// include/vsg/maths/color.h:73
template<typename T>
constexpr T opaque_white()
{
return color_cast<T>(0.0f, 0.0f, 1.0f, 1.0f);
}
color_cast<T>(r, g, b, a) 的参数顺序是 (红, 绿, 蓝, 透明)。所以 (0, 0, 1, 1) 是不透明的蓝色。
对比同文件里的其他三个:
transparent_black() → color_cast<T>(0.0f, 0.0f, 0.0f, 0.0f) // (0,0,0,0) ✓
opaque_black() → color_cast<T>(0.0f, 0.0f, 0.0f, 1.0f) // (0,0,0,1) ✓
transparent_white() → color_cast<T>(1.0f, 1.0f, 1.0f, 0.0f) // (1,1,1,0) ✓
opaque_white() → color_cast<T>(0.0f, 0.0f, 1.0f, 1.0f) // (0,0,1,1) ✗
三个对,一个错。 正确应该是 (1.0f, 1.0f, 1.0f, 1.0f)。
这个函数被 color_cast<T>(VkBorderColor) 使用:
// include/vsg/maths/color.h:90
case (VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE):
case (VK_BORDER_COLOR_INT_OPAQUE_WHITE):
return opaque_white<T>();
所以任何用 VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE 作为边框色的采样器,在 CPU 侧软采样(vsg::sample)时会得到蓝色边框,而 GPU 侧得到白色。 CPU 和 GPU 的结果不一致——这正是最难查的一类 bug(离线渲染和实时渲染的结果对不上)。
4.12.5 native_long_double_bits():22 行的一个平台探测
// src/vsg/maths/common.cpp:16
#include <float.h>
uint32_t vsg::native_long_double_bits()
{
if (LDBL_MANT_DIG == DBL_MANT_DIG) return 64;
return LDBL_MANT_DIG <= 64 ? 80 : 128;
}
三个平台,三种答案:
| 平台 | LDBL_MANT_DIG | 返回 | 实际存储 |
|---|---|---|---|
| MSVC (Windows) | 53(= double) | 64 | 8 字节 |
| x86-64 Linux / GCC | 64 | 80 | 16 字节(6 字节 padding) |
| ARM64 / AArch64 | 113 | 128 | 16 字节 |
这个函数的意义在序列化:vsg::Value<ldvec3> 写盘时要标出"这个平台上的 long double 是多少位",否则 16 字节的文件到 8 字节的平台上读不了。
sizeof(long double) 在 x86-64 上是 16,但有效位只有 80。 这意味着 ldmat4 在 x86-64 上占 16 × 16 = 256 字节,比 dmat4 的 128 字节多一倍,而精度只从 53 位提到 64 位(约 2000 倍)。这是一个性价比很低的类型——VSG 提供它主要是为了完整性(Value<ldvec3> 之类的模板要能实例化),实际使用几乎没有。
4.12.6 sample():把 GPU 的采样器搬到 CPU
sample.h 75 行实现了 VK_FILTER_NEAREST 和 VK_FILTER_LINEAR 两种过滤:
// include/vsg/maths/sample.h:32
vec2 tc_scale(static_cast<float>(image.width()) - 1.0f, static_cast<float>(image.height()) - 1.0f);
vec2 tc_index = coord * tc_scale;
(width - 1) 而不是 width:coord ∈ [0,1] 映射到 [0, width-1],即"纹素中心到纹素中心"的坐标。这是 CLAMP_TO_EDGE 的约定——coord = 1.0 对应最后一个纹素的中心,而不是右边界。
VK_FILTER_NEAREST 分支:
// include/vsg/maths/sample.h:37
uint32_t i = static_cast<uint32_t>(tc_index.x + 0.5f);
if (i >= image.width()) i = image.width() - 1;
+0.5 再截断 = 四舍五入 ✓。上界检查把 tc_index 夹回 image.width() - 1(include/vsg/maths/sample.h:39),防止 coord 略大于 1 时越界。
VK_FILTER_LINEAR 分支:
// include/vsg/maths/sample.h:46
uint32_t i = static_cast<uint32_t>(tc_index.x);
float r = tc_index.x - static_cast<float>(i);
if (i >= image.width() - 1) { i = image.width() - 1; r = 0.0f; }
auto v = image.at(i, j) * ((1.0f - r) * (1.0f - s));
if (r > 0.0) v += image.at(i + 1, j) * (r * (1.0f - s));
if (s > 0.0)
{
v += image.at(i, j + 1) * ((1.0f - r) * s);
if (r > 0.0) v += image.at(i + 1, j + 1) * (r * s);
}
两个细节:
- 边界处理是"贴边":
i到了最后一列就把r置 0,也就是只用最后一列的纹素。这等价于CLAMP_TO_EDGE✓。 if (r > 0.0)的条件跳过了不需要的采样:r = 0时i+1的权重是 0,跳过省一次内存访问。这对"大量采样在纹素中心"的情况(比如放大)很有效。
这个函数的真正用途是 vsg::Intersector 的纹理拾取(第 22 章)和离线渲染时的"GPU 结果验证"。把它的输出和 GPU 渲染的结果逐像素比,就能确认采样器的状态设置(addressMode、filter、borderColor)有没有传错——这是 4.12.4 节那个蓝色边框 bug 唯一的发现途径。
4.12.7 五个 bug 的共同点
| 函数 | 症状 | 什么时候暴露 |
|---|---|---|
smoothstep(e0, e1, x) | 返回 [e0,e1] 而不是 [0,1] | 边界不是 0..1 |
repeat(x) | 整数返回 1.0 而不是 0.0 | 坐标恰好落在纹素边界 |
opaque_white() | 返回蓝色 | 用 BORDER_COLOR_*_OPAQUE_WHITE + CPU 采样 |
inverse(quat) | 除以 |q| 而不是 |q|² | 四元数未归一化 |
computeFrustumBound | 深度范围错,球小 762 倍 | 真的调用它 |
五个 bug 有同一个形状:在"默认参数/常见输入"下完全正确,在"非默认输入"下完全错误,且不报错。 这正是数学库最需要的测试类型——不是"测试 mat4 * vec4 的结果",而是"测试边界值:零向量、未归一化的四元数、非 0..1 的边界、镜像矩阵、反向深度"。
4.13 与 glm、Eigen 的对照:约定差异表
如果你的项目里同时有 VSG 和另一个数学库,下面这张表里的差异会持续制造 bug。这张表是"混用时的对照手册"。
| 维度 | vsg:: | glm:: | Eigen:: |
|---|---|---|---|
| 矩阵存储 | 列主序(m[0] 是列) | 列主序(m[0] 是列) | 列主序(m(0,0) 是行 0 列 0,但内部列优先) |
| 索引语法 | m(col, row) | m[col][row] | m(row, col) |
| 向量乘法 | M * v(列向量) | M * v(列向量) | M * v(列向量) |
| 四元数顺序 | (x, y, z, w) | (w, x, y, z)(构造与内存都是) | 内存 (x,y,z,w),构造 (w,x,y,z) |
| 四元数乘法 | 反 Hamilton(a*b = 先 a 后 b) | 标准 Hamilton | 标准 Hamilton |
lookAt 结果 | 视矩阵(world→eye) | 视矩阵 | 无内置(用 LookAt 仿函数) |
| 投影矩阵 | reverse-Z、Y 翻转 | 标准 GL(-1..1、Y 不翻) | 无内置 |
| 对齐 | alignof(mat4) == 4 | SSE 下 alignas(16) | 视 EIGEN_MAX_ALIGN_BYTES |
| SIMD | 无(纯标量) | 有(SSE/AVX/NEON) | 有(大量手写 kernel) |
四个高危差异,按踩坑概率排序:
1. 四元数乘法顺序。 vsg::quat a, b; a * b 和 glm::quat 的 a * b 结果互为共轭顺序。把一段 glm 的四元数代码搬到 VSG,旋转方向会反。修法:VSG 侧写 b * a。
2. 四元数构造顺序。 glm::quat(w, x, y, z) vs vsg::quat(x, y, z, w)。四个 float 的构造调用参数顺序完全不同,而且类型相同,编译器不会报错。
glm::quat g(0.707f, 0.0f, 0.0f, 0.707f); // w=0.707, x=0, y=0, z=0.707:绕 z 转 90°
vsg::quat v(0.707f, 0.0f, 0.0f, 0.707f); // x=0.707, y=0, z=0, w=0.707:绕 x 转 90°
同一个字面量序列,绕不同的轴转。 这是本章最隐蔽的一个坑,因为两个结果都是合法的单位四元数。
3. 投影矩阵。 glm 的 glm::perspective 生成标准 GL 矩阵(近 → -1,远 → +1,Y 不翻)。直接喂给 VSG 的管线,结果是"上下颠倒 + 深度全废"。
4. 对齐。 std::vector<glm::mat4> 的元素是 16 字节对齐的,std::vector<vsg::mat4> 是 4 字节对齐。把后者的 data() 传给需要 16 字节对齐的 SIMD 代码会崩。反过来(glm 的向量传给 vkCmdUpdateBuffer)没问题。
4.13.1 如果重写,会改什么
假设今天从零设计这个数学库,在保持"零依赖 + 定长布局 + 可序列化"三个约束的前提下,五处值得改进:
| 现状 | 问题 | 改法 |
|---|---|---|
m(col, row) | 与数学记号相反 | 提供 m(row, col) 的具名别名 at(r, c),保留 operator() 兼容 |
| 四元数反 Hamilton | 与所有教材/引擎相反 | 改标准 Hamilton,把"父子链"的书写顺序交给调用方(q_child * q_parent) |
rotate(angle, axis) 不归一化 | 静默产生错切 | 内部做 normalize(axis)(多 3 次乘加 + 1 次开方,可接受) |
inverse(quat) 除以 |q| | 非单位四元数下错 | 除以 dot(q,q) |
smoothstep(e0,e1,x) 语义 | 与 GLSL 不同名同义 | 改名 smoothstep_between,或按 GLSL 语义返回 [0,1] |
| 无 SIMD | 批量运算慢 2–4 倍 | 不该加:见下 |
最后一行值得展开:为什么不加 SIMD。
VSG 的数学类型要被 vsg::Value<T> 持有、被 Data::compare 逐字节比较、被二进制序列化、被 Array<T> 紧凑排列。加 SIMD 意味着:
sizeof(vec3)从 12 变成 16(为了_mm_load_ps),Array<vec3>的内存涨 33%,缓存命中率下降。- 对齐要求从 4 变成 16,所有持有它的容器都要改分配器。
memcmp比较失效(padding 里有垃圾值)——第一章 1.5 节的is_equivalent就会误判。- 序列化格式改变(多出 4 字节 padding),破坏二进制兼容。
这四条里任何一条都比"快 2 倍"重要。 而"快 2 倍"在真实负载里往往兑现不了:遍历 10 万个 MatrixTransform 时,瓶颈是指针追逐和缓存未命中(第三章 3.10.2 节),不是 64 次乘加的算术吞吐。把一次 64 乘加从 64 周期压到 20 周期,在 200 周期的内存延迟面前是噪声。
真正从 SIMD 受益的是大批量同构运算:变换 100 万个顶点、批量算 8 个包围盒、矩阵数组的批量乘。这些场景在 VSG 里由 GPU 承担(顶点着色器),CPU 侧不需要。这是"用对整个系统的视角做数学库设计"和"用 microbenchmark 做设计"的区别。
4.14 三十个陷阱
按"踩到的概率 × 排查难度"排序,五列分别是陷阱名、触发条件、后果、源码坐标、规避动作。每条的完整推导都在 4.1–4.12 的对应小节,这张表只做索引与速查。
4.14.1 三十行五列速查表
| 陷阱 | 触发条件 | 后果 | 源码坐标 | 规避 |
|---|---|---|---|---|
行主序的 16 个 float 直接填进 t_mat4 | 从 .x、CAD、行主序文件读矩阵 | 得到转置矩阵,位置与旋转全错 | include/vsg/maths/mat4.h:56 | 逐元素 m(c,r) = src[r*4+c],或改用 v * M |
m[0] 当作第一行 | 手写 m[0][1] 取"第 0 行第 1 列" | 读到的是第 0 列第 1 行 | include/vsg/maths/mat4.h:82 | 记住 operator[] 返回 t_vec4,是列 |
| 变换链顺序写反 | 想要"先旋转再平移"却写 rotate * translate | 物体绕世界原点公转 | include/vsg/maths/transform.h:71 | 最右边的先作用 |
t_quat 乘法当成标准 Hamilton 积 | 从 Unity、glm 搬四元数代码 | 旋转方向整体反 | include/vsg/maths/quat.h:206 | VSG 侧改写成 b * a |
| 四元数构造参数顺序 | quat(0.707,0,0,0.707) 期望绕 Z | 实际绕 X 转 90° | include/vsg/maths/quat.h:51 | 用 set(angle, axis) 显式传轴 |
rotate(angle, axis) 传非单位轴 | 轴长 2,或来自未归一化的叉积 | 主轴项被放大,模型被拉伸 | include/vsg/maths/transform.h:52 | 先 normalize,或走 t_quat::set |
rotate(quat) 收到非单位四元数 | 插值或累加之后直接转矩阵 | 矩阵带上模长平方的缩放 | include/vsg/maths/transform.h:37 | 转矩阵前 normalize(q) |
inverse(quat) 用在非单位四元数 | 外部资产,或 q1 + q2 之后求逆 | 逆变换不是逆变换 | include/vsg/maths/quat.h:262 | 自己写 conjugate(v) / dot(v,v) |
set(from, to) 收到零向量 | 两条法线重合导致叉积为零 | 四元数全 NaN,物体消失 | include/vsg/maths/quat.h:117 | 先判 length2(from) 与 length2(to) |
acos(dot_pd / div) 未 clamp | 两个方向夹角小于 1e-4 弧度 | acos 返回 NaN | include/vsg/maths/quat.h:130 | 自己算角并 clamp 到 [-1,1] |
| 零轴被静默重置 | 轴向传入零向量 | 该次旋转被忽略,无日志 | include/vsg/maths/quat.h:100 | 调用前检查轴长并回退 |
epsilon() 当绝对容差用 | 轴长 1e-6,方向由浮点噪声决定 | 归一化放大噪声 | include/vsg/maths/quat.h:97 | 换成业务阈值如 1e-6 |
双参数 smoothstep 用在非 0..1 边界 | 距离 10 到 100 米之间淡出 | 输出落在 10..100 而不是 0..1 | include/vsg/maths/common.h:47 | 用单参数版本,或自己算 t*t*(3-2t) |
repeat() 落在整数坐标 | coord 恰为 1.0 或 2.0 | 返回 1.0 而不是 0.0 | include/vsg/maths/clamp.h:34 | 与 fract() 对齐时自己取小数 |
VK_BORDER_COLOR_*_OPAQUE_WHITE 走 CPU 采样 | 用 vsg::sample 做纹理拾取 | 边框变蓝,与 GPU 不一致 | include/vsg/maths/color.h:92 | 避开该枚举,或自行覆写白色 |
t_mat3、t_vec3 塞进 UBO | std140 或 std430 布局 | 后续字段全部错位 | include/vsg/maths/mat3.h:28 | 换 mat4、vec4 或 layout(scalar) |
| 奇异矩阵求逆 | 行列式恰好为 0 | 整矩阵 NaN,物体消失 | src/vsg/maths/maths_transform.cpp:45 | 先查 determinant 再求逆 |
| 仿射判据用精确比较 | m[3][3] 为 0.9999999 | 走 4x4 通用路径,慢 5 倍 | src/vsg/maths/maths_transform.cpp:172 | 接受变慢,或显式调 inverse_4x3 |
t_decompose 收到镜像矩阵 | scale(-1,1,1) | 返回 true,rotation 模长 0.707 | src/vsg/maths/maths_transform.cpp:262 | 先查 determinant(m) < 0 |
| 列长丢符号 | 任何负缩放 | scale 全正,镜像塞进 rotation | src/vsg/maths/maths_transform.cpp:244 | 分解后重组比对误差 |
| 近零缩放通过零检查 | scale = 1e-30 | 除法溢出成 inf | src/vsg/maths/maths_transform.cpp:250 | 用相对阈值判退化 |
无效 t_sphere 参与剔除 | reset() 之后 radius = -1 | 被当成半径 1 的球 | include/vsg/maths/sphere.h:58 | 先 valid(),无效即视为可见 |
空 t_box 参与运算 | 默认构造后直接读 min | 中心为 0、尺寸为 -inf | include/vsg/maths/box.h:28 | 先 valid(),或初始化成退化盒 |
t_plane 构造参数传反 | t_plane(p, n) 写成 t_plane(n, p) | 平面位置与朝向互换 | include/vsg/maths/plane.h:70 | 改用 t_plane(normal, -dot(pos, normal)) |
lookAt 的 up 与视线共线 | 相机垂直俯视 | side 全 NaN,画面黑 | include/vsg/maths/transform.h:188 | 限制俯仰,或扰动 up |
inside<float> 用默认 epsilon | 点恰好落在视锥边界 | 边界点被判为在外 | include/vsg/maths/plane.h:177 | 显式传 1e-4 |
| 用 GL 版透视矩阵 | 照抄 gluPerspective | 上下颠倒,深度全废 | include/vsg/maths/transform.h:144 | 只用 vsg::perspective |
changeExtent 传错 prevExtent | 手动调用时传了缩放后尺寸 | aspectRatio 漂移且复利累积 | include/vsg/app/ProjectionMatrix.h:86 | 只在 ConfigureEvent 里调用 |
t_vec3 * t_mat4 遇到 w = 0 | 用投影矩阵乘 t_vec3 | inf 或 NaN,无检查 | include/vsg/maths/mat4.h:229 | 用 vec4 并自己管 w |
computeFrustumBound 硬编码深度范围 | 任何 reverse-Z 管线 | 球心退回 near_center 附近,半径小 762 倍 | src/vsg/maths/maths_transform.cpp:326 | 别调用它,学 ViewDependentState 的写法 |
第 19、20、21 行是同一函数的三段:t_decompose 的镜像、符号、近零缩放会叠加,一个带微缩放的镜像矩阵可以同时踩中三条。
4.15 本章小结
4.15.1 九个数字
| 数字 | 含义 |
|---|---|
| 2888 | include/vsg/maths/ 的头文件总行数 |
| 456 | maths_transform.cpp 的行数(唯一的实现文件) |
| 36 | sizeof(mat3),与 std140 的 48 不一致 |
| 12 | sizeof(vec3),与 std430 的 16 不一致 |
| 4 | alignof(vec4),不是 16 |
| 0.0f | 深度清除值(reverse-Z 里的"无穷远") |
| 762× | computeFrustumBound 的半径误差倍数 |
| 24 / 53 | float / double 的尾数位数 |
| 0.5 m | float 在 ECEF 坐标(6.4e6)下的 ULP |
4.15.2 结论去哪儿了
十条结论已上移为 4.0.3 的答案骨架表,每行带真实坐标与"约定/缺陷/取舍"定性,此处不复述。小结只留一句提醒:这张表里只有第 6 行是主动设计的失败模式,其余十一行都是"实现照做了、调用方必须知道"的隐性契约。
4.15.3 三条阅读路线
路线 A(只想用):4.1(列主序)→ 4.2.1(乘法顺序)→ 4.5(投影与 reverse-Z)→ 4.6.2(Z-up)→ 4.14(三十个陷阱)。这五节覆盖 90% 的实际需求。
路线 B(想改库):4.4(四元数的五个约定)→ 4.8(inverse 的三个变体)→ 4.10(computeFrustumBound 的失效)→ 4.12(五个 bug)。重点是理解"哪些约定是被下游依赖的,改了就破坏兼容"。
路线 C(想借鉴架构):4.0(为什么 2888 行头文件 + 456 行 cpp)→ 4.13.1(为什么不该加 SIMD)→ 4.11.3(double 累加 + 一次 float 转换)。这三节合起来是"在性能、精度、ABI 三个约束下设计数学层的完整案例"。
4.16 可复现验证
本章所有数字都可以用下面几条命令或小程序复现(在仓库根目录执行)。
1. mat4 的布局
static_assert(sizeof(vsg::mat4) == 64);
static_assert(sizeof(vsg::dmat4) == 128);
static_assert(sizeof(vsg::mat3) == 36);
static_assert(sizeof(vsg::vec3) == 12);
static_assert(alignof(vsg::vec4) == 4); // 不是 16
static_assert(sizeof(vsg::quat) == 16);
static_assert(sizeof(vsg::plane) == 16);
static_assert(sizeof(vsg::sphere) == 16);
static_assert(sizeof(vsg::box) == 24); // 6 个 float
2. translate 的字节布局
auto m = vsg::translate(1.0f, 2.0f, 3.0f);
const float* p = m.data();
// p[12] == 1, p[13] == 2, p[14] == 3, p[15] == 1 → 平移在偏移 48
3. perspective 的 NDC 映射
auto P = vsg::perspective(vsg::radians(60.0f), 16.0f / 9.0f, 0.1f, 100.0f);
// 视空间近平面中心 (0,0,-0.1)
auto nearP = P * vsg::vec4(0.0f, 0.0f, -0.1f, 1.0f);
// nearP.z / nearP.w ≈ +1.0
auto farP = P * vsg::vec4(0.0f, 0.0f, -100.0f, 1.0f);
// farP.z / farP.w ≈ 0.0
auto upP = P * vsg::vec4(0.0f, 1.0f, -1.0f, 1.0f);
// upP.y < 0 → Y 被翻转
4. 四元数乘法顺序
auto q1 = vsg::quat(vsg::radians(90.0), vsg::vec3(1, 0, 0)); // 绕 X
auto q2 = vsg::quat(vsg::radians(90.0), vsg::vec3(0, 0, 1)); // 绕 Z
auto a = q1 * q2 * vsg::vec3(1, 0, 0); // 先 q1 后 q2 → (0, 1, 0)
auto b = vsg::rotate(q2) * vsg::rotate(q1) * vsg::dvec3(1, 0, 0); // 同一个结果
auto c = vsg::rotate(q1) * vsg::rotate(q2) * vsg::dvec3(1, 0, 0); // (0, 0, 1),不同
5. inverse(quat) 的非单位输入
vsg::quat q(0.2f, 0.3f, 0.4f, 0.5f); // |q| ≈ 0.735
auto inv = vsg::inverse(q);
auto prod = q * inv; // 不是单位四元数
auto correct = vsg::conjugate(q) / vsg::dot(q, q); // 正确版本
6. computeFrustumBound 的误差:下面 30 行脚本不需要 numpy,直接复现 4.10.2 的 r = 0.1546 与 r = 117.76:
import math
def inv4(m):
n=4; a=[row[:]+[1.0 if i==j else 0.0 for j in range(n)] for i,row in enumerate(m)]
for i in range(n):
p=max(range(i,n), key=lambda r: abs(a[r][i])); a[i],a[p]=a[p],a[i]
d=a[i][i]; a[i]=[v/d for v in a[i]]
for r in range(n):
if r!=i and a[r][i]!=0:
f=a[r][i]; a[r]=[x-f*y for x,y in zip(a[r],a[i])]
return [row[n:] for row in a]
def mv(m,v): return [sum(m[r][c]*v[c] for c in range(4)) for r in range(4)]
def corner(inv,x,y,z):
p=mv(inv,[x,y,z,1.0]); return [p[0]/p[3],p[1]/p[3],p[2]/p[3]]
def d2(a,b): return sum((x-y)**2 for x,y in zip(a,b))
fov,n,f=60.0,0.1,100.0; aspect=16/9
fv=1/math.tan(math.radians(fov)/2); r=1/(f-n)
M=[[fv/aspect,0,0,0],[0,-fv,0,0],[0,0,n*r,f*n*r],[0,0,-1,0]]
inv=inv4(M)
print('ndc(-1) ->', [round(v,4) for v in corner(inv,0,0,-1)]) # z = +0.1002
print('ndc(+1) ->', [round(v,4) for v in corner(inv,0,0, 1)]) # z = -0.1(真近平面)
7. 五个 bug 的 grep 定位
grep -n "return edge0" include/vsg/maths/common.h # smoothstep 的第一分支
grep -n "opaque_white" -A 4 include/vsg/maths/color.h # 返回 (0,0,1,1)
grep -n "1.0) / length(v)" include/vsg/maths/quat.h # inverse(quat)
grep -n "TODO : depth range" src/vsg/maths/maths_transform.cpp # computeFrustumBound
grep -rn "computeFrustumBound" include src | wc -l # 5,全是声明/定义,无调用
8. MatrixStack 的 double→float 转换点
grep -n "make sure matrix is a float matrix" -A 2 include/vsg/vk/State.h
预期输出:
// make sure matrix is a float matrix.
mat4 newmatrix(matrixStack.top());
vkCmdPushConstants(commandBuffer, pipeline, stageFlags, offset, sizeof(newmatrix), newmatrix.data());
9. 头文件与实现的行数账
wc -l include/vsg/maths/*.h | tail -1
wc -l src/vsg/maths/*.cpp | tail -1
输出 2888 total 与 478 total,就是 4.0 那组比例的两个分母。
10. constexpr 的覆盖范围
grep -c "constexpr" include/vsg/maths/transform.h include/vsg/maths/mat4.h
grep -n "constexpr t_mat4<T> translate" include/vsg/maths/transform.h
transform.h 的计数明显高于 mat4.h,因为构造类函数全是 constexpr、operator* 不是。transpose(const t_mat3<T>&) 同样在 constexpr 之列(include/vsg/maths/transform.h:117),所以常量表达式里可以转置。
11. 没有调用点的模板
grep -rn "difference(" src include
只有 src/vsg/maths/maths_transform.cpp:25 一处定义,零调用点——模板不实例化就不生成代码,编译器也不会报"未使用"。
12. 仓库里没有测试目录
ls tests
No such file or directory。4.17.6 的整段推论都建立在这一条命令上。
13. 三个哨兵值
grep -n "minus_one()" include/vsg/maths/sphere.h
grep -n "lowest()" include/vsg/maths/box.h
球用负半径、盒用反极值。numbers<T>::epsilon() 是这些判断里唯一的机器精度入口(include/vsg/maths/numbers.h:30),t_quat::set 的零轴分支也用它。
14. 两处最容易被改错的符号
grep -n "rhs\[3\] \* lhs\[0\]" include/vsg/maths/quat.h
grep -n "m\[0\]\[3\] == 0.0f" src/vsg/maths/maths_transform.cpp
第一条证明乘法交换了操作数,第二条证明仿射判据是精确比较。
4.17 批判性结论
4.17.1 判词:布局是可执行契约,正确性只是文档承诺
把 2,888 行头文件与 456 行实现摆在一起,第一印象是"几乎全部内联";读完 t_mat4 与 t_mat3 的成员声明,这个印象必须修正为:这是一套把内存布局当成硬契约的类型,而把数值正确性交给调用方守护。 前者由编译器强制——t_mat4 的 16 个参数在构造里按四组写进四个 t_vec4(include/vsg/maths/mat4.h:44),set() 沿用同一套 column 0..3 注释分组(include/vsg/maths/mat4.h:98),t_mat3::value 就是三个 t_vec3(include/vsg/maths/mat3.h:28)。后者没有任何强制手段:t_decompose 在遇到镜像矩阵时照样 return true(src/vsg/maths/maths_transform.cpp:287),t_quat 的 operator* 交换了操作数而不加注释(include/vsg/maths/quat.h:203)。
这个不对称不是疏忽,而是成本核算的结果。布局错了,序列化文件读不回来、Array<vec3> 的对齐假设崩掉、Vulkan 的 vkCmdPushConstants 拿到错位的 64 字节——错误立刻可见且无法绕过;数值错了,画面只是"看起来怪",可以推迟处理。库作者选择了"让错得离谱的地方不可能发生,让错得隐蔽的地方留给使用者"。评价这套库,必须按这个前提来评,否则会把一堆刻意的取舍当成 bug。
4.17.2 错误被编码成三种形态,而且三种都不带诊断
第一种是NaN 广播。t_inverse_3x3 在行列式为零时返回 quiet_NaN 填满的矩阵(src/vsg/maths/maths_transform.cpp:45),t_inverse_4x4 同样(src/vsg/maths/maths_transform.cpp:137)。这条路径的好处是"响亮":NaN 会穿过矩阵乘法、穿过包围盒计算,最终让顶点被裁剪,屏幕上物体消失。坏处是没有中间观测点——你只能在 inverse 返回之后自己断言 !std::isnan(inv[0][0]),而库不提供任何开关。
第二种是静默成功。前面算过 scale(-1,1,1) 的分解结果:scale 全正、rotation 模长 0.707、函数返回 true。同类还有 inside<float> 的默认 epsilon = 1e-10(include/vsg/maths/plane.h:177)、repeat() 对整数坐标返回 1.0(include/vsg/maths/clamp.h:34)。这类错误最难查,因为返回值、日志、断言全部"正常",只有几何结果偏了。
第三种是注释认账。t_computeFrustumBound 里那行 TODO(src/vsg/maths/maths_transform.cpp:322)承认深度范围应该是 0 到 1,但函数体照旧按 -1 到 1 取角点,于是近平面中点被算到相机背后。三种形态里,这一种最有欺骗性:读注释的人以为问题已被记录、会被修;读代码的人以为注释只是历史遗留。两种读者都不会去验证半径到底是 0.1546 还是 117.76。
从工程角度看,第三种最该被清理。一个公开 API 带着已知错误活了多年,比一个私有函数带错误更糟——它会被人调用,而调用者没有任何手段知道结果不可信。最省事的处理不是修 TODO(修它要改签名或加参数),而是在函数体开头加一行 static_assert 式的运行时断言、或在文档里写"此函数假定 OpenGL 深度范围"。现状是两者都没有:头文件里只有一句"compute the bounding sphere that encloses a frustum"。
4.17.3 反 Hamilton 的价格:用可移植性换一致性
t_quat 的乘法把 lhs 放在 rhs 之后(include/vsg/maths/quat.h:205),于是 a * b 表示"先 a 后 b",与矩阵的"先右后左"正好互补。这个设计的收益在本章 4.4.4 已经算清:场景图的父子链可以用同一种书写顺序表达,q_parent * q_child 与 M_parent * M_child 读起来一致,ComputeTransform::apply 这类累加代码不需要为两种类型写两套顺序(src/vsg/maths/maths_transform.cpp:434)。
价格有三项,前两项是显性的,第三项是隐性的。
显性价格之一是迁移成本。任何从论文、Unity、glm 搬来的四元数公式都要交换操作数;conjugate() 的语义没变(include/vsg/maths/quat.h:184),normalize() 也没变(include/vsg/maths/quat.h:247),唯独乘法反了,所以错误往往只出现在"两个旋转复合"的位置,单旋转的代码搬过来是对的。这种"部分正确"比全错更难定位。
显性价格之二是协作成本。一个人写 q1 * q2 时必须在脑子里跑一遍"这到底是先谁",而 dot()(include/vsg/maths/quat.h:254)之类不含顺序的函数又会让人放松警惕。团队里只要有一个人按 Hamilton 直觉写,代码仍然能编译、能跑、旋转方向错 100%。
隐性价格是它把一致性建立在单一实现上。四元数只负责存储与插值、矩阵负责累加(4.4.4 的分工),这条约定没有类型系统保护:rotate(q) * rotate(q2) 和 rotate(q * q2) 都能编译,前者按矩阵顺序、后者按四元数顺序,两者相等的前提是调用者记得把顺序反过来。一个 using Quat = t_quat<double> 的别名救不了这件事。
4.17.4 reverse-Z 是唯一一处全栈闭环的设计
这个库大部分约定是"局部正确、全局靠人";reverse-Z 是例外:投影矩阵、比较函数、清除值三处默认值互相对齐,任何一处被换成教科书值都会立刻黑屏。t_mat4 投影矩阵把远平面压到 0、近平面抬到 1(include/vsg/maths/transform.h:145),DepthStencilState 默认 VK_COMPARE_OP_GREATER(include/vsg/state/DepthStencilState.h:30),RenderGraph 的默认清除深度是 0.0f(include/vsg/app/RenderGraph.h:66),注释还点名要求 VK_FORMAT_D32_SFLOAT(include/vsg/maths/transform.h:136)。
闭环的价值可以用 4.5.4 的表量化:f/n = 10⁵ 时,1 km 处的深度分辨率从 0.6 m 提到 73 μm,5 km 处从 15 m 提到 0.23 mm。这不是"稍微好一点",而是把 z-fighting 从"必然发生"变成"配置错误才发生"。代价是整条链路不可混用:任何在 CPU 侧读深度做判断的代码(软粒子、SSAO 重建、拾取)都要记住"1 近 0 远",而库没有提供 isReverseZ() 之类的查询接口。
更值得注意的是它的可组合性很差。orthographic 复用了同一套深度约定(include/vsg/maths/transform.h:166),但它不做透视除法,w 恒为 1,于是"深度反转"在正交下只剩下线性重映射——收益从三四个数量级退化为零,副作用(读深度的代码要反着理解)却完整保留。这是约定复用的典型陷阱:一个为透视推导的规则被平移到正交,正确但无益。
4.17.5 精度的分层是真的,但它只覆盖一半问题
这套库的精度设计有一条清晰的主线:所有累加在 double 里做,只在出口处降到 float 一次。 MatrixStack 存 dmat4(include/vsg/vk/State.h:101),record() 里才构造 mat4 newmatrix(matrixStack.top()) 并推进 push constant(include/vsg/vk/State.h:173)。结果是一百层嵌套变换的误差仍然等于一次舍入,而不是一百次。
但这条主线只解决了"矩阵链"的精度。顶点数据本身如果是 1e7 量级的 float,读进着色器的那一刻精度就只剩一米,后面用多少位 double 都补不回来。CoordinateFrame 把大平移挪进 dvec3 origin(include/vsg/nodes/CoordinateFrame.h:28),配合"顶点存相对坐标"的约定,把相对精度拉回微米级;ViewMatrix::transform 的 offset 参数(include/vsg/app/ViewMatrix.h:40)给相机相对渲染留了一个钩子。两者合起来仍然不是完整方案——真正的绝对精度需要相机相对 MVP,而这件事库只给了一个默认参数,没有给示例、没有给断言、没有给"你忘了减相机位置"的提示。
所以"VSG 支持大世界"这句话要打折:它支持"大世界里的相对几何",不支持"直接把 ECEF 坐标塞进 float 顶点"。前者靠 CoordinateFrame,后者无论怎么配都会抖。
4.17.6 缺的那一层:没有任何测试
仓库里没有 tests/ 目录。这件事实解释了很多现象:difference() 这个模板在 maths_transform.cpp 里定义了却没有任何调用点(src/vsg/maths/maths_transform.cpp:25),它遍历 columns() 与 rows() 求逐元素绝对差之和(src/vsg/maths/maths_transform.cpp:28),形状完全是为"分解后重组、比较误差"这类测试准备的——测试没写,辅助函数留下来了。模板函数不实例化就没有代码生成,编译器连"未使用"都不会警告,于是它可以一直躺着。
同样的痕迹出现在别处:t_inverse_4x3 里六个中间量 A1223、A0223、A0123、A1213、A0213、A0113(src/vsg/maths/maths_transform.cpp:83)只用于 m30 一行(src/vsg/maths/maths_transform.cpp:101);t_computeFrustumBound 的 update_radius2 lambda(src/vsg/maths/maths_transform.cpp:316)承担了四个角点的取最大;ViewDependentState 里另写了一个 computeFrustumBoundsClipped(src/vsg/state/ViewDependentState.cpp:592)来处理近平面裁剪。这些都是"写的时候有人在验证"的代码,但验证过程没有沉淀成可执行的测试。
后果是可枚举的:本章列出的三十行陷阱里,至少有十二行可以用一个二十行的断言测试提前发现(镜像分解、零轴、非单位四元数求逆、奇异矩阵、inside 的 float 容差、repeat 的整数边界、opaque_white 的颜色、smoothstep 的边界)。这些测试不需要 GPU、不需要窗口、不需要 Vulkan,纯头文件即可编译。缺的不是能力,是习惯。
4.17.7 该不该用:三条判据
判据一:你的坐标系是不是 Z-up、右手、看 -Z。 如果不是,你会持续和 lookAt 的默认值、perspective 的 Y 翻转、CoordinateConvention 的符号问题打架。默认相机 center = (0,1,0)、up = (0,0,1)(include/vsg/app/ViewMatrix.h:56)不是可配置项,是硬编码的类默认值;LookAt 的三参构造会顺手归一化 up(include/vsg/app/ViewMatrix.h:49),但不会处理 up 与视线共线。
判据二:你能不能接受"约定错误只在边界输入下暴露"。 如果项目里存在外部资产(glTF、FBX、Collada)、用户可交互的相机、可缩放的模型,那么本章列的陷阱会逐个找上门。反过来,如果所有矩阵都由 translate/rotate/scale 生成、所有四元数都由 set(angle, axis) 生成,那么八成陷阱不会触发——因为默认构造、默认参数、单位输入全都落在"正确"的那一侧。
判据三:你需不需要 SIMD 吞吐。 这套库是纯标量的,批量变换一百万个顶点在 CPU 侧会很慢。但 4.13.1 算过账:真正的瓶颈在指针追逐与缓存未命中,把 64 次乘加压到 20 次在 200 周期的内存延迟面前是噪声。需要 SIMD 的场景(大批量同构运算)通常已经交给 GPU 了。
三条判据都过,这套库的性价比极高:零依赖、header-only、布局可预测、序列化现成、精度分层清晰。有一条不过,就要准备好为它写一层适配——不是改库,而是在库外面加断言、加检查、加坐标转换。
4.17.8 一句话总结
这套库把"能被 memcpy、能被序列化、能被 GPU 直接吃"放在第一位,用三十处隐性约定换来了零转换与零依赖;它的缺陷不是算错,而是假设调用者读过源码。
源码索引
| 结论 | 位置 | 关键符号 |
|---|---|---|
列主序存储、(列,行) 索引 | include/vsg/maths/mat4.h:80 | columns()、rows()、t_mat4 |
矩阵乘与 dot(c,r) | include/vsg/maths/mat4.h:172 | dot、t_mat4 |
M*v、v*M、M*plane、plane*M | include/vsg/maths/mat4.h:204 | t_vec4、operator* |
t_vec3 * t_mat4 的透视除法 | include/vsg/maths/mat4.h:238 | t_vec3、lhs |
t_mat3 的 36 字节布局 | include/vsg/maths/mat3.h:22 | t_mat3、column_type |
t_vec3 的 union 与 12 字节 | include/vsg/maths/vec3.h:39 | t_vec3、value |
normalize 无零检查 | include/vsg/maths/vec3.h:251 | normalize、length |
orthogonal 的嵌套分支 | include/vsg/maths/vec3.h:282 | orthogonal、fabs |
| 四元数布局与默认值 | include/vsg/maths/quat.h:43 | t_quat、value_type |
set(angle, axis) 的零轴重置 | include/vsg/maths/quat.h:96 | length、epsilon |
set(from, to) 的三个隐患 | include/vsg/maths/quat.h:119 | epsilon、orthogonal |
| 反 Hamilton 乘法 | include/vsg/maths/quat.h:207 | lhs、rhs、t_quat |
q * v 的三次叉积 | include/vsg/maths/quat.h:220 | cross、qvec |
inverse 除以 length | include/vsg/maths/quat.h:264 | conjugate、inverse_len |
mix 的最短路径 | include/vsg/maths/quat.h:271 | cosomega、t_quat |
perspective(reverse-Z + Y 翻) | include/vsg/maths/transform.h:146 | t_mat4、aspectRatio |
对称视锥 perspective | include/vsg/maths/transform.h:159 | zNear、right |
orthographic(reverse-Z) | include/vsg/maths/transform.h:172 | zFar、right |
lookAt | include/vsg/maths/transform.h:191 | side、forward |
computeBillboardMatrix | include/vsg/maths/transform.h:204 | centerEye、autoscaleDistance |
CoordinateConvention 与 transform() | include/vsg/maths/transform.h:230 | CoordinateConvention、matrix |
inverse_3x3、inverse_4x3、inverse_4x4 声明 | include/vsg/maths/transform.h:251 | inverse、VSG_DECLSPEC |
decompose 声明与 TRS 注释 | include/vsg/maths/transform.h:265 | decompose、translation |
inverse 的自动选择 | src/vsg/maths/maths_transform.cpp:174 | t_inverse_4x3、t_inverse_4x4 |
| 3x3 逆(法线矩阵) | src/vsg/maths/maths_transform.cpp:49 | inv_det、m00 |
| 4x3 快速逆 | src/vsg/maths/maths_transform.cpp:105 | m30、value_type |
| 通用 4x4 逆 | src/vsg/maths/maths_transform.cpp:141 | inv_det、A2323 |
determinant | src/vsg/maths/maths_transform.cpp:220 | det、A2323 |
decompose 的两个分支 | src/vsg/maths/maths_transform.cpp:257 | trace、rm |
computeFrustumBound 的球心分支 | src/vsg/maths/maths_transform.cpp:346 | beyond、radius |
| 坐标约定转换矩阵 | src/vsg/maths/maths_transform.cpp:391 | matrix、CoordinateConvention |
| 正确的 frustum 计算(参数化深度) | src/vsg/state/ViewDependentState.cpp:585 | bounds、clipToWorld |
| 从投影矩阵推 NDC 深度 | src/vsg/state/ViewDependentState.cpp:846 | clip_near、projectionMatrix |
Hessian 平面与 distance | include/vsg/maths/plane.h:47 | normal_type、t_plane |
intersect(planes, sphere) | include/vsg/maths/plane.h:162 | negative_radius、t_sphere |
inside(planes, v, eps) | include/vsg/maths/plane.h:180 | negative_epsilon、t_vec3 |
t_sphere 的 radius=-1 哨兵 | include/vsg/maths/sphere.h:109 | t_vec3、radius |
t_box 的反极值空盒 | include/vsg/maths/box.h:29 | vec_type、lowest |
numbers<T> | include/vsg/maths/numbers.h:22 | numbers、zero |
smoothstep 返回 edge 值 | include/vsg/maths/common.h:51 | edge0、edge1 |
clamp、repeat、mirror_repeat | include/vsg/maths/clamp.h:43 | mirror_repeat、v_fract |
opaque_white 返回蓝 | include/vsg/maths/color.h:74 | opaque_white、color_cast |
sample() 的软件采样 | include/vsg/maths/sample.h:48 | tc_index、tc_scale |
native_long_double_bits | src/vsg/maths/common.cpp:21 | LDBL_MANT_DIG |
MatrixStack(dmat4 → float) | include/vsg/vk/State.h:160 | dirty、matrixStack |
LookAt 的 Z-up 默认值 | include/vsg/app/ViewMatrix.h:57 | center、dvec3 |
Perspective 的默认值与 changeExtent | include/vsg/app/ProjectionMatrix.h:53 | fieldOfViewY、Perspective |
CoordinateFrame 的 origin/rotation | src/vsg/nodes/CoordinateFrame.cpp:65 | translate、rotation |
depthCompareOp 的默认值 | include/vsg/state/DepthStencilState.h:31 | depthBoundsTestEnable、depthTestEnable |
| 深度清除值 0.0 | include/vsg/app/RenderGraph.h:63 | ClearValues、clearValues |
下一章预告
第五章回到 CPU 数据与 GPU 资源的接缝:Data/Array 的内存布局已经在第二章讲过,这一章讲它们怎么变成 VkBuffer 和 VkImage。
具体要回答的问题:
BufferInfo的九个字段(data、offset、range、stride、usage、dataVariance、shared……)分别在什么阶段被谁读?为什么stride不能从Data推出来?ImageInfo的VkImageCreateInfo是用户填的,而Data里的像素数据是现成的——两者不匹配时谁负责报错?(答案:没人,设备会丢给验证层)MemoryBufferPools的三条上传路径(直接映射 / staging / 批量预留)各自适合什么dataVariance?为什么STATIC_DATA_UNREF_AFTER_TRANSFER能省一半内存?TransferTask如何把 N 个小上传合并成 1 次vkCmdCopyBuffer?合并的阈值是多少字节?- 一个 4K 纹理从
read()到出现在VkImage里,中间经过几次内存拷贝?第二章算过 33.2 MB × 3 = 99.6 MB 的峰值,这一章会把那三次拷贝逐一标出来。
这一章会大量引用第二章的 MemorySlots 和第三章的 CompileTraversal,建议先读完那两章。