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