NAME¶

astcenc - compress or decompress images using the ASTC format

SYNOPSIS¶

DESCRIPTION¶

astcenc compresses image files into the Adaptive Scalable Texture Compression (ASTC) image format, a lossy compression format design for use in real-time graphics applications. It is a fully featured compressor implementation, supporting all of the compression profiles and block sizes specified by the ASTC format:

• All color profiles (LDR linear, LDR sRGB, and HDR)
• All 2D block sizes (4x4 through to 12x12)
• All 3D block sizes (3x3x3 through to 6x6x6)

The compressor provides a number of pre-determined quality presets, which allow users to tradeoff compressed image quality against compression performance. For advanced users the compressor provides many additional control options.

astcenc can also be used to decompress ASTC compressed images, and perform compression image quality analysis.

COMPRESSION¶

To compress an image using the ASTC format you must specify the color profile, the input file name, the output file name, the target block size, and the quality preset.

The color profile is specified using the -cl (LDR linear), -cs (LDR sRGB), -ch (HDR RGB, LDR A), or -cH(HDR RGBA) encoder options. Note that not all hardware implementations of ASTC support the HDR profile.

The input file path must match a valid file format for compression, and the output file format must be a valid output for compression. See the FILE FORMATS section for the list of supported formats.

The block size must be a valid ASTC block size. Every block compresses into 128 bits of compressed output, so the block size determines the compressed data bitrate.

Supported 2D block sizes are:

• 4x4: 8.00 bpp
• 5x4: 6.40 bpp
• 5x5: 5.12 bpp
• 6x5: 4.27 bpp
• 6x6: 3.56 bpp
• 8x5: 3.20 bpp
• 8x6: 2.67 bpp
• 10x5: 2.56 bpp
• 10x6: 2.13 bpp
• 8x8: 2.00 bpp
• 10x8: 1.60 bpp
• 10x10: 1.28 bpp
• 12x10: 1.07 bpp
• 12x12: 0.89 bpp

Supported 3D block sizes are:

• 3x3x3: 4.74 bpp
• 4x3x3: 3.56 bpp
• 4x4x3: 2.67 bpp
• 4x4x4: 2.00 bpp
• 5x4x4: 1.60 bpp
• 5x5x4: 1.28 bpp
• 5x5x5: 1.02 bpp
• 6x5x5: 0.85 bpp
• 6x6x5: 0.71 bpp
• 6x6x6: 0.59 bpp

The quality preset configures the quality-performance tradeoff for the compressor; more complete searches of the search space improve image quality at the expense of compression time. The available presets are:

-fastest
-fast
-medium
-thorough
-exhaustive

Using the -fastest setting throws away a lot of image quality compared. It is useful for quickly roughing-out new content, but we recommend using higher quality settings for production builds.

Using the -exhaustive setting significantly increases compression time, but typically only gives minor quality improvements over using -thorough.

There are a number of additional compressor options which are useful to consider for common usage, based on the type of image data being compressed.

-mask

The input texture is a mask texture with unrelated data stored in the various color channels, so enable error heuristics that aim to improve perceptual quality by minimizing the effect of error cross-talk across the color channels.

-normal

The input texture is a three channel linear LDR normal map storing unit length normals as (R=X, G=Y, B=Z). The output will be a two channel X+Y normal map stored as (RGB=X, A=Y), optimized for angular error instead of simple PSNR. The Z component can be recovered programmatically in shader code by using the equation:

nml.xy = texture(...).ga; // Load in [0,1]

nml.xy = nml.xy * 2.0 - 1.0; // Unpack to [-1,1]

nml.z = sqrt(1 - dot(nml.xy, nml.xy)); // Compute Z

-perceptual

The codec should optimize perceptual error, instead of direct RMS error. This aims to improves perceived image quality, but typically lowers the measured PSNR score. Perceptual methods are currently only available for normal maps.

-array <size>

Loads an array of <size> 2D image slices to use as a 3D image. The input filename given is used is decorated with the postfix "_<slice>" to find the file to load. For example, an input named "input.png" would load as input_0.png, input_1.png, etc.

-pp-normalize

Run a preprocess over the image that forces normal vectors to be unit length. Preprocessing applies before any codec encoding swizzle, so normal data must be in the RGB channels in the source image.

-pp-premultiply

Run a preprocess over the image that scales RGB components in the image by the alpha value. Preprocessing applies before any codec encoding swizzle, so color data must be in the RGB channels in the source image.

COMPRESSION TIPS & TRICKS¶

ASTC is a block-based format that can be prone to block artifacts. If block artifacts are a problem when compressing a given texture, adding some or all of following command-line options may help:

-b 1.8
-v 2 1 1 0 25 0.1
-va 1 1 0 25
-dblimit 60

The -b option is a general-purpose block-artifact reduction option. The -v and -va option settings will concentrate effort where smooth regions lie next to regions with high detail, which are particularly prone to block artifacts. Increasing the -dblimit option is sometimes also needed to force the compressor to keep searching for a better encoding, which can be needed in images with smooth gradients.

If a texture exhibits severe block artifacts in only some of the color channels, which is a common problem for mask textures, then using the -cw option to raise the weighting of the affected color channel(s) may help. For example, if the green color channel is particularly badly encoded then try -cw 1 6 1 1.

ADVANCED COMPRESSION¶

DECOMPRESSION¶

To decompress an image stored in the ASTC format you must specify the color profile, the input file name, and the output file name.

The color profile is specified using the -dl (LDR linear), -ds (LDR sRGB), -dh (HDR RGB, LDR A), or -dH(HDR RGBA) decoder options.

The input file path must match a valid file format for decompression, and the output file format must be a valid output for a decompressed image. Note that not all output formats that the coompression path can produce are supported for decompression. See the FILE FORMATS section for the list of supported formats.

The -dsw options documented in ADVANCED COMPRESSION option documentation are relevant to decompression.

TEST¶

To perform a compression test which round-trips a single image through compression and decompression and stores the decompressed result back to file, you must specify same settings as COMPRESSION other than swapping the color profile to select test mode. Note that the compressed intermediate data is discarded in this mode.

The color profile is specified using the -tl (LDR linear), -ts (LDR sRGB), -th (HDR RGB, LDR A), or -tH (HDR RGBA) encoder options.

This operation mode will print error metrics suitable for either LDR and HDR images, allowing some assessment of the compression image quality.

COMPRESSION FILE FORMATS¶

The following formats are supported as compression inputs:

For the KTX and DDS formats only a subset of the features of the formats are supported:

• Texture topology must be 2D, 2D-array, 3D, or cube-map. Note that 2D-array textures are treated as 3D block input.
• Texel format must be R, RG, RGB, BGR, RGBA, BGRA, L, or LA.
• Only the first mipmap in the file will be read.

The following formats are supported as compression outputs:

• ASTC (*.astc)
• Khronos Texture KTX (*.ktx)

DECOMPRESSION FILE FORMATS¶

The following formats are supported as decompression inputs:

• ASTC (*.astc)
• Khronos Texture KTX (*.ktx)

The following formats are supported as decompression outputs: