《OGRE 3D 渲染引擎原理与架构》4.1 Vector 与 Quaternion

v14.6.3 的向量是模板化的 Vector<dims,T>,Vector3 只是 Vector<3,Real> 的别名,旧的 OgreVector3.h 已退化为弃用桩。四元数 Quaternion 用角轴构造,FromAngleAxis 把公式 q=cos(A/2)+sin(A/2)*axis 落成代码。lab 用 C++ 复现点积叉积、角轴构造与向量旋转。

4.1 Vector 与 Quaternion

OGRE 的数学库在 v14 经历了一次大改:向量从独立的 Vector3/Vector4 类变成模板化的 Vector<dims, T>。OgreVector.h 里先定义 VectorBase<dims, T> 基模板,再对 2/3/4 维特化,最后 Vector 继承它:

// OgreMain/include/OgreVector.h:VectorBase 模板(v14.6.3 源码摘录,已删减)
template <int dims, typename T> struct VectorBase
{
...
template <> struct _OgreExport VectorBase<3, Real>
{
...
constexpr VectorBase(Real _x, Real _y, Real _z) : x(_x), y(_y), z(_z) {}
Real x, y, z;
...
Real absDotProduct(const VectorBase& vec) const
...
};

class _OgreMaybeExport Vector : public VectorBase<dims, T>
{
...
constexpr Vector(T _x, T _y, T _z) : VectorBase<dims, T>(_x, _y, _z) {}
...
};

Vector<3, Real> 的别名在 OgrePrerequisites.h:

// OgreMain/include/OgrePrerequisites.h:Vector 别名(v14.6.3 源码摘录,已删减)
    typedef Vector<3, Real> Vector3;

Real 是浮点类型别名(默认 float)。因此全书代码里的 Vector3、Vector4 本质都是 Vector<3, Real>、Vector<4, Real>。旧头文件 OgreVector3.h 已经退化成一行弃用桩,指向新模板:

// OgreMain/include/OgreVector3.h:弃用桩(v14.6.3 源码摘录)
#include "OgreVector.h"
#pragma message( __FILE__ " is deprecated, migrate to Ogre.h")

这个「旧文件名保留、内容迁走」的模式,是源码演进里兼容性设计的缩影。向量长度用 Math::Sqrt 而不是裸 std::sqrt,因为 Math 类统一了数学函数的入口:

// OgreMain/include/OgreVector.h:length(v14.6.3 源码摘录,已删减)
Real length() const { return Math::Sqrt(squaredLength()); }

Quaternion:角轴构造与旋转

OgreQuaternion.h 的 Quaternion 用 w + x*i + y*j + z*k 表示旋转。角轴构造的实现公式非常经典,注释里直接写了推导:

// OgreMain/src/OgreQuaternion.cpp:Quaternion::FromAngleAxis(v14.6.3 源码摘录,已删减)
    void Quaternion::FromAngleAxis (const Radian& rfAngle,
        const Vector3& rkAxis)
    {
        // The quaternion representing the rotation is
        //   q = cos(A/2)+sin(A/2)*(x*i+y*j+z*k)

        Radian fHalfAngle ( 0.5*rfAngle );
        Real fSin = Math::Sin(fHalfAngle);
        w = Math::Cos(fHalfAngle);
        x = fSin*rkAxis.x;
        y = fSin*rkAxis.y;
        z = fSin*rkAxis.z;
    }

绕轴 axis 旋转角度 A,四元数是半角公式:w = cos(A/2),虚部 (x,y,z) = sin(A/2)*axis。注意轴必须单位化。旋转向量则用 v' = q v q*,OgreQuaternion.h 里 operator*(Vector3) 声明,实现在 .cpp 里展开为代数式。Norm() 与 normalise() 负责四元数的单位化:

// OgreMain/include/OgreQuaternion.h:Norm/normalise(v14.6.3 源码摘录,已删减)
        Real Norm() const { return Math::Sqrt(w * w + x * x + y * y + z * z); }
        Real normalise(void)
        {
            Real len = Norm();
            ...
        }

为什么向量要模板化

Vector<dims, T> 带来的直接收益是 Vector<2, float>、Vector<4, double> 这类变体不用各自写一份。代价是 2/3/4 维特化要手写成员。这套「模板 + 特化」的组合在 OGRE 里广泛存在,读源码时看到 Vector<3, Real> 要知道它等价于老的 Vector3。

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现 Vector3 的点积/叉积/长度,以及 Quaternion::FromAngleAxis 的角轴构造与向量旋转。它与 src/04-1-vector-quaternion.cpp 逐字节一致:

// file: src/04-1-vector-quaternion.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/04-1-vector-quaternion.cpp -o bin/04-1-vector-quaternion && ./bin/04-1-vector-quaternion
//
// 复现 OgreVector.h 的 Vector3 运算与 OgreQuaternion 的角轴构造/旋转。
// 公式:q = cos(A/2) + sin(A/2)*(x*i+y*j+z*k);v' = q v q*。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cmath>

namespace ogre_repro {

// 对应 VectorBase<3,Real>:x/y/z + 长度/点积/叉积
struct Vector3 {
  double x, y, z;
  Vector3(double _x = 0, double _y = 0, double _z = 0) : x(_x), y(_y), z(_z) {}

  double dot(const Vector3& rhs) const { return x * rhs.x + y * rhs.y + z * rhs.z; }
  Vector3 cross(const Vector3& rhs) const {
    return Vector3(y * rhs.z - z * rhs.y, z * rhs.x - x * rhs.z,
                   x * rhs.y - y * rhs.x);
  }
  Vector3 operator+(const Vector3& r) const {
    return Vector3(x + r.x, y + r.y, z + r.z);
  }
  Vector3 operator*(double s) const {
    return Vector3(x * s, y * s, z * s);
  }
  friend Vector3 operator*(double s, const Vector3& v) { return v * s; }
  double squaredLength() const { return x * x + y * y + z * z; }
  // 对应 OgreVector.h:length() { return Math::Sqrt(squaredLength()); }
  double length() const { return std::sqrt(squaredLength()); }
};

// 对应 OgreQuaternion.h:w + x*i + y*j + z*k
struct Quaternion {
  double w, x, y, z;
  Quaternion(double _w = 1, double _x = 0, double _y = 0, double _z = 0)
      : w(_w), x(_x), y(_y), z(_z) {}

  // 对应 Quaternion::FromAngleAxis:
  // q = cos(A/2) + sin(A/2)*(axis.x*i + axis.y*j + axis.z*k)
  static Quaternion fromAngleAxis(double angle, const Vector3& axis) {
    const double half = 0.5 * angle;
    return Quaternion(std::cos(half), std::sin(half) * axis.x,
                      std::sin(half) * axis.y, std::sin(half) * axis.z);
  }

  // 对应 Quaternion::Norm:w*w+x*x+y*y+z*z 的开方
  double norm() const { return std::sqrt(w * w + x * x + y * y + z * z); }

  Quaternion conjugate() const { return Quaternion(w, -x, -y, -z); }

  Quaternion operator*(const Quaternion& r) const {
    return Quaternion(w * r.w - x * r.x - y * r.y - z * r.z,
                      w * r.x + x * r.w + y * r.z - z * r.y,
                      w * r.y - x * r.z + y * r.w + z * r.x,
                      w * r.z + x * r.y - y * r.x + z * r.w);
  }

  // 对应 Quaternion::operator*(Vector3):v' = q v q* 的向量旋转
  Vector3 operator*(const Vector3& v) const {
    const Vector3 u(x, y, z);
    const Vector3 t = 2.0 * u.cross(v);
    return v + (w * t) + u.cross(t);
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // Vector3:点积 / 叉积 / 长度
  Vector3 a(1, 0, 0), b(0, 1, 0);
  CHECK(a.dot(b) == 0.0);
  CHECK(a.cross(b).z == 1.0);
  CHECK(b.cross(a).z == -1.0);
  CHECK(a.length() == 1.0);
  CHECK(Vector3(3, 4, 0).length() == 5.0);

  // 绕 z 轴旋转 90°:(1,0,0) → (0,1,0)
  // 半角 45°,w = cos(45°) ≈ 0.7071
  const Quaternion q = Quaternion::fromAngleAxis(3.141592653589793 / 2, Vector3(0, 0, 1));
  CHECK(std::abs(q.w - 0.70710678) < 1e-6);
  CHECK(std::abs(q.z - 0.70710678) < 1e-6);         // sin(45°) 落在 z 分量
  const Vector3 rotated = q * Vector3(1, 0, 0);
  CHECK(std::abs(rotated.x) < 1e-9);
  CHECK(std::abs(rotated.y - 1.0) < 1e-9);

  // 单位四元数范数为 1
  const Quaternion unit = Quaternion::fromAngleAxis(0.7, Vector3(1, 0, 0));
  CHECK(std::abs(unit.norm() - 1.0) < 1e-9);

  // 四元数乘法保持范数(旋转复合仍是旋转)
  const Quaternion c = q * unit;
  CHECK(std::abs(c.norm() - 1.0) < 1e-9);

  std::printf("rotate (1,0,0) by 90deg about z → (%.3f, %.3f, %.3f)\n",
              rotated.x, rotated.y, rotated.z);
  return lab::report("04-1 数学库:Vector 与 Quaternion");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 12/12 通过,打印 90° 旋转结果 (0.000, 1.000, 0.000)。

小结

  • v14.6.3 向量模板化:Vector3 = Vector<3, Real>,旧头文件退化为弃用桩。
  • Math 类统一数学函数入口,length() 内部走 Math::Sqrt。
  • Quaternion::FromAngleAxis 实现半角公式:q = cos(A/2)+sin(A/2)*axis。
  • 旋转向量用 v' = q v q*,Norm/normalise 负责单位化。

阅读导航:上一节:3.3 插件安装、初始化与注册序 · 下一节:4.2 Matrix、Plane 与 AABB 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图