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