4 * This file was part of the Independent JPEG Group's software:
5 * Copyright (C) 1991-1997, Thomas G. Lane.
6 * Modified 1997-2009 by Guido Vollbeding.
7 * libjpeg-turbo Modifications:
8 * Copyright (C) 2015-2016, 2019, 2021, D. R. Commander.
9 * Copyright (C) 2015, Google, Inc.
10 * Copyright (C) 2021, Alex Richardson.
11 * For conditions of distribution and use, see the accompanying README.ijg
14 * This file provides common declarations for the various JPEG modules.
15 * These declarations are considered internal to the JPEG library; most
16 * applications using the library shouldn't need to include this file.
20 /* Declarations for both compression & decompression */
22 typedef enum { /* Operating modes for buffer controllers */
23 JBUF_PASS_THRU
, /* Plain stripwise operation */
24 /* Remaining modes require a full-image buffer to have been created */
25 JBUF_SAVE_SOURCE
, /* Run source subobject only, save output */
26 JBUF_CRANK_DEST
, /* Run dest subobject only, using saved data */
27 JBUF_SAVE_AND_PASS
/* Run both subobjects, save output */
30 /* Values of global_state field (jdapi.c has some dependencies on ordering!) */
31 #define CSTATE_START 100 /* after create_compress */
32 #define CSTATE_SCANNING 101 /* start_compress done, write_scanlines OK */
33 #define CSTATE_RAW_OK 102 /* start_compress done, write_raw_data OK */
34 #define CSTATE_WRCOEFS 103 /* jpeg_write_coefficients done */
35 #define DSTATE_START 200 /* after create_decompress */
36 #define DSTATE_INHEADER 201 /* reading header markers, no SOS yet */
37 #define DSTATE_READY 202 /* found SOS, ready for start_decompress */
38 #define DSTATE_PRELOAD 203 /* reading multiscan file in start_decompress*/
39 #define DSTATE_PRESCAN 204 /* performing dummy pass for 2-pass quant */
40 #define DSTATE_SCANNING 205 /* start_decompress done, read_scanlines OK */
41 #define DSTATE_RAW_OK 206 /* start_decompress done, read_raw_data OK */
42 #define DSTATE_BUFIMAGE 207 /* expecting jpeg_start_output */
43 #define DSTATE_BUFPOST 208 /* looking for SOS/EOI in jpeg_finish_output */
44 #define DSTATE_RDCOEFS 209 /* reading file in jpeg_read_coefficients */
45 #define DSTATE_STOPPING 210 /* looking for EOI in jpeg_finish_decompress */
48 /* JLONG must hold at least signed 32-bit values. */
51 /* JUINTPTR must hold pointer values. */
52 #ifdef __UINTPTR_TYPE__
54 * __UINTPTR_TYPE__ is GNU-specific and available in GCC 4.6+ and Clang 3.0+.
55 * Fortunately, that is sufficient to support the few architectures for which
56 * sizeof(void *) != sizeof(size_t). The only other options would require C99
57 * or Clang-specific builtins.
59 typedef __UINTPTR_TYPE__ JUINTPTR
;
61 typedef size_t JUINTPTR
;
65 * Left shift macro that handles a negative operand without causing any
69 #define LEFT_SHIFT(a, b) ((JLONG)((unsigned long)(a) << (b)))
72 /* Declarations for compression modules */
74 /* Master control module */
75 struct jpeg_comp_master
{
76 void (*prepare_for_pass
) (j_compress_ptr cinfo
);
77 void (*pass_startup
) (j_compress_ptr cinfo
);
78 void (*finish_pass
) (j_compress_ptr cinfo
);
80 /* State variables made visible to other modules */
81 boolean call_pass_startup
; /* True if pass_startup must be called */
82 boolean is_last_pass
; /* True during last pass */
85 /* Main buffer control (downsampled-data buffer) */
86 struct jpeg_c_main_controller
{
87 void (*start_pass
) (j_compress_ptr cinfo
, J_BUF_MODE pass_mode
);
88 void (*process_data
) (j_compress_ptr cinfo
, JSAMPARRAY input_buf
,
89 JDIMENSION
*in_row_ctr
, JDIMENSION in_rows_avail
);
92 /* Compression preprocessing (downsampling input buffer control) */
93 struct jpeg_c_prep_controller
{
94 void (*start_pass
) (j_compress_ptr cinfo
, J_BUF_MODE pass_mode
);
95 void (*pre_process_data
) (j_compress_ptr cinfo
, JSAMPARRAY input_buf
,
96 JDIMENSION
*in_row_ctr
, JDIMENSION in_rows_avail
,
97 JSAMPIMAGE output_buf
,
98 JDIMENSION
*out_row_group_ctr
,
99 JDIMENSION out_row_groups_avail
);
102 /* Coefficient buffer control */
103 struct jpeg_c_coef_controller
{
104 void (*start_pass
) (j_compress_ptr cinfo
, J_BUF_MODE pass_mode
);
105 boolean (*compress_data
) (j_compress_ptr cinfo
, JSAMPIMAGE input_buf
);
108 /* Colorspace conversion */
109 struct jpeg_color_converter
{
110 void (*start_pass
) (j_compress_ptr cinfo
);
111 void (*color_convert
) (j_compress_ptr cinfo
, JSAMPARRAY input_buf
,
112 JSAMPIMAGE output_buf
, JDIMENSION output_row
,
117 struct jpeg_downsampler
{
118 void (*start_pass
) (j_compress_ptr cinfo
);
119 void (*downsample
) (j_compress_ptr cinfo
, JSAMPIMAGE input_buf
,
120 JDIMENSION in_row_index
, JSAMPIMAGE output_buf
,
121 JDIMENSION out_row_group_index
);
123 boolean need_context_rows
; /* TRUE if need rows above & below */
126 /* Forward DCT (also controls coefficient quantization) */
127 struct jpeg_forward_dct
{
128 void (*start_pass
) (j_compress_ptr cinfo
);
129 /* perhaps this should be an array??? */
130 void (*forward_DCT
) (j_compress_ptr cinfo
, jpeg_component_info
*compptr
,
131 JSAMPARRAY sample_data
, JBLOCKROW coef_blocks
,
132 JDIMENSION start_row
, JDIMENSION start_col
,
133 JDIMENSION num_blocks
);
136 /* Entropy encoding */
137 struct jpeg_entropy_encoder
{
138 void (*start_pass
) (j_compress_ptr cinfo
, boolean gather_statistics
);
139 boolean (*encode_mcu
) (j_compress_ptr cinfo
, JBLOCKROW
*MCU_data
);
140 void (*finish_pass
) (j_compress_ptr cinfo
);
144 struct jpeg_marker_writer
{
145 void (*write_file_header
) (j_compress_ptr cinfo
);
146 void (*write_frame_header
) (j_compress_ptr cinfo
);
147 void (*write_scan_header
) (j_compress_ptr cinfo
);
148 void (*write_file_trailer
) (j_compress_ptr cinfo
);
149 void (*write_tables_only
) (j_compress_ptr cinfo
);
150 /* These routines are exported to allow insertion of extra markers */
151 /* Probably only COM and APPn markers should be written this way */
152 void (*write_marker_header
) (j_compress_ptr cinfo
, int marker
,
153 unsigned int datalen
);
154 void (*write_marker_byte
) (j_compress_ptr cinfo
, int val
);
158 /* Declarations for decompression modules */
160 /* Master control module */
161 struct jpeg_decomp_master
{
162 void (*prepare_for_output_pass
) (j_decompress_ptr cinfo
);
163 void (*finish_output_pass
) (j_decompress_ptr cinfo
);
165 /* State variables made visible to other modules */
166 boolean is_dummy_pass
; /* True during 1st pass for 2-pass quant */
168 /* Partial decompression variables */
169 JDIMENSION first_iMCU_col
;
170 JDIMENSION last_iMCU_col
;
171 JDIMENSION first_MCU_col
[MAX_COMPONENTS
];
172 JDIMENSION last_MCU_col
[MAX_COMPONENTS
];
173 boolean jinit_upsampler_no_alloc
;
175 /* Last iMCU row that was successfully decoded */
176 JDIMENSION last_good_iMCU_row
;
179 /* Input control module */
180 struct jpeg_input_controller
{
181 int (*consume_input
) (j_decompress_ptr cinfo
);
182 void (*reset_input_controller
) (j_decompress_ptr cinfo
);
183 void (*start_input_pass
) (j_decompress_ptr cinfo
);
184 void (*finish_input_pass
) (j_decompress_ptr cinfo
);
186 /* State variables made visible to other modules */
187 boolean has_multiple_scans
; /* True if file has multiple scans */
188 boolean eoi_reached
; /* True when EOI has been consumed */
191 /* Main buffer control (downsampled-data buffer) */
192 struct jpeg_d_main_controller
{
193 void (*start_pass
) (j_decompress_ptr cinfo
, J_BUF_MODE pass_mode
);
194 void (*process_data
) (j_decompress_ptr cinfo
, JSAMPARRAY output_buf
,
195 JDIMENSION
*out_row_ctr
, JDIMENSION out_rows_avail
);
198 /* Coefficient buffer control */
199 struct jpeg_d_coef_controller
{
200 void (*start_input_pass
) (j_decompress_ptr cinfo
);
201 int (*consume_data
) (j_decompress_ptr cinfo
);
202 void (*start_output_pass
) (j_decompress_ptr cinfo
);
203 int (*decompress_data
) (j_decompress_ptr cinfo
, JSAMPIMAGE output_buf
);
204 /* Pointer to array of coefficient virtual arrays, or NULL if none */
205 jvirt_barray_ptr
*coef_arrays
;
208 /* Decompression postprocessing (color quantization buffer control) */
209 struct jpeg_d_post_controller
{
210 void (*start_pass
) (j_decompress_ptr cinfo
, J_BUF_MODE pass_mode
);
211 void (*post_process_data
) (j_decompress_ptr cinfo
, JSAMPIMAGE input_buf
,
212 JDIMENSION
*in_row_group_ctr
,
213 JDIMENSION in_row_groups_avail
,
214 JSAMPARRAY output_buf
, JDIMENSION
*out_row_ctr
,
215 JDIMENSION out_rows_avail
);
218 /* Marker reading & parsing */
219 struct jpeg_marker_reader
{
220 void (*reset_marker_reader
) (j_decompress_ptr cinfo
);
221 /* Read markers until SOS or EOI.
222 * Returns same codes as are defined for jpeg_consume_input:
223 * JPEG_SUSPENDED, JPEG_REACHED_SOS, or JPEG_REACHED_EOI.
225 int (*read_markers
) (j_decompress_ptr cinfo
);
226 /* Read a restart marker --- exported for use by entropy decoder only */
227 jpeg_marker_parser_method read_restart_marker
;
229 /* State of marker reader --- nominally internal, but applications
230 * supplying COM or APPn handlers might like to know the state.
232 boolean saw_SOI
; /* found SOI? */
233 boolean saw_SOF
; /* found SOF? */
234 int next_restart_num
; /* next restart number expected (0-7) */
235 unsigned int discarded_bytes
; /* # of bytes skipped looking for a marker */
238 /* Entropy decoding */
239 struct jpeg_entropy_decoder
{
240 void (*start_pass
) (j_decompress_ptr cinfo
);
241 boolean (*decode_mcu
) (j_decompress_ptr cinfo
, JBLOCKROW
*MCU_data
);
243 /* This is here to share code between baseline and progressive decoders; */
244 /* other modules probably should not use it */
245 boolean insufficient_data
; /* set TRUE after emitting warning */
248 /* Inverse DCT (also performs dequantization) */
249 typedef void (*inverse_DCT_method_ptr
) (j_decompress_ptr cinfo
,
250 jpeg_component_info
*compptr
,
252 JSAMPARRAY output_buf
,
253 JDIMENSION output_col
);
255 struct jpeg_inverse_dct
{
256 void (*start_pass
) (j_decompress_ptr cinfo
);
257 /* It is useful to allow each component to have a separate IDCT method. */
258 inverse_DCT_method_ptr inverse_DCT
[MAX_COMPONENTS
];
261 /* Upsampling (note that upsampler must also call color converter) */
262 struct jpeg_upsampler
{
263 void (*start_pass
) (j_decompress_ptr cinfo
);
264 void (*upsample
) (j_decompress_ptr cinfo
, JSAMPIMAGE input_buf
,
265 JDIMENSION
*in_row_group_ctr
,
266 JDIMENSION in_row_groups_avail
, JSAMPARRAY output_buf
,
267 JDIMENSION
*out_row_ctr
, JDIMENSION out_rows_avail
);
269 boolean need_context_rows
; /* TRUE if need rows above & below */
272 /* Colorspace conversion */
273 struct jpeg_color_deconverter
{
274 void (*start_pass
) (j_decompress_ptr cinfo
);
275 void (*color_convert
) (j_decompress_ptr cinfo
, JSAMPIMAGE input_buf
,
276 JDIMENSION input_row
, JSAMPARRAY output_buf
,
280 /* Color quantization or color precision reduction */
281 struct jpeg_color_quantizer
{
282 void (*start_pass
) (j_decompress_ptr cinfo
, boolean is_pre_scan
);
283 void (*color_quantize
) (j_decompress_ptr cinfo
, JSAMPARRAY input_buf
,
284 JSAMPARRAY output_buf
, int num_rows
);
285 void (*finish_pass
) (j_decompress_ptr cinfo
);
286 void (*new_color_map
) (j_decompress_ptr cinfo
);
290 /* Miscellaneous useful macros */
293 #define MAX(a, b) ((a) > (b) ? (a) : (b))
295 #define MIN(a, b) ((a) < (b) ? (a) : (b))
298 /* We assume that right shift corresponds to signed division by 2 with
299 * rounding towards minus infinity. This is correct for typical "arithmetic
300 * shift" instructions that shift in copies of the sign bit. But some
301 * C compilers implement >> with an unsigned shift. For these machines you
302 * must define RIGHT_SHIFT_IS_UNSIGNED.
303 * RIGHT_SHIFT provides a proper signed right shift of a JLONG quantity.
304 * It is only applied with constant shift counts. SHIFT_TEMPS must be
305 * included in the variables of any routine using RIGHT_SHIFT.
308 #ifdef RIGHT_SHIFT_IS_UNSIGNED
309 #define SHIFT_TEMPS JLONG shift_temp;
310 #define RIGHT_SHIFT(x, shft) \
311 ((shift_temp = (x)) < 0 ? \
312 (shift_temp >> (shft)) | ((~((JLONG)0)) << (32 - (shft))) : \
313 (shift_temp >> (shft)))
316 #define RIGHT_SHIFT(x, shft) ((x) >> (shft))
320 /* Compression module initialization routines */
321 EXTERN(void) jinit_compress_master(j_compress_ptr cinfo
);
322 EXTERN(void) jinit_c_master_control(j_compress_ptr cinfo
,
323 boolean transcode_only
);
324 EXTERN(void) jinit_c_main_controller(j_compress_ptr cinfo
,
325 boolean need_full_buffer
);
326 EXTERN(void) jinit_c_prep_controller(j_compress_ptr cinfo
,
327 boolean need_full_buffer
);
328 EXTERN(void) jinit_c_coef_controller(j_compress_ptr cinfo
,
329 boolean need_full_buffer
);
330 EXTERN(void) jinit_color_converter(j_compress_ptr cinfo
);
331 EXTERN(void) jinit_downsampler(j_compress_ptr cinfo
);
332 EXTERN(void) jinit_forward_dct(j_compress_ptr cinfo
);
333 EXTERN(void) jinit_huff_encoder(j_compress_ptr cinfo
);
334 EXTERN(void) jinit_phuff_encoder(j_compress_ptr cinfo
);
335 EXTERN(void) jinit_arith_encoder(j_compress_ptr cinfo
);
336 EXTERN(void) jinit_marker_writer(j_compress_ptr cinfo
);
337 /* Decompression module initialization routines */
338 EXTERN(void) jinit_master_decompress(j_decompress_ptr cinfo
);
339 EXTERN(void) jinit_d_main_controller(j_decompress_ptr cinfo
,
340 boolean need_full_buffer
);
341 EXTERN(void) jinit_d_coef_controller(j_decompress_ptr cinfo
,
342 boolean need_full_buffer
);
343 EXTERN(void) jinit_d_post_controller(j_decompress_ptr cinfo
,
344 boolean need_full_buffer
);
345 EXTERN(void) jinit_input_controller(j_decompress_ptr cinfo
);
346 EXTERN(void) jinit_marker_reader(j_decompress_ptr cinfo
);
347 EXTERN(void) jinit_huff_decoder(j_decompress_ptr cinfo
);
348 EXTERN(void) jinit_phuff_decoder(j_decompress_ptr cinfo
);
349 EXTERN(void) jinit_arith_decoder(j_decompress_ptr cinfo
);
350 EXTERN(void) jinit_inverse_dct(j_decompress_ptr cinfo
);
351 EXTERN(void) jinit_upsampler(j_decompress_ptr cinfo
);
352 EXTERN(void) jinit_color_deconverter(j_decompress_ptr cinfo
);
353 EXTERN(void) jinit_1pass_quantizer(j_decompress_ptr cinfo
);
354 EXTERN(void) jinit_2pass_quantizer(j_decompress_ptr cinfo
);
355 EXTERN(void) jinit_merged_upsampler(j_decompress_ptr cinfo
);
356 /* Memory manager initialization */
357 EXTERN(void) jinit_memory_mgr(j_common_ptr cinfo
);
359 /* Utility routines in jutils.c */
360 EXTERN(long) jdiv_round_up(long a
, long b
);
361 EXTERN(long) jround_up(long a
, long b
);
362 EXTERN(void) jcopy_sample_rows(JSAMPARRAY input_array
, int source_row
,
363 JSAMPARRAY output_array
, int dest_row
,
364 int num_rows
, JDIMENSION num_cols
);
365 EXTERN(void) jcopy_block_row(JBLOCKROW input_row
, JBLOCKROW output_row
,
366 JDIMENSION num_blocks
);
367 EXTERN(void) jzero_far(void *target
, size_t bytestozero
);
368 /* Constant tables in jutils.c */
369 #if 0 /* This table is not actually needed in v6a */
370 extern const int jpeg_zigzag_order
[]; /* natural coef order to zigzag order */
372 extern const int jpeg_natural_order
[]; /* zigzag coef order to natural order */
374 /* Arithmetic coding probability estimation tables in jaricom.c */
375 extern const JLONG jpeg_aritab
[];