diff --git a/Home.md b/Home.md index da265fb..51dae16 100644 --- a/Home.md +++ b/Home.md @@ -1,95 +1,97 @@ -http://go.microsoft.com/fwlink/?LinkID=615560 - -![DirectX Logo](https://github.com/Microsoft/DirectXMath/wiki/X_jpg.jpg)DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps. - -See [this post](https://blogs.msdn.microsoft.com/chuckw/2012/03/26/introducing-directxmath/). - -# Documentation -The DirectXMath library is documented [here](https://docs.microsoft.com/en-us/windows/desktop/dxmath/directxmath-portal). - -# Windows SDK - -The DirectXMath library is included in the Windows SDK starting with version 8.0. Therefore it is included with Visual C++ 2012, 2013, 2015, and 2017. For a full list versions, see [releases](https://github.com/Microsoft/DirectXMath/releases). - -# Instruction set -For x86/x64, DirectXMath makes use of SSE/SSE2 intrinsics. All x64 native CPUs are required to support SSE and SSE2. Windows 8.0 (32-bit) or later will not install without SSE/SSE2 support. - -For ARM, DirectXMath makes use of ARMv7 ARM-NEON intrinsics. All Windows on ARM devices support ARM-NEON and VFPv3. - -For ARM64, DirectXMath makes use of ARMv8 ARM-NEON intrinsics. ARM-NEON and VFPv4 support is required for the ARM 64 architecture. - -See [this post](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-sse-sse2-and-arm-neon/) for full details. - -> Using ``_XM_NO_INTRINSICS_`` results in only C/C++ codepaths which should work on any architecture, but the library is not optimized for this case. - -## Architecture switch - -If you build with ``/arch:AVX`` so that your binary requires Intel [Advanced Vector Extensions](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions), DirectXMath 3.09 or later will make use of SSE3, SSE4.1, and AVX instructions. - -> The primary benefit of building with ``/arch:AVX`` is the use of the [VEX prefix](https://en.wikipedia.org/wiki/VEX_prefix) in all generated SSE instructions. - -If you build with ``/arch:AVX2`` so that your binary requires Intel Advanced Vector Extensions 2, DirectXMath 3.09 or later will make use of SSE3, SSE4.1, AVX, and F16C instructions. - -> The compiler should make use of ``FMA3`` as appropriate when building with ``/arch:AVX2`` even without explicit use of the ``_mm_f*add_ps`` intrinsic. In DirectXMath 3.10 or later, ``XMVerifyCPUSupport`` will check for AVX2 and FMA3 instruction support when building with ``/arch:AVX2``. - -# Windows XP -The DirectXMath library is all inline and uses only Visual C++ intrinsics. Therefore, it is compatible with all version of Windows supported by Visual C++. There's no standard configuration that will put DirectXMath in the include path when using the ``v1x0_xp`` Platform Toolset, but you can add it manually or make use of the [NuGet](https://www.nuget.org/packages/directxmath) package. Keep in mind there are a number of other differences when doing DirectX development for Windows XP support. See [this post](https://blogs.msdn.microsoft.com/chuckw/2012/11/26/visual-studio-2012-update-1/). - -# Migrating code - -Details on moving from XNAMath to DirectXMath are covered in [MSDN: Code Migration from the XNA Math Library](https://msdn.microsoft.com/en-us/library/windows/desktop/ee418730.aspx). - -Moving from the legacy D3DX9/D3DX10 D3DXMath is covered in [MSDN: Working with D3DXMath](https://msdn.microsoft.com/en-us/library/windows/desktop/ff729728.aspx). - -# Calling convention - -Be sure to read the [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ee418728.aspx#Call_Conventions) details on the calling convention types which are designed to deal with the various architectures and vector calling conventions. The best way to ensure you have them correct is to attempt to build your code with x86, x64, and ARM. - -If writing client code that is intended to build with both DirectXMath 3.06+ (Windows 8.1 SDK / VS 2013) and DirectXMath 3.03 (Windows 8 XDK / VS 2012), the following adapter code can be used: - - #include - namespace DirectX - { - #if (DIRECTX_MATH_VERSION < 305) && !defined(XM_CALLCONV) - #define XM_CALLCONV __fastcall - typedef const XMVECTOR& HXMVECTOR; - typedef const XMMATRIX& FXMMATRIX; - #endif - } - -# Language extensions -DirectXMath is written using standard Intel-style intrinsics, which should be portable to other compilers. The ARM codepaths use ARM-style intrinsics (earlier versions of the library used Visual C++ specific ``__n64`` and ``__n128``), so these should also be portable. - -The DirectXMath library make use of two commonly implemented extensions to Standard C++: - -* **anonymous structs**, which are widely supported and are part of the C11 standard. Note that the library also uses [anonymous unions](https://en.wikipedia.org/wiki/Union_type#Anonymous_union), but these are part of the C++ and C99 standard. -* **#pragma once** rather than old-style #define based guards, but are [widely supported](https://en.m.wikipedia.org/wiki/Pragma_once) - -> Because of these, DirectXMath is not compatible with Visual C++'s ``/Za`` switch which enforces ISO C89 / C++11. It does work with ``/permissive-``. - -# Additional content - -[[Extensions]] - Advanced instruction set variants for DirectXMath -[[SHMath]] - Spherical Harmonics math -[[XDSP]] - Digital Signal Processing helper functions -[[Stereo3D]] - Stereo 3D matrix helper functions - -[[Resources]] - -# Related -See the _DirectX Tool Kit_'s [SimpleMath](https://github.com/Microsoft/DirectXTK/wiki/SimpleMath) wrapper for DirectXMath. - -# Credits - -The xboxmath library was originated by Matt Bronder with contributions from Sakphong Chanbai and David Hefner for the Xbox 360. - -The xnamath library for the DirectX SDK and Xbox XDK was the work of Chuck Walbourn and Becky Heineman based on xboxmath, with contributions from Jeremy Gup, Dan Haffner, Matt Lee, Casey Meekhof, Rich Sauer, Jason Strayer, and Xiaoyue Zheng. - -The DirectXMath library for the Windows SDK and Xbox One XDK is the work of Chuck Walbourn based on xnamath, with contributions from Darren Anderson, Matt Lee, Aaron Rodriguez Hernandez, Yuichi Ito, Reza Nourai, Rich Sauer, and Jason Strayer. - -Thanks to Dave Eberly for his contributions particularly in improving the transcendental functions. - -Thanks to Bruce Dawson for his help with the rounding functions. - -Special thanks to Andy Glaister and Shawn Hargreaves for their on-going support and sponsorship. - +http://go.microsoft.com/fwlink/?LinkID=615560 + +![DirectX Logo](https://github.com/Microsoft/DirectXMath/wiki/X_jpg.jpg)DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps. + +See [this post](https://aka.ms/Kjp2dz). + +# Documentation +The DirectXMath library is documented [here](https://docs.microsoft.com/en-us/windows/desktop/dxmath/directxmath-portal). + +# Windows SDK + +The DirectXMath library is included in the Windows SDK starting with version 8.0. Therefore it is included with Visual C++ 2012, 2013, 2015, and 2017. For a full list versions, see [releases](https://github.com/Microsoft/DirectXMath/releases). + +# Instruction set +For x86/x64, DirectXMath makes use of SSE/SSE2 intrinsics. All x64 native CPUs are required to support SSE and SSE2. Windows 8.0 (32-bit) or later will not install without SSE/SSE2 support. + +For ARM, DirectXMath makes use of ARMv7 ARM-NEON intrinsics. All Windows on ARM devices support ARM-NEON and VFPv3. + +For ARM64, DirectXMath makes use of ARMv8 ARM-NEON intrinsics. ARM-NEON and VFPv4 support is required for the ARM 64 architecture. + +See [this post](https://walbourn.github.io/directxmath-sse-sse2-and-arm-neon/) for full details. + +> Using ``_XM_NO_INTRINSICS_`` results in only C/C++ codepaths which should work on any architecture, but the library is not optimized for this case. + +## Architecture switch + +If you build with ``/arch:AVX`` so that your binary requires Intel [Advanced Vector Extensions](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions), DirectXMath 3.09 or later will make use of SSE3, SSE4.1, and AVX instructions. + +> The primary benefit of building with ``/arch:AVX`` is the use of the [VEX prefix](https://en.wikipedia.org/wiki/VEX_prefix) in all generated SSE instructions. + +If you build with ``/arch:AVX2`` so that your binary requires Intel Advanced Vector Extensions 2, DirectXMath 3.09 or later will make use of SSE3, SSE4.1, AVX, and F16C instructions. + +> The compiler should make use of ``FMA3`` as appropriate when building with ``/arch:AVX2`` even without explicit use of the ``_mm_f*add_ps`` intrinsic. In DirectXMath 3.10 or later, ``XMVerifyCPUSupport`` will check for AVX2 and FMA3 instruction support when building with ``/arch:AVX2``. + +# Windows XP +The DirectXMath library is all inline and uses only Visual C++ intrinsics. Therefore, it is compatible with all version of Windows supported by Visual C++. There's no standard configuration that will put DirectXMath in the include path when using the ``v1x0_xp`` Platform Toolset, but you can add it manually or make use of the [NuGet](https://www.nuget.org/packages/directxmath) package. Keep in mind there are a number of other differences when doing DirectX development for Windows XP support. See [this post](https://walbourn.github.io/visual-studio-2012-update-1/). + +# Migrating code + +Details on moving from XNAMath to DirectXMath are covered in [Code Migration from the XNA Math Library](https://docs.microsoft.com/en-us/windows/desktop/dxmath/pg-xnamath-migration). + +Moving from the legacy D3DX9/D3DX10 D3DXMath is covered in [Working with D3DXMath](https://docs.microsoft.com/en-us/windows/desktop/dxmath/pg-xnamath-migration-d3dx). + +# Calling convention + +Be sure to read the [Microsoft Docs](https://docs.microsoft.com/en-us/windows/desktop/dxmath/pg-xnamath-internals#Call_Conventions) details on the calling convention types which are designed to deal with the various architectures and vector calling conventions. The best way to ensure you have them correct is to attempt to build your code with x86, x64, and ARM. + +If writing client code that is intended to build with both DirectXMath 3.06+ (Windows 8.1 SDK / VS 2013) and DirectXMath 3.03 (Windows 8 XDK / VS 2012), the following adapter code can be used: + +```cpp +#include +namespace DirectX +{ + #if (DIRECTX_MATH_VERSION < 305) && !defined(XM_CALLCONV) + #define XM_CALLCONV __fastcall + typedef const XMVECTOR& HXMVECTOR; + typedef const XMMATRIX& FXMMATRIX; + #endif +} +``` + +# Language extensions +DirectXMath is written using standard Intel-style intrinsics, which should be portable to other compilers. The ARM codepaths use ARM-style intrinsics (earlier versions of the library used Visual C++ specific ``__n64`` and ``__n128``), so these should also be portable. + +The DirectXMath library make use of two commonly implemented extensions to Standard C++: + +* **anonymous structs**, which are widely supported and are part of the C11 standard. Note that the library also uses [anonymous unions](https://en.wikipedia.org/wiki/Union_type#Anonymous_union), but these are part of the C++ and C99 standard. +* **#pragma once** rather than old-style #define based guards, but are [widely supported](https://en.m.wikipedia.org/wiki/Pragma_once) + +> Because of these, DirectXMath is not compatible with Visual C++'s ``/Za`` switch which enforces ISO C89 / C++11. It does work with ``/permissive-``. + +# Additional content + +[[Extensions]] - Advanced instruction set variants for DirectXMath +[[SHMath]] - Spherical Harmonics math +[[XDSP]] - Digital Signal Processing helper functions +[[Stereo3D]] - Stereo 3D matrix helper functions + +[[Resources]] + +# Related +See the _DirectX Tool Kit_'s [SimpleMath](https://github.com/Microsoft/DirectXTK/wiki/SimpleMath) wrapper for DirectXMath. + +# Credits + +The xboxmath library was originated by Matt Bronder with contributions from Sakphong Chanbai and David Hefner for the Xbox 360. + +The xnamath library for the DirectX SDK and Xbox XDK was the work of Chuck Walbourn and Becky Heineman based on xboxmath, with contributions from Jeremy Gup, Dan Haffner, Matt Lee, Casey Meekhof, Rich Sauer, Jason Strayer, and Xiaoyue Zheng. + +The DirectXMath library for the Windows SDK and Xbox One XDK is the work of Chuck Walbourn based on xnamath, with contributions from Darren Anderson, Matt Lee, Aaron Rodriguez Hernandez, Yuichi Ito, Reza Nourai, Rich Sauer, and Jason Strayer. + +Thanks to Dave Eberly for his contributions particularly in improving the transcendental functions. + +Thanks to Bruce Dawson for his help with the rounding functions. + +Special thanks to Andy Glaister and Shawn Hargreaves for their on-going support and sponsorship. + diff --git a/Resources.md b/Resources.md index 9ce9437..58fa284 100644 --- a/Resources.md +++ b/Resources.md @@ -1,54 +1,56 @@ # DirectX SDK and Games for Windows Blog -[Introducing DirectXMath](https://blogs.msdn.microsoft.com/chuckw/2012/03/26/introducing-directxmath/) +[Introducing DirectXMath](https://aka.ms/Kjp2dz) -[Known Issues: DirectXMath 3.03](https://blogs.msdn.microsoft.com/chuckw/2013/03/05/known-issues-directxmath-3-03/) +[Known Issues: DirectXMath 3.03](https://walbourn.github.io/known-issues-directxmath-3-03/) -[DirectXMath 3.06](https://blogs.msdn.microsoft.com/chuckw/2013/10/24/directxmath-3-06/) +[DirectXMath 3.06](https://walbourn.github.io/directxmath-3-06/) -[Known Issues: DirectXMath 3.06](https://blogs.msdn.microsoft.com/chuckw/2014/12/12/known-issues-directxmath-3-06/) +[Known Issues: DirectXMath 3.06](https://walbourn.github.io/known-issues-directxmath-3-06/) -[DirectXMath 3.07](https://blogs.msdn.microsoft.com/chuckw/2015/04/29/directxmath-3-07/) +[DirectXMath 3.07](https://walbourn.github.io/directxmath-3-07/) -[DirectXMath 3.08](https://blogs.msdn.microsoft.com/chuckw/2015/12/01/directxmath-3-08/) +[DirectXMath 3.08](https://walbourn.github.io/directxmath-3-08/) -[DirectXMath 3.09](https://blogs.msdn.microsoft.com/chuckw/2016/08/02/directxmath-3-09/) +[DirectXMath 3.09](https://walbourn.github.io/directxmath-3-09/) -[DirectXMath 3.10](https://blogs.msdn.microsoft.com/chuckw/2017/04/06/directxmath-3-10/) +[DirectXMath 3.10](https://walbourn.github.io/directxmath-3-10/) -[DirectXMath 3.11](https://blogs.msdn.microsoft.com/chuckw/2017/06/28/directxmath-3-11/) +[DirectXMath 3.11](https://walbourn.github.io/directxmath-3-11/) + +[DirectXMath 3.13](https://walbourn.github.io/directxmath-3-13/) ## Processors and instruction sets -[DirectXMath: SSE, SSE2, and ARM-NEON](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-sse-sse2-and-arm-neon/) +[DirectXMath: SSE, SSE2, and ARM-NEON](https://walbourn.github.io/directxmath-sse-sse2-and-arm-neon/) -[DirectXMath: SSE3 and SSSE3](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-sse3-and-ssse3/) +[DirectXMath: SSE3 and SSSE3](https://walbourn.github.io/directxmath-sse3-and-ssse3/) -[DirectXMath: SSE4.1 and SSE4.2](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-sse4-1-and-sse4-2/) +[DirectXMath: SSE4.1 and SSE4.2](https://walbourn.github.io/directxmath-sse4-1-and-sse4-2/) -[DirectXMath: AVX](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-avx/) +[DirectXMath: AVX](https://walbourn.github.io/directxmath-avx/) -[DirectXMath: F16C and FMA](https://blogs.msdn.microsoft.com/chuckw/2012/09/11/directxmath-f16c-and-fma/) +[DirectXMath: F16C and FMA](https://walbourn.github.io/directxmath-f16c-and-fma/) -[DirectXMath: AVX2](https://blogs.msdn.microsoft.com/chuckw/2015/06/03/directxmath-avx2/) +[DirectXMath: AVX2](https://walbourn.github.io/directxmath-avx2/) ## DirectXMath-based helpers -[Spherical Harmonics Math](https://blogs.msdn.microsoft.com/chuckw/2012/07/28/spherical-harmonics-math/) +[Spherical Harmonics Math](https://walbourn.github.io/spherical-harmonics-math/) -[XDSP.H: Digital Signal Processing helper functions](https://blogs.msdn.microsoft.com/chuckw/2012/04/30/xdsp-h-digital-signal-processing-helper-functions/) +[XDSP.H: Digital Signal Processing helper functions](https://walbourn.github.io/xdsp-h-digital-signal-processing-helper-functions/) ## XNAMath (aka xboxmath 2.0) -[XNA Math Version 2.05: Smoothing the transition to DirectXMath](https://blogs.msdn.microsoft.com/chuckw/2012/06/22/xna-math-version-2-05-smoothing-the-transition-to-directxmath/) +[XNA Math Version 2.05: Smoothing the transition to DirectXMath](https://walbourn.github.io/xna-math-version-2-05-smoothing-the-transition-to-directxmath/) -[XNA Math Version 2.04](https://blogs.msdn.microsoft.com/chuckw/2011/02/22/xna-math-version-2-04/) +[XNA Math Version 2.04](https://walbourn.github.io/xna-math-version-2-04/) -[Known Issues in XNAMath v2.03](https://blogs.msdn.microsoft.com/chuckw/2011/01/20/known-issues-in-xnamath-v2-03/) +[Known Issues in XNAMath v2.03](https://walbourn.github.io/known-issues-in-xnamath-v2-03/) -[A little love for XNAMath…](https://blogs.msdn.microsoft.com/chuckw/2010/01/28/a-little-love-for-xnamath/) +[A little love for XNAMath…](https://walbourn.github.io/a-little-love-for-xnamath/) # Shawn Hargreaves' Blog -[SimpleMath – a simplified wrapper for DirectXMath](https://blogs.msdn.microsoft.com/shawnhar/2013/01/08/simplemath-a-simplified-wrapper-for-directxmath/) +[SimpleMath - a simplified wrapper for DirectXMath](http://www.shawnhargreaves.com/blog/simplemath-a-simplified-wrapper-for-directxmath.html) # Bruce Dawson's blog @@ -56,7 +58,7 @@ # Visual C++ Team Blog -[Introducing ‘Vector Calling Convention’](https://blogs.msdn.microsoft.com/vcblog/2013/07/11/introducing-vector-calling-convention/) +[Introducing 'Vector Calling Convention'](https://devblogs.microsoft.com/cppblog/introducing-vector-calling-convention/) # Conferences @@ -65,4 +67,3 @@ # Further reading [What Every Programmer Should Know About Floating-Point Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html) - diff --git a/XDSP.md b/XDSP.md index cb27b0c..14a7ad2 100644 --- a/XDSP.md +++ b/XDSP.md @@ -1,24 +1,24 @@ -This is an implementation of the legacy DirectX SDK utility header DSP math functions using DirectXMath. - -See [this blog post](https://blogs.msdn.microsoft.com/chuckw/2012/04/30/xdsp-h-digital-signal-processing-helper-functions/) for more details. - -# API -All functions are in the C++ namespace ``XDSP``. - -All memory buffers used with these functions must be 16-byte aligned. This happens by default for x64, but requires alignment or use of ``__aligned_malloc`` with x86 or ARM. - -* [[FFT]] - Fast Fourier Transform with an arbitrary number of samples. -* [[FFT4]] - Four sample Fast Fourier Transform. -* [[FFT8]] - Eight sample Fast Fourier Transform. -* [[FFT16]] - Sixteen sample Fast Fourier Transform. -* [[FFTInitializeUnityTable]] - Initializes unity roots lookup table used by Fast Fourier Transform functions (``FFT``, ``FFTDeinterleaved``, and ``FFTInterleaved``) - -* [[FFTPolar]] - Converts complex components to polar form. -* [[FFTUnswizzle]] - Arranges Fast Fourier Transform function output by order of increasing frequency. - -* [[Interleave]] - Interleaves audio samples. -* [[Deinterleave]] - Deinterleaves audio samples. - -* [[FFTInterleaved]] - Fast Fourier Transform, plus deinterleaves multichannel audio before processing. -* [[IFFTDeinterleaved]] - Fast Fourier Transform, plus interleaved multichannel audio. - +This is an implementation of the legacy DirectX SDK utility header DSP math functions using DirectXMath. + +See [this blog post](https://walbourn.github.io/xdsp-h-digital-signal-processing-helper-functions/) for more details. + +# API +All functions are in the C++ namespace ``XDSP``. + +All memory buffers used with these functions must be 16-byte aligned. This happens by default for x64, but requires alignment or use of ``__aligned_malloc`` with x86 or ARM. + +* [[FFT]] - Fast Fourier Transform with an arbitrary number of samples. +* [[FFT4]] - Four sample Fast Fourier Transform. +* [[FFT8]] - Eight sample Fast Fourier Transform. +* [[FFT16]] - Sixteen sample Fast Fourier Transform. +* [[FFTInitializeUnityTable]] - Initializes unity roots lookup table used by Fast Fourier Transform functions (``FFT``, ``FFTDeinterleaved``, and ``FFTInterleaved``) + +* [[FFTPolar]] - Converts complex components to polar form. +* [[FFTUnswizzle]] - Arranges Fast Fourier Transform function output by order of increasing frequency. + +* [[Interleave]] - Interleaves audio samples. +* [[Deinterleave]] - Deinterleaves audio samples. + +* [[FFTInterleaved]] - Fast Fourier Transform, plus deinterleaves multichannel audio before processing. +* [[IFFTDeinterleaved]] - Fast Fourier Transform, plus interleaved multichannel audio. +