docs: update math API docs

This commit is contained in:
2026-03-20 02:35:15 +08:00
parent e165dbea1c
commit c5b17239ca
243 changed files with 5307 additions and 1327 deletions

View File

@@ -1,24 +1,50 @@
# Matrix4::Decompose
# Matrix4x4::Decompose
```cpp
void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const
```
将矩阵分解为平移、旋转和缩放分量。
变换矩阵分解为平移、旋转和缩放三个独立分量。
**参数:**
- `translation` - 输出平移向量
- `rotation` - 输出旋转四元数
- `scale` - 输出缩放向量
- `translation` - 输出参数,接收平移向量
- `rotation` - 输出参数,接收旋转四元数
- `scale` - 输出参数,接收缩放向量
**返回:** (无)
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 m = ...;
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
#include "XCEngine/Math/Quaternion.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(1.0f, 2.0f, 3.0f),
Quaternion::FromEuler(45.0f, 0.0f, 0.0f),
Vector3(2.0f, 2.0f, 2.0f)
);
Vector3 translation;
Quaternion rotation;
Vector3 scale;
m.Decompose(translation, rotation, scale);
transform.Decompose(translation, rotation, scale);
// translation = (1.0f, 2.0f, 3.0f)
// rotation 表示 45 度 X 轴旋转
// scale = (2.0f, 2.0f, 2.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [TRS](trs.md) - 组合变换矩阵
- [GetTranslation](gettranslation.md) - 获取平移分量
- [GetRotation](getrotation.md) - 获取旋转分量
- [GetScale](getscale.md) - 获取缩放分量

View File

