XCEngine/docs/api/math/math-matrix4.md

Matrix4 / Matrix4x4

4x4 矩阵结构体，用于表示完整的 3D 变换（平移、旋转、缩放）、视图和投影变换。

头文件

#include <XCEngine/Math/Matrix4.h>

命名空间

XCEngine::Math

类型别名

using Matrix4 = Matrix4x4;

存储方式

行优先存储 (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()	Matrix4	单位矩阵
Zero()	Matrix4	零矩阵
Translation(const Vector3& v)	Matrix4	平移矩阵
Scale(const Vector3& v)	Matrix4	缩放矩阵
Rotation(const Quaternion& q)	Matrix4	旋转矩阵（四元数）
TRS(translation, rotation, scale)	Matrix4	完整变换

旋转

方法	返回值	描述
RotationX(float radians)	Matrix4	X 轴旋转
RotationY(float radians)	Matrix4	Y 轴旋转
RotationZ(float radians)	Matrix4	Z 轴旋转

相机变换

方法	返回值	描述
LookAt(eye, target, up)	Matrix4	视图矩阵
Perspective(fov, aspect, near, far)	Matrix4	透视投影
Orthographic(left, right, bottom, top, near, far)	Matrix4	正交投影

实例方法

乘法

方法	返回值	描述
operator*(Matrix4, Matrix4)	Matrix4	矩阵乘法
operator*(Matrix4, Vector4)	Vector4	矩阵-向量乘法
MultiplyPoint(v)	Vector3	点变换（带平移）
MultiplyVector(v)	Vector3	方向变换（不带平移）

分解

方法	返回值	描述
Transpose()	Matrix4	转置矩阵
Inverse()	Matrix4	逆矩阵
Determinant()	float	行列式
GetTranslation()	Vector3	获取平移分量
GetRotation()	Quaternion	获取旋转分量
GetScale()	Vector3	获取缩放分量
Decompose(translation, rotation, scale)	void	分解所有分量

使用示例

// MVP 矩阵
Matrix4 model = Matrix4::TRS(position, rotation, scale);
Matrix4 view = Matrix4::LookAt(cameraPos, target, Vector3::Up());
Matrix4 proj = Matrix4::Perspective(45.0f * DEG_TO_RAD, aspect, 0.1f, 100.0f);
Matrix4 mvp = proj * view * model;

// 变换点
Vector3 worldPos = model.MultiplyPoint(localPos);
Vector3 worldDir = model.MultiplyVector(localDir);

// 分解矩阵
Vector3 translation;
Quaternion rotation;
Vector3 scale;
model.Decompose(translation, rotation, scale);