Quantcast
Channel: DirectXTex texture processing library
Viewing all 1174 articles
Browse latest View live

Updated Release: February 2014 (Feb 24, 2014)

$
0
0
February 24, 2014
  • Direct3D 11 video and Xbox One extended format support
  • New APIs: IsPlanar, IsPalettized, IsDepthStencil, ConvertToSinglePlane
  • Added 'alphaWeight' parameter to GPU Compress [breaking change]
  • texconv '-aw' switch to control the alpha weighting for the BC7 GPU compressor
  • Fixed bug with ordered dithering in non-WIC conversion codepaths
  • Fixed SaveToDDS* functions when using arbitrary row pitch values

Released: February 2014 (Feb 24, 2014)

$
0
0
February 24, 2014
  • Direct3D 11 video and Xbox One extended format support
  • New APIs: IsPlanar, IsPalettized, IsDepthStencil, ConvertToSinglePlane
  • Added 'alphaWeight' parameter to GPU Compress [breaking change]
  • texconv '-aw' switch to control the alpha weighting for the BC7 GPU compressor
  • Fixed bug with ordered dithering in non-WIC conversion codepaths
  • Fixed SaveToDDS* functions when using arbitrary row pitch values

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions 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 for both functions 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.

CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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. 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.

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

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions 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 for both functions 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.
CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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. 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.

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

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions 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 for both functions 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.
CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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. 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.

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

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions 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 for both functions 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.
CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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. 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.

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

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions 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 for both functions 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.
CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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.

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

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: DDSTextureLoader

$
0
0
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=248929

Functions

CreateDDSTextureFromMemory
Loads 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 );

CreateDDSTextureFromFile
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 );

CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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.aspx

http://blogs.msdn.com/b/chuckw/archive/2012/06/20/direct3d-feature-levels.aspx

http://msdn.microsoft.com/en-us/library/windows/desktop/bb219822.aspx

Windows 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);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: WICTextureLoader

$
0
0
A Direct3D 11 2D texture loader that uses WIC to load a bitmap (BMP, JPEG, PNG, TIFF, GIF, HD Photo, or other WIC supported file container), resize if needed based on the current feature level (or by explicit parameter), format convert to a standard DXGI format if required, and then create a 2D texture. Furthermore, if a Direct3D 11 device context is provided and the current device supports it for the given pixel format, it will auto-generate mipmaps.

This loader does not support array textures, 1D textures, 3D volume textures, or cubemaps. For these scenarios, use the .DDS file format and DDSTextureLoader instead.

DDSTextureLoader is recommended for fully "precooked" textures for maximum performance and image quality, but this loader can be useful for creating simple 2D texture from standard image files at runtime.

Also part of DirectXTK http://go.microsoft.com/fwlink/?LinkId=248929

NOTE: WICTextureLoader is not supported on Windows Phone 8, because WIC is not available on that platform.

The module assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling the WIC loader routines

Functions

CreateWICTextureFromMemory
Loads a WIC-supported bitmap file from a memory buffer. It creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromMemoryEx
CreateWICTextureFromFileEx
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 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.

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView);

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice, _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView);

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

Parameters

For all these functions above, the maxsize parameter provides an upper limit on the size of the resulting texture. If given a 0, the functions assume a maximum size determined from the device's current feature level. If the bitmap file contains a larger image, it will be resized using WIC at load-time to provide scaling.

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.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering. It also makes use of the immediate ID3D11DeviceContext immContext to auto-gen mipmaps if supported.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateWICTextureFromFile( d3dDevice, immContext, L"LOGO.BMP",
    nullptr, &pSRV );
if (FAILED(hr))
   // error

Release Notes

  • On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, 16bpp pixel formats will be converted to a RGBA 32-bit format.
  • WICTextureLoader cannot load .TGA files unless the system has a 3rd party WIC codec installed. You must use the DirectXTex library for TGA file format support without relying on an add-on WIC codec.
  • While there is no explicit 'sRGB' pixel format defined for WIC, the load function will check for known metadata tags and may return DXGI_FORMAT_*_SRGB formats if there are equivalents of the same size and channel configuration available.