@@ -1,18 +1,36 @@
# Matrix4::Determinant
# Matrix4x4::Determinant
```cpp
float Determinant() const
```
计算矩阵的行列式。
计算矩阵的行列式。行列式为零的矩阵不可逆。
**返回** `float` - 行列式值
**参数** (无)
**复杂度** O(1)
**返回** 矩阵的行列式值
**线程安全:**
**复杂度:** O(n³) - O(64)
**示例:**
```cpp
Matrix4 m = ...;
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 m = Matrix4::Identity();
float det = m.Determinant();
// det = 1.0f
Matrix4 singular;
float det2 = singular.Determinant();
// det2 = 0.0f
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Inverse](inverse.md) - 矩阵求逆

View File

@@ -1,18 +1,42 @@
# Matrix4::GetRotation
# Matrix4x4::GetRotation
```cpp
Quaternion GetRotation() const
```
从矩阵中提取旋转分量。
变换矩阵中提取旋转分量。将矩阵转换为对应的四元数表示。
**返回** `Quaternion` - 旋转四元数
**参数** (无)
**返回:** 旋转四元数
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 m = ...;
Quaternion rotation = m.GetRotation();
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Quaternion.h"
using namespace XCEngine::Math;
Quaternion expected = Quaternion::FromEuler(0.0f, 90.0f, 0.0f);
Matrix4 transform = Matrix4::TRS(
Vector3(0.0f, 0.0f, 0.0f),
expected,
Vector3(1.0f, 1.0f, 1.0f)
);
Quaternion rotation = transform.GetRotation();
// rotation 表示相同的旋转
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Quaternion](../quaternion/quaternion.md) - 四元数类
- [GetTranslation](gettranslation.md) - 获取平移分量
- [GetScale](getscale.md) - 获取缩放分量
- [Decompose](decompose.md) - 分解矩阵

View File

@@ -1,18 +1,40 @@
# Matrix4::GetScale
# Matrix4x4::GetScale
```cpp
Vector3 GetScale() const
```
从矩阵中提取缩放分量。
变换矩阵中提取缩放分量。计算各列向量的长度作为缩放因子。
**返回** `Vector3` - 缩放向量
**参数** (无)
**返回:** 缩放向量
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 m = ...;
Vector3 scale = m.GetScale();
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(0.0f, 0.0f, 0.0f),
Quaternion::Identity(),
Vector3(2.0f, 3.0f, 4.0f)
);
Vector3 scale = transform.GetScale();
// scale = (2.0f, 3.0f, 4.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [GetTranslation](gettranslation.md) - 获取平移分量
- [GetRotation](getrotation.md) - 获取旋转分量
- [Decompose](decompose.md) - 分解矩阵

View File

@@ -1,18 +1,40 @@
# Matrix4::GetTranslation
# Matrix4x4::GetTranslation
```cpp
Vector3 GetTranslation() const
```
从矩阵中提取平移分量。
变换矩阵中提取平移分量。读取矩阵的最后一列前三个元素。
**返回** `Vector3` - 平移向量
**参数** (无)
**返回:** 平移向量
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 m = ...;
Vector3 translation = m.GetTranslation();
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(5.0f, 3.0f, 2.0f),
Quaternion::Identity(),
Vector3(1.0f, 1.0f, 1.0f)
);
Vector3 translation = transform.GetTranslation();
// translation = (5.0f, 3.0f, 2.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [GetRotation](getrotation.md) - 获取旋转分量
- [GetScale](getscale.md) - 获取缩放分量
- [Decompose](decompose.md) - 分解矩阵

View File

@@ -1,17 +1,31 @@
# Matrix4::Identity
# Matrix4x4::Identity
```cpp
static Matrix4 Identity()
static Matrix4x4 Identity()
```
返回 4x4 单位矩阵。
返回单位矩阵。单位矩阵是对角线元素为 1其他元素为 0 的特殊矩阵。
**返回** `Matrix4` - 单位矩阵
**参数** (无)
**返回:** 单位矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 identity = Matrix4::Identity();
// identity.m[0][0] = 1, identity.m[1][1] = 1, identity.m[2][2] = 1, identity.m[3][3] = 1
// 所有其他元素为 0
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览

View File

@@ -1,18 +1,39 @@
# Matrix4::Inverse
# Matrix4x4::Inverse
```cpp
Matrix4 Inverse() const
Matrix4x4 Inverse() const
```
返回矩阵的逆矩阵。
返回矩阵的逆矩阵。如果矩阵的行列式接近零(不可逆),则返回单位矩阵。
**返回** `Matrix4` - 逆矩阵
**参数** (无)
**复杂度** O(1)
**返回** 逆矩阵;如果矩阵不可逆则返回单位矩阵
**线程安全:**
**复杂度:** O(n³),对于 4x4 矩阵固定为 64 次基本运算
**示例:**
```cpp
Matrix4 m = ...;
Matrix4 inv = m.Inverse();
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(1.0f, 2.0f, 3.0f),
Quaternion::FromEuler(0.0f, 45.0f, 0.0f),
Vector3(2.0f, 2.0f, 2.0f)
);
Matrix4 inv = transform.Inverse();
Matrix4 identity = transform * inv;
// identity 接近单位矩阵
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Determinant](determinant.md) - 计算行列式
- [Transpose](transpose.md) - 矩阵转置

View File

@@ -1,22 +1,39 @@
# Matrix4::LookAt
# Matrix4x4::LookAt
```cpp
static Matrix4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up)
static Matrix4x4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up)
```
创建视图矩阵(观察矩阵)。
创建视图矩阵(观察矩阵)。用于将世界空间中的点转换到摄像机视角。
**参数:**
- `eye` - 机位置
- `eye` - 摄像机位置
- `target` - 观察目标点
- `up` - 世界空间中的上方向
- `up` - 摄像机上方向向量
**返回:** `Matrix4` - 视图矩阵
**返回:** 视图矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 view = Matrix4::LookAt(
Vector3(0.0f, 1.0f, 5.0f),
Vector3(0.0f, 0.0f, 0.0f),
Vector3(0.0f, 1.0f, 0.0f)
);
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Perspective](perspective.md) - 透视投影
- [Orthographic](orthographic.md) - 正交投影

View File

