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