Implementation Details

  • The conversion tables are designed so that they prefer to convert to RGB if a conversion is required as a general preferance for DXGI 1.0 supporting formats supported by WDDM 1.0 drivers. The majority of Direct3D 11 devices actually support BGR DXGI 1.1 formats so we use them when they are the best match. For example, GUID_WICPixelFormat32bppBGRA loads directly as DXGI_FORMAT_B8G8R8A8_UNORM, but GUID_WICPixelFormat32bppPBGRA converts to DXGI_FORMAT_R8G8B8A8_UNORM.
  • GUID_WICPixelFormatBlackWhite is always converted to a greyscale DXGI_FORMAT_R8_UNORM since DXGI_FORMAT_R1_UNORM is not supported by Direct3D 10.x/11.x.
  • GUID_WICPixelFormat32bppRGBE is an 8:8:8:8 format, which does not match DXGI_FORMAT_R9G9B9E5_SHAREDEXP. This WIC pixel format is therefore converted to GUID_WICPixelFormat128bppRGBAFloat and returns as DXGI_FORMAT_R32G32B32A32_FLOAT.

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.
  • If WIC2 is supported, then it will load the new WIC pixel format GUID_WICPixelFormat96bppRGBFloat directly as DXGI_FORMAT_R32G32B32_FLOAT. Otherwise the module converts this to DXGI_FORMAT_R32G32B32A32_FLOAT.
  • If WIC2 is supported, then it will include conversions cases for the new WIC pixel formats GUID_WICPixelFormat32bppRGB, GUID_WICPixelFormat64bppRGB, and GUID_WICPixelFormat64bppPRGBAHalf.
  • If WIC2 is supported, then it will convert the WIC pixel format GUID_WICPixelFormat96bppRGBFixedPoint to DXGI_FORMAT_R32G32B32_FLOAT. There is special-case handling so that if auto-gen mips fails for this format (this is optional support for Feature Level 10.0 or later devices), it will use DXGI_FORMAT_R32G32B32A32_FLOAT instead (which has required support for Feature Level 10.0 or later devices).
http://support.microsoft.com/kb/2670838

Windows 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 WICTextureLoader 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 = CreateWICTextureFromFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: WICTextureLoader

$
0
0
A Direct3D 11 2D texture loader that uses WIC to load a bitmap (BMP, JPEG, PNG, TIFF, GIF, HD Photo, or other WIC supported file container), resize if needed based on the current feature level (or by explicit parameter), format convert to a standard DXGI format if required, and then create a 2D texture. Furthermore, if a Direct3D 11 device context is provided and the current device supports it for the given pixel format, it will auto-generate mipmaps.

This loader does not support array textures, 1D textures, 3D volume textures, or cubemaps. For these scenarios, use the .DDS file format and DDSTextureLoader instead.

DDSTextureLoader is recommended for fully "precooked" textures for maximum performance and image quality, but this loader can be useful for creating simple 2D texture from standard image files at runtime.

Also part of DirectXTK http://go.microsoft.com/fwlink/?LinkId=248929

NOTE: WICTextureLoader is not supported on Windows Phone 8, because WIC is not available on that platform.

The module assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling the WIC loader routines

Functions

CreateWICTextureFromMemory
Loads a WIC-supported bitmap file from a memory buffer. It creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromMemoryEx
CreateWICTextureFromFileEx
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 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.

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView);

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView);

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

Parameters

For all these functions above, the maxsize parameter provides an upper limit on the size of the resulting texture. If given a 0, the functions assume a maximum size determined from the device's current feature level. If the bitmap file contains a larger image, it will be resized using WIC at load-time to provide scaling.

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.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering. It also makes use of the immediate ID3D11DeviceContext immContext to auto-gen mipmaps if supported.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateWICTextureFromFile( d3dDevice, immContext, L"LOGO.BMP",
    nullptr, &pSRV );
if (FAILED(hr))
   // error

