astc_encoder.enum

  1"""The enumeration classes for the ASTC encoder."""
  2
  3from enum import IntEnum, IntFlag
  4
  5
  6class ASTCProfile(IntEnum):
  7    """A codec color profile.
  8
  9    Attributes
 10    ----------
 11    LDR_SRGB : int = 0
 12        The LDR sRGB color profile.
 13    LDR : int = 1
 14        The LDR linear color profile.
 15    HDR_RGB_LDR_A : int = 2
 16        The HDR RGB with LDR alpha color profile.
 17    HDR : int = 3
 18        The HDR RGB color profile.
 19    """
 20
 21    LDR_SRGB = 0
 22    LDR = 1
 23    HDR_RGB_LDR_A = 2
 24    HDR = 3
 25
 26
 27class ASTCQualityPreset(IntEnum):
 28    """The quality presets.
 29
 30    These values are just presets, the user can set the quality to any value between 0 and 100.
 31
 32    Attributes
 33    ----------
 34    FASTEST : int = 0
 35        The fastest, lowest quality, search preset.
 36    FAST : int = 10
 37        The fast search preset.
 38    MEDIUM : int = 60
 39        The medium quality search preset.
 40    THOROUGH : int = 98
 41        The thorough quality search preset.
 42    VERYTHOROUGH : int = 99
 43        The very thorough quality search preset.
 44    EXHAUSTIVE : int = 100
 45        The exhaustive, highest quality, search preset.
 46    """
 47
 48    FASTEST = 0
 49    FAST = 10
 50    MEDIUM = 60
 51    THOROUGH = 98
 52    VERYTHOROUGH = 99
 53    EXHAUSTIVE = 100
 54
 55
 56class ASTCConfigFlags(IntFlag):
 57    """The configuration flags.
 58
 59    Attributes
 60    ----------
 61    MAP_NORMAL : int = 1 << 0
 62        Enable normal map compression.
 63
 64        Input data will be treated a two component normal map,
 65        storing X and Y, and the codec will optimize for angular error rather than simple linear PSNR.
 66        In this mode the input swizzle should be e.g.
 67        - rrrg (the default ordering for ASTC normals on the command line)
 68        - gggr (the ordering used by BC5n)
 69
 70    USE_DECODE_UNORM8 : int = 1 << 1
 71        Enable compression heuristics that assume use of decode_unorm8 decode mode.
 72
 73        The decode_unorm8 decode mode rounds differently to the decode_fp16 decode mode,
 74        so enabling this flag during compression will allow the compressor to use
 75        the correct rounding when selecting encodings.
 76        This will improve the compressed image quality if your application is using the decode_unorm8 decode mode,
 77        but will reduce image quality if using decode_fp16.
 78        Note that LDR_SRGB images will always use decode_unorm8 for the RGB channels,
 79        irrespective of this setting.
 80
 81    USE_APLHA_WEIGHT : int = 1 << 2
 82        Enable alpha weighting.
 83
 84        The input alpha value is used for transparency, so errors in the RGB components are weighted by
 85        the transparency level. This allows the codec to more accurately encode the alpha value in areas
 86        where the color value is less significant.
 87    USE_PERCEPTUAL : int = 1 << 3
 88        Enable perceptual error metrics.
 89
 90        This mode enables perceptual compression mode, which will optimize for perceptual error rather
 91        than best PSNR. Only some input modes support perceptual error metrics.
 92
 93    SELF_DECOMPRESS_ONLY : int = 1 << 4
 94        Create a self-decompression context.
 95
 96        This mode configures the compressor so that it is only guaranteed to be able to decompress images
 97        that were actually created using the current context.
 98        This is the common case for compression use cases, and setting this flag enables additional optimizations,
 99        but does mean that the context cannot reliably decompress arbitrary ASTC images.
100
101    MAP_RGBM : int = 1 << 6
102        Enable RGBM map compression.
103
104        Input data will be treated as HDR data that has been stored in an LDR RGBM-encoded wrapper format.
105        Data must be preprocessed by the user to be in LDR RGBM format before calling the compression function,
106        this flag is only used to control the use of RGBM-specific heuristics and error metrics.
107
108        **IMPORTANT**:
109
110        The ASTC format is prone to bad failure modes with unconstrained RGBM data;
111        very small M values can round to zero due to quantization and result in black or white pixels.
112        It is highly recommended that the minimum value of M used in the encoding is kept above a lower threshold (try 16 or 32).
113        Applying this threshold reduces the number of very dark colors that can be represented,
114        but is still higher precision than 8-bit LDR.
115
116        When this flag is set the value of ``c rgbm_m_scale`` in the context must be set to the RGBM scale factor used during reconstruction.
117        This defaults to 5 when in RGBM mode.
118        It is recommended that the value of ``c cw_a_weight`` is set to twice the value of the multiplier scale,
119        ensuring that the M value is accurately encoded.
120        This defaults to 10 when in RGBM mode, matching the default scale factor.
121    """
122
123    MAP_NORMAL = 1 << 0
124    USE_DECODE_UNORM8 = 1 << 1
125    USE_APLHA_WEIGHT = 1 << 2
126    USE_PERCEPTUAL = 1 << 3
127    DECOMPRESS_ONLY = 1 << 4
128    SELF_DECOMPRESS_ONLY = 1 << 5
129    MAP_RGBM = 1 << 6
130
131
132class ASTCType(IntEnum):
133    """A texel component data format.
134
135    Attributes
136    ----------
137    U8 : int = 0
138        Unorm 8-bit data per component.
139    F16 : int = 1
140        16-bit float per component.
141    F32 : int = 2
142        32-bit float per component.
143    """
144
145    U8 = 0
146    F16 = 1
147    F32 = 2
148
149
150class ASTCSwizzleComponentSelector(IntEnum):
151    """A codec component swizzle selector.
152
153    Attributes
154    ----------
155    R : int = 0
156        Select the red component.
157    G : int = 1
158        Select the green component.
159    B : int = 2
160        Select the blue component.
161    A : int = 3
162        Select the alpha component.
163    ZERO : int = 4
164        Use a constant zero component.
165    ONE : int = 5
166        Use a constant one component.
167    Z : int = 6
168        Use a reconstructed normal vector Z component.
169    """
170
171    R = 0
172    G = 1
173    B = 2
174    A = 3
175    ZERO = 4
176    ONE = 5
177    Z = 6
178
179
180__all__ = (
181    "ASTCProfile",
182    "ASTCQualityPreset",
183    "ASTCConfigFlags",
184    "ASTCType",
185    "ASTCSwizzleComponentSelector",
186)