数学库编程指南

概述

Flexi引擎使用的数学库是微软的DirectXMath，为常用的线性代数和图形数学运算提供 SIMD 友好的 C++ 类型和函数，本文档是介绍Flexi里常用的DirectXMath数据结构和函数。

DirectXMath的详细文档可以参考微软官方的文档 https://learn.microsoft.com/en-us/windows/win32/dxmath/directxmath-portal

库目录及包含头文件

引擎数学库头文件: ../visual/dx_math.h

DirectXMath位于第三方库目录: ../extern/math/dxmath

说明：库中的接口全部为内联方式(inline)，仅包含../visual/dx_math.h头文件即可，无需包含其它的文件和库。

常用结构体

• 浮点向量：

  二维向量 XMFLOAT2

  三维向量 XMFLOAT3

  四维向量 XMFLOAT4

• 整型向量：

  二维向量 XMINT2

  三维向量 XMINT3

• 矩阵：

  XMFLOAT4X4

  XMFLOAT4X3

  XMFLOAT3X4

  XMFLOAT3X3

• 基本用法：

  和普通的c结构没有区别，成员变量、全局变量、堆变量、栈变量都可以使用。一般不能直接参与数学库的计算，DirectXMath中很少有直接操作这些结构体的接口。

• 注意：此处仅列出几种常用的结构体，没有包含所有可能用到的结构体。

支持SIMD优化的结构体

• 向量

  基本类型：

  XMVECTOR

  别名(Aliases)：

  CXMVECTOR

  FXMVECTOR

  GXMVECTOR

  详情请参见DirectXMath.h。

  所有数据向量（二维，三维，四维的浮点和整型向量等），在使用DirectXMath做计算之前，需要先转成XMVECTOR。

• 矩阵

  基本类型：

  XMMATRIX

  别名（Aliases）：

  CXMMATRIX

  FXMMATRIX

  XMVECTORI32

  详情参加参见数学库DirectXMath.h文件。

  所有数据矩阵（4X4，4X3，3X4，3X3等矩阵），在使用DirectXMath做计算之前，需要先转成XMMATRIX。

• 基本用法：

  主要用于数据计算处理，一般从数据对象进行加载创建，然后参与计算和数据缓存，因为其内存需要字节对齐等特殊要求，一般仅用于栈变量，不能用于成员变量、堆变量。开发过程中如有必要的情况下可以申请分配16字节对齐的内存块。

  XMFLOAT3 vNormal;
  XMFLOAT4X4 mtxWorld;
  ...
  // Loads a XMFLOAT3 into a XMVECTOR
  XMVECTOR n = XMLoadFloat3(&vNormal);
  // Loads a XMFLOAT4X4 into a XMMATRIX
  XMMATRIX mtx = XMLoadFloat4X4(&mtxWorld);
  
  // Do somthing
  n = XMVector3Normalize(n);
  n = XMVector3TransformNormal(n, mtx);
  
  // Store a XMVECTOR into a XMFLOAT3
  XMFLOAT3 v;
  XMStoreFloat3(&v, n);

基本的接口

说明：下文中默认向量指的是XMVECTOR，矩阵指的是MATRIX，[n]表示向量维数，缺省值为4。下文中仅列出最常用的部分接口作解释和用法说明。

向量

• 数据向量转XMVECTOR

  XMVECTOR XMLoadFloat2(const XMFLOAT2* pSource)

  XMVECTOR XMLoadFloat3(const XMFLOAT3* pSource)

  XMVECTOR XMLoadFloat4(const XMFLOAT4* pSource)

  XMVECTOR XMLoadInt2( const uint32_t* pSource)

  XMVECTOR XMLoadInt( const uint32_t* pSource)

  例如：

  XMFLOAT3 vPosition;
  ...
  XMVECTOR pos = XMLoadFloat3(&vPosition);