@@ -1,79 +1,77 @@
# Matrix4 / Matrix4x4
# Matrix4
4x4 矩阵结构体,用于表示完整的 3D 变换(平移、旋转、缩放)、视图和投影变换。
**命名空间**: `XCEngine::Math`
**头文件:** `#include <XCEngine/Math/Matrix4.h>`
**类型**: `struct`
**命名空间:** `XCEngine::Math`
**头文件**: `XCEngine/Math/Matrix4.h`
## 类型别名
**描述**: 4x4 矩阵,用于 3D 变换(平移、旋转、缩放)、视图和投影计算
## 概述
`Matrix4` (别名 `Matrix4x4`) 是 XCEngine 中用于表示 4x4 变换矩阵的结构体。它支持标准的 3D 图形变换操作,包括平移、旋转、缩放,以及视图矩阵和投影矩阵的构建。该结构体采用列主序存储方式,适用于 GPU 渲染和物理计算场景。
## 结构体成员
| 成员 | 类型 | 描述 |
|------|------|------|
| `m[4][4]` | `float` | 矩阵元素数组 |
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Identity`](identity.md) | 返回单位矩阵 |
| [`Zero`](zero.md) | 返回零矩阵 |
| [`Translation`](translation.md) | 创建平移矩阵 |
| [`Rotation`](rotation.md) | 从四元数创建旋转矩阵 |
| [`Scale`](scale.md) | 创建缩放矩阵 |
| [`TRS`](trs.md) | 创建组合变换矩阵 |
| [`LookAt`](lookat.md) | 创建视图矩阵 |
| [`Perspective`](perspective.md) | 创建透视投影矩阵 |
| [`Orthographic`](orthographic.md) | 创建正交投影矩阵 |
| [`RotationX`](rotationx.md) | 创建绕 X 轴旋转矩阵 |
| [`RotationY`](rotationy.md) | 创建绕 Y 轴旋转矩阵 |
| [`RotationZ`](rotationz.md) | 创建绕 Z 轴旋转矩阵 |
| [`operator*`](operator_mul.md) | 矩阵乘法 |
| [`MultiplyPoint`](multiplypoint.md) | 变换点w=1 |
| [`MultiplyVector`](multiplyvector.md) | 变换向量w=0 |
| [`Transpose`](transpose.md) | 转置矩阵 |
| [`Inverse`](inverse.md) | 求逆矩阵 |
| [`Determinant`](determinant.md) | 计算行列式 |
| [`GetTranslation`](gettranslation.md) | 获取平移分量 |
| [`GetRotation`](getrotation.md) | 获取旋转分量 |
| [`GetScale`](getscale.md) | 获取缩放分量 |
| [`Decompose`](decompose.md) | 分解矩阵为变换分量 |
| [`operator[]`](operator_index.md) | 访问矩阵行数据 |
## 使用示例
```cpp
using Matrix4 = Matrix4x4;
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
#include "XCEngine/Math/Quaternion.h"
using namespace XCEngine::Math;
void MatrixExample() {
Matrix4 mat = Matrix4::TRS(
Vector3(1.0f, 2.0f, 3.0f),
Quaternion::FromEuler(0.0f, 90.0f, 0.0f),
Vector3(1.5f, 1.5f, 1.5f)
);
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 transformed = mat.MultiplyPoint(point);
Matrix4 inv = mat.Inverse();
Matrix4 result = mat * inv;
}
```
## 存储方式
行优先存储 (row-major)
```
m[0][0] m[0][1] m[0][2] m[0][3]
m[1][0] m[1][1] m[1][2] m[1][3]
m[2][0] m[2][1] m[2][2] m[2][3]
m[3][0] m[3][1] m[3][2] m[3][3]
```
## 静态工厂方法
### 基础变换
| 方法 | 返回值 | 描述 |
|------|--------|------|
| [Identity()](identity.md) | `Matrix4` | 单位矩阵 |
| [Zero()](zero.md) | `Matrix4` | 零矩阵 |
| [Translation(v)](translation.md) | `Matrix4` | 平移矩阵 |
| [Scale(v)](scale.md) | `Matrix4` | 缩放矩阵 |
| [Rotation(q)](rotation.md) | `Matrix4` | 旋转矩阵(四元数) |
| [TRS(translation, rotation, scale)](trs.md) | `Matrix4` | 完整变换 |
### 旋转
| 方法 | 返回值 | 描述 |
|------|--------|------|
| [RotationX(radians)](rotationx.md) | `Matrix4` | X 轴旋转 |
| [RotationY(radians)](rotationy.md) | `Matrix4` | Y 轴旋转 |
| [RotationZ(radians)](rotationz.md) | `Matrix4` | Z 轴旋转 |
### 相机变换
| 方法 | 返回值 | 描述 |
|------|--------|------|
| [LookAt(eye, target, up)](lookat.md) | `Matrix4` | 视图矩阵 |
| [Perspective(fov, aspect, near, far)](perspective.md) | `Matrix4` | 透视投影 |
| [Orthographic(left, right, bottom, top, near, far)](orthographic.md) | `Matrix4` | 正交投影 |
## 实例方法
### 乘法
| 方法 | 返回值 | 描述 |
|------|--------|------|
| `operator*(Matrix4, Matrix4)` | `Matrix4` | 矩阵乘法 |
| `operator*(Matrix4, Vector4)` | `Vector4` | 矩阵-向量乘法 |
| [MultiplyPoint(v)](multiplypoint.md) | `Vector3` | 点变换(带平移) |
| [MultiplyVector(v)](multiplyvector.md) | `Vector3` | 方向变换(不带平移) |
### 分解
| 方法 | 返回值 | 描述 |
|------|--------|------|
| [Transpose()](transpose.md) | `Matrix4` | 转置矩阵 |
| [Inverse()](inverse.md) | `Matrix4` | 逆矩阵 |
| [Determinant()](determinant.md) | `float` | 行列式 |
| [GetTranslation()](gettranslation.md) | `Vector3` | 获取平移分量 |
| [GetRotation()](getrotation.md) | `Quaternion` | 获取旋转分量 |
| [GetScale()](getscale.md) | `Vector3` | 获取缩放分量 |
| [Decompose(translation, rotation, scale)](decompose.md) | `void` | 分解所有分量 |
## 相关文档
- [Math 模块总览](../math.md) - 返回 Math 模块总览
- [Vector3](../vector3/vector3.md) - 三维向量
- [Quaternion](../quaternion/quaternion.md) - 四元数
- [Matrix3](../matrix3/matrix3.md) - 3x3 矩阵

View File

@@ -1,21 +1,41 @@
# Matrix4::MultiplyPoint
# Matrix4x4::MultiplyPoint
```cpp
Vector3 MultiplyPoint(const Vector3& v) const
```
使用矩阵变换点(包含平移)
使用矩阵变换一个点。会自动处理 w=1 的齐次坐标变换,适用于位置变换
**参数:**
- `v` - 变换的点
- `v` - 变换的三维
**返回:** `Vector3` - 变换后的点
**返回:** 变换后的三维
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 model = Matrix4::TRS(pos, rot, scale);
Vector3 worldPos = model.MultiplyPoint(localPos);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(1.0f, 2.0f, 3.0f),
Quaternion::Identity(),
Vector3(1.0f, 1.0f, 1.0f)
);
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 transformed = transform.MultiplyPoint(point);
// transformed = (2.0f, 2.0f, 3.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [MultiplyVector](multiplyvector.md) - 向量变换
- [operator*](operator_mul.md) - 矩阵乘法

View File

@@ -1,21 +1,36 @@
# Matrix4::MultiplyVector
# Matrix4x4::MultiplyVector
```cpp
Vector3 MultiplyVector(const Vector3& v) const
```
使用矩阵变换方向向量(不包含平移)
使用矩阵变换一个方向向量。会自动处理 w=0 的齐次坐标变换,适用于方向变换,不受平移影响
**参数:**
- `v` - 变换的方向向量
- `v` - 变换的三维方向向量
**返回:** `Vector3` - 变换后的方向
**返回:** 变换后的三维方向向量
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 model = Matrix4::TRS(pos, rot, scale);
Vector3 worldDir = model.MultiplyVector(localDir);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 rotation = Matrix4::RotationY(3.14159265f / 2.0f);
Vector3 direction(1.0f, 0.0f, 0.0f);
Vector3 rotated = rotation.MultiplyVector(direction);
// rotated = (0.0f, 0.0f, -1.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [MultiplyPoint](multiplypoint.md) - 点变换
- [operator*](operator_mul.md) - 矩阵乘法

View File

@@ -0,0 +1,35 @@
# Matrix4x4::operator[]
```cpp
float* operator[](int row)
const float* operator[](int row) const
```
通过行索引访问矩阵元素。返回指向该行第一列元素的指针。
**参数:**
- `row` - 行索引0-3
**返回:** 指向该行数据的指针
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 m = Matrix4::Identity();
m[0][0] = 5.0f; // 设置第一行第一列
m[1][2] = 3.0f; // 设置第二行第三列
float val = m[0][1]; // 读取第一行第二列
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览

View File

@@ -0,0 +1,44 @@
# Matrix4x4::operator*
```cpp
Matrix4x4 operator*(const Matrix4x4& other) const
Vector4 operator*(const Vector4& v) const
```
两个重载分别用于矩阵与矩阵乘法,以及矩阵与四维向量的乘法。
**参数(矩阵乘法):**
- `other` - 右侧矩阵
**参数(向量乘法):**
- `v` - 四维向量
**返回:**
- 矩阵乘法:结果矩阵
- 向量乘法:变换后的四维向量
**线程安全:**
**复杂度:** O(n²) - 矩阵乘法为 O(4³),向量乘法为 O(4)
**示例:**
```cpp
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector4.h"
using namespace XCEngine::Math;
Matrix4 m1 = Matrix4::RotationY(1.0f);
Matrix4 m2 = Matrix4::Translation(Vector3(1.0f, 0.0f, 0.0f));
Matrix4 combined = m1 * m2;
Vector4 v(1.0f, 0.0f, 0.0f, 1.0f);
Vector4 transformed = m1 * v;
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [MultiplyPoint](multiplypoint.md) - 点变换
- [MultiplyVector](multiplyvector.md) - 向量变换

