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 933