Programming Guide for DDS

Direct3D implements the DDS file format for storing uncompressed or compressed (DXTn) textures. The file format implements several slightly different types designed for storing different types of data, and supports single layer textures, textures with mipmaps, cube maps, volume maps and texture arrays (in Direct3D 10/11). This section describes the layout of a DDS file.

For help creating a texture in Direct3D 11, see How to: Create a Texture. For help in Direct3D 9, see Texture Support in D3DX (Direct3D 9).

• DDS File Layout
• DDS Variants
• Using Texture Arrays in Direct3D 10/11
• Common DDS File Resource Formats and Associated Header Content
• Related topics

DDS File Layout

A DDS file is a binary file that contains the following information:

• A DWORD (magic number) containing the four character code value 'DDS ' (0x20534444).

• A description of the data in the file.

  The data is described with a header description using DDS_HEADER; the pixel format is defined using DDS_PIXELFORMAT. Note that the DDS_HEADER and DDS_PIXELFORMAT structures replace the deprecated DDSURFACEDESC2, DDSCAPS2 and DDPIXELFORMAT DirectDraw 7 structures. DDS_HEADER is the binary equivalent of DDSURFACEDESC2 and DDSCAPS2. DDS_PIXELFORMAT is the binary equivalent of DDPIXELFORMAT.

  DWORD               dwMagic;
  DDS_HEADER          header;
  
  

  If the DDS_PIXELFORMAT dwFlags is set to DDPF_FOURCC and dwFourCC is set to "DX10" an additional DDS_HEADER_DXT10 structure will be present to accommodate texture arrays or DXGI formats that cannot be expressed as an RGB pixel format such as floating point formats, sRGB formats etc. When the DDS_HEADER_DXT10 structure is present the entire data description will looks like this.

  DWORD               dwMagic;
  DDS_HEADER          header;
  DDS_HEADER_DXT10    header10;
  

• A pointer to an array of bytes that contains the main surface data.

  BYTE bdata[]
  

• A pointer to an array of bytes that contains the remaining surfaces such as; mipmap levels, faces in a cube map, depths in a volume texture. Follow these links for more information about the DDS file layout for a: texture, a cube map, or a volume texture.

  BYTE bdata2[]
  

For broad hardware support, we recommend that you use the 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, or DXGI_FORMAT_BC3_UNORM_SRGB format.

For more info about compressed texture formats, see Texture Block Compression in Direct3D 11 and Block Compression (Direct3D 10).

The D3DX library (for example, D3DX11.lib) and other similar libraries unreliably or inconsistently provide the pitch value in the dwPitchOrLinearSize member of the DDS_HEADER structure. Therefore, when you read and write to DDS files, we recommend that you compute the pitch in one of the following ways for the indicated formats:

• For block-compressed formats, compute the pitch as:

  max( 1, ((width+3)/4) ) * block-size

  The block-size is 8 bytes for DXT1, BC1, and BC4 formats, and 16 bytes for other block-compressed formats.

• For R8G8_B8G8, G8R8_G8B8, legacy UYVY-packed, and legacy YUY2-packed formats, compute the pitch as:

  ((width+1) >> 1) * 4

• For other formats, compute the pitch as:

  ( width * bits-per-pixel + 7 ) / 8

  You divide by 8 for byte alignment.

DDS Variants

There are many tools that create and consume DDS files, but they can vary in the details of what they require in the header. Writers should populate the headers as fully as possible, and readers should check the minimal values for maximum compatibility. To validate a DDS file, a reader should ensure the file is at least 128 bytes long to accommodate the magic value and basic header, the magic value is 0x20534444 ("DDS "), the DDS_HEADER size is 124, and the DDS_PIXELFORMAT in the header size is 32. If the DDS_PIXELFORMAT dwFlags is set to DDPF_FOURCC and a dwFourCC is set to "DX10", then the total file size needs to be at least 148 bytes.

There are some common variants in use where the pixel format is set to a DDPF_FOURCC code where dwFourCC is set to a D3DFORMAT or DXGI_FORMAT enumeration value. There is no way to tell if an enumeration value is a D3DFORMAT or a DXGI_FORMAT, so it is highly recommended that the "DX10" extension and DDS_HEADER_DXT10 header is used instead to store the dxgiFormat when the basic DDS_PIXELFORMAT cannot express the format.

The standard DDS_PIXELFORMAT should be preferred for maximum compatibility to store RGB uncompressed data and DXT1-5 data as not all DDS tools support the DX10 extension.

Using Texture Arrays in Direct3D 10/11

The new DDS structures (DDS_HEADER and DDS_HEADER_DXT10) in Direct3D 10/11 extend the DDS file format to support an array of textures, which is a new resource type in Direct3D 10/11. Here is some sample code that shows how to access the different mipmap levels in an array of textures, using the new headers.

DWORD               dwMagic;
DDS_HEADER          header;
DDS_HEADER_DXT10    header10;
   
for (int iArrayElement = 0; iArrayElement < header10.arraySize; iArrayElement++)
{
   for (int iMipLevel = 0; iMipLevel < header.dwMipMapCount; iMipLevel++)
   {
     ...
   }
}       

Common DDS File Resource Formats and Associated Header Content

* = A robust DDS reader must be able to handle these legacy format codes. However, such a DDS reader should prefer to use the "DX10" header extension when it writes these format codes to avoid ambiguity.

** = Because of some long-standing issues in common implementations of DDS readers and writers, the most robust way to write out 10:10:10:2-type data is to use the "DX10" header extension with the DXGI_FORMAT code "24" (that is, the DXGI_FORMAT_R10G10B10A2_UNORM value). D3DFMT_A2R10G10B10 data should be converted to 10:10:10:2-type data before being written out as a DXGI_FORMAT_R10G10B10A2_UNORM format DDS file.

Related topics

DDS