View File

@@ -1,25 +1,36 @@
# Matrix4::Orthographic
# Matrix4x4::Orthographic
```cpp
static Matrix4 Orthographic(float left, float right, float bottom, float top, float near, float far)
static Matrix4x4 Orthographic(float left, float right, float bottom, float top, float near, float far)
```
创建正交投影矩阵。
创建正交投影矩阵。用于 2D UI 或建筑制图等需要保持物体实际大小的场景。
**参数:**
- `left` - 左裁剪面
- `right` - 右裁剪面
- `bottom` - 下裁剪面
- `top` - 上裁剪面
- `near` - 近裁剪面距离
- `far` - 远裁剪面距离
- `left` - 左裁切面 x 坐标
- `right` - 右裁切面 x 坐标
- `bottom` - 下裁切面 y 坐标
- `top` - 上裁切面 y 坐标
- `near` - 近裁切面 z 坐标
- `far` - 远裁切面 z 坐标
**返回:** `Matrix4` - 正交投影矩阵
**返回:** 正交投影矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 ortho = Matrix4::Orthographic(-aspect, aspect, -1.0f, 1.0f, 0.1f, 100.0f);
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 ortho = Matrix4::Orthographic(-10.0f, 10.0f, -5.0f, 5.0f, 0.1f, 100.0f);
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Perspective](perspective.md) - 透视投影