Release Notes

  • On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, 16bpp pixel formats will be converted to a RGBA 32-bit format.
  • WICTextureLoader cannot load .TGA files unless the system has a 3rd party WIC codec installed. You must use the DirectXTex library for TGA file format support without relying on an add-on WIC codec.
  • While there is no explicit 'sRGB' pixel format defined for WIC, the load function will check for known metadata tags and may return DXGI_FORMAT_*_SRGB formats if there are equivalents of the same size and channel configuration available.

Implementation Details

  • The conversion tables are designed so that they prefer to convert to RGB if a conversion is required as a general preferance for DXGI 1.0 supporting formats supported by WDDM 1.0 drivers. The majority of Direct3D 11 devices actually support BGR DXGI 1.1 formats so we use them when they are the best match. For example, GUID_WICPixelFormat32bppBGRA loads directly as DXGI_FORMAT_B8G8R8A8_UNORM, but GUID_WICPixelFormat32bppPBGRA converts to DXGI_FORMAT_R8G8B8A8_UNORM.
  • GUID_WICPixelFormatBlackWhite is always converted to a greyscale DXGI_FORMAT_R8_UNORM since DXGI_FORMAT_R1_UNORM is not supported by Direct3D 10.x/11.x.
  • GUID_WICPixelFormat32bppRGBE is an 8:8:8:8 format, which does not match DXGI_FORMAT_R9G9B9E5_SHAREDEXP. This WIC pixel format is therefore converted to GUID_WICPixelFormat128bppRGBAFloat and returns as DXGI_FORMAT_R32G32B32A32_FLOAT.

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.
  • If WIC2 is supported, then it will load the new WIC pixel format GUID_WICPixelFormat96bppRGBFloat directly as DXGI_FORMAT_R32G32B32_FLOAT. Otherwise the module converts this to DXGI_FORMAT_R32G32B32A32_FLOAT.
  • If WIC2 is supported, then it will include conversions cases for the new WIC pixel formats GUID_WICPixelFormat32bppRGB, GUID_WICPixelFormat64bppRGB, and GUID_WICPixelFormat64bppPRGBAHalf.
  • If WIC2 is supported, then it will convert the WIC pixel format GUID_WICPixelFormat96bppRGBFixedPoint to DXGI_FORMAT_R32G32B32_FLOAT. There is special-case handling so that if auto-gen mips fails for this format (this is optional support for Feature Level 10.0 or later devices), it will use DXGI_FORMAT_R32G32B32A32_FLOAT instead (which has required support for Feature Level 10.0 or later devices).
http://support.microsoft.com/kb/2670838

Windows 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 WICTextureLoader 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 = CreateWICTextureFromFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: WICTextureLoader

$
0
0
A Direct3D 11 2D texture loader that uses WIC to load a bitmap (BMP, JPEG, PNG, TIFF, GIF, HD Photo, or other WIC supported file container), resize if needed based on the current feature level (or by explicit parameter), format convert to a standard DXGI format if required, and then create a 2D texture. Furthermore, if a Direct3D 11 device context is provided and the current device supports it for the given pixel format, it will auto-generate mipmaps.

This loader does not support array textures, 1D textures, 3D volume textures, or cubemaps. For these scenarios, use the .DDS file format and DDSTextureLoader instead.

DDSTextureLoader is recommended for fully "precooked" textures for maximum performance and image quality, but this loader can be useful for creating simple 2D texture from standard image files at runtime.

Also part of DirectXTK http://go.microsoft.com/fwlink/?LinkId=248929

NOTE: WICTextureLoader is not supported on Windows Phone 8, because WIC is not available on that platform.

The module assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling the WIC loader routines

Functions

CreateWICTextureFromMemory
Loads a WIC-supported bitmap file from a memory buffer. It creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_z_ constwchar_t* szFileName,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView,
    _In_ size_t maxsize = 0 );

CreateWICTextureFromMemoryEx
CreateWICTextureFromFileEx
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 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.

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
    _In_opt_ ID3D11DeviceContext* d3dContext,
    _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
    _In_ size_t maxsize,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _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,
    _Out_opt_ ID3D11Resource** texture, _Out_opt_ ID3D11ShaderResourceView** textureView );

Parameters

