SimpleMath.h wraps the DirectXMath SIMD vector/matrix math API with an easier to use C++ interface. It provides the following types, with similar names, methods, and operator overloads to the XNA Game Studio math API:
If that sounds horribly confusing, the short version is that the SimpleMath types pretty much "Just Work" the way you would expect them to.
By now you must be wondering, where is the catch? And of course there is one. SimpleMath hides the complexities of SIMD programming by automatically converting back and forth between memory and SIMD register types, which tends to generate additional load and store instructions. This can add significant overhead compared to the lower level DirectXMath approach, where SIMD loads and stores are under explicit control of the programmer.
You should use SimpleMath if you are:
You should go straight to the underlying DirectXMath API if you:
This need not be a global either/or decision. The SimpleMath types know how to convert themselves to and from the corresponding DirectXMath types, so it is easy to mix and match. You can use SimpleMath for the parts of your program where readability and development time matter most, then drop down to DirectXMath for performance hotspots where runtime efficiency is more important.
If you want to use left-handed coordinates, use the DirectXMath methods directly. For example
With the methods Matrix::CreateBillboard and Matrix::CreateConstrainedBillboard the handedness is inherent in the default vectors for cameraForward, and objectForward which are right-handed. You can make them behave left-handed by providing appropriate vectors.
BasicMath.h also includes typedef aliases for these types to make them use the same naming as HLSL vector types, although the usage syntax and operations are quite different:
Note: The actual operations would look different than the way they would using BasicMath.
http://blogs.msdn.com/b/chuckw/archive/2012/09/11/directxmath-sse-sse2-and-arm-neon.aspx
http://blogs.msdn.com/b/chuckw/archive/2013/03/06/known-issues-directxmath-3-03.aspx
http://blogs.msdn.com/b/shawnhar/archive/2013/01/08/simplemath-a-simplified-wrapper-for-directxmath.aspx
- Vector2
- Vector3
- Vector4
- Matrix
- Quaternion
- Plane
- Ray
- Color
To use:
#include "SimpleMath.h"usingnamespace DirectX::SimpleMath;Why wrap DirectXMath?
DirectXMath provides highly optimized vector and matrix math functions, which take advantage of SSE SIMD intrinsics when compiled for x86/x64, or the ARM NEON instruction set when compiled for an ARM platform such as Windows RT or Windows Phone. The downside of being designed for efficient SIMD usage is that DirectXMath can be somewhat complicated to work with. Developers must be aware of correct type usage (understanding the difference between SIMD register types such as XMVECTOR vs. memory storage types such as XMFLOAT4), must take care to maintain correct alignment for SIMD heap allocations, and must carefully structure their code to avoid accessing individual components from a SIMD register. This complexity is necessary for optimal SIMD performance, but sometimes you just want to get stuff working without so much hassle!Enter SimpleMath...
These types derive from the equivalent DirectXMath memory storage types (for instance Vector3 is derived from XMFLOAT3), so they can be stored in arbitrary locations without worrying about SIMD alignment, and individual components can be accessed without bothering to call SIMD accessor functions. But unlike XMFLOAT3, the Vector3 type defines a rich set of methods and overloaded operators, so it can be directly manipulated without having to first load its value into an XMVECTOR. Vector3 also defines an operator for automatic conversion to XMVECTOR, so it can be passed directly to methods that were written to use the lower level DirectXMath types.If that sounds horribly confusing, the short version is that the SimpleMath types pretty much "Just Work" the way you would expect them to.
By now you must be wondering, where is the catch? And of course there is one. SimpleMath hides the complexities of SIMD programming by automatically converting back and forth between memory and SIMD register types, which tends to generate additional load and store instructions. This can add significant overhead compared to the lower level DirectXMath approach, where SIMD loads and stores are under explicit control of the programmer.
You should use SimpleMath if you are:
- Looking for a C++ math library with similar API to the C# XNA types
- Porting existing XNA code from C# to C++
- Wanting to optimize for programmer efficiency (simplicity, readability, development speed) at the expense of runtime efficiency
You should go straight to the underlying DirectXMath API if you:
- Want to create the fastest possible code
- Enjoy the lateral thinking needed to express algorithms in raw SIMD
This need not be a global either/or decision. The SimpleMath types know how to convert themselves to and from the corresponding DirectXMath types, so it is easy to mix and match. You can use SimpleMath for the parts of your program where readability and development time matter most, then drop down to DirectXMath for performance hotspots where runtime efficiency is more important.
Coordinate Systems
Because SimpleMath Is intended to look a lot like like XNA Game Studio's math library, it uses right-handed coordinates by convention for the following Matrix methods:- CreatePerspectiveFieldOfView
- CreatePerspective
- CreatePerspectiveOffCenter
- CreateOrthographic
- CreateOrthographicOffCenter
- CreateLookAt
If you want to use left-handed coordinates, use the DirectXMath methods directly. For example
// Here's a RH example Vector3 eye, target, up; ... Matrix mView = Matrix::CreateLookAt( eye, target, up ); // Here' is a LH example of same thing which relies on// Vector3 and Matrix conversion operators Vector3 eye, target, up; ... Matrix mView = XMMatrixLookAtLH( eye, target, up );
With the methods Matrix::CreateBillboard and Matrix::CreateConstrainedBillboard the handedness is inherent in the default vectors for cameraForward, and objectForward which are right-handed. You can make them behave left-handed by providing appropriate vectors.
Vector3 objectPosition, cameraPosition, rotateAxis; Matrix mView = Matrix::CreateBillboard( objectPosition, cameraPosition, Vector3::Up, Vector3::Backward ); Matrix mView = Matrix::CreateConstrainedBillboard( objectPosition, cameraPosition, rotateAxis, Vector3::Backward, Vector3::Backward );
Windows Store apps
A number of Windows Store samples include a "BasicMath.h" header that includes some very simplistic math types:- Vector2
- Vector3
- Vector4
- Matrix4x4
BasicMath.h also includes typedef aliases for these types to make them use the same naming as HLSL vector types, although the usage syntax and operations are quite different:
- float2
- float3
- float4
- float4x4
#include "SimpleMath.h"typedef DirectX::SimpleMath::Vector2 float2; typedef DirectX::SimpleMath::Vector3 float3; typedef DirectX::SimpleMath::Vector4 float4; typedef DirectX::SimpleMath::Matrix float4x4;
Note: The actual operations would look different than the way they would using BasicMath.
Further Reading
http://blogs.msdn.com/b/chuckw/archive/2012/03/27/introducing-directxmath.aspxhttp://blogs.msdn.com/b/chuckw/archive/2012/09/11/directxmath-sse-sse2-and-arm-neon.aspx
http://blogs.msdn.com/b/chuckw/archive/2013/03/06/known-issues-directxmath-3-03.aspx
http://blogs.msdn.com/b/shawnhar/archive/2013/01/08/simplemath-a-simplified-wrapper-for-directxmath.aspx