4 * This file was part of the Independent JPEG Group's software:
5 * Copyright (C) 1994-1998, Thomas G. Lane.
6 * libjpeg-turbo Modifications:
7 * Copyright (C) 2016, 2022, D. R. Commander.
8 * For conditions of distribution and use, see the accompanying README.ijg
11 * This file contains application interface code for the decompression half
12 * of the JPEG library. These are the "minimum" API routines that may be
13 * needed in either the normal full-decompression case or the
14 * transcoding-only case.
16 * Most of the routines intended to be called directly by an application
17 * are in this file or in jdapistd.c. But also see jcomapi.c for routines
18 * shared by compression and decompression, and jdtrans.c for the transcoding
22 #define JPEG_INTERNALS
29 * Initialization of a JPEG decompression object.
30 * The error manager must already be set up (in case memory manager fails).
34 jpeg_CreateDecompress(j_decompress_ptr cinfo
, int version
, size_t structsize
)
38 /* Guard against version mismatches between library and caller. */
39 cinfo
->mem
= NULL
; /* so jpeg_destroy knows mem mgr not called */
40 if (version
!= JPEG_LIB_VERSION
)
41 ERREXIT2(cinfo
, JERR_BAD_LIB_VERSION
, JPEG_LIB_VERSION
, version
);
42 if (structsize
!= sizeof(struct jpeg_decompress_struct
))
43 ERREXIT2(cinfo
, JERR_BAD_STRUCT_SIZE
,
44 (int)sizeof(struct jpeg_decompress_struct
), (int)structsize
);
46 /* For debugging purposes, we zero the whole master structure.
47 * But the application has already set the err pointer, and may have set
48 * client_data, so we have to save and restore those fields.
49 * Note: if application hasn't set client_data, tools like Purify may
53 struct jpeg_error_mgr
*err
= cinfo
->err
;
54 void *client_data
= cinfo
->client_data
; /* ignore Purify complaint here */
55 memset(cinfo
, 0, sizeof(struct jpeg_decompress_struct
));
57 cinfo
->client_data
= client_data
;
59 cinfo
->is_decompressor
= TRUE
;
61 /* Initialize a memory manager instance for this object */
62 jinit_memory_mgr((j_common_ptr
)cinfo
);
64 /* Zero out pointers to permanent structures. */
65 cinfo
->progress
= NULL
;
68 for (i
= 0; i
< NUM_QUANT_TBLS
; i
++)
69 cinfo
->quant_tbl_ptrs
[i
] = NULL
;
71 for (i
= 0; i
< NUM_HUFF_TBLS
; i
++) {
72 cinfo
->dc_huff_tbl_ptrs
[i
] = NULL
;
73 cinfo
->ac_huff_tbl_ptrs
[i
] = NULL
;
76 /* Initialize marker processor so application can override methods
77 * for COM, APPn markers before calling jpeg_read_header.
79 cinfo
->marker_list
= NULL
;
80 jinit_marker_reader(cinfo
);
82 /* And initialize the overall input controller. */
83 jinit_input_controller(cinfo
);
86 cinfo
->global_state
= DSTATE_START
;
88 /* The master struct is used to store extension parameters, so we allocate it
91 cinfo
->master
= (struct jpeg_decomp_master
*)
92 (*cinfo
->mem
->alloc_small
) ((j_common_ptr
)cinfo
, JPOOL_PERMANENT
,
93 sizeof(my_decomp_master
));
94 memset(cinfo
->master
, 0, sizeof(my_decomp_master
));
99 * Destruction of a JPEG decompression object
103 jpeg_destroy_decompress(j_decompress_ptr cinfo
)
105 jpeg_destroy((j_common_ptr
)cinfo
); /* use common routine */
110 * Abort processing of a JPEG decompression operation,
111 * but don't destroy the object itself.
115 jpeg_abort_decompress(j_decompress_ptr cinfo
)
117 jpeg_abort((j_common_ptr
)cinfo
); /* use common routine */
122 * Set default decompression parameters.
126 default_decompress_parms(j_decompress_ptr cinfo
)
128 /* Guess the input colorspace, and set output colorspace accordingly. */
129 /* (Wish JPEG committee had provided a real way to specify this...) */
130 /* Note application may override our guesses. */
131 switch (cinfo
->num_components
) {
133 cinfo
->jpeg_color_space
= JCS_GRAYSCALE
;
134 cinfo
->out_color_space
= JCS_GRAYSCALE
;
138 if (cinfo
->saw_JFIF_marker
) {
139 cinfo
->jpeg_color_space
= JCS_YCbCr
; /* JFIF implies YCbCr */
140 } else if (cinfo
->saw_Adobe_marker
) {
141 switch (cinfo
->Adobe_transform
) {
143 cinfo
->jpeg_color_space
= JCS_RGB
;
146 cinfo
->jpeg_color_space
= JCS_YCbCr
;
149 WARNMS1(cinfo
, JWRN_ADOBE_XFORM
, cinfo
->Adobe_transform
);
150 cinfo
->jpeg_color_space
= JCS_YCbCr
; /* assume it's YCbCr */
154 /* Saw no special markers, try to guess from the component IDs */
155 int cid0
= cinfo
->comp_info
[0].component_id
;
156 int cid1
= cinfo
->comp_info
[1].component_id
;
157 int cid2
= cinfo
->comp_info
[2].component_id
;
159 if (cid0
== 1 && cid1
== 2 && cid2
== 3)
160 cinfo
->jpeg_color_space
= JCS_YCbCr
; /* assume JFIF w/out marker */
161 else if (cid0
== 82 && cid1
== 71 && cid2
== 66)
162 cinfo
->jpeg_color_space
= JCS_RGB
; /* ASCII 'R', 'G', 'B' */
164 TRACEMS3(cinfo
, 1, JTRC_UNKNOWN_IDS
, cid0
, cid1
, cid2
);
165 cinfo
->jpeg_color_space
= JCS_YCbCr
; /* assume it's YCbCr */
168 /* Always guess RGB is proper output colorspace. */
169 cinfo
->out_color_space
= JCS_RGB
;
173 if (cinfo
->saw_Adobe_marker
) {
174 switch (cinfo
->Adobe_transform
) {
176 cinfo
->jpeg_color_space
= JCS_CMYK
;
179 cinfo
->jpeg_color_space
= JCS_YCCK
;
182 WARNMS1(cinfo
, JWRN_ADOBE_XFORM
, cinfo
->Adobe_transform
);
183 cinfo
->jpeg_color_space
= JCS_YCCK
; /* assume it's YCCK */
187 /* No special markers, assume straight CMYK. */
188 cinfo
->jpeg_color_space
= JCS_CMYK
;
190 cinfo
->out_color_space
= JCS_CMYK
;
194 cinfo
->jpeg_color_space
= JCS_UNKNOWN
;
195 cinfo
->out_color_space
= JCS_UNKNOWN
;
199 /* Set defaults for other decompression parameters. */
200 cinfo
->scale_num
= 1; /* 1:1 scaling */
201 cinfo
->scale_denom
= 1;
202 cinfo
->output_gamma
= 1.0;
203 cinfo
->buffered_image
= FALSE
;
204 cinfo
->raw_data_out
= FALSE
;
205 cinfo
->dct_method
= JDCT_DEFAULT
;
206 cinfo
->do_fancy_upsampling
= TRUE
;
207 cinfo
->do_block_smoothing
= TRUE
;
208 cinfo
->quantize_colors
= FALSE
;
209 /* We set these in case application only sets quantize_colors. */
210 cinfo
->dither_mode
= JDITHER_FS
;
211 #ifdef QUANT_2PASS_SUPPORTED
212 cinfo
->two_pass_quantize
= TRUE
;
214 cinfo
->two_pass_quantize
= FALSE
;
216 cinfo
->desired_number_of_colors
= 256;
217 cinfo
->colormap
= NULL
;
218 /* Initialize for no mode change in buffered-image mode. */
219 cinfo
->enable_1pass_quant
= FALSE
;
220 cinfo
->enable_external_quant
= FALSE
;
221 cinfo
->enable_2pass_quant
= FALSE
;
226 * Decompression startup: read start of JPEG datastream to see what's there.
227 * Need only initialize JPEG object and supply a data source before calling.
229 * This routine will read as far as the first SOS marker (ie, actual start of
230 * compressed data), and will save all tables and parameters in the JPEG
231 * object. It will also initialize the decompression parameters to default
232 * values, and finally return JPEG_HEADER_OK. On return, the application may
233 * adjust the decompression parameters and then call jpeg_start_decompress.
234 * (Or, if the application only wanted to determine the image parameters,
235 * the data need not be decompressed. In that case, call jpeg_abort or
236 * jpeg_destroy to release any temporary space.)
237 * If an abbreviated (tables only) datastream is presented, the routine will
238 * return JPEG_HEADER_TABLES_ONLY upon reaching EOI. The application may then
239 * re-use the JPEG object to read the abbreviated image datastream(s).
240 * It is unnecessary (but OK) to call jpeg_abort in this case.
241 * The JPEG_SUSPENDED return code only occurs if the data source module
242 * requests suspension of the decompressor. In this case the application
243 * should load more source data and then re-call jpeg_read_header to resume
245 * If a non-suspending data source is used and require_image is TRUE, then the
246 * return code need not be inspected since only JPEG_HEADER_OK is possible.
248 * This routine is now just a front end to jpeg_consume_input, with some
249 * extra error checking.
253 jpeg_read_header(j_decompress_ptr cinfo
, boolean require_image
)
257 if (cinfo
->global_state
!= DSTATE_START
&&
258 cinfo
->global_state
!= DSTATE_INHEADER
)
259 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
261 retcode
= jpeg_consume_input(cinfo
);
264 case JPEG_REACHED_SOS
:
265 retcode
= JPEG_HEADER_OK
;
267 case JPEG_REACHED_EOI
:
268 if (require_image
) /* Complain if application wanted an image */
269 ERREXIT(cinfo
, JERR_NO_IMAGE
);
270 /* Reset to start state; it would be safer to require the application to
271 * call jpeg_abort, but we can't change it now for compatibility reasons.
272 * A side effect is to free any temporary memory (there shouldn't be any).
274 jpeg_abort((j_common_ptr
)cinfo
); /* sets state = DSTATE_START */
275 retcode
= JPEG_HEADER_TABLES_ONLY
;
287 * Consume data in advance of what the decompressor requires.
288 * This can be called at any time once the decompressor object has
289 * been created and a data source has been set up.
291 * This routine is essentially a state machine that handles a couple
292 * of critical state-transition actions, namely initial setup and
293 * transition from header scanning to ready-for-start_decompress.
294 * All the actual input is done via the input controller's consume_input
299 jpeg_consume_input(j_decompress_ptr cinfo
)
301 int retcode
= JPEG_SUSPENDED
;
303 /* NB: every possible DSTATE value should be listed in this switch */
304 switch (cinfo
->global_state
) {
306 /* Start-of-datastream actions: reset appropriate modules */
307 (*cinfo
->inputctl
->reset_input_controller
) (cinfo
);
308 /* Initialize application's data source module */
309 (*cinfo
->src
->init_source
) (cinfo
);
310 cinfo
->global_state
= DSTATE_INHEADER
;
311 FALLTHROUGH
/*FALLTHROUGH*/
312 case DSTATE_INHEADER
:
313 retcode
= (*cinfo
->inputctl
->consume_input
) (cinfo
);
314 if (retcode
== JPEG_REACHED_SOS
) { /* Found SOS, prepare to decompress */
315 /* Set up default parameters based on header data */
316 default_decompress_parms(cinfo
);
317 /* Set global state: ready for start_decompress */
318 cinfo
->global_state
= DSTATE_READY
;
322 /* Can't advance past first SOS until start_decompress is called */
323 retcode
= JPEG_REACHED_SOS
;
327 case DSTATE_SCANNING
:
329 case DSTATE_BUFIMAGE
:
331 case DSTATE_STOPPING
:
332 retcode
= (*cinfo
->inputctl
->consume_input
) (cinfo
);
335 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
342 * Have we finished reading the input file?
346 jpeg_input_complete(j_decompress_ptr cinfo
)
348 /* Check for valid jpeg object */
349 if (cinfo
->global_state
< DSTATE_START
||
350 cinfo
->global_state
> DSTATE_STOPPING
)
351 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
352 return cinfo
->inputctl
->eoi_reached
;
357 * Is there more than one scan?
361 jpeg_has_multiple_scans(j_decompress_ptr cinfo
)
363 /* Only valid after jpeg_read_header completes */
364 if (cinfo
->global_state
< DSTATE_READY
||
365 cinfo
->global_state
> DSTATE_STOPPING
)
366 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
367 return cinfo
->inputctl
->has_multiple_scans
;
372 * Finish JPEG decompression.
374 * This will normally just verify the file trailer and release temp storage.
376 * Returns FALSE if suspended. The return value need be inspected only if
377 * a suspending data source is used.
381 jpeg_finish_decompress(j_decompress_ptr cinfo
)
383 if ((cinfo
->global_state
== DSTATE_SCANNING
||
384 cinfo
->global_state
== DSTATE_RAW_OK
) && !cinfo
->buffered_image
) {
385 /* Terminate final pass of non-buffered mode */
386 if (cinfo
->output_scanline
< cinfo
->output_height
)
387 ERREXIT(cinfo
, JERR_TOO_LITTLE_DATA
);
388 (*cinfo
->master
->finish_output_pass
) (cinfo
);
389 cinfo
->global_state
= DSTATE_STOPPING
;
390 } else if (cinfo
->global_state
== DSTATE_BUFIMAGE
) {
391 /* Finishing after a buffered-image operation */
392 cinfo
->global_state
= DSTATE_STOPPING
;
393 } else if (cinfo
->global_state
!= DSTATE_STOPPING
) {
394 /* STOPPING = repeat call after a suspension, anything else is error */
395 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
398 while (!cinfo
->inputctl
->eoi_reached
) {
399 if ((*cinfo
->inputctl
->consume_input
) (cinfo
) == JPEG_SUSPENDED
)
400 return FALSE
; /* Suspend, come back later */
402 /* Do final cleanup */
403 (*cinfo
->src
->term_source
) (cinfo
);
404 /* We can use jpeg_abort to release memory and reset global_state */
405 jpeg_abort((j_common_ptr
)cinfo
);