code.vuplus.com Git - vuplus_xbmc/blob - lib/libsquish/squish.h

   1 /* -----------------------------------------------------------------------------
   2
   3         Copyright (c) 2006 Simon Brown                          si@sjbrown.co.uk
   4
   5         Permission is hereby granted, free of charge, to any person obtaining
   6         a copy of this software and associated documentation files (the
   7         "Software"), to deal in the Software without restriction, including
   8         without limitation the rights to use, copy, modify, merge, publish,
   9         distribute, sublicense, and/or sell copies of the Software, and to
  10         permit persons to whom the Software is furnished to do so, subject to
  11         the following conditions:
  12
  13         The above copyright notice and this permission notice shall be included
  14         in all copies or substantial portions of the Software.
  15
  16         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17         OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18         MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19         IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  20         CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  21         TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  22         SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24    -------------------------------------------------------------------------- */
  25
  26 #ifndef SQUISH_H
  27 #define SQUISH_H
  28
  29 //! All squish API functions live in this namespace.
  30 namespace squish {
  31
  32 // -----------------------------------------------------------------------------
  33
  34 //! Typedef a quantity that is a single unsigned byte.
  35 typedef unsigned char u8;
  36
  37 // -----------------------------------------------------------------------------
  38
  39 enum
  40 {
  41         //! Use DXT1 compression.
  42         kDxt1 = ( 1 << 0 ),
  43
  44         //! Use DXT3 compression.
  45         kDxt3 = ( 1 << 1 ),
  46
  47         //! Use DXT5 compression.
  48         kDxt5 = ( 1 << 2 ),
  49
  50         //! Use a very slow but very high quality colour compressor.
  51         kColourIterativeClusterFit = ( 1 << 8 ),
  52
  53         //! Use a slow but high quality colour compressor (the default).
  54         kColourClusterFit = ( 1 << 3 ),
  55
  56         //! Use a fast but low quality colour compressor.
  57         kColourRangeFit = ( 1 << 4 ),
  58
  59         //! Weight the colour by alpha during cluster fit (disabled by default).
  60         kWeightColourByAlpha = ( 1 << 7 ),
  61
  62         //! Source is BGRA rather than RGBA
  63         kSourceBGRA = ( 1 << 9 ),
  64 };
  65
  66 // -----------------------------------------------------------------------------
  67
  68 /*! @brief Compresses a 4x4 block of pixels.
  69
  70         @param rgba             The rgba values of the 16 source pixels.
  71         @param mask             The valid pixel mask.
  72         @param block    Storage for the compressed DXT block.
  73         @param flags    Compression flags.
  74         @param metric   An optional perceptual metric.
  75
  76         The source pixels should be presented as a contiguous array of 16 rgba
  77         values, with each component as 1 byte each. In memory this should be:
  78
  79                 { r1, g1, b1, a1, .... , r16, g16, b16, a16 }
  80
  81         The mask parameter enables only certain pixels within the block. The lowest
  82         bit enables the first pixel and so on up to the 16th bit. Bits beyond the
  83         16th bit are ignored. Pixels that are not enabled are allowed to take
  84         arbitrary colours in the output block. An example of how this can be used
  85         is in the CompressImage function to disable pixels outside the bounds of
  86         the image when the width or height is not divisible by 4.
  87
  88         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
  89         however, DXT1 will be used by default if none is specified. When using DXT1
  90         compression, 8 bytes of storage are required for the compressed DXT block.
  91         DXT3 and DXT5 compression require 16 bytes of storage per block.
  92
  93         The flags parameter can also specify a preferred colour compressor to use
  94         when fitting the RGB components of the data. Possible colour compressors
  95         are: kColourClusterFit (the default), kColourRangeFit (very fast, low
  96         quality) or kColourIterativeClusterFit (slowest, best quality).
  97
  98         When using kColourClusterFit or kColourIterativeClusterFit, an additional
  99         flag can be specified to weight the importance of each pixel by its alpha
 100         value. For images that are rendered using alpha blending, this can
 101         significantly increase the perceived quality.
 102
 103         The metric parameter can be used to weight the relative importance of each
 104         colour channel, or pass NULL to use the default uniform weight of
 105         { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that
 106         allowed either uniform or "perceptual" weights with the fixed values
 107         { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a
 108         contiguous array of 3 floats.
 109 */
 110 void CompressMasked( u8 const* rgba, int mask, void* block, int flags, float* metric = 0 );
 111
 112 // -----------------------------------------------------------------------------
 113
 114 /*! @brief Compresses a 4x4 block of pixels.
 115
 116         @param rgba             The rgba values of the 16 source pixels.
 117         @param block    Storage for the compressed DXT block.
 118         @param flags    Compression flags.
 119         @param metric   An optional perceptual metric.
 120
 121         The source pixels should be presented as a contiguous array of 16 rgba
 122         values, with each component as 1 byte each. In memory this should be:
 123
 124                 { r1, g1, b1, a1, .... , r16, g16, b16, a16 }
 125
 126         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 127         however, DXT1 will be used by default if none is specified. When using DXT1
 128         compression, 8 bytes of storage are required for the compressed DXT block.
 129         DXT3 and DXT5 compression require 16 bytes of storage per block.
 130
 131         The flags parameter can also specify a preferred colour compressor to use
 132         when fitting the RGB components of the data. Possible colour compressors
 133         are: kColourClusterFit (the default), kColourRangeFit (very fast, low
 134         quality) or kColourIterativeClusterFit (slowest, best quality).
 135
 136         When using kColourClusterFit or kColourIterativeClusterFit, an additional
 137         flag can be specified to weight the importance of each pixel by its alpha
 138         value. For images that are rendered using alpha blending, this can
 139         significantly increase the perceived quality.
 140
 141         The metric parameter can be used to weight the relative importance of each
 142         colour channel, or pass NULL to use the default uniform weight of
 143         { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that
 144         allowed either uniform or "perceptual" weights with the fixed values
 145         { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a
 146         contiguous array of 3 floats.
 147
 148         This method is an inline that calls CompressMasked with a mask of 0xffff,
 149         provided for compatibility with older versions of squish.
 150 */
 151 inline void Compress( u8 const* rgba, void* block, int flags, float* metric = 0 )
 152 {
 153         CompressMasked( rgba, 0xffff, block, flags, metric );
 154 }
 155
 156 // -----------------------------------------------------------------------------
 157
 158 /*! @brief Decompresses a 4x4 block of pixels.
 159
 160         @param rgba             Storage for the 16 decompressed pixels.
 161         @param block    The compressed DXT block.
 162         @param flags    Compression flags.
 163
 164         The decompressed pixels will be written as a contiguous array of 16 rgba
 165         values, with each component as 1 byte each. In memory this is:
 166
 167                 { r1, g1, b1, a1, .... , r16, g16, b16, a16 }
 168
 169         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 170         however, DXT1 will be used by default if none is specified. All other flags
 171         are ignored.
 172 */
 173 void Decompress( u8* rgba, void const* block, int flags );
 174
 175 // -----------------------------------------------------------------------------
 176
 177 /*! @brief Computes the amount of compressed storage required.
 178
 179         @param width    The width of the image.
 180         @param height   The height of the image.
 181         @param flags    Compression flags.
 182
 183         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 184         however, DXT1 will be used by default if none is specified. All other flags
 185         are ignored.
 186
 187         Most DXT images will be a multiple of 4 in each dimension, but this
 188         function supports arbitrary size images by allowing the outer blocks to
 189         be only partially used.
 190 */
 191 int GetStorageRequirements( int width, int height, int flags );
 192
 193 // -----------------------------------------------------------------------------
 194
 195 /*! @brief Compresses an image in memory.
 196
 197         @param rgba             The pixels of the source.
 198         @param width    The width of the source image.
 199         @param height   The height of the source image.
 200         @param pitch    The pitch of the source image.
 201         @param blocks   Storage for the compressed output.
 202         @param flags    Compression flags.
 203         @param metric   An optional perceptual metric.
 204
 205         The source pixels should be presented as a contiguous array of width*height
 206         rgba values, with each component as 1 byte each. In memory this should be:
 207
 208                 { r1, g1, b1, a1, .... , rn, gn, bn, an } for n = width*height
 209
 210         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 211         however, DXT1 will be used by default if none is specified. When using DXT1
 212         compression, 8 bytes of storage are required for each compressed DXT block.
 213         DXT3 and DXT5 compression require 16 bytes of storage per block.
 214
 215         The flags parameter can also specify a preferred colour compressor to use
 216         when fitting the RGB components of the data. Possible colour compressors
 217         are: kColourClusterFit (the default), kColourRangeFit (very fast, low
 218         quality) or kColourIterativeClusterFit (slowest, best quality).
 219
 220         When using kColourClusterFit or kColourIterativeClusterFit, an additional
 221         flag can be specified to weight the importance of each pixel by its alpha
 222         value. For images that are rendered using alpha blending, this can
 223         significantly increase the perceived quality.
 224
 225         The metric parameter can be used to weight the relative importance of each
 226         colour channel, or pass NULL to use the default uniform weight of
 227         { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that
 228         allowed either uniform or "perceptual" weights with the fixed values
 229         { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a
 230         contiguous array of 3 floats.
 231
 232         Internally this function calls squish::CompressMasked for each block, which
 233         allows for pixels outside the image to take arbitrary values. The function
 234         squish::GetStorageRequirements can be called to compute the amount of memory
 235         to allocate for the compressed output.
 236 */
 237 void CompressImage( u8 const* rgba, int width, int height, void* blocks, int flags, float* metric = 0 );
 238 void CompressImage( u8 const* rgba, int width, int height, int pitch, void* blocks, int flags, float* metric = 0 );
 239
 240 // -----------------------------------------------------------------------------
 241
 242 /*! @brief Decompresses an image in memory.
 243
 244         @param rgba             Storage for the decompressed pixels.
 245         @param width    The width of the source image.
 246         @param height   The height of the source image.
 247         @param pitch    The pitch of the decompressed pixels.
 248         @param blocks   The compressed DXT blocks.
 249         @param flags    Compression flags.
 250
 251         The decompressed pixels will be written as a contiguous array of width*height
 252         16 rgba values, with each component as 1 byte each. In memory this is:
 253
 254                 { r1, g1, b1, a1, .... , rn, gn, bn, an } for n = width*height
 255
 256         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 257         however, DXT1 will be used by default if none is specified. All other flags
 258         are ignored.
 259
 260         Internally this function calls squish::Decompress for each block.
 261 */
 262 void DecompressImage( u8* rgba, int width, int height, void const* blocks, int flags );
 263 void DecompressImage( u8* rgba, int width, int height, int pitch, void const* blocks, int flags );
 264
 265 // -----------------------------------------------------------------------------
 266
 267 /*! @brief Computes MSE of an compressed image in memory.
 268
 269         @param rgba             The original image pixels.
 270         @param width    The width of the source image.
 271         @param height   The height of the source image.
 272         @param pitch    The pitch of the source image.
 273         @param dxt              The compressed dxt blocks
 274         @param flags    Compression flags.
 275         @param colourMSE        The MSE of the colour values.
 276         @param alphaMSE The MSE of the alpha values.
 277
 278         The colour MSE and alpha MSE are computed across all pixels. The colour MSE is
 279         averaged across all rgb values (i.e. colourMSE = sum sum_k ||dxt.k - rgba.k||/3)
 280
 281         The flags parameter should specify either kDxt1, kDxt3 or kDxt5 compression,
 282         however, DXT1 will be used by default if none is specified. All other flags
 283         are ignored.
 284
 285         Internally this function calls squish::Decompress for each block.
 286 */
 287 void ComputeMSE(u8 const *rgba, int width, int height, u8 const *dxt, int flags, double &colourMSE, double &alphaMSE);
 288 void ComputeMSE(u8 const *rgba, int width, int height, int pitch, u8 const *dxt, int flags, double &colourMSE, double &alphaMSE);
 289
 290 // -----------------------------------------------------------------------------
 291
 292 } // namespace squish
 293
 294 #endif // ndef SQUISH_H
 295