Skip to main content

Programming Guide for Math Library

Overview​

Flexi Engine supports Microsoft DirectXMath, which provides SIMD-friendly C++ types and functions for commonly used linear algebra and graphics math operations. This document describes some common DirectXMath data structures and functions in the Flexi Engine.

For detailed documentation on DirectXMath, please refer to the official Microsoft documentation at https://learn.microsoft.com/en-us/windows/win32/dxmath/directxmath-portal

Library Directory and Included Headers​

Engine Math Library Headers: ... /visual/dx_math.h

Third-party Library Directory for DirectXMath: ... /extern/math/dxmath

Note: The interfaces in the library are all inline and contain only ... /visual/dx_math.h header files, no other files or libraries are included.

Common Structures​

  • Floating-point Vectors:

    Two-dimensional vector: XMFLOAT2

    Three-dimensional vector: XMFLOAT3

    Four-dimensional vector: XMFLOAT4

  • Integer Vectors:

    Two-dimensional vector: XMINT2

    Three-dimensional vector: XMINT3

  • Matrices:

    XMFLOAT4X4

    XMFLOAT4X3

    XMFLOAT3X4

    XMFLOAT3X3

  • How to Use:

    Same as common C-Structures, member variables, global variables, heap variables, and stack variables are all available. But these structures cannot be directly involved in any calculation of math libraries, and there are few interfaces in DirectXMath to manipulate these structures directly either.

  • Note: Only a few commonly used structures are listed here, not for all.

Structures supporting SIMD-Accelerated Type​

  • Vectors

    Basic Type:

    XMVECTOR

    Aliases:

    CXMVECTOR

    FXMVECTOR

    GXMVECTOR

    Please refer to DirectXMath.h for more details.

    All data vectors (two-dimensional, three-dimensional, four-dimensional floating-point and integer vectors, etc.) need to be converted to XMVECTOR before using DirectXMath for calculations.

  • Matrices:

    Basic Type:

    XMMATRIX

    Aliases:

    CXMMATRIX

    FXMMATRIX

    XMVECTORI32

    Please refer to the Math Library DirectXMath.h file for more details.

    All data matrices (4X4, 4X3, 3X4, 3X3 matrices, etc.) need to be converted to XMVECTOR before using DirectXMath for calculations.

  • How to Use:

    Mainly used for data computing and processing, generally created by loading from data objects, then participating in computing and data caching, since its memory requires byte alignment and other special demands, usually only used for stack variables, not for member variables or heap variables. The16-byte aligned memory block can be applied if necessary in the development process.

    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);

Basic Interfaces​

Note: The following default vector designates XMVECTOR, matrix refers to MATRIX, and [n] represents the vector dimensions, the default value is 4. Only the most commonly used interfaces are listed below for explanation and usage.

Vectors​

  • Converting Data Vector to 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)

    For example：

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

  • Converting XMVECTOR to Data Vectors

    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)

    For example：

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

  • Getting the Component of the Vectors

    float XMVectorGetX(FXMVECTOR V)

    float XMVectorGetY(FXMVECTOR V)

    float XMVectorGetZ(FXMVECTOR V)

    float XMVectorGetW(FXMVECTOR V)

  • Changing the Component of the Vectors

    XMVECTOR XMVectorSetX(FXMVECTOR V, float x)

    XMVECTOR XMVectorSetY(FXMVECTOR V, float x)

    XMVECTOR XMVectorSetZ(FXMVECTOR V, float x)

    XMVECTOR XMVectorSetW(FXMVECTOR V, float x)

    Note: These changed interfaces returned new vectors, will not change the original vector of the input.

    For example:

    If you need to change the X Component of the V Vector to 1, the proper way to write it is as follows:

    V = XMVectorSetX(V, 1 .0F)；

  • Initializing Vectors

    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.

  • Four Operations of Vectors

    • Operator supported: +、-、、/、+=、-=、=、/=, etc

    • Support vectors and basic data, four operations

    • Four operations interfaces:

      XMVECTOR XMVectorAdd(FXMVECTOR V1, FXMVECTOR V2)

      XMVECTOR XMVectorSum(FXMVECTOR V1, FXMVECTOR V2)

      XMVECTOR XMVectorMultiply(FXMVECTOR V1, FXMVECTOR V2)

      XMVECTOR XMVectorDivide(FXMVECTOR V1, FXMVECTOR V2)

  • Most Values of the Vectors

    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)

  • Absolute Value Vectors

    XMVECTOR XMVector[n]abs(FXMVECTOR V)

  • Comparison of Vectors

    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)

  • Vector Interval Limits

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

    XMVECTOR XMVector[n]Saturate(FXMVECTOR V)

  • Vector Linear Interpolations

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

  • Vector Dot Products

    XMVECTOR XMVector2Dot(FXMVECTOR V1, FXMVECTOR V2)

    XMVECTOR XMVector3Dot(FXMVECTOR V1, FXMVECTOR V2)

  • Vector Cross Products

    XMVECTOR XMVector2Cross(FXMVECTOR V1, FXMVECTOR V2)

    XMVECTOR XMVector3Cross(FXMVECTOR V1, FXMVECTOR V2)

  • Value of Vector Module/Length Square of the vectors' module/length

    XMVECTOR XMVector2LengthSq(FXMVECTOR V)

    XMVECTOR XMVector3LengthSq(FXMVECTOR V)

    Vector Module/Length

    XMVECTOR XMVector2Length(FXMVECTOR V)

    XMVECTOR XMVector3Length(FXMVECTOR V)

    Vector Estimated Module/Length

    XMVECTOR XMVector2LengthEst(FXMVECTOR V)

    XMVECTOR XMVector3LengthEst(FXMVECTOR V)

  • Vector Normalization

    XMVECTOR XMVector2Normalize(FXMVECTOR V)

    XMVECTOR XMVector3Normalize(FXMVECTOR V)

  • Computing Reflection Vector

    XMVECTOR XMVector3Reflect(FXMVECTOR Incident, FXMVECTOR Normal)

  • Vectors and Matrices

    • For coordinate transformation

      XMVECTOR XMVector3TransformCoord(FXMVECTOR V, FXMMATRIX M)

    • For vector (normal) transformation

      XMVECTOR XMVector3TransformNormal(FXMVECTOR V, FXMMATRIX M)

    • Keep homogeneous data transformation, if the result does not divide w is equal to XMVector3TransformNormal, if the result divides w is equal to XMVector3TransformCoordXMVECTOR XMVector3Transform

  • Vectors and Quaternions

    XMVECTOR XMVector3Rotate(FXMVECTOR V, FXMVECTOR RotationQuaternion)

