Provided by: astcenc_4.1.0+ds-1_amd64 bug

NAME

       astcenc - compress or decompress images using the ASTC format

SYNOPSIS

       astcenc [-cl|-cs|-ch|-cH] <in> <out> <blocksize> <preset> [options]

       astcenc [-dl|-ds|-dh|-dH] <in> <out> <blocksize> <preset> [options]

       astcenc [-tl|-ts|-th|-tH] <in> <out> <blocksize> <preset> [options]

DESCRIPTION

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

       •   All color profiles (LDR linear, LDR sRGB, and HDR)

       •   All 2D block sizes (4x4 through to 12x12)

       •   All 3D block sizes (3x3x3 through to 6x6x6)

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

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

COMPRESSION

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

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

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

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

       Supported 2D block sizes are:

       •   4x4: 8.00 bpp

       •   5x4: 6.40 bpp

       •   5x5: 5.12 bpp

       •   6x5: 4.27 bpp

       •   6x6: 3.56 bpp

       •   8x5: 3.20 bpp

       •   8x6: 2.67 bpp

       •   10x5: 2.56 bpp

       •   10x6: 2.13 bpp

       •   8x8: 2.00 bpp

       •   10x8: 1.60 bpp

       •   10x10: 1.28 bpp

       •   12x10: 1.07 bpp

       •   12x12: 0.89 bpp

       Supported 3D block sizes are:

       •   3x3x3: 4.74 bpp

       •   4x3x3: 3.56 bpp

       •   4x4x3: 2.67 bpp

       •   4x4x4: 2.00 bpp

       •   5x4x4: 1.60 bpp

       •   5x5x4: 1.28 bpp

       •   5x5x5: 1.02 bpp

       •   6x5x5: 0.85 bpp

       •   6x6x5: 0.71 bpp

       •   6x6x6: 0.59 bpp

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

              -fastest
              -fast
              -medium
              -thorough
              -exhaustive

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

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

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

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

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

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

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

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

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

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

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

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

COMPRESSION TIPS & TRICKS

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

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

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

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

