1 /* 2 * Copyright (C)2009-2012 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 Lite 42 * TurboJPEG API. This API provides an interface for generating and decoding 43 * 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 */ 63 enum TJSAMP 64 { 65 /** 66 * 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG or 67 * YUV image will contain one chrominance component for every pixel in the 68 * source image. 69 */ 70 TJSAMP_444=0, 71 /** 72 * 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one 73 * chrominance component for every 2x1 block of pixels in the source image. 74 */ 75 TJSAMP_422, 76 /** 77 * 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one 78 * chrominance component for every 2x2 block of pixels in the source image. 79 */ 80 TJSAMP_420, 81 /** 82 * Grayscale. The JPEG or YUV image will contain no chrominance components. 83 */ 84 TJSAMP_GRAY, 85 /** 86 * 4:4:0 chrominance subsampling. The JPEG or YUV image will contain one 87 * chrominance component for every 1x2 block of pixels in the source image. 88 */ 89 TJSAMP_440 90 }; 91 92 /** 93 * MCU block width (in pixels) for a given level of chrominance subsampling. 94 * MCU block sizes: 95 * - 8x8 for no subsampling or grayscale 96 * - 16x8 for 4:2:2 97 * - 8x16 for 4:4:0 98 * - 16x16 for 4:2:0 99 */ 100 static const int tjMCUWidth[TJ_NUMSAMP] = {8, 16, 16, 8, 8}; 101 102 /** 103 * MCU block height (in pixels) for a given level of chrominance subsampling. 104 * MCU block sizes: 105 * - 8x8 for no subsampling or grayscale 106 * - 16x8 for 4:2:2 107 * - 8x16 for 4:4:0 108 * - 16x16 for 4:2:0 109 */ 110 static const int tjMCUHeight[TJ_NUMSAMP] = {8, 8, 16, 8, 16}; 111 112 113 /** 114 * The number of pixel formats 115 */ 116 #define TJ_NUMPF 11 117 118 /** 119 * Pixel formats 120 */ 121 enum TJPF 122 { 123 /** 124 * RGB pixel format. The red, green, and blue components in the image are 125 * stored in 3-byte pixels in the order R, G, B from lowest to highest byte 126 * address within each pixel. 127 */ 128 TJPF_RGB=0, 129 /** 130 * BGR pixel format. The red, green, and blue components in the image are 131 * stored in 3-byte pixels in the order B, G, R from lowest to highest byte 132 * address within each pixel. 133 */ 134 TJPF_BGR, 135 /** 136 * RGBX pixel format. The red, green, and blue components in the image are 137 * stored in 4-byte pixels in the order R, G, B from lowest to highest byte 138 * address within each pixel. The X component is ignored when compressing 139 * and undefined when decompressing. 140 */ 141 TJPF_RGBX, 142 /** 143 * BGRX pixel format. The red, green, and blue components in the image are 144 * stored in 4-byte pixels in the order B, G, R from lowest to highest byte 145 * address within each pixel. The X component is ignored when compressing 146 * and undefined when decompressing. 147 */ 148 TJPF_BGRX, 149 /** 150 * XBGR pixel format. The red, green, and blue components in the image are 151 * stored in 4-byte pixels in the order R, G, B from highest to lowest byte 152 * address within each pixel. The X component is ignored when compressing 153 * and undefined when decompressing. 154 */ 155 TJPF_XBGR, 156 /** 157 * XRGB pixel format. The red, green, and blue components in the image are 158 * stored in 4-byte pixels in the order B, G, R from highest to lowest byte 159 * address within each pixel. The X component is ignored when compressing 160 * and undefined when decompressing. 161 */ 162 TJPF_XRGB, 163 /** 164 * Grayscale pixel format. Each 1-byte pixel represents a luminance 165 * (brightness) level from 0 to 255. 166 */ 167 TJPF_GRAY, 168 /** 169 * RGBA pixel format. This is the same as @ref TJPF_RGBX, except that when 170 * decompressing, the X component is guaranteed to be 0xFF, which can be 171 * interpreted as an opaque alpha channel. 172 */ 173 TJPF_RGBA, 174 /** 175 * BGRA pixel format. This is the same as @ref TJPF_BGRX, except that when 176 * decompressing, the X component is guaranteed to be 0xFF, which can be 177 * interpreted as an opaque alpha channel. 178 */ 179 TJPF_BGRA, 180 /** 181 * ABGR pixel format. This is the same as @ref TJPF_XBGR, except that when 182 * decompressing, the X component is guaranteed to be 0xFF, which can be 183 * interpreted as an opaque alpha channel. 184 */ 185 TJPF_ABGR, 186 /** 187 * ARGB pixel format. This is the same as @ref TJPF_XRGB, except that when 188 * decompressing, the X component is guaranteed to be 0xFF, which can be 189 * interpreted as an opaque alpha channel. 190 */ 191 TJPF_ARGB 192 }; 193 194 /** 195 * Red offset (in bytes) for a given pixel format. This specifies the number 196 * of bytes that the red component is offset from the start of the pixel. For 197 * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>, 198 * then the red component will be <tt>pixel[tjRedOffset[TJ_BGRX]]</tt>. 199 */ 200 static const int tjRedOffset[TJ_NUMPF] = {0, 2, 0, 2, 3, 1, 0, 0, 2, 3, 1}; 201 /** 202 * Green offset (in bytes) for a given pixel format. This specifies the number 203 * of bytes that the green component is offset from the start of the pixel. 204 * For instance, if a pixel of format TJ_BGRX is stored in 205 * <tt>char pixel[]</tt>, then the green component will be 206 * <tt>pixel[tjGreenOffset[TJ_BGRX]]</tt>. 207 */ 208 static const int tjGreenOffset[TJ_NUMPF] = {1, 1, 1, 1, 2, 2, 0, 1, 1, 2, 2}; 209 /** 210 * Blue offset (in bytes) for a given pixel format. This specifies the number 211 * of bytes that the Blue component is offset from the start of the pixel. For 212 * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>, 213 * then the blue component will be <tt>pixel[tjBlueOffset[TJ_BGRX]]</tt>. 214 */ 215 static const int tjBlueOffset[TJ_NUMPF] = {2, 0, 2, 0, 1, 3, 0, 2, 0, 1, 3}; 216 217 /** 218 * Pixel size (in bytes) for a given pixel format. 219 */ 220 static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4}; 221 222 223 /** 224 * The uncompressed source/destination image is stored in bottom-up (Windows, 225 * OpenGL) order, not top-down (X11) order. 226 */ 227 #define TJFLAG_BOTTOMUP 2 228 /** 229 * Turn off CPU auto-detection and force TurboJPEG to use MMX code (IPP and 230 * 32-bit libjpeg-turbo versions only.) 231 */ 232 #define TJFLAG_FORCEMMX 8 233 /** 234 * Turn off CPU auto-detection and force TurboJPEG to use SSE code (32-bit IPP 235 * and 32-bit libjpeg-turbo versions only) 236 */ 237 #define TJFLAG_FORCESSE 16 238 /** 239 * Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (32-bit IPP 240 * and 32-bit libjpeg-turbo versions only) 241 */ 242 #define TJFLAG_FORCESSE2 32 243 /** 244 * Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (64-bit IPP 245 * version only) 246 */ 247 #define TJFLAG_FORCESSE3 128 248 /** 249 * Use fast, inaccurate chrominance upsampling routines in the JPEG 250 * decompressor (libjpeg and libjpeg-turbo versions only) 251 */ 252 #define TJFLAG_FASTUPSAMPLE 256 253 254 255 /** 256 * Scaling factor 257 */ 258 typedef struct 259 { 260 /** 261 * Numerator 262 */ 263 int num; 264 /** 265 * Denominator 266 */ 267 int denom; 268 } tjscalingfactor; 269 270 271 /** 272 * TurboJPEG instance handle 273 */ 274 typedef void* tjhandle; 275 276 277 /** 278 * Pad the given width to the nearest 32-bit boundary 279 */ 280 #define TJPAD(width) (((width)+3)&(~3)) 281 282 /** 283 * Compute the scaled value of <tt>dimension</tt> using the given scaling 284 * factor. This macro performs the integer equivalent of <tt>ceil(dimension * 285 * scalingFactor)</tt>. 286 */ 287 #define TJSCALED(dimension, scalingFactor) ((dimension * scalingFactor.num \ 288 + scalingFactor.denom - 1) / scalingFactor.denom) 289 290 291 #ifdef __cplusplus 292 extern "C" { 293 #endif 294 295 296 /** 297 * Create a TurboJPEG compressor instance. 298 * 299 * @return a handle to the newly-created instance, or NULL if an error 300 * occurred (see #tjGetErrorStr().) 301 */ 302 DLLEXPORT tjhandle DLLCALL tjInitCompress(void); 303 304 305 /** 306 * Compress an RGB or grayscale image into a JPEG image. 307 * 308 * @param handle a handle to a TurboJPEG compressor or transformer instance 309 * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels 310 * to be compressed 311 * @param width width (in pixels) of the source image 312 * @param pitch bytes per line of the source image. Normally, this should be 313 * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, 314 * or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of 315 * the image is padded to the nearest 32-bit boundary, as is the case 316 * for Windows bitmaps. You can also be clever and use this parameter 317 * to skip lines, etc. Setting this parameter to 0 is the equivalent of 318 * setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>. 319 * @param height height (in pixels) of the source image 320 * @param pixelFormat pixel format of the source image (see @ref TJPF 321 * "Pixel formats".) 322 * @param jpegBuf address of a pointer to an image buffer that will receive the 323 * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer 324 * to accommodate the size of the JPEG image. Thus, you can choose to: 325 * -# pre-allocate the JPEG buffer with an arbitrary size using 326 * #tjAlloc() and let TurboJPEG grow the buffer as needed, 327 * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the 328 * buffer for you, or 329 * -# pre-allocate the buffer to a "worst case" size determined by 330 * calling #tjBufSize(). This should ensure that the buffer never has 331 * to be re-allocated (setting #TJFLAG_NOREALLOC guarantees this.) 332 * . 333 * If you choose option 1, <tt>*jpegSize</tt> should be set to the 334 * size of your pre-allocated buffer. In any case, unless you have 335 * set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon 336 * return from this function, as it may have changed. 337 * @param jpegSize pointer to an unsigned long variable that holds the size of 338 * the JPEG image buffer. If <tt>*jpegBuf</tt> points to a 339 * pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the 340 * size of the buffer. Upon return, <tt>*jpegSize</tt> will contain the 341 * size of the JPEG image (in bytes.) 342 * @param jpegSubsamp the level of chrominance subsampling to be used when 343 * generating the JPEG image (see @ref TJSAMP 344 * "Chrominance subsampling options".) 345 * @param jpegQual the image quality of the generated JPEG image (1 = worst, 346 100 = best) 347 * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP 348 * "flags". 349 * 350 * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().) 351 */ 352 DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf, 353 int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf, 354 unsigned long *jpegSize, int jpegSubsamp, int jpegQual, int flags); 355 356 357 /** 358 * The maximum size of the buffer (in bytes) required to hold a JPEG image with 359 * the given parameters. The number of bytes returned by this function is 360 * larger than the size of the uncompressed source image. The reason for this 361 * is that the JPEG format uses 16-bit coefficients, and it is thus possible 362 * for a very high-quality JPEG image with very high frequency content to 363 * expand rather than compress when converted to the JPEG format. Such images 364 * represent a very rare corner case, but since there is no way to predict the 365 * size of a JPEG image prior to compression, the corner case has to be 366 * handled. 367 * 368 * @param width width of the image (in pixels) 369 * @param height height of the image (in pixels) 370 * @param jpegSubsamp the level of chrominance subsampling to be used when 371 * generating the JPEG image (see @ref TJSAMP 372 * "Chrominance subsampling options".) 373 * 374 * @return the maximum size of the buffer (in bytes) required to hold the 375 * image, or -1 if the arguments are out of bounds. 376 */ 377 DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height, 378 int jpegSubsamp); 379 380 381 /** 382 * Create a TurboJPEG decompressor instance. 383 * 384 * @return a handle to the newly-created instance, or NULL if an error 385 * occurred (see #tjGetErrorStr().) 386 */ 387 DLLEXPORT tjhandle DLLCALL tjInitDecompress(void); 388 389 390 /** 391 * Retrieve information about a JPEG image without decompressing it. 392 * 393 * @param handle a handle to a TurboJPEG decompressor or transformer instance 394 * @param jpegBuf pointer to a buffer containing a JPEG image 395 * @param jpegSize size of the JPEG image (in bytes) 396 * @param width pointer to an integer variable that will receive the width (in 397 * pixels) of the JPEG image 398 * @param height pointer to an integer variable that will receive the height 399 * (in pixels) of the JPEG image 400 * @param jpegSubsamp pointer to an integer variable that will receive the 401 * level of chrominance subsampling used when compressing the JPEG image 402 * (see @ref TJSAMP "Chrominance subsampling options".) 403 * 404 * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().) 405 */ 406 DLLEXPORT int DLLCALL tjDecompressHeader2(tjhandle handle, 407 unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height, 408 int *jpegSubsamp); 409 410 411 /** 412 * Returns a list of fractional scaling factors that the JPEG decompressor in 413 * this implementation of TurboJPEG supports. 414 * 415 * @param numscalingfactors pointer to an integer variable that will receive 416 * the number of elements in the list 417 * 418 * @return a pointer to a list of fractional scaling factors, or NULL if an 419 * error is encountered (see #tjGetErrorStr().) 420 */ 421 DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors); 422 423 424 /** 425 * Decompress a JPEG image to an RGB or grayscale image. 426 * 427 * @param handle a handle to a TurboJPEG decompressor or transformer instance 428 * @param jpegBuf pointer to a buffer containing the JPEG image to decompress 429 * @param jpegSize size of the JPEG image (in bytes) 430 * @param dstBuf pointer to an image buffer that will receive the decompressed 431 * image. This buffer should normally be <tt>pitch * scaledHeight</tt> 432 * bytes in size, where <tt>scaledHeight</tt> can be determined by 433 * calling #TJSCALED() with the JPEG image height and one of the scaling 434 * factors returned by #tjGetScalingFactors(). The dstBuf pointer may 435 * also be used to decompress into a specific region of a larger buffer. 436 * @param width desired width (in pixels) of the destination image. If this is 437 * smaller than the width of the JPEG image being decompressed, then 438 * TurboJPEG will use scaling in the JPEG decompressor to generate the 439 * largest possible image that will fit within the desired width. If 440 * width is set to 0, then only the height will be considered when 441 * determining the scaled image size. 442 * @param pitch bytes per line of the destination image. Normally, this is 443 * <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed 444 * image is unpadded, else <tt>#TJPAD(scaledWidth * 445 * #tjPixelSize[pixelFormat])</tt> if each line of the decompressed 446 * image is padded to the nearest 32-bit boundary, as is the case for 447 * Windows bitmaps. (NOTE: <tt>scaledWidth</tt> can be determined by 448 * calling #TJSCALED() with the JPEG image width and one of the scaling 449 * factors returned by #tjGetScalingFactors().) You can also be clever 450 * and use the pitch parameter to skip lines, etc. Setting this 451 * parameter to 0 is the equivalent of setting it to <tt>scaledWidth 452 * * #tjPixelSize[pixelFormat]</tt>. 453 * @param height desired height (in pixels) of the destination image. If this 454 * is smaller than the height of the JPEG image being decompressed, then 455 * TurboJPEG will use scaling in the JPEG decompressor to generate the 456 * largest possible image that will fit within the desired height. If 457 * height is set to 0, then only the width will be considered when 458 * determining the scaled image size. 459 * @param pixelFormat pixel format of the destination image (see @ref 460 * TJPF "Pixel formats".) 461 * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP 462 * "flags". 463 * 464 * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().) 465 */ 466 DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle, 467 unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, 468 int width, int pitch, int height, int pixelFormat, int flags); 469 470 471 /** 472 * Destroy a TurboJPEG compressor, decompressor, or transformer instance. 473 * 474 * @param handle a handle to a TurboJPEG compressor, decompressor or 475 * transformer instance 476 * 477 * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().) 478 */ 479 DLLEXPORT int DLLCALL tjDestroy(tjhandle handle); 480 481 482 /** 483 * Returns a descriptive error message explaining why the last command failed. 484 * 485 * @return a descriptive error message explaining why the last command failed. 486 */ 487 DLLEXPORT char* DLLCALL tjGetErrorStr(void); 488 489 490 /* Backward compatibility functions and macros (nothing to see here) */ 491 #define NUMSUBOPT TJ_NUMSAMP 492 #define TJ_444 TJSAMP_444 493 #define TJ_422 TJSAMP_422 494 #define TJ_420 TJSAMP_420 495 #define TJ_411 TJSAMP_420 496 #define TJ_GRAYSCALE TJSAMP_GRAY 497 498 #define TJ_BGR 1 499 #define TJ_BOTTOMUP TJFLAG_BOTTOMUP 500 #define TJ_FORCEMMX TJFLAG_FORCEMMX 501 #define TJ_FORCESSE TJFLAG_FORCESSE 502 #define TJ_FORCESSE2 TJFLAG_FORCESSE2 503 #define TJ_ALPHAFIRST 64 504 #define TJ_FORCESSE3 TJFLAG_FORCESSE3 505 #define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE 506 507 DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height); 508 509 DLLEXPORT int DLLCALL tjCompress(tjhandle handle, unsigned char *srcBuf, 510 int width, int pitch, int height, int pixelSize, unsigned char *dstBuf, 511 unsigned long *compressedSize, int jpegSubsamp, int jpegQual, int flags); 512 513 DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle handle, 514 unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height); 515 516 DLLEXPORT int DLLCALL tjDecompress(tjhandle handle, 517 unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, 518 int width, int pitch, int height, int pixelSize, int flags); 519 520 521 /** 522 * @} 523 */ 524 525 #ifdef __cplusplus 526 } 527 #endif 528 529 #endif 530
