1// SPDX-License-Identifier: Apache-2.0 2// ---------------------------------------------------------------------------- 3// Copyright 2011-2023 Arm Limited 4// 5// Licensed under the Apache License, Version 2.0 (the "License"); you may not 6// use this file except in compliance with the License. You may obtain a copy 7// of the License at: 8// 9// http://www.apache.org/licenses/LICENSE-2.0 10// 11// Unless required by applicable law or agreed to in writing, software 12// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 14// License for the specific language governing permissions and limitations 15// under the License. 16// ---------------------------------------------------------------------------- 17 18/** 19 * @brief Functions for printing build info and help messages. 20 */ 21 22#include "astcenccli_internal.h" 23#include "astcenccli_version.h" 24 25/** @brief The version header. */ 26static const char *astcenc_copyright_string = 27R"(astcenc v%s, %u-bit %s%s%s 28Copyright (c) 2011-%s Arm Limited. All rights reserved. 29)"; 30 31/** @brief The short-form help text. */ 32static const char *astcenc_short_help = 33R"( 34Basic usage: 35 36To compress an image use: 37 astcenc {-cl|-cs|-ch|-cH} <in> <out> <blockdim> <quality> [options] 38 39e.g. using LDR profile, 8x6 blocks, and the thorough quality preset: 40 astcenc -cl kodim01.png kodim01.astc 8x6 -thorough 41 42To decompress an image use: 43 astcenc {-dl|-ds|-dh|-dH} <in> <out> 44 45e.g. using LDR profile: 46 astcenc -dl kodim01.astc kodim01.png 47 48To perform a compression test, writing back the decompressed output, use: 49 astcenc {-tl|-ts|-th|-tH} <in> <out> <blockdim> <quality> [options] 50 51e.g. using LDR profile, 8x6 blocks, and the thorough quality preset: 52 astcenc -tl kodim01.png kodim01-test.png 8x6 -thorough 53 54The -*l options are used to configure the codec to support only the linear 55LDR profile, preventing use of the HDR encoding features. 56 57The -*s options are used to configure the codec to support only 58the sRGB LDR profile, preventing use of the HDR encoding features. Input 59texture data must be encoded in the sRGB colorspace for this option to 60provide correct output results. 61 62The -*h/-*H options are used to configure the codec to support the HDR ASTC 63color profile. Textures compressed with this profile may fail to decompress 64correctly on GPU hardware without HDR profile support. The -*h options 65configure the compressor for HDR RGB components and an LDR alpha component. 66The -*H options configure the compressor for HDR across all 4 components. 67 68For full help documentation run 'astcenc -help'. 69)"; 70 71/** @brief The long-form help text. */ 72static const char *astcenc_long_help = R"( 73NAME 74 astcenc - compress or decompress images using the ASTC format 75 76SYNOPSIS 77 astcenc {-h|-help} 78 astcenc {-v|-version} 79 astcenc {-cl|-cs|-ch|-cH} <in> <out> <blocksize> <quality> [options] 80 astcenc {-dl|-ds|-dh|-dH} <in> <out> <blocksize> <quality> [options] 81 astcenc {-tl|-ts|-th|-tH} <in> <out> <blocksize> <quality> [options] 82 83DESCRIPTION 84 astcenc compresses image files into the Adaptive Scalable Texture 85 Compression (ASTC) image format, a lossy compression format design 86 for use in real-time graphics applications. It is a fully featured 87 compressor implementation, supporting all of the compression 88 profiles and block sizes specified by the ASTC format: 89 90 All color profiles (LDR linear, LDR sRGB, and HDR) 91 All 2D block sizes (4x4 though to 12x12) 92 All 3D block sizes (3x3x3 through to 6x6x6) 93 94 The compressor provides a flexible quality level, allowing users to 95 trade off compressed image quality against compression performance. 96 For ease of use, a number of quality presets are also provided. For 97 advanced users the compressor provides many additional control 98 options for fine tuning quality. 99 100 astcenc can also be used to decompress ASTC compressed images, and 101 perform compression image quality analysis. 102 103COMPRESSION 104 To compress an image using the ASTC format you must specify the 105 color profile, the input file name, the output file name, the target 106 block size, and the quality preset. 107 108 The color profile is specified using the -cl (LDR linear), -cs (LDR 109 sRGB), -ch (HDR RGB, LDR A), or -cH (HDR RGBA) encoder options. Note 110 that not all GPUs implementing ASTC support the HDR profile. 111 112 The input file path must match a valid file format for compression, 113 and the output file format must be a valid output for compression. 114 See the FILE FORMATS section for the list of supported formats. 115 116 The block size must be a valid ASTC block size. Every block 117 compresses into 128 bits of compressed output, so the block size 118 determines the compressed data bitrate. 119 120 Supported 2D block sizes are: 121 122 4x4: 8.00 bpp 10x5: 2.56 bpp 123 5x4: 6.40 bpp 10x6: 2.13 bpp 124 5x5: 5.12 bpp 8x8: 2.00 bpp 125 6x5: 4.27 bpp 10x8: 1.60 bpp 126 6x6: 3.56 bpp 10x10: 1.28 bpp 127 8x5: 3.20 bpp 12x10: 1.07 bpp 128 8x6: 2.67 bpp 12x12: 0.89 bpp 129 130 Supported 3D block sizes are: 131 132 3x3x3: 4.74 bpp 5x5x4: 1.28 bpp 133 4x3x3: 3.56 bpp 5x5x5: 1.02 bpp 134 4x4x3: 2.67 bpp 6x5x5: 0.85 bpp 135 4x4x4: 2.00 bpp 6x6x5: 0.71 bpp 136 5x4x4: 1.60 bpp 6x6x6: 0.59 bpp 137 138 The quality level configures the quality-performance tradeoff for 139 the compressor; more complete searches of the search space improve 140 image quality at the expense of compression time. The quality level 141 can be set to any value between 0 (fastest) and 100 (exhaustive), 142 or to a fixed quality preset: 143 144 -fastest (equivalent to quality = 0) 145 -fast (equivalent to quality = 10) 146 -medium (equivalent to quality = 60) 147 -thorough (equivalent to quality = 98) 148 -verythorough (equivalent to quality = 99) 149 -exhaustive (equivalent to quality = 100) 150 151 For compression of production content we recommend using a quality 152 level equivalent to -medium or higher. 153 154 Using quality levels higher than -thorough will significantly 155 increase compression time, but typically only gives minor quality 156 improvements. 157 158 There are a number of additional compressor options which are useful 159 to consider for common usage, based on the type of image data being 160 compressed. 161 162 -decode_unorm8 163 Indicate that an LDR compressed texture will be used with 164 the decode_unorm8 extension behavior, instead of the default 165 decode_unorm16 decompression. 166 167 Matching the decode mode used during compression to the mode 168 used at runtime will improve image quality as the compressor 169 can ensure that rounding goes the right way. 170 171 This mode is used automatically if you decompress to an 8-bit 172 per component output image format. 173 174 -normal 175 The input texture is a three component linear LDR normal map 176 storing unit length normals as (R=X, G=Y, B=Z). The output will 177 be a two component X+Y normal map stored as (RGB=X, A=Y). The Z 178 component can be recovered programmatically in shader code by 179 using the equation: 180 181 nml.xy = texture(...).ga; // Load in [0,1] 182 nml.xy = nml.xy * 2.0 - 1.0; // Unpack to [-1,1] 183 nml.z = sqrt(1 - dot(nml.xy, nml.xy)); // Compute Z 184 185 Alternative component swizzles can be set with -esw and -dsw 186 parameters. 187 188 -rgbm <max> 189 The input texture is an RGBM encoded texture, storing values HDR 190 values between 0 and <max> in an LDR container format with a 191 shared multiplier. Shaders reconstruct the HDR value as: 192 193 vec3 hdr_value = tex.rgb * tex.a * max; 194 195 The compression behavior of the ASTC format for RGBM data 196 requires that the user's RGBM encoding preprocess keeps values 197 of M above a lower threshold to avoid them quantizing to zero 198 during compression. We recommend trying 16/255 or 32/255. 199 200 -perceptual 201 The codec should optimize perceptual error, instead of direct 202 RMS error. This aims to improves perceived image quality, but 203 typically lowers the measured PSNR score. Perceptual methods are 204 currently only available for normal maps and RGB color data. 205 206 -zdim <zdim> 207 Load a sequence of <zdim> 2D image slices to use as a 3D image. 208 The input filename given is used is decorated with the postfix 209 "_<slice>" to find the file to load. For example, an input named 210 "input.png" would load as input_0.png, input_1.png, etc. 211 212 -pp-normalize 213 Run a preprocess over the image that forces normal vectors to 214 be unit length. Preprocessing applies before any codec encoding 215 swizzle, so normal data must be in the RGB components in the 216 source image. 217 218 -pp-premultiply 219 Run a preprocess over the image that scales RGB components in 220 the image by the alpha value. Preprocessing applies before any 221 codec encoding swizzle, so color data must be in the RGB 222 components in the source image.)" 223// This split in the literals is needed for Visual Studio; the compiler 224// will concatenate these two strings together ... 225R"( 226 227COMPRESSION TIPS & TRICKS 228 ASTC is a block-based format that can be prone to block artifacts. 229 If block artifacts are a problem when compressing a given texture, 230 increasing the compressor quality preset can help to alleviate the 231 problem. 232 233 If a texture exhibits severe block artifacts in only some of the 234 color components, which is a common problem for mask textures, then 235 using the -cw option to raise the weighting of the affected color 236 component(s) may help. For example, if the green color component is 237 particularly badly encoded then try '-cw 1 6 1 1'. 238 239ADVANCED COMPRESSION 240 Error weighting options 241 ----------------------- 242 243 These options provide low-level control of the codec error metric 244 computation, used to determine what good compression looks like. 245 246 -a <radius> 247 For textures with alpha component, scale per-texel weights by 248 the alpha value. The alpha value chosen for scaling of any 249 particular texel is taken as an average across a neighborhood of 250 the texel defined by the <radius> argument. Setting <radius> to 251 0 causes only the texel's own alpha to be used. 252 253 ASTC blocks that are entirely zero weighted, after the radius is 254 taken into account, are replaced by constant color blocks. This 255 is an RDO-like technique to improve compression ratio in any 256 application packaging compression that is applied. 257 258 -cw <red> <green> <blue> <alpha> 259 Assign an additional weight scaling to each color component, 260 allowing the components to be treated differently in terms of 261 error significance. Set values above 1 to increase a component's 262 significance, and values below 1 to decrease it. Set to 0 to 263 exclude a component from error computation. 264 265 -mpsnr <low> <high> 266 Set the low and high f-stop values for the mPSNR error metric. 267 The mPSNR error metric only applies to HDR textures. 268 269 Performance-quality tradeoff options 270 ------------------------------------ 271 272 These options provide low-level control of the codec heuristics that 273 drive the performance-quality trade off. The presets vary by block 274 bitrate; the recommended starting point for a 4x4 block is very 275 different to a 8x8 block. The presets documented here are for the 276 high bitrate mode (fewer than 25 texels). 277 278 -partitioncountlimit <number> 279 Test up to and including <number> partitions for each block. 280 Higher numbers give better quality, as more complex blocks can 281 be encoded, but will increase search time. Preset defaults are: 282 283 -fastest : 2 284 -fast : 3 285 -medium : 4 286 -thorough : 4 287 -verythorough : 4 288 -exhaustive : 4 289 290 -[2|3|4]partitionindexlimit <number> 291 Estimate errors for <number> block partition indices for this 292 partition count. Higher numbers give better quality, however 293 large values give diminishing returns especially for smaller 294 block sizes. Preset defaults are: 295 296 -fastest : 10 | 6 | 4 297 -fast : 18 | 10 | 8 298 -medium : 34 | 28 | 16 299 -thorough : 82 | 60 | 30 300 -verythorough : 256 | 128 | 64 301 -exhaustive : 512 | 512 | 512 302 303 -[2|3|4]partitioncandidatelimit <number> 304 Calculate errors for <number> block partition indices for this 305 partition count. Higher numbers give better quality, however 306 large values give diminishing returns especially for smaller 307 block sizes. Preset defaults are: 308 309 -fastest : 2 | 2 | 2 310 -fast : 2 | 2 | 2 311 -medium : 2 | 2 | 2 312 -thorough : 3 | 2 | 2 313 -verythorough : 20 | 14 | 8 314 -exhaustive : 32 | 32 | 32 315 316 -blockmodelimit <number> 317 Test block modes below <number> usage centile in an empirically 318 determined distribution of block mode frequency. This option is 319 ineffective for 3D textures. Preset defaults are: 320 321 -fastest : 43 322 -fast : 55 323 -medium : 77 324 -thorough : 94 325 -verythorough : 98 326 -exhaustive : 100 327 328 -refinementlimit <number> 329 Iterate <number> refinement iterations on colors and 330 weights. Minimum value is 1. Preset defaults are: 331 332 -fastest : 2 333 -fast : 3 334 -medium : 3 335 -thorough : 4 336 -verythorough : 4 337 -exhaustive : 4 338 339 -candidatelimit <number> 340 Trial <number> candidate encodings for each block mode: 341 342 -fastest : 2 343 -fast : 3 344 -medium : 3 345 -thorough : 4 346 -verythorough : 6 347 -exhaustive : 8 348 349 -dblimit <number> 350 Stop compression work on a block as soon as the PSNR of the 351 block, measured in dB, exceeds <number>. This option is 352 ineffective for HDR textures. Preset defaults, where N is the 353 number of texels in a block, are: 354 355 -fastest : MAX(63-19*log10(N), 85-35*log10(N)) 356 -fast : MAX(63-19*log10(N), 85-35*log10(N)) 357 -medium : MAX(70-19*log10(N), 95-35*log10(N)) 358 -thorough : MAX(77-19*log10(N), 105-35*log10(N)) 359 -verythorough : 999 360 -exhaustive : 999 361 362 -[2|3]partitionlimitfactor <factor> 363 Stop compression work on a block after only testing blocks with 364 up to 2/3 partitions and one plane of weights, unless the 2/3 365 partition error term is lower than the error term from encoding 366 with 1/2 partitions by more than the specified factor. Preset 367 defaults are: 368 369 -fastest : 1.00 | 1.00 370 -fast : 1.00 | 1.00 371 -medium : 1.10 | 1.05 372 -thorough : 1.35 | 1.15 373 -verythrorough : 1.60 | 1.40 374 -exhaustive : 2.00 | 2.00 375 376 -2planelimitcorrelation <factor> 377 Stop compression after testing only one plane of weights, unless 378 the minimum color correlation factor between any pair of color 379 components is below this factor. This option is ineffective for 380 normal maps. Preset defaults are: 381 382 -fastest : 0.50 383 -fast : 0.65 384 -medium : 0.85 385 -thorough : 0.95 386 -verythorough : 0.98 387 -exhaustive : 0.99 388)" 389// This split in the literals is needed for Visual Studio; the compiler 390// will concatenate these two strings together ... 391R"( 392 Other options 393 ------------- 394 395 -esw <swizzle> 396 Specify an encoding swizzle to reorder the color components 397 before compression. The swizzle is specified using a four 398 character string, which defines the format ordering used by 399 the compressor. 400 401 The characters may be taken from the set [rgba01], selecting 402 either input color components or a literal zero or one. For 403 example to swap the RG components, and replace alpha with 1, 404 the swizzle 'grb1' should be used. 405 406 By default all 4 post-swizzle components are included in the 407 compression error metrics. When using -esw to map two 408 component data to the L+A endpoint (e.g. -esw rrrg) the 409 luminance data stored in the RGB components will be weighted 3 410 times more strongly than the alpha component. This can be 411 corrected using the -ssw option to specify which components 412 will be sampled at runtime e.g. -ssw ra. 413 414 -ssw <swizzle> 415 Specify a sampling swizzle to identify which color components 416 are actually read by the application shader program. For example, 417 using -ssw ra tells the compressor that the green and blue error 418 does not matter because the data is not actually read. 419 420 The sampling swizzle is based on the channel ordering after the 421 -esw transform has been applied. Note -ssw exposes the same 422 functionality as -cw, but in a more user-friendly form. 423 424 -dsw <swizzle> 425 Specify a decompression swizzle used to reorder the color 426 components after decompression. The swizzle is specified using 427 the same method as the -esw option, with support for an extra 428 "z" character. This is used to specify that the compressed data 429 stores an X+Y normal map, and that the Z output component 430 should be reconstructed from the two components stored in the 431 data. For the typical ASTC normal encoding, which uses an 432 'rrrg' compression swizzle, you should specify an 'raz1' 433 swizzle for decompression. 434 435 -yflip 436 Flip the image in the vertical axis prior to compression and 437 after decompression. Note that using this option in a test mode 438 (-t*) will have no effect as the image will be flipped twice. 439 440 -j <threads> 441 Explicitly specify the number of threads to use in the codec. If 442 not specified, the codec will use one thread per CPU detected in 443 the system. 444 445 -silent 446 Suppresses all non-essential diagnostic output from the codec. 447 Error messages will always be printed, as will mandatory outputs 448 for the selected operation mode. For example, the test mode will 449 always output image quality metrics and compression time but 450 will suppress all other output.)" 451// This split in the literals is needed for Visual Studio; the compiler 452// will concatenate these two strings together ... 453R"( 454 455DECOMPRESSION 456 To decompress an image stored in the ASTC format you must specify 457 the color profile, the input file name, and the output file name. 458 459 The color profile is specified using the -dl (LDR linear), -ds (LDR 460 sRGB), -dh (HDR RGB, LDR A), or -dH (HDR RGBA) decoder options. 461 462 The input file path must match a valid file format for 463 decompression, and the output file format must be a valid output for 464 a decompressed image. Note that not all output formats that the 465 compression path can produce are supported for decompression. See 466 the FILE FORMATS section for the list of supported formats. 467 468 The -dsw option documented in ADVANCED COMPRESSION option 469 documentation is also relevant to decompression. 470 471TEST 472 To perform a compression test which round-trips a single image 473 through compression and decompression and stores the decompressed 474 result back to file, you must specify same settings as COMPRESSION 475 other than swapping the color profile to select test mode. Note that 476 the compressed intermediate data is discarded in this mode. 477 478 The color profile is specified using the -tl (LDR linear), -ts (LDR 479 sRGB), -th (HDR RGB, LDR A), or -tH (HDR RGBA) encoder options. 480 481 This operation mode will print error metrics suitable for either LDR 482 and HDR images, allowing some assessment of the compression image 483 quality. 484 485COMPRESSION FILE FORMATS 486 The following formats are supported as compression inputs: 487 488 LDR Formats: 489 BMP (*.bmp) 490 PNG (*.png) 491 Targa (*.tga) 492 JPEG (*.jpg) 493 494 HDR Formats: 495 OpenEXR (*.exr) 496 Radiance HDR (*.hdr) 497 498 Container Formats: 499 Khronos Texture KTX (*.ktx) 500 DirectDraw Surface DDS (*.dds) 501 502 For the KTX and DDS formats only a subset of the features of the 503 formats are supported: 504 505 Texture topology must be 2D, 2D-array, 3D, or cube-map. Note 506 that 2D-array textures are treated as 3D block input. 507 508 Texel format must be R, RG, RGB, BGR, RGBA, BGRA, L, or LA. 509 510 Only the first mipmap in the file will be read. 511 512 The following formats are supported as compression outputs: 513 514 ASTC (*.astc) 515 Khronos Texture KTX (*.ktx) 516 517 518DECOMPRESSION FILE FORMATS 519 The following formats are supported as decompression inputs: 520 521 ASTC (*.astc) 522 Khronos Texture KTX (*.ktx) 523 524 The following formats are supported as decompression outputs: 525 526 LDR Formats: 527 BMP (*.bmp) 528 PNG (*.png) 529 Targa (*.tga) 530 531 HDR Formats: 532 OpenEXR (*.exr) 533 Radiance HDR (*.hdr) 534 535 Container Formats: 536 Khronos Texture KTX (*.ktx) 537 DirectDraw Surface DDS (*.dds) 538 539QUICK REFERENCE 540 541 To compress an image use: 542 astcenc {-cl|-cs|-ch|-cH} <in> <out> <blockdim> <quality> [options] 543 544 To decompress an image use: 545 astcenc {-dl|-ds|-dh|-dH} <in> <out> 546 547 To perform a quality test use: 548 astcenc {-tl|-ts|-th|-tH} <in> <out> <blockdim> <quality> [options] 549 550 Mode -*l = linear LDR, -*s = sRGB LDR, -*h = HDR RGB/LDR A, -*H = HDR. 551 Quality = -fastest/-fast/-medium/-thorough/-verythorough/-exhaustive/a float [0-100]. 552)"; 553 554/* See header for documentation. */ 555void astcenc_print_header() 556{ 557#if (ASTCENC_AVX == 2) 558 const char* simdtype = "avx2"; 559#elif (ASTCENC_SSE == 41) 560 const char* simdtype = "sse4.1"; 561#elif (ASTCENC_SSE == 20) 562 const char* simdtype = "sse2"; 563#elif (ASTCENC_NEON == 1) 564 const char* simdtype = "neon"; 565#else 566 const char* simdtype = "none"; 567#endif 568 569#if (ASTCENC_POPCNT == 1) 570 const char* pcnttype = "+popcnt"; 571#else 572 const char* pcnttype = ""; 573#endif 574 575#if (ASTCENC_F16C == 1) 576 const char* f16ctype = "+f16c"; 577#else 578 const char* f16ctype = ""; 579#endif 580 581 unsigned int bits = static_cast<unsigned int>(sizeof(void*) * 8); 582 printf(astcenc_copyright_string, 583 VERSION_STRING, bits, simdtype, pcnttype, f16ctype, YEAR_STRING); 584} 585 586/* See header for documentation. */ 587void astcenc_print_shorthelp() 588{ 589 astcenc_print_header(); 590 printf("%s", astcenc_short_help); 591} 592 593/* See header for documentation. */ 594void astcenc_print_longhelp() 595{ 596 astcenc_print_header(); 597 printf("%s", astcenc_long_help); 598} 599