For all these functions above, the maxsize parameter provides an upper limit on the size of the resulting texture. If given a 0, the functions assume a maximum size determined from the device's current feature level. If the bitmap file contains a larger image, it will be resized using WIC at load-time to provide scaling.

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.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering. It also makes use of the immediate ID3D11DeviceContext immContext to auto-gen mipmaps if supported.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateWICTextureFromFile( d3dDevice, immContext, L"LOGO.BMP",
    nullptr, &pSRV );
if (FAILED(hr))
   // error

Release Notes

  • On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, 16bpp pixel formats will be converted to a RGBA 32-bit format.
  • WICTextureLoader cannot load .TGA files unless the system has a 3rd party WIC codec installed. You must use the DirectXTex library for TGA file format support without relying on an add-on WIC codec.
  • While there is no explicit 'sRGB' pixel format defined for WIC, the load function will check for known metadata tags and may return DXGI_FORMAT_*_SRGB formats if there are equivalents of the same size and channel configuration available.

Implementation Details

  • The conversion tables are designed so that they prefer to convert to RGB if a conversion is required as a general preferance for DXGI 1.0 supporting formats supported by WDDM 1.0 drivers. The majority of Direct3D 11 devices actually support BGR DXGI 1.1 formats so we use them when they are the best match. For example, GUID_WICPixelFormat32bppBGRA loads directly as DXGI_FORMAT_B8G8R8A8_UNORM, but GUID_WICPixelFormat32bppPBGRA converts to DXGI_FORMAT_R8G8B8A8_UNORM.
  • GUID_WICPixelFormatBlackWhite is always converted to a greyscale DXGI_FORMAT_R8_UNORM since DXGI_FORMAT_R1_UNORM is not supported by Direct3D 10.x/11.x.
  • GUID_WICPixelFormat32bppRGBE is an 8:8:8:8 format, which does not match DXGI_FORMAT_R9G9B9E5_SHAREDEXP. This WIC pixel format is therefore converted to GUID_WICPixelFormat128bppRGBAFloat and returns as DXGI_FORMAT_R32G32B32A32_FLOAT.

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.
  • If WIC2 is supported, then it will load the new WIC pixel format GUID_WICPixelFormat96bppRGBFloat directly as DXGI_FORMAT_R32G32B32_FLOAT. Otherwise the module converts this to DXGI_FORMAT_R32G32B32A32_FLOAT.
  • If WIC2 is supported, then it will include conversions cases for the new WIC pixel formats GUID_WICPixelFormat32bppRGB, GUID_WICPixelFormat64bppRGB, and GUID_WICPixelFormat64bppPRGBAHalf.
  • If WIC2 is supported, then it will convert the WIC pixel format GUID_WICPixelFormat96bppRGBFixedPoint to DXGI_FORMAT_R32G32B32_FLOAT. There is special-case handling so that if auto-gen mips fails for this format (this is optional support for Feature Level 10.0 or later devices), it will use DXGI_FORMAT_R32G32B32A32_FLOAT instead (which has required support for Feature Level 10.0 or later devices).
http://support.microsoft.com/kb/2670838

Windows 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 WICTextureLoader 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 = CreateWICTextureFromFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Updated Wiki: ScreenGrab

$
0
0
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 full 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 DirectXTK http://go.microsoft.com/fwlink/?LinkId=248929

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, because WIC is not available on that platform.

Examples

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

ID3D11Texture2D* backBuffer = nullptr;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( *backBuffer ), ( LPVOID* )&backBuffer );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext, backBuffer,
                GUID_ContainerFormatJpeg, L"SCREENSHOT.JPG" );
    backBuffer->Release();
}
if ( FAILED(hr) )
    // error

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

ID3D11Texture2D* backBuffer = nullptr;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( *backBuffer ), ( LPVOID* )&backBuffer );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext, backBuffer,
                GUID_ContainerFormatBmp, L"SCREENSHOT.BMP",
                &GUID_WICPixelFormat16bppBGR565 );
    backBuffer->Release();
}
if ( FAILED(hr) )
    // error

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