View File

@@ -1,23 +1,37 @@
# Matrix4::Perspective
# Matrix4x4::Perspective
```cpp
static Matrix4 Perspective(float fov, float aspect, float near, float far)
static Matrix4x4 Perspective(float fov, float aspect, float near, float far)
```
创建透视投影矩阵。
创建透视投影矩阵。用于将 3D 场景投影到 2D 视口,产生近大远小的效果。
**参数:**
- `fov` - 垂直视野角度(弧度)
- `aspect` - 宽高比
- `near` - 近裁面距离
- `far` - 远裁面距离
- `aspect` - 宽高比width / height
- `near` - 近裁面距离
- `far` - 远裁面距离
**返回:** `Matrix4` - 透视投影矩阵
**返回:** 透视投影矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
float fov = 60.0f * 3.14159265f / 180.0f;
float aspect = 16.0f / 9.0f;
Matrix4 proj = Matrix4::Perspective(fov, aspect, 0.1f, 100.0f);
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Orthographic](orthographic.md) - 正交投影
- [LookAt](lookat.md) - 视图矩阵

View File

@@ -1,21 +1,39 @@
# Matrix4::Rotation
# Matrix4x4::Rotation
```cpp
static Matrix4 Rotation(const Quaternion& q)
static Matrix4x4 Rotation(const Quaternion& q)
```
从四元数创建旋转矩阵。
从四元数创建旋转矩阵。用于将旋转变换应用到点或向量。
**参数:**
- `q` - 四元数
- `q` - 表示旋转的四元数
**返回:** `Matrix4` - 旋转矩阵
**返回:** 旋转矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
Matrix4 rotation = Matrix4::Rotation(rot);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Quaternion.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Quaternion q = Quaternion::FromEuler(0.0f, 90.0f, 0.0f);
Matrix4 rotate = Matrix4::Rotation(q);
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 rotated = rotate.MultiplyVector(point);
// point 绕 Y 轴旋转 90 度
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Quaternion](../quaternion/quaternion.md) - 四元数类
- [TRS](trs.md) - 组合变换矩阵

