DirectXHelpers

DirectXTK

Contains various C++ utilities that simplify Direct3D 12 programming.

Direct3D 12 "core" helpers

The d3dx12.h header provides a number of helper classes intended to simplify the usage of the API when working with C++. These are all in the global C++ namespace, and are documented on Microsoft Docs.

CD3DX12_RECT
CD3DX12_VIEWPORT
CD3DX12_BOX
CD3DX12_DEPTH_STENCIL_DESC / CD3DX12_DEPTH_STENCIL_DESC1 / CD3DX12_DEPTH_STENCIL_DESC2
CD3DX12_BLEND_DESC
CD3DX12_RASTERIZER_DESC / CD3DX12_RASTERIZER_DESC1
CD3DX12_RESOURCE_ALLOCATION_INFO
CD3DX12_HEAP_PROPERTIES
CD3DX12_HEAP_DESC
CD3DX12_CLEAR_VALUE
CD3DX12_RANGE
CD3DX12_RANGE_UINT64
CD3DX12_SUBRESOURCE_RANGE_UINT64
CD3DX12_SHADER_BYTECODE
CD3DX12_TILED_RESOURCE_COORDINATE
CD3DX12_TILE_REGION_SIZE
CD3DX12_SUBRESOURCE_TILING
CD3DX12_TILE_SHAPE
CD3DX12_RESOURCE_BARRIER
CD3DX12_PACKED_MIP_INFO
CD3DX12_SUBRESOURCE_FOOTPRINT
CD3DX12_TEXTURE_COPY_LOCATION
CD3DX12_DESCRIPTOR_RANGE / CD3DX12_DESCRIPTOR_RANGE1
CD3DX12_ROOT_DESCRIPTOR_TABLE / CD3DX12_ROOT_DESCRIPTOR_TABLE1
CD3DX12_ROOT_CONSTANTS
CD3DX12_ROOT_DESCRIPTOR/ CD3DX12_ROOT_DESCRIPTOR1
CD3DX12_ROOT_PARAMETER / CD3DX12_ROOT_PARAMETER1
CD3DX12_STATIC_SAMPLER_DESC
CD3DX12_ROOT_SIGNATURE_DESC
CD3DX12_VERSIONED_ROOT_SIGNATURE_DESC
CD3DX12_CPU_DESCRIPTOR_HANDLE
CD3DX12_GPU_DESCRIPTOR_HANDLE
CD3DX12_RESOURCE_DESC / CD3DX12_RESOURCE_DESC1
CD3DX12_VIEW_INSTANCING_DESC
CD3DX12_RT_FORMAT_ARRAY
CD3DX12_PIPELINE_STATE_STREAM_SUBOBJECT
CD3DX12_PIPELINE_STATE_STREAM - CD3DX12_PIPELINE_STATE_STREAM4
D3DX12_MESH_SHADER_PIPELINE_STATE_DESC
D3D12CalcSubresource
D3D12DecomposeSubresource
D3D12GetFormatPlaneCount
MemcpySubresource
GetRequiredIntermediateSize
UpdateSubresources
D3D12IsLayoutOpaque
CommandListCast
D3DX12SerializeVersionedRootSignature
D3DX12ParsePipelineStream
CD3DX12_BARRIER_SUBRESOURCE_RANGE
CD3DX12_GLOBAL_BARRIER
CD3DX12_BUFFER_BARRIER
CD3DX12_TEXTURE_BARRIER
CD3DX12_BARRIER_GROUP

Note that d3dx12.h is not included in the Windows SDK, nor is it a part of the DirectX Tool Kit. It is included in the DirectX project templates built into Visual Studio and in the Direct3D Game VS Templates. You can find the latest version on GitHub.

For Xbox One development d3dx12_x.h is included in the Xbox One XDK / Microsoft GDKX; for Xbox Series X|S development you use d3dx12_xs.h.

D3DX12 State Object Creation Helpers

CD3DX12_STATE_OBJECT_DESC
CD3DX12_DXIL_LIBRARY_SUBOBJECT
CD3DX12_EXISTING_COLLECTION_SUBOBJECT
CD3DX12_SUBOBJECT_TO_EXPORTS_ASSOCIATION_SUBOBJECT
CD3DX12_DXIL_SUBOBJECT_TO_EXPORTS_ASSOCIATION
CD3DX12_HIT_GROUP_SUBOBJECT
CD3DX12_RAYTRACING_SHADER_CONFIG_SUBOBJECT
CD3DX12_RAYTRACING_PIPELINE_CONFIG_SUBOBJECT / CD3DX12_RAYTRACING_PIPELINE_CONFIG1_SUBOBJECT
CD3DX12_GLOBAL_ROOT_SIGNATURE_SUBOBJECT
CD3DX12_LOCAL_ROOT_SIGNATURE_SUBOBJECT
CD3DX12_STATE_OBJECT_CONFIG_SUBOBJECT
CD3DX12_NODE_MASK_SUBOBJECT

