Edit

Share via

Code Migration from the XNA Math Library

  • Article

This overview describes the changes required to migrate existing code using the XNA Math library to the DirectXMath library.

Header Changes

The DirectXMath library uses a new set of headers.

Replace the xnamath.h header with DirectXMath.h, and add DirectXPackedVector.h for the GPU packed types.

The bounding types from the DirectX SDK Collision sample in xnacollision.h is now part of the DirectXMath library in DirectXCollision.h. These have been modified to use C++ classes rather than a C-style API.

Constant Changes

XNAMATH_VERSION (200, 201, 202, 203, 204, and so on) has been replaced with DIRECXTMATH_VERSION (300, 301, 302, 303, and so on).

Note

DirectXMath 3.00 and 3.02 shipped with preliminary versions of the Windows SDK. DirectXMath 3.03 is in the final version of the Windows 8 SDK.

Namespaces

The DirectXMath library uses C++ namespaces to organize the types. XNA Math used only the global namespace. The DirectXMath types in common with XNA Math are in the DirectX or the DirectX::PackedVector namespace.

In C++ source files, a simple solution is to add using statements.

#include "DirectXMath.h"
#include "DirectXPackedVector.h"

using namespace DirectX; 
using namespace DirectX::PackedVector;

For headers, it is not considered best practice to add using statements. Instead, add fully-qualified namespaces.

struct mystruct
{
   DirectX::XMFLOAT3 position;
   DirectX::PackedVector::HALF packedValue;
};

Partial Loads

For various functions that load less than 4 elements of an XMVECTOR, the XNA Math library left the additional elements undefined. DirectXMath will always fill these additional elements with 0.

Removal of Xbox 360 Specific Types

The following XNA Math library types, functions, and constants are not available in DirectXMath.

  • HENDN3, XMHEND3, XMUHENDN3, XMUHEND3, XMDHENN3, XMDHEN3, XMUDHENN3, XMUDHEN3
  • XMLoadHenDN3(), XMLoadHenD3(), XMLoadUHenDN3(), XMLoadUHenD3(), XMLoadDHenN3(), XMLoadDHen3(), XMLoadUDHenN3(), XMLoadUDHen3()
  • XMStoreHenDN3(), XMStoreHenD3(), XMStoreUHenDN3(), XMStoreUHenD3(), XMStoreDHenN3(), XMStoreDHen3(), XMStoreUDHenN3(), XMStoreUDHen3()
  • g_XMMaskHenD3, g_XMMaskDHen3, g_XMAddUHenD3, g_XMAddHenD3, g_XMAddDHen, g_XMMulHenD3, g_XMMulDHen3, g_XMXorHenD3, g_XMXorDHen3
  • XMXICON4, XMXICO4, XMICON4, XMICO4, XMUICON4, XMUICO4
  • XMLoadXIcoN4(), XMLoadXIco4(), XMLoadIcoN4(), XMLoadIco4(), XMLoadUIcoN4(), XMLoadUIco4()
  • XMStoreXIcoN4(), XMStoreXIco4() ,XMStoreIcoN4(), XMStoreIco4(), XMStoreUIcoN4(), XMStoreUIco4()
  • g_XMMaskIco4, g_XMXorXIco4, g_XMXorIco4, g_XMAddXIco4, g_XMAddUIco4, g_XMAddIco4, g_XMMulIco4

__vector4i is deprecated. Use XMVECTORI32 or XMVECTORU32 instead.

The following functions and types are deprecated as they are Xbox 360 only: XMLoadDecN4, XMStoreDecN4, XMDECN4, XMLoadDec4, XMStoreDec4, XMDEC4, XMLoadXDec4, XMStoreXDec4, XMXDEC4.

ARM-NEON Intrinsics

Declaring a vector constant with this code will compile for XNA Math for SSE and NO-INTRINSICS, but will fail for DirectXMath using ARM-NEON.

XMVECTOR v = { 1.f, 2.f, 3.f, 4.f }