View File

@@ -1,20 +1,36 @@
# Matrix4::RotationX
# Matrix4x4::RotationX
```cpp
static Matrix4 RotationX(float radians)
static Matrix4x4 RotationX(float radians)
```
创建绕 X 轴旋转的矩阵。
创建绕 X 轴旋转的矩阵。角度为正时,按右手定则逆时针旋转。
**参数:**
- `radians` - 旋转角度(弧度)
**返回:** `Matrix4` - 旋转矩阵
**返回:** 绕 X 轴旋转矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 rotX = Matrix4::RotationX(Math::HALF_PI);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 rotX = Matrix4::RotationX(3.14159265f / 2.0f); // 90 度
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 rotated = rotX.MultiplyVector(point);
// point 绕 X 轴旋转 90 度
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [RotationY](rotationy.md) - 绕 Y 轴旋转
- [RotationZ](rotationz.md) - 绕 Z 轴旋转

View File

@@ -1,20 +1,36 @@
# Matrix4::RotationY
# Matrix4x4::RotationY
```cpp
static Matrix4 RotationY(float radians)
static Matrix4x4 RotationY(float radians)
```
创建绕 Y 轴旋转的矩阵。
创建绕 Y 轴旋转的矩阵。角度为正时,按右手定则逆时针旋转。
**参数:**
- `radians` - 旋转角度(弧度)
**返回:** `Matrix4` - 旋转矩阵
**返回:** 绕 Y 轴旋转矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 rotY = Matrix4::RotationY(Math::HALF_PI);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 rotY = Matrix4::RotationY(3.14159265f / 2.0f); // 90 度
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 rotated = rotY.MultiplyVector(point);
// point 绕 Y 轴旋转 90 度
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [RotationX](rotationx.md) - 绕 X 轴旋转
- [RotationZ](rotationz.md) - 绕 Z 轴旋转

View File

@@ -1,20 +1,36 @@
# Matrix4::RotationZ
# Matrix4x4::RotationZ
```cpp
static Matrix4 RotationZ(float radians)
static Matrix4x4 RotationZ(float radians)
```
创建绕 Z 轴旋转的矩阵。
创建绕 Z 轴旋转的矩阵。角度为正时,按右手定则逆时针旋转。
**参数:**
- `radians` - 旋转角度(弧度)
**返回:** `Matrix4` - 旋转矩阵
**返回:** 绕 Z 轴旋转矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 rotZ = Matrix4::RotationZ(Math::HALF_PI);
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 rotZ = Matrix4::RotationZ(3.14159265f / 2.0f); // 90 度
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 rotated = rotZ.MultiplyVector(point);
// point 绕 Z 轴旋转 90 度
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [RotationX](rotationx.md) - 绕 X 轴旋转
- [RotationY](rotationy.md) - 绕 Y 轴旋转

View File

@@ -1,20 +1,35 @@
# Matrix4::Scale
# Matrix4x4::Scale
```cpp
static Matrix4 Scale(const Vector3& v)
static Matrix4x4 Scale(const Vector3& v)
```
创建缩放矩阵。
创建缩放矩阵。用于沿各轴方向对点或向量进行缩放变换。
**参数:**
- `v` - 各轴缩放因子
- `v` - 缩放向量,指定 x、y、z 方向上的缩放因子
**返回:** `Matrix4` - 缩放矩阵
**返回:** 缩放矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 2.0f, 2.0f));
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 scale = Matrix4::Scale(Vector3(2.0f, 0.5f, 1.0f));
Vector3 point(2.0f, 4.0f, 2.0f);
Vector3 scaled = scale.MultiplyVector(point);
// scaled = (4.0f, 2.0f, 2.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [TRS](trs.md) - 组合变换矩阵

