Repository navigation
Expand file tree
/
Copy pathbasisu_tool_help.h
More file actions
903 lines (903 loc) · 44.7 KB
/
Copy pathbasisu_tool_help.h
File metadata and controls
903 lines (903 loc) · 44.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
// Don't edit directly - see python script in cmd_help directory.
"See project and wiki at: https://github.com/BinomialLLC/basis_universal\n"
"\n"
"The default processing mode is compression of one or more .PNG/.TGA/.JPG/.QOI/\n"
".DDS/.EXR/.HDR files to a LDR or HDR .KTX2 file. Alternate modes:\n"
"\n"
" -unpack: Use transcoder to unpack a .basis/.KTX2/.DDS file to one or more .KTX,\n"
" .DDS, .PNG, .ASTC, etc. files. For a .DDS input, each layer/face/mip image is\n"
" decoded to _unpacked_rgb_/_a_/_rgba_ PNGs and transcoded to every GPU format\n"
" as single-image _transcoded_ files (BC1-7 to .DDS+.KTX, others .KTX only),\n"
" similar to unpacking a .KTX2/.basis (flat per-image output; the exact format\n"
" set differs). (-no_ktx skips the GPU files, -ktx_only skips PNGs.) DDS unpack\n"
" uses a fixed transcode-target set -- -format_only/-etc1_only are ignored for\n"
" .dds. A bare .dds with no mode is a compress SOURCE, not unpacked -- pass\n"
" -unpack to unpack it.\n"
"\n"
" -export_dds <FORMAT>: Transcode each input .ktx2 to a .DDS file (all mips,\n"
" array layers, cubemap faces). FORMAT: BC1 BC3 BC4 BC5 BC6H BC7 RGBA32. Output\n"
" is <base>_<FORMAT>.dds; -output_file/-output_path override the name/dir.\n"
"\n"
" -dds: Write a basic DX10 .DDS file directly from source image(s). Use with\n"
" -dds_format <FMT>. Honors -mipmap, -cubemap, -tex_type 2darray, -srgb/-linear,\n"
" -swizzle, -resample, etc. (the same source-prep options as compression). All\n"
" inputs form a single .dds (one per layer/face). Output is <first_input>.dds;\n"
" -output_file/-output_path override the name/dir. LDR only.\n"
" -dds_format <FMT>: Output format for -dds (defaults to BC7 if omitted). Block\n"
" compressed: BC1 BC2 BC3 BC4 BC5 BC7. Uncompressed: A8R8G8B8 A8B8G8R8 R8 R8G8\n"
" R5G6B5 A1R5G5B5 A4R4G4B4. The sRGB DXGI variant is used for BC1/BC2/BC3/BC7/\n"
" A8R8G8B8/A8B8G8R8 unless -linear is given (other formats are always UNORM). No\n"
" transfer-function conversion is applied to texel data.\n"
" -dds_bc7f / -dds_bc7e_scalar (alias -dds_bc7e): select the BC7 packer for -dds\n"
" -dds_format BC7. bc7f = built-in fast real-time packer (default); bc7e_scalar =\n"
" higher-quality, slower scalar encoder.\n"
" -dds_bc7f_level <0-2>: bc7f quality: 0=analytical, 1=partially analytical\n"
" (default), 2=non analytical (slowest/best).\n"
" -dds_bc7e_scalar_level <0-6>: bc7e_scalar quality: 0=ultrafast..6=slowest\n"
" (default 2); implies -dds_bc7e_scalar.\n"
"\n"
" -export_ktx <FORMAT>: Transcode each input .ktx2 to a compressed KTX1 (.ktx)\n"
" file (all mips, array layers, cubemap faces). FORMAT (compressed only): BC1\n"
" BC3 BC4 BC5 BC6H BC7 ETC1 ETC2 EAC_R11 EAC_RG11 PVRTC1 PVRTC2 ASTC ASTC_<WxH>\n"
" ASTC_HDR_4x4 ASTC_HDR_6x6. Output is <base>_<FORMAT>.ktx.\n"
"\n"
" -tinydds_info: Print header info (dimensions, type, mips, array slices, format)\n"
" for each input .DDS file, via the tinydds parser. Header only -- no decode.\n"
" (-info also prints DDS header info, via the dds_transcoder.)\n"
"\n"
" -ktx_info: Print KTX1 (.ktx) header fields (GL type/format/internalFormat,\n"
" dimensions, array elements, faces, mip levels) for each input file. Header\n"
" only -- no key/value or image data parsing.\n"
"\n"
" -info: Display high-level information about a .basis/.KTX2/.DDS/.KTX1 file.\n"
" Each input is detected by content, so mixed file types on one command line\n"
" are fine (a .DDS prints its header info; a .KTX1 prints its KTX header). For\n"
" a .DDS this prints the transcoder's view (closest-matching format); use\n"
" -tinydds_info for the raw DDS header (physical pixel layout).\n"
" \n"
" -validate: Validate and display information about a .basis/.KTX2/.DDS file\n"
" (decodes/transcodes every image to exercise the codecs; writes nothing).\n"
" \n"
" -compare: Compare two LDR PNG/BMP/TGA/JPG/QOI images specified with -file,\n"
" output PSNR and SSIM statistics and RGB/A delta images\n"
"\n"
" -compare_hdr: Compare two HDR .EXR/.HDR images specified with -file, output\n"
" PSNR statistics and RGB delta images\n"
"\n"
" -dump_image_stats: Print reference-free per-channel RGBA statistics (min/max/\n"
" mean/variance/std dev/unique count) for each LDR image given with -file, plus\n"
" flags for common issues (constant/dropped channel, all-opaque or all-zero\n"
" alpha, possibly-premultiplied alpha, R==G==B grayscale). LDR/8-bit only for now.\n"
" -dump_image_stats <x> <y> <w> <h>: As above, but restrict the stats to the\n"
" given rectangle (must lie fully inside the image).\n"
"\n"
" -dump_pixel <x> <y>: Print the exact RGBA value of texel (x,y) of each -file\n"
" image (LDR only). Can be combined with -dump_image_stats / -dump_block.\n"
"\n"
" -dump_block <bx> <by>: Print the 4x4 texel block at block coords (bx,by) (i.e.\n"
" source texels [bx*4..bx*4+3] x [by*4..by*4+3]) of each -file image (LDR only).\n"
" Can be combined with -dump_image_stats / -dump_pixel.\n"
"\n"
" -tonemap: Tonemap an HDR or EXR image to PNG at multiple exposures, use -file\n"
" to specify filename\n"
"\n"
" -split: Split the -file input image into split_rgb.png plus per-channel\n"
" grayscale split_R/G/B/A.png files\n"
"\n"
" -combine: Combine two -file images: RGB from the first plus the second's\n"
" green channel as alpha, written to combined.png (or -output_file)\n"
"\n"
" -extract_channel <c> <out.png> [x y w h]: Write one channel (c = r/g/b/a or\n"
" 0..3) of the -file image as a grayscale PNG. Optionally restrict to the given\n"
" rectangle (must lie fully inside the image). LDR only.\n"
"\n"
" -extract_swizzle <swizzle> <out.png> [x y w h]: Write an RGBA PNG whose R,G,B,A\n"
" come from the source channels named by <swizzle>, a list of 1..4 comma-\n"
" separated channels (each r/g/b/a or 0..3), e.g. \"0,1,2,3\" (identity),\n"
" \"2,1,0\" (swap R/B), \"a,a,a,a\" (broadcast alpha). Output channels not listed\n"
" pass through unchanged. Optional rectangle as with -extract_channel. LDR only.\n"
"\n"
" -extract_region <out.png> <x> <y> <w> <h>: Write the given rectangle of the\n"
" -file image (full RGBA) to a PNG. The rectangle must lie fully inside the\n"
" image. LDR only.\n"
"\n"
" -extract_to_linear / -extract_to_srgb: Optional transforms applied by the\n"
" -extract_* commands above: convert the output from sRGB to linear, or from\n"
" linear to sRGB. Applied to RGB only by default (alpha passes through).\n"
" -extract_xform_alpha: Also apply the -extract_to_linear/-extract_to_srgb\n"
" transform to the alpha channel (off by default).\n"
"\n"
" -text_to_png <in.txt> <out.png>: Compose a small PNG from a comma-separated\n"
" pixel text file. Line 1 is the header \"W,H,C\" (W,H in [1,1024], C channels in\n"
" [1,4]); then one pixel per line with C decimal values 0..255 in row-major\n"
" order (1=L, 2=LA, 3=RGB, 4=RGBA). Blank lines and '#' comments are ignored.\n"
" Strict: malformed values / wrong counts are a hard error with the line number.\n"
" -png_to_text <in.png> <out.txt>: Inverse of -text_to_png. Auto-detects the\n"
" minimal channel count (L/LA/RGB/RGBA) and writes the text format above.\n"
"\n"
" -peek_astc: Read an .astc file and calculate statistics (for testing/dev)\n"
"\n"
" -version or --version: Print version and exit\n"
"\n"
"--- Intro:\n"
"\n"
"This tool compresses LDR/SDR and HDR images and textures to a Basis Universal\n"
"supercompressed GPU texture, which can be written to supercompressed .basis or\n"
"standard .KTX2 files. It supports a number of SDR and HDR codecs, each with\n"
"different quality, transcoding performance, and bitrate tradeoffs. A SDR/HDR\n"
"mipmap generator is also included. This tool can also examine and\n"
"unpack .KTX2/.basis files to .PNG, .KTX (v1), .ASTC, or .DDS files using its\n"
"single source file transcoder library.\n"
"\n"
"Options may be given in either -opt or Unix-style --opt form.\n"
"\n"
"The list of supported texture/supercompressed texture codecs:\n"
" -LDR: ETC1S (SDR default), RDO UASTC LDR 4x4, ASTC or XUASTC LDR 4x4-12x12\n"
" -HDR: UASTC HDR 4x4 (HDR default), RDO ASTC HDR 6x6, UASTC HDR 6x6\n"
" \n"
"RDO=Rate-Distortion Optimization. Two key parameters (quality and effort) have\n"
"been unified across all the codecs:\n"
"\n"
"- The -quality X parameter, where X ranges from [0, 100], controls the\n"
"compression quality vs. bitrate (output file size) tradeoff for those codecs\n"
"supporting supercompression or RDO (Rate-distortion optimization). 100=max\n"
"quality, and lower levels produce smaller files with more distortion.\n"
"\n"
"- The -effort X parameter, where X ranges from [0, 10], controls the\n"
"compression speed (and max CPU usage) vs. max achievable quality tradeoff.\n"
"Low efforts result in more distortion/artifacts, but faster compression. Lower\n"
"efforts result in less utilization of the underlying GPU block format's\n"
"capabilities.\n"
"\n"
"Key Definitions: \n"
"\"Quality\" controls the explicit tradeoff between output distortion and output\n"
"file bitrate (in bits per pixel or target). At max quality (100) each\n"
"compressor will output the lowest distortion it's capable of at its currently\n"
"configured effort level.\n"
"\n"
"\"Effort\" controls how intensely a compressor uses the CPU to focus on each\n"
"block format's encoding capabilities. Low effort levels only target a set of\n"
"core or basic capabilities (specific to each output target format), while\n"
"higher effort levels allow each compressor to explore more of each target's\n"
"features (at the cost of higher CPU time). Lower effort levels result in more\n"
"brittle compression (higher distortion on tough image/texture features).\n"
"Effort=0 fastest compression, effort=10=extremely slow.\n"
"\n"
"Unless an explicit mode is specified, if one or more files have the .basis,\n"
".KTX2, or .ktx (KTX1) extension this tool defaults to unpack mode. (A .ktx is\n"
"KTX1, which can't be unpacked -- it errors with a pointer to -info/-ktx_info.\n"
"A bare .dds is treated as a compress SOURCE, not unpacked; use -unpack for it.)\n"
"\n"
"By default, the compressor assumes the input is in the sRGB colorspace (like\n"
"typical photos/albedo textures). If the input is NOT sRGB (like a normal map),\n"
"be sure to specify -linear for less artifacts. Depending on the content type,\n"
"some experimentation may be needed.\n"
"\n"
"The TinyEXR library is used to read .EXR images. Crucially, this small library\n"
"does not support all .EXR compression methods. For unsupported images, you can\n"
"use a tool like ImageMagick to convert them to uncompressed .EXR.\n"
"\n"
"For .DDS COMPRESSION SOURCE files (i.e. compressing a .dds as an input image --\n"
"this does NOT limit -unpack): Mipmapped or plain 2D textures (but not cubemaps)\n"
"are supported, and only uncompressed 32-bit RGBA/BGRA, half float RGBA, or\n"
"float RGBA .DDS files. In -tex_array mode, if a .DDS file is specified, all\n"
"source files must be in .DDS format. (To UNPACK a compressed .dds -- BC1-7,\n"
"cubemaps, arrays, etc. -- use -unpack, which has no such restrictions.)\n"
"\n"
"Filenames prefixed with a @ symbol are read as filename listing files. Listing\n"
"text files specify which actual filenames to process (one filename per line).\n"
"\n"
"--- High-Level Texture Mode (Codec) Selection:\n"
"\n"
" 1. -etc1s: Encode to supercompressed ETC1S LDR (the default for SDR/LDR\n"
" inputs). Roughly .8-2.5 bpp. Supports temporal texture supercompression\n"
" (texture video) with skip blocks (Conditional Replenishment), with global\n"
" codebooks shared across all frames.\n"
"\n"
" 2. -uastc/-uastc_ldr: UASTC LDR 4x4. Encode to UASTC LDR 4x4, a custom high\n"
" quality virtual texture format designed for fast transcoding to numerous\n"
" GPU texture formats. Roughly 5-8 bpp. Supports RDO encoding using -lambda X\n"
" option - see options below. In this mode the multi-target compressor\n"
" optimizes for a balance of transcoded ASTC 4x4 LDR and BC7 quality.\n"
"\n"
" 3. -hdr/-hdr_4x4: UASTC HDR 4x4. Encode input as UASTC HDR 4x4 (the default if\n"
" any input file has the .EXR or .HDR extension, or if any .DDS file is HDR).\n"
" Output is standard, but constrained, ASTC HDR 4x4. Roughly 5-8 bpp. In this\n"
" mode the dual-target compressor optimizes for a balance of transcoded ASTC\n"
" 4x4 HDR and BC6H quality.\n"
"\n"
" 4. -hdr_6x6: ASTC HDR 6x6. Encode input as RDO or highest quality standard\n"
" ASTC HDR 6x6. Use -quality (preferred) or -lambda X (low-level, try\n"
" 100-20000 or higher) option to enable RDO ASTC HDR 6x6, where x controls\n"
" the quality vs. size tradeoff. Roughly 1.2-3.2 bpp.\n"
"\n"
" 5. -hdr_6x6i: UASTC HDR 6x6. Encode input as supercompressed UASTC HDR 6x6\n"
" intermediate. Use -quality (preferred) or -lambda X (low-level, try\n"
" 100-20000 or higher) option to enable RDO UASTC HDR 6x6, where x controls\n"
" the quality vs. size tradeoff. Roughly 1-3.2 bpp.\n"
"\n"
" 6. XUASTC LDR 4x4-12x12: -ldr_4x4i, -ldr_5x4i, -ldr_5x5i, -ldr_6x5i,\n"
" -ldr_6x6i, -ldr_8x5i, -ldr_8x6i, -ldr_10x5i, -ldr_10x6i, -ldr_8x8i,\n"
" -ldr_10x8i, -ldr_10x10i, -ldr_12x10i, -ldr_12x12i:\n"
" Compress to supercompressed XUASTC LDR/SDR using the specific\n"
" ASTC block size. See additional ASTC/XUASTC LDR specific options\n"
" (-effort, -quality, -xy, -ts, -tl, etc.) below. Roughly .3-5.7 bpp\n"
"\n"
" 7. ASTC LDR 4x4-12x12: -ldr_4x4, -ldr_5x4, -ldr_5x5, -ldr_6x5, -ldr_6x6,\n"
" -ldr_8x5, -ldr_8x6, -ldr_10x5, -ldr_10x6, -ldr_8x8, -ldr_10x8,\n"
" -ldr_10x10, -ldr_12x10, -ldr_12x12:\n"
" Compress to standard or ZStd supercompressed ASTC LDR/SDR using\n"
" the specific ASTC block size. See additional ASTC LDR specific\n"
" options (-effort, -quality, -xy, -ts, -tl, etc.) below. .89-8 bpp before\n"
" ZStd compression.\n"
"\n"
" 8. XUBC7: -xubc7. Lossless or lossy supercompressed BC7. Options:\n"
" Use -quality [1,100], -effort [0,10], and -xubc7_rdo_level [0,100]\n"
" (0=no RDO - default, 100=aggressive RDO)\n"
" -xubc7_num_stripes [1,16]: # of encode stripes (default 8; more=faster\n"
" decode/encode parallelism, slightly larger file)\n"
" -xubc7_bc7f / -xubc7_bc7e_scalar: select the BC7 base encoder (default\n"
" bc7f - fast; bc7e_scalar - bc7e.ispc-based: slower, higher quality)\n"
" -xubc7_bc7e_scalar_level [0,6]: use bc7e_scalar+set quality level (def=2)\n"
"\n"
"--- Tool Options:\n"
"\n"
" -ktx2: Write .KTX2 files (the default). By default, UASTC LDR/HDR 4x4 and ASTC\n"
" 6x6 files will be compressed using Zstandard unless -ktx2_no_zstandard is\n"
" specified.\n"
"\n"
" -basis: Write .basis files instead of .KTX2 files.\n"
"\n"
" -file filename.png/tga/jpg/qoi/exr/hdr: Input image filename, multiple images\n"
" are OK, use -file X for each input filename (prefixing input filenames\n"
" with -file is optional)\n"
"\n"
" -alpha_file filename.png/tga/jpg/qoi: Input alpha image filename, multiple\n"
" images are OK, use -file X for each input filename (must be paired\n"
" with -file), images converted to REC709 grayscale and used as input alpha\n"
"\n"
" -quiet or -no_status_output: Disable compressor's status output to stdout\n"
"\n"
" -output_file filename: Output .basis/.KTX2 filename\n"
"\n"
" -output_path: Output .basis/.KTX2 files to specified directory.\n"
"\n"
" -debug: Enable codec debug print to stdout (slightly slower).\n"
"\n"
" -verbose: Shorthand for -debug -stats (debug output plus quality metrics).\n"
"\n"
" -debug_images: Enable codec debug images (much slower).\n"
"\n"
" -stats: Compute and display image quality metrics (slightly to much slower).\n"
"\n"
" -no_stats: Disable image quality metrics (overrides -verbose/-csv_file).\n"
"\n"
" -validate_output: Validate output texture data after compression.\n"
"\n"
" -csv_file filename.csv: Log image quality metrics to a CSV file (also enables\n"
" -stats computation).\n"
"\n"
" -individual: Process input images individually and output\n"
" multiple .basis/.KTX2 files (not as a texture array - this is now the default\n"
" as of v1.16)\n"
"\n"
" -parallel: Compress multiple textures simultaneously (one per thread), instead\n"
" of one at a time. Compatible with OpenCL mode. This is much faster, but in\n"
" OpenCL mode the driver is pushed harder, and the CLI output will be jumbled.\n"
"\n"
" -linear: Use linear colorspace metrics (instead of the default sRGB or scaled\n"
" RGB for HDR), write linear transfer function setting to KTX2/basis file, and\n"
" by default linear (not sRGB) mipmap filtering (unless overridden). Same\n"
" as -tl.\n"
"\n"
" -srgb: Use sRGB colorspace metrics, write sRGB transfer function setting to\n"
" KTX2/basis file, and by default use sRGB mipmap filtering (unless\n"
" overridden). Same as -ts.\n"
"\n"
" -tex_type <2d, 2darray, 3d, video, cubemap>: Set Basis file header's texture\n"
" type field. Cubemap arrays require multiples of 6 images, in X+, X-, Y+, Y-,\n"
" Z+, Z- order, each image must be the same resolutions. 2d=arbitrary 2D\n"
" images, 2darray=2D array, 3D=volume texture slices, video=video frames,\n"
" cubemap=array of faces. For 2darray/3d/cubemaps/video, each source image's\n"
" dimensions and # of mipmap levels must be the same. For video, the .basis\n"
" file will be written with the first frame being an I-Frame, and subsequent\n"
" frames being P-Frames (using conditional replenishment). Playback must always\n"
" occur in order from first to last image.\n"
"\n"
" -cubemap: same as -tex_type cubemap\n"
"\n"
" -tex_array: Process input images as a single texture array and write a\n"
" single .basis/.KTX2 file (the former default before v1.16)\n"
"\n"
" -fuzz_testing: Use with -validate: Disables CRC16 validation of file contents\n"
" before transcoding\n"
"\n"
" -multifile_printf: printf() format string to use to compose multiple filenames\n"
"\n"
" -multifile_first: The index of the first file to process, default is 0 (must\n"
" specify -multifile_printf and -multifile_num)\n"
"\n"
" -multifile_num: The total number of files to process.\n"
"\n"
" -opencl: Enable OpenCL usage (currently only accelerates ETC1S encoding)\n"
"\n"
" -opencl_serialize: Serialize all calls to the OpenCL driver (to work around\n"
" buggy drivers, only useful with -parallel)\n"
"\n"
"--- ETC1S specific options (-etc1s - the LDR/SDR default):\n"
"\n"
" -quality X and -effort X: Set quality (1-100) and effort (0-10) levels\n"
"\n"
" -q X: Low-level ETC1S quality level, 1-255, default is 128, lower=better\n"
" compression/lower quality/faster, higher=less compression/higher\n"
" quality/slower, default is 128. For even higher quality,\n"
" use -max_endpoints/-max_selectors. (-quality is preferred.)\n"
"\n"
" -comp_level X: Low-level ETC1S speed vs. quality tradeoff. Range is 0-6,\n"
" default is 1. Higher values=MUCH slower, but slightly higher quality. Higher\n"
" levels intended for videos. (-effort is preferred.)\n"
"\n"
" -max_endpoints X: ETC1S: Manually set the max number of color endpoint\n"
" clusters from 1-16128, use instead of -q\n"
"\n"
" -max_selectors X: ETC1S: Manually set the max number of color selector\n"
" clusters from 1-16128, use instead of -q\n"
"\n"
"--- UASTC LDR/HDR 4x4 specific options (-uastc or -uastc_ldr):\n"
"\n"
" -quality X and -effort X: Set quality (1-100) and effort (0-10) levels\n"
"\n"
" -uastc, -uastc_ldr or -uastc_ldr_4x4: Enable UASTC LDR 4x4 texture mode,\n"
" instead of the default ETC1S mode. Significantly higher texture quality, but\n"
" much larger (~8bpp) files. (Note that UASTC LDR 4x4 .basis files must be\n"
" losslessly compressed by the user.)\n"
"\n"
" -uastc_level: Set low-level UASTC LDR/HDR 4x4 encoding effort level. LDR Range\n"
" is [0,4], default is 2, higher=slower but higher quality. 0=fastest/lowest\n"
" quality, 3=slowest practical option, 4=impractically slow/highest achievable\n"
" quality. UASTC HDR 4x4 range is [0,4]: higher=slower, but higher quality. HDR\n"
" 4x4 default level=1.\n"
"\n"
" -uastc_rdo_l X: Enable UASTC LDR 4x4 RDO post-processing and set the low-level\n"
" UASTC LDR 4x4 RDO quality scalar (lambda) to X. Lower values=higher\n"
" quality/larger LZ compressed files, higher values=lower quality/smaller LZ\n"
" compressed files. Good range to try is [.25-10]. Note: Previous versons used\n"
" the -uastc_rdo_q option, which was removed because the RDO algorithm was\n"
" changed.\n"
"\n"
" -uastc_rdo_d X: Set UASTC LDR 4x4 RDO dictionary size in bytes. Default is\n"
" 4096, max is 65536. Lower values=faster, but less compression.\n"
"\n"
" -uastc_rdo_b X: Set UASTC LDR 4x4 RDO max smooth block error scale. Range is\n"
" [1,300]. Default is 10.0, 1.0=disabled. Larger values suppress more artifacts\n"
" (and allocate more bits) on smooth blocks.\n"
"\n"
" -uastc_rdo_s X: Set UASTC LDR 4x4 RDO max smooth block standard deviation.\n"
" Range is [.01,65536]. Default is 18.0. Larger values expand the range of\n"
" blocks considered smooth.\n"
"\n"
" -uastc_rdo_f: Don't favor simpler UASTC LDR 4x4 modes in RDO mode.\n"
"\n"
" -uastc_rdo_m: Disable RDO multithreading (slightly higher compression,\n"
" deterministic).\n"
"\n"
"--- UASTC HDR 4x4 specific options (-hdr or -hdr_4x4 - the HDR default):\n"
"\n"
" -hdr, -hdr_4x4, or -uastc_hdr_4x4: Enable UASTC HDR 4x4 mode\n"
"\n"
" -quality X and -effort X: Set quality (1-100) and effort (0-10) levels\n"
"\n"
" -uastc_level X: Sets the low-level UASTC HDR 4x4 compressor's effort level.\n"
" Valid range is [0,4]: higher=slower but higher quality. HDR\n"
" default=1. Level 0=fastest/lowest quality, 3=highest practical\n"
" setting, 4=exhaustive\n"
"\n"
" -hdr_uber_mode: Allow the UASTC HDR 4x4 encoder to try varying the CEM 11\n"
" selectors more for slightly higher quality (slower). This may negatively\n"
" impact BC6H quality, however.\n"
"\n"
" -hdr_ultra_quant: UASTC HDR 4x4: Try to find better quantized CEM 7/11\n"
" endpoint values (slower).\n"
"\n"
" -hdr_favor_astc: UASTC HDR 4x4: By default the dual-target UASTC HDR 4x4\n"
" encoder tries to strike a balance or even slightly favor BC6H quality. If\n"
" this option is specified, ASTC HDR 4x4 quality is favored instead.\n"
"\n"
"--- ASTC/UASTC HDR 6x6 specific options (-hdr_6x6 or -hdr_6x6i):\n"
"\n"
"Internally both modes use the same compressor which can generate either\n"
"standard ASTC HDR 6x6 (with optional RDO) or UASTC HDR 6x6 (supercompressed\n"
"with a custom format).\n"
"\n"
" -hdr_6x6 or -astc_hdr_6x6: Enable RDO ASTC HDR 6x6 mode\n"
"\n"
" -hdr_6x6i or -uastc_hdr_6x6: Enable UASTC HDR 6x6 mode\n"
"\n"
" -quality X and -effort X: Set quality (1-100) and effort (0-10) levels\n"
"\n"
" -lambda X: Low-level option to enable rate distortion optimization (RDO) and\n"
" directly control the HDR 6x6 compressor's lambda setting. The\n"
" higher this value, the lower the quality, but the smaller the file\n"
" size. Try 100-20000, or higher values on some images. Upconverted\n"
" SDR images can generally tolerate much higher lambda settings vs.\n"
" true HDR images.\n"
"\n"
" -hdr_6x6_level X: Low-level option to set the codec to 6x6 HDR mode (same\n"
" as -hdr_6x6) and controls encoder performance vs. max quality\n"
" tradeoff. X may range from [0,12]. Default level is 2. Higher\n"
" values result in better quality but slower encoding. Values above\n"
" 10 are extremely slow.\n"
"\n"
" -hdr_6x6i_level X: Low-level option to set the codec to 6x6 HDR intermediate\n"
" mode (same as -hdr_6x6i) and controls encoder performance vs. max\n"
" quality tradeoff. X may range from [0,12]. Default level is 2.\n"
"\n"
" -rec_2020: The input image's gamut is Rec. 2020 vs. the default Rec. 709 - for\n"
" accurate colorspace error calculations. This value will also be\n"
" written to the KTX2 file's header in the DFD.\n"
"\n"
" -hdr_6x6_jnd X, -hdr_6x6_extra_pats, -hdr_6x6_brute_force_pats,\n"
" -hdr_6x6_comp_levels X Y, or -hdr_6x6i_comp_levels X Y: Low-level\n"
" control over the encoder's configuration.\n"
"\n"
" -hdr_6x6i_16_compatibility: Write basisu v1.6 UASTC HDR 6x6i files (default)\n"
"\n"
" -hdr_6x6i_20_compatibility: Write basisu v2.0 UASTC HDR 6x6i files (slightly\n"
" lower bitrate, only compatible with v2.0+ transcoders however.)\n"
"\n"
"--- SDR/LDR->HDR upconversion options (only used when encoding to HDR formats\n"
"from an LDR/SDR source image):\n"
"\n"
" -hdr_ldr_no_srgb_to_linear: If specified, LDR images will NOT be converted to\n"
" normalized linear light (via a sRGB->Linear conversion) during SDR->HDR\n"
" upconversion before compressing as HDR.\n"
"\n"
" -hdr_ldr_upconversion_nit_multiplier X: Specify how many nits (candelas per\n"
" sq. meter) LDR/SDR images are converted to after converting to linear\n"
" light. Default is 100 nits. Note: Previous builds used 1 nit. Common\n"
" values are 80-100 nits.\n"
"\n"
" -hdr_ldr_upconversion_black_bias X: Black bias [0,1] added during SDR->HDR\n"
" upconversion (default 0).\n"
"\n"
"--- ASTC LDR/XUASTC LDR specific options (-ldr_4x4 or -ldr_4x4i, up to 12x12):\n"
"\n"
"Internally both modes (ASTC 4x4-12x12 and XUASTC 4x4-12x12) use the same\n"
"core compressor but with different outputs. All 14 standard ASTC block \n"
"sizes are supported (see the list below).\n"
"\n"
" -ldr_4x4-12x12 or -astc_ldr_4x4-12x12: Enable ASTC LDR 4x4-12x12 mode\n"
"\n"
" -ldr_4x4i-12x12 or -xuastc_ldr_4x4-12x12: Enable XUASTC LDR 4x4-12x12 mode\n"
"\n"
" -quality X: Enables lossy weight grid DCT and sets DCT quality level [1,100]\n"
" (defaults to no DCT). Higher=better quality, but higher bitrate. Good values\n"
" to try are 30-90. Default is no weight grid DCT.\n"
"\n"
" -effort X: Set encoder effort level [0,10]: Encoding speed tradeoff, \n"
" higher=slower but potentially higher overall quality. Default=3, 10=Insane.\n"
" \n"
" -xuastc_arith, -xuastc_hybrid, -xuastc_zstd: Set transcoding speed vs.\n"
" compression ratio tradeoff by selecting the output profile/syntax. Default\n"
" is -xuastc_zstd (fastest, lowest ratio). ZStd is fastest/lowest ratio, arith\n"
" is slowest/highest ratio (3-15% better vs. ZStd).\n"
"\n"
" -xy: Enables lossy supercompression using windowed/bounded RDO for extra\n"
" compression (default is lossless supercompression of the XUASTC texture data\n"
" unless DCT is enabled)\n"
"\n"
" -xyd: Disables lossy supercompression (default, but automatically enabled\n"
" if -quality less than 100 is specified )\n"
"\n"
" -xs: Force disable 2-3 subset usage in all effort levels (lower quality but\n"
" faster compression and faster transcoding to BC7 at certain block sizes)\n"
"\n"
" -xp: Force disable RGB dual plane usage in all effort levels (lower quality\n"
" but faster compression and faster transcoding to BC7 at certain block sizes)\n"
"\n"
" -xsu, -xpu: Inverses of -xs/-xp - force-enable 2-3 subset usage / RGB dual\n"
" plane, respectively.\n"
"\n"
" -ts: Use LDR sRGB ASTC decoding profile - the default. This parameter should\n"
" match how the developer will decode or sample the ASTC texture data. Inverse\n"
" of -tl. Same as -srgb.\n"
"\n"
" -tl: Use LDR Linear ASTC decoding profile. Inverse of -ts. Same as -linear.\n"
"\n"
" -weights X Y Z W: Set unsigned integer channel error weights. Default is\n"
" 9,11,1,11 (sRGB); -linear or -normal_map use 1,1,1,1. Useful to favor\n"
" certain channels during compression.\n"
"\n"
" -ls_min_psnr X, -ls_min_alpha_psnr X, -ls_thresh_psnr X, -ls_thresh_alpha_psnr\n"
" X, -ls_thresh_edge_psnr X, -ls_thresh_edge_alpha_psnr X: Windowed/bounded RDO\n"
" settings (Lossy supercompression must be enabled, or -xy.)\n"
"\n"
" -xuastc_blurring: Experimental - enable blurred block candidates (MUCH slower\n"
" compression, higher quality).\n"
"\n"
" -xuastc_sharpen X: Enable sharpening, set amount [0,10] (0 disables; higher\n"
" = sharper, but more likely to add artifacts). Off by default; default amount\n"
" is 2.0. -xuastc_no_sharpen disables.\n"
"\n"
" -xuastc_heavy_subset_usage, -xuastc_no_heavy_subset_usage: Enable/disable\n"
" heavier 2-3 subset usage (higher quality, slower; disabled by default).\n"
"\n"
"Encode-time deblocking (XUASTC LDR only): control deblocking awareness (SCD)\n"
"and/or the deblocking filter applied during compression. Default is\n"
"-xuastc_deblocking_largest. Each flag also has a -xuastc_ldr_* alias, e.g.\n"
"-xuastc_ldr_deblocking_all.\n"
"\n"
" -xuastc_no_deblocking: Disable both SCD and filtering.\n"
"\n"
" -xuastc_deblocking_largest: Use SCD and filtering only on the largest block\n"
" sizes (the codec default).\n"
"\n"
" -xuastc_deblocking_all: Use SCD and filtering on all block sizes.\n"
"\n"
" -xuastc_deblocking_scd_no_filtering: Use SCD only, no filtering.\n"
"\n"
" -xuastc_deblocking_no_scd_filtering_largest: No SCD, filter largest blocks.\n"
"\n"
" -xuastc_deblocking_no_scd_filtering_all: No SCD, filter all block sizes.\n"
"\n"
" -xuastc_deblocking_num_passes X: Set number of deblocking filter passes\n"
" [2,256].\n"
"\n"
"Internal ASTC encoder selection (advanced/experimental). The astcenc-based\n"
"options (-xuastc_use_astcenc, -xuastc_merge_astcenc, -xuastc_merge_all) require\n"
"building with BASISU_SUPPORT_ASTCENC=1:\n"
"\n"
" -xuastc_use_auto_comp: Auto-pick the ASTC encoder by effort level (default).\n"
"\n"
" -xuastc_use_basisu: Use the built-in basisu ASTC encoder.\n"
"\n"
" -xuastc_use_astcf: Use the astcf ASTC encoder.\n"
"\n"
" -xuastc_use_astcenc: Use the astcenc ASTC encoder.\n"
"\n"
" -xuastc_merge_astcf: Try basisu + astcf, keep the best result per block.\n"
"\n"
" -xuastc_merge_astcenc: Try basisu + astcenc, keep the best result per block.\n"
"\n"
" -xuastc_merge_all: Try all available encoders, keep the best result per block.\n"
"\n"
"These modes support all the standard ASTC block sizes. The larger the block\n"
"size, the lower the bitrate on disk and in memory, but the more noticeable the\n"
"artifacts. Some block sizes (4x4, 6x6, and 8x6) have specially optimized direct\n"
"transcoding paths to BC7. For faster direct BC7 transcoding at these block\n"
"sizes, disable RGB dual plane (-xp) and subset usage (-xs).\n"
"\n"
" Block Size Base/Memory Size\n"
" 1. 4x4 8.00 bpp\n"
" 2. 5x4 6.40 bpp\n"
" 3. 5x5 5.12 bpp\n"
" 4. 6x5 4.27 bpp\n"
" 5. 6x6 3.56 bpp\n"
" 6. 8x5 3.20 bpp\n"
" 7. 8x6 2.67 bpp\n"
" 8. 10x5 2.56 bpp\n"
" 9. 10x6 2.13 bpp\n"
" 10. 8x8 2.00 bpp\n"
" 11. 10x8 1.60 bpp\n"
" 12. 10x10 1.28 bpp\n"
" 13. 12x10 1.07 bpp\n"
" 14. 12x12 0.89 bpp\n"
"\n"
"--- More options:\n"
"\n"
" -test: Run an automated LDR ETC1S/UASTC LDR 4x4 encoding and transcoding test.\n"
" Returns EXIT_FAILURE on any failures.\n"
"\n"
" -test_hdr_4x4/-test_hdr_6x6/-test_hdr_6x6i: Run automated UASTC HDR encoding\n"
" and transcoding tests. Returns EXIT_FAILURE on any failures.\n"
"\n"
" -test_xuastc: Run an automated XUASTC LDR encoding and transcoding test.\n"
" Returns EXIT_FAILURE on any failures.\n"
"\n"
" -test_codecs [codec]: Sweep all LDR+HDR codecs across quality 10/25/50/75/100\n"
" and effort 0/3/6, comparing size and RGB/RGBA (LDR) or RGB (HDR) PSNRs vs the\n"
" golden table in basisu_tool_test_codecs.inl. Optional codec name filter, e.g.\n"
" -test_codecs ETC1S | XUASTC | ASTC | XUBC7 | HDR. Defaults test dir to\n"
" \"test_files\". Returns EXIT_FAILURE on any failures.\n"
"\n"
" -test_codecs_gen [outfile.inl] [codec]: (Re)generate the golden table for\n"
" -test_codecs by running the same sweep and writing the measured results.\n"
" Defaults to basisu_tool_test_codecs.inl. Use after a codec changes.\n"
"\n"
" -test_dir: Optional directory of test files. Defaults to \"../test_files\".\n"
"\n"
" -y_flip: Flip input images vertically before compression\n"
"\n"
" -normal_map: Tunes codec parameters for better quality on normal maps (linear\n"
" colorspace metrics, linear mipmap filtering, no selector RDO, no sRGB)\n"
"\n"
" -photo: Tune for photographic content (the codec defaults): sRGB metrics,\n"
" endpoint+selector RDO on, sRGB channel weights, sharpening off, deblock\n"
" largest blocks. Opposite of -normal_map/-texture.\n"
"\n"
" -no_alpha: Always output non-alpha basis files, even if one or more inputs has\n"
" alpha\n"
"\n"
" -force_alpha: Always output alpha basis files, even if no inputs has alpha\n"
"\n"
" -separate_rg_to_color_alpha: Separate input R and G channels to RGB and A (for\n"
" tangent space XY normal maps)\n"
"\n"
" -swizzle rgba: Specify swizzle for the 4 input color channels using r, g, b\n"
" and a (the -separate_rg_to_color_alpha flag is equivalent to rrrg)\n"
"\n"
" -renorm: Renormalize each input image before any further\n"
" processing/compression\n"
"\n"
" -no_multithreading: Disable multithreading\n"
"\n"
" -max_threads X: Use at most X threads total when multithreading is enabled\n"
" (this includes the main thread)\n"
"\n"
" -wasi_threads: Set number of threads to use in WASI threading builds\n"
" (default=8, only used in WASI threading builds)\n"
"\n"
" -no_ktx (alias -no_dds): When unpacking, skip the transcoded GPU files (the\n"
" .ktx, and .dds for BC1-7) and write only the decoded PNGs (faster, fewer\n"
" files). The two names are identical -- both gate the same .ktx+.dds output.\n"
"\n"
" -ktx_only (alias -dds_only): When unpacking, write only the transcoded GPU\n"
" files (.ktx, plus .dds for BC1-7) and skip the decoded PNGs. Note not every\n"
" format yields a .dds -- only BC1-7 do; the rest are .ktx-only.\n"
"\n"
" -write_out: Write 3dfx OUT files when unpacking FXT1 textures\n"
"\n"
" -format_only: Only unpack the specified format, by its numeric code.\n"
"\n"
" -etc1_only: Only unpack to ETC1, skipping the other texture formats\n"
" during -unpack\n"
"\n"
" -disable_hierarchical_endpoint_codebooks: Disable hierarchical endpoint\n"
" codebook usage, slower but higher quality on some compression levels\n"
"\n"
" -compare_ssim: Compute and display SSIM of image comparison (slow)\n"
"\n"
" -compare_plot: Display histogram plots in -compare mode\n"
"\n"
" -bench: UASTC benchmark mode, for development only\n"
"\n"
" -resample X Y: Resample all input textures to XxY pixels using a box filter\n"
"\n"
" -resample_factor X: Resample all input textures by scale factor X using a box\n"
" filter\n"
"\n"
" -no_sse: Forbid all SSE instruction set usage\n"
"\n"
" -validate_etc1s: Validate internal ETC1S compressor's data structures during\n"
" compression (slower, intended for development).\n"
"\n"
" -ktx2_animdata_duration X: Set KTX2animData duration field to integer value X\n"
" (only valid/useful for -tex_type video, default is 1)\n"
"\n"
" -ktx2_animdata_timescale X: Set KTX2animData timescale field to integer value\n"
" X (only valid/useful for -tex_type video, default is 15)\n"
"\n"
" -ktx2_animdata_loopcount X: Set KTX2animData loopcount field to integer value\n"
" X (only valid/useful for -tex_type video, default is 0)\n"
"\n"
" -framerate X: Set framerate in .basis header to X/frames sec.\n"
"\n"
" -ktx2_no_zstandard: Don't compress UASTC texture data using Zstandard -- store\n"
" it uncompressed instead.\n"
"\n"
" -ktx2_zstandard_level X: Set ZStandard compression level to X (see Zstandard\n"
" documentation, default level is 6)\n"
"\n"
" -tonemap_dither: Dither tonemapper's 8-bit/component output by adding a small\n"
" amount of white noise, only used with -tonemap mode\n"
"\n"
"--- Mipmap Generator Options:\n"
"\n"
"By default, SDR textures will be converted from sRGB to linear light before\n"
"mipmap filtering, then back to sRGB (for the RGB color channels) unless -linear\n"
"is specified. You can override this behavior with -mip_srgb/-mip_linear.\n"
"\n"
" -mipmap: Generate mipmaps for each source image\n"
"\n"
" -mip_srgb: Convert image to linear before filtering, then back to sRGB.\n"
" (This is set automatically by default, unless you override it.)\n"
"\n"
" -mip_linear: Keep image in linear light during mipmap filtering (i.e. do not\n"
" convert to/from sRGB for filtering purposes). (This is set automatically by\n"
" default, unless you override it.)\n"
"\n"
" -mip_scale X: Set mipmap filter kernel's scale, lower=sharper, higher=more\n"
" blurry, default is 1.0 (quite conservative).\n"
"\n"
" -mip_filter X: Set mipmap filter kernel, default is kaiser. Supported filters:\n"
" box, tent, bell, b-spline, mitchell, blackman, lanczos3, lanczos4, lanczos6,\n"
" lanczos12, kaiser, gaussian, catmullrom, quadratic_interp, quadratic_approx,\n"
" quadratic_mix\n"
"\n"
" -mip_renorm: Renormalize normal map to unit length vectors after filtering\n"
"\n"
" -mip_clamp: Use clamp addressing on borders, instead of wrapping\n"
"\n"
" -mip_fast: Use faster mipmap generation (resample from previous mip, not\n"
" always first/largest mip level). The default.\n"
"\n"
" -mip_slow: Always resample each mipmap level starting from the largest mipmap.\n"
" Higher quality, but slower. Opposite of -mip_fast. \n"
"\n"
" -mip_smallest X: Set smallest pixel dimension for generated mipmaps, default\n"
" is 1 pixel \n"
"\n"
"--- Transcoding Options (used while unpacking, validating after compression):\n"
"\n"
"These settings control the \"decode flags\" used while transcoding:\n"
"\n"
" -higher_quality_transcoding: Enable higher quality, but slower, transcoding\n"
"\n"
" -transcode_no_deblocking: Always disable deblocking filter on all block\n"
" sizes (XUASTC/ASTC LDR 4x4-12x12 only). Alias:\n"
" -transcode_disable_deblocking. By default only sizes >= 10x8 are deblocked\n"
" while transcoding. (No CPU deblocking ever occurs when transcoding to ASTC:\n"
" only when transcoding ASTC to another formats.)\n"
"\n"
" -transcode_force_deblocking: Always use deblocking filter, even for block\n"
" sizes smaller than 10x8 (XUASTC/ASTC LDR 4x4-12x12 only).\n"
"\n"
" -no_etc1s_chroma_filtering: Disable adaptive ETC1S transcode chroma filter,\n"
" for faster transcoding to BC7.\n"
"\n"
" -fast_xuastc_ldr_bc7_transcoding: Use much faster, but lower quality, XUASTC\n"
" LDR 4x4/6x6/8x6 direct BC7 transcoders (the default)\n"
"\n"
" -no_fast_xuastc_ldr_bc7_transcoding: Disable much faster, but slightly lower\n"
" quality, XUASTC LDR 4x4/6x6/8x6 direct BC7 transcoders\n"
"\n"
"--- Low-Level ETC1S backend endpoint/selector RDO codec options:\n"
"\n"
" -no_selector_rdo: Disable backend's selector rate distortion optimizations\n"
" (slightly faster, less noisy output, but lower quality per output bit)\n"
"\n"
" -selector_rdo_thresh X: Set selector RDO quality threshold, default is 1.25,\n"
" lower is higher quality but less quality per output bit (try 1.0-3.0)\n"
"\n"
" -no_endpoint_rdo: Disable backend's endpoint rate distortion optimizations\n"
" (slightly faster, less noisy output, but lower quality per output bit)\n"
"\n"
" -endpoint_rdo_thresh X: Set endpoint RDO quality threshold, default is 1.5,\n"
" lower is higher quality but less quality per output bit (try 1.0-3.0)\n"
"\n"
"--- Set various low-level fields in the Basis file header:\n"
"\n"
" -userdata0 X: Set 32-bit userdata0 field in Basis file header to X (X is a\n"
" signed 32-bit int)\n"
"\n"
" -userdata1 X: Set 32-bit userdata1 field in Basis file header to X (X is a\n"
" signed 32-bit int)\n"
"\n"
"--- Example LDR ETC1S/UASTC LDR 4x4 command lines:\n"
"\n"
" - basisu x.png : Compress sRGB image x.png to x.ktx2 using default settings\n"
" (multiple filenames OK, use -tex_array if you want a tex array vs. multiple\n"
" output files)\n"
"\n"
" - basisu -basis x.qoi : Compress sRGB image x.qoi to x.basis (supports 24-bit\n"
" or 32-bit .QOI files)\n"
"\n"
" - basisu x.ktx2 : Unpack x.ktx2 to PNG/KTX files (multiple filenames OK)\n"
"\n"
" - basisu x.basis : Unpack x.basis to PNG/KTX files (multiple filenames OK)\n"
"\n"
" - basisu -uastc x.png -uastc_rdo_l 2.0 -ktx2 -stats : Compress to a\n"
" UASTC .KTX2 file with RDO (rate distortion optimization) to reduce .KTX2\n"
" compressed file size\n"
"\n"
" - basisu -file x.png -mipmap -y_flip : Compress a mipmapped x.ktx2 file from\n"
" an sRGB image named x.png, Y flip each source image\n"
"\n"
" - basisu -validate -file x.basis : Validate x.basis (check header, check file\n"
" CRC's, attempt to transcode all slices)\n"
"\n"
" - basisu -unpack -file x.basis : Validates, transcodes and unpacks x.basis to\n"
" mipmapped .KTX and RGB/A .PNG files (transcodes to all supported GPU texture\n"
" formats)\n"
"\n"
" - basisu -q 255 -file x.png -mipmap -debug -stats : Compress sRGB x.png to\n"
" x.ktx2 at quality level 255 with compressor debug output/statistics\n"
"\n"
" - basisu -linear -max_endpoints 16128 -max_selectors 16128 -file x.png :\n"
" Compress non-sRGB x.png to x.ktx2 using the largest supported manually\n"
" specified codebook sizes\n"
"\n"
" - basisu -basis -comp_level 2 -max_selectors 8192 -max_endpoints\n"
" 8192 -tex_type video -framerate 20 -multifile_printf\n"
" \"x%02u.png\" -multifile_first 1 -multifile_num 20 : Compress a 20 sRGB source\n"
" image video sequence (x01.png, x02.png, x03.png, etc.) to x01.basis\n"
"\n"
"--- Example UASTC HDR 4x4 command lines:\n"
"\n"
" - basisu x.exr : Compress a HDR .EXR (or .HDR) image to a UASTC HDR 4x4 .KTX2\n"
" file. LDR/SDR images will be upconverted to linear light HDR before\n"
" compression. See HDR upconversion options, above.\n"
"\n"
" - basisu -hdr_4x4 x.exr : Compress a HDR .EXR image to a UASTC HDR 4x4 .KTX2\n"
" file.\n"
"\n"
" - basisu x.hdr -uastc_level 0 : Compress a HDR .hdr image to a UASTC HDR\n"
" 4x4 .KTX2 file, fastest encoding but lowest quality\n"
"\n"
" - basisu -hdr x.png : Compress a LDR .PNG image to UASTC HDR 4x4 (image is\n"
" converted from sRGB to linear light first, use -hdr_ldr_no_srgb_to_linear to\n"
" disable)\n"
"\n"
" - basisu x.hdr -uastc_level 3 : Compress a HDR .hdr image to UASTC HDR 4x4 at\n"
" higher quality (-uastc_level 4 is highest quality, but very slow encoding)\n"
"\n"
" - basisu x.hdr -uastc_level 3 -mipmap -basis -stats -debug -debug_images :\n"
" Compress a HDR .hdr image to UASTC HDR 4x4, .basis output file, at higher\n"
" quality, generate mipmaps, output statistics and debug information, and write\n"
" tone mapped debug images\n"
"\n"
" - basisu x.hdr -stats -hdr_favor_astc -hdr_uber_mode -uastc_level 4 : Highest\n"
" achievable ASTC HDR 4x4 quality (very slow encoding, BC6H quality is traded\n"
" off)\n"
"\n"
"--- Example RDO ASTC/UASTC HDR 6x6 command lines:\n"
"\n"
" - basisu -hdr_6x6 x.exr : Compress a HDR .EXR (or .HDR) image to a UASTC HDR\n"
" 6x6 .KTX2 file. LDR/SDR images will be upconverted to linear light HDR before\n"
" compression. See HDR upconversion options, above.\n"
"\n"
" - basisu -lambda 1000 -hdr_6x6 x.exr : Compress a HDR .EXR (or .HDR) image to\n"
" a UASTC HDR 6x6 .KTX2 file with rate-distortion optimization (RDO), at lambda\n"
" level 1000.\n"
"\n"
" - basisu -hdr_6x6i x.exr : Compress a HDR .EXR image to a compressed\n"
" intermediate format UASTC HDR 6x6 .KTX2 file.\n"
"\n"
" - basisu -lambda 1000 -hdr_6x6i x.exr : Compress a HDR .EXR image to a\n"
" compressed intermediate format UASTC HDR 6x6 .KTX2 file with rate-distortion\n"
" optimization (RDO), at lambda level 1000.\n"
"\n"
"--- Example ASTC/XUASTC LDR 4x4-12x12 command lines:\n"
"\n"
" - basisu -ldr_6x6i -quality 75 -xuastc_arith test.png : Compress test.png\n"
" to XUASTC LDR 6x6 using weight grid DCT with setting 75 and the arith\n"
" profile for higher compression.\n"
"\n"
" - basisu -ldr_4x4 -effort 5 test.png : Compress test.png to ASTC LDR 4x4\n"
"\n"
" - basisu -mipmap -ldr_10x5i test.png : Compress test.png to XUASTC LDR 10x5,\n"
" using lossless ZStd supercompression, with mipmaps\n"
"\n"
"--- ETC1S Texture Video Notes: Use -comp_level 2 or higher for better codebook\n"
"generation, specify very large codebooks using -max_endpoints\n"
"and -max_selectors, and reduce the default endpoint RDO threshold\n"
"(-endpoint_rdo_thresh) to around 1.25. Videos may have mipmaps and alpha\n"
"channels. Videos must always be played back by the transcoder in first to last\n"
"image order. Video files currently use I-Frames on the first image, and\n"
"P-Frames using conditional replenishment on subsequent frames.\n"
"\n"
"--- Low-level ETC1S compression (Effort) Level (-comp_level X) Details \n"
"\n"
"This setting controls the ETC1S speed vs. quality tradeoff. (Use -q to control\n"
"the quality vs. compressed size tradeoff.):\n"
"\n"
" - Level 0: Fastest, but has marginal quality and can be brittle on complex\n"
"images. Avg. Y dB: 35.45\n"
"\n"
" - Level 1: Hierarchical codebook searching, faster ETC1S encoding. 36.87 dB,\n"
"~1.4x slower vs. level 0. (This is the default setting.)\n"
"\n"
" - Level 2: Use this or higher for video. Hierarchical codebook searching.\n"
"36.87 dB, ~1.4x slower vs. level 0. (This is the v1.12's default setting.)\n"
"\n"
" - Level 3: Full codebook searching. 37.13 dB, ~1.8x slower vs. level 0.\n"
"(Equivalent to the initial release's default settings.)\n"
"\n"
" - Level 4: Hierarchical codebook searching, codebook k-means iterations. 37.15\n"
"dB, ~4x slower vs. level 0\n"
"\n"
" - Level 5: Full codebook searching, codebook k-means iterations. 37.41 dB,\n"
"~5.5x slower vs. level 0.\n"
"\n"
" - Level 6: Full codebook searching, twice as many codebook k-means iterations,\n"
"best ETC1 endpoint opt. 37.43 dB, ~12x slower vs. level 0"