1# About 2 3This is the official repository for the Arm® Adaptive Scalable Texture 4Compression (ASTC) Encoder, `astcenc`, a command-line tool for compressing 5and decompressing images using the ASTC texture 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 Open GL®, 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`, `thorough`, `medium`, `fast`, and `fastest` encoding quality 37presets. 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**Latest 4.x stable release:** TBD 62* Change log: [4.x series](./Docs/ChangeLog-4x.md) 63 64**Latest 3.x stable release:** 3.7 65* Change log: [3.x series](./Docs/ChangeLog-3x.md) 66 67**Latest 2.x stable release:** 2.5 68* Change log: [2.x series](./Docs/ChangeLog-2x.md) 69 70Binaries are provided for 64-bit builds on Windows, macOS, and Linux. The 71builds of the astcenc are provided as multiple binaries, each tuned for a 72specific SIMD instruction set. 73 74For x86-64 we provide, in order of increasing performance: 75 76* `astcenc-sse2` - uses SSE2 77* `astcenc-sse4.1` - uses SSE4.1 and POPCNT 78* `astcenc-avx2` - uses AVX2, SSE4.2, POPCNT, and F16C 79 80The x86-64 SSE2 builds will work on all x86-64 machines, but it is the slowest 81of the three. The other two require extended CPU instruction set support which 82is not universally available, but each step gains ~15% more performance. 83 84For Apple silicon macOS devices we provide: 85 86* `astcenc-neon` - uses NEON 87 88 89## Repository branches 90 91The `main` branch is an active development branch for the compressor. It aims 92to be a stable branch for the latest major release series, but as it is used 93for ongoing development expect it to have some volatility. 94 95The `2.x` and `3.x` branches are a stable branches for the 2.x and 3.x release 96series. They are no longer under active development, but are supported branches 97that will continue to get backported bug fixes. 98 99The `1.x` branch is a stable branch for the 1.x release series. It is no longer 100under active development or getting bug fixes. 101 102Any other branches you might find are development branches for new features or 103optimizations, so might be interesting to play with but should be considered 104transient and unstable. 105 106 107# Getting started 108 109Open a terminal, change to the appropriate directory for your system, and run 110the astcenc encoder program, like this on Linux or macOS: 111 112 ./astcenc 113 114... or like this on Windows: 115 116 astcenc 117 118Invoking `astcenc -help` gives an extensive help message, including usage 119instructions and details of all available command line options. A summary of 120the main encoder options are shown below. 121 122## Compressing an image 123 124Compress an image using the `-cl` \ `-cs` \ `-ch` \ `-cH` modes. For example: 125 126 astcenc -cl example.png example.astc 6x6 -medium 127 128This compresses `example.png` using the LDR color profile and a 6x6 block 129footprint (3.56 bits/pixel). The `-medium` quality preset gives a reasonable 130image quality for a relatively fast compression speed, so is a good starting 131point for compression. The output is stored to a linear color space compressed 132image, `example.astc`. 133 134The modes available are: 135 136* `-cl` : use the linear LDR color profile. 137* `-cs` : use the sRGB LDR color profile. 138* `-ch` : use the HDR color profile, tuned for HDR RGB and LDR A. 139* `-cH` : use the HDR color profile, tuned for HDR RGBA. 140 141## Decompressing an image 142 143Decompress an image using the `-dl` \ `-ds` \ `-dh` \ `-dH` modes. For example: 144 145 astcenc -dh example.astc example.tga 146 147This decompresses `example.astc` using the full HDR feature profile, storing 148the decompressed output to `example.tga`. 149 150The modes available mirror the options used for compression, but use a `d` 151prefix. Note that for decompression there is no difference between the two HDR 152modes, they are both provided simply to maintain symmetry across operations. 153 154## Measuring image quality 155 156Review the compression quality using the `-tl` \ `-ts` \ `-th` \ `-tH` modes. 157For example: 158 159 astcenc -tl example.png example.tga 5x5 -thorough 160 161This is equivalent to using using the LDR color profile and a 5x5 block size 162to compress the image, using the `-thorough` quality preset, and then 163immediately decompressing the image and saving the result. This can be used 164to enable a visual inspection of the compressed image quality. In addition 165this mode also prints out some image quality metrics to the console. 166 167The modes available mirror the options used for compression, but use a `t` 168prefix. 169 170## Experimenting 171 172Efficient real-time graphics benefits from minimizing compressed texture size, 173as it reduces memory footprint, reduces memory bandwidth, saves energy, and can 174improve texture cache efficiency. However, like any lossy compression format 175there will come a point where the compressed image quality is unacceptable 176because there are simply not enough bits to represent the output with the 177precision needed. We recommend experimenting with the block footprint to find 178the optimum balance between size and quality, as the finely adjustable 179compression ratio is one of major strengths of the ASTC format. 180 181The compression speed can be controlled from `-fastest`, through `-fast`, 182`-medium` and `-thorough`, up to `-exhaustive`. In general, the more time the 183encoder has to spend looking for good encodings the better the results, but it 184does result in increasingly small improvements for the amount of time required. 185 186There are many other command line options for tuning the encoder parameters 187which can be used to fine tune the compression algorithm. See the command line 188help message for more details. 189 190# Documentation 191 192The [ASTC Format Overview](./Docs/FormatOverview.md) page provides a high level 193introduction to the ASTC texture format, how it encodes data, and why it is 194both flexible and efficient. 195 196The [Effective ASTC Encoding](./Docs/Encoding.md) page looks at some of the 197guidelines that should be followed when compressing data using `astcenc`. 198It covers: 199 200* How to efficiently encode data with fewer than 4 channels. 201* How to efficiently encode normal maps, sRGB data, and HDR data. 202* Coding equivalents to other compression formats. 203 204The [.astc File Format](./Docs/FileFormat.md) page provides a light-weight 205specification for the `.astc` file format and how to read or write it. 206 207The [Building ASTC Encoder](./Docs/Building.md) page provides instructions on 208how to build `astcenc` from the sources in this repository. 209 210The [Testing ASTC Encoder](./Docs/Testing.md) page provides instructions on 211how to test any modifications to the source code in this repository. 212 213# Support 214 215If you have issues with the `astcenc` encoder, or questions about the ASTC 216texture format itself, please raise them in the GitHub issue tracker. 217 218If you have any questions about Arm GPUs, application development for Arm GPUs, 219or general mobile graphics development or technology please submit them on the 220[Arm Community graphics forums][4]. 221 222- - - 223 224_Copyright © 2013-2022, Arm Limited and contributors. All rights reserved._ 225 226[1]: ./Docs/FormatOverview.md 227[2]: https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html#ASTC 228[3]: https://github.com/ARM-software/astc-encoder/releases 229[4]: https://community.arm.com/support-forums/f/graphics-gaming-and-vr-forum/ 230
