// 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 file to one or more .KTX, \n"
"  .DDS, .PNG, .ASTC, etc. files.\n"
"\n"
" -info: Display high-level information about a .basis/.KTX2 file\n"
" \n"
" -validate: Validate and display information about a .basis/.KTX2 file\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"
" -tonemap: Tonemap an HDR or EXR image to PNG at multiple exposures, use -file\n"
"  to specify filename\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"
"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"
"or .KTX2 extension this tool defaults to unpack mode.\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 source files: Mipmapped or plain 2D textures (but not cubemaps) are\n"
"supported. Only uncompressed 32-bit RGBA/BGRA, half float RGBA, or float\n"
"RGBA .DDS files are supported. In -tex_array mode, if a .DDS file is specified,\n"
"all source files must be in .DDS format.\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"
"--- 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 or -verbose: Enable codec debug print to stdout (slightly slower).\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"
" -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"
"--- 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"
" -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. Defaults are\n"
"  1,1,1,1. Useful to favor 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"
"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_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"
" -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: Disable KTX writing when unpacking (faster, less output files)\n"
"\n"
" -ktx_only: Only write KTX files when unpacking (faster, less output files)\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"
" -no_deblocking: Always disable adaptive deblocking filter on all block sizes\n"
"  (XUASTC/ASTC LDR 4x4-12x12 only). By default only block sizes >8x6 are\n"
"  deblocked while transcoding. (No deblocking ever occurs when transcoding to\n"
"  ASTC: only when re-encoding ASTC to another format, to lower artifacts.)\n"
"\n"
" -force_deblocking: Always use adaptive deblocking filter, even for block sizes\n"
"  <= 8x6 (XUASTC/ASTC LDR 4x4-12x12 only)\n"
"\n"
" -stronger_deblocking: Use stronger adaptive deblocking filtering (XUASTC/ASTC\n"
"  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.basis 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 to XUASTC\n"
"  LDR 6x6 using weight grid DCT with setting 75 and the arith profile for\n"
"  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"