src/third_party/libjpeg_turbo/turbojpeg.h

   1 /*
   2  * Copyright (C)2009-2013 D. R. Commander.  All Rights Reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  * - Redistributions of source code must retain the above copyright notice,
   8  *   this list of conditions and the following disclaimer.
   9  * - Redistributions in binary form must reproduce the above copyright notice,
  10  *   this list of conditions and the following disclaimer in the documentation
  11  *   and/or other materials provided with the distribution.
  12  * - Neither the name of the libjpeg-turbo Project nor the names of its
  13  *   contributors may be used to endorse or promote products derived from this
  14  *   software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 #ifndef __TURBOJPEG_H__
  30 #define __TURBOJPEG_H__
  31
  32 #if defined(_WIN32) && defined(DLLDEFINE)
  33 #define DLLEXPORT __declspec(dllexport)
  34 #else
  35 #define DLLEXPORT
  36 #endif
  37 #define DLLCALL
  38
  39
  40 /**
  41  * @addtogroup TurboJPEG
  42  * TurboJPEG API.  This API provides an interface for generating, decoding, and
  43  * transforming planar YUV and JPEG images in memory.
  44  *
  45  * @{
  46  */
  47
  48
  49 /**
  50  * The number of chrominance subsampling options
  51  */
  52 #define TJ_NUMSAMP 5
  53
  54 /**
  55  * Chrominance subsampling options.
  56  * When an image is converted from the RGB to the YCbCr colorspace as part of
  57  * the JPEG compression process, some of the Cb and Cr (chrominance) components
  58  * can be discarded or averaged together to produce a smaller image with little
  59  * perceptible loss of image clarity (the human eye is more sensitive to small
  60  * changes in brightness than small changes in color.)  This is called
  61  * "chrominance subsampling".
  62  * <p>
  63  * NOTE: Technically, the JPEG format uses the YCbCr colorspace, but per the
  64  * convention of the digital video community, the TurboJPEG API uses "YUV" to
  65  * refer to an image format consisting of Y, Cb, and Cr image planes.
  66  */
  67 enum TJSAMP
  68 {
  69   /**
  70    * 4:4:4 chrominance subsampling (no chrominance subsampling).  The JPEG or
  71    * YUV image will contain one chrominance component for every pixel in the
  72    * source image.
  73    */
  74   TJSAMP_444=0,
  75   /**
  76    * 4:2:2 chrominance subsampling.  The JPEG or YUV image will contain one
  77    * chrominance component for every 2x1 block of pixels in the source image.
  78    */
  79   TJSAMP_422,
  80   /**
  81    * 4:2:0 chrominance subsampling.  The JPEG or YUV image will contain one
  82    * chrominance component for every 2x2 block of pixels in the source image.
  83    */
  84   TJSAMP_420,
  85   /**
  86    * Grayscale.  The JPEG or YUV image will contain no chrominance components.
  87    */
  88   TJSAMP_GRAY,
  89   /**
  90    * 4:4:0 chrominance subsampling.  The JPEG or YUV image will contain one
  91    * chrominance component for every 1x2 block of pixels in the source image.
  92    * Note that 4:4:0 subsampling is not fully accelerated in libjpeg-turbo.
  93    */
  94   TJSAMP_440
  95 };
  96
  97 /**
  98  * MCU block width (in pixels) for a given level of chrominance subsampling.
  99  * MCU block sizes:
 100  * - 8x8 for no subsampling or grayscale
 101  * - 16x8 for 4:2:2
 102  * - 8x16 for 4:4:0
 103  * - 16x16 for 4:2:0
 104  */
 105 static const int tjMCUWidth[TJ_NUMSAMP]  = {8, 16, 16, 8, 8};
 106
 107 /**
 108  * MCU block height (in pixels) for a given level of chrominance subsampling.
 109  * MCU block sizes:
 110  * - 8x8 for no subsampling or grayscale
 111  * - 16x8 for 4:2:2
 112  * - 8x16 for 4:4:0
 113  * - 16x16 for 4:2:0
 114  */
 115 static const int tjMCUHeight[TJ_NUMSAMP] = {8, 8, 16, 8, 16};
 116
 117
 118 /**
 119  * The number of pixel formats
 120  */
 121 #define TJ_NUMPF 11
 122
 123 /**
 124  * Pixel formats
 125  */
 126 enum TJPF
 127 {
 128   /**
 129    * RGB pixel format.  The red, green, and blue components in the image are
 130    * stored in 3-byte pixels in the order R, G, B from lowest to highest byte
 131    * address within each pixel.
 132    */
 133   TJPF_RGB=0,
 134   /**
 135    * BGR pixel format.  The red, green, and blue components in the image are
 136    * stored in 3-byte pixels in the order B, G, R from lowest to highest byte
 137    * address within each pixel.
 138    */
 139   TJPF_BGR,
 140   /**
 141    * RGBX pixel format.  The red, green, and blue components in the image are
 142    * stored in 4-byte pixels in the order R, G, B from lowest to highest byte
 143    * address within each pixel.  The X component is ignored when compressing
 144    * and undefined when decompressing.
 145    */
 146   TJPF_RGBX,
 147   /**
 148    * BGRX pixel format.  The red, green, and blue components in the image are
 149    * stored in 4-byte pixels in the order B, G, R from lowest to highest byte
 150    * address within each pixel.  The X component is ignored when compressing
 151    * and undefined when decompressing.
 152    */
 153   TJPF_BGRX,
 154   /**
 155    * XBGR pixel format.  The red, green, and blue components in the image are
 156    * stored in 4-byte pixels in the order R, G, B from highest to lowest byte
 157    * address within each pixel.  The X component is ignored when compressing
 158    * and undefined when decompressing.
 159    */
 160   TJPF_XBGR,
 161   /**
 162    * XRGB pixel format.  The red, green, and blue components in the image are
 163    * stored in 4-byte pixels in the order B, G, R from highest to lowest byte
 164    * address within each pixel.  The X component is ignored when compressing
 165    * and undefined when decompressing.
 166    */
 167   TJPF_XRGB,
 168   /**
 169    * Grayscale pixel format.  Each 1-byte pixel represents a luminance
 170    * (brightness) level from 0 to 255.
 171    */
 172   TJPF_GRAY,
 173   /**
 174    * RGBA pixel format.  This is the same as @ref TJPF_RGBX, except that when
 175    * decompressing, the X component is guaranteed to be 0xFF, which can be
 176    * interpreted as an opaque alpha channel.
 177    */
 178   TJPF_RGBA,
 179   /**
 180    * BGRA pixel format.  This is the same as @ref TJPF_BGRX, except that when
 181    * decompressing, the X component is guaranteed to be 0xFF, which can be
 182    * interpreted as an opaque alpha channel.
 183    */
 184   TJPF_BGRA,
 185   /**
 186    * ABGR pixel format.  This is the same as @ref TJPF_XBGR, except that when
 187    * decompressing, the X component is guaranteed to be 0xFF, which can be
 188    * interpreted as an opaque alpha channel.
 189    */
 190   TJPF_ABGR,
 191   /**
 192    * ARGB pixel format.  This is the same as @ref TJPF_XRGB, except that when
 193    * decompressing, the X component is guaranteed to be 0xFF, which can be
 194    * interpreted as an opaque alpha channel.
 195    */
 196   TJPF_ARGB
 197 };
 198
 199 /**
 200  * Red offset (in bytes) for a given pixel format.  This specifies the number
 201  * of bytes that the red component is offset from the start of the pixel.  For
 202  * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,
 203  * then the red component will be <tt>pixel[tjRedOffset[TJ_BGRX]]</tt>.
 204  */
 205 static const int tjRedOffset[TJ_NUMPF] = {0, 2, 0, 2, 3, 1, 0, 0, 2, 3, 1};
 206 /**
 207  * Green offset (in bytes) for a given pixel format.  This specifies the number
 208  * of bytes that the green component is offset from the start of the pixel.
 209  * For instance, if a pixel of format TJ_BGRX is stored in
 210  * <tt>char pixel[]</tt>, then the green component will be
 211  * <tt>pixel[tjGreenOffset[TJ_BGRX]]</tt>.
 212  */
 213 static const int tjGreenOffset[TJ_NUMPF] = {1, 1, 1, 1, 2, 2, 0, 1, 1, 2, 2};
 214 /**
 215  * Blue offset (in bytes) for a given pixel format.  This specifies the number
 216  * of bytes that the Blue component is offset from the start of the pixel.  For
 217  * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,
 218  * then the blue component will be <tt>pixel[tjBlueOffset[TJ_BGRX]]</tt>.
 219  */
 220 static const int tjBlueOffset[TJ_NUMPF] = {2, 0, 2, 0, 1, 3, 0, 2, 0, 1, 3};
 221
 222 /**
 223  * Pixel size (in bytes) for a given pixel format.
 224  */
 225 static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4};
 226
 227
 228 /**
 229  * The uncompressed source/destination image is stored in bottom-up (Windows,
 230  * OpenGL) order, not top-down (X11) order.
 231  */
 232 #define TJFLAG_BOTTOMUP        2
 233 /**
 234  * Turn off CPU auto-detection and force TurboJPEG to use MMX code (if the
 235  * underlying codec supports it.)
 236  */
 237 #define TJFLAG_FORCEMMX        8
 238 /**
 239  * Turn off CPU auto-detection and force TurboJPEG to use SSE code (if the
 240  * underlying codec supports it.)
 241  */
 242 #define TJFLAG_FORCESSE       16
 243 /**
 244  * Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (if the
 245  * underlying codec supports it.)
 246  */
 247 #define TJFLAG_FORCESSE2      32
 248 /**
 249  * Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (if the
 250  * underlying codec supports it.)
 251  */
 252 #define TJFLAG_FORCESSE3     128
 253 /**
 254  * When decompressing an image that was compressed using chrominance
 255  * subsampling, use the fastest chrominance upsampling algorithm available in
 256  * the underlying codec.  The default is to use smooth upsampling, which
 257  * creates a smooth transition between neighboring chrominance components in
 258  * order to reduce upsampling artifacts in the decompressed image.
 259  */
 260 #define TJFLAG_FASTUPSAMPLE  256
 261 /**
 262  * Disable buffer (re)allocation.  If passed to #tjCompress2() or
 263  * #tjTransform(), this flag will cause those functions to generate an error if
 264  * the JPEG image buffer is invalid or too small rather than attempting to
 265  * allocate or reallocate that buffer.  This reproduces the behavior of earlier
 266  * versions of TurboJPEG.
 267  */
 268 #define TJFLAG_NOREALLOC     1024
 269 /**
 270  * Use the fastest DCT/IDCT algorithm available in the underlying codec.  The
 271  * default if this flag is not specified is implementation-specific.  For
 272  * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast
 273  * algorithm by default when compressing, because this has been shown to have
 274  * only a very slight effect on accuracy, but it uses the accurate algorithm
 275  * when decompressing, because this has been shown to have a larger effect.
 276  */
 277 #define TJFLAG_FASTDCT       2048
 278 /**
 279  * Use the most accurate DCT/IDCT algorithm available in the underlying codec.
 280  * The default if this flag is not specified is implementation-specific.  For
 281  * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast
 282  * algorithm by default when compressing, because this has been shown to have
 283  * only a very slight effect on accuracy, but it uses the accurate algorithm
 284  * when decompressing, because this has been shown to have a larger effect.
 285  */
 286 #define TJFLAG_ACCURATEDCT   4096
 287
 288
 289 /**
 290  * The number of transform operations
 291  */
 292 #define TJ_NUMXOP 8
 293
 294 /**
 295  * Transform operations for #tjTransform()
 296  */
 297 enum TJXOP
 298 {
 299   /**
 300    * Do not transform the position of the image pixels
 301    */
 302   TJXOP_NONE=0,
 303   /**
 304    * Flip (mirror) image horizontally.  This transform is imperfect if there
 305    * are any partial MCU blocks on the right edge (see #TJXOPT_PERFECT.)
 306    */
 307   TJXOP_HFLIP,
 308   /**
 309    * Flip (mirror) image vertically.  This transform is imperfect if there are
 310    * any partial MCU blocks on the bottom edge (see #TJXOPT_PERFECT.)
 311    */
 312   TJXOP_VFLIP,
 313   /**
 314    * Transpose image (flip/mirror along upper left to lower right axis.)  This
 315    * transform is always perfect.
 316    */
 317   TJXOP_TRANSPOSE,
 318   /**
 319    * Transverse transpose image (flip/mirror along upper right to lower left
 320    * axis.)  This transform is imperfect if there are any partial MCU blocks in
 321    * the image (see #TJXOPT_PERFECT.)
 322    */
 323   TJXOP_TRANSVERSE,
 324   /**
 325    * Rotate image clockwise by 90 degrees.  This transform is imperfect if
 326    * there are any partial MCU blocks on the bottom edge (see
 327    * #TJXOPT_PERFECT.)
 328    */
 329   TJXOP_ROT90,
 330   /**
 331    * Rotate image 180 degrees.  This transform is imperfect if there are any
 332    * partial MCU blocks in the image (see #TJXOPT_PERFECT.)
 333    */
 334   TJXOP_ROT180,
 335   /**
 336    * Rotate image counter-clockwise by 90 degrees.  This transform is imperfect
 337    * if there are any partial MCU blocks on the right edge (see
 338    * #TJXOPT_PERFECT.)
 339    */
 340   TJXOP_ROT270
 341 };
 342
 343
 344 /**
 345  * This option will cause #tjTransform() to return an error if the transform is
 346  * not perfect.  Lossless transforms operate on MCU blocks, whose size depends
 347  * on the level of chrominance subsampling used (see #tjMCUWidth
 348  * and #tjMCUHeight.)  If the image's width or height is not evenly divisible
 349  * by the MCU block size, then there will be partial MCU blocks on the right
 350  * and/or bottom edges.  It is not possible to move these partial MCU blocks to
 351  * the top or left of the image, so any transform that would require that is
 352  * "imperfect."  If this option is not specified, then any partial MCU blocks
 353  * that cannot be transformed will be left in place, which will create
 354  * odd-looking strips on the right or bottom edge of the image.
 355  */
 356 #define TJXOPT_PERFECT  1
 357 /**
 358  * This option will cause #tjTransform() to discard any partial MCU blocks that
 359  * cannot be transformed.
 360  */
 361 #define TJXOPT_TRIM     2
 362 /**
 363  * This option will enable lossless cropping.  See #tjTransform() for more
 364  * information.
 365  */
 366 #define TJXOPT_CROP     4
 367 /**
 368  * This option will discard the color data in the input image and produce
 369  * a grayscale output image.
 370  */
 371 #define TJXOPT_GRAY     8
 372 /**
 373  * This option will prevent #tjTransform() from outputting a JPEG image for
 374  * this particular transform (this can be used in conjunction with a custom
 375  * filter to capture the transformed DCT coefficients without transcoding
 376  * them.)
 377  */
 378 #define TJXOPT_NOOUTPUT 16
 379
 380
 381 /**
 382  * Scaling factor
 383  */
 384 typedef struct
 385 {
 386   /**
 387    * Numerator
 388    */
 389   int num;
 390   /**
 391    * Denominator
 392    */
 393   int denom;
 394 } tjscalingfactor;
 395
 396 /**
 397  * Cropping region
 398  */
 399 typedef struct
 400 {
 401   /**
 402    * The left boundary of the cropping region.  This must be evenly divisible
 403    * by the MCU block width (see #tjMCUWidth.)
 404    */
 405   int x;
 406   /**
 407    * The upper boundary of the cropping region.  This must be evenly divisible
 408    * by the MCU block height (see #tjMCUHeight.)
 409    */
 410   int y;
 411   /**
 412    * The width of the cropping region. Setting this to 0 is the equivalent of
 413    * setting it to the width of the source JPEG image - x.
 414    */
 415   int w;
 416   /**
 417    * The height of the cropping region. Setting this to 0 is the equivalent of
 418    * setting it to the height of the source JPEG image - y.
 419    */
 420   int h;
 421 } tjregion;
 422
 423 /**
 424  * Lossless transform
 425  */
 426 typedef struct tjtransform
 427 {
 428   /**
 429    * Cropping region
 430    */
 431   tjregion r;
 432   /**
 433    * One of the @ref TJXOP "transform operations"
 434    */
 435   int op;
 436   /**
 437    * The bitwise OR of one of more of the @ref TJXOPT_CROP "transform options"
 438    */
 439   int options;
 440   /**
 441    * Arbitrary data that can be accessed within the body of the callback
 442    * function
 443    */
 444   void *data;
 445   /**
 446    * A callback function that can be used to modify the DCT coefficients
 447    * after they are losslessly transformed but before they are transcoded to a
 448    * new JPEG image.  This allows for custom filters or other transformations
 449    * to be applied in the frequency domain.
 450    *
 451    * @param coeffs pointer to an array of transformed DCT coefficients.  (NOTE:
 452    *        this pointer is not guaranteed to be valid once the callback
 453    *        returns, so applications wishing to hand off the DCT coefficients
 454    *        to another function or library should make a copy of them within
 455    *        the body of the callback.)
 456    * @param arrayRegion #tjregion structure containing the width and height of
 457    *        the array pointed to by <tt>coeffs</tt> as well as its offset
 458    *        relative to the component plane.  TurboJPEG implementations may
 459    *        choose to split each component plane into multiple DCT coefficient
 460    *        arrays and call the callback function once for each array.
 461    * @param planeRegion #tjregion structure containing the width and height of
 462    *        the component plane to which <tt>coeffs</tt> belongs
 463    * @param componentID ID number of the component plane to which
 464    *        <tt>coeffs</tt> belongs (Y, Cb, and Cr have, respectively, ID's of
 465    *        0, 1, and 2 in typical JPEG images.)
 466    * @param transformID ID number of the transformed image to which
 467    *        <tt>coeffs</tt> belongs.  This is the same as the index of the
 468    *        transform in the <tt>transforms</tt> array that was passed to
 469    *        #tjTransform().
 470    * @param transform a pointer to a #tjtransform structure that specifies the
 471    *        parameters and/or cropping region for this transform
 472    *
 473    * @return 0 if the callback was successful, or -1 if an error occurred.
 474    */
 475   int (*customFilter)(short *coeffs, tjregion arrayRegion,
 476     tjregion planeRegion, int componentIndex, int transformIndex,
 477     struct tjtransform *transform);
 478 } tjtransform;
 479
 480 /**
 481  * TurboJPEG instance handle
 482  */
 483 typedef void* tjhandle;
 484
 485
 486 /**
 487  * Pad the given width to the nearest 32-bit boundary
 488  */
 489 #define TJPAD(width) (((width)+3)&(~3))
 490
 491 /**
 492  * Compute the scaled value of <tt>dimension</tt> using the given scaling
 493  * factor.  This macro performs the integer equivalent of <tt>ceil(dimension *
 494  * scalingFactor)</tt>.
 495  */
 496 #define TJSCALED(dimension, scalingFactor) ((dimension * scalingFactor.num \
 497   + scalingFactor.denom - 1) / scalingFactor.denom)
 498
 499
 500 #ifdef __cplusplus
 501 extern "C" {
 502 #endif
 503
 504
 505 /**
 506  * Create a TurboJPEG compressor instance.
 507  *
 508  * @return a handle to the newly-created instance, or NULL if an error
 509  * occurred (see #tjGetErrorStr().)
 510  */
 511 DLLEXPORT tjhandle DLLCALL tjInitCompress(void);
 512
 513
 514 /**
 515  * Compress an RGB or grayscale image into a JPEG image.
 516  *
 517  * @param handle a handle to a TurboJPEG compressor or transformer instance
 518  * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels
 519  *        to be compressed
 520  * @param width width (in pixels) of the source image
 521  * @param pitch bytes per line of the source image.  Normally, this should be
 522  *        <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded,
 523  *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
 524  *        the image is padded to the nearest 32-bit boundary, as is the case
 525  *        for Windows bitmaps.  You can also be clever and use this parameter
 526  *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
 527  *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
 528  * @param height height (in pixels) of the source image
 529  * @param pixelFormat pixel format of the source image (see @ref TJPF
 530  *        "Pixel formats".)
 531  * @param jpegBuf address of a pointer to an image buffer that will receive the
 532  *        JPEG image.  TurboJPEG has the ability to reallocate the JPEG buffer
 533  *        to accommodate the size of the JPEG image.  Thus, you can choose to:
 534  *        -# pre-allocate the JPEG buffer with an arbitrary size using
 535  *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
 536  *        -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the
 537  *        buffer for you, or
 538  *        -# pre-allocate the buffer to a "worst case" size determined by
 539  *        calling #tjBufSize().  This should ensure that the buffer never has
 540  *        to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
 541  *        .
 542  *        If you choose option 1, <tt>*jpegSize</tt> should be set to the
 543  *        size of your pre-allocated buffer.  In any case, unless you have
 544  *        set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon
 545  *        return from this function, as it may have changed.
 546  * @param jpegSize pointer to an unsigned long variable that holds the size of
 547  *        the JPEG image buffer.  If <tt>*jpegBuf</tt> points to a
 548  *        pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the
 549  *        size of the buffer.  Upon return, <tt>*jpegSize</tt> will contain the
 550  *        size of the JPEG image (in bytes.)
 551  * @param jpegSubsamp the level of chrominance subsampling to be used when
 552  *        generating the JPEG image (see @ref TJSAMP
 553  *        "Chrominance subsampling options".)
 554  * @param jpegQual the image quality of the generated JPEG image (1 = worst,
 555           100 = best)
 556  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
 557  *        "flags".
 558  *
 559  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 560 */
 561 DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf,
 562   int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf,
 563   unsigned long *jpegSize, int jpegSubsamp, int jpegQual, int flags);
 564
 565
 566 /**
 567  * The maximum size of the buffer (in bytes) required to hold a JPEG image with
 568  * the given parameters.  The number of bytes returned by this function is
 569  * larger than the size of the uncompressed source image.  The reason for this
 570  * is that the JPEG format uses 16-bit coefficients, and it is thus possible
 571  * for a very high-quality JPEG image with very high-frequency content to
 572  * expand rather than compress when converted to the JPEG format.  Such images
 573  * represent a very rare corner case, but since there is no way to predict the
 574  * size of a JPEG image prior to compression, the corner case has to be
 575  * handled.
 576  *
 577  * @param width width of the image (in pixels)
 578  * @param height height of the image (in pixels)
 579  * @param jpegSubsamp the level of chrominance subsampling to be used when
 580  *        generating the JPEG image (see @ref TJSAMP
 581  *        "Chrominance subsampling options".)
 582  *
 583  * @return the maximum size of the buffer (in bytes) required to hold the
 584  * image, or -1 if the arguments are out of bounds.
 585  */
 586 DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height,
 587   int jpegSubsamp);
 588
 589
 590 /**
 591  * The size of the buffer (in bytes) required to hold a YUV planar image with
 592  * the given parameters.
 593  *
 594  * @param width width of the image (in pixels)
 595  * @param height height of the image (in pixels)
 596  * @param subsamp level of chrominance subsampling in the image (see
 597  *        @ref TJSAMP "Chrominance subsampling options".)
 598  *
 599  * @return the size of the buffer (in bytes) required to hold the image, or
 600  * -1 if the arguments are out of bounds.
 601  */
 602 DLLEXPORT unsigned long DLLCALL tjBufSizeYUV(int width, int height,
 603   int subsamp);
 604
 605
 606 /**
 607  * Encode an RGB or grayscale image into a YUV planar image.  This function
 608  * uses the accelerated color conversion routines in TurboJPEG's underlying
 609  * codec to produce a planar YUV image that is suitable for X Video.
 610  * Specifically, if the chrominance components are subsampled along the
 611  * horizontal dimension, then the width of the luminance plane is padded to the
 612  * nearest multiple of 2 in the output image (same goes for the height of the
 613  * luminance plane, if the chrominance components are subsampled along the
 614  * vertical dimension.)  Also, each line of each plane in the output image is
 615  * padded to 4 bytes.  Although this will work with any subsampling option, it
 616  * is really only useful in combination with TJ_420, which produces an image
 617  * compatible with the I420 (AKA "YUV420P") format.
 618  * <p>
 619  * NOTE: Technically, the JPEG format uses the YCbCr colorspace, but per the
 620  * convention of the digital video community, the TurboJPEG API uses "YUV" to
 621  * refer to an image format consisting of Y, Cb, and Cr image planes.
 622  *
 623  * @param handle a handle to a TurboJPEG compressor or transformer instance
 624  * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels
 625  *        to be encoded
 626  * @param width width (in pixels) of the source image
 627  * @param pitch bytes per line of the source image.  Normally, this should be
 628  *        <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded,
 629  *        or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of
 630  *        the image is padded to the nearest 32-bit boundary, as is the case
 631  *        for Windows bitmaps.  You can also be clever and use this parameter
 632  *        to skip lines, etc.  Setting this parameter to 0 is the equivalent of
 633  *        setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.
 634  * @param height height (in pixels) of the source image
 635  * @param pixelFormat pixel format of the source image (see @ref TJPF
 636  *        "Pixel formats".)
 637  * @param dstBuf pointer to an image buffer that will receive the YUV image.
 638  *        Use #tjBufSizeYUV() to determine the appropriate size for this buffer
 639  *        based on the image width, height, and level of chrominance
 640  *        subsampling.
 641  * @param subsamp the level of chrominance subsampling to be used when
 642  *        generating the YUV image (see @ref TJSAMP
 643  *        "Chrominance subsampling options".)
 644  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
 645  *        "flags".
 646  *
 647  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 648 */
 649 DLLEXPORT int DLLCALL tjEncodeYUV2(tjhandle handle,
 650   unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat,
 651   unsigned char *dstBuf, int subsamp, int flags);
 652
 653
 654 /**
 655  * Create a TurboJPEG decompressor instance.
 656  *
 657  * @return a handle to the newly-created instance, or NULL if an error
 658  * occurred (see #tjGetErrorStr().)
 659 */
 660 DLLEXPORT tjhandle DLLCALL tjInitDecompress(void);
 661
 662
 663 /**
 664  * Retrieve information about a JPEG image without decompressing it.
 665  *
 666  * @param handle a handle to a TurboJPEG decompressor or transformer instance
 667  * @param jpegBuf pointer to a buffer containing a JPEG image
 668  * @param jpegSize size of the JPEG image (in bytes)
 669  * @param width pointer to an integer variable that will receive the width (in
 670  *        pixels) of the JPEG image
 671  * @param height pointer to an integer variable that will receive the height
 672  *        (in pixels) of the JPEG image
 673  * @param jpegSubsamp pointer to an integer variable that will receive the
 674  *        level of chrominance subsampling used when compressing the JPEG image
 675  *        (see @ref TJSAMP "Chrominance subsampling options".)
 676  *
 677  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 678 */
 679 DLLEXPORT int DLLCALL tjDecompressHeader2(tjhandle handle,
 680   unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height,
 681   int *jpegSubsamp);
 682
 683
 684 /**
 685  * Returns a list of fractional scaling factors that the JPEG decompressor in
 686  * this implementation of TurboJPEG supports.
 687  *
 688  * @param numscalingfactors pointer to an integer variable that will receive
 689  *        the number of elements in the list
 690  *
 691  * @return a pointer to a list of fractional scaling factors, or NULL if an
 692  * error is encountered (see #tjGetErrorStr().)
 693 */
 694 DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors);
 695
 696
 697 /**
 698  * Decompress a JPEG image to an RGB or grayscale image.
 699  *
 700  * @param handle a handle to a TurboJPEG decompressor or transformer instance
 701  * @param jpegBuf pointer to a buffer containing the JPEG image to decompress
 702  * @param jpegSize size of the JPEG image (in bytes)
 703  * @param dstBuf pointer to an image buffer that will receive the decompressed
 704  *        image.  This buffer should normally be <tt>pitch * scaledHeight</tt>
 705  *        bytes in size, where <tt>scaledHeight</tt> can be determined by
 706  *        calling #TJSCALED() with the JPEG image height and one of the scaling
 707  *        factors returned by #tjGetScalingFactors().  The <tt>dstBuf</tt>
 708  *        pointer may also be used to decompress into a specific region of a
 709  *        larger buffer.
 710  * @param width desired width (in pixels) of the destination image.  If this is
 711  *        different than the width of the JPEG image being decompressed, then
 712  *        TurboJPEG will use scaling in the JPEG decompressor to generate the
 713  *        largest possible image that will fit within the desired width.  If
 714  *        <tt>width</tt> is set to 0, then only the height will be considered
 715  *        when determining the scaled image size.
 716  * @param pitch bytes per line of the destination image.  Normally, this is
 717  *        <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed
 718  *        image is unpadded, else <tt>#TJPAD(scaledWidth *
 719  *        #tjPixelSize[pixelFormat])</tt> if each line of the decompressed
 720  *        image is padded to the nearest 32-bit boundary, as is the case for
 721  *        Windows bitmaps.  (NOTE: <tt>scaledWidth</tt> can be determined by
 722  *        calling #TJSCALED() with the JPEG image width and one of the scaling
 723  *        factors returned by #tjGetScalingFactors().)  You can also be clever
 724  *        and use the pitch parameter to skip lines, etc.  Setting this
 725  *        parameter to 0 is the equivalent of setting it to <tt>scaledWidth
 726  *        * #tjPixelSize[pixelFormat]</tt>.
 727  * @param height desired height (in pixels) of the destination image.  If this
 728  *        is different than the height of the JPEG image being decompressed,
 729  *        then TurboJPEG will use scaling in the JPEG decompressor to generate
 730  *        the largest possible image that will fit within the desired height.
 731  *        If <tt>height</tt> is set to 0, then only the width will be
 732  *        considered when determining the scaled image size.
 733  * @param pixelFormat pixel format of the destination image (see @ref
 734  *        TJPF "Pixel formats".)
 735  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
 736  *        "flags".
 737  *
 738  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 739  */
 740 DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
 741   unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
 742   int width, int pitch, int height, int pixelFormat, int flags);
 743
 744
 745 /**
 746  * Decompress a JPEG image to a YUV planar image.  This function performs JPEG
 747  * decompression but leaves out the color conversion step, so a planar YUV
 748  * image is generated instead of an RGB image.  The padding of the planes in
 749  * this image is the same as in the images generated by #tjEncodeYUV2().  Note
 750  * that, if the width or height of the image is not an even multiple of the MCU
 751  * block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate buffer
 752  * copy will be performed within TurboJPEG.
 753  * <p>
 754  * NOTE: Technically, the JPEG format uses the YCbCr colorspace, but per the
 755  * convention of the digital video community, the TurboJPEG API uses "YUV" to
 756  * refer to an image format consisting of Y, Cb, and Cr image planes.
 757  *
 758  * @param handle a handle to a TurboJPEG decompressor or transformer instance
 759  * @param jpegBuf pointer to a buffer containing the JPEG image to decompress
 760  * @param jpegSize size of the JPEG image (in bytes)
 761  * @param dstBuf pointer to an image buffer that will receive the YUV image.
 762  *        Use #tjBufSizeYUV() to determine the appropriate size for this buffer
 763  *        based on the image width, height, and level of subsampling.
 764  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
 765  *        "flags".
 766  *
 767  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 768  */
 769 DLLEXPORT int DLLCALL tjDecompressToYUV(tjhandle handle,
 770   unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
 771   int flags);
 772
 773
 774 /**
 775  * Create a new TurboJPEG transformer instance.
 776  *
 777  * @return a handle to the newly-created instance, or NULL if an error
 778  * occurred (see #tjGetErrorStr().)
 779  */
 780 DLLEXPORT tjhandle DLLCALL tjInitTransform(void);
 781
 782
 783 /**
 784  * Losslessly transform a JPEG image into another JPEG image.  Lossless
 785  * transforms work by moving the raw coefficients from one JPEG image structure
 786  * to another without altering the values of the coefficients.  While this is
 787  * typically faster than decompressing the image, transforming it, and
 788  * re-compressing it, lossless transforms are not free.  Each lossless
 789  * transform requires reading and performing Huffman decoding on all of the
 790  * coefficients in the source image, regardless of the size of the destination
 791  * image.  Thus, this function provides a means of generating multiple
 792  * transformed images from the same source or  applying multiple
 793  * transformations simultaneously, in order to eliminate the need to read the
 794  * source coefficients multiple times.
 795  *
 796  * @param handle a handle to a TurboJPEG transformer instance
 797  * @param jpegBuf pointer to a buffer containing the JPEG image to transform
 798  * @param jpegSize size of the JPEG image (in bytes)
 799  * @param n the number of transformed JPEG images to generate
 800  * @param dstBufs pointer to an array of n image buffers.  <tt>dstBufs[i]</tt>
 801  *        will receive a JPEG image that has been transformed using the
 802  *        parameters in <tt>transforms[i]</tt>.  TurboJPEG has the ability to
 803  *        reallocate the JPEG buffer to accommodate the size of the JPEG image.
 804  *        Thus, you can choose to:
 805  *        -# pre-allocate the JPEG buffer with an arbitrary size using
 806  *        #tjAlloc() and let TurboJPEG grow the buffer as needed,
 807  *        -# set <tt>dstBufs[i]</tt> to NULL to tell TurboJPEG to allocate the
 808  *        buffer for you, or
 809  *        -# pre-allocate the buffer to a "worst case" size determined by
 810  *        calling #tjBufSize() with the transformed or cropped width and
 811  *        height.  This should ensure that the buffer never has to be
 812  *        re-allocated (setting #TJFLAG_NOREALLOC guarantees this.)
 813  *        .
 814  *        If you choose option 1, <tt>dstSizes[i]</tt> should be set to
 815  *        the size of your pre-allocated buffer.  In any case, unless you have
 816  *        set #TJFLAG_NOREALLOC, you should always check <tt>dstBufs[i]</tt>
 817  *        upon return from this function, as it may have changed.
 818  * @param dstSizes pointer to an array of n unsigned long variables that will
 819  *        receive the actual sizes (in bytes) of each transformed JPEG image.
 820  *        If <tt>dstBufs[i]</tt> points to a pre-allocated buffer, then
 821  *        <tt>dstSizes[i]</tt> should be set to the size of the buffer.  Upon
 822  *        return, <tt>dstSizes[i]</tt> will contain the size of the JPEG image
 823  *        (in bytes.)
 824  * @param transforms pointer to an array of n #tjtransform structures, each of
 825  *        which specifies the transform parameters and/or cropping region for
 826  *        the corresponding transformed output image.
 827  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
 828  *        "flags".
 829  *
 830  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 831  */
 832 DLLEXPORT int DLLCALL tjTransform(tjhandle handle, unsigned char *jpegBuf,
 833   unsigned long jpegSize, int n, unsigned char **dstBufs,
 834   unsigned long *dstSizes, tjtransform *transforms, int flags);
 835
 836
 837 /**
 838  * Destroy a TurboJPEG compressor, decompressor, or transformer instance.
 839  *
 840  * @param handle a handle to a TurboJPEG compressor, decompressor or
 841  *        transformer instance
 842  *
 843  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 844  */
 845 DLLEXPORT int DLLCALL tjDestroy(tjhandle handle);
 846
 847
 848 /**
 849  * Allocate an image buffer for use with TurboJPEG.  You should always use
 850  * this function to allocate the JPEG destination buffer(s) for #tjCompress2()
 851  * and #tjTransform() unless you are disabling automatic buffer
 852  * (re)allocation (by setting #TJFLAG_NOREALLOC.)
 853  *
 854  * @param bytes the number of bytes to allocate
 855  *
 856  * @return a pointer to a newly-allocated buffer with the specified number of
 857  *         bytes
 858  *
 859  * @sa tjFree()
 860  */
 861 DLLEXPORT unsigned char* DLLCALL tjAlloc(int bytes);
 862
 863
 864 /**
 865  * Free an image buffer previously allocated by TurboJPEG.  You should always
 866  * use this function to free JPEG destination buffer(s) that were automatically
 867  * (re)allocated by #tjCompress2() or #tjTransform() or that were manually
 868  * allocated using #tjAlloc().
 869  *
 870  * @param buffer address of the buffer to free
 871  *
 872  * @sa tjAlloc()
 873  */
 874 DLLEXPORT void DLLCALL tjFree(unsigned char *buffer);
 875
 876
 877 /**
 878  * Returns a descriptive error message explaining why the last command failed.
 879  *
 880  * @return a descriptive error message explaining why the last command failed.
 881  */
 882 DLLEXPORT char* DLLCALL tjGetErrorStr(void);
 883
 884
 885 /* Backward compatibility functions and macros (nothing to see here) */
 886 #define NUMSUBOPT TJ_NUMSAMP
 887 #define TJ_444 TJSAMP_444
 888 #define TJ_422 TJSAMP_422
 889 #define TJ_420 TJSAMP_420
 890 #define TJ_411 TJSAMP_420
 891 #define TJ_GRAYSCALE TJSAMP_GRAY
 892
 893 #define TJ_BGR 1
 894 #define TJ_BOTTOMUP TJFLAG_BOTTOMUP
 895 #define TJ_FORCEMMX TJFLAG_FORCEMMX
 896 #define TJ_FORCESSE TJFLAG_FORCESSE
 897 #define TJ_FORCESSE2 TJFLAG_FORCESSE2
 898 #define TJ_ALPHAFIRST 64
 899 #define TJ_FORCESSE3 TJFLAG_FORCESSE3
 900 #define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE
 901 #define TJ_YUV 512
 902
 903 DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height);
 904
 905 DLLEXPORT unsigned long DLLCALL TJBUFSIZEYUV(int width, int height,
 906   int jpegSubsamp);
 907
 908 DLLEXPORT int DLLCALL tjCompress(tjhandle handle, unsigned char *srcBuf,
 909   int width, int pitch, int height, int pixelSize, unsigned char *dstBuf,
 910   unsigned long *compressedSize, int jpegSubsamp, int jpegQual, int flags);
 911
 912 DLLEXPORT int DLLCALL tjEncodeYUV(tjhandle handle,
 913   unsigned char *srcBuf, int width, int pitch, int height, int pixelSize,
 914   unsigned char *dstBuf, int subsamp, int flags);
 915
 916 DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle handle,
 917   unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height);
 918
 919 DLLEXPORT int DLLCALL tjDecompress(tjhandle handle,
 920   unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
 921   int width, int pitch, int height, int pixelSize, int flags);
 922
 923
 924 /**
 925  * @}
 926  */
 927
 928 #ifdef __cplusplus
 929 }
 930 #endif
 931
 932 #endif