ADVANCED COMPRESSION

   Error weighting options
       These options provide low-level control of the codec error  metric  computation,  used  to
       determine what good compression looks like.

       -v <radius> <power> <base> <mean> <stdev> <mix>
              Compute  the  per-texel  relative  error  weighting  for  the RGB color channels as
              follows:

              weight = 1 / (<base> + <mean> * <mean> + <stdev> * <stdev>)

              The <radius> argument specifies the texel radius of the neighborhood over which the
              average and standard deviation are computed.

       The  <mix>  parameter  is  used  to control the degree of mixing of the average and stddev
       error components across the color  channels.  Setting  this  parameter  to  0  causes  the
       computation  to  be  done  completely  separately  for each color channel; setting it to 1
       causes the results from the RGB channels to be combined and applied to all three together.
       Intermediate values between these two extremes do a linear mix of the two error values.

       The  <power>  argument  is  a  power  used  to raise the values of the input texels before
       computing average and standard deviation; e.g. a power of 0.5 causes the codec to take the
       square root of every input texel value.

       -va <power> <base> <mean> <stdev>
              Compute  the per-texel relative error weighting for the alpha channel, when used in
              conjunction with -v.  See documentation for -v for parameter documentation.

       -a <radius>
              For textures with alpha channel, scale per-texel weights by the  alpha  value.  The
              alpha  value  chosen  for  scaling  of  any particular texel is taken as an average
              across a neighborhood of the  texel  defined  by  the  <radius>  argument.  Setting
              <radius> to 0 causes only the texel's own alpha to be used.

       -cw <red> <green> <blue> <alpha>
              Assign an additional weight scaling to each color channel, allowing the channels to
              be treated differently in terms of  error  significance.  Set  values  above  1  to
              increase  a  channel's significance, and values below 1 to decrease it. Set to 0 to
              exclude a channel from error computation completely.

       -b <weight>
              Assign an additional weight scaling for  texels  at  compression  block  edges  and
              corners.  Setting  this  to  a  value  above 1 increases the significance of texels
              closer to the edges of a block, and can help to reduce block artifacts.

       -mpsnr <low> <high>
              Set the low and high f-stop values for the mPSNR error  metric.   The  mPSNR  error
              metric only applies to HDR textures.

   Performance-quality tradeoff options
       These   options  provide  low-level  control  of  the  codec  heuristics  that  drive  the
       performance-quality trade off.

       -partitionlimit <number>
              Test only <number> block partitions. Higher numbers give  better  quality,  however
              large  values  give  diminishing returns especially for smaller block sizes. Preset
              defaults are:

              -fastest    :    2
              -fast       :    4
              -medium     :   25
              -thorough   :  100
              -exhaustive : 1024

       -blockmodelimit <number>
              Test only block modes below the <number> usage centile in an empirically determined
              distribution  of block mode frequency.  This option is ineffective for 3D textures.
              Preset defaults are:

              -fastest    :  25
              -fast       :  50
              -medium     :  75
              -thorough   :  95
              -exhaustive : 100

       -refinementlimit <value>
              Iterate only <value> refinement iterations on colors and weights. Minimum value  is
              1. Preset defaults are:

              -fastest    : 1
              -fast       : 1
              -medium     : 2
              -thorough   : 4
              -exhaustive : 4

       -candidatelimit <value>
              Trial only <value> candidate encodings for each block mode:

       -fastest    : 1
              -fast       : 2
              -medium     : 2
              -thorough   : 3
              -exhaustive : 4

       -dblimit <number>
              Stop  compression work on a block as soon as the PSNR of the block, measured in dB,
              exceeds <number>.  This option is ineffective for HDR  textures.  Preset  defaults,
              where N is the number of texels in a block, are:

              -fastest    : MAX(53-19*log10(N),  70-35*log10(N))
              -fast       : MAX(63-19*log10(N),  85-35*log10(N))
              -medium     : MAX(70-19*log10(N),  95-35*log10(N))
              -thorough   : MAX(77-19*log10(N), 105-35*log10(N))
              -exhaustive : 999

       -partitionearlylimit <factor>
              Stop  compression work on a block after only testing blocks with up to two partions
              and one plane of weights, unless the two partition error term  is  lower  than  the
              error term from encoding with one partition by more than the specified factor. This
              option is ineffective for normal maps. Preset defaults are:

              -fastest    :    1.0
              -fast       :    1.0
              -medium     :    1.2
              -thorough   :    2.5
              -exhaustive : 1000.0

       -planecorlimit <factor>
              Stop compression after testing only one planes of weights, unless the minimum color
              correlation  factor  between  any pair of color channels is below this factor. This
              option is ineffective for normal maps. Preset defaults are:

              -fastest    : 0.50
              -fast       : 0.50
              -medium     : 0.75
              -thorough   : 0.95
              -exhaustive : 0.99

   Other options
       -esw <swizzle>
              Swizzle the color components before compression. The swizzle is specified  using  a
              4-character string, which defines the output format ordering. The characters may be
              taken from the set [rgba01], selecting either input color  channels  or  a  literal
              zero  or  one.  For  example to swap the RG channels, and replace alpha with 1, the
              swizzle 'grb1' should be used.

              The input swizzle takes place before  any  compression,  and  all  error  weighting
              applied using the -cw option is applied to the post-swizzle channel ordering.

              By  default  all  4  post-swizzle channels are included in the error metrics during
              compression. When using -esw to map two channel data to the L+A endpoint (e.g. -esw
              rrrg)  the  luminance  data stored in the rgb channels will be weighted three times
              more strongly than the alpha channel. This can be corrected using the -cw option to
              zero the weights of unused channels; e.g. using -cw 1 0 0 1.

       -dsw <swizzle>
              Swizzle  the  color  components after decompression. The swizzle is specified using
              the same method as the -esw option, with support for an additional  "z"  character.
              This is used to specify that the compressed data stores an X+Y normal map, and that
              the Z output channel should be reconstructed from the two channels  stored  in  the
              data.  For  the  typical  ASTC  normal  encoding,  which uses an 'rrrg' compression
              swizzle, you should specify an 'raz1' swizzle for decompression.

       -yflip Flip the image in the vertical axis prior to compression and  after  decompression.
              Note  that  using this option in a test mode (-t*) will have no effect as the image
              will be flipped twice.

       -j <threads>
              Explicitly specify the number of compression/decompression theads  to  use  in  the
              codec.  If  not  specified,  the  codec will use one thread per CPU detected in the
              system.

       -silent
              Suppresses all non-essential diagnostic output from the codec.  Error messages will
              always  be  printed, as will mandatory outputs for the selected operation mode. For
              example, the test mode will always output image  quality  metrics  and  compression
              time but will suppress all other output.

DECOMPRESSION

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

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

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

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

TEST

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

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

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

COMPRESSION FILE FORMATS

       The following formats are supported as compression inputs:

               LDR Formats:

               •      BMP (*.bmp)

               •      PNG (*.png)

               •      Targa (*.tga)

               •      JPEG (*.jpg)

               HDR Formats:

               •      OpenEXR (*.exr)

               •      Radiance HDR (*.hdr)

               Container Formats:

               •      Khronos Texture KTX (*.ktx)

               •      DirectDraw Surface DDS (*.dds)

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

       •      Texture topology must be 2D, 2D-array, 3D, or cube-map. Note that 2D-array textures
              are treated as 3D block input.

       •      Texel format must be R, RG, RGB, BGR, RGBA, BGRA, L, or LA.

       •      Only the first mipmap in the file will be read.

       The following formats are supported as compression outputs:

       •      ASTC (*.astc)

       •      Khronos Texture KTX (*.ktx)

DECOMPRESSION FILE FORMATS

       The following formats are supported as decompression inputs:

       •      ASTC (*.astc)

       •      Khronos Texture KTX (*.ktx)

       The following formats are supported as decompression outputs:

               LDR Formats:

               •      BMP (*.bmp)

               •      PNG (*.png)

               •      Targa (*.tga)

               HDR Formats:

               •      OpenEXR (*.exr)

               •      Radiance HDR (*.hdr)

               Container Formats:

               •      Khronos Texture KTX (*.ktx)

               •      DirectDraw Surface DDS (*.dds)

                                                                                       ASTCENC(1)