NEWS: This project is now hosted on GitHub https://github.com/Microsoft/DirectXTK. This site is being maintained for now, but please move to using GitHub https://github.com/Microsoft/DirectXTK/wiki/DirectXTK

A Direct3D 11 2D texture save routine for generating a "screenshot" from a render target texture. There is a function that will dump the 2D texture to a .DDS file, and another that will write using WIC (BMP, JPEG, PNG, TIFF, GIF, JPEG-XR / HD Photo, or other WIC supported file container).

These writers do not support array textures, 1D textures, 3D volume textures, or cubemaps. Mipmaps are also ignored. For those scenarios, use the DirectXTex library functionality. The ScreenGrab module is really designed to make a quick and light-weight solution for capturing screenshots at runtime.

MSAA textures are resolved before being written.

Also part of DirectXTex http://go.microsoft.com/fwlink/?LinkId=248926

The module assumes that the client code will have already called CoInitialize, CoInitializeEx, or Windows::Foundation::Initialize as needed by the application before calling the WIC save routines

Header

#include <ScreenGrab.h>

Functions

SaveDDSTextureToFile
Saves a texture to a DDS file on disk. It performs no format conversions, but will try to favor writing legacy .DDS files when possible for improved tool support.

HRESULT SaveDDSTextureToFile( _In_ ID3D11DeviceContext* pContext,
    _In_ ID3D11Resource* pSource,
    _In_z_ LPCWSTR fileName );

SaveWICTextureToFile
Saves a texture to a WIC-supported bitmap file on disk. The caller provides the desired WIC container format via guidContainerFormat and can optionally specify a desired WIC pixel format via targetFormat (which will result in E_FAIL if the requested pixel format is not supported by the WIC codec). If no WIC pixel format GUID is provided as the targetFormat parameter, it will default to a non-alpha format since 'screenshots' usually ignore the alpha channel in render targets.

HRESULT SaveWICTextureToFile( _In_ ID3D11DeviceContext* pContext,
    _In_ ID3D11Resource* pSource,
    _In_ REFGUID guidContainerFormat, 
    _In_z_ LPCWSTR fileName,
    _In_opt_ const GUID* targetFormat = nullptr,
    _In_opt_ std::function<void(IPropertyBag2*)> setCustomProps = nullptr );

NOTE: SaveWICTextureToFile is not supported on Windows Phone 8.0, because WIC is not available on that platform

Examples

This example saves a JPEG screenshot given a ID3D11DeviceContext immContext and IDXGISwapChain swapChain.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11Texture2D> backBuffer;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( ID3D11Texture2D ),
   reinterpret_cast<LPVOID*>( backBuffer.GetAddressOf() ) );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext.Get(), backBuffer.Get(),
                GUID_ContainerFormatJpeg, L"SCREENSHOT.JPG" );
}
DX::ThrowIfFailed(hr);

Here is an example of explicitly writing a screenshot as a 16-bit (5:6:5) BMP.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11Texture2D> backBuffer;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( ID3D11Texture2D ),
   reinterpret_cast<LPVOID*>( backBuffer.GetAddressOf() ) );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext.Get(), backBuffer.Get(),
                GUID_ContainerFormatBmp, L"SCREENSHOT.BMP",
                &GUID_WICPixelFormat16bppBGR565 );
}
DX::ThrowIfFailed(hr);

When writing WIC files, you can also provide a callback for setting specific encoding options.

using namespace DirectX;
using namespace Microsoft::WRL;

ComPtr<ID3D11Texture2D> backBuffer;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( ID3D11Texture2D ),
   reinterpret_cast<LPVOID*>( backBuffer.GetAddressOf() ) );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext.Get(), backBuffer.Get(),
                GUID_ContainerFormatTiff, L"SCREENSHOT.TIF", nullptr,
                [&](IPropertyBag2* props)
                {
                    PROPBAG2 options[2] = { 0, 0 };
                    options[0].pstrName = L"CompressionQuality";
                    options[1].pstrName = L"TiffCompressionMethod";

                    VARIANT varValues[2];
                    varValues[0].vt = VT_R4;
                    varValues[0].fltVal = 0.75f;

                    varValues[1].vt = VT_UI1;
                    varValues[1].bVal = WICTiffCompressionNone;

                    (void)props->Write( 2, options, varValues ); 
                });
}
DX::ThrowIfFailed(hr);

Release Notes

  • If built with #define DXGI_1_2_FORMATS the DDS writer supports BGRA 4:4:4:4 files.
  • JPEG-XR / HD Photo supports nearly all WIC pixel formats including floating-point for both encoding and decoding.
  • TIFF can contain floating-point data (128bpp or 96bpp), but the WIC built-in codec can only decode such images. It always converts floating-point data to unorm when encoding.
  • Paletted WIC formats are not supported for writing by the SaveWICTextureToFile function.

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.
  • If WIC2 is supported, then this function can make use of the new WIC pixel format GUID_WICPixelFormat96bppRGBFloat.
http://support.microsoft.com/kb/2670838

Windows Store apps

For Save*TextureToFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:

auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base

If you are going to immediately copy it to another location via StorageFolder::MoveAndReplaceAsync, then use the app's temporary folder:

#include <ppltasks.h>
using namespace concurrency;

using Windows::Storage;
using Windows::Storage::Pickers;

auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;

WCHAR fname[ _MAX_PATH ];
wcscpy_s( fname, folder->Path->Data() );
wcscat_s( fname, L"\\screenshot.jpg" );

// note that context use is not thread-safe
HRESULT hr = SaveWICTextureToFile( immContext.Get(), backBuffer.Get(),
    GUID_ContainerFormatJpeg, fname  );

DX::ThrowIfFailed(hr);

create_task(savePicker->PickSaveFileAsync()).then([](StorageFile^ file)
{
    if ( file )
    {
        auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
        auto task = create_task( folder->GetFileAsync("screenshot.jpg") );
        task.then([file](StorageFile^ tempFile) ->IAsyncAction^
        {
            return tempFile->MoveAndReplaceAsync( file );
        });
    }
});

https://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx
http://msdn.microsoft.com/en-us/library/windows/apps/xaml/windows.storage.applicationdata.temporaryfolder.aspx

Last edited Jul 28, 2015 at 7:10 PM by walbourn, version 36