Format:DDS (DirectDraw Surface)
| Magic | 44 44 53 20 ("DDS ") |
|---|---|
| Extensions | .dds |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Microsoft's DirectDraw Surface texture container (.dds): the magic 'DDS ' (0x20534444), a 124-byte DDS_HEADER, an optional 20-byte DDS_HEADER_DXT10, then the pixel data; block-compressed formats are named by FourCC (DXT1-5, ATI1/ATI2, BC4U/BC5U) or by a DXGI_FORMAT in the DX10 extension.
Identification
A DDS file starts with the four bytes 44 44 53 20 ("DDS ", DDS_MAGIC = 0x20534444 read as a little-endian uint32), followed by a 124-byte DDS_HEADER, so the pixel data of a legacy file begins at offset 128. DDS_HEADER.size must be 124 and DDS_PIXELFORMAT.size 32; DirectXTex rejects other values unless its permissive flag is set, in which case it also accepts 24 as a "known variant" (and 0 for the pixel format size). All fields are little-endian uint32.
Layout
| Offset | Part |
|---|---|
| 0x00 | magic "DDS " |
| 0x04 | DDS_HEADER, 124 bytes: size, flags, height, width, pitchOrLinearSize, depth, mipMapCount, 11 reserved words, DDS_PIXELFORMAT (32 bytes), caps, caps2, caps3, caps4, reserved |
| 0x80 | DDS_HEADER_DXT10, 20 bytes, only when the pixel format is the FourCC "DX10" |
| 0x80 or 0x94 | image data |
Header flags and caps
DirectXTex writes flags as DDSD_CAPS|HEIGHT|WIDTH|PIXELFORMAT (0x1007) for a texture, adds 0x20000 (DDSD_MIPMAPCOUNT) when mipmaps exist, 0x800000 (DDSD_DEPTH) for a volume texture, and 0x8 (DDSD_PITCH) or 0x80000 (DDSD_LINEARSIZE) to say whether pitchOrLinearSize is a row pitch or the size of the top level. caps carries DDSCAPS_TEXTURE 0x1000 and, for mipmapped or cube files, DDSCAPS_COMPLEX 0x8 and DDSCAPS_MIPMAP 0x400000. For a legacy cubemap caps2 has DDSCAPS2_CUBEMAP 0x200 plus one bit per face (+X 0x400, -X 0x800, +Y 0x1000, -Y 0x2000, +Z 0x4000, -Z 0x8000) and DirectXTex requires all six faces; a legacy volume sets DDSCAPS2_VOLUME 0x200000.
Pixel format and block-compressed codes
DDS_PIXELFORMAT.flags 0x4 (DDPF_FOURCC) means fourCC names the format. The FourCCs DirectXTex maps to DXGI block formats (see Technique:Block-compressed texture formats):
- "DXT1" = BC1; "DXT3" and "DXT2" (premultiplied alpha) = BC2; "DXT5" and "DXT4" (premultiplied alpha) = BC3.
- "BC4U"/"BC4S" and "ATI1" = BC4; "BC5U"/"BC5S", "ATI2" and "A2XY" = BC5.
- "BC6H" = BC6H_UF16; "BC7L" and "BC7\0" = BC7_UNORM.
- "A2D5", "xGBR", "RxBG", "RBxG", "xRBG", "RGxB", "xGxR", "GXRB", "GRXB", "RXGB", "BRGX" are DXT5 variants with swizzled channels, returned unchanged as BC3.
- "DX10" announces the 20-byte DDS_HEADER_DXT10: dxgiFormat, resourceDimension (2, 3, 4 = 1D, 2D, 3D), miscFlag (0x4 = cube), arraySize, miscFlags2 (low 3 bits = alpha mode 0-4). A DX10 file must have header size 124 and pixel-format size 32; for a cube array, arraySize counts cubes, not faces.
Uncompressed legacy formats are described by flags (DDPF_RGB 0x40, DDPF_ALPHAPIXELS 0x1, DDPF_LUMINANCE 0x20000, DDPF_ALPHA 0x2, DDPF_PALETTEINDEXED8 0x20, bump formats) with RGBBitCount and four channel masks, for example A8R8G8B8 = 32 bits, masks 00FF0000 0000FF00 000000FF FF000000.
Code & repositories
- https://github.com/microsoft/DirectXTex @
4234f77df9c6c8bb2880607b82d5d597b54d1fa9· license: MIT
Reference DDS reader/writer (DDS.h, DirectXTexDDS.cpp) and BC1-BC7 codecs; MIT
Tested on: source read, not run: source read, no build · checked 2026-10-19; last activity 2026-10-16; Note: the latest release ships binaries; the wiki links only the source, never the binaries
Pitfalls
- Mipmap count 0 is treated as 1; a DX10 arraySize of 0 as 1.
- A legacy file cannot express a 1D texture; DX10 1D files are expected to have height 1.
- Block-compressed sizes use ceil(width/4) x ceil(height/4) blocks of 8 or 16 bytes; DirectXTex has a "bad DXTn tails" mode for files written with width/4 rounded down.
- Unverified: the order of subresources in the data (all mips of one array element or face, then the next) is the usual convention; the sources were not read for it.
Sources
DirectXTex DirectXTex/DDS.h and DirectXTexDDS.cpp (MIT).