XCEngine/docs/api/XCEngine/Core/Math/Math.md

# Math

**命名空间**: `XCEngine::Math`

**类型**: `submodule`

**描述**: 定义向量、矩阵、四元数、颜色和基础几何体等运行时数学类型。

## 概览

`Core/Math` 是引擎运行时的基础数学层。它承载了场景变换、摄像机矩阵、包围体计算、颜色处理和几何查询依赖的核心类型。

从结构上看，它大致分成几层：

- 标量常量与角度辅助：[Math](Math/Math.md)
- 向量：[Vector2](Vector2/Vector2.md)、[Vector3](Vector3/Vector3.md)、[Vector4](Vector4/Vector4.md)
- 旋转与矩阵：[Quaternion](Quaternion/Quaternion.md)、[Matrix3](Matrix3/Matrix3.md)、[Matrix4](Matrix4/Matrix4.md)
- 颜色、变换和几何体：`Color`、`Transform`、`Plane`、`Ray`、`Bounds`、`Frustum` 等

这套 API 的设计方向很接近商业引擎常见的运行时 math layer，但当前不同类型成熟度并不完全一致。向量、`Matrix4` 和 `Quaternion` 已经比较可用；部分几何类型和个别矩阵构造路径仍然需要结合源码行为理解。

## 设计要点

- 当前所有基础数学类型都采用公开字段和轻量值类型设计。
- 大部分函数是静态工厂或内联运算，倾向直接可读而不是极限泛型化。
- 若和 Unity 风格类比：
  - `Vector3` / `Quaternion` / `Matrix4` 的心智模型比较接近 Unity 同名类型
  - 但具体行为仍应以当前源码为准，而不是默认等同 Unity
- 当前数学层默认不做运行时边界检查，例如向量和矩阵的 `operator[]` 都没有保护。

## 当前实现现状

- `Lerp()` 在当前向量实现里会 clamp `t` 到 `[0, 1]`，不是无界线性插值。
- `MultiplyPoint()` 当前只是把点乘以齐次矩阵并直接取 `x/y/z`，不会做透视除法。
- `Matrix4::Inverse()` 与 `Matrix3::Inverse()` 在奇异矩阵情况下都会返回 `Identity()`，不会报错。
- `Matrix3::RotationX/Y/Z()` 当前实现从零矩阵开始填值，未设置的主对角项保持为 `0`，这会让结果和标准旋转矩阵不同。

## 头文件

- [AABB](AABB/AABB.md) - `AABB.h`
- [Bounds](Bounds/Bounds.md) - `Bounds.h`
- [Box](Box/Box.md) - `Box.h`
- [Color](Color/Color.md) - `Color.h`
- [Frustum](Frustum/Frustum.md) - `Frustum.h`
- [Math](Math/Math.md) - `Math.h`
- [Matrix3](Matrix3/Matrix3.md) - `Matrix3.h`
- [Matrix4](Matrix4/Matrix4.md) - `Matrix4.h`
- [Plane](Plane/Plane.md) - `Plane.h`
- [Quaternion](Quaternion/Quaternion.md) - `Quaternion.h`
- [Ray](Ray/Ray.md) - `Ray.h`
- [Rect](Rect/Rect.md) - `Rect.h`
- [Sphere](Sphere/Sphere.md) - `Sphere.h`
- [Transform](Transform/Transform.md) - `Transform.h`
- [Vector2](Vector2/Vector2.md) - `Vector2.h`
- [Vector3](Vector3/Vector3.md) - `Vector3.h`
- [Vector4](Vector4/Vector4.md) - `Vector4.h`

## 推荐阅读顺序

1. 先读 [Math](Math/Math.md)，确认常量、角度换算和 `EPSILON` 约定。
2. 再读 [Vector3](Vector3/Vector3.md) 与 [Quaternion](Quaternion/Quaternion.md)，这是变换和空间计算最常用的两类。
3. 然后读 [Matrix4](Matrix4/Matrix4.md)，理解当前矩阵乘法、投影和分解约定。
4. 需要二维或齐次向量时再补 [Vector2](Vector2/Vector2.md) 与 [Vector4](Vector4/Vector4.md)。

## 相关指南

- [Vectors, Quaternions, And Matrices In Runtime Transforms](../../../_guides/Core/Math/Vectors-Quaternions-And-Matrices-In-Runtime-Transforms.md)

## 相关文档

- [上级目录](../Core.md)
- [TransformComponent](../../Components/TransformComponent/TransformComponent.md)
- [API 总索引](../../../main.md)