《VulkanSceneGraph 1.1.16 源码深度解析》第四章 数学库:列主序、Z-up 与精度的三重代价

0 阅读1小时+

《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

这是每个读源码的人都会问的问题。三个理由,按权重排序:

  1. constexpr 的覆盖度。 2018 年 VSG 立项时,glm 的 constexpr 支持是残缺的(glm 0.9.9 只有部分函数标了 GLM_CONSTEXPR,且依赖 GLM_FORCE_CXX14 之类的宏)。VSG 需要 constexpr 来支撑 4.0 节说的常量折叠。
  2. 类型必须能被 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 字节。
  3. 坐标系约定。 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 或图像)、缺陷(在特定输入下错且不报错)、取舍(换来了别的东西)。后面每一节都是对其中某一行的展开,读完全章可以回来核对这张表。

#结论证据坐标性质
1t_mat4::value 是 t_vec4 的数组,m[0] 是第一列include/vsg/maths/mat4.h:30约定:与 GLSL 一致,可直接 memcpy 进 UBO
2t_mat4::operator() 先列后行,与数学记号 A(i,j) 相反include/vsg/maths/mat4.h:86约定:所有调用点都要按 (c, r) 读
3dot(lhs, rhs, c, r) 用 lhs[k][r] * rhs[c][k] 累加,就是标准 lhs × rhsinclude/vsg/maths/mat4.h:163约定:A * B 先作用 B
4t_quat::operator* 把 lhs 与 rhs 对调,a * b 算的是 rhs ⊗ lhsinclude/vsg/maths/quat.h:205约定:反 Hamilton,OSG 遗产
5t_quat 的 inverse 除 length(v) 而不是 dot(v,v)include/vsg/maths/quat.h:263缺陷:仅非单位四元数暴露
6inverse 对奇异矩阵返回 quiet_NaN 填充的整矩阵src/vsg/maths/maths_transform.cpp:137取舍:响亮失败,但零诊断
7perspective 的 -f 与 1 → 0 深度范围是一对,不能拆include/vsg/maths/transform.h:147约定:与 Vulkan NDC + GREATER 配套
8t_plane 是 n·x = -p,distance 用 dot(pl.n, v) + pl.pinclude/vsg/maths/plane.h:145约定:法线正向侧为正距离
9t_decompose 只在 scale[i] == 0.0 时返回 false,其余输入一律 truesrc/vsg/maths/maths_transform.cpp:250缺陷:负缩放与 skew 都不设防
10t_computeFrustumBound 的球心由 (b2 + c2 - a2)/(2c) 在 near_center、far_center 之间插值src/vsg/maths/maths_transform.cpp:342取舍:数学最优,但深度范围硬编码
11opaque_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 在内存里存的是转置的:

