1# The .astc File Format
2
3The default file format for compressed textures generated by `astcenc`, as well
4as from many other ASTC compressors, is the `.astc` format. This is a very
5simple format consisting of a small header followed immediately by the binary
6payload for a single image surface.
7
8Header
9======
10
11The header is a fixed 16 byte structure, defined as storing only bytes to avoid
12any endianness issues or incur any padding overhead.
13
14```
15struct astc_header
16{
17    uint8_t magic[4];
18    uint8_t block_x;
19    uint8_t block_y;
20    uint8_t block_z;
21    uint8_t dim_x[3];
22    uint8_t dim_y[3];
23    uint8_t dim_z[3];
24};
25```
26
27Magic number
28------------
29
30The 4 byte magic number at the start of the file acts as a format identifier.
31
32```
33    magic[0] = 0x13;
34    magic[1] = 0xAB;
35    magic[2] = 0xA1;
36    magic[3] = 0x5C;
37```
38
39Block size
40----------
41
42The `block_*` fields store the ASTC block dimensions in texels. For 2D images
43the Z dimension must be set to 1.
44
45Image dimensions
46----------------
47
48The `dim_*` fields store the image dimensions in texels.  For 2D images the
49Z dimension must be set to 1.
50
51Note that the image is not required to be an exact multiple of the compressed
52block size; the compressed data may include padding that is discarded during
53decompression.
54
55Each dimension is a 24 bit unsigned value that is reconstructed from the stored
56byte values as:
57
58```
59decoded_dim = dim[0] + (dim[1] << 8) + (dim[2] << 16);
60```
61
62Binary payload
63==============
64
65The binary payload is a byte stream that immediately follows the header. It
66contains 16 bytes per compressed block. The number of compressed blocks is
67determined from the header information.
68
69- - -
70
71_Copyright © 2020-2022, Arm Limited and contributors. All rights reserved._
72