ID3D11Texture2D* backBuffer = nullptr;
HRESULT hr = swapChain->GetBuffer( 0, __uuidof( *backBuffer ), ( LPVOID* )&backBuffer );
if ( SUCCEEDED(hr) )
{
    hr = SaveWICTextureToFile( immContext, backBuffer,
                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 ); 
                });
    backBuffer->Release();
}
if ( FAILED(hr) )
    // error

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 (128bpp or 96bpp) data, 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, then use the app's temporary folder:

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

http://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx

Updated Wiki: Documentation

$
0
0
DirectXTex library

Porting from D3DX

Texconv utility

Texassemble utility

DDSView sample

Supporting code: DDSTextureLoader, WICTextureLoader, ScreenGrab

Version History

Resources

Note There is another version of the DirectXTex library and the Texconv utility as an official Microsoft Windows SDK Sample http://code.msdn.microsoft.com/windowsdesktop/DirectX-11-Texture-fecd4824. This version uses DirectXMath, DXGI 1.2 headers, and SAL2 annotations. It is functionality similiar to the June 2013 release.

Updated Wiki: CreateTexture

$
0
0
Creates a Direct3D 11 resource from a set of images.

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

HRESULT CreateTexture( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _Outptr_ ID3D11Resource** ppResource );

HRESULT CreateTextureEx( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Outptr_ ID3D11Resource** ppResource );

Parameters

  • usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
  • bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
  • cpuAccessFlags: The non-Ex version of this function assumes this is 0.
  • miscFlags: The non-Ex version of this function assumes this is 0.
  • forceSRGB: This is 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.

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D

Updated Wiki: CaptureTexture

$
0
0
Captures a Direct3D 11 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 instead of DirectXTex.

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

Updated Wiki: CreateTexture

$
0
0
Creates a Direct3D 11 resource from a set of images.

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

HRESULT CreateTexture( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _Outptr_ ID3D11Resource** ppResource );

HRESULT CreateTextureEx( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Outptr_ ID3D11Resource** ppResource );

Parameters

  • usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
  • bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
  • cpuAccessFlags: The non-Ex version of this function assumes this is 0.
  • miscFlags: The non-Ex version of this function assumes this is 0.
  • forceSRGB: This is 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.

Example

WCHAR ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );

TexMetadata metadata;
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
    hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, &metadata, image );
}
elseif ( _wcsicmp( ext, L".tga" ) == 0 )
{
    hr = LoadFromTGAFile( filename, &metadata, image );
}
else
{
    hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, &metadata, image );
}
if ( SUCCEEDED(hr) )
{
    ID3D11Resource* pResource = nullptr;
    hr = CreateTexture( device), image.GetImages(), image.GetImageCount(),
        metadata, &pResource );

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D

Updated Wiki: CreateTexture

$
0
0
Creates a Direct3D 11 resource from a set of images.

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

HRESULT CreateTexture( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _Outptr_ ID3D11Resource** ppResource );

HRESULT CreateTextureEx( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Outptr_ ID3D11Resource** ppResource );

Parameters

  • usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
  • bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
  • cpuAccessFlags: The non-Ex version of this function assumes this is 0.
  • miscFlags: The non-Ex version of this function assumes this is 0.
  • forceSRGB: This is 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.

Example

WCHAR ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );

TexMetadata metadata;
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
    hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, &metadata, image );
}
elseif ( _wcsicmp( ext, L".tga" ) == 0 )
{
    hr = LoadFromTGAFile( filename, &metadata, image );
}
else
{
    hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, &metadata, image );
}
if ( SUCCEEDED(hr) )
{
    ID3D11Resource* pResource = nullptr;
    hr = CreateTexture( device,
        image.GetImages(), image.GetImageCount(),
        metadata, &pResource );

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D

Updated Wiki: CreateShaderResourceView

$
0
0
Creates a Direct3D 11 resource and shader resource view from a set of images.

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

HRESULT CreateShaderResourceView( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _Outptr_ ID3D11ShaderResourceView** ppSRV );

HRESULT CreateShaderResourceViewEx( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Outptr_ ID3D11ShaderResourceView** ppSRV );

Parameters

  • usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
  • bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
  • cpuAccessFlags: The non-Ex version of this function assumes this is 0.
  • miscFlags: The non-Ex version of this function assumes this is 0.
  • forceSRGB: This is 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.

Example

WCHAR ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );

TexMetadata metadata;
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
    hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, &metadata, image );
}
elseif ( _wcsicmp( ext, L".tga" ) == 0 )
{
    hr = LoadFromTGAFile( filename, &metadata, image );
}
else
{
    hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, &metadata, image );
}
if ( SUCCEEDED(hr) )
{
    ID3D11ShaderResourceView* * pSRV = nullptr;
    hr = CreateShaderResourceView( device,
        image.GetImages(), image.GetImageCount(),
        metadata, &&pSRV );

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D

Updated Wiki: CreateShaderResourceView

$
0
0
Creates a Direct3D 11 resource and shader resource view from a set of images.

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

HRESULT CreateShaderResourceView( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _Outptr_ ID3D11ShaderResourceView** ppSRV );

HRESULT CreateShaderResourceViewEx( _In_ ID3D11Device* pDevice,
    _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ D3D11_USAGE usage, _In_ unsignedint bindFlags,
    _In_ unsignedint cpuAccessFlags, _In_ unsignedint miscFlags,
    _In_ bool forceSRGB,
    _Outptr_ ID3D11ShaderResourceView** ppSRV );

Parameters

  • usage: The non-Ex version of this function assumes this is D3D11_USAGE_DEFAULT.
  • bindFlags: The non-Ex version of this function assumes this is D3D11_BIND_SHADER_RESOURCE.
  • cpuAccessFlags: The non-Ex version of this function assumes this is 0.
  • miscFlags: The non-Ex version of this function assumes this is 0.
  • forceSRGB: This is 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.

Example

WCHAR ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );

TexMetadata metadata;
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
    hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, &metadata, image );
}
elseif ( _wcsicmp( ext, L".tga" ) == 0 )
{
    hr = LoadFromTGAFile( filename, &metadata, image );
}
else
{
    hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, &metadata, image );
}
if ( SUCCEEDED(hr) )
{
    ID3D11ShaderResourceView* * pSRV = nullptr;
    hr = CreateShaderResourceView( device,
        image.GetImages(), image.GetImageCount(),
        metadata, &pSRV );

Remark

This function does not provide support for auto-gen mipmaps (the runtime/engine loaders can support this) because the assumption is if you need mipmaps with DirectTex you will call GenerateMipMaps or GenerateMipMaps3D

Updated Wiki: DDS I/O Functions

$
0
0
These functions perform file I/O for .DDS files. These functions support many legacy Direct3D 9 .DDS files and all Direct3D 10.x/11.x era "DX10" extension .DDS files

GetMetadataFromDDSMemory
GetMetadataFromDDSFile
Returns the TexMetadata from a .DDS file.

HRESULT GetMetadataFromDDSMemory( _In_reads_bytes_(size) LPCVOID pSource,
    _In_ size_t size, _In_ DWORD flags,
    _Out_ TexMetadata& metadata );

HRESULT GetMetadataFromDDSFile( _In_z_ LPCWSTR szFile,
    _In_ DWORD flags, _Out_ TexMetadata& metadata );

LoadFromDDSMemory
LoadFromDDSFile
Loads a .DDS file.

HRESULT LoadFromDDSMemory( _In_reads_bytes_(size) LPCVOID pSource,
    _In_ size_t size, _In_ DWORD flags,
    _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image );

HRESULT LoadFromDDSFile( _In_z_ LPCWSTR szFile,
    _In_ DWORD flags,
    _Out_opt_ TexMetadata* metadata, _Out_ ScratchImage& image );

SaveToDDSMemory
SaveToDDSFile
Saves a single image or a set of images to a .DDS file.

HRESULT SaveToDDSMemory( _In_ const Image& image, _In_ DWORD flags,
    _Out_ Blob& blob );

HRESULT SaveToDDSMemory( _In_reads_(nimages) const Image* images,
    _In_ size_t nimages, _In_ const TexMetadata& metadata, _In_ DWORD flags,
    _Out_ Blob& blob );

Examples

This is a simple loading example. A DDS file can potentially include any kind of Direct3D resource in any DXGI format, so the TexMetadata info is needed to understand the full content of the file.

TexMetadata info;
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS", DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
    // error

When saving a DDS file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.).
Therefore, the writer needs the TexMetadata info to know how to interpret the image set.