偏移元素数学含义
01m(0,0)
40m(0,1)
80m(0,2)
120m(0,3)
160m(1,0)
201m(1,1)
240m(1,2)
280m(1,3)
320m(2,0)
360m(2,1)
401m(2,2)
440m(2,3)
481m(3,0) ← 平移 x
522m(3,1) ← 平移 y
563m(3,2) ← 平移 z
601m(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"假设:

  1. sizeof(t_vec4<float>) == 16
  2. alignof(t_vec4<float>) == 4(不是 16!因为 t_vec4 里没有 alignas,也没有 SIMD 类型)
  3. 数组 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 字节。

正确的做法有三种:

  1. 着色器里用 float data[],CPU 侧也传 float 数组(最省心)。
  2. 用 vec4 存 xyz + padding(浪费 25%,但对齐天然正确)。
  3. 用 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() 之后是单位四元数。

它只在两种情况下错:

  1. 从外部数据读入未归一化的四元数(比如从 glTF/FBX 读进来,文件里写的是 (0.1, 0.2, 0.3, 0.9),模长 0.98)。
  2. 对四元数做了线性插值/累加(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,远 → 0include/vsg/maths/transform.h 第 140 行
深度比较VK_COMPARE_OP_GREATERinclude/vsg/state/DepthStencilState.h 第 30 行
深度清除值0.0finclude/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 m0.900006.0e-80.6 μm0.099997.5e-90.075 μm
100 m0.999006.0e-86 mm9.9e-41.2e-1012 μm
1000 m0.999906.0e-80.60 m9.0e-57.3e-1273 μm
5000 m0.999986.0e-815 m1.0e-59.1e-130.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 不变),但显式写出来更清楚。

这个测试有两个在文档里没写的假设:

  1. 平面法线指向视锥内部。 如果某个平面的法线朝外,测试会反过来——所有物体都被判为"在外侧"而全部剔除(画面全空),或者全部保留(剔除完全失效)。视锥平面的法线方向是 Frustum 构造时定的,View::ViewDependentState 里生成。
  2. 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 的行列式 = -1
  • trace = -1 + 1 + 1 = 1 > 0,走分支 1
  • w = 0.5·√2 ≈ 0.707
  • x = (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,使得到"近平面四个角"和"远平面四个角"的最大距离最小。

解法:

  1. near_center、far_center 是两个面的中点,c = |far_center - near_center| 是轴线长度。
  2. a2 是近平面角点到 near_center 的最大距离平方(近平面"半径")。
  3. b2 是远平面角点到 far_center 的最大距离平方。
  4. 在轴线上参数化球心 P(d)(d 是到 near_center 的距离)。到近角点的距离是 √(a2 + d²),到远角点是 √(b2 + (c-d)²)。
  5. 令两者相等: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
float24≈ 5.96e-81.19e-7
double53≈ 1.11e-162.22e-16
long double(x86-64)64≈ 5.4e-201.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 m1.2e-7 m0.12 微米
100 m7.6e-6 m7.6 微米
1 km6.1e-5 m0.06 毫米
10 km9.8e-4 m1 毫米
100 km7.8e-3 m8 毫米
1000 km0.0625 m6 厘米
10000 km1 m1 米

地球半径 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.4e60.5 m0.5 m → 100 米的建筑只有 200 个可分辨位置,墙面呈阶梯状
CoordinateFrame + 局部顶点1007.6e-6 m7.6 μm
CoordinateFrame + 相机相对 MVP1007.6e-6 m7.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):

xGLSLVSG
1.00.02.0
2.00.02.0
3.50.53.5
5.01.05.0
6.01.05.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)648 字节
x86-64 Linux / GCC648016 字节(6 字节 padding)
ARM64 / AArch6411312816 字节

这个函数的意义在序列化: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);
}