View File

@@ -1,20 +1,35 @@
# Matrix4::Translation
# Matrix4x4::Translation
```cpp
static Matrix4 Translation(const Vector3& v)
static Matrix4x4 Translation(const Vector3& v)
```
创建平移矩阵。
创建平移矩阵。生成的矩阵用于沿指定方向移动点或向量。
**参数:**
- `v` - 平移向量
- `v` - 平移向量 (x, y, z 方向上的平移量)
**返回:** `Matrix4` - 平移矩阵
**返回:** 平移矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
Matrix4 translation = Matrix4::Translation(Vector3(1.0f, 2.0f, 3.0f));
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
using namespace XCEngine::Math;
Matrix4 translate = Matrix4::Translation(Vector3(5.0f, 3.0f, 2.0f));
Vector3 point(1.0f, 1.0f, 1.0f);
Vector3 moved = translate.MultiplyPoint(point);
// moved = (6.0f, 4.0f, 3.0f)
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [TRS](trs.md) - 组合变换矩阵

View File

@@ -1,18 +1,32 @@
# Matrix4::Transpose
# Matrix4x4::Transpose
```cpp
Matrix4 Transpose() const
Matrix4x4 Transpose() const
```
返回矩阵的转置。
返回矩阵的转置。转置操作将矩阵的行和列互换。
**返回** `Matrix4` - 转置矩阵
**参数** (无)
**复杂度** O(1)
**返回** 转置后的矩阵
**线程安全:**
**复杂度:** O(n²) - O(16)
**示例:**
```cpp
Matrix4 m = ...;
Matrix4 transposed = m.Transpose();
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 m = Matrix4::Identity();
Matrix4 t = m.Transpose();
// 转置后仍为单位矩阵
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Inverse](inverse.md) - 矩阵求逆

View File

@@ -1,22 +1,45 @@
# Matrix4::TRS
# Matrix4x4::TRS
```cpp
static Matrix4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale)
static Matrix4x4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale)
```
创建完整的 TRS平移、旋转、缩放变换矩阵
创建组合变换矩阵。等价于先缩放、再旋转、最后平移的组合效果
**参数:**
- `translation` - 平移向量
- `rotation` - 旋转四元数
- `scale` - 缩放向量
**返回:** `Matrix4` - 组合变换矩阵
**返回:** 组合变换矩阵 T * R * S
**复杂度** O(1)
**线程安全**
**复杂度:** O(n²) - 涉及多次 4x4 矩阵运算
**示例:**
```cpp
Matrix4 transform = Matrix4::TRS(position, rotation, Vector3::One());
#include "XCEngine/Math/Matrix4.h"
#include "XCEngine/Math/Vector3.h"
#include "XCEngine/Math/Quaternion.h"
using namespace XCEngine::Math;
Matrix4 transform = Matrix4::TRS(
Vector3(1.0f, 2.0f, 3.0f),
Quaternion::FromEuler(0.0f, 90.0f, 0.0f),
Vector3(2.0f, 2.0f, 2.0f)
);
Vector3 point(1.0f, 0.0f, 0.0f);
Vector3 transformed = transform.MultiplyPoint(point);
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览
- [Translation](translation.md) - 平移矩阵
- [Rotation](rotation.md) - 旋转矩阵
- [Scale](scale.md) - 缩放矩阵
- [Decompose](decompose.md) - 分解矩阵

View File

@@ -1,17 +1,30 @@
# Matrix4::Zero
# Matrix4x4::Zero
```cpp
static Matrix4 Zero()
static Matrix4x4 Zero()
```
返回零矩阵。
返回零矩阵。所有元素初始化为 0 的矩阵。
**返回** `Matrix4` - 零矩阵
**参数** (无)
**返回:** 零矩阵
**线程安全:**
**复杂度:** O(1)
**示例:**
```cpp
#include "XCEngine/Math/Matrix4.h"
using namespace XCEngine::Math;
Matrix4 zero = Matrix4::Zero();
// 所有元素均为 0
```
## 相关文档
- [Matrix4](matrix4.md) - 返回类总览