DirectXHelpers (original) (raw)

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 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 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).