π 3D Math Extension
How quaternions represent 3D rotations in Caffeine: the
Quat API, interpolation, conversion to matrices, and the ECS
components that store rotation data.
Tests:
tests/test_math.cpp(49 cases, including slerp/toMatrix/fromMatrix) RF: RF5.1
Overview#
Quat adds quaternion rotations to the math library for stable 3D orientation
without gimbal lock. Vec2, Vec3, Vec4 and Mat4 already provide the
vector and matrix types; Mat4 also supplies rotationX/Y/Z, perspective and
lookAt.
API#
namespace Caffeine {
// Quaternion for 3D rotations.
// Representation: (x, y, z, w), where w is the scalar part.
// Benefits: no gimbal lock, smooth SLERP, conversion to/from Matrix and Euler.
struct Quat {
f32 x = 0, y = 0, z = 0, w = 1; // identity
// ββ Static constructors βββββββββββββββββββββββββββββββββββββ
static Quat identity() { return {0, 0, 0, 1}; }
static Quat fromAxisAngle(Vec3 axis, f32 angleRad); // axis normalized internally
static Quat fromEuler(f32 pitchRad, f32 yawRad, f32 rollRad); // ZYX convention
static Quat lookAt(Vec3 forward, Vec3 up); // NO default: pass up explicitly
static Quat fromMatrix(const Mat4& m); // Shoemake (1987) algorithm
// ββ Interpolation βββββββββββββββββββββββββββββββββββββββββββ
static Quat slerp(Quat a, Quat b, f32 t); // spherical (shortest arc; linear fallback when aΒ·b > 0.9999)
static Quat nlerp(Quat a, Quat b, f32 t); // normalized linear (faster, not constant angular velocity)
// ββ Conversions βββββββββββββββββββββββββββββββββββββββββββββ
Vec3 toEuler() const; // ZYX, inverse of fromEuler()
Mat4 toMatrix() const; // column-major rotation (v' = qΒ·vΒ·qβ»ΒΉ)
// ββ Operations ββββββββββββββββββββββββββββββββββββββββββββββ
Vec3 rotate(Vec3 v) const; // rotates a vector (2 cross products)
Quat conjugate() const { return {-x, -y, -z, w}; }
Quat inverse() const; // conjugate / |q|Β²
Quat normalized() const; // identity when length is zero (silent)
f32 length() const;
f32 lengthSquared() const;
f32 dot(Quat o) const { return x*o.x + y*o.y + z*o.z + w*o.w; }
Quat operator*(Quat o) const; // composition (applies o first, then this)
Vec3 operator*(Vec3 v) const { return rotate(v); }
bool operator==(Quat o) const; // EXACT float equality
};
// 3D Mat4 methods (all implemented):
// identity, zero, translation, scale, rotationX/Y/Z, ortho, perspective,
// lookAt. There is NO Mat4::fromQuat β use Quat::toMatrix() for
// quaternion β matrix.
} // namespace Caffeine
Quaternion vs Euler vs Rotation Matrix#
| Representation | Memory | Composition | Interpolation | Problem |
|---|---|---|---|---|
| Euler (pitch/yaw/roll) | 12B | Yes | Lerp (with artifacts) | Gimbal lock |
| Quaternion | 16B | O(1) | Smooth SLERP | Unintuitive view |
| Rotation Matrix | 64B | O(nΒ²) | Difficult | Redundant |
Caffeine represents rotations with quaternions (Quat) and converts to a
matrix only when uploading to the shader. The ECS Rotation3D component stores
the same x/y/z/w components in a Vec4, not a Quat; convert explicitly when
crossing that boundary.
Usage Examples#
// ββ Rotation around an axis βββββββββββββββββββββββββββββββββββ
Caffeine::Quat rot = Caffeine::Quat::fromAxisAngle({0, 1, 0}, Caffeine::Math::PI_HALF); // 90Β° around Y
Caffeine::Vec3 rotated = rot * Caffeine::Vec3{1, 0, 0}; // β {0, 0, -1}
// ββ Euler to quaternion βββββββββββββββββββββββββββββββββββββββ
Caffeine::Quat camRot = Caffeine::Quat::fromEuler(pitch, yaw, 0);
// ββ SLERP for a smooth camera βββββββββββββββββββββββββββββββββ
Caffeine::Quat current = /* current orientation */;
Caffeine::Quat target = Caffeine::Quat::lookAt(direction, {0, 1, 0});
Caffeine::Quat smooth = Caffeine::Quat::slerp(current, target, 0.1f * dt * 60);
// ββ Convert for the shader ββββββββββββββββββββββββββββββββββββ
Caffeine::Mat4 modelMatrix = Caffeine::Mat4::translation(pos) * quat.toMatrix() * Caffeine::Mat4::scale(scale);
// upload modelMatrix to the shader through a uniform buffer
3D ECS Components (real)#
namespace Caffeine::ECS {
struct Position3D { Vec3 position; };
// β οΈ Rotation3D stores a Vec4 (x, y, z, w), NOT a Quat β convert manually:
struct Rotation3D { Vec4 quaternion = Vec4(0.0f, 0.0f, 0.0f, 1.0f); };
struct Scale3D { Vec3 scale = Vec3(1.0f, 1.0f, 1.0f); };
} // namespace Caffeine::ECS
There are no
Velocity3DorWorldTransform3Dcomponents in the code. Seesrc/caffeine/ecs/Components3D.hpp.
Acceptance Criteria#
- [x]
Quat::slerpinterpolates correctly (tests/test_math.cpp: same quat, t=0/t=1) - [x]
quat.toMatrix()equalsMat4::rotationY(angle)for the same angle (tested) - [x]
fromMatrix(identity)equals identity;fromEuler/toEulerround-trip tested - [x]
Quat * Vec3rotates correctly (rotatepreserves length) - [ ]
Mat4::fromQuatβ does not exist (usetoMatrix()); decide whether to add the helper - [ ] SIMD (
CF_SIMD,simdAdd...) β does not exist in the code; section removed - [ ]
Rotation3DstoresQuatinstead ofVec4(API improvement)
Dependencies#
- Upstream: Vec3, Vec4, Mat4
- Downstream: Camera 3D, Skeletal Animation, Mesh Loading
π Related Topics#
| Topic | Description |
|---|---|
| Rendering & Pipeline | Quaternions and Mat4 in the 3D pipeline |
| Memory & Data | Mathematical types as fundamental data |
References#
docs/architecture_specs.mdβ Β§15 Math Librarydocs/math/vectors.mdβ existing Vec/Mat documentation- Transversal Topic Index