Update links

Chuck Walbourn 2022-04-26 16:45:12 -07:00
Родитель b828914aac
Коммит 26aed7744d
94 изменённых файлов: 292 добавлений и 294 удалений

@ -10,7 +10,7 @@ First create a new project using the instructions from the earlier lessons: [[Us
> If using *DirectX Tool Kit for DX12*, use [Using DeviceResources](https://github.com/microsoft/DirectXTK12/wiki/Using-DeviceResources) and [Adding the DirectX Tool Kit](https://github.com/microsoft/DirectXTK12/wiki/Adding-the-DirectX-Tool-Kit). In this case, the only thing to do in this lesson is adding ``#include <Audio.h>`` to **pch.h**.
# NuGet package manager
If you used [NuGet](https://docs.microsoft.com/en-us/nuget/what-is-nuget) when [[Adding the DirectX Tool Kit]], then you already have support for _DirectX Tool Kit for Audio._.
If you used [NuGet](https://docs.microsoft.com/nuget/what-is-nuget) when [[Adding the DirectX Tool Kit]], then you already have support for _DirectX Tool Kit for Audio._.
<table>
<tr>

@ -16,7 +16,7 @@ std::unique_ptr<AlphaTestEffect> effect;
effect = std::make_unique<AlphaTestEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
@ -31,10 +31,10 @@ This effect requires ``SV_Position`` and ``TEXCOORD0``. It also requires ``COLOR
* **SetTexture**: Associates a texture shader resource view with the effect. Can be set to nullptr to remove a reference.
* **SetAlphaFunction**: Sets the alpha comparison function. See [D3D11_COMPARISON_FUNC](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ne-d3d11-d3d11_comparison_func).
* **SetAlphaFunction**: Sets the alpha comparison function. See [D3D11_COMPARISON_FUNC](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_comparison_func).
* **SetReferenceAlpha**: Sets the alpha reference value for the test.
# Remarks
This effect is primarily used to implement techniques that relied on legacy [Direct3D 9 alpha testing](https://docs.microsoft.com/en-us/windows/win32/direct3d9/alpha-testing-state) render state. This effect is independent of the depth/stencil tests set in ``D3D11_DEPTH_STENCIL_DESC.DepthFunc`` and ``StencilFunc``.
This effect is primarily used to implement techniques that relied on legacy [Direct3D 9 alpha testing](https://docs.microsoft.com/windows/win32/direct3d9/alpha-testing-state) render state. This effect is independent of the depth/stencil tests set in ``D3D11_DEPTH_STENCIL_DESC.DepthFunc`` and ``StencilFunc``.

@ -1,4 +1,4 @@
This is an example of a C++ port of the C# [XNA Game Studio sample](https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb200104(v=xnagamestudio.41)) class for drawing an animated 2D sprite using [[SpriteBatch]]. The sprite animation is assumed to be laid out horizontally.
This is an example of a C++ port of the C# [XNA Game Studio sample](https://docs.microsoft.com/previous-versions/windows/xna/bb200104(v=xnagamestudio.41)) class for drawing an animated 2D sprite using [[SpriteBatch]]. The sprite animation is assumed to be laid out horizontally.
**Related tutorial**: [[More tricks with sprites]]

@ -206,7 +206,7 @@ To add _DirectXTK for Audio_ support for a Win32 desktop application running on
> The NuGet package [directxtk_desktop_2017](https://www.nuget.org/packages/directxtk_desktop_2017/) is designed for Windows 7 compatibility for the main library, and the _DirectX Tool Kit for Audio_ uses [XAudio2Redist](https://aka.ms/XAudio2Redist) to support Windows 7 or later.
See the [[Adding the DirectX Tool Kit for Audio]] tutorial for a walk-through of configuring different [XAudio2 Versions](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/xaudio2-versions).
See the [[Adding the DirectX Tool Kit for Audio]] tutorial for a walk-through of configuring different [XAudio2 Versions](https://docs.microsoft.com/windows/win32/xaudio2/xaudio2-versions).
> It's recommended that you use XAudio 2.9, XAudio 2.8, or the XAudio2Redist. Use of [[XAudio 2.7|Legacy XAudio 2.7 Notes]] and the legacy DirectX SDK is not recommended, and support for this configuration is removed as of the June 2020 release.

@ -1,7 +1,7 @@
|[[DirectXTK]]|[[Audio]]|
|---|---|
AudioEmitter is a helper object derived from [X3DAUDIO_EMITTER](https://docs.microsoft.com/en-us/windows/desktop/api/x3daudio/ns-x3daudio-x3daudio_emitter) that can be used with the **Apply3D** method of [[SoundEffectInstance]], [[SoundStreamInstance]], and [[DynamicSoundEffectInstance]].
AudioEmitter is a helper object derived from [X3DAUDIO_EMITTER](https://docs.microsoft.com/windows/win32/api/x3daudio/ns-x3daudio-x3daudio_emitter) that can be used with the **Apply3D** method of [[SoundEffectInstance]], [[SoundStreamInstance]], and [[DynamicSoundEffectInstance]].
See [[AudioListener]].
@ -76,7 +76,7 @@ Be aware that ``pCone`` is ignored for multi-channel emitters.
The AudioEmitter constructor sets pVolumeCurve, pLFECurve, pLPFDirectCurve, pLPFReverbCurve, and pReverbCurve to nullptr which uses XAudio2 default curves. Any custom curve definitions must have a pointer to valid memory at the time Apply3D is called.
# Further reading
[X3DAudio](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/x3daudio)
[X3DAudioCalculate](https://docs.microsoft.com/en-us/windows/desktop/api/x3daudio/nf-x3daudio-x3daudiocalculate)
[X3DAudio](https://docs.microsoft.com/windows/win32/xaudio2/x3daudio)
[X3DAudioCalculate](https://docs.microsoft.com/windows/win32/api/x3daudio/nf-x3daudio-x3daudiocalculate)
[GameFest 2010: The (3D) Sound of Success: X3DAudio and Sound Positioning](https://www.microsoft.com/en-us/download/details.aspx?id=17627)

@ -20,7 +20,7 @@ XAudio2 requires COM be initialized as a prerequisite using ``Windows::Foundatio
CoInitializeEx( nullptr, COINIT_MULTITHREADED );
```
All _DirectXTK for Audio_ components require an AudioEngine instance. For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
All _DirectXTK for Audio_ components require an AudioEngine instance. For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
```cpp
std::unique_ptr<AudioEngine> audEngine;
@ -56,7 +56,7 @@ AudioEngine( AUDIO_ENGINE_FLAGS flags = AudioEngine_Default,
*deviceId*: Specifies the output debug for the XAudio2 mastering voice.
> When using XAudio 2.8 or 2.9, this must be a WinRT device identifier, while on XAudio 2.7 this is a [WASAPI](https://docs.microsoft.com/en-us/windows/desktop/CoreAudio/wasapi) audio end-point identifier. If null, it uses the default audio device.
> When using XAudio 2.8 or 2.9, this must be a WinRT device identifier, while on XAudio 2.7 this is a [WASAPI](https://docs.microsoft.com/windows/win32/coreaudio/wasapi) audio end-point identifier. If null, it uses the default audio device.
> The XAudio2 Redistributable supports either WASAPI or WinRT device identifiers, as does XAudio 2.9 on Windows 10 (May 2019 Update; Version 1903; Build 18362) or later.
@ -73,7 +73,7 @@ eflags |= AudioEngine_Debug;
audEngine = std::make_unique<AudioEngine>( eflags );
```
[XAudio2 Debugging Facilities](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/xaudio2-debugging-facilities)
[XAudio2 Debugging Facilities](https://docs.microsoft.com/windows/win32/xaudio2/xaudio2-debugging-facilities)
> With XAudio 2.7, the developer runtime must be installed on the system for the AudioEngine_Debug case to
> succeed. With XAudio 2.8 on Windows 8.x or Windows 10, the debug support is built into the OS.
@ -116,7 +116,7 @@ Parameters to **Reset** are the similar as for the AudioEngine constructor. If t
> For XAudio 2.7 and XAudio 2.8 (Windows 8.x), this logic also handles the 'lost endpoint' scenario that happens if you unplug speakers or headphones. With XAudio 2.9 (Windows 10), if you use a ``deviceId`` of ``nullptr`` (i.e. the default), then the new Windows 10 WASAPI feature Virtual Audio Client is used which prevents the 'lost endpoint' case from being triggered.
## Win32 desktop applications
For Win32 desktop applications, you can be informed of new audio devices in your application with [RegisterDeviceNotification](https://docs.microsoft.com/en-us/windows/desktop/api/winuser/nf-winuser-registerdevicenotificationa):
For Win32 desktop applications, you can be informed of new audio devices in your application with [RegisterDeviceNotification](https://docs.microsoft.com/windows/win32/api/winuser/nf-winuser-registerdevicenotificationa):
```cpp
#include <dbt.h>
@ -144,7 +144,7 @@ case WM_DEVICECHANGE:
// New audio device
```
Or you can make use of [IMMNotificationClient](https://docs.microsoft.com/en-us/windows/desktop/api/mmdeviceapi/nn-mmdeviceapi-immnotificationclient)
Or you can make use of [IMMNotificationClient](https://docs.microsoft.com/windows/win32/api/mmdeviceapi/nn-mmdeviceapi-immnotificationclient)
## Universal Windows Platform apps
@ -203,7 +203,7 @@ The XAudio2 audio renderer makes use of single-precision floating-point values,
Therefore, _DirectXTK for Audio_ supports attaching a _mastering volume limiter_ xAPO to the mastering voice by setting the ``AudioEngine_UseMasteringLimiter`` flag. It uses default settings, which can be modified by calling **SetMasteringLimit**( release, loudness ).
See [FXMASTERINGLIMITER_PARAMETERS](https://docs.microsoft.com/en-us/windows/desktop/api/xapofx/ns-xapofx-fxmasteringlimiter_parameters)
See [FXMASTERINGLIMITER_PARAMETERS](https://docs.microsoft.com/windows/win32/api/xapofx/ns-xapofx-fxmasteringlimiter_parameters)
```cpp
AUDIO_ENGINE_FLAGS eflags = AudioEngine_UseMasteringLimiter;
@ -250,6 +250,6 @@ The following methods can be used to obtain the low-level XAudio2 interface obje
# Further reading
[XAudio2 APIs](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/xaudio2-apis-portal)
[Audio Effects](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/audio-effects)
[X3DAudio](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/x3daudio)
[XAudio2 APIs](https://docs.microsoft.com/windows/win32/xaudio2/xaudio2-apis-portal)
[Audio Effects](https://docs.microsoft.com/windows/win32/xaudio2/audio-effects)
[X3DAudio](https://docs.microsoft.com/windows/win32/xaudio2/x3daudio)

@ -1,7 +1,7 @@
|[[DirectXTK]]|[[Audio]]|
|---|---|
AudioListener is a helper object derived from [X3DAUDIO_LISTENER](https://docs.microsoft.com/en-us/windows/desktop/api/x3daudio/ns-x3daudio-x3daudio_listener) that can be used by the **Apply3D** method of [[SoundEffectInstance]], [[SoundStreamInstance]], and [[DynamicSoundEffectInstance]].
AudioListener is a helper object derived from [X3DAUDIO_LISTENER](https://docs.microsoft.com/windows/win32/api/x3daudio/ns-x3daudio-x3daudio_listener) that can be used by the **Apply3D** method of [[SoundEffectInstance]], [[SoundStreamInstance]], and [[DynamicSoundEffectInstance]].
See [[AudioEmitter]].
@ -32,7 +32,7 @@ In addition to setting the members of ``X3DAUDIO_LISTENER`` directly, these help
* **Update** (XMVECTOR newPos, XMVECTOR upDir, float dt ): Computes a direction and velocity for the listener based on the existing Position and the newPos, updating the OrientFront/OrientTop to match, and then setting the Position to the newPos. If dt is 0, the update is skipped.
# Further reading
[X3DAudio](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/x3daudio)
[X3DAudioCalculate](https://docs.microsoft.com/en-us/windows/desktop/api/x3daudio/nf-x3daudio-x3daudiocalculate)
[X3DAudio](https://docs.microsoft.com/windows/win32/xaudio2/x3daudio)
[X3DAudioCalculate](https://docs.microsoft.com/windows/win32/api/x3daudio/nf-x3daudio-x3daudiocalculate)
[GameFest 2010: The (3D) Sound of Success: X3DAudio and Sound Positioning](https://www.microsoft.com/en-us/download/details.aspx?id=17627)

@ -1,7 +1,7 @@
|[[Getting Started]]|
|---|
This lesson covers writing your own [[IEffect|Effects]] implementation, specifically a custom effect for rendering a [skybox](https://en.wikipedia.org/wiki/Skybox_%28video_games%29) with a cubemap.
This lesson covers writing your own [[IEffect|Effects]] implementation, specifically a custom effect for rendering a [skybox](https://wikipedia.org/wiki/Skybox_%28video_games%29) with a cubemap.
# Setup
First create a new project using the instructions from the previous lessons: [[Using DeviceResources]] and
@ -202,7 +202,7 @@ void SkyboxEffect::SetMatrices(FXMMATRIX /*world*/, CXMMATRIX view, CXMMATRIX pr
# Managing the constant buffer
We have all the data we need now for the constant buffer. In order to compute the *worldViewProj* value, we will need to do a matrix multiply. We'd like to avoid doing this more often than necessary, either keeping it from the previous frame if it's not changed or doing it only once if multiple matrices are updated in a single frame. The built-in effects all use a [dirty bits](https://en.wikipedia.org/wiki/Dirty_bit) design which we will use here.
We have all the data we need now for the constant buffer. In order to compute the *worldViewProj* value, we will need to do a matrix multiply. We'd like to avoid doing this more often than necessary, either keeping it from the previous frame if it's not changed or doing it only once if multiple matrices are updated in a single frame. The built-in effects all use a [dirty bits](https://wikipedia.org/wiki/Dirty_bit) design which we will use here.
In **SkyboxEffect.h**, add to the class's private variable declarations:

@ -125,6 +125,6 @@ Build and run to see the camera moving up and down while still looking at the pl
# Further reading
DirectX Tool Kit docs [[SimpleMath]]
[Radian](http://en.wikipedia.org/wiki/Radian)
[Graphical projection](http://en.wikipedia.org/wiki/Graphical_projection)
[Radian](http://wikipedia.org/wiki/Radian)
[Graphical projection](http://wikipedia.org/wiki/Graphical_projection)
[Essential Math for Games Programmers (GDC)](http://www.essentialmath.com/)

@ -20,7 +20,7 @@ std::unique_ptr<BasicEffect> effect;
effect = std::make_unique<BasicEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
@ -112,9 +112,9 @@ basicEffect.reset();
# Remarks
This effect implements the classic diffuse [Lambertian](https://en.wikipedia.org/wiki/Lambertian_reflectance) shading with [Phong](https://en.wikipedia.org/wiki/Phong_reflection_model) specular highlights lighting model.
This effect implements the classic diffuse [Lambertian](https://wikipedia.org/wiki/Lambertian_reflectance) shading with [Phong](https://wikipedia.org/wiki/Phong_reflection_model) specular highlights lighting model.
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/direct3d9/lights-and-materials)
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3d9/lights-and-materials)
# Further reading

@ -16,7 +16,7 @@ std::unique_ptr<BasicPostProcess> postProcess;
postProcess = std::make_unique<BasicPostProcess>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Shader selection

@ -35,7 +35,7 @@ HRESULT CreateStaticBuffer(ID3D11Device* device,
## Parameters
*bindFlags* is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values. Typically ``D3D11_BIND_VERTEX_BUFFER`` for vertex buffers, or ``D3D11_BIND_INDEX_BUFFER`` for an index buffer.
*bindFlags* is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values. Typically ``D3D11_BIND_VERTEX_BUFFER`` for vertex buffers, or ``D3D11_BIND_INDEX_BUFFER`` for an index buffer.
## Examples
@ -124,7 +124,7 @@ HRESULT CreateTextureFromMemory(ID3D11Device* device,
## Parameters
*bindFlags* is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values. Typically ``D3D11_BIND_SHADER_RESOURCE`` textures.
*bindFlags* is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values. Typically ``D3D11_BIND_SHADER_RESOURCE`` textures.
Either _texture_ or _textureView_ can be nullptr, but not both. In most use cases for rendering, you only need the shader resource view (SRV) _textureView_ interface.

@ -35,7 +35,7 @@ static RECT Union(const RECT& rcta, const RECT& rctb);
# 3D collision detection
For 3D collision implementation, the [DirectXMath](https://docs.microsoft.com/en-us/windows/win32/dxmath/directxmath-portal) bounding classes provide implementations of many 3D test. If desired, you can interop with these using [[SimpleMath]]'s types like ``Vector3``, ``Vector4``, ``Plane``, ``Ray``, etc.
For 3D collision implementation, the [DirectXMath](https://docs.microsoft.com/windows/win32/dxmath/directxmath-portal) bounding classes provide implementations of many 3D test. If desired, you can interop with these using [[SimpleMath]]'s types like ``Vector3``, ``Vector4``, ``Plane``, ``Ray``, etc.
> See the *Collision* ([PC](https://github.com/walbourn/directx-sdk-samples/tree/main/Collision) / [UWP](https://github.com/microsoft/Xbox-ATG-Samples/tree/master/UWPSamples/System/CollisionUWP) / [GDK](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/Collision) / [XDK](https://github.com/microsoft/Xbox-ATG-Samples/tree/master/XDKSamples/System/Collision)) sample for a demonstration of these ``DirectXCollision.h`` types.
@ -72,7 +72,7 @@ PlaneIntersectionType Intersects(XMVECTOR Plane) const;
bool Intersects(XMVECTOR Origin, XMVECTOR Direction, float& Dist) const;
```
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere).
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere).
## BoundingBox class
This is an 'axis-aligned bounding box' collision primitive.
@ -83,12 +83,12 @@ The **ContainedBy** method provides *box contained by frustum* test.
The **Intersects** method provides *box/box*, *box/sphere*, *box/frustum*, *box/triangle*, *box/plane* and *ray/box* intersection tests.
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingbox).
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingbox).
## BoundingOrientedBox class
This is an 'oriented bounding box' collision primitive. It provides the same **Contains**, **ContainedBy**, and **Intersects** methods as the axis-aligned bounding box.
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingorientedbox).
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingorientedbox).
## BoundingFrustum class
This is a 'view frustum' collision primitive.
@ -97,7 +97,7 @@ The **Contains** method provides *frustum contains point*, *frustum contains tri
The **Intersects** method provides *frustum/sphere*, *frustum/box*, *frustum/frustum*, *frustum/triangle*, *frustum/plane*, and *ray/frustum* intersection tests.
See [MicrosoftDocs](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingfrustum).
See [MicrosoftDocs](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingfrustum).
> Note: The ``BoundingFrustum`` class's ``CreateFromMatrix`` function assumed Left-Handed coordinates. In [DirectXMath 3.16](https://github.com/microsoft/DirectXMath/releases) or later, there's a defaulted parameter you can use for Right-Handed projection matrices: ``BoundingFrustum::CreateFromMatrix(fr, matrix, true);``
@ -122,11 +122,11 @@ ContainmentType ContainedBy(XMVECTOR V0, XMVECTOR V1, XMVECTOR V2,
XMVECTOR Plane3, XMVECTOR Plane4, XMVECTOR Plane5);
```
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/dxmath/ovw-xnamath-triangletests).
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/dxmath/ovw-xnamath-triangletests).
**Next lesson**: [[Picking]]
# Further reading
[DirectXMath Programmer's Reference](https://docs.microsoft.com/en-us/windows/desktop/dxmath/ovw-xnamath-reference)
[DirectXMath Programmer's Reference](https://docs.microsoft.com/windows/win32/dxmath/ovw-xnamath-reference)
DirectXMath Collision sample [Win32](https://github.com/walbourn/directx-sdk-samples/tree/main/Collision) / [UWP](https://github.com/microsoft/Xbox-ATG-Samples/tree/master/UWPSamples/System/CollisionUWP) / [GDK](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/Collision)

@ -166,24 +166,24 @@ Because WRL is a pure C++ template library, it has no particular platform suppor
> The Windows 8.0 SDK and later that includes WRL does not support targeting Windows XP / Windows Server 2003. For these older operating systems you have to make use of the Windows 7.1A SDK instead. See [this blog post](https://walbourn.github.io/visual-studio-2012-update-1/) for more details.
The **DirectX-Headers** [GitHub](https://github.com/microsoft/DirectX-Headers) includes an implementation of ``Microsoft::WRL::ComPtr`` that is for use on non-Win32 platforms like [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) via ``wrl/client.h``. This version does not include support for ``WeakRef``, but I avoid using that class in general.
The **DirectX-Headers** [GitHub](https://github.com/microsoft/DirectX-Headers) includes an implementation of ``Microsoft::WRL::ComPtr`` that is for use on non-Win32 platforms like [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/install-win10) via ``wrl/client.h``. This version does not include support for ``WeakRef``, but I avoid using that class in general.
# Remarks
Making use of the older ``_com_ptr_t`` Visual Studio smart-pointer class which was originally intended as a non-ATL option is not recommended.
If using [C++/WinRT projections](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/), you could also choose to use ``winrt::com_ptr`` instead of ``Microsoft::WRL:ComPtr``. It is similar in design, but not identical. See [Microsoft Docs](https://docs.microsoft.com/en-us/uwp/cpp-ref-for-winrt/com-ptr).
If using [C++/WinRT projections](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/), you could also choose to use ``winrt::com_ptr`` instead of ``Microsoft::WRL:ComPtr``. It is similar in design, but not identical. See [Microsoft Docs](https://docs.microsoft.com/uwp/cpp-ref-for-winrt/com-ptr).
Note that WRL is not supported for Managed C++ (``/clr``) projects. In that case you should make use of ATL's ``CComPtr`` instead keeping in mind the difference in behavior of ``operator&``. See [Microsoft Docs](https://docs.microsoft.com/en-us/cpp/atl/reference/ccomptr-class).
Note that WRL is not supported for Managed C++ (``/clr``) projects. In that case you should make use of ATL's ``CComPtr`` instead keeping in mind the difference in behavior of ``operator&``. See [Microsoft Docs](https://docs.microsoft.com/cpp/atl/reference/ccomptr-class).
The [Windows Implementation Libraries (WIL)](https://github.com/microsoft/wil/) provides a COM smart-pointer called ``wil::com_ptr``.
# Further reading
[Microsoft Docs: Programming DirectX with COM](https://docs.microsoft.com/en-us/windows/win32/prog-dx-with-com)
[Microsoft Docs: ComPtr](https://docs.microsoft.com/en-us/cpp/windows/comptr-class)
[Microsoft Docs: Managing Object Lifetimes Through Reference Counting](https://docs.microsoft.com/en-us/windows/win32/com/managing-object-lifetimes-through-reference-counting)
[Microsoft Docs: Rules for Managing Reference Counts](https://docs.microsoft.com/en-us/windows/win32/com/rules-for-managing-reference-counts)
[Microsoft Docs: COM](https://docs.microsoft.com/en-us/windows/desktop/com/the-component-object-model)
[Microsoft Docs: Reference Counting (Direct3D 10)](https://docs.microsoft.com/en-us/windows/desktop/direct3d10/d3d10-graphics-programming-guide-api-features-reference-counting)
[Wikipedia: Reference counting](https://en.wikipedia.org/wiki/Reference_counting)
[Microsoft Docs: Programming DirectX with COM](https://docs.microsoft.com/windows/win32/prog-dx-with-com)
[Microsoft Docs: ComPtr](https://docs.microsoft.com/cpp/windows/comptr-class)
[Microsoft Docs: Managing Object Lifetimes Through Reference Counting](https://docs.microsoft.com/windows/win32/com/managing-object-lifetimes-through-reference-counting)
[Microsoft Docs: Rules for Managing Reference Counts](https://docs.microsoft.com/windows/win32/com/rules-for-managing-reference-counts)
[Microsoft Docs: COM](https://docs.microsoft.com/windows/win32/com/the-component-object-model)
[Microsoft Docs: Reference Counting (Direct3D 10)](https://docs.microsoft.com/windows/win32/direct3d10/d3d10-graphics-programming-guide-api-features-reference-counting)
[Wikipedia: Reference counting](https://wikipedia.org/wiki/Reference_counting)

@ -19,7 +19,7 @@ std::unique_ptr<CommonStates> states;
states = std::make_unique<CommonStates>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Using this helper to set device state
@ -33,8 +33,8 @@ deviceContext->PSSetSamplers(0, 1, &samplerState);
```
# Blending State
[D3D11_BLEND_DESC](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_blend_desc)
[D3D11_BLEND_DESC1](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11_1/ns-d3d11_1-cd3d11_blend_desc1)
[D3D11_BLEND_DESC](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_blend_desc)
[D3D11_BLEND_DESC1](https://docs.microsoft.com/windows/win32/api/d3d11_1/ns-d3d11_1-cd3d11_blend_desc1)
* ID3D11BlendState* **Opaque**();
* ID3D11BlendState* **AlphaBlend**();
@ -51,7 +51,7 @@ NonPremultiplied() if using 'straight' alpha.
For multipass rendering, you'd typically use Additive().
# Depth/Stencil State
[D3D11_DEPTH_STENCIL_DESC](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_depth_stencil_desc)
[D3D11_DEPTH_STENCIL_DESC](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_depth_stencil_desc)
* ID3D11DepthStencilState* **DepthNone**();
* ID3D11DepthStencilState* **DepthDefault**();
@ -68,8 +68,8 @@ For drawing alpha blended objects (which is typically done after all opaque obje
For drawing objects without any depth-sort at all, use DepthNone().
# Rasterizer State
[D3D11_RASTERIZER_DESC](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_rasterizer_desc)
[D3D11_RASTERIZER_DESC1](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11_1/ns-d3d11_1-cd3d11_rasterizer_desc1)
[D3D11_RASTERIZER_DESC](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_rasterizer_desc)
[D3D11_RASTERIZER_DESC1](https://docs.microsoft.com/windows/win32/api/d3d11_1/ns-d3d11_1-cd3d11_rasterizer_desc1)
* ID3D11RasterizerState* **CullNone**();
* ID3D11RasterizerState* **CullClockwise**();
@ -85,7 +85,7 @@ For "double-sided" geometry, use CullNone(). Keep in mind this is a potentially
Wireframe() is a wireframe rendering mode and shows both sides of the geometry.
# Sampler State
[D3D11_SAMPLER_DESC](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_sampler_desc)
[D3D11_SAMPLER_DESC](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_sampler_desc)
* ID3D11SamplerState* **PointWrap**();
* ID3D11SamplerState* **PointClamp**();
@ -104,7 +104,7 @@ Remember that ??SetSamplers() actually takes an _array_ of sampler state objects
All common states work with all feature levels. ``Anisotropic*`` uses a *MaxAnisotropy* of 2 on Feature Level 9.1. On all other feature levels is uses 16 (``D3D11_MAX_MAXANISOTROPY``).
[Direct3D feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
[Direct3D feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
# Remarks

@ -188,7 +188,7 @@ The main limitation of using the DGSL tool is that it creates only Shader Model
To support Windows phone, you need feature level 9.3, and to target Surface RT you need feature level 9.1. There is a workaround which is to manually export the DGSL shader to an HLSL file, then compile it using FXC with either the ``ps_4_0_level_9_1`` or ``ps_4_0_level_9_3`` shader profile. It is quite likely you'll need to manually simplify the HLSL shader to successfully get it to compile. [[DGSLEffectFactory|EffectFactory]] implements this workaround by looking for a 'base-name' equivalent of the ``.DGSL.CSO`` file as a ``.CSO`` file when on feature level 9.x devices.
[How to: Export a Shader](https://docs.microsoft.com/en-us/visualstudio/designers/how-to-export-a-shader)
[How to: Export a Shader](https://docs.microsoft.com/visualstudio/designers/how-to-export-a-shader)
> DGSLEffect is not supported for *DirectX Tool Kit for DirectX 12* since it's specific to Shader Model 4.0.
@ -197,6 +197,6 @@ To support Windows phone, you need feature level 9.3, and to target Surface RT y
# Further reading
DirectX Tool Kit docs [[Effects]]
[Using 3-D Assets in Your Game or App](https://docs.microsoft.com/en-us/visualstudio/designers/using-3-d-assets-in-your-game-or-app)
[Working with Shaders](https://docs.microsoft.com/en-us/visualstudio/designers/working-with-shaders)
[Using 3-D Assets in Your Game or App](https://docs.microsoft.com/visualstudio/designers/using-3-d-assets-in-your-game-or-app)
[Working with Shaders](https://docs.microsoft.com/visualstudio/designers/working-with-shaders)
[Visual Studio 3D Starter Kit (Windows 8.1)](http://aka.ms/vs3dkitwin)

@ -124,7 +124,7 @@ The last optional parameter _alphaMode_ is a pointer to return the _alpha mode_
* ``DDS_ALPHA_MODE_OPAQUE`` (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.
* ``DDS_ALPHA_MODE_CUSTOM`` (4) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.
For the ``Ex`` versions, the _usage_ is a [D3D11_USAGE](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_usage), typically ``D3D11_USAGE_DEFAULT``. The *bindFlags* parameter is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values, typically ``D3D11_BIND_SHADER_RESOURCE`` for textures. The _cpuAccessFlags_ parameter is ``D3D11_CPU_ACCESS_FLAG`` typically 0 for default usage textures. The _miscFlags_ parameter is a [D3D11_RESOURCE_MISC_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_resource_misc_flag) value, usually 0.
For the ``Ex`` versions, the _usage_ is a [D3D11_USAGE](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_usage), typically ``D3D11_USAGE_DEFAULT``. The *bindFlags* parameter is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values, typically ``D3D11_BIND_SHADER_RESOURCE`` for textures. The _cpuAccessFlags_ parameter is ``D3D11_CPU_ACCESS_FLAG`` typically 0 for default usage textures. The _miscFlags_ parameter is a [D3D11_RESOURCE_MISC_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_resource_misc_flag) value, usually 0.
# Example
@ -284,7 +284,7 @@ if (file)
}
```
See [File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
See [File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/windows/uwp/files/file-access-permissions)
# Debugging texture loading
@ -357,15 +357,13 @@ default:
# DDS Files
This function loads both traditional and FourCC "DX10" variant ``.DDS`` files.
[DDS on MSDN](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds)
[DDS on Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3ddds/dx-graphics-dds)
# Further Reading
[The DDS File Format Lives](https://walbourn.github.io/the-dds-file-format-lives/)
[Direct3D Feature Levels](https://aka.ms/Apsgrj)
[Programming Guide for DXGI](https://docs.microsoft.com/en-us/windows/desktop/direct3ddxgi/dx-graphics-dxgi-overviews)
[Linear-Space Lighting (i.e. Gamma)](http://filmicworlds.com/blog/linear-space-lighting-i-e-gamma/)
[Chapter 24. The Importance of Being Linear](https://developer.nvidia.com/gpugems/gpugems3/part-iv-image-effects/chapter-24-importance-being-linear), GPU Gems 3

@ -29,7 +29,7 @@ effect = std::make_unique<SkinnedDGSLEffect>(device, pixelShader);
If the _pixelShader_ instance is null, it uses one of the three built-in default materials: _Unlit_, _Lambert_, and _Phong_. This class assumes the pixel shader provided is signature compatible with the built-in DGSL vertex shader, and will work for the feature level of the device.
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces

@ -19,7 +19,7 @@ std::unique_ptr<Debugffect> effect;
effect = std::make_unique<DebugEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
PBREffect supports [[IEffect]] and [[IEffectMatrices]].
@ -68,7 +68,7 @@ If instancing is enabled, this effect also requires these vertex elements:
This effect uses Shader Model 4.0 so requires Direct3D hardware feature level 10.0 or greater.
[Direct3D feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
[Direct3D feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
# Further reading

@ -54,7 +54,7 @@ If ``depthBufferFormat`` is set to ``DXGI_FORMAT_UNKNOWN``, then no depth/stenci
The ``backBufferCount`` defaults to 2, but in some cases you may want to override it to use 3. Larger numbers would be quite unusual and are not recommended.
The ``minFeatureLevel`` defaults to 10 for PC and 9.3 for UWP. You can specify a higher [hardware level](https://docs.microsoft.com/en-us/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro) if you want to take a hard dependency on additional capabilities.
The ``minFeatureLevel`` defaults to 10 for PC and 9.3 for UWP. You can specify a higher [hardware level](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro) if you want to take a hard dependency on additional capabilities.
The ``flags`` parameter is covered below in *Device Options*.
@ -109,24 +109,24 @@ The ``flags`` parameter is covered below in *Device Options*.
# Device Options
* ``c_FlipPresent``: Prefer the use of "flip" style swap per [this blog post](https://devblogs.microsoft.com/directx/dxgi-flip-model/) on Windows 10 systems.
* ``c_AllowTearing``: Enable [variable refresh rate](https://docs.microsoft.com/en-us/windows/win32/direct3ddxgi/variable-refresh-rate-displays) (a.k.a. NVIDIAs G-SYNC, AMDs FreeSync, and VESA DisplayPort Adaptive-Sync) if supported.
* ``c_EnableHDR``: Enable [HDR10 output](https://docs.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range) if supported. See [below](https://github.com/Microsoft/DirectXTK/wiki/DeviceResources#wide-gamut-hdr-rendering).
* ``c_AllowTearing``: Enable [variable refresh rate](https://docs.microsoft.com/windows/win32/direct3ddxgi/variable-refresh-rate-displays) (a.k.a. NVIDIAs G-SYNC, AMDs FreeSync, and VESA DisplayPort Adaptive-Sync) if supported.
* ``c_EnableHDR``: Enable [HDR10 output](https://docs.microsoft.com/windows/win32/direct3darticles/high-dynamic-range) if supported. See [below](https://github.com/Microsoft/DirectXTK/wiki/DeviceResources#wide-gamut-hdr-rendering).
* ``c_FastSemantics`` (Xbox One XDK only): Create the 11.x device with "fast semantics" enabled.
* ``c_Enable4K_UHD`` (Xbox One XDK only): Enable 4k swapchain if supported, otherwise use 1080p.
# Threading model
The DeviceResources class methods are intended to be called from the main presenting thread, and not from other threads. The device context associated with DeviceResources is the immediate context, and is intended for use by this 'main' thread. Per the [DirectX Graphics Infrastructure (DXGI): Best Practices](https://docs.microsoft.com/en-us/windows/desktop/direct3darticles/dxgi-best-practices#multithreading_and_dxgi), this presenting thread should also be the same thread as the main window message processing.
The DeviceResources class methods are intended to be called from the main presenting thread, and not from other threads. The device context associated with DeviceResources is the immediate context, and is intended for use by this 'main' thread. Per the [DirectX Graphics Infrastructure (DXGI): Best Practices](https://docs.microsoft.com/windows/win32/direct3darticles/dxgi-best-practices#multithreading-and-dxgi), this presenting thread should also be the same thread as the main window message processing.
# Platform notes
## Windows desktop apps
The **DeviceResources** implementation is designed to support Direct3D 11.1 on [Windows 7 Service Pack 1](https://walbourn.github.io/directx-11-1-and-windows-7/), Windows 8.x, or later which provides [significant improvements](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/direct3d-11-1-features) such as simplified interop with Direct2D/DirectWrite.
The **DeviceResources** implementation is designed to support Direct3D 11.1 on [Windows 7 Service Pack 1](https://walbourn.github.io/directx-11-1-and-windows-7/), Windows 8.x, or later which provides [significant improvements](https://docs.microsoft.com/windows/win32/direct3d11/direct3d-11-1-features) such as simplified interop with Direct2D/DirectWrite.
> Older versions of this DeviceResources supported Windows Vista Service Pack 2 and Windows 7 RTM with DirectX 11.0. The implementation has since been changed to require DirectX 11.1 to simplify the code. If you need details on the differences, see [this blog post](https://walbourn.github.io/anatomy-of-direct3d-11-create-device/)
## Universal Windows Platform apps
The UWP version of **DeviceResources** always uses [DirectX 11.3 interfaces](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/direct3d-11-3-features).
The UWP version of **DeviceResources** always uses [DirectX 11.3 interfaces](https://docs.microsoft.com/windows/win32/direct3d11/direct3d-11-3-features).
It includes **GetRotation** and **GetOrientationTransform3D** to simplify handling of display orientation.
@ -164,7 +164,7 @@ Since the ``DeviceResources`` class is now in it's own file and no longer direct
* If the SDK Debug Layer is not present on the target system when running ``Debug`` configurations, it will automatically fallback to creating the device without debugging.
* The DR version always uses ``D3D11_CREATE_DEVICE_BGRA_SUPPORT`` which is required for Direct2D/DirectWrite interop if that's desired.
* If no hardware device is available, the DR version will fall back to using [WARP](https://docs.microsoft.com/en-us/windows/desktop/direct3darticles/directx-warp) in non-production builds as this is useful for debugging and validation.
* If no hardware device is available, the DR version will fall back to using [WARP](https://docs.microsoft.com/windows/win32/direct3darticles/directx-warp) in non-production builds as this is useful for debugging and validation.
* In ``Debug`` configurations, additional diagnostic messages are output to the debug window.
* Rather than always using the default Direct3D device, the DR version will filter out the _Microsoft Basic Render Driver_ adapter as this fallback software device is seldom acceptable performance for games.

@ -31,14 +31,14 @@ The standard ``d3d11_1.h`` headers in the Windows 8.x / 10 SDK already include a
* ``CD3D11_QUERY_DESC``
* ``CD3D11_COUNTER_DESC``
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/cd3d11-helper-classes) for more information on these helpers.
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3d11/cd3d11-helper-classes) for more information on these helpers.
> These helpers are excluded for C language builds or if the preprocessor define ``D3D11_NO_HELPERS`` is set.
> There are some additional helpers related to DirectX 11 Video not covered here that are excluded by the preprocessor define ``D3D11_VIDEO_NO_HELPERS``.
# Exception-safe Direct3D 11 resource locking
Modern C++ development strongly encourages use of the [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern for exception-safe resource management, ensuring that resources are properly cleaned up if C++ exceptions are thrown. Even without exception handling, it's generally cleaner code to use RAII and rely on the C++ scope variables rules to handle cleanup. Most of these cases are handled by the STL classes such as ``std::unique_ptr``, ``std::shared_ptr``, etc. and the recommended COM smart pointer [[``Microsoft::WRL::ComPtr``|ComPtr]] for Direct3D reference counted objects. One case that isn't so easily managed with existing classes is when you are mapping staging/dynamic Direct3D 11 resources. ``MapGuard`` solves this problem, and is modeled after ``std::lock_mutex``.
Modern C++ development strongly encourages use of the [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern for exception-safe resource management, ensuring that resources are properly cleaned up if C++ exceptions are thrown. Even without exception handling, it's generally cleaner code to use RAII and rely on the C++ scope variables rules to handle cleanup. Most of these cases are handled by the STL classes such as ``std::unique_ptr``, ``std::shared_ptr``, etc. and the recommended COM smart pointer [[``Microsoft::WRL::ComPtr``|ComPtr]] for Direct3D reference counted objects. One case that isn't so easily managed with existing classes is when you are mapping staging/dynamic Direct3D 11 resources. ``MapGuard`` solves this problem, and is modeled after ``std::lock_mutex``.
```cpp
class MapGuard : public D3D11_MAPPED_SUBRESOURCE

@ -51,7 +51,7 @@ using namespace DirectX;
# Building
This code is designed to build with Visual Studio 2019 or later. It requires the Windows SDK (19041) or later for functionality such as the DirectXMath library and the DXGI 1.2 headers.
These components are designed to work without requiring any content from the DirectX SDK. For details, see [Where is the DirectX SDK?](https://docs.microsoft.com/en-us/windows/desktop/directx-sdk--august-2009-), [Where is the DirectX SDK (2021 Edition)?](https://aka.ms/dxsdk), and [The Zombie DirectX SDK](https://aka.ms/AA4gfea).
These components are designed to work without requiring any content from the DirectX SDK. For details, see [Where is the DirectX SDK?](https://docs.microsoft.com/windows/win32/directx-sdk--august-2009-), [Where is the DirectX SDK (2021 Edition)?](https://aka.ms/dxsdk), and [The Zombie DirectX SDK](https://aka.ms/AA4gfea).
## HLSL shaders
The required Direct3D shaders are built as headers in `Src\Shader\Compiled\*.inc` and included into the DirectXTK static library. They are automatically built by the Visual Studio project if they are not present, and cleared by a Clean. They can also be manually rebuilt using the ``CompileShaders.cmd`` script (i.e. `...\DirectXTK\Src\Shaders`)
@ -122,7 +122,7 @@ See [[Audio]] for additional information when setting up Windows desktop project
See also the [Visual C+ Team Blog](https://devblogs.microsoft.com/cppblog/flexible-project-to-project-references/)
## Using NuGet package manager
Alternatively you can use [NuGet](https://docs.microsoft.com/en-us/nuget/what-is-nuget) to install one of the DirectX Tool Kit packages. Use *Project / Manage NuGet Packages...* then select "Online" and search for "DirectXTK".
Alternatively you can use [NuGet](https://docs.microsoft.com/nuget/what-is-nuget) to install one of the DirectX Tool Kit packages. Use *Project / Manage NuGet Packages...* then select "Online" and search for "DirectXTK".
<table>
<tr>
@ -207,7 +207,7 @@ The _DirectX Tool Kit_ library assumes your binary is linking with the following
### DirectX Tool Kit for Audio
For "Windows 8.x" or "Windows 10" configurations of the AudioEngine class, you'll need to use ``xaudio2.lib``.
For [XAudio2Redist](https://docs.microsoft.com/en-us/windows/win32/xaudio2/xaudio2-redistributable), the [Microsoft.XAudio2.Redist](https://www.nuget.org/packages/Microsoft.XAudio2.Redist/) NuGet package provides the ``xaudio2_9redist.lib``.
For [XAudio2Redist](https://docs.microsoft.com/windows/win32/xaudio2/xaudio2-redistributable), the [Microsoft.XAudio2.Redist](https://www.nuget.org/packages/Microsoft.XAudio2.Redist/) NuGet package provides the ``xaudio2_9redist.lib``.
### GamePad
For "Windows 10" configurations of the GamePad class that use Windows.Gaming.Input, you need ``runtimeobject.lib`` for Win32 desktop apps. For UWP apps, this is already handled with the umbrella lib ``windowsapp.lib``.
@ -215,19 +215,19 @@ For "Windows 10" configurations of the GamePad class that use Windows.Gaming.Inp
For "Windows 8.x" configurations of the GamePad class using XInput 1.4, you'll need ``xinput.lib``.
For Windows 7 configurations, use ``xinput9_1_0.lib``.
# Content pipeline
To use the Visual Studio graphics assets tools in the build system, be sure to [add them to your project](https://docs.microsoft.com/en-us/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
To use the Visual Studio graphics assets tools in the build system, be sure to [add them to your project](https://docs.microsoft.com/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
**Note:** When adding ``.spritefont``, ``.sdkmesh``, or ``.xwb`` files to your Universal Windows Platform (UWP) or Xbox One project, you need to manually set the file properties to "Content: Yes" for all configurations to have these files included in your AppX package. ``.dds`` files, other image file formats, and ``.wav`` files are automatically detected as a media file and are included as content by default.
# Error handling
DirectXTK makes use of C++ exception handling which should be enabled by the application via the `/EHsc` compiler switch. In Visual Studio, this is set in the project settings under "C++ / Code Generation" with Enable C++ Exceptions set to "Yes (/EHsc)" for all configurations.
* [C++ Exception Handling](https://docs.microsoft.com/en-us/cpp/cpp/cpp-exception-handling)
* [How to: Break When an Exception is Thrown](https://docs.microsoft.com/en-us/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [C++ Exception Handling](https://docs.microsoft.com/cpp/cpp/cpp-exception-handling)
* [How to: Break When an Exception is Thrown](https://docs.microsoft.com/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [Dual-use Coding Techniques for Games](https://aka.ms/Fo3su4)
* [Resource Acquisition Is Initialization](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization)
* [Resource Acquisition Is Initialization](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization)
* [[ThrowIfFailed]]
_Visual Studio Express editions have limited exception handling debugging support, so consider using VS Community or Pro+ instead._
@ -239,10 +239,10 @@ DirectXTK encourages and makes use of a number of smart-pointers to simplify res
* ``std::shared_ptr`` - A smart-pointer that tracks memory use with reference counting
* ``Microsoft::WRL::ComPtr`` - A [[COM smart-pointer|ComPtr]] for reference count management very similar to ATL's CComPtr
* [Smart Pointers (Modern C++)](https://docs.microsoft.com/en-us/cpp/cpp/smart-pointers-modern-cpp)
* [Managing the Lifetime of an Object](https://docs.microsoft.com/en-us/windows/desktop/LearnWin32/managing-the-lifetime-of-an-object)
* [COM Coding Practices](https://docs.microsoft.com/en-us/windows/desktop/LearnWin32/com-coding-practices#smartptr)
* [Reference Counting (Direct3D 10)](https://docs.microsoft.com/en-us/windows/desktop/direct3d10/d3d10-graphics-programming-guide-api-features-reference-counting)
* [Smart Pointers (Modern C++)](https://docs.microsoft.com/cpp/cpp/smart-pointers-modern-cpp)
* [Managing the Lifetime of an Object](https://docs.microsoft.com/windows/win32/learnwin32/managing-the-lifetime-of-an-object)
* [COM Coding Practices](https://docs.microsoft.com/windows/win32/learnwin32/com-coding-practices#smartptr)
* [Reference Counting (Direct3D 10)](https://docs.microsoft.com/windows/win32/direct3d10/d3d10-graphics-programming-guide-api-features-reference-counting)
# Additional information
[[Implementation]]

@ -16,7 +16,7 @@ First create a new project using the instructions from the earlier lessons: [[Us
The text renderer in _DirectX Tool Kit_ makes use of bitmap fonts, so the first step is to create a ``.spritefont`` file by capturing a system TrueType font using the **makespritefont** command-line utility.
* Download the [MakeSpriteFont.exe](https://github.com/microsoft/DirectXTK/releases/latest/download/MakeSpriteFont.exe) from the _DirectX Tool Kit_ site save the EXE into your project's folder.
* Open a [command-prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq) and then change to your project's folder.
* Open a Command Prompt and then change to your project's folder.
Run the following command-line
@ -232,7 +232,7 @@ Build and run to see our text string centered in the middle of the rendering win
* If you want to render Xbox controller button artwork composed with standard text, see [[ControllerFont]].
* If you want to make use of *DirectWrite* for vector-based fonts on Windows, see [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/directwrite/getting-started-with-directwrite).
* If you want to make use of *DirectWrite* for vector-based fonts on Windows, see [Microsoft Docs](https://docs.microsoft.com/windows/win32/directwrite/getting-started-with-directwrite).
**Next lesson:** [[Simple rendering]]

@ -16,7 +16,7 @@ std::unique_ptr<DualPostProcess> postProcess;
postProcess = std::make_unique<DualPostProcess>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Shader selection

@ -1,7 +1,7 @@
|[[DirectXTK]]|[[Effects]]|
|---|---|
This is a native Direct3D 11 implementation of the built-in DualTextureEffect from XNA Game Studio 4 (``Microsoft.Xna.Framework.Graphics.DualTextureEffect``) which supports two layer multi-texturing (for [light maps](https://en.wikipedia.org/wiki/Lightmap) or detail textures), vertex color, and fogging.
This is a native Direct3D 11 implementation of the built-in DualTextureEffect from XNA Game Studio 4 (``Microsoft.Xna.Framework.Graphics.DualTextureEffect``) which supports two layer multi-texturing (for [light maps](https://wikipedia.org/wiki/Lightmap) or detail textures), vertex color, and fogging.
![Dual texture map](https://github.com/Microsoft/DirectXTK/wiki/images/DualTextureEffect.png)
@ -18,7 +18,7 @@ std::unique_ptr<DualTextureEffect> effect;
effect = std::make_unique<DualTextureEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces

@ -28,7 +28,7 @@ effect = std::make_unique<DynamicSoundEffectInstance>( audEngine.get(),
44100, 1 );
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
It can optionally support 3D positional audio:

@ -32,7 +32,7 @@ std::unique_ptr<PBREffectFactory> fxFactory;
fxFactory = std::make_unique<PBREffectFactory>( device );
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Creating effects
Fill out the ``EffectInfo`` structure, then call **CreateEffect** to obtain an [[Effects]] instance. If the _info.name_ string is provided then any already created effect from the factory that has the same name will be returned as a shared instance rather than a new instance created. If there is a name match, then all the other parameters in the ``EffectInfo`` are ignored.
@ -115,7 +115,7 @@ fxFactory->CreateTexture( L"stone.dds", nullptr, srv.GetAddressOf() );
```
# Directories
The **CreateTexture** and **CreatePixelShader** methods both assume the name given is the filename. By default, this is a relative path to the current working directory ([CWD](https://docs.microsoft.com/en-us/windows/desktop/FileIO/changing-the-current-directory)). To cause the factory to look in a specific directory path, use **SetDirectory**.
The **CreateTexture** and **CreatePixelShader** methods both assume the name given is the filename. By default, this is a relative path to the current working directory ([CWD](https://docs.microsoft.com/windows/win32/fileio/changing-the-current-directory)). To cause the factory to look in a specific directory path, use **SetDirectory**.
```cpp
fxFactory->SetDirectory( L".\\Assets" );

@ -14,7 +14,7 @@ DirectX Tool Kit also includes the following built-in effects:
* [[SkinnedNormalMapEffect|NormalMapEffect]] which extends ``SkinnedEffect`` to support normal maps and optional specular map.
* [[PBREffect]] which implements a Disney-style (Roughness/Metalness workflow) Physically-Based Renderer effect using image-based lighting. This effect also supports GPU instancing.
* [[DebugEffect]] which implements debugging shaders such as visualization of normals, tangents, and bi-tangents as well as supporting hemispherical ambient lighting. This effect also supports GPU instancing.
* [[DGSLEffect]] and [[SkinnedDGSLEffect|DGSLEffect]] which support the [Visual Studio Shader Designer](https://docs.microsoft.com/en-us/visualstudio/designers/shader-designer) (DGSL) content pipeline with up to 8 textures.
* [[DGSLEffect]] and [[SkinnedDGSLEffect|DGSLEffect]] which support the [Visual Studio Shader Designer](https://docs.microsoft.com/visualstudio/designers/shader-designer) (DGSL) content pipeline with up to 8 textures.
See also [[EffectFactory]]
@ -35,7 +35,7 @@ std::unique_ptr<BasicEffect> effect;
effect = std::make_unique<BasicEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Set effect parameters
@ -159,7 +159,7 @@ The compiled shaders are integrated into the DirectXTK library to avoid the need
Creation is fully asynchronous, so you can instantiate multiple effect instances at the same time on different threads. Each instance only supports drawing from one thread at a time, but you can simultaneously draw on multiple threads if you create a separate effect instance per Direct3D 11 deferred context.
[Immediate and Deferred Rendering](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-render-multi-thread-render)
[Immediate and Deferred Rendering](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-render-multi-thread-render)
# State management

@ -20,7 +20,7 @@ std::unique_ptr<EnvironmentMapEffect> effect;
effect = std::make_unique<EnvironmentMapEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
@ -78,13 +78,13 @@ This effect requires a texture sampler in both slots 0 and 1. [[GeometricPrimiti
![Cubic Environment Map](https://github.com/Microsoft/DirectXTK/wiki/images/cubicenvmap.png)
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/direct3d9/cubic-environment-mapping)
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3d9/cubic-environment-mapping)
## Spherical Environment Map
![Sphere Environment Map](https://github.com/Microsoft/DirectXTK/wiki/images/sphereenvmap.png)
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/direct3d9/spherical-environment-mapping)
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3d9/spherical-environment-mapping)
# Feature Level Notes

@ -296,7 +296,7 @@ Build and run. The left thumb stick on the gamepad can be used to adjust the vie
## Technical notes
* The view can never be exactly straight up or straight down to avoid a problem known as
[gimbal lock](https://en.wikipedia.org/wiki/Gimbal_lock) which can cause the camera view to flip unexpectedly or tumble uncontrollably.
[gimbal lock](https://wikipedia.org/wiki/Gimbal_lock) which can cause the camera view to flip unexpectedly or tumble uncontrollably.
* This control implementation is very simple, and really only works on a system with fast frame-rate. For a more robust implementation, the ``Update`` code should make use of ``elapsedTime`` to scale the keyboard movement rate values and ``ROTATION_GAIN`` adjusted accordingly.

@ -20,7 +20,7 @@ std::unique_ptr<GamePad> gamepad;
gamepad = std::make_unique<GamePad>();
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
# Basic use
**GetState** queries the controller status given a _player_ index. If connected, it returns the status of the buttons (A, B, X, Y, left & right stick, left & right shoulder, back, and start), the directional pad (DPAD), the left & right thumb sticks, and the left & right triggers.

@ -10,7 +10,7 @@ This is a helper for drawing simple geometric shapes including texture coordinat
* Icosahedron
* Octahedron
* Sphere (uv or geodesic)
* Teapot (a.k.a. the [Utah teapot](https://en.wikipedia.org/wiki/Utah_teapot))
* Teapot (a.k.a. the [Utah teapot](https://wikipedia.org/wiki/Utah_teapot))
* Tetrahedron
* Torus
@ -35,27 +35,27 @@ For exception safety, the factory functions return a ``std::unique_ptr``.
* **CreateBox**( deviceContext, const XMFLOAT3& size): Creates a box with a non-uniform size.
* **CreateCone**( deviceContext, float diameter = 1, float height = 1, size_t tessellation = 32): Creates a [cone](http://en.wikipedia.org/wiki/Cone) of a given height, diameter, and tessellation factor.
* **CreateCone**( deviceContext, float diameter = 1, float height = 1, size_t tessellation = 32): Creates a [cone](http://wikipedia.org/wiki/Cone) of a given height, diameter, and tessellation factor.
* **CreateCube**( deviceContext, float size = 1): Creates a [cube](http://en.wikipedia.org/wiki/Cube) (also known as a [hexahedron](http://en.wikipedia.org/wiki/Hexahedron)) of the given size.
* **CreateCube**( deviceContext, float size = 1): Creates a [cube](http://wikipedia.org/wiki/Cube) (also known as a [hexahedron](http://wikipedia.org/wiki/Hexahedron)) of the given size.
* **CreateCylinder**( deviceContext, float height = 1, float diameter = 1, size_t tessellation = 32): Creates a [cylinder](http://en.wikipedia.org/wiki/Cylinder_(geometry)) of given height, diameter, tessellation factor.
* **CreateCylinder**( deviceContext, float height = 1, float diameter = 1, size_t tessellation = 32): Creates a [cylinder](http://wikipedia.org/wiki/Cylinder_(geometry)) of given height, diameter, tessellation factor.
* **CreateDodecahedron**( deviceContext, float size = 1): Creates a [dodecahedron](http://en.wikipedia.org/wiki/Dodecahedron) of a given size.
* **CreateDodecahedron**( deviceContext, float size = 1): Creates a [dodecahedron](http://wikipedia.org/wiki/Dodecahedron) of a given size.
* **CreateGeoSphere**( deviceContext, float diameter = 1, size_t tessellation = 3): Creates a geodesic [sphere](http://en.wikipedia.org/wiki/Sphere) with the given diameter and tessellation factor.
* **CreateGeoSphere**( deviceContext, float diameter = 1, size_t tessellation = 3): Creates a geodesic [sphere](http://wikipedia.org/wiki/Sphere) with the given diameter and tessellation factor.
* **CreateIcosahedron**( deviceContext, float size = 1): Creates a [icosahedron](http://en.wikipedia.org/wiki/Icosahedron) of a given size.
* **CreateIcosahedron**( deviceContext, float size = 1): Creates a [icosahedron](http://wikipedia.org/wiki/Icosahedron) of a given size.
* **CreateOctahedron**( deviceContext, float size = 1): Creates a [octahedron](http://en.wikipedia.org/wiki/Octahedron) of a given size.
* **CreateOctahedron**( deviceContext, float size = 1): Creates a [octahedron](http://wikipedia.org/wiki/Octahedron) of a given size.
* **CreateSphere**( deviceContext, float diameter = 1, size_t tessellation = 16): Creates a uv-[sphere](http://en.wikipedia.org/wiki/Sphere) of given diameter with the given tessellation factor.
* **CreateSphere**( deviceContext, float diameter = 1, size_t tessellation = 16): Creates a uv-[sphere](http://wikipedia.org/wiki/Sphere) of given diameter with the given tessellation factor.
* **CreateTeapot**( deviceContext, float size = 1, size_t tessellation = 8): Creates the [Utah Teapot](http://en.wikipedia.org/wiki/Utah_teapot) of a given size and tessellation factor.
* **CreateTeapot**( deviceContext, float size = 1, size_t tessellation = 8): Creates the [Utah Teapot](http://wikipedia.org/wiki/Utah_teapot) of a given size and tessellation factor.
* **CreateTetrahedron**( deviceContext, float size = 1): Creates a [tetrahedron](http://en.wikipedia.org/wiki/Tetrahedron) of given size.
* **CreateTetrahedron**( deviceContext, float size = 1): Creates a [tetrahedron](http://wikipedia.org/wiki/Tetrahedron) of given size.
* **CreateTorus**( deviceContext, float diameter = 1, float thickness = 0.333f, size_t tessellation = 32): Creates a [torus](http://en.wikipedia.org/wiki/Torus) of given diameter, thickness, and tessellation factor.
* **CreateTorus**( deviceContext, float diameter = 1, float thickness = 0.333f, size_t tessellation = 32): Creates a [torus](http://wikipedia.org/wiki/Torus) of given diameter, thickness, and tessellation factor.
# Type aliases
@ -339,7 +339,7 @@ deviceContext->DrawIndexed(indexCount, 0, 0);
```
# Feature Level Notes
In order to support [all feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro), the GeometricPrimitive implementation make use of 16-bit indices (``DXGI_FORMAT_R16_UINT``) which limits to a maximum of 65535 vertices.
In order to support [all feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro), the GeometricPrimitive implementation make use of 16-bit indices (``DXGI_FORMAT_R16_UINT``) which limits to a maximum of 65535 vertices.
Feature Level 9.1 is also limited to a maximum of 65535 primitives in a single draw. This rules out using extremely large numbers for the tessellation factor, although the exact limit depends on the shape implementation.
@ -348,7 +348,7 @@ Note that these shapes tend to duplicate rather than share vertices in order to
# Threading model
Each GeometricPrimitive instance only supports drawing from one thread at a time, but you can simultaneously submit primitives on multiple threads if you create a separate GeometricPrimitive instance per Direct3D 11 deferred context.
[Immediate and Deferred Rendering](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-render-multi-thread-render)
[Immediate and Deferred Rendering](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-render-multi-thread-render)
# State management
@ -372,6 +372,6 @@ GeometricPrimitive makes use of the following states:
The GeometricPrimitive class assumes you've already set the Render Target view, Depth Stencil view, and Viewport.
# Remark
Tetrahedron, Cube/Hexahedron, Octahedron, Dodecahedron, and Icosahedron comprise the five [Platonic solids](https://en.wikipedia.org/wiki/Platonic_solid). The surface normals for these shapes are constructed as "face-normals" for faceted shading.
Tetrahedron, Cube/Hexahedron, Octahedron, Dodecahedron, and Icosahedron comprise the five [Platonic solids](https://wikipedia.org/wiki/Platonic_solid). The surface normals for these shapes are constructed as "face-normals" for faceted shading.
The *Utah Teapot* (also known as the *Newell Teapot*) is sometimes jokingly referred to as the "Sixth Platonic solid" due to its prevalence in rendering sample images. It was created in 1975 by Martin Newell at the University of Utah. It's become the "Hello, world" of 3D models hence why it's included as a basic geometric primitive shape in *DirectX Tool Kit*.

@ -6,27 +6,27 @@ This is the _Getting Started_ tutorial for _DirectX Tool Kit_ which introduces t
# Background
This tutorial assumes the reader is familiar with the basics of C++ programming using Microsoft Visual C++, including writing code, building applications, and basic debugging. Coding conventions here will make use of C++11 language features such as ``nullptr``, ``auto``, ranged-based ``for`` loops, simple _lambdas_ (aka anonymous functions), the standard smart-pointer ``std::unique_ptr`` / ``std::make_unique<T>()``, and ``std::function<>``. Familiarity with the Standard C++ Library ``std::wstring`` and the ``std::vector`` container are required as well.
* [Welcome back to C++ - Modern C++](https://docs.microsoft.com/en-us/cpp/cpp/welcome-back-to-cpp-modern-cpp)
* [C++ Language and Standard Libraries](https://docs.microsoft.com/en-us/cpp/cpp/c-cpp-language-and-standard-libraries)
* [Tools for Visual C++ Development](https://docs.microsoft.com/en-us/cpp/ide/ide-and-tools-for-visual-cpp-development)
* [Smart Pointers](https://docs.microsoft.com/en-us/cpp/cpp/smart-pointers-modern-cpp)
* [Welcome back to C++ - Modern C++](https://docs.microsoft.com/cpp/cpp/welcome-back-to-cpp-modern-cpp)
* [C++ Language and Standard Libraries](https://docs.microsoft.com/cpp/cpp/c-cpp-language-and-standard-libraries)
* [Tools for Visual C++ Development](https://docs.microsoft.com/cpp/ide/ide-and-tools-for-visual-cpp-development)
* [Smart Pointers](https://docs.microsoft.com/cpp/cpp/smart-pointers-modern-cpp)
* [[ComPtr]]
> If you are more comfortable with C#, then you should consider [SharpDX](http://sharpdx.org/) and [read this blog post](https://devblogs.microsoft.com/dotnet/choose-a-net-game-engine/).
This tutorial does not assume prior experience with Direct3D, but the reader should be familiar with the basic graphics concepts for DirectX or OpenGL. That said, you can get a long way using _DirectX Tool Kit_ without much in the way of graphics experience. You may also find it useful to review the _Programming Guide for Direct3D 11_ on [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/direct3d11/dx-graphics-overviews).
This tutorial does not assume prior experience with Direct3D, but the reader should be familiar with the basic graphics concepts for DirectX or OpenGL. That said, you can get a long way using _DirectX Tool Kit_ without much in the way of graphics experience. You may also find it useful to review the _Programming Guide for Direct3D 11_ on [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3d11/dx-graphics-overviews).
* [Getting Started with Direct3D 11](https://walbourn.github.io/getting-started-with-direct3d-11/)
* [Migrating to Direct3D 11](https://docs.microsoft.com/en-us/windows/win32/direct3d11/d3d11-programming-guide-migrating)
* [Migrating to Direct3D 11](https://docs.microsoft.com/windows/win32/direct3d11/d3d11-programming-guide-migrating)
> Note that Direct3D 11 and _DirectX Tool Kit_ are not Windows Runtime (aka "WinRT") components, so we do not make use of the C++/CX language extensions (a.k.a. ``/ZW`` switch) or C++/WinRT language projections, although it is compatible with both of those programming models. _DirectX Tool Kit_ is a 'pure' C++ library, which is why it's not directly usable by Visual Basic, C# or HTML+JavaScript applications.
# Error handling
One thing that many C++ developers, particularly game developers, may not be all that familiar with is "C++ Exception Handling". This is distinct from "Structured Exception Handling" (SEH) which some developers have seen in the past, and can leave an unfavorable impression of C++ EH. On both ARM and x64 native platforms, C++ EH is very efficient, although the x86 32-bit implementation does have some quirks. In any case, _DirectX Tool Kit_ uses C++ Exception Handling for most error conditions, just as the Standard Template Library (STL) does and the standard behavior of the operator ``new``.
* [Errors and Exception Handling](https://docs.microsoft.com/en-us/cpp/cpp/errors-and-exception-handling-modern-cpp)
* [C++ Exception Handling](https://docs.microsoft.com/en-us/cpp/cpp/cpp-exception-handling)
* [Exception Handling (Debugging)](https://docs.microsoft.com/en-us/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [Errors and Exception Handling](https://docs.microsoft.com/cpp/cpp/errors-and-exception-handling-modern-cpp)
* [C++ Exception Handling](https://docs.microsoft.com/cpp/cpp/cpp-exception-handling)
* [Exception Handling (Debugging)](https://docs.microsoft.com/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [[ThrowIfFailed]]
For debugging exceptions thrown by the _DirectX Tool Kit_, you should enable the checkbox next to ``std::exception`` in the Visual Studio Exception Settings dialog (_Debug_ -> _Windows_ -> _Exception Settings_). It's not on by default. Then select the "C++ Exceptions" line, right-click and select the <kbd>+</kbd> button, and type ``DirectX::com_exception`` to add that one. If working with the [Direct3D VS Game templates](https://github.com/walbourn/directx-vs-templates) you should do this once more typing ``DX::com_exception``.
@ -54,7 +54,7 @@ For learning purposes, these instructions are going to focus on the following se
We will be using a Win32 desktop application project template in order to support developers using Windows 7, but all these techniques and APIs apply to Universal Windows Platform apps and Xbox as well.
> There is no need to install the legacy DirectX SDK to use DirectX Tool Kit. The DirectX SDK is deprecated and you should not use it per [Microsoft Docs](https://docs.microsoft.com/en-us/windows/desktop/directx-sdk--august-2009-). See [this blog post](http://aka.ms/dxsdk), [The Zombie DirectX SDK](https://walbourn.github.io/the-zombie-directx-sdk/), [DirectX SDK Samples Catalog](https://walbourn.github.io/directx-sdk-samples-catalog/), and [DirectX SDK Tools Catalog](https://walbourn.github.io/directx-sdk-tools-catalog/).
> There is no need to install the legacy DirectX SDK to use DirectX Tool Kit. The DirectX SDK is deprecated and you should not use it per [Microsoft Docs](https://docs.microsoft.com/windows/win32/directx-sdk--august-2009-). See [this blog post](http://aka.ms/dxsdk), [The Zombie DirectX SDK](https://walbourn.github.io/the-zombie-directx-sdk/), [DirectX SDK Samples Catalog](https://walbourn.github.io/directx-sdk-samples-catalog/), and [DirectX SDK Tools Catalog](https://walbourn.github.io/directx-sdk-tools-catalog/).
## Visual Studio 2019 / 2022
When using the [new lightweight installer](https://devblogs.microsoft.com/cppblog/the-lightweight-visual-studio-15-installer/) be sure to select the appropriate workloads:

@ -18,7 +18,7 @@ std::unique_ptr<GraphicsMemory> graphicsMemory;
graphicsMemory = std::make_unique<GraphicsMemory>(device, backBufferCount);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
# Present
The graphics memory helper manages memory allocation for 'in-flight' data shared between the CPU and GPU. After each frame is rendered, the application needs to call **Commit** to let the manager know that a frame's worth of video memory has been sent to the GPU. This allows the manager to check to see if a previous frame's data is complete and can be released.

@ -20,7 +20,7 @@ effect->SetFogEnd(8);
effect->SetFogColor( Colors::CornflowerBlue );
```
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://en.wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
```cpp
std::shared_ptr<IEffect> effect;

@ -20,7 +20,7 @@ static const XMVECTORF32 light { 0.f, -1.f, 0.f, 0.f };
effect->SetLightDirection( 0, light );
```
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://en.wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
```cpp
std::shared_ptr<IEffect> effect;

@ -23,7 +23,7 @@ If you are setting all three matrices at once, you can use:
effect->SetMatrices(world, view, projection);
```
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://en.wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
```cpp
std::shared_ptr<IEffect> effect;

@ -18,7 +18,7 @@ std::shared_ptr<SkinnedEffect> effect;
effect->SetBoneTransforms( bones.get(), boneCount );
```
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://en.wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
For more general cases where a number of effect classes can be in use (such as [[Model]] which uses a mix of _BasicEffect_, _DualTextureEffect_, _SkinnedEffect_, and/or _DGSLEffect_), use [Run-Time Type Information](https://wikipedia.org/wiki/Run-time_type_information) (RTTI) to obtain the interface.
```cpp
std::shared_ptr<IEffect> effect;

@ -15,13 +15,13 @@ For clang/LLVM for Windows, there is a ``CMakeList.txt`` provided to validate th
# Naming conventions
While the _DirectX Tool Kit_ design is heavily influenced by the XNA Game Studio framework C# object design, it uses C++ conventions consistent with modern Win32 APIs rather than the strict .NET use of [PascalCase](https://en.wikipedia.org/wiki/CamelCase) as enforced by FXCop.
While the _DirectX Tool Kit_ design is heavily influenced by the XNA Game Studio framework C# object design, it uses C++ conventions consistent with modern Win32 APIs rather than the strict .NET use of [PascalCase](https://wikipedia.org/wiki/CamelCase) as enforced by FXCop.
* PascalCase for class names, methods, functions, and enums.
* camelCase for class member variables, struct members
* UPPERCASE for preprocessor defines (and nameless enums)
The library does not generally make use of [Hungarian notation](https://en.wikipedia.org/wiki/Hungarian_notation) which as been deprecated for Win32 C++ APIs for many years, with the exception of a few uses of ``p`` for pointers and ``sz`` for strings.
The library does not generally make use of [Hungarian notation](https://wikipedia.org/wiki/Hungarian_notation) which as been deprecated for Win32 C++ APIs for many years, with the exception of a few uses of ``p`` for pointers and ``sz`` for strings.
# Type usage
@ -101,7 +101,7 @@ if ((sampleRate < XAUDIO2_MIN_SAMPLE_RATE) || (sampleRate > XAUDIO2_MAX_SAMPLE_R
The _DirectX Toolkit_ library makes extensive use of SAL2 annotations (``_In_``, ``_Outptr_opt_``, etc.) which greatly improves the accuracy of the Visual C++ static code analysis (also known as PREFAST). The standard Windows headers ``#define`` them all to empty strings if not building with ``/analyze``, so they have no effect on code-generation.
# The pImpl idiom
DirectXTK's implementation makes extensive use of the [pImpl idiom](http://en.wikipedia.org/wiki/Opaque_pointer). This keeps the public headers slim and minimizes inter-module dependencies.
DirectXTK's implementation makes extensive use of the [pImpl idiom](http://wikipedia.org/wiki/Opaque_pointer). This keeps the public headers slim and minimizes inter-module dependencies.
```cpp
// SpriteBatch.h public header
@ -184,7 +184,7 @@ Rectangle& operator= (Rectangle&&) = default;
> Note that use of ``= default`` can improve codegen for derived types as well.
# DirectXMath Parameter Conventions
The library uses the [DirectXMath](https://docs.microsoft.com/en-us/windows/desktop/dxmath/pg-xnamath-internals#Call_Conventions) calling convention types to improve parameter passing of ``XMVECTOR`` and ``XMMATRIX`` types.
The library uses the [DirectXMath](https://docs.microsoft.com/windows/win32/dxmath/pg-xnamath-internals#Call_Conventions) calling convention types to improve parameter passing of ``XMVECTOR`` and ``XMMATRIX`` types.
# Further Reading
[Dual-use Coding Techniques for Games](https://aka.ms/Fo3su4)

@ -20,7 +20,7 @@ std::unique_ptr<Keyboard> keyboard;
keyboard = std::make_unique<Keyboard>();
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
# Integration
@ -150,7 +150,7 @@ Most of the ``Oem*`` values vary based on country/region, but you can count on `
> If accidentally pressing the <kbd>Windows</kbd> key or triggering the Windows Accessibility hotkeys is a common problem for your control scheme, see [Disabling Shortcut Keys in Games](https://docs.microsoft.com/windows/win32/dxtecharts/disabling-shortcut-keys-in-games).
For more information on virtual keys, see [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes).
For more information on virtual keys, see [Microsoft Docs](https://docs.microsoft.com/windows/win32/inputdev/virtual-key-codes).
# Keyboard state tracker
@ -198,8 +198,8 @@ Keep in mind when designing the keyboard controls for your game the different la
The Keyboard class makes use of virtual keys and not scancodes so your code has to be aware of these layout differences.
[QWERTY](https://en.wikipedia.org/wiki/QWERTY), [QWERTZ](https://en.wikipedia.org/wiki/QWERTZ), [AZERTY](https://en.wikipedia.org/wiki/AZERTY), [QZERTY](https://en.wikipedia.org/wiki/Keyboard_layout#QZERTY)
[QWERTY](https://wikipedia.org/wiki/QWERTY), [QWERTZ](https://wikipedia.org/wiki/QWERTZ), [AZERTY](https://wikipedia.org/wiki/AZERTY), [QZERTY](https://wikipedia.org/wiki/Keyboard_layout#QZERTY)
# Further reading
[DirectX Tool Kit: Keyboard and Mouse support](https://walbourn.github.io/directx-tool-kit-keyboard-and-mouse-support/)
[Using Keyboard Input](https://docs.microsoft.com/en-us/windows/desktop/inputdev/using-keyboard-input)
[Using Keyboard Input](https://docs.microsoft.com/windows/win32/inputdev/using-keyboard-input)

@ -17,7 +17,7 @@ DirectXTK makes use of the latest Direct3D 11.1 headers available in the Windows
[KB2728613](http://support.microsoft.com/kb/2728613)
[Where is the DirectX SDK?](https://docs.microsoft.com/en-us/windows/desktop/directx-sdk--august-2009-)
[Where is the DirectX SDK?](https://docs.microsoft.com/windows/win32/directx-sdk--august-2009-)
> When using the legacy DirectX SDK you need to set up VC++ Directories paths in your project (particularly your EXE/DLL). For the Windows 8.1 SDK or Windows 10 SDK, you need to set up those paths in _reverse_ order from previous include orders. You really only need a small portion of the legacy DirectX SDK for XAudio 2.7, and want to be using the Windows 8.1 SDK / Windows 10 SDK for everything else. For more details see [The Zombie DirectX SDK](https://aka.ms/AA4gfea).
@ -60,12 +60,12 @@ Click "Apply".
![VC++ Directories (x64)](https://github.com/Microsoft/DirectXTK/wiki/images/settingsDXx64.png)
It is important that the legacy DirectX SDK paths be after the existing path since are making use of the Windows 8.1 / 10 SDK. See [Where is the DirectX SDK?](https://docs.microsoft.com/en-us/windows/desktop/directx-sdk--august-2009-) for more details.
It is important that the legacy DirectX SDK paths be after the existing path since are making use of the Windows 8.1 / 10 SDK. See [Where is the DirectX SDK?](https://docs.microsoft.com/windows/win32/directx-sdk--august-2009-) for more details.
<details><summary><i>Click here for troubleshooting advice</i></summary>
<p>If you get a compilation error indicating you are missing "comdecl.h", there are two possible reasons:
<ul><li>You have incorrectly configured your VC++ Directory include paths. If you get a link error indicating you are missing <code>x3daudio.lib</code>, then you incorrectly configured your VC++ Directory library paths.</li>
<li>You have incorrectly configured the ``_WIN32_WINNT`` variable. See <a href="https://docs.microsoft.com/en-us/windows/desktop/WinProg/using-the-windows-headers">Using the Windows Headers</a></li></ul></p></details>
<li>You have incorrectly configured the ``_WIN32_WINNT`` variable. See <a href="https://docs.microsoft.com/windows/win32/winprog/using-the-windows-headers">Using the Windows Headers</a></li></ul></p></details>
# Deployment

@ -127,7 +127,7 @@ m_world = Matrix::CreateRotationY(cosf(static_cast<float>(timer.GetTotalSeconds(
Build and run to see the grid spinning, and notice the slight shimmering of the lines--it will be more obvious if you maximize the window size.
There are two approaches to addressing this problem, known as [aliasing](https://en.wikipedia.org/wiki/Aliasing).
There are two approaches to addressing this problem, known as [aliasing](https://wikipedia.org/wiki/Aliasing).
## Anti-aliased lines
The first is to enable a special anti-aliasing mode specific to line drawing in Direct3D.
@ -174,7 +174,7 @@ Build and run to see the shimmering of the lines lessen, although they will appe
![Screenshot of the AA grid](https://github.com/Microsoft/DirectXTK/wiki/images/screenshotGridAA.PNG)
## Multisampling
A second more general solution is to use [Multisample anti-aliasing](https://en.wikipedia.org/wiki/Multisample_anti-aliasing) (MSAA) which uses more video memory and pixel-fill performance to achieve higher quality rendering results. In this case, we will make use of 4x MSAA where the render target and the depth buffer will be 4 times larger. MSAA can be used with all primitives, not just lines.
A second more general solution is to use [Multisample anti-aliasing](https://wikipedia.org/wiki/Multisample_anti-aliasing) (MSAA) which uses more video memory and pixel-fill performance to achieve higher quality rendering results. In this case, we will make use of 4x MSAA where the render target and the depth buffer will be 4 times larger. MSAA can be used with all primitives, not just lines.
In the **Game.h** file, add the following variables to the bottom of the Game class's private declarations:
@ -295,7 +295,7 @@ Build and run to see the shimmering of the lines lessen compared to the first ve
![Screenshot of the MSAA grid](https://github.com/Microsoft/DirectXTK/wiki/images/screenshotGridMSAA.PNG)
<details><summary><i>Click here for troubleshooting advice</i></summary>
<p>If you get an exception, it may be because your device does not support 4x MSAA--which you can confirm by checking the debug device output at the failure point. Direct3D Feature Level 10.1 or later devices all support 4x MSAA for most render target formats, but some 10.0 and 9.x feature levels do not. You can try setting <code>MSAA_COUNT</code> to 2 if this happens. If you have a Feature Level 11.0 or later device, you can try using 4 or 8 for <code>MSAA_COUNT</code>. See also <a href="https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11device-checkmultisamplequalitylevels">CheckMultisampleQualityLevels</a></p></details>
<p>If you get an exception, it may be because your device does not support 4x MSAA--which you can confirm by checking the debug device output at the failure point. Direct3D Feature Level 10.1 or later devices all support 4x MSAA for most render target formats, but some 10.0 and 9.x feature levels do not. You can try setting <code>MSAA_COUNT</code> to 2 if this happens. If you have a Feature Level 11.0 or later device, you can try using 4 or 8 for <code>MSAA_COUNT</code>. See also <a href="https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11device-checkmultisamplequalitylevels">CheckMultisampleQualityLevels</a></p></details>
> If you are using a Direct3D Feature Level 9.x device, you will also need to use ``DXGI_FORMAT_D24_UNORM_S8_UINT`` instead of ``DXGI_FORMAT_D32_FLOAT`` as the depth/stencil format.
@ -319,6 +319,6 @@ See [this blog series](https://walbourn.github.io/care-and-feeding-of-modern-swa
# Further reading
DirectX Tool Kit docs [[CommonStates]], [[Effects]], [[PrimitiveBatch]], [[VertexTypes]]
[FXAA](https://en.wikipedia.org/wiki/Fast_approximate_anti-aliasing)
[FXAA](https://wikipedia.org/wiki/Fast_approximate_anti-aliasing)
[SMAA](http://www.iryoku.com/smaa/)
[Spatial anti-alising](https://en.wikipedia.org/wiki/Spatial_anti-aliasing)
[Spatial anti-alising](https://wikipedia.org/wiki/Spatial_anti-aliasing)

@ -12,7 +12,7 @@ See [[SpriteFont]]
**Related tutorial:** [[Drawing text]]
# TrueType
Open a [Command Prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq), and change to the directory containing ``MakeSpriteFont.exe`` (i.e. ``...\DirectXTK\MakeSpriteFont\bin\Release``)
Open a Command Prompt, and change to the directory containing ``MakeSpriteFont.exe`` (i.e. ``...\DirectXTK\MakeSpriteFont\bin\Release``)
Enter the following command-line after changing to the appropriate directory:
@ -92,7 +92,7 @@ Examples:
* Dumps the generated texture to a bitmap file (useful when debugging the MakeSpriteFont tool, not so much if you are just trying to use it).
# Localization
Since all glyphs specified are captured into a texture, the SpriteFont solution is very effective for smaller character sets. For large character sets such as Chinese, Japanese, or Korean, capturing every possible glyph is extremely slow, and the resulting texture is extremely large possibly exceeding the size supported by your target [Direct3D hardware feature level](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro). For these large character sets, using DirectWrite to render glyphs on-the-fly is a better solution.
Since all glyphs specified are captured into a texture, the SpriteFont solution is very effective for smaller character sets. For large character sets such as Chinese, Japanese, or Korean, capturing every possible glyph is extremely slow, and the resulting texture is extremely large possibly exceeding the size supported by your target [Direct3D hardware feature level](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro). For these large character sets, using DirectWrite to render glyphs on-the-fly is a better solution.
For cases where DirectWrite is not supported (such as Windows phone 8.0 and Xbox One exclusive apps) and/or when rendering a set of static localized text, another solution is to scan all your translated text and capture only those character regions actually used by your application's specific display strings.
@ -130,4 +130,4 @@ To aid in debugging, here is a [simple console program](https://raw.githubuserco
# Further reading
[Knapsack problem](http://en.wikipedia.org/wiki/Knapsack_problem)
[Knapsack problem](http://wikipedia.org/wiki/Knapsack_problem)

@ -12,13 +12,13 @@ First create a new project using the instructions from the earlier lessons: [[Us
In the previous tutorial we loaded the individual sound files as distinct **SoundEffect** objects, but games commonly have hundreds or thousands of distinct sounds, music, and voice recordings. A more efficient way to manage this data is to make of a 'wave bank' which is a single file that contains a collection of ``.wav ``files that can be loaded all at once.
_DirectX Tool Kit for Audio_ supports "wave banks" which were created for the Cross-platform Audio Creation Tool ([XACT](https://en.wikipedia.org/wiki/Cross-platform_Audio_Creation_Tool)) from the legacy DirectX SDK. It makes no use of "sound banks" or "cues".
_DirectX Tool Kit for Audio_ supports "wave banks" which were created for the Cross-platform Audio Creation Tool ([XACT](https://wikipedia.org/wiki/Cross-platform_Audio_Creation_Tool)) from the legacy DirectX SDK. It makes no use of "sound banks" or "cues".
# Creating wave bank files
1. Download the [XWBTool.exe](https://github.com/microsoft/DirectXTK/releases/latest/download/XWBTool.exe) from the _DirectX Tool Kit_ site and extract the EXE into your project's folder.
1. Download these media files to your project's folder [Explo1.wav](https://github.com/Microsoft/DirectXTK/wiki/media/Explo1.wav), [Explo2.wav](https://github.com/Microsoft/DirectXTK/wiki/media/Explo2.wav), [Explo3.wav](https://github.com/Microsoft/DirectXTK/wiki/media/Explo3.wav), [Explo4.wav](https://github.com/Microsoft/DirectXTK/wiki/media/Explo4.wav), [NightAmbienceSimple_02.wav](https://github.com/Microsoft/DirectXTK/wiki/media/NightAmbienceSimple_02.wav).
1. Open a [command-prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq) and then change to your project's folder.
1. Open a Command Prompt and then change to your project's folder.
> These ``.wav`` files are from the _XNA Game Studio_ [SoundLab](https://github.com/SimonDarksideJ/XNAGameStudio/wiki/SoundLab) which provides a small collection of sounds under the [MS-PL](http://opensource.org/licenses/MS-PL) license.

@ -1,9 +1,9 @@
|[[DirectXTK]]|[[SimpleMath]]|
|---|---|
A four by four row-major [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) modeled after the XNA Game Studio 4 (``Microsoft.Xna.Framework.Matrix``) math library.
A four by four row-major [matrix](https://wikipedia.org/wiki/Matrix_(mathematics)) modeled after the XNA Game Studio 4 (``Microsoft.Xna.Framework.Matrix``) math library.
A 4x4 *matrix* is commonly used in computer graphics for 2D and 3D [transformations](https://en.wikipedia.org/wiki/Transformation_matrix).
A 4x4 *matrix* is commonly used in computer graphics for 2D and 3D [transformations](https://wikipedia.org/wiki/Transformation_matrix).
# Header
```cpp
@ -70,11 +70,11 @@ Matrix m( arr ); // Creates a matrix [1 2 3 0
* **Decompose**: Decomposes the matrix into rotation (a [[Quaternion]]), scaling, and translation components. Returns ``false`` if the matrix can't be decomposed.
* **Transpose**: Computes the [transpose](https://en.wikipedia.org/wiki/Transpose) of the matrix. Note that for a pure rotation matrix, this is the same as the inverse.
* **Transpose**: Computes the [transpose](https://wikipedia.org/wiki/Transpose) of the matrix. Note that for a pure rotation matrix, this is the same as the inverse.
* **Invert**: Computes the inverse of the matrix using [Cramer's rule](https://en.wikipedia.org/wiki/Cramer%27s_rule). It returns ``false`` if the matrix is not invertible.
* **Invert**: Computes the inverse of the matrix using [Cramer's rule](https://wikipedia.org/wiki/Cramer%27s_rule). It returns ``false`` if the matrix is not invertible.
* **Determinant**: Computes the [determinant](https://en.wikipedia.org/wiki/Determinant) of the matrix.
* **Determinant**: Computes the [determinant](https://wikipedia.org/wiki/Determinant) of the matrix.
* **ToEuler**: Computes rotation about y-axis (y), then x-axis (x), then z-axis (z) as angles in radians. The return value is compatible with one of the overloads of ``CreateFromYawPitchRoll``. This result is only valid if the input matrix's upper 3x3 contains only rotation (i.e. no scaling).
@ -88,7 +88,7 @@ Matrix m( arr ); // Creates a matrix [1 2 3 0
* **CreateScale**: Creates a matrix for scaling by the given X, Y, and Z scale factors. Note you can create the inverse of this matrix by passing 1/X, 1/Y, 1/Z.
* **CreateRotationX**, **CreateRotationY**, **CreateRotationZ**: Creates a matrix for rotation about the x-axis / y-axis / z-axis by angle given in [radians](https://en.wikipedia.org/wiki/Radian).
* **CreateRotationX**, **CreateRotationY**, **CreateRotationZ**: Creates a matrix for rotation about the x-axis / y-axis / z-axis by angle given in [radians](https://wikipedia.org/wiki/Radian).
* **CreateFromAxisAngle**: Creates a matrix a rotation about a given 3-vector axis and an angle given in radians.
@ -98,7 +98,7 @@ Matrix m( arr ); // Creates a matrix [1 2 3 0
* **CreateLookAt**: Creates a look-at matrix in right-handed (RH) coordinates
> For Left-Handed (LH) viewing coordinates, you can use the [DirectXMath](https://docs.microsoft.com/en-us/windows/win32/dxmath/ovw-xnamath-reference-functions-matrix) functions directly which interop freely with ``Matrix``.
> For Left-Handed (LH) viewing coordinates, you can use the [DirectXMath](https://docs.microsoft.com/windows/win32/dxmath/ovw-xnamath-reference-functions-matrix) functions directly which interop freely with ``Matrix``.
* **CreateWorld**

@ -27,7 +27,7 @@ m_proj = XMMatrixPerspectiveFovLH( XM_PI / 4.f,
Many 'handed' _DirectX Tool Kit_ functions take a bool parameter _rhcoords_ that defaults to true. You should pass false when using left-handed view coordinates.
[Right-hand Rule](http://en.wikipedia.org/wiki/Right-hand_rule)
[Right-hand Rule](http://wikipedia.org/wiki/Right-hand_rule)
# Constants
@ -60,7 +60,7 @@ m_view = Matrix::CreateLookAt( s_lookat, Vector3::Zero, Vector3::UnitY);
# Fresnel term
Because of the free conversion of SimpleMath types, you can easily mix existing SimpleMath code with DirectXMath functions. For example, the [XMFresnelTerm](https://docs.microsoft.com/en-us/windows/desktop/api/directxmath/nf-directxmath-xmfresnelterm) function doesn't have a SimpleMath equivalent:
Because of the free conversion of SimpleMath types, you can easily mix existing SimpleMath code with DirectXMath functions. For example, the [XMFresnelTerm](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmfresnelterm) function doesn't have a SimpleMath equivalent:
```cpp
Vector3 fresnel = XMFresnelTerm( Vector4( a1, a2, a3, a4 ),
@ -87,7 +87,7 @@ for ( size_t h = 0; h < height; ++h )
}
```
[DirectXMath Library Internals](https://docs.microsoft.com/en-us/windows/desktop/dxmath/pg-xnamath-internals)
[DirectXMath Library Internals](https://docs.microsoft.com/windows/win32/dxmath/pg-xnamath-internals)
**Next lesson:** [[Adding the DirectX Tool Kit for Audio]]

@ -232,7 +232,7 @@ The various ``CreateFrom*`` methods have a defaulted parameter to provide additi
* ``ModelLoader_DisableSkinning``: Normally the presence of bone indices in the model file indicate that skinning effects should be used. If this flag is set, non-skinning effects are always used. *Some legacy SDKMESH models contain more bone influences than ``IEffectSkinning::MaxBones`` (72) can support, and these models render incorrectly. The use of this flag can at least render those as rigid models correctly.*
# Feature Level Notes
If any ModelMeshPart makes use of 32-bit indices (i.e. ModelMeshPart:: indexFormat equals ``DXGI_FORMAT_R32_UINT``) rather than 16-bit indices (``DXGI_FORMAT_R16_UINT``), then that model requires [Feature Level](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro) 9.2 or greater.
If any ModelMeshPart makes use of 32-bit indices (i.e. ModelMeshPart:: indexFormat equals ``DXGI_FORMAT_R32_UINT``) rather than 16-bit indices (``DXGI_FORMAT_R16_UINT``), then that model requires [Feature Level](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro) 9.2 or greater.
If any ModelMeshPart uses adjacency (i.e. ModelMeshPart::primitiveType equals ``D3D_PRIMITIVE_TOPOLOGY_*_ADJ``), then that model requires Feature Level 10.0 or greater. If using tessellation (i.e. ``D3D_PRIMITIVE_TOPOLOGY_?_CONTROL_POINT_PATCHLIST``), then that model requires Feature Level 11.0 or greater.

@ -49,7 +49,7 @@ Each bone contains three pointers:
These pointers are used to form a tree hierarchy. The 0th bone in a Model is the root and should have a *parentIndex* of ``ModelBone::c_Invalid``.
> Note that bones must form an [acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph).
> Note that bones must form an [acyclic graph](https://wikipedia.org/wiki/Directed_acyclic_graph).
# Working with bones

@ -97,7 +97,7 @@ In addition to the list of ModelMeshPart instances that make up the mesh, a Mode
It includes a bool to indicate if the mesh should be rendered using counter-clockwise winding or clockwise winding (_ccw_), as well as a bool to indicate if the mesh should be rendered with premultiplied alpha blending or 'straight' alpha blending (_pmalpha_).
A ModelMesh also includes bounding information for culling & collision detection in the form of a [BoundingSphere](http://msdn.microsoft.com/en-us/library/windows/desktop/microsoft.directx_sdk.directxcollision.boundingsphere.aspx) and a [BoundingBox](https://docs.microsoft.com/en-us/windows/desktop/api/directxcollision/ns-directxcollision-boundingbox).
A ModelMesh also includes bounding information for culling & collision detection in the form of a [BoundingSphere](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere) and a [BoundingBox](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingbox).
The choice of frame-of-reference for these bounding volumes is up to the Model loader, but is typically in 'local' coordinates.

@ -22,23 +22,23 @@ ModelMeshPart instances are typically created by a Model loader along with the M
# Data
All members of ModelMeshPart are public to facilitate writing custom model loaders and sophisticated rendering solutions. Care should be taken whenever modifying any of these elements as they have interdependencies, and can ultimately be referenced by numerous instances of Model via shared ModelMesh instances.
* _indexCount_ - Number of indices in the index buffer associated with this submesh. This is used as the first parameter to Direct3D11's [DrawIndexed](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11devicecontext-drawindexed) method.
* _indexCount_ - Number of indices in the index buffer associated with this submesh. This is used as the first parameter to Direct3D11's [DrawIndexed](https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-drawindexed) method.
* _startIndex_ - The index to start drawing with for this submesh. This facilitates sharing index buffers between multiple submeshes. This is used as the second parameter to Direct3D11's ``DrawIndexed`` method.
* _vertexOffset_ - base vertex location which is added to each index in the index buffer before referencing the vertex buffer. This facilitates sharing of vertex buffers between multiple submeshes. This is used as the third parameter to Direct3D11's ``DrawIndexed`` method.
* _vertexBuffer_ - COM smart pointer to the vertex buffer associated with this submesh. This is used when calling Direct3D 11's [IASetVertexBuffers](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11devicecontext-iasetvertexbuffers) method. This vertex buffer can be shared by multiple submeshes or even other meshes.
* _vertexBuffer_ - COM smart pointer to the vertex buffer associated with this submesh. This is used when calling Direct3D 11's [IASetVertexBuffers](https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-iasetvertexbuffers) method. This vertex buffer can be shared by multiple submeshes or even other meshes.
* _vertexStride_ - Stride in bytes for each vertex in the vertex buffer associated with this submesh. This is used when calling Direct3D 11's ``IASetVertexBuffers`` method.
* _indexBuffer_ - COM smart pointer to the index buffer associated with this submesh. This is used when calling Direct3D11's [IASetIndexBuffer](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11devicecontext-iasetindexbuffer) method. This index buffer can be shared by multiple submeshes or even other meshes.
* _indexBuffer_ - COM smart pointer to the index buffer associated with this submesh. This is used when calling Direct3D11's [IASetIndexBuffer](https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-iasetindexbuffer) method. This index buffer can be shared by multiple submeshes or even other meshes.
* _indexFormat_ - Format of the index buffer. For 16-bit index buffers, this is set to ``DXGI_FORMAT_R16_UINT``. For 32-bit index buffers, this is set to ``DXGI_FORMAT_R32_UINT``. This is used when calling Direct3D11's ``IASetIndexBuffer`` method.
* _primitiveType_ - Topology for the primitives in the submesh. It is usually set to ``D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST`` with each three indices in the index buffer forming a triangle. This is used when calling Direct3D11's [IASetPrimitiveTopology](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11devicecontext-iasetprimitivetopology) method.
* _primitiveType_ - Topology for the primitives in the submesh. It is usually set to ``D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST`` with each three indices in the index buffer forming a triangle. This is used when calling Direct3D11's [IASetPrimitiveTopology](https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-iasetprimitivetopology) method.
* _inputLayout_ - COM smart pointer to the input layout associated with this submesh. This is used when calling Direct3D11's [IASetInputLayout](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/nf-d3d11-id3d11devicecontext-iasetinputlayout) method. This must correctly match the signature of the effect and match the vertex data format in the vertex buffer.
* _inputLayout_ - COM smart pointer to the input layout associated with this submesh. This is used when calling Direct3D11's [IASetInputLayout](https://docs.microsoft.com/windows/win32/api/d3d11/nf-d3d11-id3d11devicecontext-iasetinputlayout) method. This must correctly match the signature of the effect and match the vertex data format in the vertex buffer.
* _effect_ - An [[IEffect|Effects]] instance which is used to set up the proper constant buffer and shader states before drawing the submesh.

@ -163,7 +163,7 @@ These lessons on SpriteBatch only begin to show the many techniques you can impl
* The *transformationMatrix* parameter to ``Begin`` lets you provide a custom transformation for the sprite renderering. This is combined with the viewport-based final view transform, but if you use ``SetRotation( DXGI_MODE_ROTATION_UNSPECIFIED )`` this will be disabled. The default value for this parameter is the _identity matrix_.
* You can use [custom sampler states](https://github.com/Microsoft/DirectXTK/wiki/SpriteBatch#custom-render-states) for special effects utilizing [texture addressing](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ne-d3d11-d3d11_texture_address_mode). You can also achieve a 'pixel art' look by using ``CommonStates::PointClamp``.
* You can use [custom sampler states](https://github.com/Microsoft/DirectXTK/wiki/SpriteBatch#custom-render-states) for special effects utilizing [texture addressing](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_texture_address_mode). You can also achieve a 'pixel art' look by using ``CommonStates::PointClamp``.
**Next lesson:** [[Drawing text]]

@ -408,7 +408,7 @@ Build and run. Now in addition to keyboard controls, you can press & hold the le
* We rotate the movement vector created by the keyboard commands by the pitch/yaw values so that they are relative to the view direction rather than be fixed in world coordinates.
* The view can never be exactly straight up or straight down to avoid a problem known as
[gimbal lock](https://en.wikipedia.org/wiki/Gimbal_lock) which can cause the camera view to flip unexpectedly or tumble uncontrollably.
[gimbal lock](https://wikipedia.org/wiki/Gimbal_lock) which can cause the camera view to flip unexpectedly or tumble uncontrollably.
* This control implementation is very simple, and really only works on a system with fast frame-rate. For a more robust implementation, the ``Update`` code should make use of ``elapsedTime`` to scale the keyboard movement rate values and ``ROTATION_GAIN`` / ``MOVEMENT_GAIN`` adjusted accordingly.

@ -20,7 +20,7 @@ std::unique_ptr<Mouse> mouse;
mouse = std::make_unique<Mouse>();
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr``.
# Integration
@ -277,12 +277,12 @@ The Mouse class should be thread-safe with the exception of the **ProcessMessage
# Platform notes
For Universal Windows Platform apps, touch/pointer devices are captured as [mouse movement](https://docs.microsoft.com/en-us/windows/uwp/gaming/tutorial--adding-touch-controls-to-your-directx-game). Touch/pointer devices do not, however, result in changes to button state. Relative mouse movement is captured per this [Microsoft Docs](https://docs.microsoft.com/en-us/windows/uwp/gaming/relative-mouse-movement) article.
For Universal Windows Platform apps, touch/pointer devices are captured as [mouse movement](https://docs.microsoft.com/windows/uwp/gaming/tutorial--adding-touch-controls-to-your-directx-game). Touch/pointer devices do not, however, result in changes to button state. Relative mouse movement is captured per this [Microsoft Docs](https://docs.microsoft.com/windows/uwp/gaming/relative-mouse-movement) article.
> For UWP applications on Xbox One, the game controller can be made to emulate a mouse which will provide input through the Mouse class, but the input paradigm is more natural if you use the [[GamePad]] class directly.
For Windows desktop apps, relative mouse movement is captured using "raw input" per the article [Taking Advantage of High-Definition Mouse Movement](https://docs.microsoft.com/en-us/windows/desktop/DxTechArts/taking-advantage-of-high-dpi-mouse-movement). Note that a consequence of this implementation is that relative mouse movement is not available when using the application through Remote Desktop.
For Windows desktop apps, relative mouse movement is captured using "raw input" per the article [Taking Advantage of High-Definition Mouse Movement](https://docs.microsoft.com/windows/win32/dxtecharts/taking-advantage-of-high-dpi-mouse-movement). Note that a consequence of this implementation is that relative mouse movement is not available when using the application through Remote Desktop.
# Further reading
[DirectX Tool Kit: Keyboard and Mouse support](https://walbourn.github.io/directx-tool-kit-keyboard-and-mouse-support/)
[Mouse Input](https://docs.microsoft.com/en-us/windows/desktop/inputdev/mouse-input)
[Mouse Input](https://docs.microsoft.com/windows/win32/inputdev/mouse-input)

@ -25,7 +25,7 @@ std::unique_ptr<SkinnedNormalMapEffect> effect;
effect = std::make_unique<SkinnedNormalMapEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
@ -81,7 +81,7 @@ The normal map textures used by this effect are assumed to be ``_UNORM`` formats
The red (x) and green (y) channels are loaded from the texture, but blue (z) and alpha (w) channels are unused. The shader reconstructs the z component of the normal using ``z = sqrt( 1 - dot( xy, xy ) )``. This has two positive benefits:
1. You can make use the ``DXGI_FORMAT_BC5_UNORM`` (i.e. [3Dc](https://en.wikipedia.org/wiki/3Dc)) for normal map texture compression without any shader or configuration changes.
1. You can make use the ``DXGI_FORMAT_BC5_UNORM`` (i.e. [3Dc](https://wikipedia.org/wiki/3Dc)) for normal map texture compression without any shader or configuration changes.
1. Due to quantization effects, the actual unit length of the normal can drift, so this reconstruction can improve quality by effectively renormalizing the value.
Finally, the green (y) channel is used "as is" in the shader code. Some viewing and materials conventions can require the green channel to be inverted to properly 'push in' or 'push out'. This issue should be handled by modifying the texture content either offline or at load time. _Because the shader reconstructs the z channel, an inverted y channel can result in black pixels on the model if it's backwards._
@ -90,7 +90,7 @@ Finally, the green (y) channel is used "as is" in the shader code. Some viewing
# Remarks
This effect implements the classic diffuse [Lambertian](https://en.wikipedia.org/wiki/Lambertian_reflectance) shading with [Phong](https://en.wikipedia.org/wiki/Phong_reflection_model) specular highlights lighting model with the addition of per-pixel normals and lighting. Optionally the specular highlights can be implemented as a specular map.
This effect implements the classic diffuse [Lambertian](https://wikipedia.org/wiki/Lambertian_reflectance) shading with [Phong](https://wikipedia.org/wiki/Phong_reflection_model) specular highlights lighting model with the addition of per-pixel normals and lighting. Optionally the specular highlights can be implemented as a specular map.
Calls to ``SetLightingEnabled(false);`` will generate a C++ exception, and calls to **SetPerPixelLighting** are ignored.
@ -115,7 +115,7 @@ This effect uses Shader Model 4.0 so requires Direct3D hardware feature level 10
> Note this means you can also count on ``DXGI_FORMAT_BC5_UNORM`` texture compression hardware support for your normal maps.
[Direct3D feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
[Direct3D feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
# Further reading

@ -1,7 +1,7 @@
|[[DirectXTK]]|[[Effects]]|
|---|---|
**PBREffect** implements a Disney-style (Roughness/Metalness workflow) Physically-Based Renderer ([PBR](https://en.wikipedia.org/wiki/Physically_based_rendering)) effect using Image-Based Lighting ([IBL](https://en.wikipedia.org/wiki/Image-based_lighting)) in combination with up to three directional lights. This effect also supports GPU instancing.
**PBREffect** implements a Disney-style (Roughness/Metalness workflow) Physically-Based Renderer ([PBR](https://wikipedia.org/wiki/Physically_based_rendering)) effect using Image-Based Lighting ([IBL](https://wikipedia.org/wiki/Image-based_lighting)) in combination with up to three directional lights. This effect also supports GPU instancing.
**SkinnedPBREffect** extends ``PBREffect`` to support vertex skinning. The skinned effect does not support velocity buffer generation or GPU instancing.
@ -29,7 +29,7 @@ std::unique_ptr<SkinnedPBREffect> effect;
effect = std::make_unique<SkinnedPBREffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces
PBREffect supports [[IEffect]], [[IEffectMatrices]], and [[IEffectLights]].
@ -127,7 +127,7 @@ These effects use Shader Model 4.0 so requires Direct3D hardware feature level 1
> Note this means you can also count on ``DXGI_FORMAT_BC5_UNORM`` texture compression hardware support for your normal maps.
[Direct3D feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
[Direct3D feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
# Further reading
[Basic Theory of Physically-Based Rendering](https://marmoset.co/posts/basic-theory-of-physically-based-rendering/)

@ -5,15 +5,15 @@ In this lesson we learn the basics of Physically-Based Rendering (PBR) as suppor
# What does 'Physically-based' mean?
A full discussion of Physically-Based Rendering (PBR) is beyond the scope of this lesson, so see the references at the end of the page. Instead I'll provide a short motivation of why PBR is useful. The first thing to acknowledge is that traditional computer graphics lighting algorithms are inspired hacks. They work well at providing many useful lighting clues, and have been inexpensive enough to compute on consumer level hardware for decades. These algorithms, however, all have drawbacks. For example, basically anything you render using [Phong shading](https://en.wikipedia.org/wiki/Phong_shading) ends up looking like it's made of smooth plastic. Another challenge is that textures, models, and other assets that look great in some lighting conditions and lighting algorithms don't work at all when moved to a new engine or solution which makes it harder to reuse expensive artwork.
A full discussion of Physically-Based Rendering (PBR) is beyond the scope of this lesson, so see the references at the end of the page. Instead I'll provide a short motivation of why PBR is useful. The first thing to acknowledge is that traditional computer graphics lighting algorithms are inspired hacks. They work well at providing many useful lighting clues, and have been inexpensive enough to compute on consumer level hardware for decades. These algorithms, however, all have drawbacks. For example, basically anything you render using [Phong shading](https://wikipedia.org/wiki/Phong_shading) ends up looking like it's made of smooth plastic. Another challenge is that textures, models, and other assets that look great in some lighting conditions and lighting algorithms don't work at all when moved to a new engine or solution which makes it harder to reuse expensive artwork.
The proponents of PBR rendering have gone back to the foundational [rendering equation](https://en.wikipedia.org/wiki/Rendering_equation) and built new algorithms that in some way better mimic laws of physics (such as the *law of conservation of energy*). While there are many ways to formulate a PBR materials & lighting system, the industry has converged on a few workflows. *DirectX Tool Kit* implements the "Disney-style Roughness/Metalness" workflow as it's well-understood, has reasonably good tooling support, and is the one that was chosen for [Khronos' glTF2 asset format](https://www.khronos.org/gltf/) and many modern game engines.
The proponents of PBR rendering have gone back to the foundational [rendering equation](https://wikipedia.org/wiki/Rendering_equation) and built new algorithms that in some way better mimic laws of physics (such as the *law of conservation of energy*). While there are many ways to formulate a PBR materials & lighting system, the industry has converged on a few workflows. *DirectX Tool Kit* implements the "Disney-style Roughness/Metalness" workflow as it's well-understood, has reasonably good tooling support, and is the one that was chosen for [Khronos' glTF2 asset format](https://www.khronos.org/gltf/) and many modern game engines.
> PBR rendering essentially requires HDR rendering as there's no physical process that clamps light into a 0 to 1 range. As such, be sure you have worked through the [[Using HDR rendering]] tutorial before this one.
## Image-Based Lighting (IBL)
Another important aspect of PBR is that real world lighting is not well modeled by trivial point, directional, or spot light sources. Area lighting or other global illumination systems are expensive and/or complex to implement in real-time systems, so for the purposes of *DirectX Tool Kit*'s PBR implementation we make use of [image-based lighting](https://en.wikipedia.org/wiki/Image-based_lighting). Specifically the ambient lighting environment consists of two specially formulated cubemaps, in addition to direct lighting from up to 3 directional lights.
Another important aspect of PBR is that real world lighting is not well modeled by trivial point, directional, or spot light sources. Area lighting or other global illumination systems are expensive and/or complex to implement in real-time systems, so for the purposes of *DirectX Tool Kit*'s PBR implementation we make use of [image-based lighting](https://wikipedia.org/wiki/Image-based_lighting). Specifically the ambient lighting environment consists of two specially formulated cubemaps, in addition to direct lighting from up to 3 directional lights.
# Setup
First create a new project using the instructions from the previous lessons: [[Using DeviceResources]] and
@ -250,7 +250,7 @@ Build and run to see the sphere rendered a more complex material.
The use of the emissive texture is optional. Any textured use of **PBREffect** requires albedo, normal, and roughness/metalness/ambient-occlusion maps.
> PBR typically refers to the 'base colors' as [albedo](https://en.wikipedia.org/wiki/Albedo) rather than the traditional-lighting texture name 'diffuse'.
> PBR typically refers to the 'base colors' as [albedo](https://wikipedia.org/wiki/Albedo) rather than the traditional-lighting texture name 'diffuse'.
# Rendering a PBR Model
@ -287,7 +287,7 @@ model->UpdateEffects([&](IEffect* effect)
DirectX Tool Kit docs [[PBREffect]]
[Physically-Based Rendering wikipedia](https://en.wikipedia.org/wiki/Physically_based_rendering)
[Physically-Based Rendering wikipedia](https://wikipedia.org/wiki/Physically_based_rendering)
[Basic Theory of Physically-Based Rendering](https://marmoset.co/posts/basic-theory-of-physically-based-rendering/)

@ -5,7 +5,7 @@ This lesson covers performing picking in 3D.
# Ray casting
You can find an older tutorial on 3D picking using ray/object tests at [Rastertek](http://rastertek.com/dx11tut47.html) that uses the deprecated D3DXMath library. Note that instead of a 'roll your own' ``RaySphereIntersect`` you can use [BoundingSphere](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere) from ``DirectXCollision.h`` with the following method to do the ray-sphere test:
You can find an older tutorial on 3D picking using ray/object tests at [Rastertek](http://rastertek.com/dx11tut47.html) that uses the deprecated D3DXMath library. Note that instead of a 'roll your own' ``RaySphereIntersect`` you can use [BoundingSphere](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere) from ``DirectXCollision.h`` with the following method to do the ray-sphere test:
```cpp
bool Intersects(FXMVECTOR Origin, FXMVECTOR Direction, float& Dist) const;
@ -19,5 +19,5 @@ You can also review the Direct3D 10 era "picking" sample from the [legacy Direct
# Further reading
[DirectMath Programmer's Guide](https://docs.microsoft.com/en-us/windows/desktop/dxmath/ovw-xnamath-reference)
[DirectXMath Collision sample](https://code.msdn.microsoft.com/DirectXMath-Win32-Sample-f365b9e5)
[DirectMath Programmer's Guide](https://docs.microsoft.com/windows/win32/dxmath/ovw-xnamath-reference)
DirectXMath Collision sample for [Win32](https://github.com/walbourn/directx-sdk-samples/tree/main/Collision), [UWP](https://github.com/microsoft/Xbox-ATG-Samples/tree/main/UWPSamples/System/CollisionUWP), [XDK](https://github.com/microsoft/Xbox-ATG-Samples/tree/main/XDKSamples/System/Collision), [GDK](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/Collision)

@ -55,4 +55,4 @@ Plane p(arr); // Creates a plane in XZ at the origin
Plane can freely convert to and from a ``XMFLOAT4`` and ``XMVECTOR``
# Further reading
[Plane](https://en.wikipedia.org/wiki/Plane_(geometry))
[Plane](https://wikipedia.org/wiki/Plane_(geometry))

@ -154,7 +154,7 @@ dualPostProcess->Process(context);
The built-in post-processing shaders rely on Direct3D hardware feature level 10.0 or greater. This allows the vertex shader to self-generate a full-screen rectangle without requiring any vertex buffer to be bound using the built-in ``SV_VertexId`` system value. Applications should either have a minimum supported feature level of 10.0 or greater, or provide a run-time fallback (perhaps turning off post-processing effects or making use of simplified effects via [[SpriteBatch]] instead).
[Direct3D feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
[Direct3D feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro)
# Threading model
@ -178,4 +178,4 @@ Most post-process effects make use of the following states:
# Further reading
[Video post-processing](https://en.wikipedia.org/wiki/Video_post-processing)
[Video post-processing](https://wikipedia.org/wiki/Video_post-processing)

@ -27,7 +27,7 @@ std::unique_ptr<PrimitiveBatch<VertexPositionColor>> primitiveBatch;
primitiveBatch = std::make_unique<PrimitiveBatch<VertexPositionColor>>(deviceContext);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
The default values assume that your maximum batch size is 2048 vertices arranged in triangles. If you want to use larger batches, you need to provide the additional constructor parameters (be sure to review the Feature Level limitations below).
@ -127,7 +127,7 @@ Primitive batch is best used for dynamic submission, which is commonly needed fo
# Feature Level Notes
In order to support [all feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro), PrimitiveBatch only supports 16-bit indices (``DXGI_FORMAT_R16_UINT``) which limits to a maximum of 65535 addressable vertices. This does not apply to non-indexed drawing when the PrimitiveBatch constructor is called with a maxIndices of 0.
In order to support [all feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro), PrimitiveBatch only supports 16-bit indices (``DXGI_FORMAT_R16_UINT``) which limits to a maximum of 65535 addressable vertices. This does not apply to non-indexed drawing when the PrimitiveBatch constructor is called with a maxIndices of 0.
Keep in mind there is a feature-level based limit on the maximum number of primitives in a single draw call, so the overall batch size needs to be under this limit. To support all feature levels, this should be 65535 or less lines or triangles in a single 'draw batch'.
@ -137,7 +137,7 @@ Keep in mind there is a feature-level based limit on the maximum number of primi
Each PrimitiveBatch instance only supports drawing from one thread at a time, but you can simultaneously submit primitives on multiple threads if you create a separate PrimitiveBatch instance per Direct3D 11 deferred context.
[Immediate and Deferred Rendering](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-render-multi-thread-render)
[Immediate and Deferred Rendering](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-render-multi-thread-render)
# State management
PrimitiveBatch does not save and restore existing state. For efficiency, it simply sets the state it requires to render and assumes that any subsequent rendering after ``primitiveBatch->End()`` will overwrite state that it needs.
@ -153,5 +153,5 @@ The PrimitiveBatch class assumes you've already set the Render Target view, Dept
> Be sure that if you set any of the following shaders prior to using ``PrimitiveBatch`` that you clear them: Geometry Shader, Hull Shader, Domain Shader, Compute Shader.
# Further Reading
[DirectXTK PrimitiveBatch helper makes it easy to draw user primitives with D3D11]( http://www.shawnhargreaves.com/blog/directxtk-primitivebatch-helper-makes-it-easy-to-draw-user-primitives-with-d3d11.html)
[How to: Use dynamic resources](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/how-to--use-dynamic-resources)
[DirectXTK PrimitiveBatch helper makes it easy to draw user primitives with D3D11](http://www.shawnhargreaves.com/blog/directxtk-primitivebatch-helper-makes-it-easy-to-draw-user-primitives-with-d3d11.html)
[How to: Use dynamic resources](https://docs.microsoft.com/windows/win32/direct3d11/how-to--use-dynamic-resources)

@ -1,9 +1,9 @@
|[[DirectXTK]]|[[SimpleMath]]|
|---|---|
A [rotation represented as a four component vector](https://en.wikipedia.org/wiki/Quaternion) modeled after the XNA Game Studio 4 (``Microsoft.Xna.Framework.Quaternion``) math library.
A [rotation represented as a four component vector](https://wikipedia.org/wiki/Quaternion) modeled after the XNA Game Studio 4 (``Microsoft.Xna.Framework.Quaternion``) math library.
A *quaternion* is a very efficient and compact method for working with 3D rotation. A *quaternion* is a 4-dimensional value and only has physical meaning when it's normalized. In computer graphics, they are used to represent 3D rotations as a 4-vector (i.e. 4 float values) instead of requiring a 3x3 matrix (i.e. 9 float values) and are thus more compact. They are extremely useful implementing cameras and animation where a *quaternion* can smoothly interpolate between 3D rotations while avoiding the [gimbal lock](https://en.wikipedia.org/wiki/Gimbal_lock) problem common to [Euler angles](https://en.wikipedia.org/wiki/Euler_angles).
A *quaternion* is a very efficient and compact method for working with 3D rotation. A *quaternion* is a 4-dimensional value and only has physical meaning when it's normalized. In computer graphics, they are used to represent 3D rotations as a 4-vector (i.e. 4 float values) instead of requiring a 3x3 matrix (i.e. 9 float values) and are thus more compact. They are extremely useful implementing cameras and animation where a *quaternion* can smoothly interpolate between 3D rotations while avoiding the [gimbal lock](https://wikipedia.org/wiki/Gimbal_lock) problem common to [Euler angles](https://wikipedia.org/wiki/Euler_angles).
# Header
```cpp
@ -88,7 +88,7 @@ Quaternion q(arr); // Creates a quaternion [0, 0, 0, 1]
Quaternion can freely convert to and from a ``XMFLOAT4`` and ``XMVECTOR``.
# Further Reading
[Quaternions and spatial rotation](https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation)
[Quaternions and spatial rotation](https://wikipedia.org/wiki/Quaternions_and_spatial_rotation)
Jonathan Blow, "Understanding Slerp, Then Not Using It", The Inner Product, April 2004 [link](http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/)

2
Ray.md

@ -31,4 +31,4 @@ Ray( Vector3(1,2,3), Vector3(0,1,0 ); // Creates a ray at 1,2,3
# Further reading
[Ray](https://en.wikipedia.org/wiki/Line_%28geometry%29#Ray)
[Ray](https://wikipedia.org/wiki/Line_%28geometry%29#Ray)

@ -3,7 +3,7 @@
A 2D rectangle class modeled after the XNA Game Studio 4 (``Microsoft.Xna.Framework.Rectangle``) math library
> For Universal Windows Platform and Xbox One, similar functionality is provided by the [Windows::Foundation::Rect](https://docs.microsoft.com/en-us/uwp/api/Windows.Foundation.Rect) Windows Runtime structure
> For Universal Windows Platform and Xbox One, similar functionality is provided by the [Windows::Foundation::Rect](https://docs.microsoft.com/uwp/api/Windows.Foundation.Rect) Windows Runtime structure
# Header
```cpp

@ -10,12 +10,12 @@ First create a new project using the instructions from the earlier lessons: [[Us
# Creating a model
Source assets for models are often stored in Autodesk FBX, Wavefront OBJ, or similar formats. A build process is used to convert them to a more run-time friendly format that is easier to load and render.
Visual Studio has a built-in system for converting a Wavefront OBJ or Autodesk FBX as part of the build process to a CMO, which you can read about [here](https://docs.microsoft.com/en-us/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
Visual Studio has a built-in system for converting a Wavefront OBJ or Autodesk FBX as part of the build process to a CMO, which you can read about [here](https://docs.microsoft.com/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
For this tutorial, we will make of use of the [DirectXMesh](http://go.microsoft.com/fwlink/?LinkID=324981) **meshconvert** command-line tool. Start by saving [cup._obj](https://github.com/Microsoft/DirectXTK/wiki/media/cup._obj), [cup.mtl](https://github.com/Microsoft/DirectXTK/wiki/media/cup.mtl), and [cup.jpg](https://github.com/Microsoft/DirectXTK/wiki/images/cup.jpg) into your new project's directory, and then from the top menu select **Project** / **Add Existing Item...**. Select "cup.jpg" and click "OK".
1. Download the [Meshconvert.exe](https://github.com/microsoft/DirectXMesh/releases/latest/download/meshconvert.exe) from the _DirectXMesh_ site save the EXE into your project's folder.
1. Open a [command-prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq) and then change to your project's folder.
1. Open a Command Prompt and then change to your project's folder.
Run the following command-line
@ -126,7 +126,7 @@ m_model->Draw(context, *m_states, m_world, m_view, m_proj, false, [&]() -> void
# Updating effects settings in a model
The Model class creates effects automatically for the loaded materials which are set to default lighting parameters. To update them, you use the **Model::UpdateEffects** method. Because the effects system is flexible, we must first enable [C++ Run-Time Type Information](https://docs.microsoft.com/en-us/cpp/cpp/run-time-type-information) (RTTI) in order to safely discover the various interfaces supported at runtime. From the drop-down menu, select **Project** / **Properties**. Set to "All Configurations" / "All Platforms". On the left-hand tree view select **``C/C++``** / **Language**. Then set "Enable Run-Time Type Information" to "Yes". Click "OK".
The Model class creates effects automatically for the loaded materials which are set to default lighting parameters. To update them, you use the **Model::UpdateEffects** method. Because the effects system is flexible, we must first enable [C++ Run-Time Type Information](https://docs.microsoft.com/cpp/cpp/run-time-type-information) (RTTI) in order to safely discover the various interfaces supported at runtime. From the drop-down menu, select **Project** / **Properties**. Set to "All Configurations" / "All Platforms". On the left-hand tree view select **``C/C++``** / **Language**. Then set "Enable Run-Time Type Information" to "Yes". Click "OK".
![Screenshot C++ RTTI settings](https://github.com/Microsoft/DirectXTK/wiki/images/settingsRTTI.PNG)
@ -194,7 +194,7 @@ Build and run. If you still have the **UpdateEffects** code in place, you'll see
![Screenshot of DSGL cup model](https://github.com/Microsoft/DirectXTK/wiki/images/screenshotCupNoFog.PNG)
The lack of fog is because our "cup.cmo" makes use of the default built-in DGSL shaders _lambert_ and _phong_ which do not implement fog. The ``DGSLEffectFactory`` allows you to use ``Model`` and the [[IEffect]] interface with the more complex custom DGSL shaders supported by the Visual Studio CMO pipeline where you use a [visual editor to build pixel shaders](https://docs.microsoft.com/en-us/visualstudio/designers/working-with-shaders).
The lack of fog is because our "cup.cmo" makes use of the default built-in DGSL shaders _lambert_ and _phong_ which do not implement fog. The ``DGSLEffectFactory`` allows you to use ``Model`` and the [[IEffect]] interface with the more complex custom DGSL shaders supported by the Visual Studio CMO pipeline where you use a [visual editor to build pixel shaders](https://docs.microsoft.com/visualstudio/designers/working-with-shaders).
# More to explore

@ -19,7 +19,7 @@ MSAA textures are resolved before being written.
> You only need to directly include the ``<wincodec.h>`` header if you are providing an explicit *guidContainerFormat* or *targetFormat*. Note you should link with ``uuid.lib`` as well.
# Initialization
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any [Windows Imaging Component](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-about-windows-imaging-codec) functionality.
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any [Windows Imaging Component](https://docs.microsoft.com/windows/win32/wic/-wic-about-windows-imaging-codec) functionality.
For a Universal Windows Platform (UWP) app using ``/ZW``, the Windows Runtime and COM is initialized by the C/C++ Run-Time. For C++/WinRT applications, this is done by calling ``winrt::init_apartment();``.
@ -242,8 +242,8 @@ if (file)
}
```
See [File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions),
[ApplicationData.TemporaryFolder property](https://docs.microsoft.com/en-us/uwp/api/Windows.Storage.ApplicationData#Windows_Storage_ApplicationData_TemporaryFolder)
See [File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/windows/uwp/files/file-access-permissions),
[ApplicationData.TemporaryFolder property](https://docs.microsoft.com/uwp/api/Windows.Storage.ApplicationData#Windows_Storage_ApplicationData_TemporaryFolder)
# Xbox One
When using Direct3D 11.x fast semantics and trying to capture a Render Target, it must be decompressed with ``DecompressResource`` before calling ``SaveDDSTextureToFile`` or ``SaveWICTextureToFile``. The save functions will block until the resource copy is completed, so it should not be used with high frequency.

@ -11,11 +11,11 @@ First create a new project using the instructions from the earlier lessons: [[Us
In order to do a draw operation with Direct3D 11, we need to provide the following objects and settings:
* A *vertex buffer* containing the vertices of the elements to draw.
* The *input layout* that [describes](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_input_element_desc) the memory layout of the vertices in the _vertex buffer_.
* The *input layout* that [describes](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_input_element_desc) the memory layout of the vertices in the _vertex buffer_.
* A *primitive topology* setting that indicates how to interpret the individual vertices (as a point, a line, a triangle, etc.)
* A compiled *vertex shader* program
* A compiled *pixel shader* program
* Set any required *state objects* for [rasterizer state](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_rasterizer_desc), [depth/stencil state](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_depth_stencil_desc), [blend state](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_blend_desc), and [sampler state](https://docs.microsoft.com/en-us/windows/desktop/api/d3d11/ns-d3d11-d3d11_sampler_desc) (if using textures)
* Set any required *state objects* for [rasterizer state](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_rasterizer_desc), [depth/stencil state](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_depth_stencil_desc), [blend state](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_blend_desc), and [sampler state](https://docs.microsoft.com/windows/win32/api/d3d11/ns-d3d11-d3d11_sampler_desc) (if using textures)
For this lesson, the [[BasicEffect]] object will provide the vertex and pixel shader programs, [[VertexPositionColor|VertexTypes]] will provide the input layout, [[CommonStates]] will provide the 'stock' state objects, and **PrimitiveBatch** will provide the vertex buffer and primitive topology.
@ -156,7 +156,7 @@ context->RSSetState(m_states->CullCounterClockwise());
Then build & run you will see the triangle reappear.
For 'closed' objects, you typically use [backface culling](https://en.wikipedia.org/wiki/Back-face_culling) to speed up rendering which can quickly reject triangles that are not facing the viewer and avoids the need to run the pixel shader for those pixels.
For 'closed' objects, you typically use [backface culling](https://wikipedia.org/wiki/Back-face_culling) to speed up rendering which can quickly reject triangles that are not facing the viewer and avoids the need to run the pixel shader for those pixels.
> The culling mode does not affect points or lines.
@ -299,7 +299,7 @@ using VertexType = DirectX::VertexPositionNormalTexture;
Also change the type of effect. Since we are using a flat 2D triangle, the lighting is not going to be very interesting so we are going to add some simple normal mapping to give the texture some definition.
> If you are not familiar with *lighting* (also known as [shading](https://en.wikipedia.org/wiki/Shading)) in the computer graphics sense, you should review some of the basic material on the web or in a standard book. Most of the built-in effects use simple "dot-product" style lighting where the 'light value' is scaled by a value of 0 (not lit) to 1 (fully lit) computed from the angle between the vector to the light (i.e. the inverse of the light direction) and the normal vector at the surface.
> If you are not familiar with *lighting* (also known as [shading](https://wikipedia.org/wiki/Shading)) in the computer graphics sense, you should review some of the basic material on the web or in a standard book. Most of the built-in effects use simple "dot-product" style lighting where the 'light value' is scaled by a value of 0 (not lit) to 1 (fully lit) computed from the angle between the vector to the light (i.e. the inverse of the light direction) and the normal vector at the surface.
```cpp
std::unique_ptr<DirectX::NormalMapEffect> m_effect;

@ -74,11 +74,11 @@ The SimpleMath wrapper does not include classes for bounding volumes because the
This includes:
* [BoundingSphere](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere) class
* [BoundingBox](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingbox) class
* [BoundingOrientedBox](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingorientedbox) class
* [BoundingFrustum](https://docs.microsoft.com/en-us/windows/win32/api/directxcollision/ns-directxcollision-boundingfrustum) class
* [TriangleTests](https://docs.microsoft.com/en-us/windows/win32/dxmath/ovw-xnamath-triangletests) namespace
* [BoundingSphere](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingsphere) class
* [BoundingBox](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingbox) class
* [BoundingOrientedBox](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingorientedbox) class
* [BoundingFrustum](https://docs.microsoft.com/windows/win32/api/directxcollision/ns-directxcollision-boundingfrustum) class
* [TriangleTests](https://docs.microsoft.com/windows/win32/dxmath/ovw-xnamath-triangletests) namespace
These were designed to already be similar to the XNA Game Studio math API bounding types.
@ -123,9 +123,9 @@ Matrix mView = Matrix::CreateConstrainedBillboard( objectPosition,
```
# Using with HLSL
SimpleMath as with DirectXMath uses [row-major ordering](https://en.wikipedia.org/wiki/Row-major_order) for matrices. This means that elements are stored in memory in the following order:``_11``, ``_12``, ``_13``, ``_14``, ``_21``, ``_22``, etc.
SimpleMath as with DirectXMath uses [row-major ordering](https://wikipedia.org/wiki/Row-major_order) for matrices. This means that elements are stored in memory in the following order:``_11``, ``_12``, ``_13``, ``_14``, ``_21``, ``_22``, etc.
HLSL as noted on [Microsoft Docs](https://docs.microsoft.com/en-us/windows/desktop/direct3dhlsl/dx-graphics-hlsl-per-component-math#Matrix_Ordering) defaults to using _column-major ordering_ as this makes for slightly more efficient shader matrix multiplies. Therefore, if a ``Matrix`` is going to be copied into a HLSL _constant buffer_, it is usually [transposed](https://en.wikipedia.org/wiki/Transpose) to flip the ordering to ``_11``, ``_21``, ``_31``, ``_41_``, ``_12``, ``_22``, etc. as part of updating the constant buffer.
HLSL as noted on [Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3dhlsl/dx-graphics-hlsl-per-component-math#matrix-ordering) defaults to using _column-major ordering_ as this makes for slightly more efficient shader matrix multiplies. Therefore, if a ``Matrix`` is going to be copied into a HLSL _constant buffer_, it is usually [transposed](https://wikipedia.org/wiki/Transpose) to flip the ordering to ``_11``, ``_21``, ``_31``, ``_41_``, ``_12``, ``_22``, etc. as part of updating the constant buffer.
With the built-in [[Effects]] this is done internally, but if writing your own shaders and managing your own constant buffers, you will need to ensure you pass in your matrix data in the correct order for your HLSL shader settings. This means sticking with the HLSL default by transposing your matrices as you update the constant buffer, using `` #pragma pack_matrix(row_major)`` in your HLSL shader source, or compiling your shaders with ``D3DCOMPILE_PACK_MATRIX_ROW_MAJOR`` / ``/Zpr``.

@ -18,7 +18,7 @@ std::unique_ptr<SkinnedEffect> effect;
effect = std::make_unique<SkinnedEffect>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Interfaces

@ -19,7 +19,7 @@ std::unique_ptr<SoundEffect> effect;
effect = std::make_unique<SoundEffect>( audEngine.get(), L"sound.wav" );
```
For exception safety, it is recommended you make use of the C++ C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
The second takes ownership of a memory buffer containing the wave data. The _wfx_ and _startAudio_ pointers are assumed to point into the same memory buffer owned by _wavData_ since they must remain valid for the life of the SoundEffect object.
@ -148,4 +148,4 @@ To compress to XMA2 ``.wav`` files, use ``xma2encode.exe`` from the Xbox One XDK
To aid in debugging, here is a [simple console program](https://github.com/Microsoft/DirectXTK/wiki/wavdump.cpp) for dumping out the content of a ``.wav`` in a human-readable form.
[Resource Interchange File Format (RIFF)](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/resource-interchange-file-format--riff-)
[Resource Interchange File Format (RIFF)](https://docs.microsoft.com/windows/win32/xaudio2/resource-interchange-file-format--riff-)

@ -87,7 +87,7 @@ This is a combination of sound effect instance flags. It defaults to ``SoundEffe
# Positional 3D audio
DirectXTK for Audio uses [X3DAudio](https://docs.microsoft.com/en-us/windows/desktop/xaudio2/x3daudio) for positional audio computations. To apply a 3D effect to a sound instance, you call **Apply3D** with the listener location (i.e. where the player/camera is located) and the emitter (i.e. where the sound source is located in 3D dimensions):
DirectXTK for Audio uses [X3DAudio](https://docs.microsoft.com/windows/win32/xaudio2/x3daudio) for positional audio computations. To apply a 3D effect to a sound instance, you call **Apply3D** with the listener location (i.e. where the player/camera is located) and the emitter (i.e. where the sound source is located in 3D dimensions):
```cpp
AudioListener listener;

@ -41,7 +41,7 @@ if ( !stream )
// Index not found in wave bank
```
> Only 'streaming' WaveBanks are supported. Attempts to create a SoundStreamInstance from an 'in-memory' wavebank will result in a C++ exception. The 'streaming' Wavebank produced by [[xwbtool]] is properly aligned to allow very efficient [non-buffered](https://docs.microsoft.com/en-us/windows/win32/fileio/file-buffering) [asynchronous I/O](https://docs.microsoft.com/en-us/windows/win32/fileio/synchronous-and-asynchronous-i-o) requests.
> Only 'streaming' WaveBanks are supported. Attempts to create a SoundStreamInstance from an 'in-memory' wavebank will result in a C++ exception. The 'streaming' Wavebank produced by [[xwbtool]] is properly aligned to allow very efficient [non-buffered](https://docs.microsoft.com/windows/win32/fileio/file-buffering) [asynchronous I/O](https://docs.microsoft.com/windows/win32/fileio/synchronous-and-asynchronous-i-o) requests.
# Instance flags

@ -20,7 +20,7 @@ std::unique_ptr<SpriteBatch> spriteBatch;
spriteBatch = std::make_unique<SpriteBatch>(deviceContext);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Simple drawing
@ -245,7 +245,7 @@ For more extreme usage scenarios (large particle systems, star fields, etc.), wr
# Threading model
Creation is fully asynchronous, so you can instantiate multiple SpriteBatch instances at the same time on different threads. Each SpriteBatch instance only supports drawing from one thread at a time, but you can simultaneously submit sprites on multiple threads if you create a separate SpriteBatch instance per Direct3D 11 deferred context.
[Immediate and Deferred Rendering](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-render-multi-thread-render)
[Immediate and Deferred Rendering](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-render-multi-thread-render)
# Orientation
For phones, laptops, and tablets the orientation of the display can be changed by the user. For Windows Store apps, DirectX applications are encouraged to handle the rotation internally rather than relying on DXGI's auto-rotation handling.

@ -26,7 +26,7 @@ spriteBatch = std::make_unique<SpriteBatch>(deviceContext);
spriteFont = std::make_unique<SpriteFont>(device, L"myfile.spritefont");
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
> You create one ``SpriteFont`` instance per font style & point-size you want to use to render with. You can use the same ``SpriteBatch`` or use several ``SpriteBatch`` instances if desired. Be sure to read the _Threading model_ notes for [[SpriteBatch]].
@ -101,7 +101,7 @@ The default character region for [[MakeSpriteFont]] from 32 to 127 covers the st
# Extended ASCII
If you are wanting to render an [extended ASCII](http://ascii-table.com/ascii-extended-pc-list.php) string with SpriteFont, you need to capture the full set of characters which are not contiguous in Unicode (see [[MakeSpriteFont]] for details). You then need to convert your 'extended ASCII' string to Unicode using [Code page 437](http://en.wikipedia.org/wiki/Code_page_437) before calling ``DrawString``.
If you are wanting to render an [extended ASCII](http://ascii-table.com/ascii-extended-pc-list.php) string with SpriteFont, you need to capture the full set of characters which are not contiguous in Unicode (see [[MakeSpriteFont]] for details). You then need to convert your 'extended ASCII' string to Unicode using [Code page 437](http://wikipedia.org/wiki/Code_page_437) before calling ``DrawString``.
```cpp
char ascii[...];
@ -138,7 +138,7 @@ Code for rendering text mixed with the Xbox controller button spritefont, see [[
# Feature Level Notes
The Sprite Font implementation is compatible with all feature levels. The primary limitation is on the size of the sprite sheet texture which should fit into the limits for [known feature levels](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/overviews-direct3d-11-devices-downlevel-intro) (i.e. to support all feature levels, it should be no larger than 2048 x 2048; if you target feature level 9.3 or later you can use 4096 x 4096, etc.).
The Sprite Font implementation is compatible with all feature levels. The primary limitation is on the size of the sprite sheet texture which should fit into the limits for [known feature levels](https://docs.microsoft.com/windows/win32/direct3d11/overviews-direct3d-11-devices-downlevel-intro) (i.e. to support all feature levels, it should be no larger than 2048 x 2048; if you target feature level 9.3 or later you can use 4096 x 4096, etc.).
> You are of course free to use a larger texture as long as you set your application's minimum supported feature level as appropriate. [[MakeSpriteFont]] will emit warnings if your captured font texture exceeds the various feature level size thresholds.

@ -300,7 +300,7 @@ If you are making use of CodeAndWeb's **TexturePacker** tool, you will be writin
If you are using premultiplied alpha for your blending (the default for SpriteBatch), you should under _Texture \ show advanced_ set the _Premultiply alpha_ check box option.
The default _Pixel format_ of RGBA8888 is suitable for all feature levels, and will be loaded at runtime as ``DXGI_FORMAT_B8G8R8A8_UNORM``. Due to limitations of the [built-in Windows PNG codec](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-codec-native-pixel-formats#png__native_codec), using other pixel formats does not reduce video memory usage; only disk space usage. For more flexible control over pixel format at runtime, you should convert to a ``.DDS`` instead (see below).
The default _Pixel format_ of RGBA8888 is suitable for all feature levels, and will be loaded at runtime as ``DXGI_FORMAT_B8G8R8A8_UNORM``. Due to limitations of the [built-in Windows PNG codec](https://docs.microsoft.com/windows/win32/wic/-wic-codec-native-pixel-formats#png-native-codec), using other pixel formats does not reduce video memory usage; only disk space usage. For more flexible control over pixel format at runtime, you should convert to a ``.DDS`` instead (see below).
The default _Max size_ of 2048 x 2048 under _Layout_ is suitable for all feature levels. If your _minimum_ supported feature level is not 9.1 or 9.2, you can set it higher to make use of larger supported texture sizes for more efficient packing.
* Feature Level 9.1, 9.2 -> 2048 x 2048
@ -316,7 +316,7 @@ If using ``DDS`` rather than ``PNG`` and premultiplied alpha for your blending,
In most cases you won't need mipmap levels generated so specify *-m 1* when converting the ``DDS``. If you do want mipmaps levels and want to support all feature levels (i.e. Feature Levesl 9.x), then in your **TexturePacker** project under _Layout / Size constraints_ set it to "POW (Power of 2)" and do not use *-m 1*.
Open a [Command Prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq), and change to the directory containing [Texconv.exe](https://github.com/Microsoft/DirectXTex/releases/latest/download/texconv.exe)
Open a Command Prompt, and change to the directory containing [Texconv.exe](https://github.com/Microsoft/DirectXTex/releases/latest/download/texconv.exe)
Enter the following command-line after changing to the appropriate directory:

@ -3,6 +3,10 @@
In this lesson, we will cover the basics of creating a texture from a bitmap file, and then rendering it using a 2D sprite with various drawing options.
# Setup
First create a new project using the instructions from the previous lessons: [[Using DeviceResources]] and
[[Adding the DirectX Tool Kit]] which we will use for this lesson.
# Background
A [sprite](https://wikipedia.org/wiki/Sprite_(computer_graphics)) is a bitmap rendered at some location on the screen. For Direct3D, this requires making use of:
@ -19,10 +23,6 @@ A [sprite](https://wikipedia.org/wiki/Sprite_(computer_graphics)) is a bitmap re
* Additional Direct3D objects are also required (*vertex buffer*, *index buffer*, *rasterizer state object*, *input layout*, *vertex shader*, *pixel shader*, and *constant buffer*), but in this tutorial these are handled by [[SpriteBatch]].
# Setup
First create a new project using the instructions from the previous lessons: [[Using DeviceResources]] and
[[Adding the DirectX Tool Kit]] which we will use for this lesson.
# Loading a texture
Start by saving [cat.png](https://github.com/Microsoft/DirectXTK/wiki/images/cat.png) into your new project's directory, and then from the top menu select **Project** / **Add Existing Item...**. Select "cat.png" and click "OK".
@ -158,12 +158,12 @@ Build and run again, and you'll get a nice clean cat:
Rather than use a ``PNG`` and the Windows Imaging Component (WIC) to load the texture, a more efficient thing for us to do is to make use of a ``DDS`` file instead. A ``DDS`` file is a container for all kinds of Direct3D resources including 1D and 2D textures, _cubemaps_, _volume maps_, arrays of 1D or 2D textures or cubemaps each optionally with _mipmaps_. It can contain a wide-array of pixel formats and hardware-supported 'block-compression' schemes to save on video memory usage at runtime.
Visual Studio has a built-in system for converting images to DDS as part of the build process, which you can read about [here](https://docs.microsoft.com/en-us/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
Visual Studio has a built-in system for converting images to DDS as part of the build process, which you can read about [here](https://docs.microsoft.com/visualstudio/designers/using-3-d-assets-in-your-game-or-app).
For this tutorial, we will instead make of use of the [DirectXTex](http://go.microsoft.com/fwlink/?LinkId=248926) **texconv** command-line tool.
1. Download the [Texconv.exe](https://github.com/Microsoft/DirectXTex/releases/latest/download/texconv.exe) from the _DirectXTex_ site save the EXE into your project's folder.
1. Open a [command-prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq) and then change to your project's folder.
1. Open a Command Prompt and then change to your project's folder.
Then run the following command-line:

@ -55,7 +55,7 @@ The fixed-step duration can be set by using **SetTargetElapsedTicks** or **SetTa
If a larger than usual delay is expected, the code should call **ResetElapsedTime** to avoid the fixed-step ``Tick`` calling the update method a large number of times to 'catch-up'.
> The overall loop time is limited by the frame rate of ``Present`` for standard 'render loop' usage. Otherwise, you can 'Tick' an instance of ``StepTimer`` on it's own thread at your own rate limited only by the [system timer resolution](https://docs.microsoft.com/en-us/windows/win32/api/timeapi/nf-timeapi-timebeginperiod).
> The overall loop time is limited by the frame rate of ``Present`` for standard 'render loop' usage. Otherwise, you can 'Tick' an instance of ``StepTimer`` on it's own thread at your own rate limited only by the [system timer resolution](https://docs.microsoft.com/windows/win32/api/timeapi/nf-timeapi-timebeginperiod).
# StepTimer
The class provides the following accessors:

@ -3,6 +3,9 @@
The first lesson in the [[Getting Started]] guide is to create a basic game loop which creates a Direct3D device, swap chain, and update/render loop.
# Setup
Our starting point is to use the **Direct3D Win32 Game** or the **Direct3D <abbr title="Universal Windows Platform">UWP</abbr> Game** project template. Install the [VS 2019/2022](https://github.com/walbourn/directx-vs-templates/raw/main/VSIX/Direct3DUWPGame.vsix) VSIX on your development system, and then start (or restart) Visual Studio.
# Background
The basic rendering setup for Direct3D 11 consists of the following interface objects:
@ -21,9 +24,6 @@ The basic rendering setup for Direct3D 11 consists of the following interface ob
* A *depth/stencil view* interface is the object that tells Direct3D the current properties of the depth/stencil resource.
# Setup
Our starting point is to use the **Direct3D Win32 Game** or the **Direct3D <abbr title="Universal Windows Platform">UWP</abbr> Game** project template. Install the [VS 2019/2022](https://github.com/walbourn/directx-vs-templates/raw/main/VSIX/Direct3DUWPGame.vsix) VSIX on your development system, and then start (or restart) Visual Studio.
# Creating a new project
## Visual Studio 2019 / 2022
@ -104,7 +104,7 @@ This is pretty unlikely on modern versions of Windows.</li>
for your operating system.</li>
<li>Finally, if you are on Windows 7 Service Pack 1, you need to have <a href="https://walbourn.github.io/directx-11-1-and-windows-7-update/">KB2670838</a> installed for DirectX 11.1 support.</li></ul></p></details>
> **Xbox**: the background color may be slightly oversaturated. This is because the basic Xbox template uses a backBufferFormat of ``DXGI_FORMAT_B8G8R8A8_UNORM_SRGB``. The DirectXMath Colors values are defined using standard [sRGB](https://en.wikipedia.org/wiki/SRGB) colorspace which is slightly different. All the colors defines need to be adjusted slightly for the linear RGB colorspace (aka gamma correct rendering) via ``XMColorSRGBToRGB``.
> **Xbox**: the background color may be slightly oversaturated. This is because the basic Xbox template uses a backBufferFormat of ``DXGI_FORMAT_B8G8R8A8_UNORM_SRGB``. The DirectXMath Colors values are defined using standard [sRGB](https://wikipedia.org/wiki/SRGB) colorspace which is slightly different. All the colors defines need to be adjusted slightly for the linear RGB colorspace (aka gamma correct rendering) via ``XMColorSRGBToRGB``.
> **ARM64**: With the ARM64 compiler installed targeting a Windows on ARM64 device such as a *Microsoft Surface X*, you can build using the ARM64 platform for desktop as well.
@ -274,7 +274,7 @@ We make use of the ``Microsoft::WRL::ComPtr`` smart-pointer for managing the lif
# Error handling
Many Direct3D functions return an ``HRESULT`` which is the standard for COM APIs. For robustness and easier debugging, it is important that you always check the result of every function that return an ``HRESULT``. If you really can safely assume there is no error condition for a particular function, the function itself will return ``void`` instead of ``HRESULT``.
The Win32 game template makes use of the helper function [[ThrowIfFailed]] in the ``DX`` C++ namespace declared in ``pch.h``. This is the same helper that is used by the Windows Store and Windows phone VS templates. This helper throws a C++ exception if the standard ``FAILED`` macro returns true for a given ``HRESULT``. This is used for [fail fast](https://en.wikipedia.org/wiki/Fail-fast) error handling.
The Win32 game template makes use of the helper function [[ThrowIfFailed]] in the ``DX`` C++ namespace declared in ``pch.h``. This is the same helper that is used by the Windows Store and Windows phone VS templates. This helper throws a C++ exception if the standard ``FAILED`` macro returns true for a given ``HRESULT``. This is used for [fail fast](https://wikipedia.org/wiki/Fail-fast) error handling.
```cpp
DX::ThrowIfFailed(m_d3dDevice->CreateTexture2D(&depthStencilDesc,
@ -326,4 +326,4 @@ For UWP, the equivalent thing is done inside the ``ViewProvider`` **Run** method
[Direct3D Game Visual Studio templates (Redux)](https://walbourn.github.io/direct3d-game-visual-studio-templates-redux/)
[Anatomy of Direct3D 11 Create Device](https://walbourn.github.io/anatomy-of-direct3d-11-create-device/)
[Manifest Madness](https://aka.ms/I6kdnw)
[64-bit programming for Game Developers](https://docs.microsoft.com/windows/desktop/DxTechArts/sixty-four-bit-programming-for-game-developers)
[64-bit programming for Game Developers](https://docs.microsoft.com/windows/win32/dxtecharts/sixty-four-bit-programming-for-game-developers)

@ -105,6 +105,6 @@ namespace DX
# Further reading
* [C++ Exception Handling](https://docs.microsoft.com/en-us/cpp/cpp/cpp-exception-handling)
* [Managing Exceptions with the Debugger](https://docs.microsoft.com/en-us/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [Error Handling in COM](https://docs.microsoft.com/en-us/windows/desktop/LearnWin32/error-handling-in-com)
* [C++ Exception Handling](https://docs.microsoft.com/cpp/cpp/cpp-exception-handling)
* [Managing Exceptions with the Debugger](https://docs.microsoft.com/visualstudio/debugger/managing-exceptions-with-the-debugger)
* [Error Handling in COM](https://docs.microsoft.com/windows/win32/learnwin32/error-handling-in-com)

@ -18,7 +18,7 @@ std::unique_ptr<ToneMapPostProcess> toneMap;
toneMap = std::make_unique<ToneMapPostProcess>(device);
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
# Shader selection
@ -59,5 +59,5 @@ enum|Notes
# Further reading
Reinhard et al. "Photographic Tone Reproduction for Digital Images" [PDF](http://www.cs.utah.edu/~reinhard/cdrom/tonemap.pdf)
[Tone mapping](https://en.wikipedia.org/wiki/Tone_mapping)
[High-dynamic-range video](https://en.wikipedia.org/wiki/High-dynamic-range_video)
[Tone mapping](https://wikipedia.org/wiki/Tone_mapping)
[High-dynamic-range video](https://wikipedia.org/wiki/High-dynamic-range_video)

@ -115,7 +115,7 @@ If doing _gamma-correct rendering_, you should use ``DXGI_FORMAT_*_UNORM_SRGB``
m_deviceResources = std::make_unique<DX::DeviceResources>(DXGI_FORMAT_B8G8R8A8_UNORM_SRGB);
```
If you do not want DeviceResources to create a depth/stencil buffer, you can use ``DXGI_FORMAT_UNKNOWN`` for ``depthBufferFormat``. This is useful for 2D only rendering or when doing [MSAA](https://en.wikipedia.org/wiki/Multisample_anti-aliasing) on Universal Windows Platform (UWP) apps which requires handling your own render target and depth buffer with ``Sample.Count`` > 1. Be sure to update ``Clear`` below to avoid referencing a null depth/stencil buffer object.
If you do not want DeviceResources to create a depth/stencil buffer, you can use ``DXGI_FORMAT_UNKNOWN`` for ``depthBufferFormat``. This is useful for 2D only rendering or when doing [MSAA](https://wikipedia.org/wiki/Multisample_anti-aliasing) on Universal Windows Platform (UWP) apps which requires handling your own render target and depth buffer with ``Sample.Count`` > 1. Be sure to update ``Clear`` below to avoid referencing a null depth/stencil buffer object.
```cpp
// Renders only 2D, so no need for a depth buffer.
@ -245,7 +245,7 @@ void Game::Clear()
}
```
If you are using _gamma-correct rendering_ with a [sRGB](https://en.wikipedia.org/wiki/SRGB) or HDR backbuffer format, you need to ensure you are using a linear RGB clear color. DirectXMath colors are defined in sRGB colorspace since they are [.NET color constants](https://docs.microsoft.com/dotnet/api/system.drawing.color), so you need to replace ``ClearRenderTargetView`` in **Clear** with:
If you are using _gamma-correct rendering_ with a [sRGB](https://wikipedia.org/wiki/SRGB) or HDR backbuffer format, you need to ensure you are using a linear RGB clear color. DirectXMath colors are defined in sRGB colorspace since they are [.NET color constants](https://docs.microsoft.com/dotnet/api/system.drawing.color), so you need to replace ``ClearRenderTargetView`` in **Clear** with:
```cpp
// Use linear clear color for gamma-correct rendering.
@ -300,7 +300,7 @@ We make use of the ``Microsoft::WRL::ComPtr`` smart-pointer for managing the lif
# Error handling
Many Direct3D functions return an ``HRESULT`` which is the standard for COM APIs. For robustness and easier debugging, it is important that you always check the result of every function that return an ``HRESULT``. If you really can safely assume there is no error condition for a particular function, the function itself will return ``void`` instead of ``HRESULT``.
The Win32 game template makes use of the helper function [[ThrowIfFailed]] in the ``DX`` C++ namespace declared in ``pch.h``. This is the same helper that is used by the Windows Store and Windows phone VS templates. This helper throws a C++ exception if the standard ``FAILED`` macro returns true for a given ``HRESULT``. This is used for [fail fast](https://en.wikipedia.org/wiki/Fail-fast) error handling.
The Win32 game template makes use of the helper function [[ThrowIfFailed]] in the ``DX`` C++ namespace declared in ``pch.h``. This is the same helper that is used by the Windows Store and Windows phone VS templates. This helper throws a C++ exception if the standard ``FAILED`` macro returns true for a given ``HRESULT``. This is used for [fail fast](https://wikipedia.org/wiki/Fail-fast) error handling.
```cpp
DX::ThrowIfFailed(device->CreateTexture2D(&depthStencilDesc,
@ -350,4 +350,4 @@ For UWP, the equivalent thing is done inside the ``ViewProvider`` **Run** method
[Direct3D Game Visual Studio templates (Redux)](https://walbourn.github.io/direct3d-game-visual-studio-templates-redux/)
[Anatomy of Direct3D 11 Create Device](https://walbourn.github.io/anatomy-of-direct3d-11-create-device/)
[Manifest Madness](https://aka.ms/I6kdnw)
[64-bit programming for Game Developers](https://docs.microsoft.com/windows/desktop/DxTechArts/sixty-four-bit-programming-for-game-developers)
[64-bit programming for Game Developers](https://docs.microsoft.com/windows/win32/dxtecharts/sixty-four-bit-programming-for-game-developers)

@ -9,7 +9,7 @@ First create a new project using the instructions from the previous lessons: [[U
# Environment mapping
Environment mapping (also known as [reflection mapping](https://en.wikipedia.org/wiki/Reflection_mapping)) is a common technique for adding reflections of the surrounding environment to 3D rendered materials using a [cubemap](https://en.wikipedia.org/wiki/Cube_mapping).
Environment mapping (also known as [reflection mapping](https://wikipedia.org/wiki/Reflection_mapping)) is a common technique for adding reflections of the surrounding environment to 3D rendered materials using a [cubemap](https://wikipedia.org/wiki/Cube_mapping).
Start by saving [wood.dds](https://github.com/Microsoft/DirectXTK/wiki/media/wood.dds) and [cubemap.dds](https://github.com/Microsoft/DirectXTK/wiki/media/cubemap.dds) into your new project's directory, and then from the top menu select **Project / Add Existing Item....** Select "wood.dds" and click "OK". Repeat for "cubemap.dds"
@ -109,7 +109,7 @@ In **Game.cpp** add the following to the TODO section of **Update**:
m_effect->SetFresnelFactor(cosf(time * 2.f));
```
Build and run to see the effect of animating the [Fresnel](https://en.wikipedia.org/wiki/Fresnel_equations) factor.
Build and run to see the effect of animating the [Fresnel](https://wikipedia.org/wiki/Fresnel_equations) factor.
![Screenshot of teapot](https://github.com/Microsoft/DirectXTK/wiki/images/screenshotTeapot2.PNG)
@ -120,7 +120,7 @@ For dynamic environments, you can generate the cubemap at runtime by rendering t
# Normal mapping
[[NormalMapEffect]] is similar to the [[BasicEffect]] with the addition of a [normal texture map](https://en.wikipedia.org/wiki/Normal_mapping) and an optional [specular texture map](https://en.wikipedia.org/wiki/Specularity).
[[NormalMapEffect]] is similar to the [[BasicEffect]] with the addition of a [normal texture map](https://wikipedia.org/wiki/Normal_mapping) and an optional [specular texture map](https://wikipedia.org/wiki/Specularity).
> Note that ``NormalMapEffect`` requires Direct3D hardware feature level 10.0 or higher. It won't run on 9.x feature levels.
@ -196,13 +196,13 @@ Build and run to see the debug effect rendering a blue/purple gradient teapot:
# More to explore
* The [[EnvironmentMapEffect]] also supports spherical environment maps (a [DirectX 9](https://docs.microsoft.com/en-us/windows/win32/direct3d9/spherical-environment-mapping) feature) and dual-parabolic environment maps.
* The [[EnvironmentMapEffect]] also supports spherical environment maps (a [DirectX 9](https://docs.microsoft.com/windows/win32/direct3d9/spherical-environment-mapping) feature) and dual-parabolic environment maps.
* [[PBREffect]] is a Disney-style [[Physically-based rendering]] effect which uses an albedo map, normal map, and roughness/metalness/ambient-occlusion map along with two cubemaps for [Image-Based Lighting](https://en.wikipedia.org/wiki/Image-based_lighting).
* [[PBREffect]] is a Disney-style [[Physically-based rendering]] effect which uses an albedo map, normal map, and roughness/metalness/ambient-occlusion map along with two cubemaps for [Image-Based Lighting](https://wikipedia.org/wiki/Image-based_lighting).
* [[DualTextureEffect]] is used to render a material with two textures applied. This requires the input layout to contain a second set of _texture coordinates_. This does not perform vertex or per-pixel lighting, as the second texture is most often a [lightmap](https://en.wikipedia.org/wiki/Lightmap) with statically computed lighting information. ``.SDKMESH`` and the [Content Exporter](https://aka.ms/dxsdkcontentexporter) support exporting light-mapped models which utilize this effect (see ``-lightmaps``).
* [[DualTextureEffect]] is used to render a material with two textures applied. This requires the input layout to contain a second set of _texture coordinates_. This does not perform vertex or per-pixel lighting, as the second texture is most often a [lightmap](https://wikipedia.org/wiki/Lightmap) with statically computed lighting information. ``.SDKMESH`` and the [Content Exporter](https://aka.ms/dxsdkcontentexporter) support exporting light-mapped models which utilize this effect (see ``-lightmaps``).
* The [[AlphaTestEffect]] is used to perform pixel rejection based on an alpha reference value and function selection. It's primarily to implement techniques that relied on [legacy Direct3D 9 alpha testing](https://docs.microsoft.com/en-us/windows/win32/direct3d9/alpha-testing-state) render state. This effect is independent of the depth/stencil tests set in ``D3D11_DEPTH_STENCIL_DESC.DepthFunc`` and ``StencilFunc``.
* The [[AlphaTestEffect]] is used to perform pixel rejection based on an alpha reference value and function selection. It's primarily to implement techniques that relied on [legacy Direct3D 9 alpha testing](https://docs.microsoft.com/windows/win32/direct3d9/alpha-testing-state) render state. This effect is independent of the depth/stencil tests set in ``D3D11_DEPTH_STENCIL_DESC.DepthFunc`` and ``StencilFunc``.
**Next lesson:** [[Multistream rendering and instancing]]

@ -9,9 +9,9 @@ First create a new project using the instructions from the earlier lessons: [[Us
> If using *DirectX Tool Kit for DX12*, use [Using DeviceResources](https://github.com/microsoft/DirectXTK12/wiki/Using-DeviceResources), then [Adding the DirectX Tool Kit](https://github.com/microsoft/DirectXTK12/wiki/Adding-the-DirectX-Tool-Kit), add ``#include <Audio.h>`` to **pch.h**, and finally [[Adding audio to your project]]
# Background
Games provide an immersive visual and audio experience, and often use [3D audio effects](https://en.wikipedia.org/wiki/3D_audio_effect) to enhance the audio. The effect modifies the speaker position, pitch, and volume of a sound to provide audial cues to place it in the 3D environment. **XAudio2** itself provides the ability to specify a complex per-channel volume mapping, pitch modification, and other parameters to generate these 3D effects, but does not perform the computations. The X3DAudio library is used by *DirectX Tool Kit for Audio* to compute the virtual placement of the sound.
Games provide an immersive visual and audio experience, and often use [3D audio effects](https://wikipedia.org/wiki/3D_audio_effect) to enhance the audio. The effect modifies the speaker position, pitch, and volume of a sound to provide audial cues to place it in the 3D environment. **XAudio2** itself provides the ability to specify a complex per-channel volume mapping, pitch modification, and other parameters to generate these 3D effects, but does not perform the computations. The X3DAudio library is used by *DirectX Tool Kit for Audio* to compute the virtual placement of the sound.
See [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/xaudio2/x3daudio-overview) for more information on **X3DAudio**.
See [Microsoft Docs](https://docs.microsoft.com/windows/win32/xaudio2/x3daudio-overview) for more information on **X3DAudio**.
# Sound

@ -8,7 +8,7 @@ First create a new project using the instructions from the previous lessons: [[U
[[Adding the DirectX Tool Kit]] which we will use for this lesson.
# Background
In the [[previous lesson|Animating using model bones]], we learned the use of [[ModelBone]] as general metadata and for doing rigid-body animation of meshes. The other common use for model bones is as a 'skeleton' to control vertices for [vertex skinning](https://en.wikipedia.org/wiki/Skeletal_animation) animation.
In the [[previous lesson|Animating using model bones]], we learned the use of [[ModelBone]] as general metadata and for doing rigid-body animation of meshes. The other common use for model bones is as a 'skeleton' to control vertices for [vertex skinning](https://wikipedia.org/wiki/Skeletal_animation) animation.
Like *XNA Game Studio*, the *DirectX Tool Kit* does not provide a specific implementation of an animation control system. There are numerous approaches, and each have their own strengths and weaknesses. In this lesson, we'll cover the animation system in the Visual Studio Mesh Content Pipeline (``CMO``) and the legacy DirectX SDK sample animation system (``SDKMESH`` v1), providing some basic code for using them. Neither solution is ideal, but they do a good job of demonstrating the techniques and some trade-offs.

@ -5,12 +5,12 @@ This lesson introduces the reader to the SimpleMath game and graphics math libra
# Background
The *DirectX Tool Kit* tutorials assume a basic understanding of the classic "world -> view -> projection" [graphics pipeline](https://en.wikipedia.org/wiki/Graphics_pipeline), [transformation matricies](https://en.wikipedia.org/wiki/Transformation_matrix), and in particular the classic [affine transformations](https://en.wikipedia.org/wiki/Affine_transformation) of *translation*, *scaling*, and *rotation*.
The *DirectX Tool Kit* tutorials assume a basic understanding of the classic "world -> view -> projection" [graphics pipeline](https://wikipedia.org/wiki/Graphics_pipeline), [transformation matricies](https://wikipedia.org/wiki/Transformation_matrix), and in particular the classic [affine transformations](https://wikipedia.org/wiki/Affine_transformation) of *translation*, *scaling*, and *rotation*.
A great resource for learning more about the essential math of graphics programming, see [Essential Math for Games Programmers](http://www.essentialmath.com/).
# Coordinate system
Consistent with the original XNA Game Framework C# math library, SimpleMath assumes a [right-handed](https://en.wikipedia.org/wiki/Right-hand_rule) coordinate system, with the positive z-axis pointing toward the observer when the positive x-axis is pointing to the right, and the positive y-axis is pointing up.
Consistent with the original XNA Game Framework C# math library, SimpleMath assumes a [right-handed](https://wikipedia.org/wiki/Right-hand_rule) coordinate system, with the positive z-axis pointing toward the observer when the positive x-axis is pointing to the right, and the positive y-axis is pointing up.
# Namespace
The operator overloads defined in the SimpleMath library are defined in the ``DirectX::SimpleMath`` C++ namespace. You therefore need to add ``using`` statements to get them to properly resolve:
@ -62,7 +62,7 @@ Quaternion c = Quaternion::Slerp(a, b, 0.25f);
# Homogenous Coordinates
Matrix is 4x4 single-precision floating-point and is normally assumed to be [homogenous coordinates](https://en.wikipedia.org/wiki/Homogeneous_coordinates) as per the standard 3D transformation pipeline:
Matrix is 4x4 single-precision floating-point and is normally assumed to be [homogenous coordinates](https://wikipedia.org/wiki/Homogeneous_coordinates) as per the standard 3D transformation pipeline:
```
| _11 _12 _13 _14 |
@ -71,7 +71,7 @@ Matrix is 4x4 single-precision floating-point and is normally assumed to be [hom
| _41 _42 _43 _44 |
```
The upper-3x3 matrix is used for 3D scaling (_11, _22, _33) & rotation transformations (as well as shearing, reflection/mirroring, or other [affine transformation](https://en.wikipedia.org/wiki/Affine_transformation)):
The upper-3x3 matrix is used for 3D scaling (_11, _22, _33) & rotation transformations (as well as shearing, reflection/mirroring, or other [affine transformation](https://wikipedia.org/wiki/Affine_transformation)):
```
| _11 _12 _13 ? |

@ -37,7 +37,7 @@ Vector2 v(arr); // Creates a vector [1, 2]
* **Dot**: Returns the dot-product between two 2-vectors.
* **Cross**: Computes the geometric cross-product of two 2-vectors. See [XMVector2Cross](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector2cross).
* **Cross**: Computes the geometric cross-product of two 2-vectors. See [XMVector2Cross](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector2cross).
* **Normalize**: Computes a unit-length vector.
@ -58,9 +58,9 @@ Vector2 v(arr); // Creates a vector [1, 2]
* **Reflect**: Reflects an incident vector across a normal vector.
* **Refract**: Refracts an incident vector across a normal vector.
* **Transform**: Transform the vector by the rotation and scale in the matrix or a quaternion. There is also an overload for transforming an array of vectors. See [XMVector2Transform](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector2transform).
* **Transform**: Transform the vector by the rotation and scale in the matrix or a quaternion. There is also an overload for transforming an array of vectors. See [XMVector2Transform](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector2transform).
* **TransformNormal**: Transforms the vector by the rotation and scale in the matrix, ignoring translation (rows 2 & 3). There is also an overload for transforming an array of vectors. See [XMVector2TransformNormal](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector2transformnormal).
* **TransformNormal**: Transforms the vector by the rotation and scale in the matrix, ignoring translation (rows 2 & 3). There is also an overload for transforming an array of vectors. See [XMVector2TransformNormal](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector2transformnormal).
# Constants

@ -58,9 +58,9 @@ Vector3 v(arr); // Creates a vector [1, 2, 3]
* **Reflect**: Reflects an incident vector across a normal vector.
* **Refract**: Refracts an incident vector across a normal vector.
* **Transform**: Transform the vector by a matrix or a quaternion. See [XMVector3Transform](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector3transform). There are overloads for returning the homogenous normalized ``Vector3`` result (i.e. ``w = 1``) or the ``Vector4`` result. There is also an overload for transforming an array of vectors.
* **Transform**: Transform the vector by a matrix or a quaternion. See [XMVector3Transform](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector3transform). There are overloads for returning the homogenous normalized ``Vector3`` result (i.e. ``w = 1``) or the ``Vector4`` result. There is also an overload for transforming an array of vectors.
* **TransformNormal**: Transforms the vector by matrix, ignoring translation (row 3). There is also an overload for transforming an array of vectors. See [XMVector3TransformNormal](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector3transformnormal).
* **TransformNormal**: Transforms the vector by matrix, ignoring translation (row 3). There is also an overload for transforming an array of vectors. See [XMVector3TransformNormal](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector3transformnormal).
# Constants

@ -39,7 +39,7 @@ Vector4 v(arr); // Creates a vector [1, 2, 3, 4]
* **Dot**: Returns the dot-product of two 4-vectors.
* **Cross**: Computes the geometric dot-product of 4-vectors. See [XMVector4Cross](https://docs.microsoft.com/en-us/windows/win32/api/directxmath/nf-directxmath-xmvector4cross).
* **Cross**: Computes the geometric dot-product of 4-vectors. See [XMVector4Cross](https://docs.microsoft.com/windows/win32/api/directxmath/nf-directxmath-xmvector4cross).
* **Normalize**: Computes a unit-length vector.

@ -49,7 +49,7 @@ Viewport vp(rct); // Creates the viewport [0,0,640,480,0,1]
> If using ICoreWindow, be sure to convert logicalWidth and logicalHeight from DIPs to pixels using the window's DPI property. ``int ConvertDipsToPixels(float dips, float dpi) { return int(dips * dpi / 96.f + 0.5f); }``
* **ComputeTitleSafeArea**: When displaying on televisions, edges of the screen can't always be seen by users. This function takes a backbuffer width and height in pixels and returns a [safe area](https://en.wikipedia.org/wiki/Safe_area_%28television%29) rectangle for the content to be displayed. This function uses the [SMPTE RP 2046-2](http://www.nab.org/xert/scitech/pdfs/tv031510.pdf) standard of 90% safe area intended for LCDs, rather than the older SMPTE RP 218 intended for CRTs that used 80% safe area which is what the original XNA Game Studio math function implemented.
* **ComputeTitleSafeArea**: When displaying on televisions, edges of the screen can't always be seen by users. This function takes a backbuffer width and height in pixels and returns a [safe area](https://wikipedia.org/wiki/Safe_area_%28television%29) rectangle for the content to be displayed. This function uses the [SMPTE RP 2046-2](http://www.nab.org/xert/scitech/pdfs/tv031510.pdf) standard of 90% safe area intended for LCDs, rather than the older SMPTE RP 218 intended for CRTs that used 80% safe area which is what the original XNA Game Studio math function implemented.
> Note that the XNA Game Studio equivalent of this function only returned the reduced safe area on Xbox, and returns the full rectangle otherwise on Windows phone and PC. Because the Universal Windows Platform app can share a single binary or set of binaries across many devices, it is up to the app to determine what device it is currently running under. Therefore, this function always returns the reduced safe area and it is up to the app to apply this in the correct circumstances.

@ -19,7 +19,7 @@ This loader does not support array textures, 1D textures, 3D volume textures, cu
```
# Initialization
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any [Windows Imaging Component](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-about-windows-imaging-codec) functionality.
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any [Windows Imaging Component](https://docs.microsoft.com/windows/win32/wic/-wic-about-windows-imaging-codec) functionality.
For a Universal Windows Platform (UWP) app using ``/ZW``, the Windows Runtime and COM is initialized by the C/C++ Run-Time. For C++/WinRT applications, this is done by calling ``winrt::init_apartment();``.
@ -127,7 +127,7 @@ For all these functions above, the _maxsize_ parameter provides an upper limit o
If a _d3dContext_ is given to these functions, they will attempt to use the auto-generation of mipmaps features in the Direct3D 11 API if supported for the pixel format. Note the quality of auto-gen mipmaps is up to the driver, so can vary widely. Also if a context is passed, the function is not thread safe. If _d3dContext_ is nullptr, then it functions the same as the version which does not take a context.
For the ``Ex`` versions, the _usage_ is a [D3D11_USAGE](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_usage), typically ``D3D11_USAGE_DEFAULT``. The *bindFlags* parameter is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values, typically ``D3D11_BIND_SHADER_RESOURCE`` for textures. The _cpuAccessFlags_ parameter is ``D3D11_CPU_ACCESS_FLAG`` typically 0 for default usage textures. The _miscFlags_ parameter is a [D3D11_RESOURCE_MISC_FLAG](https://docs.microsoft.com/en-us/windows/win32/api/d3d11/ne-d3d11-d3d11_resource_misc_flag) value, usually 0.
For the ``Ex`` versions, the _usage_ is a [D3D11_USAGE](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_usage), typically ``D3D11_USAGE_DEFAULT``. The *bindFlags* parameter is one or more [D3D11_BIND_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_bind_flag) values, typically ``D3D11_BIND_SHADER_RESOURCE`` for textures. The _cpuAccessFlags_ parameter is ``D3D11_CPU_ACCESS_FLAG`` typically 0 for default usage textures. The _miscFlags_ parameter is a [D3D11_RESOURCE_MISC_FLAG](https://docs.microsoft.com/windows/win32/api/d3d11/ne-d3d11-d3d11_resource_misc_flag) value, usually 0.
# Examples
@ -258,7 +258,7 @@ if (file)
}
```
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/windows/uwp/files/file-access-permissions)
# Debugging texture loading

@ -30,7 +30,7 @@ WORD nBlockAlign;
# PCMWAVEFORMAT
The next simplest form is another partial ``WAVEFORMATEX`` version using an older structure (it's only 16 bytes instead of 18 bytes). This is commonly used to encode [PCM](https://en.wikipedia.org/wiki/Pulse-code_modulation) format data using ``WAVE_FORMAT_PCM`` or ``WAVE_FORMAT_IEEE_FLOAT``, although it's recommended you use a complete ``WAVEFORMATEX`` instead.
The next simplest form is another partial ``WAVEFORMATEX`` version using an older structure (it's only 16 bytes instead of 18 bytes). This is commonly used to encode [PCM](https://wikipedia.org/wiki/Pulse-code_modulation) format data using ``WAVE_FORMAT_PCM`` or ``WAVE_FORMAT_IEEE_FLOAT``, although it's recommended you use a complete ``WAVEFORMATEX`` instead.
```cpp
WAVEFORMAT wf;
@ -45,7 +45,7 @@ XAudio2 only supports a ``wBitsPerSample`` of 32 for WAVE_FORMAT_IEEE_FLOAT.
# ADPCMWAVEFORMAT
A common compressed encoding for audio data is [ADPCM](https://en.wikipedia.org/wiki/Adaptive_differential_pulse-code_modulation) which is indicated with ``WAVE_FORMAT_ADPCM``.
A common compressed encoding for audio data is [ADPCM](https://wikipedia.org/wiki/Adaptive_differential_pulse-code_modulation) which is indicated with ``WAVE_FORMAT_ADPCM``.
```cpp
WAVEFORMATEX wfx;

@ -21,7 +21,7 @@ std::unique_ptr<WaveBank> wb;
wb = std::make_unique<WaveBank>( audEngine.get(), "wavebank.xwb" ) );
```
For exception safety, it is recommended you make use of the C++ [RAII](http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
For exception safety, it is recommended you make use of the C++ [RAII](http://wikipedia.org/wiki/Resource_Acquisition_Is_Initialization) pattern and use a ``std::unique_ptr`` or ``std::shared_ptr``
Note that in-memory banks may still be loading the wave data asynchronously after the return of this constructor. You can see if the wave data has completed loading by calling **IsPrepared**. If you call **Play** or **CreateInstance** before the wave data has loaded, then the thread will wait until the load is complete before returning.

@ -1,7 +1,7 @@
|[[Getting Started]]|
|---|
This lesson covers the basics of writing your own [HLSL shaders](https://en.wikipedia.org/wiki/High-Level_Shading_Language) and using them with _DirectX Tool Kit_, in particular to customize **SpriteBatch**.
This lesson covers the basics of writing your own [HLSL shaders](https://wikipedia.org/wiki/High-Level_Shading_Language) and using them with _DirectX Tool Kit_, in particular to customize **SpriteBatch**.
# Setup
First create a new project using the instructions from the previous lessons: [[Using DeviceResources]] and
@ -553,7 +553,7 @@ float4 main(float4 color : COLOR0, float2 texCoord : TEXCOORD0) : SV_Target0
![Screenshot of post-processed torus](https://github.com/Microsoft/DirectXTK/wiki/images/postprocessPass2.png)
We take that result in ``m_renderTarget2`` and then blur it vertically using the same shader--we are using a [Gaussian blur](https://en.wikipedia.org/wiki/Gaussian_blur) which is a separable filter which allows us to do the filter in two simple render passes one for each dimension--back into ``m_renderTarget1``.
We take that result in ``m_renderTarget2`` and then blur it vertically using the same shader--we are using a [Gaussian blur](https://wikipedia.org/wiki/Gaussian_blur) which is a separable filter which allows us to do the filter in two simple render passes one for each dimension--back into ``m_renderTarget1``.
![Screenshot of post-processed torus](https://github.com/Microsoft/DirectXTK/wiki/images/postprocessPass3.png)
@ -606,7 +606,7 @@ DirectX Tool Kit docs [[SpriteBatch]]
[HLSL, FXC, and D3DCompile](https://aka.ms/Tuoxjdx)
[What's up with D3DCompiler_xx.dll](https://walbourn.github.io/whats-up-with-d3dcompiler_xx-dll)
[Compiling Shaders](https://docs.microsoft.com/en-us/windows/desktop/direct3dhlsl/dx-graphics-hlsl-part1)
[Compiling Shaders](https://docs.microsoft.com/windows/win32/direct3dhlsl/dx-graphics-hlsl-part1)
# Credits

@ -44,7 +44,7 @@ The file-name parameter indicates the ``.wav`` file(s) to add to the wave bank.
# Example usage
Open a [Command Prompt](http://windows.microsoft.com/en-us/windows/command-prompt-faq), and change to the directory containing ``XWBTool.exe`` (i.e. ``...\DirectXTK\XWBTool\bin\Release``)
Open a Command Prompt, and change to the directory containing ``XWBTool.exe`` (i.e. ``...\DirectXTK\XWBTool\bin\Release``)
Enter the following command-line after changing to the appropriate directory:
@ -71,7 +71,7 @@ For streaming wave banks, the layout of the file is purposely designed to suppor
Use of ``-af`` is recommended when creating streaming wave banks for Xbox Series X\|S.
See [Wikipedia](https://en.wikipedia.org/wiki/Advanced_Format) and [Microsoft Docs](https://docs.microsoft.com/en-us/windows/win32/w8cookbook/advanced-format--4k--disk-compatibility-update) for more information.
See [Wikipedia](https://wikipedia.org/wiki/Advanced_Format) and [Microsoft Docs](https://docs.microsoft.com/windows/win32/w8cookbook/advanced-format--4k--disk-compatibility-update) for more information.
Compact wave banks (``-c``) are not compatible with Advanced Format sector alignment (``-af``), so can't be used together.
@ -84,7 +84,7 @@ The XACT3 GUI and/or the XACTBLD command-line tool in the legacy DirectX SDK (Di
[KB2728613](https://support.microsoft.com/en-us/kb/2728613)
[Where is the DirectX SDK?](https://docs.microsoft.com/en-us/windows/desktop/directx-sdk--august-2009-)
[Where is the DirectX SDK?](https://docs.microsoft.com/windows/win32/directx-sdk--august-2009-)
**Compact wave banks**: The legacy XACT3 ENGINE only supports 'streaming' compact wave banks not 'in-memory' compact wave banks. The XACT3 GUI / XACTBLD toolset will therefore only create 'standard' in-memory wave banks. There is also a known bug in the DirectX SDK (June 2010) version of the XACT3 GUI / XACTBLD toolsets that will not attempt to create a compact wave bank if the wave data size exceeds 2,097,151 (~2 MB).

@ -87,4 +87,4 @@ DDS_HEADER_XBOX
Other ``DDS`` loaders and viewers will fail to recognize this pixel format, and other ``DDS`` creation tools do not support creating it. See the **xtexconv** sample for more information on creating this variant form of DDS files.
[DDS on Microsoft Docs](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds)
[DDS on Microsoft Docs](https://docs.microsoft.com/windows/win32/direct3ddds/dx-graphics-dds)