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 */
63enum 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 */
100static 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 */
110static 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 */
121enum 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 */
200static 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 */
208static 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 */
215static 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 */
220static 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 */
258typedef 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 */
274typedef 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
292extern "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 */
302DLLEXPORT 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*/
352DLLEXPORT 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 */
377DLLEXPORT 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*/
387DLLEXPORT 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*/
406DLLEXPORT 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*/
421DLLEXPORT 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 */
466DLLEXPORT 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 */
479DLLEXPORT 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 */
487DLLEXPORT 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
507DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height);
508
509DLLEXPORT 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
513DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle handle,
514  unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height);
515
516DLLEXPORT 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