If you define D3DX12_NO_STATE_OBJECT_HELPERS before including d3dx12.h you prevent the definition of these types which require the use of Standard C++ Library.

Checking Feature Support in Direct3D 12

The latest version of d3dx12.h includes CD3DX12FeatureSupport. See this blog post for details.

If you define D3DX12_NO_CHECK_FEATURE_SUPPORT_CLASS before including d3dx12.h you prevent the definition of this class which require the use of Standard C++ Library.

Resource barrier helpers

The DirectXHelpers.h header includes the following helpers in the DirectX namespace:

TransitionResource: Inserts a resource barrier into the command list if the before and after state parameters are not the same.
ScopedBarrier: RAII-style class for applying resource barriers to a graphics command list, and then reversing them.

For more information, see Resource Barriers.

View helpers

CreateShaderResourceView: Simplifies creating a texture heap descriptor from a resource. See DDSTextureLoader and WICTextureLoader for example usage. The main difference between this and providing a nullptr description is that this helper supports cubemaps.
CreateBufferShaderResourceView: This version supports creating SRVs for buffer resources.
CreateUnorderedAccessView: Simplifies creating a UAV descriptor from a resource.
CreateBufferUnorderedAccessView: This version supports creating UAVs for buffer resources.
CreateRenderTargetView: Simplifies creating a RTV descriptor from a resource.

Misc helpers

CreateRootSignature: Combines the D3D12SerializeRootSignature and CreateRootSignature calls which are typically used together. See PSOs, Shaders, and Signatures for more information.
GetTextureSize: Returns the width and height of the texture resource as a XMUINT2 for simplified use with SpriteBatch.
IsPowerOf2: Tests if a value a power of 2.
AlignDown: Aligns a value down to the next power of 2.
AlignUp: Aligns a value up to the next power of 2.

Debug object naming

To help track down resource leaks, the Direct3D 12 debug layer allows you to provide debug names to Direct3D 12 objects. The SetDebugObjectName template simplifies this for static debug name strings.

DX::ThrowIfFailed(
    device->CreateComputePipelineState(&desc,
    IID_PPV_ARGS(m_pipelineState.GetAddressOf()))
);

SetDebugObjectName(m_pipelineState.Get(), L"FancyEffectPSO");

PIX events

The Windows SDK header pix.h defines various standard PIX events for use with Visual Studio Graphics Diagnostics. This header has been deprecated for DirectX 12. For Direct3D 12 on Windows, you should use the latest version of PIX, #include <pix3.h> instead of pix.h, and add the WinPixEventRuntime NuGet package to your project.

The DirectXHelpers.h header provides a ScopedPixEvent class if either pix.h or pix3.h is included before DirectXHelpers.h.

#include <pix3.h>

#include "DirectXHelpers.h"

Xbox-specific

A number of DirectX APIs use the COM parameter pattern of (..., REFIID riid, LPVOID *ppv). In these cases, the IID_PPV_ARGS macro is often employed such as the following:

using Microsoft::WRL::ComPtr;

ComPtr<ID3D12PipelineState> pso;

DX::ThrowIfFailed(
    device->CreateComputePipelineState(&desc,
    IID_PPV_ARGS(&pso))
);

The IID_PPV_ARGS macro works on any type that's derived from IUnknown.

For Xbox One XDK / Microsoft GDKX development, however, the Direct3D 12.X Runtime variant does not make use of the standard IUnknown interface (this is referred to as the 'monolithic' runtime vs. the Windows-style 'stock' runtime). This provides significant software optimizations for the fixed-hardware nature of the console, and generally is client-code compatible. The one exception is that this breaks IID_PPV_ARGS. Therefore, the Direct3D 12.X headers include a IID_GRAPHICS_PPV_ARGS macro which works on the variant DirectX APIs in the same way.

In order to simplify coding that is portable to both 'stock' PC and 'monolithic' Xbox, all usage of IID_PPV_ARGS within the library is replaced with IID_GRAPHICS_PPV_ARGS for graphics APIs. The DirectXHelpers.h provides a simple macro that maps IID_GRAPHICS_PPV_ARGS to IID_PPV_ARGS for non-Xbox platforms. This helper is available for client code as well.

#include "DirectXHelpers.h"

using Microsoft::WRL::ComPtr;

ComPtr<ID3D12PipelineState> pso;

DX::ThrowIfFailed(
    device->CreateComputePipelineState(&desc,
    IID_GRAPHICS_PPV_ARGS(&pso))
);

Note that IID_PPV_ARGS is still used on Xbox for COM APIs like the Windows Imaging Component (WIC).

All content and source code for this package are subject to the terms of the MIT License.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.