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

Vector3

3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。

头文件

#include <XCEngine/Math/Vector3.h>

命名空间

XCEngine::Math

结构体定义

struct Vector3 {
    float x = 0.0f;
    float y = 0.0f;
    float z = 0.0f;
};

静态工厂方法

方法	返回值	描述
Zero()	Vector3	返回 (0, 0, 0)
One()	Vector3	返回 (1, 1, 1)
Forward()	Vector3	返回 (0, 0, 1)，前方向（Z+）
Back()	Vector3	返回 (0, 0, -1)，后方向
Up()	Vector3	返回 (0, 1, 0)，上方向
Down()	Vector3	返回 (0, -1, 0)，下方向
Right()	Vector3	返回 (1, 0, 0)，右方向
Left()	Vector3	返回 (-1, 0, 0)，左方向

静态数学方法

方法	返回值	描述
Dot(a, b)	float	点积
Cross(a, b)	Vector3	叉积（垂直于 a 和 b）
Normalize(v)	Vector3	归一化向量
Magnitude(v)	float	向量长度
SqrMagnitude(v)	float	长度平方
Lerp(a, b, t)	Vector3	线性插值
MoveTowards(current, target, maxDistance)	Vector3	朝目标移动
Project(vector, onNormal)	Vector3	投影到法线上
ProjectOnPlane(vector, planeNormal)	Vector3	投影到平面上
Angle(from, to)	float	两向量夹角（度）
Reflect(inDirection, inNormal)	Vector3	反射

实例方法

方法	返回值	描述
Magnitude()	float	获取向量长度
SqrMagnitude()	float	获取长度平方
Normalized()	Vector3	获取归一化副本

运算符

• 算术: +, -, * (scalar/memberwise), / (scalar/memberwise)
• 复合赋值: +=, -=, *=, /=
• 下标: operator[] (0=x, 1=y, 2=z)
• 比较: ==, !=

与 Quaternion 的乘法

Vector3 operator*(const Quaternion& q, const Vector3& v);

用四元数旋转向量。

使用示例

Vector3 pos(1.0f, 2.0f, 3.0f);
Vector3 dir = Vector3::Normalize(pos);
float len = pos.Magnitude();
Vector3 reflected = Vector3::Reflect(dir, Vector3::Up());
float angle = Vector3::Angle(Vector3::Forward(), dir);