• XMVECTOR 转数据向量

  void XMStoreFloat2(XMFLOAT2* pDestination, FXMVECTOR V)

  void XMStoreFloat3(XMFLOAT3* pDestination, FXMVECTOR V)

  void XMStoreFloat4(XMFLOAT4* pDestination, FXMVECTOR V)

  void XMStoreInt2(uint32_t* pDestination, FXMVECTOR V)

  void XMStoreInt3(uint32_t* pDestination, FXMVECTOR V)

  例如：

  XMVECTOR pos;
  ...
  XMFLOAT3 vPosition;
  XMStoreFloat3(&vPosition，pos);

• 向量的分量获取

  float XMVectorGetX(FXMVECTOR V)

  float XMVectorGetY(FXMVECTOR V)

  float XMVectorGetZ(FXMVECTOR V)

  float XMVectorGetW(FXMVECTOR V)

• 向量的分量更改

  XMVECTOR XMVectorSetX(FXMVECTOR V, float x)

  XMVECTOR XMVectorSetY(FXMVECTOR V, float x)

  XMVECTOR XMVectorSetZ(FXMVECTOR V, float x)

  XMVECTOR XMVectorSetW(FXMVECTOR V, float x)

  注意：这些更改接口，返回的更改后的新向量，并不会更改入参的原始向量。

  例如，需要更改V向量的X分量为1，正确的写法为：

  V = XMVectorSetX(V, 1.0F)；

• 初始化一个向量

  XMVECTOR XMVectorSet(float x, float y, float z, float w)

  XMVECTOR XMVectorReplicate(float value) // Initialize a vector with a replicated floating point value

  XMVECTOR XMVectorZero() // Creates the zero vector.

• 向量的四则运算

  • 运算符方式，支持+、-、、/、+=、-=、=、/=等

  • 支持向量与基本数据支持四则运算

  • 四则运算接口

    XMVECTOR XMVectorAdd(FXMVECTOR V1, FXMVECTOR V2)

    XMVECTOR XMVectorSum(FXMVECTOR V1, FXMVECTOR V2)

    XMVECTOR XMVectorMultiply(FXMVECTOR V1, FXMVECTOR V2)

    XMVECTOR XMVectorDivide(FXMVECTOR V1, FXMVECTOR V2)

