| Microsoft DirectX 8.1 (C++) |
The Microsoft® DirectDraw® Surface (DDS) file format is used to store textures and cubic environment maps, both with and without mipmap levels. This format can store uncompressed and compressed pixel formats, and is the preferred file format for storing DXTn compressed data. This file format is supported by the Microsoft DirectX® Texture tool (DXTex Tool), as well as some third party tools, and by the Microsoft Direct3DX library.
This format was introduced with DirectX 7.0. In DirectX 8.0, support for volume textures was added.
The basic structure of a DDS file is a header, and one or more surfaces written to a binary file. The header consists of a four-character code and a DDSURFACEDESC2 structure. This header contains all the information needed to determine the contents of the entire file. The image below shows the layout of a DDS file.
The DDSURFACEDESC2 structure describes the file contents using the standard flags and values defined in the DirectDraw documentation, but files should use a restricted set of values to ensure full compatibility. A robust reader should verify key values and a robust writer should ensure all required flags are set for the different fields and options to ensure easy loading by the application or other tool. Also, a robust reader should not use a field unless the corresponding flag is set, and a robust writer should set all undefined fields to 0.
The table below shows the members of the DDSURFACEDESC2 structure.
| Member | Description |
|---|---|
| DWORD dwSize | Size of structure. This member must be set to 124. |
| DWORD dwFlags | Flags to indicate valid fields. Always include DDSD_CAPS, DDSD_PIXELFORMAT, DDSD_WIDTH, DDSD_HEIGHT and either DDSD_PITCH or DDSD_LINEARSIZE. |
| DWORD dwHeight | Height of the main image in pixels |
| DWORD dwWidth | Width of the main image in pixels |
| DWORD dwPitchOrLinearSize | For uncompressed formats, this is the number of bytes per scan line (DWORD aligned) for the main image. dwFlags should include DDSD_PITCH in this case. For compressed formats, this is the total number of bytes for the main image. dwFlags should be include DDSD_LINEARSIZE in this case. |
| DWORD dwDepth | For volume textures, this is the depth of the volume. dwFlags should include DDSD_DEPTH in this case. |
| DWORD dwMipMapCount | For items with mipmap levels, this is the total number of levels in the mipmap chain of the main image. dwFlags should include DDSD_MIPMAPCOUNT in this case |
| DWORD dwReserved1[11] | |
| DDPIXELFORMAT ddpfPixelFormat | A 32-byte value that specifies the pixel format structure. |
| DDCAPS2 ddsCaps | A 16-byte value that specifies the capabilities structure. |
| DWORD dwReserved2 |
Note that the field names used in this description do not correspond exactly with the DDSURFACEDESC2 fields due to the restrictions placed on the DDS file format, but a standard DDSURFACEDESC2 structure can and should be used. Use the magic DDS value and the header dwSize value to validate the file.
The pixel format of the image is given in the ddpfPixelFormat field of the header, and can describe all the formats supported by Microsoft Direct3D®. DDS files are usually restricted to either RGB or FOURCC formats, and the use of other formats is not generally supported. Restrict usage to RGB formats A8R8G8B8, A1R5G5B5, A4R4G4B4, R8G8B8, R5G6B5; and FOURCC formats DXT1, DXT2, DXT3, DXT4, and DXT5 to ensure the best support. A well-written reader should handle more formats, if possible.
The following table shows the layout of the DDPIXELFORMAT structure.
| Member | Description |
|---|---|
| DWORD dwSize | Size of structure. This member must be set to 32. |
| DWORD dwFlags | Flags to indicate valid fields. Uncompressed formats will usually use DDPF_RGB to indicate an RGB format, while compressed formats will use DDPF_FOURCC with a four-character code. |
| DWORD dwFourCC | This is the four-character code for compressed formats. dwFlags should include DDPF_FOURCC in this case. For DXTn compression, this is set to "DXT1", "DXT2", "DXT3", "DXT4", or "DXT5". |
| DWORD dwRGBBitCount | For RGB formats, this is the total number of bits in the format. dwFlags should include DDPF_RGB in this case. This value is usually 16, 24, or 32. For A8R8G8B8, this value would be 32. |
| DWORD dwRBitMask DWORD dwGBitMask DWORD dwBBitMask | For RGB formats, this contains the masks for the red, green, and blue channels. For A8R8G8B8, these values would be 0x00ff0000, 0x0000ff00, and 0x000000ff respectively. |
| DWORD dwRGBAlphaBitMask | For RGB formats, this contains the mask for the alpha channel, if any. dwFlags should include DDPF_ALPHAPIXELS in this case. For A8R8G8B8, this value would be 0xff000000. |
The final details of the format are inferred from the capabilities bits set in the ddsCaps field of the header. The layout of the ddsCaps structure is shown in the table below.
| Member | Description |
|---|---|
| DWORD dwCaps1 | DDS files should always include DDSCAPS_TEXTURE. If the file contains mipmaps, DDSCAPS_MIPMAP should be set. For any DDS file with more than one main surface, such as a mipmaps, cubic environment map, or volume texture, DDSCAPS_COMPLEX should also be set. |
| DWORD dwCaps2 | For cubic environment maps, DDSCAPS2_CUBEMAP should be included as well as one or more faces of the map (DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, DDSCAPS2_CUBEMAP_NEGATIVEY, DDSCAPS2_CUBEMAP_POSITIVEZ, DDSCAPS2_CUBEMAP_NEGATIVEZ). For volume textures, DDSCAPS2_VOLUME should be included. |
| DWORD Reserved[2] |
Note that as of DirectX 8.0, cubic environment maps are always written with all faces defined.
The following topics show the layout.