/src/libjpeg-turbo.main/turbojpeg.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * Copyright (C)2009-2015, 2017, 2020-2023 D. R. Commander. |
3 | | * All Rights Reserved. |
4 | | * |
5 | | * Redistribution and use in source and binary forms, with or without |
6 | | * modification, are permitted provided that the following conditions are met: |
7 | | * |
8 | | * - Redistributions of source code must retain the above copyright notice, |
9 | | * this list of conditions and the following disclaimer. |
10 | | * - Redistributions in binary form must reproduce the above copyright notice, |
11 | | * this list of conditions and the following disclaimer in the documentation |
12 | | * and/or other materials provided with the distribution. |
13 | | * - Neither the name of the libjpeg-turbo Project nor the names of its |
14 | | * contributors may be used to endorse or promote products derived from this |
15 | | * software without specific prior written permission. |
16 | | * |
17 | | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", |
18 | | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
19 | | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
20 | | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE |
21 | | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
22 | | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
23 | | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
24 | | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
25 | | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
26 | | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
27 | | * POSSIBILITY OF SUCH DAMAGE. |
28 | | */ |
29 | | |
30 | | #ifndef __TURBOJPEG_H__ |
31 | | #define __TURBOJPEG_H__ |
32 | | |
33 | | #include <stddef.h> |
34 | | |
35 | | #if defined(_WIN32) && defined(DLLDEFINE) |
36 | | #define DLLEXPORT __declspec(dllexport) |
37 | | #else |
38 | | #define DLLEXPORT |
39 | | #endif |
40 | | #define DLLCALL |
41 | | |
42 | | |
43 | | /** |
44 | | * @addtogroup TurboJPEG |
45 | | * TurboJPEG API. This API provides an interface for generating, decoding, and |
46 | | * transforming planar YUV and JPEG images in memory. |
47 | | * |
48 | | * @anchor YUVnotes |
49 | | * YUV Image Format Notes |
50 | | * ---------------------- |
51 | | * Technically, the JPEG format uses the YCbCr colorspace (which is technically |
52 | | * not a colorspace but a color transform), but per the convention of the |
53 | | * digital video community, the TurboJPEG API uses "YUV" to refer to an image |
54 | | * format consisting of Y, Cb, and Cr image planes. |
55 | | * |
56 | | * Each plane is simply a 2D array of bytes, each byte representing the value |
57 | | * of one of the components (Y, Cb, or Cr) at a particular location in the |
58 | | * image. The width and height of each plane are determined by the image |
59 | | * width, height, and level of chrominance subsampling. The luminance plane |
60 | | * width is the image width padded to the nearest multiple of the horizontal |
61 | | * subsampling factor (1 in the case of 4:4:4, grayscale, 4:4:0, or 4:4:1; 2 in |
62 | | * the case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the |
63 | | * luminance plane height is the image height padded to the nearest multiple of |
64 | | * the vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, |
65 | | * or 4:1:1; 2 in the case of 4:2:0 or 4:4:0; 4 in the case of 4:4:1.) This is |
66 | | * irrespective of any additional padding that may be specified as an argument |
67 | | * to the various YUV functions. The chrominance plane width is equal to the |
68 | | * luminance plane width divided by the horizontal subsampling factor, and the |
69 | | * chrominance plane height is equal to the luminance plane height divided by |
70 | | * the vertical subsampling factor. |
71 | | * |
72 | | * For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is |
73 | | * used, then the luminance plane would be 36 x 35 bytes, and each of the |
74 | | * chrominance planes would be 18 x 35 bytes. If you specify a row alignment |
75 | | * of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, |
76 | | * and each of the chrominance planes would be 20 x 35 bytes. |
77 | | * |
78 | | * @{ |
79 | | */ |
80 | | |
81 | | |
82 | | /** |
83 | | * The number of initialization options |
84 | | */ |
85 | 186k | #define TJ_NUMINIT 3 |
86 | | |
87 | | /** |
88 | | * Initialization options. |
89 | | */ |
90 | | enum TJINIT { |
91 | | /** |
92 | | * Initialize the TurboJPEG instance for compression. |
93 | | */ |
94 | | TJINIT_COMPRESS, |
95 | | /** |
96 | | * Initialize the TurboJPEG instance for decompression. |
97 | | */ |
98 | | TJINIT_DECOMPRESS, |
99 | | /** |
100 | | * Initialize the TurboJPEG instance for lossless transformation (both |
101 | | * compression and decompression.) |
102 | | */ |
103 | | TJINIT_TRANSFORM |
104 | | }; |
105 | | |
106 | | |
107 | | /** |
108 | | * The number of chrominance subsampling options |
109 | | */ |
110 | 1.51M | #define TJ_NUMSAMP 7 |
111 | | |
112 | | /** |
113 | | * Chrominance subsampling options. |
114 | | * When pixels are converted from RGB to YCbCr (see #TJCS_YCbCr) or from CMYK |
115 | | * to YCCK (see #TJCS_YCCK) as part of the JPEG compression process, some of |
116 | | * the Cb and Cr (chrominance) components can be discarded or averaged together |
117 | | * to produce a smaller image with little perceptible loss of image clarity. |
118 | | * (The human eye is more sensitive to small changes in brightness than to |
119 | | * small changes in color.) This is called "chrominance subsampling". |
120 | | */ |
121 | | enum TJSAMP { |
122 | | /** |
123 | | * 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG or |
124 | | * YUV image will contain one chrominance component for every pixel in the |
125 | | * source image. |
126 | | */ |
127 | | TJSAMP_444, |
128 | | /** |
129 | | * 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one |
130 | | * chrominance component for every 2x1 block of pixels in the source image. |
131 | | */ |
132 | | TJSAMP_422, |
133 | | /** |
134 | | * 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one |
135 | | * chrominance component for every 2x2 block of pixels in the source image. |
136 | | */ |
137 | | TJSAMP_420, |
138 | | /** |
139 | | * Grayscale. The JPEG or YUV image will contain no chrominance components. |
140 | | */ |
141 | | TJSAMP_GRAY, |
142 | | /** |
143 | | * 4:4:0 chrominance subsampling. The JPEG or YUV image will contain one |
144 | | * chrominance component for every 1x2 block of pixels in the source image. |
145 | | * |
146 | | * @note 4:4:0 subsampling is not fully accelerated in libjpeg-turbo. |
147 | | */ |
148 | | TJSAMP_440, |
149 | | /** |
150 | | * 4:1:1 chrominance subsampling. The JPEG or YUV image will contain one |
151 | | * chrominance component for every 4x1 block of pixels in the source image. |
152 | | * JPEG images compressed with 4:1:1 subsampling will be almost exactly the |
153 | | * same size as those compressed with 4:2:0 subsampling, and in the |
154 | | * aggregate, both subsampling methods produce approximately the same |
155 | | * perceptual quality. However, 4:1:1 is better able to reproduce sharp |
156 | | * horizontal features. |
157 | | * |
158 | | * @note 4:1:1 subsampling is not fully accelerated in libjpeg-turbo. |
159 | | */ |
160 | | TJSAMP_411, |
161 | | /** |
162 | | * 4:4:1 chrominance subsampling. The JPEG or YUV image will contain one |
163 | | * chrominance component for every 1x4 block of pixels in the source image. |
164 | | * JPEG images compressed with 4:4:1 subsampling will be almost exactly the |
165 | | * same size as those compressed with 4:2:0 subsampling, and in the |
166 | | * aggregate, both subsampling methods produce approximately the same |
167 | | * perceptual quality. However, 4:4:1 is better able to reproduce sharp |
168 | | * vertical features. |
169 | | * |
170 | | * @note 4:4:1 subsampling is not fully accelerated in libjpeg-turbo. |
171 | | */ |
172 | | TJSAMP_441, |
173 | | /** |
174 | | * Unknown subsampling. The JPEG image uses an unusual type of chrominance |
175 | | * subsampling. Such images can be decompressed into packed-pixel images, |
176 | | * but they cannot be |
177 | | * - decompressed into planar YUV images, |
178 | | * - losslessly transformed if #TJXOPT_CROP is specified, or |
179 | | * - partially decompressed using a cropping region. |
180 | | */ |
181 | | TJSAMP_UNKNOWN = -1 |
182 | | }; |
183 | | |
184 | | /** |
185 | | * MCU block width (in pixels) for a given level of chrominance subsampling. |
186 | | * MCU block sizes: |
187 | | * - 8x8 for no subsampling or grayscale |
188 | | * - 16x8 for 4:2:2 |
189 | | * - 8x16 for 4:4:0 |
190 | | * - 16x16 for 4:2:0 |
191 | | * - 32x8 for 4:1:1 |
192 | | * - 8x32 for 4:4:1 |
193 | | */ |
194 | | static const int tjMCUWidth[TJ_NUMSAMP] = { 8, 16, 16, 8, 8, 32, 8 }; |
195 | | |
196 | | /** |
197 | | * MCU block height (in pixels) for a given level of chrominance subsampling. |
198 | | * MCU block sizes: |
199 | | * - 8x8 for no subsampling or grayscale |
200 | | * - 16x8 for 4:2:2 |
201 | | * - 8x16 for 4:4:0 |
202 | | * - 16x16 for 4:2:0 |
203 | | * - 32x8 for 4:1:1 |
204 | | * - 8x32 for 4:4:1 |
205 | | */ |
206 | | static const int tjMCUHeight[TJ_NUMSAMP] = { 8, 8, 16, 8, 16, 8, 32 }; |
207 | | |
208 | | |
209 | | /** |
210 | | * The number of pixel formats |
211 | | */ |
212 | 149k | #define TJ_NUMPF 12 |
213 | | |
214 | | /** |
215 | | * Pixel formats |
216 | | */ |
217 | | enum TJPF { |
218 | | /** |
219 | | * RGB pixel format. The red, green, and blue components in the image are |
220 | | * stored in 3-sample pixels in the order R, G, B from lowest to highest |
221 | | * memory address within each pixel. |
222 | | */ |
223 | | TJPF_RGB, |
224 | | /** |
225 | | * BGR pixel format. The red, green, and blue components in the image are |
226 | | * stored in 3-sample pixels in the order B, G, R from lowest to highest |
227 | | * memory address within each pixel. |
228 | | */ |
229 | | TJPF_BGR, |
230 | | /** |
231 | | * RGBX pixel format. The red, green, and blue components in the image are |
232 | | * stored in 4-sample pixels in the order R, G, B from lowest to highest |
233 | | * memory address within each pixel. The X component is ignored when |
234 | | * compressing and undefined when decompressing. |
235 | | */ |
236 | | TJPF_RGBX, |
237 | | /** |
238 | | * BGRX pixel format. The red, green, and blue components in the image are |
239 | | * stored in 4-sample pixels in the order B, G, R from lowest to highest |
240 | | * memory address within each pixel. The X component is ignored when |
241 | | * compressing and undefined when decompressing. |
242 | | */ |
243 | | TJPF_BGRX, |
244 | | /** |
245 | | * XBGR pixel format. The red, green, and blue components in the image are |
246 | | * stored in 4-sample pixels in the order R, G, B from highest to lowest |
247 | | * memory address within each pixel. The X component is ignored when |
248 | | * compressing and undefined when decompressing. |
249 | | */ |
250 | | TJPF_XBGR, |
251 | | /** |
252 | | * XRGB pixel format. The red, green, and blue components in the image are |
253 | | * stored in 4-sample pixels in the order B, G, R from highest to lowest |
254 | | * memory address within each pixel. The X component is ignored when |
255 | | * compressing and undefined when decompressing. |
256 | | */ |
257 | | TJPF_XRGB, |
258 | | /** |
259 | | * Grayscale pixel format. Each 1-sample pixel represents a luminance |
260 | | * (brightness) level from 0 to the maximum sample value (255 for 8-bit |
261 | | * samples, 4095 for 12-bit samples, and 65535 for 16-bit samples.) |
262 | | */ |
263 | | TJPF_GRAY, |
264 | | /** |
265 | | * RGBA pixel format. This is the same as @ref TJPF_RGBX, except that when |
266 | | * decompressing, the X component is guaranteed to be equal to the maximum |
267 | | * sample value, which can be interpreted as an opaque alpha channel. |
268 | | */ |
269 | | TJPF_RGBA, |
270 | | /** |
271 | | * BGRA pixel format. This is the same as @ref TJPF_BGRX, except that when |
272 | | * decompressing, the X component is guaranteed to be equal to the maximum |
273 | | * sample value, which can be interpreted as an opaque alpha channel. |
274 | | */ |
275 | | TJPF_BGRA, |
276 | | /** |
277 | | * ABGR pixel format. This is the same as @ref TJPF_XBGR, except that when |
278 | | * decompressing, the X component is guaranteed to be equal to the maximum |
279 | | * sample value, which can be interpreted as an opaque alpha channel. |
280 | | */ |
281 | | TJPF_ABGR, |
282 | | /** |
283 | | * ARGB pixel format. This is the same as @ref TJPF_XRGB, except that when |
284 | | * decompressing, the X component is guaranteed to be equal to the maximum |
285 | | * sample value, which can be interpreted as an opaque alpha channel. |
286 | | */ |
287 | | TJPF_ARGB, |
288 | | /** |
289 | | * CMYK pixel format. Unlike RGB, which is an additive color model used |
290 | | * primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive |
291 | | * color model used primarily for printing. In the CMYK color model, the |
292 | | * value of each color component typically corresponds to an amount of cyan, |
293 | | * magenta, yellow, or black ink that is applied to a white background. In |
294 | | * order to convert between CMYK and RGB, it is necessary to use a color |
295 | | * management system (CMS.) A CMS will attempt to map colors within the |
296 | | * printer's gamut to perceptually similar colors in the display's gamut and |
297 | | * vice versa, but the mapping is typically not 1:1 or reversible, nor can it |
298 | | * be defined with a simple formula. Thus, such a conversion is out of scope |
299 | | * for a codec library. However, the TurboJPEG API allows for compressing |
300 | | * packed-pixel CMYK images into YCCK JPEG images (see #TJCS_YCCK) and |
301 | | * decompressing YCCK JPEG images into packed-pixel CMYK images. |
302 | | */ |
303 | | TJPF_CMYK, |
304 | | /** |
305 | | * Unknown pixel format. Currently this is only used by #tj3LoadImage8(), |
306 | | * #tj3LoadImage12(), and #tj3LoadImage16(). |
307 | | */ |
308 | | TJPF_UNKNOWN = -1 |
309 | | }; |
310 | | |
311 | | /** |
312 | | * Red offset (in samples) for a given pixel format. This specifies the number |
313 | | * of samples that the red component is offset from the start of the pixel. |
314 | | * For instance, if an 8-bit-per-component pixel of format TJPF_BGRX is stored |
315 | | * in `unsigned char pixel[]`, then the red component will be |
316 | | * `pixel[tjRedOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does |
317 | | * not have a red component. |
318 | | */ |
319 | | static const int tjRedOffset[TJ_NUMPF] = { |
320 | | 0, 2, 0, 2, 3, 1, -1, 0, 2, 3, 1, -1 |
321 | | }; |
322 | | /** |
323 | | * Green offset (in samples) for a given pixel format. This specifies the |
324 | | * number of samples that the green component is offset from the start of the |
325 | | * pixel. For instance, if an 8-bit-per-component pixel of format TJPF_BGRX is |
326 | | * stored in `unsigned char pixel[]`, then the green component will be |
327 | | * `pixel[tjGreenOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does |
328 | | * not have a green component. |
329 | | */ |
330 | | static const int tjGreenOffset[TJ_NUMPF] = { |
331 | | 1, 1, 1, 1, 2, 2, -1, 1, 1, 2, 2, -1 |
332 | | }; |
333 | | /** |
334 | | * Blue offset (in samples) for a given pixel format. This specifies the |
335 | | * number of samples that the blue component is offset from the start of the |
336 | | * pixel. For instance, if an 8-bit-per-component pixel of format TJPF_BGRX is |
337 | | * stored in `unsigned char pixel[]`, then the blue component will be |
338 | | * `pixel[tjBlueOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does |
339 | | * not have a blue component. |
340 | | */ |
341 | | static const int tjBlueOffset[TJ_NUMPF] = { |
342 | | 2, 0, 2, 0, 1, 3, -1, 2, 0, 1, 3, -1 |
343 | | }; |
344 | | /** |
345 | | * Alpha offset (in samples) for a given pixel format. This specifies the |
346 | | * number of samples that the alpha component is offset from the start of the |
347 | | * pixel. For instance, if an 8-bit-per-component pixel of format TJPF_BGRA is |
348 | | * stored in `unsigned char pixel[]`, then the alpha component will be |
349 | | * `pixel[tjAlphaOffset[TJPF_BGRA]]`. This will be -1 if the pixel format does |
350 | | * not have an alpha component. |
351 | | */ |
352 | | static const int tjAlphaOffset[TJ_NUMPF] = { |
353 | | -1, -1, -1, -1, -1, -1, -1, 3, 3, 0, 0, -1 |
354 | | }; |
355 | | /** |
356 | | * Pixel size (in samples) for a given pixel format |
357 | | */ |
358 | | static const int tjPixelSize[TJ_NUMPF] = { |
359 | | 3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4, 4 |
360 | | }; |
361 | | |
362 | | |
363 | | /** |
364 | | * The number of JPEG colorspaces |
365 | | */ |
366 | | #define TJ_NUMCS 5 |
367 | | |
368 | | /** |
369 | | * JPEG colorspaces |
370 | | */ |
371 | | enum TJCS { |
372 | | /** |
373 | | * RGB colorspace. When compressing the JPEG image, the R, G, and B |
374 | | * components in the source image are reordered into image planes, but no |
375 | | * colorspace conversion or subsampling is performed. RGB JPEG images can be |
376 | | * compressed from and decompressed to packed-pixel images with any of the |
377 | | * extended RGB or grayscale pixel formats, but they cannot be compressed |
378 | | * from or decompressed to planar YUV images. |
379 | | */ |
380 | | TJCS_RGB, |
381 | | /** |
382 | | * YCbCr colorspace. YCbCr is not an absolute colorspace but rather a |
383 | | * mathematical transformation of RGB designed solely for storage and |
384 | | * transmission. YCbCr images must be converted to RGB before they can |
385 | | * actually be displayed. In the YCbCr colorspace, the Y (luminance) |
386 | | * component represents the black & white portion of the original image, and |
387 | | * the Cb and Cr (chrominance) components represent the color portion of the |
388 | | * original image. Originally, the analog equivalent of this transformation |
389 | | * allowed the same signal to drive both black & white and color televisions, |
390 | | * but JPEG images use YCbCr primarily because it allows the color data to be |
391 | | * optionally subsampled for the purposes of reducing network or disk usage. |
392 | | * YCbCr is the most common JPEG colorspace, and YCbCr JPEG images can be |
393 | | * compressed from and decompressed to packed-pixel images with any of the |
394 | | * extended RGB or grayscale pixel formats. YCbCr JPEG images can also be |
395 | | * compressed from and decompressed to planar YUV images. |
396 | | */ |
397 | | TJCS_YCbCr, |
398 | | /** |
399 | | * Grayscale colorspace. The JPEG image retains only the luminance data (Y |
400 | | * component), and any color data from the source image is discarded. |
401 | | * Grayscale JPEG images can be compressed from and decompressed to |
402 | | * packed-pixel images with any of the extended RGB or grayscale pixel |
403 | | * formats, or they can be compressed from and decompressed to planar YUV |
404 | | * images. |
405 | | */ |
406 | | TJCS_GRAY, |
407 | | /** |
408 | | * CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K |
409 | | * components in the source image are reordered into image planes, but no |
410 | | * colorspace conversion or subsampling is performed. CMYK JPEG images can |
411 | | * only be compressed from and decompressed to packed-pixel images with the |
412 | | * CMYK pixel format. |
413 | | */ |
414 | | TJCS_CMYK, |
415 | | /** |
416 | | * YCCK colorspace. YCCK (AKA "YCbCrK") is not an absolute colorspace but |
417 | | * rather a mathematical transformation of CMYK designed solely for storage |
418 | | * and transmission. It is to CMYK as YCbCr is to RGB. CMYK pixels can be |
419 | | * reversibly transformed into YCCK, and as with YCbCr, the chrominance |
420 | | * components in the YCCK pixels can be subsampled without incurring major |
421 | | * perceptual loss. YCCK JPEG images can only be compressed from and |
422 | | * decompressed to packed-pixel images with the CMYK pixel format. |
423 | | */ |
424 | | TJCS_YCCK |
425 | | }; |
426 | | |
427 | | |
428 | | /** |
429 | | * The number of parameters |
430 | | */ |
431 | | #define TJ_NUMPARAM |
432 | | |
433 | | /** |
434 | | * Parameters |
435 | | */ |
436 | | enum TJPARAM { |
437 | | #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION |
438 | | TJPARAM_MAXPIXELS = -1, |
439 | | #endif |
440 | | /** |
441 | | * Error handling behavior |
442 | | * |
443 | | * **Value** |
444 | | * - `0` *[default]* Allow the current compression/decompression/transform |
445 | | * operation to complete unless a fatal error is encountered. |
446 | | * - `1` Immediately discontinue the current |
447 | | * compression/decompression/transform operation if a warning (non-fatal |
448 | | * error) occurs. |
449 | | */ |
450 | | TJPARAM_STOPONWARNING, |
451 | | /** |
452 | | * Row order in packed-pixel source/destination images |
453 | | * |
454 | | * **Value** |
455 | | * - `0` *[default]* top-down (X11) order |
456 | | * - `1` bottom-up (Windows, OpenGL) order |
457 | | */ |
458 | | TJPARAM_BOTTOMUP, |
459 | | /** |
460 | | * JPEG destination buffer (re)allocation [compression, lossless |
461 | | * transformation] |
462 | | * |
463 | | * **Value** |
464 | | * - `0` *[default]* Attempt to allocate or reallocate the JPEG destination |
465 | | * buffer as needed. |
466 | | * - `1` Generate an error if the JPEG destination buffer is invalid or too |
467 | | * small. |
468 | | */ |
469 | | TJPARAM_NOREALLOC, |
470 | | /** |
471 | | * Perceptual quality of lossy JPEG images [compression only] |
472 | | * |
473 | | * **Value** |
474 | | * - `1`-`100` (`1` = worst quality but best compression, `100` = best |
475 | | * quality but worst compression) *[no default; must be explicitly |
476 | | * specified]* |
477 | | */ |
478 | | TJPARAM_QUALITY, |
479 | | /** |
480 | | * Chrominance subsampling level |
481 | | * |
482 | | * The JPEG or YUV image uses (decompression, decoding) or will use (lossy |
483 | | * compression, encoding) the specified level of chrominance subsampling. |
484 | | * |
485 | | * **Value** |
486 | | * - One of the @ref TJSAMP "chrominance subsampling options" *[no default; |
487 | | * must be explicitly specified for lossy compression, encoding, and |
488 | | * decoding]* |
489 | | */ |
490 | | TJPARAM_SUBSAMP, |
491 | | /** |
492 | | * JPEG width (in pixels) [decompression only, read-only] |
493 | | */ |
494 | | TJPARAM_JPEGWIDTH, |
495 | | /** |
496 | | * JPEG height (in pixels) [decompression only, read-only] |
497 | | */ |
498 | | TJPARAM_JPEGHEIGHT, |
499 | | /** |
500 | | * JPEG data precision (bits per sample) [decompression only, read-only] |
501 | | * |
502 | | * The JPEG image uses the specified number of bits per sample. |
503 | | * |
504 | | * **Value** |
505 | | * - `8`, `12`, or `16` |
506 | | * |
507 | | * 12-bit data precision implies #TJPARAM_OPTIMIZE unless #TJPARAM_ARITHMETIC |
508 | | * is set. |
509 | | */ |
510 | | TJPARAM_PRECISION, |
511 | | /** |
512 | | * JPEG colorspace |
513 | | * |
514 | | * The JPEG image uses (decompression) or will use (lossy compression) the |
515 | | * specified colorspace. |
516 | | * |
517 | | * **Value** |
518 | | * - One of the @ref TJCS "JPEG colorspaces" *[default for lossy compression: |
519 | | * automatically selected based on the subsampling level and pixel format]* |
520 | | */ |
521 | | TJPARAM_COLORSPACE, |
522 | | /** |
523 | | * Chrominance upsampling algorithm [lossy decompression only] |
524 | | * |
525 | | * **Value** |
526 | | * - `0` *[default]* Use smooth upsampling when decompressing a JPEG image |
527 | | * that was compressed using chrominance subsampling. This creates a smooth |
528 | | * transition between neighboring chrominance components in order to reduce |
529 | | * upsampling artifacts in the decompressed image. |
530 | | * - `1` Use the fastest chrominance upsampling algorithm available, which |
531 | | * may combine upsampling with color conversion. |
532 | | */ |
533 | | TJPARAM_FASTUPSAMPLE, |
534 | | /** |
535 | | * DCT/IDCT algorithm [lossy compression and decompression] |
536 | | * |
537 | | * **Value** |
538 | | * - `0` *[default]* Use the most accurate DCT/IDCT algorithm available. |
539 | | * - `1` Use the fastest DCT/IDCT algorithm available. |
540 | | * |
541 | | * This parameter is provided mainly for backward compatibility with libjpeg, |
542 | | * which historically implemented several different DCT/IDCT algorithms |
543 | | * because of performance limitations with 1990s CPUs. In the libjpeg-turbo |
544 | | * implementation of the TurboJPEG API: |
545 | | * - The "fast" and "accurate" DCT/IDCT algorithms perform similarly on |
546 | | * modern x86/x86-64 CPUs that support AVX2 instructions. |
547 | | * - The "fast" algorithm is generally only about 5-15% faster than the |
548 | | * "accurate" algorithm on other types of CPUs. |
549 | | * - The difference in accuracy between the "fast" and "accurate" algorithms |
550 | | * is the most pronounced at JPEG quality levels above 90 and tends to be |
551 | | * more pronounced with decompression than with compression. |
552 | | * - The "fast" algorithm degrades and is not fully accelerated for JPEG |
553 | | * quality levels above 97, so it will be slower than the "accurate" |
554 | | * algorithm. |
555 | | */ |
556 | | TJPARAM_FASTDCT, |
557 | | /** |
558 | | * Optimized baseline entropy coding [lossy compression only] |
559 | | * |
560 | | * **Value** |
561 | | * - `0` *[default]* The JPEG image will use the default Huffman tables. |
562 | | * - `1` Optimal Huffman tables will be computed for the JPEG image. For |
563 | | * lossless transformation, this can also be specified using |
564 | | * #TJXOPT_OPTIMIZE. |
565 | | * |
566 | | * Optimized baseline entropy coding will improve compression slightly |
567 | | * (generally 5% or less), but it will reduce compression performance |
568 | | * considerably. |
569 | | */ |
570 | | TJPARAM_OPTIMIZE, |
571 | | /** |
572 | | * Progressive entropy coding |
573 | | * |
574 | | * **Value** |
575 | | * - `0` *[default for compression, lossless transformation]* The lossy JPEG |
576 | | * image uses (decompression) or will use (compression, lossless |
577 | | * transformation) baseline entropy coding. |
578 | | * - `1` The lossy JPEG image uses (decompression) or will use (compression, |
579 | | * lossless transformation) progressive entropy coding. For lossless |
580 | | * transformation, this can also be specified using #TJXOPT_PROGRESSIVE. |
581 | | * |
582 | | * Progressive entropy coding will generally improve compression relative to |
583 | | * baseline entropy coding, but it will reduce compression and decompression |
584 | | * performance considerably. Can be combined with #TJPARAM_ARITHMETIC. |
585 | | * Implies #TJPARAM_OPTIMIZE unless #TJPARAM_ARITHMETIC is also set. |
586 | | */ |
587 | | TJPARAM_PROGRESSIVE, |
588 | | /** |
589 | | * Progressive JPEG scan limit for lossy JPEG images [decompression, lossless |
590 | | * transformation] |
591 | | * |
592 | | * Setting this parameter will cause the decompression and transform |
593 | | * functions to return an error if the number of scans in a progressive JPEG |
594 | | * image exceeds the specified limit. The primary purpose of this is to |
595 | | * allow security-critical applications to guard against an exploit of the |
596 | | * progressive JPEG format described in |
597 | | * <a href="https://libjpeg-turbo.org/pmwiki/uploads/About/TwoIssueswiththeJPEGStandard.pdf" target="_blank">this report</a>. |
598 | | * |
599 | | * **Value** |
600 | | * - maximum number of progressive JPEG scans that the decompression and |
601 | | * transform functions will process *[default: `0` (no limit)]* |
602 | | * |
603 | | * @see #TJPARAM_PROGRESSIVE |
604 | | */ |
605 | | TJPARAM_SCANLIMIT, |
606 | | /** |
607 | | * Arithmetic entropy coding |
608 | | * |
609 | | * **Value** |
610 | | * - `0` *[default for compression, lossless transformation]* The lossy JPEG |
611 | | * image uses (decompression) or will use (compression, lossless |
612 | | * transformation) Huffman entropy coding. |
613 | | * - `1` The lossy JPEG image uses (decompression) or will use (compression, |
614 | | * lossless transformation) arithmetic entropy coding. For lossless |
615 | | * transformation, this can also be specified using #TJXOPT_ARITHMETIC. |
616 | | * |
617 | | * Arithmetic entropy coding will generally improve compression relative to |
618 | | * Huffman entropy coding, but it will reduce compression and decompression |
619 | | * performance considerably. Can be combined with #TJPARAM_PROGRESSIVE. |
620 | | */ |
621 | | TJPARAM_ARITHMETIC, |
622 | | /** |
623 | | * Lossless JPEG |
624 | | * |
625 | | * **Value** |
626 | | * - `0` *[default for compression]* The JPEG image is (decompression) or |
627 | | * will be (compression) lossy/DCT-based. |
628 | | * - `1` The JPEG image is (decompression) or will be (compression) |
629 | | * lossless/predictive. |
630 | | * |
631 | | * In most cases, compressing and decompressing lossless JPEG images is |
632 | | * considerably slower than compressing and decompressing lossy JPEG images. |
633 | | * Also note that the following features are not available with lossless JPEG |
634 | | * images: |
635 | | * - Colorspace conversion (lossless JPEG images always use #TJCS_RGB, |
636 | | * #TJCS_GRAY, or #TJCS_CMYK, depending on the pixel format of the source |
637 | | * image) |
638 | | * - Chrominance subsampling (lossless JPEG images always use #TJSAMP_444) |
639 | | * - JPEG quality selection |
640 | | * - DCT/IDCT algorithm selection |
641 | | * - Progressive entropy coding |
642 | | * - Arithmetic entropy coding |
643 | | * - Compression from/decompression to planar YUV images |
644 | | * - Decompression scaling |
645 | | * - Lossless transformation |
646 | | * |
647 | | * @see #TJPARAM_LOSSLESSPSV, #TJPARAM_LOSSLESSPT |
648 | | */ |
649 | | TJPARAM_LOSSLESS, |
650 | | /** |
651 | | * Lossless JPEG predictor selection value (PSV) |
652 | | * |
653 | | * **Value** |
654 | | * - `1`-`7` *[default for compression: `1`]* |
655 | | * |
656 | | * @see #TJPARAM_LOSSLESS |
657 | | */ |
658 | | TJPARAM_LOSSLESSPSV, |
659 | | /** |
660 | | * Lossless JPEG point transform (Pt) |
661 | | * |
662 | | * **Value** |
663 | | * - `0` through ***precision*** *- 1*, where ***precision*** is the JPEG |
664 | | * data precision in bits *[default for compression: `0`]* |
665 | | * |
666 | | * A point transform value of `0` is necessary in order to generate a fully |
667 | | * lossless JPEG image. (A non-zero point transform value right-shifts the |
668 | | * input samples by the specified number of bits, which is effectively a form |
669 | | * of lossy color quantization.) |
670 | | * |
671 | | * @see #TJPARAM_LOSSLESS, #TJPARAM_PRECISION |
672 | | */ |
673 | | TJPARAM_LOSSLESSPT, |
674 | | /** |
675 | | * JPEG restart marker interval in MCU blocks (lossy) or samples (lossless) |
676 | | * [compression only] |
677 | | * |
678 | | * The nature of entropy coding is such that a corrupt JPEG image cannot |
679 | | * be decompressed beyond the point of corruption unless it contains restart |
680 | | * markers. A restart marker stops and restarts the entropy coding algorithm |
681 | | * so that, if a JPEG image is corrupted, decompression can resume at the |
682 | | * next marker. Thus, adding more restart markers improves the fault |
683 | | * tolerance of the JPEG image, but adding too many restart markers can |
684 | | * adversely affect the compression ratio and performance. |
685 | | * |
686 | | * **Value** |
687 | | * - the number of MCU blocks or samples between each restart marker |
688 | | * *[default: `0` (no restart markers)]* |
689 | | * |
690 | | * Setting this parameter to a non-zero value sets #TJPARAM_RESTARTROWS to 0. |
691 | | */ |
692 | | TJPARAM_RESTARTBLOCKS, |
693 | | /** |
694 | | * JPEG restart marker interval in MCU rows (lossy) or sample rows (lossless) |
695 | | * [compression only] |
696 | | * |
697 | | * See #TJPARAM_RESTARTBLOCKS for a description of restart markers. |
698 | | * |
699 | | * **Value** |
700 | | * - the number of MCU rows or sample rows between each restart marker |
701 | | * *[default: `0` (no restart markers)]* |
702 | | * |
703 | | * Setting this parameter to a non-zero value sets #TJPARAM_RESTARTBLOCKS to |
704 | | * 0. |
705 | | */ |
706 | | TJPARAM_RESTARTROWS, |
707 | | /** |
708 | | * JPEG horizontal pixel density |
709 | | * |
710 | | * **Value** |
711 | | * - The JPEG image has (decompression) or will have (compression) the |
712 | | * specified horizontal pixel density *[default for compression: `1`]*. |
713 | | * |
714 | | * This value is stored in or read from the JPEG header. It does not affect |
715 | | * the contents of the JPEG image. Note that this parameter is set by |
716 | | * #tj3LoadImage8() when loading a Windows BMP file that contains pixel |
717 | | * density information, and the value of this parameter is stored to a |
718 | | * Windows BMP file by #tj3SaveImage8() if the value of #TJPARAM_DENSITYUNIT |
719 | | * is `2`. |
720 | | * |
721 | | * @see TJPARAM_DENSITYUNIT |
722 | | */ |
723 | | TJPARAM_XDENSITY, |
724 | | /** |
725 | | * JPEG vertical pixel density |
726 | | * |
727 | | * **Value** |
728 | | * - The JPEG image has (decompression) or will have (compression) the |
729 | | * specified vertical pixel density *[default for compression: `1`]*. |
730 | | * |
731 | | * This value is stored in or read from the JPEG header. It does not affect |
732 | | * the contents of the JPEG image. Note that this parameter is set by |
733 | | * #tj3LoadImage8() when loading a Windows BMP file that contains pixel |
734 | | * density information, and the value of this parameter is stored to a |
735 | | * Windows BMP file by #tj3SaveImage8() if the value of #TJPARAM_DENSITYUNIT |
736 | | * is `2`. |
737 | | * |
738 | | * @see TJPARAM_DENSITYUNIT |
739 | | */ |
740 | | TJPARAM_YDENSITY, |
741 | | /** |
742 | | * JPEG pixel density units |
743 | | * |
744 | | * **Value** |
745 | | * - `0` *[default for compression]* The pixel density of the JPEG image is |
746 | | * expressed (decompression) or will be expressed (compression) in unknown |
747 | | * units. |
748 | | * - `1` The pixel density of the JPEG image is expressed (decompression) or |
749 | | * will be expressed (compression) in units of pixels/inch. |
750 | | * - `2` The pixel density of the JPEG image is expressed (decompression) or |
751 | | * will be expressed (compression) in units of pixels/cm. |
752 | | * |
753 | | * This value is stored in or read from the JPEG header. It does not affect |
754 | | * the contents of the JPEG image. Note that this parameter is set by |
755 | | * #tj3LoadImage8() when loading a Windows BMP file that contains pixel |
756 | | * density information, and the value of this parameter is stored to a |
757 | | * Windows BMP file by #tj3SaveImage8() if the value is `2`. |
758 | | * |
759 | | * @see TJPARAM_XDENSITY, TJPARAM_YDENSITY |
760 | | */ |
761 | | TJPARAM_DENSITYUNITS |
762 | | }; |
763 | | |
764 | | |
765 | | /** |
766 | | * The number of error codes |
767 | | */ |
768 | | #define TJ_NUMERR 2 |
769 | | |
770 | | /** |
771 | | * Error codes |
772 | | */ |
773 | | enum TJERR { |
774 | | /** |
775 | | * The error was non-fatal and recoverable, but the destination image may |
776 | | * still be corrupt. |
777 | | */ |
778 | | TJERR_WARNING, |
779 | | /** |
780 | | * The error was fatal and non-recoverable. |
781 | | */ |
782 | | TJERR_FATAL |
783 | | }; |
784 | | |
785 | | |
786 | | /** |
787 | | * The number of transform operations |
788 | | */ |
789 | | #define TJ_NUMXOP 8 |
790 | | |
791 | | /** |
792 | | * Transform operations for #tj3Transform() |
793 | | */ |
794 | | enum TJXOP { |
795 | | /** |
796 | | * Do not transform the position of the image pixels |
797 | | */ |
798 | | TJXOP_NONE, |
799 | | /** |
800 | | * Flip (mirror) image horizontally. This transform is imperfect if there |
801 | | * are any partial MCU blocks on the right edge (see #TJXOPT_PERFECT.) |
802 | | */ |
803 | | TJXOP_HFLIP, |
804 | | /** |
805 | | * Flip (mirror) image vertically. This transform is imperfect if there are |
806 | | * any partial MCU blocks on the bottom edge (see #TJXOPT_PERFECT.) |
807 | | */ |
808 | | TJXOP_VFLIP, |
809 | | /** |
810 | | * Transpose image (flip/mirror along upper left to lower right axis.) This |
811 | | * transform is always perfect. |
812 | | */ |
813 | | TJXOP_TRANSPOSE, |
814 | | /** |
815 | | * Transverse transpose image (flip/mirror along upper right to lower left |
816 | | * axis.) This transform is imperfect if there are any partial MCU blocks in |
817 | | * the image (see #TJXOPT_PERFECT.) |
818 | | */ |
819 | | TJXOP_TRANSVERSE, |
820 | | /** |
821 | | * Rotate image clockwise by 90 degrees. This transform is imperfect if |
822 | | * there are any partial MCU blocks on the bottom edge (see |
823 | | * #TJXOPT_PERFECT.) |
824 | | */ |
825 | | TJXOP_ROT90, |
826 | | /** |
827 | | * Rotate image 180 degrees. This transform is imperfect if there are any |
828 | | * partial MCU blocks in the image (see #TJXOPT_PERFECT.) |
829 | | */ |
830 | | TJXOP_ROT180, |
831 | | /** |
832 | | * Rotate image counter-clockwise by 90 degrees. This transform is imperfect |
833 | | * if there are any partial MCU blocks on the right edge (see |
834 | | * #TJXOPT_PERFECT.) |
835 | | */ |
836 | | TJXOP_ROT270 |
837 | | }; |
838 | | |
839 | | |
840 | | /** |
841 | | * This option will cause #tj3Transform() to return an error if the transform |
842 | | * is not perfect. Lossless transforms operate on MCU blocks, whose size |
843 | | * depends on the level of chrominance subsampling used (see #tjMCUWidth and |
844 | | * #tjMCUHeight.) If the image's width or height is not evenly divisible by |
845 | | * the MCU block size, then there will be partial MCU blocks on the right |
846 | | * and/or bottom edges. It is not possible to move these partial MCU blocks to |
847 | | * the top or left of the image, so any transform that would require that is |
848 | | * "imperfect." If this option is not specified, then any partial MCU blocks |
849 | | * that cannot be transformed will be left in place, which will create |
850 | | * odd-looking strips on the right or bottom edge of the image. |
851 | | */ |
852 | 0 | #define TJXOPT_PERFECT (1 << 0) |
853 | | /** |
854 | | * This option will cause #tj3Transform() to discard any partial MCU blocks |
855 | | * that cannot be transformed. |
856 | | */ |
857 | 0 | #define TJXOPT_TRIM (1 << 1) |
858 | | /** |
859 | | * This option will enable lossless cropping. See #tj3Transform() for more |
860 | | * information. |
861 | | */ |
862 | 0 | #define TJXOPT_CROP (1 << 2) |
863 | | /** |
864 | | * This option will discard the color data in the source image and produce a |
865 | | * grayscale destination image. |
866 | | */ |
867 | 0 | #define TJXOPT_GRAY (1 << 3) |
868 | | /** |
869 | | * This option will prevent #tj3Transform() from outputting a JPEG image for |
870 | | * this particular transform. (This can be used in conjunction with a custom |
871 | | * filter to capture the transformed DCT coefficients without transcoding |
872 | | * them.) |
873 | | */ |
874 | 0 | #define TJXOPT_NOOUTPUT (1 << 4) |
875 | | /** |
876 | | * This option will enable progressive entropy coding in the JPEG image |
877 | | * generated by this particular transform. Progressive entropy coding will |
878 | | * generally improve compression relative to baseline entropy coding (the |
879 | | * default), but it will reduce decompression performance considerably. |
880 | | * Can be combined with #TJXOPT_ARITHMETIC. Implies #TJXOPT_OPTIMIZE unless |
881 | | * #TJXOPT_ARITHMETIC is also specified. |
882 | | */ |
883 | 0 | #define TJXOPT_PROGRESSIVE (1 << 5) |
884 | | /** |
885 | | * This option will prevent #tj3Transform() from copying any extra markers |
886 | | * (including EXIF and ICC profile data) from the source image to the |
887 | | * destination image. |
888 | | */ |
889 | 0 | #define TJXOPT_COPYNONE (1 << 6) |
890 | | /** |
891 | | * This option will enable arithmetic entropy coding in the JPEG image |
892 | | * generated by this particular transform. Arithmetic entropy coding will |
893 | | * generally improve compression relative to Huffman entropy coding (the |
894 | | * default), but it will reduce decompression performance considerably. Can be |
895 | | * combined with #TJXOPT_PROGRESSIVE. |
896 | | */ |
897 | 0 | #define TJXOPT_ARITHMETIC (1 << 7) |
898 | | /** |
899 | | * This option will enable optimized baseline entropy coding in the JPEG image |
900 | | * generated by this particular transform. Optimized baseline entropy coding |
901 | | * will improve compression slightly (generally 5% or less.) |
902 | | */ |
903 | 0 | #define TJXOPT_OPTIMIZE (1 << 8) |
904 | | |
905 | | |
906 | | /** |
907 | | * Scaling factor |
908 | | */ |
909 | | typedef struct { |
910 | | /** |
911 | | * Numerator |
912 | | */ |
913 | | int num; |
914 | | /** |
915 | | * Denominator |
916 | | */ |
917 | | int denom; |
918 | | } tjscalingfactor; |
919 | | |
920 | | /** |
921 | | * Cropping region |
922 | | */ |
923 | | typedef struct { |
924 | | /** |
925 | | * The left boundary of the cropping region. This must be evenly divisible |
926 | | * by the MCU block width (see #tjMCUWidth.) |
927 | | */ |
928 | | int x; |
929 | | /** |
930 | | * The upper boundary of the cropping region. For lossless transformation, |
931 | | * this must be evenly divisible by the MCU block height (see #tjMCUHeight.) |
932 | | */ |
933 | | int y; |
934 | | /** |
935 | | * The width of the cropping region. Setting this to 0 is the equivalent of |
936 | | * setting it to the width of the source JPEG image - x. |
937 | | */ |
938 | | int w; |
939 | | /** |
940 | | * The height of the cropping region. Setting this to 0 is the equivalent of |
941 | | * setting it to the height of the source JPEG image - y. |
942 | | */ |
943 | | int h; |
944 | | } tjregion; |
945 | | |
946 | | /** |
947 | | * A #tjregion structure that specifies no cropping |
948 | | */ |
949 | | static const tjregion TJUNCROPPED = { 0, 0, 0, 0 }; |
950 | | |
951 | | /** |
952 | | * Lossless transform |
953 | | */ |
954 | | typedef struct tjtransform { |
955 | | /** |
956 | | * Cropping region |
957 | | */ |
958 | | tjregion r; |
959 | | /** |
960 | | * One of the @ref TJXOP "transform operations" |
961 | | */ |
962 | | int op; |
963 | | /** |
964 | | * The bitwise OR of one of more of the @ref TJXOPT_ARITHMETIC |
965 | | * "transform options" |
966 | | */ |
967 | | int options; |
968 | | /** |
969 | | * Arbitrary data that can be accessed within the body of the callback |
970 | | * function |
971 | | */ |
972 | | void *data; |
973 | | /** |
974 | | * A callback function that can be used to modify the DCT coefficients after |
975 | | * they are losslessly transformed but before they are transcoded to a new |
976 | | * JPEG image. This allows for custom filters or other transformations to be |
977 | | * applied in the frequency domain. |
978 | | * |
979 | | * @param coeffs pointer to an array of transformed DCT coefficients. (NOTE: |
980 | | * this pointer is not guaranteed to be valid once the callback returns, so |
981 | | * applications wishing to hand off the DCT coefficients to another function |
982 | | * or library should make a copy of them within the body of the callback.) |
983 | | * |
984 | | * @param arrayRegion #tjregion structure containing the width and height of |
985 | | * the array pointed to by `coeffs` as well as its offset relative to the |
986 | | * component plane. TurboJPEG implementations may choose to split each |
987 | | * component plane into multiple DCT coefficient arrays and call the callback |
988 | | * function once for each array. |
989 | | * |
990 | | * @param planeRegion #tjregion structure containing the width and height of |
991 | | * the component plane to which `coeffs` belongs |
992 | | * |
993 | | * @param componentID ID number of the component plane to which `coeffs` |
994 | | * belongs. (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in |
995 | | * typical JPEG images.) |
996 | | * |
997 | | * @param transformID ID number of the transformed image to which `coeffs` |
998 | | * belongs. This is the same as the index of the transform in the |
999 | | * `transforms` array that was passed to #tj3Transform(). |
1000 | | * |
1001 | | * @param transform a pointer to a #tjtransform structure that specifies the |
1002 | | * parameters and/or cropping region for this transform |
1003 | | * |
1004 | | * @return 0 if the callback was successful, or -1 if an error occurred. |
1005 | | */ |
1006 | | int (*customFilter) (short *coeffs, tjregion arrayRegion, |
1007 | | tjregion planeRegion, int componentIndex, |
1008 | | int transformIndex, struct tjtransform *transform); |
1009 | | } tjtransform; |
1010 | | |
1011 | | /** |
1012 | | * TurboJPEG instance handle |
1013 | | */ |
1014 | | typedef void *tjhandle; |
1015 | | |
1016 | | |
1017 | | /** |
1018 | | * Compute the scaled value of `dimension` using the given scaling factor. |
1019 | | * This macro performs the integer equivalent of `ceil(dimension * |
1020 | | * scalingFactor)`. |
1021 | | */ |
1022 | | #define TJSCALED(dimension, scalingFactor) \ |
1023 | 126k | (((dimension) * scalingFactor.num + scalingFactor.denom - 1) / \ |
1024 | 126k | scalingFactor.denom) |
1025 | | |
1026 | | /** |
1027 | | * A #tjscalingfactor structure that specifies a scaling factor of 1/1 (no |
1028 | | * scaling) |
1029 | | */ |
1030 | | static const tjscalingfactor TJUNSCALED = { 1, 1 }; |
1031 | | |
1032 | | |
1033 | | #ifdef __cplusplus |
1034 | | extern "C" { |
1035 | | #endif |
1036 | | |
1037 | | |
1038 | | /** |
1039 | | * Create a new TurboJPEG instance. |
1040 | | * |
1041 | | * @param initType one of the @ref TJINIT "initialization options" |
1042 | | * |
1043 | | * @return a handle to the newly-created instance, or NULL if an error occurred |
1044 | | * (see #tj3GetErrorStr().) |
1045 | | */ |
1046 | | DLLEXPORT tjhandle tj3Init(int initType); |
1047 | | |
1048 | | |
1049 | | /** |
1050 | | * Set the value of a parameter. |
1051 | | * |
1052 | | * @param handle handle to a TurboJPEG instance |
1053 | | * |
1054 | | * @param param one of the @ref TJPARAM "parameters" |
1055 | | * |
1056 | | * @param value value of the parameter (refer to @ref TJPARAM |
1057 | | * "parameter documentation") |
1058 | | * |
1059 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr().) |
1060 | | */ |
1061 | | DLLEXPORT int tj3Set(tjhandle handle, int param, int value); |
1062 | | |
1063 | | |
1064 | | /** |
1065 | | * Get the value of a parameter. |
1066 | | * |
1067 | | * @param handle handle to a TurboJPEG instance |
1068 | | * |
1069 | | * @param param one of the @ref TJPARAM "parameters" |
1070 | | * |
1071 | | * @return the value of the specified parameter, or -1 if the value is unknown. |
1072 | | */ |
1073 | | DLLEXPORT int tj3Get(tjhandle handle, int param); |
1074 | | |
1075 | | |
1076 | | /** |
1077 | | * Compress an 8-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into |
1078 | | * an 8-bit-per-sample JPEG image. |
1079 | | * |
1080 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1081 | | * compression |
1082 | | * |
1083 | | * @param srcBuf pointer to a buffer containing a packed-pixel RGB, grayscale, |
1084 | | * or CMYK source image to be compressed. This buffer should normally be |
1085 | | * `pitch * height` samples in size. However, you can also use this parameter |
1086 | | * to compress from a specific region of a larger buffer. |
1087 | | * |
1088 | | * @param width width (in pixels) of the source image |
1089 | | * |
1090 | | * @param pitch samples per row in the source image. Normally this should be |
1091 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded. |
1092 | | * (Setting this parameter to 0 is the equivalent of setting it to |
1093 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this |
1094 | | * parameter to specify the row alignment/padding of the source image, to skip |
1095 | | * rows, or to compress from a specific region of a larger buffer. |
1096 | | * |
1097 | | * @param height height (in pixels) of the source image |
1098 | | * |
1099 | | * @param pixelFormat pixel format of the source image (see @ref TJPF |
1100 | | * "Pixel formats".) |
1101 | | * |
1102 | | * @param jpegBuf address of a pointer to a byte buffer that will receive the |
1103 | | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to |
1104 | | * accommodate the size of the JPEG image. Thus, you can choose to: |
1105 | | * -# pre-allocate the JPEG buffer with an arbitrary size using #tj3Alloc() and |
1106 | | * let TurboJPEG grow the buffer as needed, |
1107 | | * -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you, |
1108 | | * or |
1109 | | * -# pre-allocate the buffer to a "worst case" size determined by calling |
1110 | | * #tj3JPEGBufSize(). This should ensure that the buffer never has to be |
1111 | | * re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.) |
1112 | | * . |
1113 | | * If you choose option 1, then `*jpegSize` should be set to the size of your |
1114 | | * pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC, |
1115 | | * you should always check `*jpegBuf` upon return from this function, as it may |
1116 | | * have changed. |
1117 | | * |
1118 | | * @param jpegSize pointer to a size_t variable that holds the size of the JPEG |
1119 | | * buffer. If `*jpegBuf` points to a pre-allocated buffer, then `*jpegSize` |
1120 | | * should be set to the size of the buffer. Upon return, `*jpegSize` will |
1121 | | * contain the size of the JPEG image (in bytes.) If `*jpegBuf` points to a |
1122 | | * JPEG buffer that is being reused from a previous call to one of the JPEG |
1123 | | * compression functions, then `*jpegSize` is ignored. |
1124 | | * |
1125 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1126 | | * and #tj3GetErrorCode().) |
1127 | | */ |
1128 | | DLLEXPORT int tj3Compress8(tjhandle handle, const unsigned char *srcBuf, |
1129 | | int width, int pitch, int height, int pixelFormat, |
1130 | | unsigned char **jpegBuf, size_t *jpegSize); |
1131 | | |
1132 | | /** |
1133 | | * Compress a 12-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into |
1134 | | * a 12-bit-per-sample JPEG image. |
1135 | | * |
1136 | | * \details \copydetails tj3Compress8() |
1137 | | */ |
1138 | | DLLEXPORT int tj3Compress12(tjhandle handle, const short *srcBuf, int width, |
1139 | | int pitch, int height, int pixelFormat, |
1140 | | unsigned char **jpegBuf, size_t *jpegSize); |
1141 | | |
1142 | | /** |
1143 | | * Compress a 16-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into |
1144 | | * a 16-bit-per-sample lossless JPEG image. |
1145 | | * |
1146 | | * \details \copydetails tj3Compress8() |
1147 | | */ |
1148 | | DLLEXPORT int tj3Compress16(tjhandle handle, const unsigned short *srcBuf, |
1149 | | int width, int pitch, int height, int pixelFormat, |
1150 | | unsigned char **jpegBuf, size_t *jpegSize); |
1151 | | |
1152 | | |
1153 | | /** |
1154 | | * Compress an 8-bit-per-sample unified planar YUV image into an |
1155 | | * 8-bit-per-sample JPEG image. |
1156 | | * |
1157 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1158 | | * compression |
1159 | | * |
1160 | | * @param srcBuf pointer to a buffer containing a unified planar YUV source |
1161 | | * image to be compressed. The size of this buffer should match the value |
1162 | | * returned by #tj3YUVBufSize() for the given image width, height, row |
1163 | | * alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The |
1164 | | * Y, U (Cb), and V (Cr) image planes should be stored sequentially in the |
1165 | | * buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".) |
1166 | | * |
1167 | | * @param width width (in pixels) of the source image. If the width is not an |
1168 | | * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate |
1169 | | * buffer copy will be performed. |
1170 | | * |
1171 | | * @param align row alignment (in bytes) of the source image (must be a power |
1172 | | * of 2.) Setting this parameter to n indicates that each row in each plane of |
1173 | | * the source image is padded to the nearest multiple of n bytes |
1174 | | * (1 = unpadded.) |
1175 | | * |
1176 | | * @param height height (in pixels) of the source image. If the height is not |
1177 | | * an even multiple of the MCU block height (see #tjMCUHeight), then an |
1178 | | * intermediate buffer copy will be performed. |
1179 | | * |
1180 | | * @param jpegBuf address of a pointer to a byte buffer that will receive the |
1181 | | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to |
1182 | | * accommodate the size of the JPEG image. Thus, you can choose to: |
1183 | | * -# pre-allocate the JPEG buffer with an arbitrary size using #tj3Alloc() and |
1184 | | * let TurboJPEG grow the buffer as needed, |
1185 | | * -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you, |
1186 | | * or |
1187 | | * -# pre-allocate the buffer to a "worst case" size determined by calling |
1188 | | * #tj3JPEGBufSize(). This should ensure that the buffer never has to be |
1189 | | * re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.) |
1190 | | * . |
1191 | | * If you choose option 1, then `*jpegSize` should be set to the size of your |
1192 | | * pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC, |
1193 | | * you should always check `*jpegBuf` upon return from this function, as it may |
1194 | | * have changed. |
1195 | | * |
1196 | | * @param jpegSize pointer to a size_t variable that holds the size of the JPEG |
1197 | | * buffer. If `*jpegBuf` points to a pre-allocated buffer, then `*jpegSize` |
1198 | | * should be set to the size of the buffer. Upon return, `*jpegSize` will |
1199 | | * contain the size of the JPEG image (in bytes.) If `*jpegBuf` points to a |
1200 | | * JPEG buffer that is being reused from a previous call to one of the JPEG |
1201 | | * compression functions, then `*jpegSize` is ignored. |
1202 | | * |
1203 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1204 | | * and #tj3GetErrorCode().) |
1205 | | */ |
1206 | | DLLEXPORT int tj3CompressFromYUV8(tjhandle handle, |
1207 | | const unsigned char *srcBuf, int width, |
1208 | | int align, int height, |
1209 | | unsigned char **jpegBuf, size_t *jpegSize); |
1210 | | |
1211 | | |
1212 | | /** |
1213 | | * Compress a set of 8-bit-per-sample Y, U (Cb), and V (Cr) image planes into |
1214 | | * an 8-bit-per-sample JPEG image. |
1215 | | * |
1216 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1217 | | * compression |
1218 | | * |
1219 | | * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes |
1220 | | * (or just a Y plane, if compressing a grayscale image) that contain a YUV |
1221 | | * source image to be compressed. These planes can be contiguous or |
1222 | | * non-contiguous in memory. The size of each plane should match the value |
1223 | | * returned by #tj3YUVPlaneSize() for the given image width, height, strides, |
1224 | | * and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) Refer to |
1225 | | * @ref YUVnotes "YUV Image Format Notes" for more details. |
1226 | | * |
1227 | | * @param width width (in pixels) of the source image. If the width is not an |
1228 | | * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate |
1229 | | * buffer copy will be performed. |
1230 | | * |
1231 | | * @param strides an array of integers, each specifying the number of bytes per |
1232 | | * row in the corresponding plane of the YUV source image. Setting the stride |
1233 | | * for any plane to 0 is the same as setting it to the plane width (see |
1234 | | * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the |
1235 | | * strides for all planes will be set to their respective plane widths. You |
1236 | | * can adjust the strides in order to specify an arbitrary amount of row |
1237 | | * padding in each plane or to create a JPEG image from a subregion of a larger |
1238 | | * planar YUV image. |
1239 | | * |
1240 | | * @param height height (in pixels) of the source image. If the height is not |
1241 | | * an even multiple of the MCU block height (see #tjMCUHeight), then an |
1242 | | * intermediate buffer copy will be performed. |
1243 | | * |
1244 | | * @param jpegBuf address of a pointer to a byte buffer that will receive the |
1245 | | * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to |
1246 | | * accommodate the size of the JPEG image. Thus, you can choose to: |
1247 | | * -# pre-allocate the JPEG buffer with an arbitrary size using #tj3Alloc() and |
1248 | | * let TurboJPEG grow the buffer as needed, |
1249 | | * -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you, |
1250 | | * or |
1251 | | * -# pre-allocate the buffer to a "worst case" size determined by calling |
1252 | | * #tj3JPEGBufSize(). This should ensure that the buffer never has to be |
1253 | | * re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.) |
1254 | | * . |
1255 | | * If you choose option 1, then `*jpegSize` should be set to the size of your |
1256 | | * pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC, |
1257 | | * you should always check `*jpegBuf` upon return from this function, as it may |
1258 | | * have changed. |
1259 | | * |
1260 | | * @param jpegSize pointer to a size_t variable that holds the size of the JPEG |
1261 | | * buffer. If `*jpegBuf` points to a pre-allocated buffer, then `*jpegSize` |
1262 | | * should be set to the size of the buffer. Upon return, `*jpegSize` will |
1263 | | * contain the size of the JPEG image (in bytes.) If `*jpegBuf` points to a |
1264 | | * JPEG buffer that is being reused from a previous call to one of the JPEG |
1265 | | * compression functions, then `*jpegSize` is ignored. |
1266 | | * |
1267 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1268 | | * and #tj3GetErrorCode().) |
1269 | | */ |
1270 | | DLLEXPORT int tj3CompressFromYUVPlanes8(tjhandle handle, |
1271 | | const unsigned char * const *srcPlanes, |
1272 | | int width, const int *strides, |
1273 | | int height, unsigned char **jpegBuf, |
1274 | | size_t *jpegSize); |
1275 | | |
1276 | | |
1277 | | /** |
1278 | | * The maximum size of the buffer (in bytes) required to hold a JPEG image with |
1279 | | * the given parameters. The number of bytes returned by this function is |
1280 | | * larger than the size of the uncompressed source image. The reason for this |
1281 | | * is that the JPEG format uses 16-bit coefficients, so it is possible for a |
1282 | | * very high-quality source image with very high-frequency content to expand |
1283 | | * rather than compress when converted to the JPEG format. Such images |
1284 | | * represent very rare corner cases, but since there is no way to predict the |
1285 | | * size of a JPEG image prior to compression, the corner cases have to be |
1286 | | * handled. |
1287 | | * |
1288 | | * @param width width (in pixels) of the image |
1289 | | * |
1290 | | * @param height height (in pixels) of the image |
1291 | | * |
1292 | | * @param jpegSubsamp the level of chrominance subsampling to be used when |
1293 | | * generating the JPEG image (see @ref TJSAMP |
1294 | | * "Chrominance subsampling options".) #TJSAMP_UNKNOWN is treated like |
1295 | | * #TJSAMP_444, since a buffer large enough to hold a JPEG image with no |
1296 | | * subsampling should also be large enough to hold a JPEG image with an |
1297 | | * arbitrary level of subsampling. Note that lossless JPEG images always |
1298 | | * use #TJSAMP_444. |
1299 | | * |
1300 | | * @return the maximum size of the buffer (in bytes) required to hold the |
1301 | | * image, or 0 if the arguments are out of bounds. |
1302 | | */ |
1303 | | DLLEXPORT size_t tj3JPEGBufSize(int width, int height, int jpegSubsamp); |
1304 | | |
1305 | | |
1306 | | /** |
1307 | | * The size of the buffer (in bytes) required to hold a unified planar YUV |
1308 | | * image with the given parameters. |
1309 | | * |
1310 | | * @param width width (in pixels) of the image |
1311 | | * |
1312 | | * @param align row alignment (in bytes) of the image (must be a power of 2.) |
1313 | | * Setting this parameter to n specifies that each row in each plane of the |
1314 | | * image will be padded to the nearest multiple of n bytes (1 = unpadded.) |
1315 | | * |
1316 | | * @param height height (in pixels) of the image |
1317 | | * |
1318 | | * @param subsamp level of chrominance subsampling in the image (see |
1319 | | * @ref TJSAMP "Chrominance subsampling options".) |
1320 | | * |
1321 | | * @return the size of the buffer (in bytes) required to hold the image, or 0 |
1322 | | * if the arguments are out of bounds. |
1323 | | */ |
1324 | | DLLEXPORT size_t tj3YUVBufSize(int width, int align, int height, int subsamp); |
1325 | | |
1326 | | |
1327 | | /** |
1328 | | * The size of the buffer (in bytes) required to hold a YUV image plane with |
1329 | | * the given parameters. |
1330 | | * |
1331 | | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr) |
1332 | | * |
1333 | | * @param width width (in pixels) of the YUV image. NOTE: this is the width of |
1334 | | * the whole image, not the plane width. |
1335 | | * |
1336 | | * @param stride bytes per row in the image plane. Setting this to 0 is the |
1337 | | * equivalent of setting it to the plane width. |
1338 | | * |
1339 | | * @param height height (in pixels) of the YUV image. NOTE: this is the height |
1340 | | * of the whole image, not the plane height. |
1341 | | * |
1342 | | * @param subsamp level of chrominance subsampling in the image (see |
1343 | | * @ref TJSAMP "Chrominance subsampling options".) |
1344 | | * |
1345 | | * @return the size of the buffer (in bytes) required to hold the YUV image |
1346 | | * plane, or 0 if the arguments are out of bounds. |
1347 | | */ |
1348 | | DLLEXPORT size_t tj3YUVPlaneSize(int componentID, int width, int stride, |
1349 | | int height, int subsamp); |
1350 | | |
1351 | | |
1352 | | /** |
1353 | | * The plane width of a YUV image plane with the given parameters. Refer to |
1354 | | * @ref YUVnotes "YUV Image Format Notes" for a description of plane width. |
1355 | | * |
1356 | | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr) |
1357 | | * |
1358 | | * @param width width (in pixels) of the YUV image |
1359 | | * |
1360 | | * @param subsamp level of chrominance subsampling in the image (see |
1361 | | * @ref TJSAMP "Chrominance subsampling options".) |
1362 | | * |
1363 | | * @return the plane width of a YUV image plane with the given parameters, or 0 |
1364 | | * if the arguments are out of bounds. |
1365 | | */ |
1366 | | DLLEXPORT int tj3YUVPlaneWidth(int componentID, int width, int subsamp); |
1367 | | |
1368 | | |
1369 | | /** |
1370 | | * The plane height of a YUV image plane with the given parameters. Refer to |
1371 | | * @ref YUVnotes "YUV Image Format Notes" for a description of plane height. |
1372 | | * |
1373 | | * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr) |
1374 | | * |
1375 | | * @param height height (in pixels) of the YUV image |
1376 | | * |
1377 | | * @param subsamp level of chrominance subsampling in the image (see |
1378 | | * @ref TJSAMP "Chrominance subsampling options".) |
1379 | | * |
1380 | | * @return the plane height of a YUV image plane with the given parameters, or |
1381 | | * 0 if the arguments are out of bounds. |
1382 | | */ |
1383 | | DLLEXPORT int tj3YUVPlaneHeight(int componentID, int height, int subsamp); |
1384 | | |
1385 | | |
1386 | | /** |
1387 | | * Encode an 8-bit-per-sample packed-pixel RGB or grayscale image into an |
1388 | | * 8-bit-per-sample unified planar YUV image. This function performs color |
1389 | | * conversion (which is accelerated in the libjpeg-turbo implementation) but |
1390 | | * does not execute any of the other steps in the JPEG compression process. |
1391 | | * |
1392 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1393 | | * compression |
1394 | | * |
1395 | | * @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale |
1396 | | * source image to be encoded. This buffer should normally be `pitch * height` |
1397 | | * bytes in size. However, you can also use this parameter to encode from a |
1398 | | * specific region of a larger buffer. |
1399 | | * |
1400 | | * @param width width (in pixels) of the source image |
1401 | | * |
1402 | | * @param pitch bytes per row in the source image. Normally this should be |
1403 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded. |
1404 | | * (Setting this parameter to 0 is the equivalent of setting it to |
1405 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this |
1406 | | * parameter to specify the row alignment/padding of the source image, to skip |
1407 | | * rows, or to encode from a specific region of a larger packed-pixel image. |
1408 | | * |
1409 | | * @param height height (in pixels) of the source image |
1410 | | * |
1411 | | * @param pixelFormat pixel format of the source image (see @ref TJPF |
1412 | | * "Pixel formats".) |
1413 | | * |
1414 | | * @param dstBuf pointer to a buffer that will receive the unified planar YUV |
1415 | | * image. Use #tj3YUVBufSize() to determine the appropriate size for this |
1416 | | * buffer based on the image width, height, row alignment, and level of |
1417 | | * chrominance subsampling (see #TJPARAM_SUBSAMP.) The Y, U (Cb), and V (Cr) |
1418 | | * image planes will be stored sequentially in the buffer. (Refer to |
1419 | | * @ref YUVnotes "YUV Image Format Notes".) |
1420 | | * |
1421 | | * @param align row alignment (in bytes) of the YUV image (must be a power of |
1422 | | * 2.) Setting this parameter to n will cause each row in each plane of the |
1423 | | * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) |
1424 | | * To generate images suitable for X Video, `align` should be set to 4. |
1425 | | * |
1426 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1427 | | * and #tj3GetErrorCode().) |
1428 | | */ |
1429 | | DLLEXPORT int tj3EncodeYUV8(tjhandle handle, const unsigned char *srcBuf, |
1430 | | int width, int pitch, int height, int pixelFormat, |
1431 | | unsigned char *dstBuf, int align); |
1432 | | |
1433 | | |
1434 | | /** |
1435 | | * Encode an 8-bit-per-sample packed-pixel RGB or grayscale image into separate |
1436 | | * 8-bit-per-sample Y, U (Cb), and V (Cr) image planes. This function performs |
1437 | | * color conversion (which is accelerated in the libjpeg-turbo implementation) |
1438 | | * but does not execute any of the other steps in the JPEG compression process. |
1439 | | * |
1440 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1441 | | * compression |
1442 | | * |
1443 | | * @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale |
1444 | | * source image to be encoded. This buffer should normally be `pitch * height` |
1445 | | * bytes in size. However, you can also use this parameter to encode from a |
1446 | | * specific region of a larger buffer. |
1447 | | * |
1448 | | * |
1449 | | * @param width width (in pixels) of the source image |
1450 | | * |
1451 | | * @param pitch bytes per row in the source image. Normally this should be |
1452 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded. |
1453 | | * (Setting this parameter to 0 is the equivalent of setting it to |
1454 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this |
1455 | | * parameter to specify the row alignment/padding of the source image, to skip |
1456 | | * rows, or to encode from a specific region of a larger packed-pixel image. |
1457 | | * |
1458 | | * @param height height (in pixels) of the source image |
1459 | | * |
1460 | | * @param pixelFormat pixel format of the source image (see @ref TJPF |
1461 | | * "Pixel formats".) |
1462 | | * |
1463 | | * @param dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes |
1464 | | * (or just a Y plane, if generating a grayscale image) that will receive the |
1465 | | * encoded image. These planes can be contiguous or non-contiguous in memory. |
1466 | | * Use #tj3YUVPlaneSize() to determine the appropriate size for each plane |
1467 | | * based on the image width, height, strides, and level of chrominance |
1468 | | * subsampling (see #TJPARAM_SUBSAMP.) Refer to @ref YUVnotes |
1469 | | * "YUV Image Format Notes" for more details. |
1470 | | * |
1471 | | * @param strides an array of integers, each specifying the number of bytes per |
1472 | | * row in the corresponding plane of the YUV image. Setting the stride for any |
1473 | | * plane to 0 is the same as setting it to the plane width (see @ref YUVnotes |
1474 | | * "YUV Image Format Notes".) If `strides` is NULL, then the strides for all |
1475 | | * planes will be set to their respective plane widths. You can adjust the |
1476 | | * strides in order to add an arbitrary amount of row padding to each plane or |
1477 | | * to encode an RGB or grayscale image into a subregion of a larger planar YUV |
1478 | | * image. |
1479 | | * |
1480 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1481 | | * and #tj3GetErrorCode().) |
1482 | | */ |
1483 | | DLLEXPORT int tj3EncodeYUVPlanes8(tjhandle handle, const unsigned char *srcBuf, |
1484 | | int width, int pitch, int height, |
1485 | | int pixelFormat, unsigned char **dstPlanes, |
1486 | | int *strides); |
1487 | | |
1488 | | |
1489 | | /** |
1490 | | * Retrieve information about a JPEG image without decompressing it, or prime |
1491 | | * the decompressor with quantization and Huffman tables. If a JPEG image is |
1492 | | * passed to this function, then the @ref TJPARAM "parameters" that describe |
1493 | | * the JPEG image will be set when the function returns. |
1494 | | * |
1495 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1496 | | * decompression |
1497 | | * |
1498 | | * @param jpegBuf pointer to a byte buffer containing a JPEG image or an |
1499 | | * "abbreviated table specification" (AKA "tables-only") datastream. Passing a |
1500 | | * tables-only datastream to this function primes the decompressor with |
1501 | | * quantization and Huffman tables that can be used when decompressing |
1502 | | * subsequent "abbreviated image" datastreams. This is useful, for instance, |
1503 | | * when decompressing video streams in which all frames share the same |
1504 | | * quantization and Huffman tables. |
1505 | | * |
1506 | | * @param jpegSize size of the JPEG image or tables-only datastream (in bytes) |
1507 | | * |
1508 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1509 | | * and #tj3GetErrorCode().) |
1510 | | */ |
1511 | | DLLEXPORT int tj3DecompressHeader(tjhandle handle, |
1512 | | const unsigned char *jpegBuf, |
1513 | | size_t jpegSize); |
1514 | | |
1515 | | |
1516 | | /** |
1517 | | * Returns a list of fractional scaling factors that the JPEG decompressor |
1518 | | * supports. |
1519 | | * |
1520 | | * @param numScalingFactors pointer to an integer variable that will receive |
1521 | | * the number of elements in the list |
1522 | | * |
1523 | | * @return a pointer to a list of fractional scaling factors, or NULL if an |
1524 | | * error is encountered (see #tj3GetErrorStr().) |
1525 | | */ |
1526 | | DLLEXPORT tjscalingfactor *tj3GetScalingFactors(int *numScalingFactors); |
1527 | | |
1528 | | |
1529 | | /** |
1530 | | * Set the scaling factor for subsequent lossy decompression operations. |
1531 | | * |
1532 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1533 | | * decompression |
1534 | | * |
1535 | | * @param scalingFactor #tjscalingfactor structure that specifies a fractional |
1536 | | * scaling factor that the decompressor supports (see #tj3GetScalingFactors()), |
1537 | | * or <tt>#TJUNSCALED</tt> for no scaling. Decompression scaling is a function |
1538 | | * of the IDCT algorithm, so scaling factors are generally limited to multiples |
1539 | | * of 1/8. If the entire JPEG image will be decompressed, then the width and |
1540 | | * height of the scaled destination image can be determined by calling |
1541 | | * #TJSCALED() with the JPEG width and height (see #TJPARAM_JPEGWIDTH and |
1542 | | * #TJPARAM_JPEGHEIGHT) and the specified scaling factor. When decompressing |
1543 | | * into a planar YUV image, an intermediate buffer copy will be performed if |
1544 | | * the width or height of the scaled destination image is not an even multiple |
1545 | | * of the MCU block size (see #tjMCUWidth and #tjMCUHeight.) Note that |
1546 | | * decompression scaling is not available (and the specified scaling factor is |
1547 | | * ignored) when decompressing lossless JPEG images (see #TJPARAM_LOSSLESS), |
1548 | | * since the IDCT algorithm is not used with those images. Note also that |
1549 | | * #TJPARAM_FASTDCT is ignored when decompression scaling is enabled. |
1550 | | * |
1551 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr().) |
1552 | | */ |
1553 | | DLLEXPORT int tj3SetScalingFactor(tjhandle handle, |
1554 | | tjscalingfactor scalingFactor); |
1555 | | |
1556 | | |
1557 | | /** |
1558 | | * Set the cropping region for partially decompressing a lossy JPEG image into |
1559 | | * a packed-pixel image |
1560 | | * |
1561 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1562 | | * decompression |
1563 | | * |
1564 | | * @param croppingRegion #tjregion structure that specifies a subregion of the |
1565 | | * JPEG image to decompress, or <tt>#TJUNCROPPED</tt> for no cropping. The |
1566 | | * left boundary of the cropping region must be evenly divisible by the scaled |
1567 | | * MCU block width (<tt>#TJSCALED(#tjMCUWidth[subsamp], scalingFactor)</tt>, |
1568 | | * where `subsamp` is the level of chrominance subsampling in the JPEG image |
1569 | | * (see #TJPARAM_SUBSAMP) and `scalingFactor` is the decompression scaling |
1570 | | * factor (see #tj3SetScalingFactor().) The cropping region should be |
1571 | | * specified relative to the scaled image dimensions. Unless `croppingRegion` |
1572 | | * is <tt>#TJUNCROPPED</tt>, the JPEG header must be read (see |
1573 | | * #tj3DecompressHeader()) prior to calling this function. |
1574 | | * |
1575 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr().) |
1576 | | */ |
1577 | | DLLEXPORT int tj3SetCroppingRegion(tjhandle handle, tjregion croppingRegion); |
1578 | | |
1579 | | |
1580 | | /** |
1581 | | * Decompress an 8-bit-per-sample JPEG image into an 8-bit-per-sample |
1582 | | * packed-pixel RGB, grayscale, or CMYK image. The @ref TJPARAM "parameters" |
1583 | | * that describe the JPEG image will be set when this function returns. |
1584 | | * |
1585 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1586 | | * decompression |
1587 | | * |
1588 | | * @param jpegBuf pointer to a byte buffer containing the JPEG image to |
1589 | | * decompress |
1590 | | * |
1591 | | * @param jpegSize size of the JPEG image (in bytes) |
1592 | | * |
1593 | | * @param dstBuf pointer to a buffer that will receive the packed-pixel |
1594 | | * decompressed image. This buffer should normally be |
1595 | | * `pitch * destinationHeight` samples in size. However, you can also use this |
1596 | | * parameter to decompress into a specific region of a larger buffer. NOTE: |
1597 | | * If the JPEG image is lossy, then `destinationHeight` is either the scaled |
1598 | | * JPEG height (see #TJSCALED(), #TJPARAM_JPEGHEIGHT, and |
1599 | | * #tj3SetScalingFactor()) or the height of the cropping region (see |
1600 | | * #tj3SetCroppingRegion().) If the JPEG image is lossless, then |
1601 | | * `destinationHeight` is the JPEG height. |
1602 | | * |
1603 | | * @param pitch samples per row in the destination image. Normally this should |
1604 | | * be set to <tt>destinationWidth * #tjPixelSize[pixelFormat]</tt>, if the |
1605 | | * destination image should be unpadded. (Setting this parameter to 0 is the |
1606 | | * equivalent of setting it to |
1607 | | * <tt>destinationWidth * #tjPixelSize[pixelFormat]</tt>.) However, you can |
1608 | | * also use this parameter to specify the row alignment/padding of the |
1609 | | * destination image, to skip rows, or to decompress into a specific region of |
1610 | | * a larger buffer. NOTE: If the JPEG image is lossy, then `destinationWidth` |
1611 | | * is either the scaled JPEG width (see #TJSCALED(), #TJPARAM_JPEGWIDTH, and |
1612 | | * #tj3SetScalingFactor()) or the width of the cropping region (see |
1613 | | * #tj3SetCroppingRegion().) If the JPEG image is lossless, then |
1614 | | * `destinationWidth` is the JPEG width. |
1615 | | * |
1616 | | * @param pixelFormat pixel format of the destination image (see @ref |
1617 | | * TJPF "Pixel formats".) |
1618 | | * |
1619 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1620 | | * and #tj3GetErrorCode().) |
1621 | | */ |
1622 | | DLLEXPORT int tj3Decompress8(tjhandle handle, const unsigned char *jpegBuf, |
1623 | | size_t jpegSize, unsigned char *dstBuf, int pitch, |
1624 | | int pixelFormat); |
1625 | | |
1626 | | /** |
1627 | | * Decompress a 12-bit-per-sample JPEG image into a 12-bit-per-sample |
1628 | | * packed-pixel RGB, grayscale, or CMYK image. |
1629 | | * |
1630 | | * \details \copydetails tj3Decompress8() |
1631 | | */ |
1632 | | DLLEXPORT int tj3Decompress12(tjhandle handle, const unsigned char *jpegBuf, |
1633 | | size_t jpegSize, short *dstBuf, int pitch, |
1634 | | int pixelFormat); |
1635 | | |
1636 | | /** |
1637 | | * Decompress a 16-bit-per-sample lossless JPEG image into a 16-bit-per-sample |
1638 | | * packed-pixel RGB, grayscale, or CMYK image. |
1639 | | * |
1640 | | * \details \copydetails tj3Decompress8() |
1641 | | */ |
1642 | | DLLEXPORT int tj3Decompress16(tjhandle handle, const unsigned char *jpegBuf, |
1643 | | size_t jpegSize, unsigned short *dstBuf, |
1644 | | int pitch, int pixelFormat); |
1645 | | |
1646 | | |
1647 | | /** |
1648 | | * Decompress an 8-bit-per-sample JPEG image into an 8-bit-per-sample unified |
1649 | | * planar YUV image. This function performs JPEG decompression but leaves out |
1650 | | * the color conversion step, so a planar YUV image is generated instead of a |
1651 | | * packed-pixel image. The @ref TJPARAM "parameters" that describe the JPEG |
1652 | | * image will be set when this function returns. |
1653 | | * |
1654 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1655 | | * decompression |
1656 | | * |
1657 | | * @param jpegBuf pointer to a byte buffer containing the JPEG image to |
1658 | | * decompress |
1659 | | * |
1660 | | * @param jpegSize size of the JPEG image (in bytes) |
1661 | | * |
1662 | | * @param dstBuf pointer to a buffer that will receive the unified planar YUV |
1663 | | * decompressed image. Use #tj3YUVBufSize() to determine the appropriate size |
1664 | | * for this buffer based on the scaled JPEG width and height (see #TJSCALED(), |
1665 | | * #TJPARAM_JPEGWIDTH, #TJPARAM_JPEGHEIGHT, and #tj3SetScalingFactor()), row |
1666 | | * alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The |
1667 | | * Y, U (Cb), and V (Cr) image planes will be stored sequentially in the |
1668 | | * buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".) |
1669 | | * |
1670 | | * @param align row alignment (in bytes) of the YUV image (must be a power of |
1671 | | * 2.) Setting this parameter to n will cause each row in each plane of the |
1672 | | * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) |
1673 | | * To generate images suitable for X Video, `align` should be set to 4. |
1674 | | * |
1675 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1676 | | * and #tj3GetErrorCode().) |
1677 | | */ |
1678 | | DLLEXPORT int tj3DecompressToYUV8(tjhandle handle, |
1679 | | const unsigned char *jpegBuf, |
1680 | | size_t jpegSize, |
1681 | | unsigned char *dstBuf, int align); |
1682 | | |
1683 | | |
1684 | | /** |
1685 | | * Decompress an 8-bit-per-sample JPEG image into separate 8-bit-per-sample Y, |
1686 | | * U (Cb), and V (Cr) image planes. This function performs JPEG decompression |
1687 | | * but leaves out the color conversion step, so a planar YUV image is generated |
1688 | | * instead of a packed-pixel image. The @ref TJPARAM "parameters" that |
1689 | | * describe the JPEG image will be set when this function returns. |
1690 | | * |
1691 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1692 | | * decompression |
1693 | | * |
1694 | | * @param jpegBuf pointer to a byte buffer containing the JPEG image to |
1695 | | * decompress |
1696 | | * |
1697 | | * @param jpegSize size of the JPEG image (in bytes) |
1698 | | * |
1699 | | * @param dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes |
1700 | | * (or just a Y plane, if decompressing a grayscale image) that will receive |
1701 | | * the decompressed image. These planes can be contiguous or non-contiguous in |
1702 | | * memory. Use #tj3YUVPlaneSize() to determine the appropriate size for each |
1703 | | * plane based on the scaled JPEG width and height (see #TJSCALED(), |
1704 | | * #TJPARAM_JPEGWIDTH, #TJPARAM_JPEGHEIGHT, and #tj3SetScalingFactor()), |
1705 | | * strides, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) Refer |
1706 | | * to @ref YUVnotes "YUV Image Format Notes" for more details. |
1707 | | * |
1708 | | * @param strides an array of integers, each specifying the number of bytes per |
1709 | | * row in the corresponding plane of the YUV image. Setting the stride for any |
1710 | | * plane to 0 is the same as setting it to the scaled plane width (see |
1711 | | * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the |
1712 | | * strides for all planes will be set to their respective scaled plane widths. |
1713 | | * You can adjust the strides in order to add an arbitrary amount of row |
1714 | | * padding to each plane or to decompress the JPEG image into a subregion of a |
1715 | | * larger planar YUV image. |
1716 | | * |
1717 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1718 | | * and #tj3GetErrorCode().) |
1719 | | */ |
1720 | | DLLEXPORT int tj3DecompressToYUVPlanes8(tjhandle handle, |
1721 | | const unsigned char *jpegBuf, |
1722 | | size_t jpegSize, |
1723 | | unsigned char **dstPlanes, |
1724 | | int *strides); |
1725 | | |
1726 | | |
1727 | | /** |
1728 | | * Decode an 8-bit-per-sample unified planar YUV image into an 8-bit-per-sample |
1729 | | * packed-pixel RGB or grayscale image. This function performs color |
1730 | | * conversion (which is accelerated in the libjpeg-turbo implementation) but |
1731 | | * does not execute any of the other steps in the JPEG decompression process. |
1732 | | * |
1733 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1734 | | * decompression |
1735 | | * |
1736 | | * @param srcBuf pointer to a buffer containing a unified planar YUV source |
1737 | | * image to be decoded. The size of this buffer should match the value |
1738 | | * returned by #tj3YUVBufSize() for the given image width, height, row |
1739 | | * alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The |
1740 | | * Y, U (Cb), and V (Cr) image planes should be stored sequentially in the |
1741 | | * source buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".) |
1742 | | * |
1743 | | * @param align row alignment (in bytes) of the YUV source image (must be a |
1744 | | * power of 2.) Setting this parameter to n indicates that each row in each |
1745 | | * plane of the YUV source image is padded to the nearest multiple of n bytes |
1746 | | * (1 = unpadded.) |
1747 | | * |
1748 | | * @param dstBuf pointer to a buffer that will receive the packed-pixel decoded |
1749 | | * image. This buffer should normally be `pitch * height` bytes in size. |
1750 | | * However, you can also use this parameter to decode into a specific region of |
1751 | | * a larger buffer. |
1752 | | * |
1753 | | * @param width width (in pixels) of the source and destination images |
1754 | | * |
1755 | | * @param pitch bytes per row in the destination image. Normally this should |
1756 | | * be set to <tt>width * #tjPixelSize[pixelFormat]</tt>, if the destination |
1757 | | * image should be unpadded. (Setting this parameter to 0 is the equivalent of |
1758 | | * setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can |
1759 | | * also use this parameter to specify the row alignment/padding of the |
1760 | | * destination image, to skip rows, or to decode into a specific region of a |
1761 | | * larger buffer. |
1762 | | * |
1763 | | * @param height height (in pixels) of the source and destination images |
1764 | | * |
1765 | | * @param pixelFormat pixel format of the destination image (see @ref TJPF |
1766 | | * "Pixel formats".) |
1767 | | * |
1768 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1769 | | * and #tj3GetErrorCode().) |
1770 | | */ |
1771 | | DLLEXPORT int tj3DecodeYUV8(tjhandle handle, const unsigned char *srcBuf, |
1772 | | int align, unsigned char *dstBuf, int width, |
1773 | | int pitch, int height, int pixelFormat); |
1774 | | |
1775 | | |
1776 | | /** |
1777 | | * Decode a set of 8-bit-per-sample Y, U (Cb), and V (Cr) image planes into an |
1778 | | * 8-bit-per-sample packed-pixel RGB or grayscale image. This function |
1779 | | * performs color conversion (which is accelerated in the libjpeg-turbo |
1780 | | * implementation) but does not execute any of the other steps in the JPEG |
1781 | | * decompression process. |
1782 | | * |
1783 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1784 | | * decompression |
1785 | | * |
1786 | | * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes |
1787 | | * (or just a Y plane, if decoding a grayscale image) that contain a YUV image |
1788 | | * to be decoded. These planes can be contiguous or non-contiguous in memory. |
1789 | | * The size of each plane should match the value returned by #tj3YUVPlaneSize() |
1790 | | * for the given image width, height, strides, and level of chrominance |
1791 | | * subsampling (see #TJPARAM_SUBSAMP.) Refer to @ref YUVnotes |
1792 | | * "YUV Image Format Notes" for more details. |
1793 | | * |
1794 | | * @param strides an array of integers, each specifying the number of bytes per |
1795 | | * row in the corresponding plane of the YUV source image. Setting the stride |
1796 | | * for any plane to 0 is the same as setting it to the plane width (see |
1797 | | * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the |
1798 | | * strides for all planes will be set to their respective plane widths. You |
1799 | | * can adjust the strides in order to specify an arbitrary amount of row |
1800 | | * padding in each plane or to decode a subregion of a larger planar YUV image. |
1801 | | * |
1802 | | * @param dstBuf pointer to a buffer that will receive the packed-pixel decoded |
1803 | | * image. This buffer should normally be `pitch * height` bytes in size. |
1804 | | * However, you can also use this parameter to decode into a specific region of |
1805 | | * a larger buffer. |
1806 | | * |
1807 | | * @param width width (in pixels) of the source and destination images |
1808 | | * |
1809 | | * @param pitch bytes per row in the destination image. Normally this should |
1810 | | * be set to <tt>width * #tjPixelSize[pixelFormat]</tt>, if the destination |
1811 | | * image should be unpadded. (Setting this parameter to 0 is the equivalent of |
1812 | | * setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can |
1813 | | * also use this parameter to specify the row alignment/padding of the |
1814 | | * destination image, to skip rows, or to decode into a specific region of a |
1815 | | * larger buffer. |
1816 | | * |
1817 | | * @param height height (in pixels) of the source and destination images |
1818 | | * |
1819 | | * @param pixelFormat pixel format of the destination image (see @ref TJPF |
1820 | | * "Pixel formats".) |
1821 | | * |
1822 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1823 | | * and #tj3GetErrorCode().) |
1824 | | */ |
1825 | | DLLEXPORT int tj3DecodeYUVPlanes8(tjhandle handle, |
1826 | | const unsigned char * const *srcPlanes, |
1827 | | const int *strides, unsigned char *dstBuf, |
1828 | | int width, int pitch, int height, |
1829 | | int pixelFormat); |
1830 | | |
1831 | | |
1832 | | /** |
1833 | | * Losslessly transform a JPEG image into another JPEG image. Lossless |
1834 | | * transforms work by moving the raw DCT coefficients from one JPEG image |
1835 | | * structure to another without altering the values of the coefficients. While |
1836 | | * this is typically faster than decompressing the image, transforming it, and |
1837 | | * re-compressing it, lossless transforms are not free. Each lossless |
1838 | | * transform requires reading and performing entropy decoding on all of the |
1839 | | * coefficients in the source image, regardless of the size of the destination |
1840 | | * image. Thus, this function provides a means of generating multiple |
1841 | | * transformed images from the same source or applying multiple transformations |
1842 | | * simultaneously, in order to eliminate the need to read the source |
1843 | | * coefficients multiple times. |
1844 | | * |
1845 | | * @param handle handle to a TurboJPEG instance that has been initialized for |
1846 | | * lossless transformation |
1847 | | * |
1848 | | * @param jpegBuf pointer to a byte buffer containing the JPEG source image to |
1849 | | * transform |
1850 | | * |
1851 | | * @param jpegSize size of the JPEG source image (in bytes) |
1852 | | * |
1853 | | * @param n the number of transformed JPEG images to generate |
1854 | | * |
1855 | | * @param dstBufs pointer to an array of n byte buffers. `dstBufs[i]` will |
1856 | | * receive a JPEG image that has been transformed using the parameters in |
1857 | | * `transforms[i]`. TurboJPEG has the ability to reallocate the JPEG |
1858 | | * destination buffer to accommodate the size of the transformed JPEG image. |
1859 | | * Thus, you can choose to: |
1860 | | * -# pre-allocate the JPEG destination buffer with an arbitrary size using |
1861 | | * #tj3Alloc() and let TurboJPEG grow the buffer as needed, |
1862 | | * -# set `dstBufs[i]` to NULL to tell TurboJPEG to allocate the buffer for |
1863 | | * you, or |
1864 | | * -# pre-allocate the buffer to a "worst case" size determined by calling |
1865 | | * #tj3JPEGBufSize() with the transformed or cropped width and height. Under |
1866 | | * normal circumstances, this should ensure that the buffer never has to be |
1867 | | * re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.) |
1868 | | * Note, however, that there are some rare cases (such as transforming images |
1869 | | * with a large amount of embedded EXIF or ICC profile data) in which the |
1870 | | * transformed JPEG image will be larger than the worst-case size, and |
1871 | | * #TJPARAM_NOREALLOC cannot be used in those cases. |
1872 | | * . |
1873 | | * If you choose option 1, then `dstSizes[i]` should be set to the size of your |
1874 | | * pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC, |
1875 | | * you should always check `dstBufs[i]` upon return from this function, as it |
1876 | | * may have changed. |
1877 | | * |
1878 | | * @param dstSizes pointer to an array of n size_t variables that will receive |
1879 | | * the actual sizes (in bytes) of each transformed JPEG image. If `dstBufs[i]` |
1880 | | * points to a pre-allocated buffer, then `dstSizes[i]` should be set to the |
1881 | | * size of the buffer. Upon return, `dstSizes[i]` will contain the size of the |
1882 | | * transformed JPEG image (in bytes.) |
1883 | | * |
1884 | | * @param transforms pointer to an array of n #tjtransform structures, each of |
1885 | | * which specifies the transform parameters and/or cropping region for the |
1886 | | * corresponding transformed JPEG image. |
1887 | | * |
1888 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr() |
1889 | | * and #tj3GetErrorCode().) |
1890 | | */ |
1891 | | DLLEXPORT int tj3Transform(tjhandle handle, const unsigned char *jpegBuf, |
1892 | | size_t jpegSize, int n, unsigned char **dstBufs, |
1893 | | size_t *dstSizes, const tjtransform *transforms); |
1894 | | |
1895 | | |
1896 | | /** |
1897 | | * Destroy a TurboJPEG instance. |
1898 | | * |
1899 | | * @param handle handle to a TurboJPEG instance. If the handle is NULL, then |
1900 | | * this function has no effect. |
1901 | | */ |
1902 | | DLLEXPORT void tj3Destroy(tjhandle handle); |
1903 | | |
1904 | | |
1905 | | /** |
1906 | | * Allocate a byte buffer for use with TurboJPEG. You should always use this |
1907 | | * function to allocate the JPEG destination buffer(s) for the compression and |
1908 | | * transform functions unless you are disabling automatic buffer (re)allocation |
1909 | | * (by setting #TJPARAM_NOREALLOC.) |
1910 | | * |
1911 | | * @param bytes the number of bytes to allocate |
1912 | | * |
1913 | | * @return a pointer to a newly-allocated buffer with the specified number of |
1914 | | * bytes. |
1915 | | * |
1916 | | * @see tj3Free() |
1917 | | */ |
1918 | | DLLEXPORT void *tj3Alloc(size_t bytes); |
1919 | | |
1920 | | |
1921 | | /** |
1922 | | * Load an 8-bit-per-sample packed-pixel image from disk into memory. |
1923 | | * |
1924 | | * @param handle handle to a TurboJPEG instance |
1925 | | * |
1926 | | * @param filename name of a file containing a packed-pixel image in Windows |
1927 | | * BMP or PBMPLUS (PPM/PGM) format. Windows BMP files require 8-bit-per-sample |
1928 | | * data precision. If the data precision of the PBMPLUS file does not match |
1929 | | * the target data precision, then upconverting or downconverting will be |
1930 | | * performed. |
1931 | | * |
1932 | | * @param width pointer to an integer variable that will receive the width (in |
1933 | | * pixels) of the packed-pixel image |
1934 | | * |
1935 | | * @param align row alignment (in samples) of the packed-pixel buffer to be |
1936 | | * returned (must be a power of 2.) Setting this parameter to n will cause all |
1937 | | * rows in the buffer to be padded to the nearest multiple of n samples |
1938 | | * (1 = unpadded.) |
1939 | | * |
1940 | | * @param height pointer to an integer variable that will receive the height |
1941 | | * (in pixels) of the packed-pixel image |
1942 | | * |
1943 | | * @param pixelFormat pointer to an integer variable that specifies or will |
1944 | | * receive the pixel format of the packed-pixel buffer. The behavior of this |
1945 | | * function will vary depending on the value of `*pixelFormat` passed to the |
1946 | | * function: |
1947 | | * - @ref TJPF_UNKNOWN : The packed-pixel buffer returned by this function will |
1948 | | * use the most optimal pixel format for the file type, and `*pixelFormat` will |
1949 | | * contain the ID of that pixel format upon successful return from this |
1950 | | * function. |
1951 | | * - @ref TJPF_GRAY : Only PGM files and 8-bit-per-pixel BMP files with a |
1952 | | * grayscale colormap can be loaded. |
1953 | | * - @ref TJPF_CMYK : The RGB or grayscale pixels stored in the file will be |
1954 | | * converted using a quick & dirty algorithm that is suitable only for testing |
1955 | | * purposes. (Proper conversion between CMYK and other formats requires a |
1956 | | * color management system.) |
1957 | | * - Other @ref TJPF "pixel formats" : The packed-pixel buffer will use the |
1958 | | * specified pixel format, and pixel format conversion will be performed if |
1959 | | * necessary. |
1960 | | * |
1961 | | * @return a pointer to a newly-allocated buffer containing the packed-pixel |
1962 | | * image, converted to the chosen pixel format and with the chosen row |
1963 | | * alignment, or NULL if an error occurred (see #tj3GetErrorStr().) This |
1964 | | * buffer should be freed using #tj3Free(). |
1965 | | */ |
1966 | | DLLEXPORT unsigned char *tj3LoadImage8(tjhandle handle, const char *filename, |
1967 | | int *width, int align, int *height, |
1968 | | int *pixelFormat); |
1969 | | |
1970 | | /** |
1971 | | * Load a 12-bit-per-sample packed-pixel image from disk into memory. |
1972 | | * |
1973 | | * \details \copydetails tj3LoadImage8() |
1974 | | */ |
1975 | | DLLEXPORT short *tj3LoadImage12(tjhandle handle, const char *filename, |
1976 | | int *width, int align, int *height, |
1977 | | int *pixelFormat); |
1978 | | |
1979 | | /** |
1980 | | * Load a 16-bit-per-sample packed-pixel image from disk into memory. |
1981 | | * |
1982 | | * \details \copydetails tj3LoadImage8() |
1983 | | */ |
1984 | | DLLEXPORT unsigned short *tj3LoadImage16(tjhandle handle, const char *filename, |
1985 | | int *width, int align, int *height, |
1986 | | int *pixelFormat); |
1987 | | |
1988 | | |
1989 | | /** |
1990 | | * Save an 8-bit-per-sample packed-pixel image from memory to disk. |
1991 | | * |
1992 | | * @param handle handle to a TurboJPEG instance |
1993 | | * |
1994 | | * @param filename name of a file to which to save the packed-pixel image. The |
1995 | | * image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format, depending |
1996 | | * on the file extension. Windows BMP files require 8-bit-per-sample data |
1997 | | * precision. |
1998 | | * |
1999 | | * @param buffer pointer to a buffer containing a packed-pixel RGB, grayscale, |
2000 | | * or CMYK image to be saved |
2001 | | * |
2002 | | * @param width width (in pixels) of the packed-pixel image |
2003 | | * |
2004 | | * @param pitch samples per row in the packed-pixel image. Setting this |
2005 | | * parameter to 0 is the equivalent of setting it to |
2006 | | * <tt>width * #tjPixelSize[pixelFormat]</tt>. |
2007 | | * |
2008 | | * @param height height (in pixels) of the packed-pixel image |
2009 | | * |
2010 | | * @param pixelFormat pixel format of the packed-pixel image (see @ref TJPF |
2011 | | * "Pixel formats".) If this parameter is set to @ref TJPF_GRAY, then the |
2012 | | * image will be stored in PGM or 8-bit-per-pixel (indexed color) BMP format. |
2013 | | * Otherwise, the image will be stored in PPM or 24-bit-per-pixel BMP format. |
2014 | | * If this parameter is set to @ref TJPF_CMYK, then the CMYK pixels will be |
2015 | | * converted to RGB using a quick & dirty algorithm that is suitable only for |
2016 | | * testing purposes. (Proper conversion between CMYK and other formats |
2017 | | * requires a color management system.) |
2018 | | * |
2019 | | * @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr().) |
2020 | | */ |
2021 | | DLLEXPORT int tj3SaveImage8(tjhandle handle, const char *filename, |
2022 | | const unsigned char *buffer, int width, int pitch, |
2023 | | int height, int pixelFormat); |
2024 | | |
2025 | | /** |
2026 | | * Save a 12-bit-per-sample packed-pixel image from memory to disk. |
2027 | | * |
2028 | | * \details \copydetails tj3SaveImage8() |
2029 | | */ |
2030 | | DLLEXPORT int tj3SaveImage12(tjhandle handle, const char *filename, |
2031 | | const short *buffer, int width, int pitch, |
2032 | | int height, int pixelFormat); |
2033 | | |
2034 | | /** |
2035 | | * Save a 16-bit-per-sample packed-pixel image from memory to disk. |
2036 | | * |
2037 | | * \details \copydetails tj3SaveImage8() |
2038 | | */ |
2039 | | DLLEXPORT int tj3SaveImage16(tjhandle handle, const char *filename, |
2040 | | const unsigned short *buffer, int width, |
2041 | | int pitch, int height, int pixelFormat); |
2042 | | |
2043 | | |
2044 | | /** |
2045 | | * Free a byte buffer previously allocated by TurboJPEG. You should always use |
2046 | | * this function to free JPEG destination buffer(s) that were automatically |
2047 | | * (re)allocated by the compression and transform functions or that were |
2048 | | * manually allocated using #tj3Alloc(). |
2049 | | * |
2050 | | * @param buffer address of the buffer to free. If the address is NULL, then |
2051 | | * this function has no effect. |
2052 | | * |
2053 | | * @see tj3Alloc() |
2054 | | */ |
2055 | | DLLEXPORT void tj3Free(void *buffer); |
2056 | | |
2057 | | |
2058 | | /** |
2059 | | * Returns a descriptive error message explaining why the last command failed. |
2060 | | * |
2061 | | * @param handle handle to a TurboJPEG instance, or NULL if the error was |
2062 | | * generated by a global function (but note that retrieving the error message |
2063 | | * for a global function is thread-safe only on platforms that support |
2064 | | * thread-local storage.) |
2065 | | * |
2066 | | * @return a descriptive error message explaining why the last command failed. |
2067 | | */ |
2068 | | DLLEXPORT char *tj3GetErrorStr(tjhandle handle); |
2069 | | |
2070 | | |
2071 | | /** |
2072 | | * Returns a code indicating the severity of the last error. See |
2073 | | * @ref TJERR "Error codes". |
2074 | | * |
2075 | | * @param handle handle to a TurboJPEG instance |
2076 | | * |
2077 | | * @return a code indicating the severity of the last error. See |
2078 | | * @ref TJERR "Error codes". |
2079 | | */ |
2080 | | DLLEXPORT int tj3GetErrorCode(tjhandle handle); |
2081 | | |
2082 | | |
2083 | | /* Backward compatibility functions and macros (nothing to see here) */ |
2084 | | |
2085 | | /* TurboJPEG 1.0+ */ |
2086 | | |
2087 | | #define NUMSUBOPT TJ_NUMSAMP |
2088 | | #define TJ_444 TJSAMP_444 |
2089 | | #define TJ_422 TJSAMP_422 |
2090 | | #define TJ_420 TJSAMP_420 |
2091 | | #define TJ_411 TJSAMP_420 |
2092 | | #define TJ_GRAYSCALE TJSAMP_GRAY |
2093 | | |
2094 | 0 | #define TJ_BGR 1 |
2095 | | #define TJ_BOTTOMUP TJFLAG_BOTTOMUP |
2096 | | #define TJ_FORCEMMX TJFLAG_FORCEMMX |
2097 | | #define TJ_FORCESSE TJFLAG_FORCESSE |
2098 | | #define TJ_FORCESSE2 TJFLAG_FORCESSE2 |
2099 | 0 | #define TJ_ALPHAFIRST 64 |
2100 | | #define TJ_FORCESSE3 TJFLAG_FORCESSE3 |
2101 | | #define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE |
2102 | | |
2103 | | #define TJPAD(width) (((width) + 3) & (~3)) |
2104 | | |
2105 | | DLLEXPORT unsigned long TJBUFSIZE(int width, int height); |
2106 | | |
2107 | | DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width, |
2108 | | int pitch, int height, int pixelSize, |
2109 | | unsigned char *dstBuf, unsigned long *compressedSize, |
2110 | | int jpegSubsamp, int jpegQual, int flags); |
2111 | | |
2112 | | DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf, |
2113 | | unsigned long jpegSize, unsigned char *dstBuf, |
2114 | | int width, int pitch, int height, int pixelSize, |
2115 | | int flags); |
2116 | | |
2117 | | DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf, |
2118 | | unsigned long jpegSize, int *width, |
2119 | | int *height); |
2120 | | |
2121 | | DLLEXPORT int tjDestroy(tjhandle handle); |
2122 | | |
2123 | | DLLEXPORT char *tjGetErrorStr(void); |
2124 | | |
2125 | | DLLEXPORT tjhandle tjInitCompress(void); |
2126 | | |
2127 | | DLLEXPORT tjhandle tjInitDecompress(void); |
2128 | | |
2129 | | /* TurboJPEG 1.1+ */ |
2130 | | |
2131 | 0 | #define TJ_YUV 512 |
2132 | | |
2133 | | DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int jpegSubsamp); |
2134 | | |
2135 | | DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf, |
2136 | | unsigned long jpegSize, int *width, |
2137 | | int *height, int *jpegSubsamp); |
2138 | | |
2139 | | DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf, |
2140 | | unsigned long jpegSize, unsigned char *dstBuf, |
2141 | | int flags); |
2142 | | |
2143 | | DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width, |
2144 | | int pitch, int height, int pixelSize, |
2145 | | unsigned char *dstBuf, int subsamp, int flags); |
2146 | | |
2147 | | /* TurboJPEG 1.2+ */ |
2148 | | |
2149 | 0 | #define TJFLAG_BOTTOMUP 2 |
2150 | 0 | #define TJFLAG_FORCEMMX 8 |
2151 | 0 | #define TJFLAG_FORCESSE 16 |
2152 | 0 | #define TJFLAG_FORCESSE2 32 |
2153 | | #define TJFLAG_FORCESSE3 128 |
2154 | 0 | #define TJFLAG_FASTUPSAMPLE 256 |
2155 | 0 | #define TJFLAG_NOREALLOC 1024 |
2156 | | |
2157 | | DLLEXPORT unsigned char *tjAlloc(int bytes); |
2158 | | |
2159 | | DLLEXPORT unsigned long tjBufSize(int width, int height, int jpegSubsamp); |
2160 | | |
2161 | | DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp); |
2162 | | |
2163 | | DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, |
2164 | | int width, int pitch, int height, int pixelFormat, |
2165 | | unsigned char **jpegBuf, unsigned long *jpegSize, |
2166 | | int jpegSubsamp, int jpegQual, int flags); |
2167 | | |
2168 | | DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf, |
2169 | | unsigned long jpegSize, unsigned char *dstBuf, |
2170 | | int width, int pitch, int height, int pixelFormat, |
2171 | | int flags); |
2172 | | |
2173 | | DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width, |
2174 | | int pitch, int height, int pixelFormat, |
2175 | | unsigned char *dstBuf, int subsamp, int flags); |
2176 | | |
2177 | | DLLEXPORT void tjFree(unsigned char *buffer); |
2178 | | |
2179 | | DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numscalingfactors); |
2180 | | |
2181 | | DLLEXPORT tjhandle tjInitTransform(void); |
2182 | | |
2183 | | DLLEXPORT int tjTransform(tjhandle handle, const unsigned char *jpegBuf, |
2184 | | unsigned long jpegSize, int n, |
2185 | | unsigned char **dstBufs, unsigned long *dstSizes, |
2186 | | tjtransform *transforms, int flags); |
2187 | | |
2188 | | /* TurboJPEG 1.2.1+ */ |
2189 | | |
2190 | 0 | #define TJFLAG_FASTDCT 2048 |
2191 | 0 | #define TJFLAG_ACCURATEDCT 4096 |
2192 | | |
2193 | | /* TurboJPEG 1.4+ */ |
2194 | | |
2195 | | DLLEXPORT unsigned long tjBufSizeYUV2(int width, int align, int height, |
2196 | | int subsamp); |
2197 | | |
2198 | | DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, |
2199 | | int width, int align, int height, int subsamp, |
2200 | | unsigned char **jpegBuf, |
2201 | | unsigned long *jpegSize, int jpegQual, |
2202 | | int flags); |
2203 | | |
2204 | | DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle, |
2205 | | const unsigned char **srcPlanes, |
2206 | | int width, const int *strides, |
2207 | | int height, int subsamp, |
2208 | | unsigned char **jpegBuf, |
2209 | | unsigned long *jpegSize, int jpegQual, |
2210 | | int flags); |
2211 | | |
2212 | | DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, |
2213 | | int align, int subsamp, unsigned char *dstBuf, |
2214 | | int width, int pitch, int height, int pixelFormat, |
2215 | | int flags); |
2216 | | |
2217 | | DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle, |
2218 | | const unsigned char **srcPlanes, |
2219 | | const int *strides, int subsamp, |
2220 | | unsigned char *dstBuf, int width, int pitch, |
2221 | | int height, int pixelFormat, int flags); |
2222 | | |
2223 | | DLLEXPORT int tjDecompressHeader3(tjhandle handle, |
2224 | | const unsigned char *jpegBuf, |
2225 | | unsigned long jpegSize, int *width, |
2226 | | int *height, int *jpegSubsamp, |
2227 | | int *jpegColorspace); |
2228 | | |
2229 | | DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, |
2230 | | unsigned long jpegSize, unsigned char *dstBuf, |
2231 | | int width, int align, int height, int flags); |
2232 | | |
2233 | | DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle, |
2234 | | const unsigned char *jpegBuf, |
2235 | | unsigned long jpegSize, |
2236 | | unsigned char **dstPlanes, int width, |
2237 | | int *strides, int height, int flags); |
2238 | | |
2239 | | DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, |
2240 | | int width, int pitch, int height, int pixelFormat, |
2241 | | unsigned char *dstBuf, int align, int subsamp, |
2242 | | int flags); |
2243 | | |
2244 | | DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf, |
2245 | | int width, int pitch, int height, |
2246 | | int pixelFormat, unsigned char **dstPlanes, |
2247 | | int *strides, int subsamp, int flags); |
2248 | | |
2249 | | DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp); |
2250 | | |
2251 | | DLLEXPORT unsigned long tjPlaneSizeYUV(int componentID, int width, int stride, |
2252 | | int height, int subsamp); |
2253 | | |
2254 | | DLLEXPORT int tjPlaneWidth(int componentID, int width, int subsamp); |
2255 | | |
2256 | | /* TurboJPEG 2.0+ */ |
2257 | | |
2258 | 0 | #define TJFLAG_STOPONWARNING 8192 |
2259 | 0 | #define TJFLAG_PROGRESSIVE 16384 |
2260 | | |
2261 | | DLLEXPORT int tjGetErrorCode(tjhandle handle); |
2262 | | |
2263 | | DLLEXPORT char *tjGetErrorStr2(tjhandle handle); |
2264 | | |
2265 | | DLLEXPORT unsigned char *tjLoadImage(const char *filename, int *width, |
2266 | | int align, int *height, int *pixelFormat, |
2267 | | int flags); |
2268 | | |
2269 | | DLLEXPORT int tjSaveImage(const char *filename, unsigned char *buffer, |
2270 | | int width, int pitch, int height, int pixelFormat, |
2271 | | int flags); |
2272 | | |
2273 | | /* TurboJPEG 2.1+ */ |
2274 | | |
2275 | 0 | #define TJFLAG_LIMITSCANS 32768 |
2276 | | |
2277 | | /** |
2278 | | * @} |
2279 | | */ |
2280 | | |
2281 | | #ifdef __cplusplus |
2282 | | } |
2283 | | #endif |
2284 | | |
2285 | | #endif |