DirectXMath

These are the Xbox One-specific aspects of Direct3D 11.

The DirectXMath implementation on the Xbox One hardware has been improved to take advantage of SSE 3, SSE 4.1, AVX, and F16C/CVT16 instructions as well as SSE/SSE2.

Developers should also use the /arch:AVX switch to improve DirectXMath code on the Xbox One hardware.

There are several compiler directives that are focused on Xbox One. See DirectXMath Library Compiler Directives.

For Programming Guide documentation, see DirectXMath documentation at MSDN.

Calling Convention

DirectXMath for Xbox One supports the __vectorcall calling convention, which is an alternative to the standard x64 native __fastcall. This calling convention can pass up to six float, double, __m128, or __m256 values in SIMD registers. It can also pass Heterogeneous Vector Aggregates (HVA; also known as XMMATRIX) in SIMD registers, given sufficient room.

To support this new calling convention, DirectXMath for Xbox One adds XM_CALLCONV, the HXMVECTOR type alias, and the FXMMATRIX type alias.

The FXMVECTOR, GXMVECTOR, HXMVECTOR, and CXMVECTOR aliases are used as follows:

Use the FXMVECTOR alias to pass up to the first three instances of XMVECTOR used as arguments to a function.
Use the GXMVECTOR alias to pass the 4th instance of an XMVECTOR used as an argument to a function.
Use the HXMVECTOR alias to pass the 5th and 6th instance of an XMVECTOR used as an argument to a function. There are some additional considerations as well; see the __vectorcall documentation for details.
Use the CXMVECTOR alias to pass any further instances of XMVECTOR used as arguments.

Note For output parameters, always use XMVECTOR* or XMVECTOR& and ignore them with respect to the preceding rules for input parameters.

Due to limitations of __vectorcall, you should not make use of GXMVECTOR or HXMVECTOR for C++ constructors. Just use FXMVECTOR for the first three XMVECTOR values, then CXMVECTOR for the rest.

The FXMMATRIX and CXMMATRIX aliases help support taking advantage of the HVA argument passing with __vectorcall.

Use FXMMATRIX alias to pass the first XMMATRIX as an argument to the function, assuming you do not have more than two FXMVECTOR arguments; or more than two float, double, or FXMVECTOR arguments to the ‘right’ of the matrix. There are some additional considerations as well; see the __vectorcall documentation for details.
Use CXMMATRIX otherwise.

Due to the limitations of _vectorcall, never use FXMMATRIX for C++ constructors. Just use CXMMATRIX.

In addition to the type aliases, you must also use the XM_CALLCONV annotation to ensure the function is using the appropriate calling convention (__fastcall vs. __vectorcall) based on your compiler and architecture. Due to the limitations of __vectorcall, do not use XM_CALLCONV for C++ constructors.

The following are example declarations that illustrate this convention:

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

XMMATRIX XM_CALLCONV XMMatrixTransformation2D(FXMVECTOR ScalingOrigin,
                                              float ScalingOrientation,
                                              FXMVECTOR Scaling,
                                              FXMVECTOR RotationOrigin,
                                              float Rotation,
                                              GXMVECTOR Translation);

void XM_CALLCONV XMVectorSinCos(XMVECTOR* pSin, XMVECTOR* pCos, FXMVECTOR V);

XMVECTOR XM_CALLCONV XMVectorHermiteV(FXMVECTOR Position0,
                                      FXMVECTOR Tangent0,
                                      FXMVECTOR Position1,
                                      GXMVECTOR Tangent1,
                                      HCXMVECTOR T);

XMMATRIX(FXMVECTOR R0, FXMVECTOR R1, FXMVECTOR R2, CXMVECTOR R3);

XMVECTOR XM_CALLCONV XMVector2Transform(FXMVECTOR V, FXMMATRIX M);

XMMATRIX XM_CALLCONV XMMatrixMultiplyTranspose(FXMMATRIX M1, CXMMATRIX M2);

For more information on __vectorcall, see the white paper:

Code Generation for Xbox One: Best Practices (Developer Education Materials > All NDA Whitepapers)

Version History

The Windows 8.0 SDK and VS 2012 shipped with DirectXMath 3.03.

DirectXMath for Xbox One contains a number of differences from the Windows version, including support for SSE3, SSE4.1, AVX, and F16C/CVT16 instructions. Additional differences include the following:

DirectXMath 3.04

XMVectorExp2, XMVectorLog2, XMVectorExpE, and XMVectorLogE functions were added, to provide base-e support in addition to the existing base-2 support.
XMVectorExp and XMVectorLog are now aliases for XMVectorExp2 and XMVectorLog2.
Additional optimizations for Stream functions.
XMConvertHalfToFloat and XMConvertFloatToHalf now use IEEE 754 standard float16 behavior for INF/QNAN.
Updated matrix version Transform for BoundingOrientedBox and Transform for BoundingFrustum to handle scaling.

DirectXMath 3.05

Use x86/x64 __vectorcall calling-convention when available (XM_CALLCONV, HXMVECTOR, FXMMATRIX introduced).
Fixed bug with XMVectorFloor and XMVectorCeiling when given whole odd numbers (such as 105.0).
Improved XMVectorRound algorithm.
Fixed potential warning, “C4723 using operator/ or operator/=”.

DirectXMath 3.06

Fixed load and store of XMFLOAT3SE to properly match the DXGI_FORMAT_R9G9B9E5_SHAREDEXP format.
Added XMLoadUDecN4_XR and XMStoreUDecN4_XR to match the DXGI_FORMAT_R10G10B10_XR_BIAS_A2_UNORM format.
Added XMColorRGBToSRGB and XMColorSRGBToRGB to convert linear RGB to and from sRGB.