Decompress

DirectXTex

Decompresses a block-compressed (BC) image or set of BC images.

HRESULT Decompress( const Image& cImage, DXGI_FORMAT format,
    ScratchImage& image );

HRESULT Decompress( const Image* cImages, size_t nimages,
    const TexMetadata& metadata,
    DXGI_FORMAT format, ScratchImage& images );

Parameters

cimage: Must be a BC compressed image or this function will fail.

format: Format to decompress to. If set to DXGI_FORMAT_UNKNOWN the routine picks a reasonable default based on the input BC format.

Source format	Uncompressed format
BC1/DXT1	DXGI_FORMAT_R8G8B8A8_UNORM
BC2/DXT3
BC3/DXT5
BC7
BC1_SRGB	DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
BC2_SRGB/DXT2
BC3_SRGB/DXT4
BC7_SRGB
BC4_UNORM	DXGI_FORMAT_R8_UNORM
BC4_SNORM	DXGI_FORMAT_R8_SNORM
BC5_UNORM	DXGI_FORMAT_R8G8_UNORM
BC5_SNORM	DXGI_FORMAT_R8G8_SNORM
BC6H	DXGI_FORMAT_R32G32B32A32_FLOAT

Example

ScratchImage bcImage;

...

ScratchImage destImage;
hr = Decompress( bcImage.GetImages(), bcImage.GetImageCount(),
    bcImage.GetMetadata(),
    DXGI_FORMAT_UNKNOWN, destImage );
if ( FAILED(hr) )
    ...

Remark

The DirectXTex library functions allow arbitrary sized images to handle non-power-of-2 mipmapped BC textures. Note that Direct3D will not allow a resource to be created using BC format with the top-level size set to something other than a multiple of 4 in width and height, even though it does allow the mipchain below it to not meet that requirement. In other words, the library allows some textures to be decompressed that are not actually valid on Direct3D.

Note that on DirectX 12, there is an optional feature of the DirectX Agility SDK 1.4 / Windows 11 or later that does support the top-level of a BC texture not being a multiple of 4. See D3D12_FEATURE_DATA_D3D12_OPTIONS8.UnalignedBlockTexturesSupported.

See Compress