Matrices​

  • Converting Data Matrices to XMMATRIX

    XMMATRIX XMLoadFloat4X4(const XMFLOAT4X4* pSource)

    XMMATRIX XMLoadFloat4X3(const XMFLOAT4X3* pSource)

    XMMATRIX XMLoadFloat3X4(const XMFLOAT3X4* pSource)

    XMMATRIX XMLoadFloat3X3(const XMFLOAT3X3* pSource)

    For example:

    XMMATRIX mtx = XMLoadFloat4X4(&m_mtxWorld);

  • Converting XMMATRIX to Data Matrices

    void XMStoreFloat4X4(XMFLOAT4X4* pDestination, FXMMATRIX M)

    void XMStoreFloat4X3(XMFLOAT4X3* pDestination, FXMMATRIX M)

    void XMStoreFloat3X4(XMFLOAT3X4* pDestination, FXMMATRIX M)

    void XMStoreFloat3X3(XMFLOAT3X3* pDestination, FXMMATRIX M)

    For example:

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

  • Identity Matrix

    XMMATRIX XMMatrixIsIdentity(FXMMATRIX M)

  • Inverse Matrix

    XMMATRIX XMMatrixInverse(XMVECTOR* pDeterminant, FXMMATRIX M)

  • Transposed Matrix

    XMMATRIX XMMatrixTranspose(FXMMATRIX M)

  • Translation Matrix

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

    XMMATRIX XMMatrixTranslationFromVector(FXMVECTOR Offset)

  • Scaling Matrix

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

    XMMATRIX XMMatrixScalingFromVector(FXMVECTOR Scale)

  • Rotation Matrix

    • Single-axis rotation around world coordinates, in radians

      XMMATRIX XMMatrixRotationX(float Angle)

      XMMATRIX XMMatrixRotationY(float Angle)

      XMMATRIX XMMatrixRotationZ(float Angle)

    • Euler angle rotation, in radians

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

      XMMATRIX XMMatrixRotationRollPitchYawFromVector(FXMVECTOR Angles)

    • Rotation around the given axis, in radians

      XMMATRIX XMMatrixRotationNormal(FXMVECTOR NormalAxis, float Angle)

      XMMATRIX XMMatrixRotationAxis(FXMVECTOR Axis, float Angle)

    • Converting Quaternion to Rotation Matrix

      XMMATRIX XMMatrixRotationQuaternion(FXMVECTOR Quaternion)

  • Translation, Scaling, Rotation Compound Matrix

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

  • Decomposition of the Compound Matrix

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

  • Viewport Matrix

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

  • Perspective Projection Matrix

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

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

  • Orthographic Projection Matrix

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

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

  • Matrix Multiply

    XMMATRIX XMMatrixMultiply(FXMMATRIX M1, CXMMATRIX M2)

  • Matrix Multiply Before Transposing

    XMMATRIX XMMatrixMultiplyTranspose(FXMMATRIX M1, CXMMATRIX M2)

Quaternions​

  • Comparison of Quaternions

    bool XMQuaternionEqual(FXMVECTOR Q1, FXMVECTOR Q2)

  • Quaternion Normalization

    XMVECTOR XMQuaternionNormalize(FXMVECTOR Q)

  • Quaternion Inversion

    XMVECTOR XMQuaternionInverse(FXMVECTOR Q)

  • Quaternion Generation

    • Identity Generation

      XMVECTOR XMQuaternionIdentity()

    • Generated from Euler angles

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

      XMVECTOR XMQuaternionRotationRollPitchYawFromVector(FXMVECTOR Angles)

    • Generated from axis and rotation angle

      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.

    • Generated from the Rotation Matrix

      XMQuaternionRotationMatrix(FXMMATRIX M)

  • Quaternion Multiply

    XMVECTOR XMQuaternionMultiply(FXMVECTOR Q1, FXMVECTOR Q2)

  • Quaternion Interpolation

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

  • Quaternion Decomposition

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

Plane​

  • Plane Normalization

    XMVECTOR XMPlaneNormalize(FXMVECTOR P)

  • Plane Generation

    XMVECTOR XMPlaneFromPointNormal(FXMVECTOR Point, FXMVECTOR Normal)

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

  • Distance from Plane to Point

    XMVECTOR XMPlaneDotCoord(FXMVECTOR P, FXMVECTOR V)

  • Angle of the Plane to the Vector

    XMVECTOR XMPlaneDotNormal(FXMVECTOR P, FXMVECTOR V)

  • Rotation of the Plane

    XMVECTOR XMPlaneTransform(FXMVECTOR P, FXMMATRIX M)

Common Constants​

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

Engine Encapsulation Library​

../flexi/math

Some of them are extended interfaces to XMMath data vectors, and others are encapsulated and integrated into objects for special purposes, which will not be presented here.