A streamlined version of the DirectX SDK sample DDSWithoutD3DX11 texture loading code for a simple light-weight runtime .DDS file loader. This version only supports Direct3D 11 and performs no runtime pixel data conversions (see
Release Notes for more details). This is ideal for runtime usage, and supports the full complement of Direct3D 11 texture resources (1D, 2D, volume maps, cubemaps, mipmap levels, texture arrays, BC formats, etc.). It supports both legacy and 'DX10' extension header format .dds files.
Also part of DirectXTK
http://go.microsoft.com/fwlink/?LinkId=248929Functions
CreateDDSTextureFromMemoryLoads a .DDS file assuming the image of the file is located in a memory buffer. Creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.
HRESULT CreateDDSTextureFromMemory( _In_ ID3D11Device* d3dDevice,
_In_reads_bytes_(ddsDataSize) const uint8_t* ddsData, _In_ size_t ddsDataSize,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_In_ size_t maxsize = 0, _Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );
HRESULT CreateDDSTextureFromMemory( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
_In_reads_bytes_(ddsDataSize) const uint8_t* ddsData, _In_ size_t ddsDataSize,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_In_ size_t maxsize = 0, _Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.
HRESULT CreateDDSTextureFromFile( _In_ ID3D11Device* d3dDevice,
_In_z_ constwchar_t* szFileName,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_In_ size_t maxsize = 0, _Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );
HRESULT CreateDDSTextureFromFile( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
_In_z_ constwchar_t* szFileName,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_In_ size_t maxsize = 0, _Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );These versions provide explicit control over the created resource's usage, binding flags, CPU access flags, and miscellaneous flags for advanced / expert scenarios. The standard routines default to D3D11_USAGE_DEFAULT, D3D11_BIND_SHADER_RESOURCE, 0, and 0 respectively. For cubemaps, the miscellaneous flags default to D3D11_RESOURCE_MISC_TEXTURECUBE. For auto-gen mipmaps, the default binding flags are D3D11_BIND_SHADER_RESOURCE | D3D11_BIND_RENDER_TARGET and miscellaneous flags is set to D3D11_RESOURCE_MISC_GENERATE_MIPS. There is also a 'forceSRGB' option for working around gamma issues with content that is in the sRGB or similar color space but is not encoded explicitly as an SRGB format. Note that the 'maxsize' parameter is not at the end of the parameter list like it is in the non-Ex version.
HRESULT CreateDDSTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
_In_reads_bytes_(ddsDataSize) const uint8_t* ddsData, _In_ size_t ddsDataSize,
_In_ size_t maxsize,
_In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
_In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
_In_ bool forceSRGB,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );
HRESULT CreateDDSTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
_In_reads_bytes_(ddsDataSize) const uint8_t* ddsData, _In_ size_t ddsDataSize,
_In_ size_t maxsize,
_In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
_In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
_In_ bool forceSRGB,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );
HRESULT CreateDDSTextureFromFileEx( _In_ ID3D11Device* d3dDevice,
_In_z_ constwchar_t* szFileName,
_In_ size_t maxsize,
_In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
_In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
_In_ bool forceSRGB,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );
HRESULT CreateDDSTextureFromFileEx( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
_In_z_ constwchar_t* szFileName,
_In_ size_t maxsize,
_In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
_In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
_In_ bool forceSRGB,
_Outptr_opt_ ID3D11Resource** texture, _Outptr_opt_ ID3D11ShaderResourceView** textureView,
_Out_opt_ DDS_ALPHA_MODE* alphaMode = nullptr );Parameters
If
maxsize parameter non-zero, then all mipmap levels larger than the maxsize are ignored before creating the Direct3D 11 resource. This allows for load-time scaling. If '0', then if the attempt to create the Direct3D 11 resource fails and there are mipmaps present, it will retry assuming a maxsize based on the device's current feature level.
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.
The last optional parameter
alphaMode is a pointer to return the
alpha mode of the DDS file. This can be one of the following values to return information about the alpha channel if present in the file:
- DDS_ALPHA_MODE_UNKNOWN (0) - This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
- DDS_ALPHA_MODE_STRAIGHT (1) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. Viewers should use the alpha channel with 'normal' alpha blending.
- DDS_ALPHA_MODE_PREMULTIPLIED (2) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
- 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.
Example
This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.
ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &pSRV );
if (FAILED(hr))
// error
Feature Level Notes
In order to support all feature levels, you should make sure your DDS textures are mip-mapped so that they contain a suitably sized image. Non-mipmapped textures will either need explicit feature level association, or be sized less than or equal to 2048 for 1D, 2048 x 2048 for 2D, 512 x 512 for cubemaps, and 256 x 256 x 256 for volume maps.
Texture arrays require Feature Level 10.0 or later. Cubemap arrays requires Feature Level 10.1 or later.
Be sure to review the various format limitations for the different feature levels. To support all feature levels, stick with textures in the following formats:
- DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
- DXGI_FORMAT_R8G8B8A8_SNORM
- DXGI_FORMAT_B8G8R8A8_UNORM
- DXGI_FORMAT_R16G16_SNORM
- DXGI_FORMAT_R8G8_SNORM
- DXGI_FORMAT_R8_UNORM
- DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
- DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
- DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB
On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.
Release Notes
- DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format
- D3DFMT_UYVY (YUV 4:2:2 16bpp) - Swizzle to YUY2
http://go.microsoft.com/fwlink/?LinkId=248926.
- If built with #define DXGI_1_2_FORMATS the code supports loading BGRA 4:4:4:4 files. Otherwise, it fails.
- On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.
- Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.
Further Reading
http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspxhttp://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspxWindows Store apps
The texture loader function is typically used to load texture files from the application's install folder as they were included with the AppX package. If you wish to create a texture from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use DDSTextureLoader on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
if (file)
{
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
{
if ( tempFile )
{
HRESULT hr = CreateDDSTextureFromFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
});