const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
     DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
    // error

You can also save data directly from memory without using the intermediate ScratchImage at all. This example assumes a single 2D image is being written out.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
    // error

Related Flags

  • DDS_FLAGS_NONE is the default
  • DDS_FLAGS_LEGACY_DWORD is used for loading some legacy Direct3D 8 era 24bpp .DDS files that use the non-standard DWORD alignment instead of BYTE. There's no realiable way to determine this from the file, so this requires trial-and-error.
  • DDS_FLAGS_NO_LEGACY_EXPANSION - By default the loader will expand many legacy Direct3D 9 .DDS files to supported formats. The use of this flag prevents expansions that increase the size of the pixels, and will return a failure instead.
  • DDS_FLAGS_NO_R10B10G10A2_FIXUP - By default, the loader uses a work-around for a long-standing issue with the D3DX DDS file format which reverses the RGB bit-masks for 10:10:10:2 formats. If this flag is used, then the loader instead assumes such data was written 'correctly'.
  • DDS_FLAGS_FORCE_RGB - By default we map many BGR formats directly to DXGI 1.1 formats. Use of this flag forces the use of DXGI 1.0 RGB formats instead for improved Direct3D 10.0/Windows Vista RTM/WDDM 1.0 driver support.
  • DDS_FLAGS_NO_16BPP - By default, 5:6:5, 5:5:5:1, and 4:4:4:4 formats are returned as DXGI 1.2 formats. If this flag is used, the loader will expand these to R8G8B8A8 instead.
  • DDS_FLAGS_EXPAND_LUMINANCE - By default, legacy luminance formats are mapped to the same size formats in DXGI (L8 -> R8_UNORM, L16 -> R16_UNORM, A8L8 -> R8G8_UNORM), but this requires some shader swizzling to replicate the original luminance greyscale behavior (.rrr or .rrrg)--this matches the implementation of DDSTextureLoader. Specifying this flag will instead expand these formats on load and replicate the colors to achieve the proper greyscale without any shader changes, but they will be significantly larger (8:8:8:8 or 16:16:16:16).
  • DDS_FLAGS_FORCE_DX10_EXT - When saving DDS files, the writer tries to use legacy Direct3D 9 .DDS file formats if possible rather than the 'DX10' header extension for better compatiblity with older tools. Using this flag, the writer will always generate 'DX10' extension header files which are much faster to parse at load-time. These files are compatible with the legacy D3DX10 or D3DX11 library.
  • DDS_FLAGS_FORCE_DX10_EXT_MISC2 - When saving DDS files, always use the 'DX10' header extension and write miscFlags2 data as needed, if even if the resulting file is not compatible with the legacy D3DX10 or D3DX11 libraries.

Remarks

Many older Direct3D 9 formats that do not directly map to DXGI formats are converted at load-time. For example, D3DFMT_R8G8B8 is always converted to DXGI_FORMAT_R8G8B8A8_UNORM since there is no 24bpp DXGI format.

The 'DX10' header is not supported by D3DX9, older Direct3D 9 era texture tools, or the legacy DirectX SDK DXTex.exe tool. Therefore, the default behavior is to prefer to use 'legacy' pixel formats when possible.

Note that for Direct3D 11.1 video formats, only DXGI_FORMAT_YUY2 is supported by Direct3D 9. Legacy DDS files containing FourCC "UYVY" are converted to YUY2 at load-time.

Windows Store apps

Load

If you wish to load 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 LoadFromDDSFile 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 = LoadFromDDSFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx

Save

For SaveToDDSFile 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, then use the app's temporary folder:

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

http://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx
Viewing all 1174 articles
Browse latest View live


<script src="https://jsc.adskeeper.com/r/s/rssing.com.1596347.js" async> </script>