两个细节:

  1. 边界处理是"贴边":i 到了最后一列就把 r 置 0,也就是只用最后一列的纹素。这等价于 CLAMP_TO_EDGE ✓。
  2. 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) == 4SSE 下 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 意味着:

  1. sizeof(vec3) 从 12 变成 16(为了 _mm_load_ps),Array<vec3> 的内存涨 33%,缓存命中率下降。
  2. 对齐要求从 4 变成 16,所有持有它的容器都要改分配器。
  3. memcmp 比较失效(padding 里有垃圾值)——第一章 1.5 节的 is_equivalent 就会误判。
  4. 序列化格式改变(多出 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:206VSG 侧改写成 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 返回 NaNinclude/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..1include/vsg/maths/common.h:47用单参数版本,或自己算 t*t*(3-2t)
repeat() 落在整数坐标coord 恰为 1.0 或 2.0返回 1.0 而不是 0.0include/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 塞进 UBOstd140 或 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.707src/vsg/maths/maths_transform.cpp:262先查 determinant(m) < 0
列长丢符号任何负缩放scale 全正,镜像塞进 rotationsrc/vsg/maths/maths_transform.cpp:244分解后重组比对误差
近零缩放通过零检查scale = 1e-30除法溢出成 infsrc/vsg/maths/maths_transform.cpp:250用相对阈值判退化
无效 t_sphere 参与剔除reset() 之后 radius = -1被当成半径 1 的球include/vsg/maths/sphere.h:58先 valid(),无效即视为可见
空 t_box 参与运算默认构造后直接读 min中心为 0、尺寸为 -infinclude/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_vec3inf 或 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 九个数字

数字含义
2888include/vsg/maths/ 的头文件总行数
456maths_transform.cpp 的行数(唯一的实现文件)
36sizeof(mat3),与 std140 的 48 不一致
12sizeof(vec3),与 std430 的 16 不一致
4alignof(vec4),不是 16
0.0f深度清除值(reverse-Z 里的"无穷远")
762×computeFrustumBound 的半径误差倍数
24 / 53float / double 的尾数位数
0.5 mfloat 在 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:80columns()、rows()、t_mat4
矩阵乘与 dot(c,r)include/vsg/maths/mat4.h:172dot、t_mat4
M*v、v*M、M*plane、plane*Minclude/vsg/maths/mat4.h:204t_vec4、operator*
t_vec3 * t_mat4 的透视除法include/vsg/maths/mat4.h:238t_vec3、lhs
t_mat3 的 36 字节布局include/vsg/maths/mat3.h:22t_mat3、column_type
t_vec3 的 union 与 12 字节include/vsg/maths/vec3.h:39t_vec3、value
normalize 无零检查include/vsg/maths/vec3.h:251normalize、length
orthogonal 的嵌套分支include/vsg/maths/vec3.h:282orthogonal、fabs
四元数布局与默认值include/vsg/maths/quat.h:43t_quat、value_type
set(angle, axis) 的零轴重置include/vsg/maths/quat.h:96length、epsilon
set(from, to) 的三个隐患include/vsg/maths/quat.h:119epsilon、orthogonal
反 Hamilton 乘法include/vsg/maths/quat.h:207lhs、rhs、t_quat
q * v 的三次叉积include/vsg/maths/quat.h:220cross、qvec
inverse 除以 lengthinclude/vsg/maths/quat.h:264conjugate、inverse_len
mix 的最短路径include/vsg/maths/quat.h:271cosomega、t_quat
perspective(reverse-Z + Y 翻)include/vsg/maths/transform.h:146t_mat4、aspectRatio
对称视锥 perspectiveinclude/vsg/maths/transform.h:159zNear、right
orthographic(reverse-Z)include/vsg/maths/transform.h:172zFar、right
lookAtinclude/vsg/maths/transform.h:191side、forward
computeBillboardMatrixinclude/vsg/maths/transform.h:204centerEye、autoscaleDistance
CoordinateConvention 与 transform()include/vsg/maths/transform.h:230CoordinateConvention、matrix
inverse_3x3、inverse_4x3、inverse_4x4 声明include/vsg/maths/transform.h:251inverse、VSG_DECLSPEC
decompose 声明与 TRS 注释include/vsg/maths/transform.h:265decompose、translation
inverse 的自动选择src/vsg/maths/maths_transform.cpp:174t_inverse_4x3、t_inverse_4x4
3x3 逆(法线矩阵)src/vsg/maths/maths_transform.cpp:49inv_det、m00
4x3 快速逆src/vsg/maths/maths_transform.cpp:105m30、value_type
通用 4x4 逆src/vsg/maths/maths_transform.cpp:141inv_det、A2323
determinantsrc/vsg/maths/maths_transform.cpp:220det、A2323
decompose 的两个分支src/vsg/maths/maths_transform.cpp:257trace、rm
computeFrustumBound 的球心分支src/vsg/maths/maths_transform.cpp:346beyond、radius
坐标约定转换矩阵src/vsg/maths/maths_transform.cpp:391matrix、CoordinateConvention
正确的 frustum 计算(参数化深度)src/vsg/state/ViewDependentState.cpp:585bounds、clipToWorld
从投影矩阵推 NDC 深度src/vsg/state/ViewDependentState.cpp:846clip_near、projectionMatrix
Hessian 平面与 distanceinclude/vsg/maths/plane.h:47normal_type、t_plane
intersect(planes, sphere)include/vsg/maths/plane.h:162negative_radius、t_sphere
inside(planes, v, eps)include/vsg/maths/plane.h:180negative_epsilon、t_vec3
t_sphere 的 radius=-1 哨兵include/vsg/maths/sphere.h:109t_vec3、radius
t_box 的反极值空盒include/vsg/maths/box.h:29vec_type、lowest
numbers<T>include/vsg/maths/numbers.h:22numbers、zero
smoothstep 返回 edge 值include/vsg/maths/common.h:51edge0、edge1
clamp、repeat、mirror_repeatinclude/vsg/maths/clamp.h:43mirror_repeat、v_fract
opaque_white 返回蓝include/vsg/maths/color.h:74opaque_white、color_cast
sample() 的软件采样include/vsg/maths/sample.h:48tc_index、tc_scale
native_long_double_bitssrc/vsg/maths/common.cpp:21LDBL_MANT_DIG
MatrixStack(dmat4 → float)include/vsg/vk/State.h:160dirty、matrixStack
LookAt 的 Z-up 默认值include/vsg/app/ViewMatrix.h:57center、dvec3
Perspective 的默认值与 changeExtentinclude/vsg/app/ProjectionMatrix.h:53fieldOfViewY、Perspective
CoordinateFrame 的 origin/rotationsrc/vsg/nodes/CoordinateFrame.cpp:65translate、rotation
depthCompareOp 的默认值include/vsg/state/DepthStencilState.h:31depthBoundsTestEnable、depthTestEnable
深度清除值 0.0include/vsg/app/RenderGraph.h:63ClearValues、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,建议先读完那两章。