CaptureTexture

DirectXTex

Captures a Direct3D render target and returns an image.

This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using ScreenGrab DX11 / DX12 instead of DirectXTex.

 HRESULT CaptureTexture(
    ID3D11Device* pDevice, ID3D11DeviceContext* pContext,
    ID3D11Resource* pSource,
    ScratchImage& result );

HRESULT CaptureTexture(
    ID3D12CommandQueue* pCommandQueue,
    ID3D12Resource* pSource,
    bool isCubeMap,
    ScratchImage& result,
    D3D12_RESOURCE_STATES beforeState = D3D12_RESOURCE_STATE_RENDER_TARGET,
    D3D12_RESOURCE_STATES afterState = D3D12_RESOURCE_STATE_RENDER_TARGET );

Parameters

These functions take a Direct3D device and either a device context or command queue to perform the 'read back' operation.

For Direct3D 12, the before and after resource states are provided for any required resource state transitions. The isCubeMap indicates the result should assume the texture array is a cubemap array.

Returns

The function will succeed with an S_OK or will return a HRESULT error code (E_INVALIDARG, E_FAIL, E_POINTER, E_UNEXPECTED, HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW), or a value returned by Direct3D).

Exceptions

These functions are marked noexcept, and do not throw C++ exceptions.

Remarks

This function can support capturing 1D, 1D array, 2D, 2D array, cubemap, cubemap array, and 3D textures in the full range of DXGI formats.

MSAA textures are resolved before being captured.

If support for DirectX 12 is required, you must explicitly include #include <d3d12.h> before including #include "DirectXTex.h"

DirectX 12 version does not support capturing textures from depth/stencil planar formats.

Example

ScratchImage image;
HRESULT hr = CaptureTexture( device, context, pResource, image );
if ( SUCCEEDED(hr) )
{
    hr = SaveToDDSFile( image.GetImages(),
        image.GetImageCount(), image.GetMetadata(),
        DDS_FLAGS_NONE, filename );
    if ( FAILED(hr) )
    {
        ...