In general, we don't recommend this method of initialization of an XMVECTOR. However, if you want a vector constant, the XMVECTORF32 class supports this style of initialization and returns the XMVECTOR type automatically so you can use XMVECTORF32 in most of the same contexts. Any write operations to an XMVECTORF32 class require explicitly referencing the .v XMVECTOR member.

Permute

The XNA Math library had the following form for general vector permute:

XMVECTOR XMVectorPermuteControl(UINT ElementIndex0, UINT ElementIndex1, UINT ElementIndex2, UINT ElementIndex3);
XMVECTOR XMVectorPermute(FXMVECTOR V1, FXMVECTOR V2, FXMVECTOR Control);

For DirectXMath, XMVectorPermuteControl has been eliminated and the XM_PERMUTE_0X .. XM_PERMUTE_1Z constants have been redefined to be simple 0-7 indices. Here is the new signature for XMVectorPermute:

XMVECTOR XMVectorPermute(FXMVECTOR V1, FXMVECTOR V2, uint32_t PermuteX, uint32_t PermuteY, uint32_t PermuteZ, uint32_t PermuteW);

Instead of a control word, this function directly takes the 4 indices as parameters, which also makes it analogous to the XMVectorSwizzle function using the new XM_SWIZZLE_X .. XM_SWIZZLE_W constants defined as simple 0-3 indices.

XMVECTOR XMVectorSwizzle(FXMVECTOR V, uint32_t E0, uint32_t E1, uint32_t E2, uint32_t E3);

Note

For constant values, there is a much more efficient way to implement permute. Instead of using the function form of XMVectorPermute, use the template form:

template<uint32_t PermuteX, uint32_t PermuteY, uint32_t PermuteZ, uint32_t PermuteW>
    XMVECTOR XMVectorPermute(FXMVECTOR V1, FXMVECTOR V2)</code></pre></td>

Template Forms

In general, using a template form over a function form of the following functions is much more efficient and allows the library to do platform specific optimizations through template specialization.

template<uint32_t PermuteX, uint32_t PermuteY, uint32_t PermuteZ, uint32_t PermuteW>
    XMVECTOR XMVectorPermute(FXMVECTOR V1, FXMVECTOR V2)

template<uint32_t SwizzleX, uint32_t SwizzleY, uint32_t SwizzleZ, uint32_t SwizzleW>
    XMVECTOR XMVectorSwizzle(FXMVECTOR V)

template<uint32_t Elements>
    XMVECTOR XMVectorShiftLeft(FXMVECTOR V1, FXMVECTOR V2)

template<uint32_t Elements>
    XMVECTOR XMVectorRotateLeft(FXMVECTOR V)

template<uint32_t Elements>
    XMVECTOR XMVectorRotateRight(FXMVECTOR V)

template<uint32_t VSLeftRotateElements, uint32_t Select0, uint32_t Select1, uint32_t Select2, uint32_t Select3>
    XMVECTOR XMVectorInsert(FXMVECTOR VD, FXMVECTOR VS)</code></pre></td>

Eliminated Functions

Eliminated Function Replacement
XMStoreFloat3x3NC XMStoreFloat3x3
XMStoreFloat4NC XMStoreFloat4
XMStoreFloat4x3NC XMStoreFloat4x3
XMStoreFloat4x4NC XMStoreFloat4x4
XMStoreInt4NC XMStoreInt4
XMVector2InBoundsR XMVector2InBounds ? XM_CRMASK_CR6BOUNDS : 0
XMVector2TransformStreamNC XMVector2TransformStream
XMVector3InBoundsR XMVector3InBounds ? XM_CRMASK_CR6BOUNDS : 0
XMVector3TransformStreamNC XMVector3TransformStream
XMVector4InBoundsR XMVector4InBounds ? XM_CRMASK_CR6BOUNDS : 0
XMVectorCosHEst XMVectorCosH
XMVectorExpEst XMVectorExp
XMVectorLogEst XMVectorLog
XMVectorPowEst XMVectorPow
XMVectorSinHEst XMVectorSinH
XMVectorTanHEst XMVectorTanH

DirectXMath Programming Guide