• 向量的最值

  XMVECTOR XMVectorMin(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVectorMax(FXMVECTOR V1, FXMVECTOR V2)

  template <class T> inline T XMMin(T a, T b)

  template <class T> inline T XMMax(T a, T b)

• 绝对值向量

  XMVECTOR XMVector[n]abs(FXMVECTOR V)

• 向量的比较

  XMVECTOR XMVector[n]Equal(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector[n]NearEqual(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector[n]Greater(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector[n]Less(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector[n]IsNaN(FXMVECTOR V1, FXMVECTOR V2)

• 向量区间限制

  XMVECTOR XMVector[n]Clamp(FXMVECTOR V, FXMVECTOR Min, FXMVECTOR Max)

  XMVECTOR XMVector[n]Saturate(FXMVECTOR V)

• 向量线性插值

  XMVECTOR XMVector[n]Lerp(FXMVECTOR V0, FXMVECTOR V1, float t)

• 向量的点乘

  XMVECTOR XMVector2Dot(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector3Dot(FXMVECTOR V1, FXMVECTOR V2)

• 向量的叉乘

  XMVECTOR XMVector2Cross(FXMVECTOR V1, FXMVECTOR V2)

  XMVECTOR XMVector3Cross(FXMVECTOR V1, FXMVECTOR V2)

• 向量的取模

  向量模的平方

  XMVECTOR XMVector2LengthSq(FXMVECTOR V)

  XMVECTOR XMVector3LengthSq(FXMVECTOR V)

  向量模

  XMVECTOR XMVector2Length(FXMVECTOR V)

  XMVECTOR XMVector3Length(FXMVECTOR V)

  向量近似模

  XMVECTOR XMVector2LengthEst(FXMVECTOR V)

  XMVECTOR XMVector3LengthEst(FXMVECTOR V)

• 向量的单位化

  XMVECTOR XMVector2Normalize(FXMVECTOR V)

  XMVECTOR XMVector3Normalize(FXMVECTOR V)

• 求反射向量

  XMVECTOR XMVector3Reflect(FXMVECTOR Incident, FXMVECTOR Normal)

• 向量与矩阵

  • 用于坐标转换

  XMVECTOR XMVector3TransformCoord(FXMVECTOR V, FXMMATRIX M)

  • 用于向量（法线）转换

    XMVECTOR XMVector3TransformNormal(FXMVECTOR V, FXMMATRIX M)

  • 保留齐次数据转换，结果不除w等价于XMVector3TransformNormal，结果除w等价于XMVector3TransformCoord XMVECTOR XMVector3Transform

• 向量与四元数

  XMVECTOR XMVector3Rotate(FXMVECTOR V, FXMVECTOR RotationQuaternion)

矩阵

• 数据矩阵转XMMATRIX

  XMMATRIX XMLoadFloat4X4(const XMFLOAT4X4* pSource)

  XMMATRIX XMLoadFloat4X3(const XMFLOAT4X3* pSource)

  XMMATRIX XMLoadFloat3X4(const XMFLOAT3X4* pSource)

  XMMATRIX XMLoadFloat3X3(const XMFLOAT3X3* pSource)

  例如：

  XMMATRIX mtx = XMLoadFloat4X4(&m_mtxWorld);

• XMMATRIX 转数据矩阵

  void XMStoreFloat4X4(XMFLOAT4X4* pDestination, FXMMATRIX M)

  void XMStoreFloat4X3(XMFLOAT4X3* pDestination, FXMMATRIX M)

  void XMStoreFloat3X4(XMFLOAT3X4* pDestination, FXMMATRIX M)

  void XMStoreFloat3X3(XMFLOAT3X3* pDestination, FXMMATRIX M)

  例如：

  XMMATRIX mtx；
    ...
  XMStoreFloat4X4(&m_mtxWorld，mtx);

• 单位化矩阵

  XMMATRIX XMMatrixIsIdentity(FXMMATRIX M)

• 逆矩阵

  XMMATRIX XMMatrixInverse(XMVECTOR* pDeterminant, FXMMATRIX M)

• 转置矩阵

  XMMATRIX XMMatrixTranspose(FXMMATRIX M)

• 平移矩阵

  XMMATRIX XMMatrixTranslation(float OffsetX, float OffsetY, float OffsetZ)

  XMMATRIX XMMatrixTranslationFromVector(FXMVECTOR Offset)

• 缩放矩阵

  XMMATRIX XMMatrixScaling(float ScaleX, float ScaleY, float ScaleZ)

  XMMATRIX XMMatrixScalingFromVector(FXMVECTOR Scale)

• 旋转矩阵

  • 绕世界坐标单轴旋转，弧度单位

  XMMATRIX XMMatrixRotationX(float Angle)

  XMMATRIX XMMatrixRotationY(float Angle)

  XMMATRIX XMMatrixRotationZ(float Angle)

  • 欧拉角旋转，弧度单位

  XMMATRIX XMMatrixRotationRollPitchYaw(float Pitch, float Yaw, float Roll)

  XMMATRIX XMMatrixRotationRollPitchYawFromVector(FXMVECTOR Angles)

  • 绕给定轴旋转，弧度单位

  XMMATRIX XMMatrixRotationNormal(FXMVECTOR NormalAxis, float Angle)

  XMMATRIX XMMatrixRotationAxis(FXMVECTOR Axis, float Angle)

  • 四元数转旋转矩阵

  XMMATRIX XMMatrixRotationQuaternion(FXMVECTOR Quaternion)

• 平移，缩放，旋转复合矩阵

  XMMATRIX XMMatrixAffineTransformation(FXMVECTOR Scaling, FXMVECTOR RotationOrigin, FXMVECTOR RotationQuaternion, GXMVECTOR Translation)

• 复合矩阵分解

  bool XMMatrixDecompose( XMVECTOR outScale, XMVECTOR outRotQuat, XMVECTOR* outTrans, FXMMATRIX M)

• 视口矩阵

  XMMATRIX XMMatrixLookAtLH(FXMVECTOR EyePosition, FXMVECTOR FocusPosition, FXMVECTOR UpDirection)

• 透视投影矩阵

  XMMATRIX XMMatrixPerspectiveLH(float ViewWidth, float ViewHeight, float NearZ, float FarZ)

  XMMATRIX XMMatrixPerspectiveFovLH(float FovAngleY, float AspectRatio, float NearZ, float FarZ)

• 正交投影矩阵

  XMMATRIX XMMatrixOrthographicLH(float ViewWidth, float ViewHeight, float NearZ, float FarZ)

  XMMATRIX XMMatrixOrthographicOffCenterLH(float ViewLeft, float ViewRight, float ViewBottom, float ViewTop, float NearZ, float FarZ)

• 矩阵乘法

  XMMATRIX XMMatrixMultiply(FXMMATRIX M1, CXMMATRIX M2)

• 矩阵先乘后转置

  XMMATRIX XMMatrixMultiplyTranspose(FXMMATRIX M1, CXMMATRIX M2)

四元数

• 四元数的比较

  bool XMQuaternionEqual(FXMVECTOR Q1, FXMVECTOR Q2)

• 四元数的单位化

  XMVECTOR XMQuaternionNormalize(FXMVECTOR Q)

• 四元数的取逆

  XMVECTOR XMQuaternionInverse(FXMVECTOR Q)

• 四元数的生成

  • 单位化生成

    XMVECTOR XMQuaternionIdentity()

  • 从欧拉角生成

    XMVECTOR XMQuaternionRotationRollPitchYaw(float Pitch, float Yaw, float Roll)

    XMVECTOR XMQuaternionRotationRollPitchYawFromVector(FXMVECTOR Angles)

  • 从轴和旋转角度生成

    XMVECTOR XMQuaternionRotationAxis(FXMVECTOR Axis, float Angle) // Computes a rotation quaternion about an axis.

    XMVECTOR XMQuaternionRotationNormal(FXMVECTOR NormalAxis, float Angle) // Computes the rotation quaternion about a normal vector.

  • 从旋转矩阵生成

    XMQuaternionRotationMatrix(FXMMATRIX M)

• 四元数的乘法

  XMVECTOR XMQuaternionMultiply(FXMVECTOR Q1, FXMVECTOR Q2)

• 四元数的插值

  XMVECTOR XMQuaternionSlerp(FXMVECTOR Q0, FXMVECTOR Q1, float t)

• 四元数的分解

  void XMQuaternionToAxisAngle(Out XMVECTOR pAxis, Out float pAngle, In FXMVECTOR Q)

面

• 面的单位化

  XMVECTOR XMPlaneNormalize(FXMVECTOR P)

• 面的生成

  XMVECTOR XMPlaneFromPointNormal(FXMVECTOR Point, FXMVECTOR Normal)

  XMVECTOR XMPlaneFromPoints(FXMVECTOR Point1, FXMVECTOR Point2, FXMVECTOR Point3)

• 求面与点的距离

  XMVECTOR XMPlaneDotCoord(FXMVECTOR P, FXMVECTOR V)

• 求面与向量的角度

  XMVECTOR XMPlaneDotNormal(FXMVECTOR P, FXMVECTOR V)

• 面的旋转

  XMVECTOR XMPlaneTransform(FXMVECTOR P, FXMMATRIX M)

常用的常量

• XM_PI π
• XM_2PI 2*π
• XM_1DIVPI 1/π
• XM_1DIV2PI 1/2π
• XMVECTORI32 g_XMFltMin
• XMVECTORI32 g_XMFltMax

引擎封装库

../flexi/math

其中部分为对XMMath数据向量的扩展接口，部分为封装集成特殊的用途对象，不在此介绍。