1# About 2 3The Arm® Adaptive Scalable Texture Compression (ASTC) Encoder, `astcenc`, is 4a command-line tool for compressing and decompressing images using the ASTC 5texture compression standard. 6 7## The ASTC format 8 9The ASTC compressed data format, developed by Arm® and AMD, has been adopted as 10an official extension to the OpenGL®, OpenGL ES, and Vulkan® graphics APIs. It 11provides a major step forward in terms of both the image quality at a given 12bitrate, and the format and bitrate flexibility available to content creators. 13This allows more assets to use compression, often at a reduced bitrate compared 14to other formats, reducing memory storage and bandwidth requirements. 15 16Read the [ASTC Format Overview][1] for a quick introduction to the format, or 17read the full [Khronos Data Format Specification][2] for all the details. 18 19## License 20 21This project is licensed under the Apache 2.0 license. By downloading any 22component from this repository you acknowledge that you accept terms specified 23in the [LICENSE.txt](LICENSE.txt) file. 24 25# Encoder feature support 26 27The encoder supports compression of low dynamic range (BMP, JPEG, PNG, TGA) and 28high dynamic range (EXR, HDR) images, as well as a subset of image data wrapped 29in the DDS and KTX container formats, into ASTC or KTX format output images. 30 31The decoder supports decompression of ASTC or KTX format input images into low 32dynamic range (BMP, PNG, TGA), high dynamic range (EXR, HDR), or DDS and KTX 33wrapped output images. 34 35The encoder allows control over the compression time/quality tradeoff with 36`exhaustive`, `verythorough`, `thorough`, `medium`, `fast`, and `fastest` 37encoding quality presets. 38 39The encoder allows compression time and quality analysis by reporting the 40compression time, and the Peak Signal-to-Noise Ratio (PSNR) between the input 41image and the compressed output. 42 43## ASTC format support 44 45The `astcenc` compressor supports generation of images for all three profiles 46allowed by the ASTC specification: 47 48* 2D Low Dynamic Range (LDR profile) 49* 2D LDR and High Dynamic Range (HDR profile) 50* 2D and 3D, LDR and HDR (Full profile) 51 52It also supports all of the ASTC block sizes and compression modes, allowing 53content creators to use the full spectrum of quality-to-bitrate options ranging 54from 0.89 bits/pixel up to 8 bits/pixel. 55 56# Prebuilt binaries 57 58Release build binaries for the `astcenc` stable releases are provided in the 59[GitHub Releases page][3]. 60 61* Change log: [4.x series](./Docs/ChangeLog-4x.md) 62* Change log: [3.x series](./Docs/ChangeLog-3x.md) 63 64Binaries are provided for 64-bit builds on Windows, macOS, and Linux. 65 66## Windows and Linux 67 68For Windows and Linux the builds of the astcenc are provided as multiple 69binaries, each tuned for a specific SIMD instruction set. 70 71For x86-64 we provide, in order of increasing performance: 72 73* `astcenc-sse2` - uses SSE2 74* `astcenc-sse4.1` - uses SSE4.1 and POPCNT 75* `astcenc-avx2` - uses AVX2, SSE4.2, POPCNT, and F16C 76 77The x86-64 SSE2 builds will work on all x86-64 machines, but it is the slowest 78of the three. The other two require extended CPU instruction set support which 79is not universally available, but each step gains ~15% more performance. 80 81For Arm, if binaries are available, we provide: 82 83* `astcenc-neon` - uses NEON 84 85## macOS 86 87For macOS devices we provide a single universal binary `astcenc`, which allows 88the OS to automatically use the correct binary variant for the current host 89machine. Support is provided for three architecture slices: 90 91* `x86_64` - uses the `astcenc-sse4.1` build defined above. 92* `x86_64h` - uses the `astcenc-avx2` build defined above. 93* `arm64` - uses the `astcenc-neon` build defined above. 94 95## Repository branches 96 97The `main` branch is an active development branch for the compressor. It aims 98to be a stable branch for the latest major release series, but as it is used 99for ongoing development expect it to have some volatility. We recommend using 100the latest stable release tag for production development. 101 102The `3.x` branch is a stable branch for the 3.x release series. It is no longer 103under active development, but is a supported branch that continues to get 104backported bug fixes. 105 106The `1.x` and `2.x` branches are stable branches for older releases. They are 107no longer under active development or getting bug fixes. 108 109Any other branches you might find are development branches for new features or 110optimizations, so might be interesting to play with but should be considered 111transient and unstable. 112 113 114# Getting started 115 116Open a terminal, change to the appropriate directory for your system, and run 117the astcenc encoder program, like this on Linux or macOS: 118 119 ./astcenc 120 121... or like this on Windows: 122 123 astcenc 124 125Invoking `astcenc -help` gives an extensive help message, including usage 126instructions and details of all available command line options. A summary of 127the main encoder options are shown below. 128 129## Compressing an image 130 131Compress an image using the `-cl` \ `-cs` \ `-ch` \ `-cH` modes. For example: 132 133 astcenc -cl example.png example.astc 6x6 -medium 134 135This compresses `example.png` using the LDR color profile and a 6x6 block 136footprint (3.56 bits/pixel). The `-medium` quality preset gives a reasonable 137image quality for a relatively fast compression speed, so is a good starting 138point for compression. The output is stored to a linear color space compressed 139image, `example.astc`. 140 141The modes available are: 142 143* `-cl` : use the linear LDR color profile. 144* `-cs` : use the sRGB LDR color profile. 145* `-ch` : use the HDR color profile, tuned for HDR RGB and LDR A. 146* `-cH` : use the HDR color profile, tuned for HDR RGBA. 147 148If you intend to use the resulting image with the decode mode extensions to 149limit the decompressed precision to UNORM8, it is recommended that you also 150specify the `-decode_unorm8` flag. This will ensure that the compressor uses 151the correct rounding rules when choosing encodings. 152 153## Decompressing an image 154 155Decompress an image using the `-dl` \ `-ds` \ `-dh` \ `-dH` modes. For example: 156 157 astcenc -dh example.astc example.tga 158 159This decompresses `example.astc` using the full HDR feature profile, storing 160the decompressed output to `example.tga`. 161 162The modes available mirror the options used for compression, but use a `d` 163prefix. Note that for decompression there is no difference between the two HDR 164modes, they are both provided simply to maintain symmetry across operations. 165 166## Measuring image quality 167 168Review the compression quality using the `-tl` \ `-ts` \ `-th` \ `-tH` modes. 169For example: 170 171 astcenc -tl example.png example.tga 5x5 -thorough 172 173This is equivalent to using using the LDR color profile and a 5x5 block size 174to compress the image, using the `-thorough` quality preset, and then 175immediately decompressing the image and saving the result. This can be used 176to enable a visual inspection of the compressed image quality. In addition 177this mode also prints out some image quality metrics to the console. 178 179The modes available mirror the options used for compression, but use a `t` 180prefix. 181 182## Experimenting 183 184Efficient real-time graphics benefits from minimizing compressed texture size, 185as it reduces memory footprint, reduces memory bandwidth, saves energy, and can 186improve texture cache efficiency. However, like any lossy compression format 187there will come a point where the compressed image quality is unacceptable 188because there are simply not enough bits to represent the output with the 189precision needed. We recommend experimenting with the block footprint to find 190the optimum balance between size and quality, as the finely adjustable 191compression ratio is one of major strengths of the ASTC format. 192 193The compression speed can be controlled from `-fastest`, through `-fast`, 194`-medium` and `-thorough`, up to `-exhaustive`. In general, the more time the 195encoder has to spend looking for good encodings the better the results, but it 196does result in increasingly small improvements for the amount of time required. 197 198There are many other command line options for tuning the encoder parameters 199which can be used to fine tune the compression algorithm. See the command line 200help message for more details. 201 202# Documentation 203 204The [ASTC Format Overview](./Docs/FormatOverview.md) page provides a high level 205introduction to the ASTC texture format, how it encodes data, and why it is 206both flexible and efficient. 207 208The [Effective ASTC Encoding](./Docs/Encoding.md) page looks at some of the 209guidelines that should be followed when compressing data using `astcenc`. 210It covers: 211 212* How to efficiently encode data with fewer than 4 channels. 213* How to efficiently encode normal maps, sRGB data, and HDR data. 214* Coding equivalents to other compression formats. 215 216The [ASTC Developer Guide][5] document (external link) provides a more detailed 217guide for developers using the `astcenc` compressor. 218 219The [.astc File Format](./Docs/FileFormat.md) page provides a light-weight 220specification for the `.astc` file format and how to read or write it. 221 222The [Building ASTC Encoder](./Docs/Building.md) page provides instructions on 223how to build `astcenc` from the sources in this repository. 224 225The [Testing ASTC Encoder](./Docs/Testing.md) page provides instructions on 226how to test any modifications to the source code in this repository. 227 228# Support 229 230If you have issues with the `astcenc` encoder, or questions about the ASTC 231texture format itself, please raise them in the GitHub issue tracker. 232 233If you have any questions about Arm GPUs, application development for Arm GPUs, 234or general mobile graphics development or technology please submit them on the 235[Arm Community graphics forums][4]. 236 237- - - 238 239_Copyright © 2013-2024, Arm Limited and contributors. All rights reserved._ 240 241[1]: ./Docs/FormatOverview.md 242[2]: https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html#ASTC 243[3]: https://github.com/ARM-software/astc-encoder/releases 244[4]: https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum/ 245[5]: https://developer.arm.com/documentation/102162/latest/?lang=en 246
