1 | /*  |
2 | * Copyright (C)2009-2015, 2017, 2020 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 | * @anchor YUVnotes  |
46 | * YUV Image Format Notes  |
47 | * ----------------------  |
48 | * Technically, the JPEG format uses the YCbCr colorspace (which is technically  |
49 | * not a colorspace but a color transform), but per the convention of the  |
50 | * digital video community, the TurboJPEG API uses "YUV" to refer to an image  |
51 | * format consisting of Y, Cb, and Cr image planes.  |
52 | *  |
53 | * Each plane is simply a 2D array of bytes, each byte representing the value  |
54 | * of one of the components (Y, Cb, or Cr) at a particular location in the  |
55 | * image. The width and height of each plane are determined by the image  |
56 | * width, height, and level of chrominance subsampling. The luminance plane  |
57 | * width is the image width padded to the nearest multiple of the horizontal  |
58 | * subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of  |
59 | * 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane  |
60 | * height is the image height padded to the nearest multiple of the vertical  |
61 | * subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4  |
62 | * or grayscale.) This is irrespective of any additional padding that may be  |
63 | * specified as an argument to the various YUV functions. The chrominance  |
64 | * plane width is equal to the luminance plane width divided by the horizontal  |
65 | * subsampling factor, and the chrominance plane height is equal to the  |
66 | * luminance plane height divided by the vertical subsampling factor.  |
67 | *  |
68 | * For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is  |
69 | * used, then the luminance plane would be 36 x 35 bytes, and each of the  |
70 | * chrominance planes would be 18 x 35 bytes. If you specify a line padding of  |
71 | * 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and  |
72 | * each of the chrominance planes would be 20 x 35 bytes.  |
73 | *  |
74 | * @{  |
75 | */  |
76 |   |
77 |   |
78 | /**  |
79 | * The number of chrominance subsampling options  |
80 | */  |
81 | #define TJ_NUMSAMP 6  |
82 |   |
83 | /**  |
84 | * Chrominance subsampling options.  |
85 | * When pixels are converted from RGB to YCbCr (see #TJCS_YCbCr) or from CMYK  |
86 | * to YCCK (see #TJCS_YCCK) as part of the JPEG compression process, some of  |
87 | * the Cb and Cr (chrominance) components can be discarded or averaged together  |
88 | * to produce a smaller image with little perceptible loss of image clarity  |
89 | * (the human eye is more sensitive to small changes in brightness than to  |
90 | * small changes in color.) This is called "chrominance subsampling".  |
91 | */  |
92 | enum TJSAMP {  |
93 | /**  |
94 | * 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG or  |
95 | * YUV image will contain one chrominance component for every pixel in the  |
96 | * source image.  |
97 | */  |
98 | TJSAMP_444 = 0,  |
99 | /**  |
100 | * 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one  |
101 | * chrominance component for every 2x1 block of pixels in the source image.  |
102 | */  |
103 | TJSAMP_422,  |
104 | /**  |
105 | * 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one  |
106 | * chrominance component for every 2x2 block of pixels in the source image.  |
107 | */  |
108 | TJSAMP_420,  |
109 | /**  |
110 | * Grayscale. The JPEG or YUV image will contain no chrominance components.  |
111 | */  |
112 | TJSAMP_GRAY,  |
113 | /**  |
114 | * 4:4:0 chrominance subsampling. The JPEG or YUV image will contain one  |
115 | * chrominance component for every 1x2 block of pixels in the source image.  |
116 | *  |
117 | * @note 4:4:0 subsampling is not fully accelerated in libjpeg-turbo.  |
118 | */  |
119 | TJSAMP_440,  |
120 | /**  |
121 | * 4:1:1 chrominance subsampling. The JPEG or YUV image will contain one  |
122 | * chrominance component for every 4x1 block of pixels in the source image.  |
123 | * JPEG images compressed with 4:1:1 subsampling will be almost exactly the  |
124 | * same size as those compressed with 4:2:0 subsampling, and in the  |
125 | * aggregate, both subsampling methods produce approximately the same  |
126 | * perceptual quality. However, 4:1:1 is better able to reproduce sharp  |
127 | * horizontal features.  |
128 | *  |
129 | * @note 4:1:1 subsampling is not fully accelerated in libjpeg-turbo.  |
130 | */  |
131 | TJSAMP_411  |
132 | };  |
133 |   |
134 | /**  |
135 | * MCU block width (in pixels) for a given level of chrominance subsampling.  |
136 | * MCU block sizes:  |
137 | * - 8x8 for no subsampling or grayscale  |
138 | * - 16x8 for 4:2:2  |
139 | * - 8x16 for 4:4:0  |
140 | * - 16x16 for 4:2:0  |
141 | * - 32x8 for 4:1:1  |
142 | */  |
143 | static const int tjMCUWidth[TJ_NUMSAMP] = { 8, 16, 16, 8, 8, 32 };  |
144 |   |
145 | /**  |
146 | * MCU block height (in pixels) for a given level of chrominance subsampling.  |
147 | * MCU block sizes:  |
148 | * - 8x8 for no subsampling or grayscale  |
149 | * - 16x8 for 4:2:2  |
150 | * - 8x16 for 4:4:0  |
151 | * - 16x16 for 4:2:0  |
152 | * - 32x8 for 4:1:1  |
153 | */  |
154 | static const int tjMCUHeight[TJ_NUMSAMP] = { 8, 8, 16, 8, 16, 8 };  |
155 |   |
156 |   |
157 | /**  |
158 | * The number of pixel formats  |
159 | */  |
160 | #define TJ_NUMPF 12  |
161 |   |
162 | /**  |
163 | * Pixel formats  |
164 | */  |
165 | enum TJPF {  |
166 | /**  |
167 | * RGB pixel format. The red, green, and blue components in the image are  |
168 | * stored in 3-byte pixels in the order R, G, B from lowest to highest byte  |
169 | * address within each pixel.  |
170 | */  |
171 | TJPF_RGB = 0,  |
172 | /**  |
173 | * BGR pixel format. The red, green, and blue components in the image are  |
174 | * stored in 3-byte pixels in the order B, G, R from lowest to highest byte  |
175 | * address within each pixel.  |
176 | */  |
177 | TJPF_BGR,  |
178 | /**  |
179 | * RGBX pixel format. The red, green, and blue components in the image are  |
180 | * stored in 4-byte pixels in the order R, G, B from lowest to highest byte  |
181 | * address within each pixel. The X component is ignored when compressing  |
182 | * and undefined when decompressing.  |
183 | */  |
184 | TJPF_RGBX,  |
185 | /**  |
186 | * BGRX pixel format. The red, green, and blue components in the image are  |
187 | * stored in 4-byte pixels in the order B, G, R from lowest to highest byte  |
188 | * address within each pixel. The X component is ignored when compressing  |
189 | * and undefined when decompressing.  |
190 | */  |
191 | TJPF_BGRX,  |
192 | /**  |
193 | * XBGR pixel format. The red, green, and blue components in the image are  |
194 | * stored in 4-byte pixels in the order R, G, B from highest to lowest byte  |
195 | * address within each pixel. The X component is ignored when compressing  |
196 | * and undefined when decompressing.  |
197 | */  |
198 | TJPF_XBGR,  |
199 | /**  |
200 | * XRGB pixel format. The red, green, and blue components in the image are  |
201 | * stored in 4-byte pixels in the order B, G, R from highest to lowest byte  |
202 | * address within each pixel. The X component is ignored when compressing  |
203 | * and undefined when decompressing.  |
204 | */  |
205 | TJPF_XRGB,  |
206 | /**  |
207 | * Grayscale pixel format. Each 1-byte pixel represents a luminance  |
208 | * (brightness) level from 0 to 255.  |
209 | */  |
210 | TJPF_GRAY,  |
211 | /**  |
212 | * RGBA pixel format. This is the same as @ref TJPF_RGBX, except that when  |
213 | * decompressing, the X component is guaranteed to be 0xFF, which can be  |
214 | * interpreted as an opaque alpha channel.  |
215 | */  |
216 | TJPF_RGBA,  |
217 | /**  |
218 | * BGRA pixel format. This is the same as @ref TJPF_BGRX, except that when  |
219 | * decompressing, the X component is guaranteed to be 0xFF, which can be  |
220 | * interpreted as an opaque alpha channel.  |
221 | */  |
222 | TJPF_BGRA,  |
223 | /**  |
224 | * ABGR pixel format. This is the same as @ref TJPF_XBGR, except that when  |
225 | * decompressing, the X component is guaranteed to be 0xFF, which can be  |
226 | * interpreted as an opaque alpha channel.  |
227 | */  |
228 | TJPF_ABGR,  |
229 | /**  |
230 | * ARGB pixel format. This is the same as @ref TJPF_XRGB, except that when  |
231 | * decompressing, the X component is guaranteed to be 0xFF, which can be  |
232 | * interpreted as an opaque alpha channel.  |
233 | */  |
234 | TJPF_ARGB,  |
235 | /**  |
236 | * CMYK pixel format. Unlike RGB, which is an additive color model used  |
237 | * primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive  |
238 | * color model used primarily for printing. In the CMYK color model, the  |
239 | * value of each color component typically corresponds to an amount of cyan,  |
240 | * magenta, yellow, or black ink that is applied to a white background. In  |
241 | * order to convert between CMYK and RGB, it is necessary to use a color  |
242 | * management system (CMS.) A CMS will attempt to map colors within the  |
243 | * printer's gamut to perceptually similar colors in the display's gamut and  |
244 | * vice versa, but the mapping is typically not 1:1 or reversible, nor can it  |
245 | * be defined with a simple formula. Thus, such a conversion is out of scope  |
246 | * for a codec library. However, the TurboJPEG API allows for compressing  |
247 | * CMYK pixels into a YCCK JPEG image (see #TJCS_YCCK) and decompressing YCCK  |
248 | * JPEG images into CMYK pixels.  |
249 | */  |
250 | TJPF_CMYK,  |
251 | /**  |
252 | * Unknown pixel format. Currently this is only used by #tjLoadImage().  |
253 | */  |
254 | TJPF_UNKNOWN = -1  |
255 | };  |
256 |   |
257 | /**  |
258 | * Red offset (in bytes) for a given pixel format. This specifies the number  |
259 | * of bytes that the red component is offset from the start of the pixel. For  |
260 | * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,  |
261 | * then the red component will be <tt>pixel[tjRedOffset[TJ_BGRX]]</tt>. This  |
262 | * will be -1 if the pixel format does not have a red component.  |
263 | */  |
264 | static const int tjRedOffset[TJ_NUMPF] = {  |
265 | 0, 2, 0, 2, 3, 1, -1, 0, 2, 3, 1, -1  |
266 | };  |
267 | /**  |
268 | * Green offset (in bytes) for a given pixel format. This specifies the number  |
269 | * of bytes that the green component is offset from the start of the pixel.  |
270 | * For instance, if a pixel of format TJ_BGRX is stored in  |
271 | * <tt>char pixel[]</tt>, then the green component will be  |
272 | * <tt>pixel[tjGreenOffset[TJ_BGRX]]</tt>. This will be -1 if the pixel format  |
273 | * does not have a green component.  |
274 | */  |
275 | static const int tjGreenOffset[TJ_NUMPF] = {  |
276 | 1, 1, 1, 1, 2, 2, -1, 1, 1, 2, 2, -1  |
277 | };  |
278 | /**  |
279 | * Blue offset (in bytes) for a given pixel format. This specifies the number  |
280 | * of bytes that the Blue component is offset from the start of the pixel. For  |
281 | * instance, if a pixel of format TJ_BGRX is stored in <tt>char pixel[]</tt>,  |
282 | * then the blue component will be <tt>pixel[tjBlueOffset[TJ_BGRX]]</tt>. This  |
283 | * will be -1 if the pixel format does not have a blue component.  |
284 | */  |
285 | static const int tjBlueOffset[TJ_NUMPF] = {  |
286 | 2, 0, 2, 0, 1, 3, -1, 2, 0, 1, 3, -1  |
287 | };  |
288 | /**  |
289 | * Alpha offset (in bytes) for a given pixel format. This specifies the number  |
290 | * of bytes that the Alpha component is offset from the start of the pixel.  |
291 | * For instance, if a pixel of format TJ_BGRA is stored in  |
292 | * <tt>char pixel[]</tt>, then the alpha component will be  |
293 | * <tt>pixel[tjAlphaOffset[TJ_BGRA]]</tt>. This will be -1 if the pixel format  |
294 | * does not have an alpha component.  |
295 | */  |
296 | static const int tjAlphaOffset[TJ_NUMPF] = {  |
297 | -1, -1, -1, -1, -1, -1, -1, 3, 3, 0, 0, -1  |
298 | };  |
299 | /**  |
300 | * Pixel size (in bytes) for a given pixel format  |
301 | */  |
302 | static const int tjPixelSize[TJ_NUMPF] = {  |
303 | 3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4, 4  |
304 | };  |
305 |   |
306 |   |
307 | /**  |
308 | * The number of JPEG colorspaces  |
309 | */  |
310 | #define TJ_NUMCS 5  |
311 |   |
312 | /**  |
313 | * JPEG colorspaces  |
314 | */  |
315 | enum TJCS {  |
316 | /**  |
317 | * RGB colorspace. When compressing the JPEG image, the R, G, and B  |
318 | * components in the source image are reordered into image planes, but no  |
319 | * colorspace conversion or subsampling is performed. RGB JPEG images can be  |
320 | * decompressed to any of the extended RGB pixel formats or grayscale, but  |
321 | * they cannot be decompressed to YUV images.  |
322 | */  |
323 | TJCS_RGB = 0,  |
324 | /**  |
325 | * YCbCr colorspace. YCbCr is not an absolute colorspace but rather a  |
326 | * mathematical transformation of RGB designed solely for storage and  |
327 | * transmission. YCbCr images must be converted to RGB before they can  |
328 | * actually be displayed. In the YCbCr colorspace, the Y (luminance)  |
329 | * component represents the black & white portion of the original image, and  |
330 | * the Cb and Cr (chrominance) components represent the color portion of the  |
331 | * original image. Originally, the analog equivalent of this transformation  |
332 | * allowed the same signal to drive both black & white and color televisions,  |
333 | * but JPEG images use YCbCr primarily because it allows the color data to be  |
334 | * optionally subsampled for the purposes of reducing bandwidth or disk  |
335 | * space. YCbCr is the most common JPEG colorspace, and YCbCr JPEG images  |
336 | * can be compressed from and decompressed to any of the extended RGB pixel  |
337 | * formats or grayscale, or they can be decompressed to YUV planar images.  |
338 | */  |
339 | TJCS_YCbCr,  |
340 | /**  |
341 | * Grayscale colorspace. The JPEG image retains only the luminance data (Y  |
342 | * component), and any color data from the source image is discarded.  |
343 | * Grayscale JPEG images can be compressed from and decompressed to any of  |
344 | * the extended RGB pixel formats or grayscale, or they can be decompressed  |
345 | * to YUV planar images.  |
346 | */  |
347 | TJCS_GRAY,  |
348 | /**  |
349 | * CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K  |
350 | * components in the source image are reordered into image planes, but no  |
351 | * colorspace conversion or subsampling is performed. CMYK JPEG images can  |
352 | * only be decompressed to CMYK pixels.  |
353 | */  |
354 | TJCS_CMYK,  |
355 | /**  |
356 | * YCCK colorspace. YCCK (AKA "YCbCrK") is not an absolute colorspace but  |
357 | * rather a mathematical transformation of CMYK designed solely for storage  |
358 | * and transmission. It is to CMYK as YCbCr is to RGB. CMYK pixels can be  |
359 | * reversibly transformed into YCCK, and as with YCbCr, the chrominance  |
360 | * components in the YCCK pixels can be subsampled without incurring major  |
361 | * perceptual loss. YCCK JPEG images can only be compressed from and  |
362 | * decompressed to CMYK pixels.  |
363 | */  |
364 | TJCS_YCCK  |
365 | };  |
366 |   |
367 |   |
368 | /**  |
369 | * The uncompressed source/destination image is stored in bottom-up (Windows,  |
370 | * OpenGL) order, not top-down (X11) order.  |
371 | */  |
372 | #define TJFLAG_BOTTOMUP 2  |
373 | /**  |
374 | * When decompressing an image that was compressed using chrominance  |
375 | * subsampling, use the fastest chrominance upsampling algorithm available in  |
376 | * the underlying codec. The default is to use smooth upsampling, which  |
377 | * creates a smooth transition between neighboring chrominance components in  |
378 | * order to reduce upsampling artifacts in the decompressed image.  |
379 | */  |
380 | #define TJFLAG_FASTUPSAMPLE 256  |
381 | /**  |
382 | * Disable buffer (re)allocation. If passed to one of the JPEG compression or  |
383 | * transform functions, this flag will cause those functions to generate an  |
384 | * error if the JPEG image buffer is invalid or too small rather than  |
385 | * attempting to allocate or reallocate that buffer. This reproduces the  |
386 | * behavior of earlier versions of TurboJPEG.  |
387 | */  |
388 | #define TJFLAG_NOREALLOC 1024  |
389 | /**  |
390 | * Use the fastest DCT/IDCT algorithm available in the underlying codec. The  |
391 | * default if this flag is not specified is implementation-specific. For  |
392 | * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast  |
393 | * algorithm by default when compressing, because this has been shown to have  |
394 | * only a very slight effect on accuracy, but it uses the accurate algorithm  |
395 | * when decompressing, because this has been shown to have a larger effect.  |
396 | */  |
397 | #define TJFLAG_FASTDCT 2048  |
398 | /**  |
399 | * Use the most accurate DCT/IDCT algorithm available in the underlying codec.  |
400 | * The default if this flag is not specified is implementation-specific. For  |
401 | * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast  |
402 | * algorithm by default when compressing, because this has been shown to have  |
403 | * only a very slight effect on accuracy, but it uses the accurate algorithm  |
404 | * when decompressing, because this has been shown to have a larger effect.  |
405 | */  |
406 | #define TJFLAG_ACCURATEDCT 4096  |
407 | /**  |
408 | * Immediately discontinue the current compression/decompression/transform  |
409 | * operation if the underlying codec throws a warning (non-fatal error). The  |
410 | * default behavior is to allow the operation to complete unless a fatal error  |
411 | * is encountered.  |
412 | */  |
413 | #define TJFLAG_STOPONWARNING 8192  |
414 | /**  |
415 | * Use progressive entropy coding in JPEG images generated by the compression  |
416 | * and transform functions. Progressive entropy coding will generally improve  |
417 | * compression relative to baseline entropy coding (the default), but it will  |
418 | * reduce compression and decompression performance considerably.  |
419 | */  |
420 | #define TJFLAG_PROGRESSIVE 16384  |
421 |   |
422 |   |
423 | /**  |
424 | * The number of error codes  |
425 | */  |
426 | #define TJ_NUMERR 2  |
427 |   |
428 | /**  |
429 | * Error codes  |
430 | */  |
431 | enum TJERR {  |
432 | /**  |
433 | * The error was non-fatal and recoverable, but the image may still be  |
434 | * corrupt.  |
435 | */  |
436 | TJERR_WARNING = 0,  |
437 | /**  |
438 | * The error was fatal and non-recoverable.  |
439 | */  |
440 | TJERR_FATAL  |
441 | };  |
442 |   |
443 |   |
444 | /**  |
445 | * The number of transform operations  |
446 | */  |
447 | #define TJ_NUMXOP 8  |
448 |   |
449 | /**  |
450 | * Transform operations for #tjTransform()  |
451 | */  |
452 | enum TJXOP {  |
453 | /**  |
454 | * Do not transform the position of the image pixels  |
455 | */  |
456 | TJXOP_NONE = 0,  |
457 | /**  |
458 | * Flip (mirror) image horizontally. This transform is imperfect if there  |
459 | * are any partial MCU blocks on the right edge (see #TJXOPT_PERFECT.)  |
460 | */  |
461 | TJXOP_HFLIP,  |
462 | /**  |
463 | * Flip (mirror) image vertically. This transform is imperfect if there are  |
464 | * any partial MCU blocks on the bottom edge (see #TJXOPT_PERFECT.)  |
465 | */  |
466 | TJXOP_VFLIP,  |
467 | /**  |
468 | * Transpose image (flip/mirror along upper left to lower right axis.) This  |
469 | * transform is always perfect.  |
470 | */  |
471 | TJXOP_TRANSPOSE,  |
472 | /**  |
473 | * Transverse transpose image (flip/mirror along upper right to lower left  |
474 | * axis.) This transform is imperfect if there are any partial MCU blocks in  |
475 | * the image (see #TJXOPT_PERFECT.)  |
476 | */  |
477 | TJXOP_TRANSVERSE,  |
478 | /**  |
479 | * Rotate image clockwise by 90 degrees. This transform is imperfect if  |
480 | * there are any partial MCU blocks on the bottom edge (see  |
481 | * #TJXOPT_PERFECT.)  |
482 | */  |
483 | TJXOP_ROT90,  |
484 | /**  |
485 | * Rotate image 180 degrees. This transform is imperfect if there are any  |
486 | * partial MCU blocks in the image (see #TJXOPT_PERFECT.)  |
487 | */  |
488 | TJXOP_ROT180,  |
489 | /**  |
490 | * Rotate image counter-clockwise by 90 degrees. This transform is imperfect  |
491 | * if there are any partial MCU blocks on the right edge (see  |
492 | * #TJXOPT_PERFECT.)  |
493 | */  |
494 | TJXOP_ROT270  |
495 | };  |
496 |   |
497 |   |
498 | /**  |
499 | * This option will cause #tjTransform() to return an error if the transform is  |
500 | * not perfect. Lossless transforms operate on MCU blocks, whose size depends  |
501 | * on the level of chrominance subsampling used (see #tjMCUWidth  |
502 | * and #tjMCUHeight.) If the image's width or height is not evenly divisible  |
503 | * by the MCU block size, then there will be partial MCU blocks on the right  |
504 | * and/or bottom edges. It is not possible to move these partial MCU blocks to  |
505 | * the top or left of the image, so any transform that would require that is  |
506 | * "imperfect." If this option is not specified, then any partial MCU blocks  |
507 | * that cannot be transformed will be left in place, which will create  |
508 | * odd-looking strips on the right or bottom edge of the image.  |
509 | */  |
510 | #define TJXOPT_PERFECT 1  |
511 | /**  |
512 | * This option will cause #tjTransform() to discard any partial MCU blocks that  |
513 | * cannot be transformed.  |
514 | */  |
515 | #define TJXOPT_TRIM 2  |
516 | /**  |
517 | * This option will enable lossless cropping. See #tjTransform() for more  |
518 | * information.  |
519 | */  |
520 | #define TJXOPT_CROP 4  |
521 | /**  |
522 | * This option will discard the color data in the input image and produce  |
523 | * a grayscale output image.  |
524 | */  |
525 | #define TJXOPT_GRAY 8  |
526 | /**  |
527 | * This option will prevent #tjTransform() from outputting a JPEG image for  |
528 | * this particular transform (this can be used in conjunction with a custom  |
529 | * filter to capture the transformed DCT coefficients without transcoding  |
530 | * them.)  |
531 | */  |
532 | #define TJXOPT_NOOUTPUT 16  |
533 | /**  |
534 | * This option will enable progressive entropy coding in the output image  |
535 | * generated by this particular transform. Progressive entropy coding will  |
536 | * generally improve compression relative to baseline entropy coding (the  |
537 | * default), but it will reduce compression and decompression performance  |
538 | * considerably.  |
539 | */  |
540 | #define TJXOPT_PROGRESSIVE 32  |
541 | /**  |
542 | * This option will prevent #tjTransform() from copying any extra markers  |
543 | * (including EXIF and ICC profile data) from the source image to the output  |
544 | * image.  |
545 | */  |
546 | #define TJXOPT_COPYNONE 64  |
547 |   |
548 |   |
549 | /**  |
550 | * Scaling factor  |
551 | */  |
552 | typedef struct {  |
553 | /**  |
554 | * Numerator  |
555 | */  |
556 | int num;  |
557 | /**  |
558 | * Denominator  |
559 | */  |
560 | int denom;  |
561 | } tjscalingfactor;  |
562 |   |
563 | /**  |
564 | * Cropping region  |
565 | */  |
566 | typedef struct {  |
567 | /**  |
568 | * The left boundary of the cropping region. This must be evenly divisible  |
569 | * by the MCU block width (see #tjMCUWidth.)  |
570 | */  |
571 | int x;  |
572 | /**  |
573 | * The upper boundary of the cropping region. This must be evenly divisible  |
574 | * by the MCU block height (see #tjMCUHeight.)  |
575 | */  |
576 | int y;  |
577 | /**  |
578 | * The width of the cropping region. Setting this to 0 is the equivalent of  |
579 | * setting it to the width of the source JPEG image - x.  |
580 | */  |
581 | int w;  |
582 | /**  |
583 | * The height of the cropping region. Setting this to 0 is the equivalent of  |
584 | * setting it to the height of the source JPEG image - y.  |
585 | */  |
586 | int h;  |
587 | } tjregion;  |
588 |   |
589 | /**  |
590 | * Lossless transform  |
591 | */  |
592 | typedef struct tjtransform {  |
593 | /**  |
594 | * Cropping region  |
595 | */  |
596 | tjregion r;  |
597 | /**  |
598 | * One of the @ref TJXOP "transform operations"  |
599 | */  |
600 | int op;  |
601 | /**  |
602 | * The bitwise OR of one of more of the @ref TJXOPT_CROP "transform options"  |
603 | */  |
604 | int options;  |
605 | /**  |
606 | * Arbitrary data that can be accessed within the body of the callback  |
607 | * function  |
608 | */  |
609 | void *data;  |
610 | /**  |
611 | * A callback function that can be used to modify the DCT coefficients  |
612 | * after they are losslessly transformed but before they are transcoded to a  |
613 | * new JPEG image. This allows for custom filters or other transformations  |
614 | * to be applied in the frequency domain.  |
615 | *  |
616 | * @param coeffs pointer to an array of transformed DCT coefficients. (NOTE:  |
617 | * this pointer is not guaranteed to be valid once the callback returns, so  |
618 | * applications wishing to hand off the DCT coefficients to another function  |
619 | * or library should make a copy of them within the body of the callback.)  |
620 | *  |
621 | * @param arrayRegion #tjregion structure containing the width and height of  |
622 | * the array pointed to by <tt>coeffs</tt> as well as its offset relative to  |
623 | * the component plane. TurboJPEG implementations may choose to split each  |
624 | * component plane into multiple DCT coefficient arrays and call the callback  |
625 | * function once for each array.  |
626 | *  |
627 | * @param planeRegion #tjregion structure containing the width and height of  |
628 | * the component plane to which <tt>coeffs</tt> belongs  |
629 | *  |
630 | * @param componentID ID number of the component plane to which  |
631 | * <tt>coeffs</tt> belongs (Y, Cb, and Cr have, respectively, ID's of 0, 1,  |
632 | * and 2 in typical JPEG images.)  |
633 | *  |
634 | * @param transformID ID number of the transformed image to which  |
635 | * <tt>coeffs</tt> belongs. This is the same as the index of the transform  |
636 | * in the <tt>transforms</tt> array that was passed to #tjTransform().  |
637 | *  |
638 | * @param transform a pointer to a #tjtransform structure that specifies the  |
639 | * parameters and/or cropping region for this transform  |
640 | *  |
641 | * @return 0 if the callback was successful, or -1 if an error occurred.  |
642 | */  |
643 | int (*customFilter) (short *coeffs, tjregion arrayRegion,  |
644 | tjregion planeRegion, int componentIndex,  |
645 | int transformIndex, struct tjtransform *transform);  |
646 | } tjtransform;  |
647 |   |
648 | /**  |
649 | * TurboJPEG instance handle  |
650 | */  |
651 | typedef void *tjhandle;  |
652 |   |
653 |   |
654 | /**  |
655 | * Pad the given width to the nearest 32-bit boundary  |
656 | */  |
657 | #define TJPAD(width) (((width) + 3) & (~3))  |
658 |   |
659 | /**  |
660 | * Compute the scaled value of <tt>dimension</tt> using the given scaling  |
661 | * factor. This macro performs the integer equivalent of <tt>ceil(dimension *  |
662 | * scalingFactor)</tt>.  |
663 | */  |
664 | #define TJSCALED(dimension, scalingFactor) \  |
665 | ((dimension * scalingFactor.num + scalingFactor.denom - 1) / \  |
666 | scalingFactor.denom)  |
667 |   |
668 |   |
669 | #ifdef __cplusplus  |
670 | extern "C" {  |
671 | #endif  |
672 |   |
673 |   |
674 | /**  |
675 | * Create a TurboJPEG compressor instance.  |
676 | *  |
677 | * @return a handle to the newly-created instance, or NULL if an error  |
678 | * occurred (see #tjGetErrorStr2().)  |
679 | */  |
680 | DLLEXPORT tjhandle tjInitCompress(void);  |
681 |   |
682 |   |
683 | /**  |
684 | * Compress an RGB, grayscale, or CMYK image into a JPEG image.  |
685 | *  |
686 | * @param handle a handle to a TurboJPEG compressor or transformer instance  |
687 | *  |
688 | * @param srcBuf pointer to an image buffer containing RGB, grayscale, or  |
689 | * CMYK pixels to be compressed  |
690 | *  |
691 | * @param width width (in pixels) of the source image  |
692 | *  |
693 | * @param pitch bytes per line in the source image. Normally, this should be  |
694 | * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or  |
695 | * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image  |
696 | * is padded to the nearest 32-bit boundary, as is the case for Windows  |
697 | * bitmaps. You can also be clever and use this parameter to skip lines, etc.  |
698 | * Setting this parameter to 0 is the equivalent of setting it to  |
699 | * <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
700 | *  |
701 | * @param height height (in pixels) of the source image  |
702 | *  |
703 | * @param pixelFormat pixel format of the source image (see @ref TJPF  |
704 | * "Pixel formats".)  |
705 | *  |
706 | * @param jpegBuf address of a pointer to an image buffer that will receive the  |
707 | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer  |
708 | * to accommodate the size of the JPEG image. Thus, you can choose to:  |
709 | * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and  |
710 | * let TurboJPEG grow the buffer as needed,  |
711 | * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer  |
712 | * for you, or  |
713 | * -# pre-allocate the buffer to a "worst case" size determined by calling  |
714 | * #tjBufSize(). This should ensure that the buffer never has to be  |
715 | * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.)  |
716 | * .  |
717 | * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your  |
718 | * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC,  |
719 | * you should always check <tt>*jpegBuf</tt> upon return from this function, as  |
720 | * it may have changed.  |
721 | *  |
722 | * @param jpegSize pointer to an unsigned long variable that holds the size of  |
723 | * the JPEG image buffer. If <tt>*jpegBuf</tt> points to a pre-allocated  |
724 | * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.  |
725 | * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in  |
726 | * bytes.) If <tt>*jpegBuf</tt> points to a JPEG image buffer that is being  |
727 | * reused from a previous call to one of the JPEG compression functions, then  |
728 | * <tt>*jpegSize</tt> is ignored.  |
729 | *  |
730 | * @param jpegSubsamp the level of chrominance subsampling to be used when  |
731 | * generating the JPEG image (see @ref TJSAMP  |
732 | * "Chrominance subsampling options".)  |
733 | *  |
734 | * @param jpegQual the image quality of the generated JPEG image (1 = worst,  |
735 | * 100 = best)  |
736 | *  |
737 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
738 | * "flags"  |
739 | *  |
740 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
741 | * and #tjGetErrorCode().)  |
742 | */  |
743 | DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf,  |
744 | int width, int pitch, int height, int pixelFormat,  |
745 | unsigned char **jpegBuf, unsigned long *jpegSize,  |
746 | int jpegSubsamp, int jpegQual, int flags);  |
747 |   |
748 |   |
749 | /**  |
750 | * Compress a YUV planar image into a JPEG image.  |
751 | *  |
752 | * @param handle a handle to a TurboJPEG compressor or transformer instance  |
753 | *  |
754 | * @param srcBuf pointer to an image buffer containing a YUV planar image to be  |
755 | * compressed. The size of this buffer should match the value returned by  |
756 | * #tjBufSizeYUV2() for the given image width, height, padding, and level of  |
757 | * chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be  |
758 | * stored sequentially in the source buffer (refer to @ref YUVnotes  |
759 | * "YUV Image Format Notes".)  |
760 | *  |
761 | * @param width width (in pixels) of the source image. If the width is not an  |
762 | * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate  |
763 | * buffer copy will be performed within TurboJPEG.  |
764 | *  |
765 | * @param pad the line padding used in the source image. For instance, if each  |
766 | * line in each plane of the YUV image is padded to the nearest multiple of 4  |
767 | * bytes, then <tt>pad</tt> should be set to 4.  |
768 | *  |
769 | * @param height height (in pixels) of the source image. If the height is not  |
770 | * an even multiple of the MCU block height (see #tjMCUHeight), then an  |
771 | * intermediate buffer copy will be performed within TurboJPEG.  |
772 | *  |
773 | * @param subsamp the level of chrominance subsampling used in the source  |
774 | * image (see @ref TJSAMP "Chrominance subsampling options".)  |
775 | *  |
776 | * @param jpegBuf address of a pointer to an image buffer that will receive the  |
777 | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to  |
778 | * accommodate the size of the JPEG image. Thus, you can choose to:  |
779 | * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and  |
780 | * let TurboJPEG grow the buffer as needed,  |
781 | * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer  |
782 | * for you, or  |
783 | * -# pre-allocate the buffer to a "worst case" size determined by calling  |
784 | * #tjBufSize(). This should ensure that the buffer never has to be  |
785 | * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.)  |
786 | * .  |
787 | * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your  |
788 | * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC,  |
789 | * you should always check <tt>*jpegBuf</tt> upon return from this function, as  |
790 | * it may have changed.  |
791 | *  |
792 | * @param jpegSize pointer to an unsigned long variable that holds the size of  |
793 | * the JPEG image buffer. If <tt>*jpegBuf</tt> points to a pre-allocated  |
794 | * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.  |
795 | * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in  |
796 | * bytes.) If <tt>*jpegBuf</tt> points to a JPEG image buffer that is being  |
797 | * reused from a previous call to one of the JPEG compression functions, then  |
798 | * <tt>*jpegSize</tt> is ignored.  |
799 | *  |
800 | * @param jpegQual the image quality of the generated JPEG image (1 = worst,  |
801 | * 100 = best)  |
802 | *  |
803 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
804 | * "flags"  |
805 | *  |
806 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
807 | * and #tjGetErrorCode().)  |
808 | */  |
809 | DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf,  |
810 | int width, int pad, int height, int subsamp,  |
811 | unsigned char **jpegBuf,  |
812 | unsigned long *jpegSize, int jpegQual,  |
813 | int flags);  |
814 |   |
815 |   |
816 | /**  |
817 | * Compress a set of Y, U (Cb), and V (Cr) image planes into a JPEG image.  |
818 | *  |
819 | * @param handle a handle to a TurboJPEG compressor or transformer instance  |
820 | *  |
821 | * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes  |
822 | * (or just a Y plane, if compressing a grayscale image) that contain a YUV  |
823 | * image to be compressed. These planes can be contiguous or non-contiguous in  |
824 | * memory. The size of each plane should match the value returned by  |
825 | * #tjPlaneSizeYUV() for the given image width, height, strides, and level of  |
826 | * chrominance subsampling. Refer to @ref YUVnotes "YUV Image Format Notes"  |
827 | * for more details.  |
828 | *  |
829 | * @param width width (in pixels) of the source image. If the width is not an  |
830 | * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate  |
831 | * buffer copy will be performed within TurboJPEG.  |
832 | *  |
833 | * @param strides an array of integers, each specifying the number of bytes per  |
834 | * line in the corresponding plane of the YUV source image. Setting the stride  |
835 | * for any plane to 0 is the same as setting it to the plane width (see  |
836 | * @ref YUVnotes "YUV Image Format Notes".) If <tt>strides</tt> is NULL, then  |
837 | * the strides for all planes will be set to their respective plane widths.  |
838 | * You can adjust the strides in order to specify an arbitrary amount of line  |
839 | * padding in each plane or to create a JPEG image from a subregion of a larger  |
840 | * YUV planar image.  |
841 | *  |
842 | * @param height height (in pixels) of the source image. If the height is not  |
843 | * an even multiple of the MCU block height (see #tjMCUHeight), then an  |
844 | * intermediate buffer copy will be performed within TurboJPEG.  |
845 | *  |
846 | * @param subsamp the level of chrominance subsampling used in the source  |
847 | * image (see @ref TJSAMP "Chrominance subsampling options".)  |
848 | *  |
849 | * @param jpegBuf address of a pointer to an image buffer that will receive the  |
850 | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to  |
851 | * accommodate the size of the JPEG image. Thus, you can choose to:  |
852 | * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and  |
853 | * let TurboJPEG grow the buffer as needed,  |
854 | * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the buffer  |
855 | * for you, or  |
856 | * -# pre-allocate the buffer to a "worst case" size determined by calling  |
857 | * #tjBufSize(). This should ensure that the buffer never has to be  |
858 | * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.)  |
859 | * .  |
860 | * If you choose option 1, <tt>*jpegSize</tt> should be set to the size of your  |
861 | * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC,  |
862 | * you should always check <tt>*jpegBuf</tt> upon return from this function, as  |
863 | * it may have changed.  |
864 | *  |
865 | * @param jpegSize pointer to an unsigned long variable that holds the size of  |
866 | * the JPEG image buffer. If <tt>*jpegBuf</tt> points to a pre-allocated  |
867 | * buffer, then <tt>*jpegSize</tt> should be set to the size of the buffer.  |
868 | * Upon return, <tt>*jpegSize</tt> will contain the size of the JPEG image (in  |
869 | * bytes.) If <tt>*jpegBuf</tt> points to a JPEG image buffer that is being  |
870 | * reused from a previous call to one of the JPEG compression functions, then  |
871 | * <tt>*jpegSize</tt> is ignored.  |
872 | *  |
873 | * @param jpegQual the image quality of the generated JPEG image (1 = worst,  |
874 | * 100 = best)  |
875 | *  |
876 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
877 | * "flags"  |
878 | *  |
879 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
880 | * and #tjGetErrorCode().)  |
881 | */  |
882 | DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle,  |
883 | const unsigned char **srcPlanes,  |
884 | int width, const int *strides,  |
885 | int height, int subsamp,  |
886 | unsigned char **jpegBuf,  |
887 | unsigned long *jpegSize, int jpegQual,  |
888 | int flags);  |
889 |   |
890 |   |
891 | /**  |
892 | * The maximum size of the buffer (in bytes) required to hold a JPEG image with  |
893 | * the given parameters. The number of bytes returned by this function is  |
894 | * larger than the size of the uncompressed source image. The reason for this  |
895 | * is that the JPEG format uses 16-bit coefficients, and it is thus possible  |
896 | * for a very high-quality JPEG image with very high-frequency content to  |
897 | * expand rather than compress when converted to the JPEG format. Such images  |
898 | * represent a very rare corner case, but since there is no way to predict the  |
899 | * size of a JPEG image prior to compression, the corner case has to be  |
900 | * handled.  |
901 | *  |
902 | * @param width width (in pixels) of the image  |
903 | *  |
904 | * @param height height (in pixels) of the image  |
905 | *  |
906 | * @param jpegSubsamp the level of chrominance subsampling to be used when  |
907 | * generating the JPEG image (see @ref TJSAMP  |
908 | * "Chrominance subsampling options".)  |
909 | *  |
910 | * @return the maximum size of the buffer (in bytes) required to hold the  |
911 | * image, or -1 if the arguments are out of bounds.  |
912 | */  |
913 | DLLEXPORT unsigned long tjBufSize(int width, int height, int jpegSubsamp);  |
914 |   |
915 |   |
916 | /**  |
917 | * The size of the buffer (in bytes) required to hold a YUV planar image with  |
918 | * the given parameters.  |
919 | *  |
920 | * @param width width (in pixels) of the image  |
921 | *  |
922 | * @param pad the width of each line in each plane of the image is padded to  |
923 | * the nearest multiple of this number of bytes (must be a power of 2.)  |
924 | *  |
925 | * @param height height (in pixels) of the image  |
926 | *  |
927 | * @param subsamp level of chrominance subsampling in the image (see  |
928 | * @ref TJSAMP "Chrominance subsampling options".)  |
929 | *  |
930 | * @return the size of the buffer (in bytes) required to hold the image, or  |
931 | * -1 if the arguments are out of bounds.  |
932 | */  |
933 | DLLEXPORT unsigned long tjBufSizeYUV2(int width, int pad, int height,  |
934 | int subsamp);  |
935 |   |
936 |   |
937 | /**  |
938 | * The size of the buffer (in bytes) required to hold a YUV image plane with  |
939 | * the given parameters.  |
940 | *  |
941 | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr)  |
942 | *  |
943 | * @param width width (in pixels) of the YUV image. NOTE: this is the width of  |
944 | * the whole image, not the plane width.  |
945 | *  |
946 | * @param stride bytes per line in the image plane. Setting this to 0 is the  |
947 | * equivalent of setting it to the plane width.  |
948 | *  |
949 | * @param height height (in pixels) of the YUV image. NOTE: this is the height  |
950 | * of the whole image, not the plane height.  |
951 | *  |
952 | * @param subsamp level of chrominance subsampling in the image (see  |
953 | * @ref TJSAMP "Chrominance subsampling options".)  |
954 | *  |
955 | * @return the size of the buffer (in bytes) required to hold the YUV image  |
956 | * plane, or -1 if the arguments are out of bounds.  |
957 | */  |
958 | DLLEXPORT unsigned long tjPlaneSizeYUV(int componentID, int width, int stride,  |
959 | int height, int subsamp);  |
960 |   |
961 |   |
962 | /**  |
963 | * The plane width of a YUV image plane with the given parameters. Refer to  |
964 | * @ref YUVnotes "YUV Image Format Notes" for a description of plane width.  |
965 | *  |
966 | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr)  |
967 | *  |
968 | * @param width width (in pixels) of the YUV image  |
969 | *  |
970 | * @param subsamp level of chrominance subsampling in the image (see  |
971 | * @ref TJSAMP "Chrominance subsampling options".)  |
972 | *  |
973 | * @return the plane width of a YUV image plane with the given parameters, or  |
974 | * -1 if the arguments are out of bounds.  |
975 | */  |
976 | DLLEXPORT int tjPlaneWidth(int componentID, int width, int subsamp);  |
977 |   |
978 |   |
979 | /**  |
980 | * The plane height of a YUV image plane with the given parameters. Refer to  |
981 | * @ref YUVnotes "YUV Image Format Notes" for a description of plane height.  |
982 | *  |
983 | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr)  |
984 | *  |
985 | * @param height height (in pixels) of the YUV image  |
986 | *  |
987 | * @param subsamp level of chrominance subsampling in the image (see  |
988 | * @ref TJSAMP "Chrominance subsampling options".)  |
989 | *  |
990 | * @return the plane height of a YUV image plane with the given parameters, or  |
991 | * -1 if the arguments are out of bounds.  |
992 | */  |
993 | DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp);  |
994 |   |
995 |   |
996 | /**  |
997 | * Encode an RGB or grayscale image into a YUV planar image. This function  |
998 | * uses the accelerated color conversion routines in the underlying  |
999 | * codec but does not execute any of the other steps in the JPEG compression  |
1000 | * process.  |
1001 | *  |
1002 | * @param handle a handle to a TurboJPEG compressor or transformer instance  |
1003 | *  |
1004 | * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels  |
1005 | * to be encoded  |
1006 | *  |
1007 | * @param width width (in pixels) of the source image  |
1008 | *  |
1009 | * @param pitch bytes per line in the source image. Normally, this should be  |
1010 | * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or  |
1011 | * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image  |
1012 | * is padded to the nearest 32-bit boundary, as is the case for Windows  |
1013 | * bitmaps. You can also be clever and use this parameter to skip lines, etc.  |
1014 | * Setting this parameter to 0 is the equivalent of setting it to  |
1015 | * <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
1016 | *  |
1017 | * @param height height (in pixels) of the source image  |
1018 | *  |
1019 | * @param pixelFormat pixel format of the source image (see @ref TJPF  |
1020 | * "Pixel formats".)  |
1021 | *  |
1022 | * @param dstBuf pointer to an image buffer that will receive the YUV image.  |
1023 | * Use #tjBufSizeYUV2() to determine the appropriate size for this buffer based  |
1024 | * on the image width, height, padding, and level of chrominance subsampling.  |
1025 | * The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the  |
1026 | * buffer (refer to @ref YUVnotes "YUV Image Format Notes".)  |
1027 | *  |
1028 | * @param pad the width of each line in each plane of the YUV image will be  |
1029 | * padded to the nearest multiple of this number of bytes (must be a power of  |
1030 | * 2.) To generate images suitable for X Video, <tt>pad</tt> should be set to  |
1031 | * 4.  |
1032 | *  |
1033 | * @param subsamp the level of chrominance subsampling to be used when  |
1034 | * generating the YUV image (see @ref TJSAMP  |
1035 | * "Chrominance subsampling options".) To generate images suitable for X  |
1036 | * Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420. This produces an  |
1037 | * image compatible with the I420 (AKA "YUV420P") format.  |
1038 | *  |
1039 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1040 | * "flags"  |
1041 | *  |
1042 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1043 | * and #tjGetErrorCode().)  |
1044 | */  |
1045 | DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf,  |
1046 | int width, int pitch, int height, int pixelFormat,  |
1047 | unsigned char *dstBuf, int pad, int subsamp,  |
1048 | int flags);  |
1049 |   |
1050 |   |
1051 | /**  |
1052 | * Encode an RGB or grayscale image into separate Y, U (Cb), and V (Cr) image  |
1053 | * planes. This function uses the accelerated color conversion routines in the  |
1054 | * underlying codec but does not execute any of the other steps in the JPEG  |
1055 | * compression process.  |
1056 | *  |
1057 | * @param handle a handle to a TurboJPEG compressor or transformer instance  |
1058 | *  |
1059 | * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels  |
1060 | * to be encoded  |
1061 | *  |
1062 | * @param width width (in pixels) of the source image  |
1063 | *  |
1064 | * @param pitch bytes per line in the source image. Normally, this should be  |
1065 | * <tt>width * #tjPixelSize[pixelFormat]</tt> if the image is unpadded, or  |
1066 | * <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line of the image  |
1067 | * is padded to the nearest 32-bit boundary, as is the case for Windows  |
1068 | * bitmaps. You can also be clever and use this parameter to skip lines, etc.  |
1069 | * Setting this parameter to 0 is the equivalent of setting it to  |
1070 | * <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
1071 | *  |
1072 | * @param height height (in pixels) of the source image  |
1073 | *  |
1074 | * @param pixelFormat pixel format of the source image (see @ref TJPF  |
1075 | * "Pixel formats".)  |
1076 | *  |
1077 | * @param dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes  |
1078 | * (or just a Y plane, if generating a grayscale image) that will receive the  |
1079 | * encoded image. These planes can be contiguous or non-contiguous in memory.  |
1080 | * Use #tjPlaneSizeYUV() to determine the appropriate size for each plane based  |
1081 | * on the image width, height, strides, and level of chrominance subsampling.  |
1082 | * Refer to @ref YUVnotes "YUV Image Format Notes" for more details.  |
1083 | *  |
1084 | * @param strides an array of integers, each specifying the number of bytes per  |
1085 | * line in the corresponding plane of the output image. Setting the stride for  |
1086 | * any plane to 0 is the same as setting it to the plane width (see  |
1087 | * @ref YUVnotes "YUV Image Format Notes".) If <tt>strides</tt> is NULL, then  |
1088 | * the strides for all planes will be set to their respective plane widths.  |
1089 | * You can adjust the strides in order to add an arbitrary amount of line  |
1090 | * padding to each plane or to encode an RGB or grayscale image into a  |
1091 | * subregion of a larger YUV planar image.  |
1092 | *  |
1093 | * @param subsamp the level of chrominance subsampling to be used when  |
1094 | * generating the YUV image (see @ref TJSAMP  |
1095 | * "Chrominance subsampling options".) To generate images suitable for X  |
1096 | * Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420. This produces an  |
1097 | * image compatible with the I420 (AKA "YUV420P") format.  |
1098 | *  |
1099 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1100 | * "flags"  |
1101 | *  |
1102 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1103 | * and #tjGetErrorCode().)  |
1104 | */  |
1105 | DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf,  |
1106 | int width, int pitch, int height,  |
1107 | int pixelFormat, unsigned char **dstPlanes,  |
1108 | int *strides, int subsamp, int flags);  |
1109 |   |
1110 |   |
1111 | /**  |
1112 | * Create a TurboJPEG decompressor instance.  |
1113 | *  |
1114 | * @return a handle to the newly-created instance, or NULL if an error  |
1115 | * occurred (see #tjGetErrorStr2().)  |
1116 | */  |
1117 | DLLEXPORT tjhandle tjInitDecompress(void);  |
1118 |   |
1119 |   |
1120 | /**  |
1121 | * Retrieve information about a JPEG image without decompressing it.  |
1122 | *  |
1123 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1124 | *  |
1125 | * @param jpegBuf pointer to a buffer containing a JPEG image  |
1126 | *  |
1127 | * @param jpegSize size of the JPEG image (in bytes)  |
1128 | *  |
1129 | * @param width pointer to an integer variable that will receive the width (in  |
1130 | * pixels) of the JPEG image  |
1131 | *  |
1132 | * @param height pointer to an integer variable that will receive the height  |
1133 | * (in pixels) of the JPEG image  |
1134 | *  |
1135 | * @param jpegSubsamp pointer to an integer variable that will receive the  |
1136 | * level of chrominance subsampling used when the JPEG image was compressed  |
1137 | * (see @ref TJSAMP "Chrominance subsampling options".)  |
1138 | *  |
1139 | * @param jpegColorspace pointer to an integer variable that will receive one  |
1140 | * of the JPEG colorspace constants, indicating the colorspace of the JPEG  |
1141 | * image (see @ref TJCS "JPEG colorspaces".)  |
1142 | *  |
1143 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1144 | * and #tjGetErrorCode().)  |
1145 | */  |
1146 | DLLEXPORT int (tjhandle handle,  |
1147 | const unsigned char *jpegBuf,  |
1148 | unsigned long jpegSize, int *width,  |
1149 | int *height, int *jpegSubsamp,  |
1150 | int *jpegColorspace);  |
1151 |   |
1152 |   |
1153 | /**  |
1154 | * Returns a list of fractional scaling factors that the JPEG decompressor in  |
1155 | * this implementation of TurboJPEG supports.  |
1156 | *  |
1157 | * @param numscalingfactors pointer to an integer variable that will receive  |
1158 | * the number of elements in the list  |
1159 | *  |
1160 | * @return a pointer to a list of fractional scaling factors, or NULL if an  |
1161 | * error is encountered (see #tjGetErrorStr2().)  |
1162 | */  |
1163 | DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numscalingfactors);  |
1164 |   |
1165 |   |
1166 | /**  |
1167 | * Decompress a JPEG image to an RGB, grayscale, or CMYK image.  |
1168 | *  |
1169 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1170 | *  |
1171 | * @param jpegBuf pointer to a buffer containing the JPEG image to decompress  |
1172 | *  |
1173 | * @param jpegSize size of the JPEG image (in bytes)  |
1174 | *  |
1175 | * @param dstBuf pointer to an image buffer that will receive the decompressed  |
1176 | * image. This buffer should normally be <tt>pitch * scaledHeight</tt> bytes  |
1177 | * in size, where <tt>scaledHeight</tt> can be determined by calling  |
1178 | * #TJSCALED() with the JPEG image height and one of the scaling factors  |
1179 | * returned by #tjGetScalingFactors(). The <tt>dstBuf</tt> pointer may also be  |
1180 | * used to decompress into a specific region of a larger buffer.  |
1181 | *  |
1182 | * @param width desired width (in pixels) of the destination image. If this is  |
1183 | * different than the width of the JPEG image being decompressed, then  |
1184 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1185 | * possible image that will fit within the desired width. If <tt>width</tt> is  |
1186 | * set to 0, then only the height will be considered when determining the  |
1187 | * scaled image size.  |
1188 | *  |
1189 | * @param pitch bytes per line in the destination image. Normally, this is  |
1190 | * <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt> if the decompressed image  |
1191 | * is unpadded, else <tt>#TJPAD(scaledWidth * #tjPixelSize[pixelFormat])</tt>  |
1192 | * if each line of the decompressed image is padded to the nearest 32-bit  |
1193 | * boundary, as is the case for Windows bitmaps. (NOTE: <tt>scaledWidth</tt>  |
1194 | * can be determined by calling #TJSCALED() with the JPEG image width and one  |
1195 | * of the scaling factors returned by #tjGetScalingFactors().) You can also be  |
1196 | * clever and use the pitch parameter to skip lines, etc. Setting this  |
1197 | * parameter to 0 is the equivalent of setting it to  |
1198 | * <tt>scaledWidth * #tjPixelSize[pixelFormat]</tt>.  |
1199 | *  |
1200 | * @param height desired height (in pixels) of the destination image. If this  |
1201 | * is different than the height of the JPEG image being decompressed, then  |
1202 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1203 | * possible image that will fit within the desired height. If <tt>height</tt>  |
1204 | * is set to 0, then only the width will be considered when determining the  |
1205 | * scaled image size.  |
1206 | *  |
1207 | * @param pixelFormat pixel format of the destination image (see @ref  |
1208 | * TJPF "Pixel formats".)  |
1209 | *  |
1210 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1211 | * "flags"  |
1212 | *  |
1213 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1214 | * and #tjGetErrorCode().)  |
1215 | */  |
1216 | DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf,  |
1217 | unsigned long jpegSize, unsigned char *dstBuf,  |
1218 | int width, int pitch, int height, int pixelFormat,  |
1219 | int flags);  |
1220 |   |
1221 |   |
1222 | /**  |
1223 | * Decompress a JPEG image to a YUV planar image. This function performs JPEG  |
1224 | * decompression but leaves out the color conversion step, so a planar YUV  |
1225 | * image is generated instead of an RGB image.  |
1226 | *  |
1227 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1228 | *  |
1229 | * @param jpegBuf pointer to a buffer containing the JPEG image to decompress  |
1230 | *  |
1231 | * @param jpegSize size of the JPEG image (in bytes)  |
1232 | *  |
1233 | * @param dstBuf pointer to an image buffer that will receive the YUV image.  |
1234 | * Use #tjBufSizeYUV2() to determine the appropriate size for this buffer based  |
1235 | * on the image width, height, padding, and level of subsampling. The Y,  |
1236 | * U (Cb), and V (Cr) image planes will be stored sequentially in the buffer  |
1237 | * (refer to @ref YUVnotes "YUV Image Format Notes".)  |
1238 | *  |
1239 | * @param width desired width (in pixels) of the YUV image. If this is  |
1240 | * different than the width of the JPEG image being decompressed, then  |
1241 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1242 | * possible image that will fit within the desired width. If <tt>width</tt> is  |
1243 | * set to 0, then only the height will be considered when determining the  |
1244 | * scaled image size. If the scaled width is not an even multiple of the MCU  |
1245 | * block width (see #tjMCUWidth), then an intermediate buffer copy will be  |
1246 | * performed within TurboJPEG.  |
1247 | *  |
1248 | * @param pad the width of each line in each plane of the YUV image will be  |
1249 | * padded to the nearest multiple of this number of bytes (must be a power of  |
1250 | * 2.) To generate images suitable for X Video, <tt>pad</tt> should be set to  |
1251 | * 4.  |
1252 | *  |
1253 | * @param height desired height (in pixels) of the YUV image. If this is  |
1254 | * different than the height of the JPEG image being decompressed, then  |
1255 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1256 | * possible image that will fit within the desired height. If <tt>height</tt>  |
1257 | * is set to 0, then only the width will be considered when determining the  |
1258 | * scaled image size. If the scaled height is not an even multiple of the MCU  |
1259 | * block height (see #tjMCUHeight), then an intermediate buffer copy will be  |
1260 | * performed within TurboJPEG.  |
1261 | *  |
1262 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1263 | * "flags"  |
1264 | *  |
1265 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1266 | * and #tjGetErrorCode().)  |
1267 | */  |
1268 | DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,  |
1269 | unsigned long jpegSize, unsigned char *dstBuf,  |
1270 | int width, int pad, int height, int flags);  |
1271 |   |
1272 |   |
1273 | /**  |
1274 | * Decompress a JPEG image into separate Y, U (Cb), and V (Cr) image  |
1275 | * planes. This function performs JPEG decompression but leaves out the color  |
1276 | * conversion step, so a planar YUV image is generated instead of an RGB image.  |
1277 | *  |
1278 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1279 | *  |
1280 | * @param jpegBuf pointer to a buffer containing the JPEG image to decompress  |
1281 | *  |
1282 | * @param jpegSize size of the JPEG image (in bytes)  |
1283 | *  |
1284 | * @param dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes  |
1285 | * (or just a Y plane, if decompressing a grayscale image) that will receive  |
1286 | * the YUV image. These planes can be contiguous or non-contiguous in memory.  |
1287 | * Use #tjPlaneSizeYUV() to determine the appropriate size for each plane based  |
1288 | * on the scaled image width, scaled image height, strides, and level of  |
1289 | * chrominance subsampling. Refer to @ref YUVnotes "YUV Image Format Notes"  |
1290 | * for more details.  |
1291 | *  |
1292 | * @param width desired width (in pixels) of the YUV image. If this is  |
1293 | * different than the width of the JPEG image being decompressed, then  |
1294 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1295 | * possible image that will fit within the desired width. If <tt>width</tt> is  |
1296 | * set to 0, then only the height will be considered when determining the  |
1297 | * scaled image size. If the scaled width is not an even multiple of the MCU  |
1298 | * block width (see #tjMCUWidth), then an intermediate buffer copy will be  |
1299 | * performed within TurboJPEG.  |
1300 | *  |
1301 | * @param strides an array of integers, each specifying the number of bytes per  |
1302 | * line in the corresponding plane of the output image. Setting the stride for  |
1303 | * any plane to 0 is the same as setting it to the scaled plane width (see  |
1304 | * @ref YUVnotes "YUV Image Format Notes".) If <tt>strides</tt> is NULL, then  |
1305 | * the strides for all planes will be set to their respective scaled plane  |
1306 | * widths. You can adjust the strides in order to add an arbitrary amount of  |
1307 | * line padding to each plane or to decompress the JPEG image into a subregion  |
1308 | * of a larger YUV planar image.  |
1309 | *  |
1310 | * @param height desired height (in pixels) of the YUV image. If this is  |
1311 | * different than the height of the JPEG image being decompressed, then  |
1312 | * TurboJPEG will use scaling in the JPEG decompressor to generate the largest  |
1313 | * possible image that will fit within the desired height. If <tt>height</tt>  |
1314 | * is set to 0, then only the width will be considered when determining the  |
1315 | * scaled image size. If the scaled height is not an even multiple of the MCU  |
1316 | * block height (see #tjMCUHeight), then an intermediate buffer copy will be  |
1317 | * performed within TurboJPEG.  |
1318 | *  |
1319 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1320 | * "flags"  |
1321 | *  |
1322 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1323 | * and #tjGetErrorCode().)  |
1324 | */  |
1325 | DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle,  |
1326 | const unsigned char *jpegBuf,  |
1327 | unsigned long jpegSize,  |
1328 | unsigned char **dstPlanes, int width,  |
1329 | int *strides, int height, int flags);  |
1330 |   |
1331 |   |
1332 | /**  |
1333 | * Decode a YUV planar image into an RGB or grayscale image. This function  |
1334 | * uses the accelerated color conversion routines in the underlying  |
1335 | * codec but does not execute any of the other steps in the JPEG decompression  |
1336 | * process.  |
1337 | *  |
1338 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1339 | *  |
1340 | * @param srcBuf pointer to an image buffer containing a YUV planar image to be  |
1341 | * decoded. The size of this buffer should match the value returned by  |
1342 | * #tjBufSizeYUV2() for the given image width, height, padding, and level of  |
1343 | * chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be  |
1344 | * stored sequentially in the source buffer (refer to @ref YUVnotes  |
1345 | * "YUV Image Format Notes".)  |
1346 | *  |
1347 | * @param pad Use this parameter to specify that the width of each line in each  |
1348 | * plane of the YUV source image is padded to the nearest multiple of this  |
1349 | * number of bytes (must be a power of 2.)  |
1350 | *  |
1351 | * @param subsamp the level of chrominance subsampling used in the YUV source  |
1352 | * image (see @ref TJSAMP "Chrominance subsampling options".)  |
1353 | *  |
1354 | * @param dstBuf pointer to an image buffer that will receive the decoded  |
1355 | * image. This buffer should normally be <tt>pitch * height</tt> bytes in  |
1356 | * size, but the <tt>dstBuf</tt> pointer can also be used to decode into a  |
1357 | * specific region of a larger buffer.  |
1358 | *  |
1359 | * @param width width (in pixels) of the source and destination images  |
1360 | *  |
1361 | * @param pitch bytes per line in the destination image. Normally, this should  |
1362 | * be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination image is  |
1363 | * unpadded, or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line  |
1364 | * of the destination image should be padded to the nearest 32-bit boundary, as  |
1365 | * is the case for Windows bitmaps. You can also be clever and use the pitch  |
1366 | * parameter to skip lines, etc. Setting this parameter to 0 is the equivalent  |
1367 | * of setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
1368 | *  |
1369 | * @param height height (in pixels) of the source and destination images  |
1370 | *  |
1371 | * @param pixelFormat pixel format of the destination image (see @ref TJPF  |
1372 | * "Pixel formats".)  |
1373 | *  |
1374 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1375 | * "flags"  |
1376 | *  |
1377 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1378 | * and #tjGetErrorCode().)  |
1379 | */  |
1380 | DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf,  |
1381 | int pad, int subsamp, unsigned char *dstBuf,  |
1382 | int width, int pitch, int height, int pixelFormat,  |
1383 | int flags);  |
1384 |   |
1385 |   |
1386 | /**  |
1387 | * Decode a set of Y, U (Cb), and V (Cr) image planes into an RGB or grayscale  |
1388 | * image. This function uses the accelerated color conversion routines in the  |
1389 | * underlying codec but does not execute any of the other steps in the JPEG  |
1390 | * decompression process.  |
1391 | *  |
1392 | * @param handle a handle to a TurboJPEG decompressor or transformer instance  |
1393 | *  |
1394 | * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes  |
1395 | * (or just a Y plane, if decoding a grayscale image) that contain a YUV image  |
1396 | * to be decoded. These planes can be contiguous or non-contiguous in memory.  |
1397 | * The size of each plane should match the value returned by #tjPlaneSizeYUV()  |
1398 | * for the given image width, height, strides, and level of chrominance  |
1399 | * subsampling. Refer to @ref YUVnotes "YUV Image Format Notes" for more  |
1400 | * details.  |
1401 | *  |
1402 | * @param strides an array of integers, each specifying the number of bytes per  |
1403 | * line in the corresponding plane of the YUV source image. Setting the stride  |
1404 | * for any plane to 0 is the same as setting it to the plane width (see  |
1405 | * @ref YUVnotes "YUV Image Format Notes".) If <tt>strides</tt> is NULL, then  |
1406 | * the strides for all planes will be set to their respective plane widths.  |
1407 | * You can adjust the strides in order to specify an arbitrary amount of line  |
1408 | * padding in each plane or to decode a subregion of a larger YUV planar image.  |
1409 | *  |
1410 | * @param subsamp the level of chrominance subsampling used in the YUV source  |
1411 | * image (see @ref TJSAMP "Chrominance subsampling options".)  |
1412 | *  |
1413 | * @param dstBuf pointer to an image buffer that will receive the decoded  |
1414 | * image. This buffer should normally be <tt>pitch * height</tt> bytes in  |
1415 | * size, but the <tt>dstBuf</tt> pointer can also be used to decode into a  |
1416 | * specific region of a larger buffer.  |
1417 | *  |
1418 | * @param width width (in pixels) of the source and destination images  |
1419 | *  |
1420 | * @param pitch bytes per line in the destination image. Normally, this should  |
1421 | * be <tt>width * #tjPixelSize[pixelFormat]</tt> if the destination image is  |
1422 | * unpadded, or <tt>#TJPAD(width * #tjPixelSize[pixelFormat])</tt> if each line  |
1423 | * of the destination image should be padded to the nearest 32-bit boundary, as  |
1424 | * is the case for Windows bitmaps. You can also be clever and use the pitch  |
1425 | * parameter to skip lines, etc. Setting this parameter to 0 is the equivalent  |
1426 | * of setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
1427 | *  |
1428 | * @param height height (in pixels) of the source and destination images  |
1429 | *  |
1430 | * @param pixelFormat pixel format of the destination image (see @ref TJPF  |
1431 | * "Pixel formats".)  |
1432 | *  |
1433 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1434 | * "flags"  |
1435 | *  |
1436 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1437 | * and #tjGetErrorCode().)  |
1438 | */  |
1439 | DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle,  |
1440 | const unsigned char **srcPlanes,  |
1441 | const int *strides, int subsamp,  |
1442 | unsigned char *dstBuf, int width, int pitch,  |
1443 | int height, int pixelFormat, int flags);  |
1444 |   |
1445 |   |
1446 | /**  |
1447 | * Create a new TurboJPEG transformer instance.  |
1448 | *  |
1449 | * @return a handle to the newly-created instance, or NULL if an error  |
1450 | * occurred (see #tjGetErrorStr2().)  |
1451 | */  |
1452 | DLLEXPORT tjhandle tjInitTransform(void);  |
1453 |   |
1454 |   |
1455 | /**  |
1456 | * Losslessly transform a JPEG image into another JPEG image. Lossless  |
1457 | * transforms work by moving the raw DCT coefficients from one JPEG image  |
1458 | * structure to another without altering the values of the coefficients. While  |
1459 | * this is typically faster than decompressing the image, transforming it, and  |
1460 | * re-compressing it, lossless transforms are not free. Each lossless  |
1461 | * transform requires reading and performing Huffman decoding on all of the  |
1462 | * coefficients in the source image, regardless of the size of the destination  |
1463 | * image. Thus, this function provides a means of generating multiple  |
1464 | * transformed images from the same source or applying multiple  |
1465 | * transformations simultaneously, in order to eliminate the need to read the  |
1466 | * source coefficients multiple times.  |
1467 | *  |
1468 | * @param handle a handle to a TurboJPEG transformer instance  |
1469 | *  |
1470 | * @param jpegBuf pointer to a buffer containing the JPEG source image to  |
1471 | * transform  |
1472 | *  |
1473 | * @param jpegSize size of the JPEG source image (in bytes)  |
1474 | *  |
1475 | * @param n the number of transformed JPEG images to generate  |
1476 | *  |
1477 | * @param dstBufs pointer to an array of n image buffers. <tt>dstBufs[i]</tt>  |
1478 | * will receive a JPEG image that has been transformed using the parameters in  |
1479 | * <tt>transforms[i]</tt>. TurboJPEG has the ability to reallocate the JPEG  |
1480 | * buffer to accommodate the size of the JPEG image. Thus, you can choose to:  |
1481 | * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and  |
1482 | * let TurboJPEG grow the buffer as needed,  |
1483 | * -# set <tt>dstBufs[i]</tt> to NULL to tell TurboJPEG to allocate the buffer  |
1484 | * for you, or  |
1485 | * -# pre-allocate the buffer to a "worst case" size determined by calling  |
1486 | * #tjBufSize() with the transformed or cropped width and height. Under normal  |
1487 | * circumstances, this should ensure that the buffer never has to be  |
1488 | * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.) Note,  |
1489 | * however, that there are some rare cases (such as transforming images with a  |
1490 | * large amount of embedded EXIF or ICC profile data) in which the output image  |
1491 | * will be larger than the worst-case size, and #TJFLAG_NOREALLOC cannot be  |
1492 | * used in those cases.  |
1493 | * .  |
1494 | * If you choose option 1, <tt>dstSizes[i]</tt> should be set to the size of  |
1495 | * your pre-allocated buffer. In any case, unless you have set  |
1496 | * #TJFLAG_NOREALLOC, you should always check <tt>dstBufs[i]</tt> upon return  |
1497 | * from this function, as it may have changed.  |
1498 | *  |
1499 | * @param dstSizes pointer to an array of n unsigned long variables that will  |
1500 | * receive the actual sizes (in bytes) of each transformed JPEG image. If  |
1501 | * <tt>dstBufs[i]</tt> points to a pre-allocated buffer, then  |
1502 | * <tt>dstSizes[i]</tt> should be set to the size of the buffer. Upon return,  |
1503 | * <tt>dstSizes[i]</tt> will contain the size of the JPEG image (in bytes.)  |
1504 | *  |
1505 | * @param transforms pointer to an array of n #tjtransform structures, each of  |
1506 | * which specifies the transform parameters and/or cropping region for the  |
1507 | * corresponding transformed output image.  |
1508 | *  |
1509 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT  |
1510 | * "flags"  |
1511 | *  |
1512 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2()  |
1513 | * and #tjGetErrorCode().)  |
1514 | */  |
1515 | DLLEXPORT int tjTransform(tjhandle handle, const unsigned char *jpegBuf,  |
1516 | unsigned long jpegSize, int n,  |
1517 | unsigned char **dstBufs, unsigned long *dstSizes,  |
1518 | tjtransform *transforms, int flags);  |
1519 |   |
1520 |   |
1521 | /**  |
1522 | * Destroy a TurboJPEG compressor, decompressor, or transformer instance.  |
1523 | *  |
1524 | * @param handle a handle to a TurboJPEG compressor, decompressor or  |
1525 | * transformer instance  |
1526 | *  |
1527 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2().)  |
1528 | */  |
1529 | DLLEXPORT int tjDestroy(tjhandle handle);  |
1530 |   |
1531 |   |
1532 | /**  |
1533 | * Allocate an image buffer for use with TurboJPEG. You should always use  |
1534 | * this function to allocate the JPEG destination buffer(s) for the compression  |
1535 | * and transform functions unless you are disabling automatic buffer  |
1536 | * (re)allocation (by setting #TJFLAG_NOREALLOC.)  |
1537 | *  |
1538 | * @param bytes the number of bytes to allocate  |
1539 | *  |
1540 | * @return a pointer to a newly-allocated buffer with the specified number of  |
1541 | * bytes.  |
1542 | *  |
1543 | * @sa tjFree()  |
1544 | */  |
1545 | DLLEXPORT unsigned char *tjAlloc(int bytes);  |
1546 |   |
1547 |   |
1548 | /**  |
1549 | * Load an uncompressed image from disk into memory.  |
1550 | *  |
1551 | * @param filename name of a file containing an uncompressed image in Windows  |
1552 | * BMP or PBMPLUS (PPM/PGM) format  |
1553 | *  |
1554 | * @param width pointer to an integer variable that will receive the width (in  |
1555 | * pixels) of the uncompressed image  |
1556 | *  |
1557 | * @param align row alignment of the image buffer to be returned (must be a  |
1558 | * power of 2.) For instance, setting this parameter to 4 will cause all rows  |
1559 | * in the image buffer to be padded to the nearest 32-bit boundary, and setting  |
1560 | * this parameter to 1 will cause all rows in the image buffer to be unpadded.  |
1561 | *  |
1562 | * @param height pointer to an integer variable that will receive the height  |
1563 | * (in pixels) of the uncompressed image  |
1564 | *  |
1565 | * @param pixelFormat pointer to an integer variable that specifies or will  |
1566 | * receive the pixel format of the uncompressed image buffer. The behavior of  |
1567 | * #tjLoadImage() will vary depending on the value of <tt>*pixelFormat</tt>  |
1568 | * passed to the function:  |
1569 | * - @ref TJPF_UNKNOWN : The uncompressed image buffer returned by the function  |
1570 | * will use the most optimal pixel format for the file type, and  |
1571 | * <tt>*pixelFormat</tt> will contain the ID of this pixel format upon  |
1572 | * successful return from the function.  |
1573 | * - @ref TJPF_GRAY : Only PGM files and 8-bit BMP files with a grayscale  |
1574 | * colormap can be loaded.  |
1575 | * - @ref TJPF_CMYK : The RGB or grayscale pixels stored in the file will be  |
1576 | * converted using a quick & dirty algorithm that is suitable only for testing  |
1577 | * purposes (proper conversion between CMYK and other formats requires a color  |
1578 | * management system.)  |
1579 | * - Other @ref TJPF "pixel formats" : The uncompressed image buffer will use  |
1580 | * the specified pixel format, and pixel format conversion will be performed if  |
1581 | * necessary.  |
1582 | *  |
1583 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP  |
1584 | * "flags".  |
1585 | *  |
1586 | * @return a pointer to a newly-allocated buffer containing the uncompressed  |
1587 | * image, converted to the chosen pixel format and with the chosen row  |
1588 | * alignment, or NULL if an error occurred (see #tjGetErrorStr2().) This  |
1589 | * buffer should be freed using #tjFree().  |
1590 | */  |
1591 | DLLEXPORT unsigned char *tjLoadImage(const char *filename, int *width,  |
1592 | int align, int *height, int *pixelFormat,  |
1593 | int flags);  |
1594 |   |
1595 |   |
1596 | /**  |
1597 | * Save an uncompressed image from memory to disk.  |
1598 | *  |
1599 | * @param filename name of a file to which to save the uncompressed image.  |
1600 | * The image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format,  |
1601 | * depending on the file extension.  |
1602 | *  |
1603 | * @param buffer pointer to an image buffer containing RGB, grayscale, or  |
1604 | * CMYK pixels to be saved  |
1605 | *  |
1606 | * @param width width (in pixels) of the uncompressed image  |
1607 | *  |
1608 | * @param pitch bytes per line in the image buffer. Setting this parameter to  |
1609 | * 0 is the equivalent of setting it to  |
1610 | * <tt>width * #tjPixelSize[pixelFormat]</tt>.  |
1611 | *  |
1612 | * @param height height (in pixels) of the uncompressed image  |
1613 | *  |
1614 | * @param pixelFormat pixel format of the image buffer (see @ref TJPF  |
1615 | * "Pixel formats".) If this parameter is set to @ref TJPF_GRAY, then the  |
1616 | * image will be stored in PGM or 8-bit (indexed color) BMP format. Otherwise,  |
1617 | * the image will be stored in PPM or 24-bit BMP format. If this parameter  |
1618 | * is set to @ref TJPF_CMYK, then the CMYK pixels will be converted to RGB  |
1619 | * using a quick & dirty algorithm that is suitable only for testing (proper  |
1620 | * conversion between CMYK and other formats requires a color management  |
1621 | * system.)  |
1622 | *  |
1623 | * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP  |
1624 | * "flags".  |
1625 | *  |
1626 | * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2().)  |
1627 | */  |
1628 | DLLEXPORT int tjSaveImage(const char *filename, unsigned char *buffer,  |
1629 | int width, int pitch, int height, int pixelFormat,  |
1630 | int flags);  |
1631 |   |
1632 |   |
1633 | /**  |
1634 | * Free an image buffer previously allocated by TurboJPEG. You should always  |
1635 | * use this function to free JPEG destination buffer(s) that were automatically  |
1636 | * (re)allocated by the compression and transform functions or that were  |
1637 | * manually allocated using #tjAlloc().  |
1638 | *  |
1639 | * @param buffer address of the buffer to free. If the address is NULL, then  |
1640 | * this function has no effect.  |
1641 | *  |
1642 | * @sa tjAlloc()  |
1643 | */  |
1644 | DLLEXPORT void tjFree(unsigned char *buffer);  |
1645 |   |
1646 |   |
1647 | /**  |
1648 | * Returns a descriptive error message explaining why the last command failed.  |
1649 | *  |
1650 | * @param handle a handle to a TurboJPEG compressor, decompressor, or  |
1651 | * transformer instance, or NULL if the error was generated by a global  |
1652 | * function (but note that retrieving the error message for a global function  |
1653 | * is thread-safe only on platforms that support thread-local storage.)  |
1654 | *  |
1655 | * @return a descriptive error message explaining why the last command failed.  |
1656 | */  |
1657 | DLLEXPORT char *tjGetErrorStr2(tjhandle handle);  |
1658 |   |
1659 |   |
1660 | /**  |
1661 | * Returns a code indicating the severity of the last error. See  |
1662 | * @ref TJERR "Error codes".  |
1663 | *  |
1664 | * @param handle a handle to a TurboJPEG compressor, decompressor or  |
1665 | * transformer instance  |
1666 | *  |
1667 | * @return a code indicating the severity of the last error. See  |
1668 | * @ref TJERR "Error codes".  |
1669 | */  |
1670 | DLLEXPORT int tjGetErrorCode(tjhandle handle);  |
1671 |   |
1672 |   |
1673 | /* Deprecated functions and macros */  |
1674 | #define TJFLAG_FORCEMMX 8  |
1675 | #define TJFLAG_FORCESSE 16  |
1676 | #define TJFLAG_FORCESSE2 32  |
1677 | #define TJFLAG_FORCESSE3 128  |
1678 |   |
1679 |   |
1680 | /* Backward compatibility functions and macros (nothing to see here) */  |
1681 | #define NUMSUBOPT TJ_NUMSAMP  |
1682 | #define TJ_444 TJSAMP_444  |
1683 | #define TJ_422 TJSAMP_422  |
1684 | #define TJ_420 TJSAMP_420  |
1685 | #define TJ_411 TJSAMP_420  |
1686 | #define TJ_GRAYSCALE TJSAMP_GRAY  |
1687 |   |
1688 | #define TJ_BGR 1  |
1689 | #define TJ_BOTTOMUP TJFLAG_BOTTOMUP  |
1690 | #define TJ_FORCEMMX TJFLAG_FORCEMMX  |
1691 | #define TJ_FORCESSE TJFLAG_FORCESSE  |
1692 | #define TJ_FORCESSE2 TJFLAG_FORCESSE2  |
1693 | #define TJ_ALPHAFIRST 64  |
1694 | #define TJ_FORCESSE3 TJFLAG_FORCESSE3  |
1695 | #define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE  |
1696 | #define TJ_YUV 512  |
1697 |   |
1698 | DLLEXPORT unsigned long TJBUFSIZE(int width, int height);  |
1699 |   |
1700 | DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int jpegSubsamp);  |
1701 |   |
1702 | DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp);  |
1703 |   |
1704 | DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width,  |
1705 | int pitch, int height, int pixelSize,  |
1706 | unsigned char *dstBuf, unsigned long *compressedSize,  |
1707 | int jpegSubsamp, int jpegQual, int flags);  |
1708 |   |
1709 | DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width,  |
1710 | int pitch, int height, int pixelSize,  |
1711 | unsigned char *dstBuf, int subsamp, int flags);  |
1712 |   |
1713 | DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width,  |
1714 | int pitch, int height, int pixelFormat,  |
1715 | unsigned char *dstBuf, int subsamp, int flags);  |
1716 |   |
1717 | DLLEXPORT int (tjhandle handle, unsigned char *jpegBuf,  |
1718 | unsigned long jpegSize, int *width,  |
1719 | int *height);  |
1720 |   |
1721 | DLLEXPORT int (tjhandle handle, unsigned char *jpegBuf,  |
1722 | unsigned long jpegSize, int *width,  |
1723 | int *height, int *jpegSubsamp);  |
1724 |   |
1725 | DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf,  |
1726 | unsigned long jpegSize, unsigned char *dstBuf,  |
1727 | int width, int pitch, int height, int pixelSize,  |
1728 | int flags);  |
1729 |   |
1730 | DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf,  |
1731 | unsigned long jpegSize, unsigned char *dstBuf,  |
1732 | int flags);  |
1733 |   |
1734 | DLLEXPORT char *tjGetErrorStr(void);  |
1735 |   |
1736 |   |
1737 | /**  |
1738 | * @}  |
1739 | */  |
1740 |   |
1741 | #ifdef __cplusplus  |
1742 | }  |
1743 | #endif  |
1744 |   |
1745 | #endif  |
1746 | |