Alien-FreeImage

 view release on metacpan or  search on metacpan

src/Source/LibJPEG/libjpeg.txt  view on Meta::CPAN

6. jpeg_finish_compress(...);

After all the image data has been written, call jpeg_finish_compress() to
complete the compression cycle.  This step is ESSENTIAL to ensure that the
last bufferload of data is written to the data destination.
jpeg_finish_compress() also releases working memory associated with the JPEG
object.

Typical code:

	jpeg_finish_compress(&cinfo);

If using the stdio destination manager, don't forget to close the output
stdio stream (if necessary) afterwards.

If you have requested a multi-pass operating mode, such as Huffman code
optimization, jpeg_finish_compress() will perform the additional passes using
data buffered by the first pass.  In this case jpeg_finish_compress() may take
quite a while to complete.  With the default compression parameters, this will
not happen.

It is an error to call jpeg_finish_compress() before writing the necessary
total number of scanlines.  If you wish to abort compression, call
jpeg_abort() as discussed below.

After completing a compression cycle, you may dispose of the JPEG object
as discussed next, or you may use it to compress another image.  In that case
return to step 2, 3, or 4 as appropriate.  If you do not change the
destination manager, the new datastream will be written to the same target.
If you do not change any JPEG parameters, the new datastream will be written
with the same parameters as before.  Note that you can change the input image
dimensions freely between cycles, but if you change the input colorspace, you
should call jpeg_set_defaults() to adjust for the new colorspace; and then
you'll need to repeat all of step 3.


7. Release the JPEG compression object.

When you are done with a JPEG compression object, destroy it by calling
jpeg_destroy_compress().  This will free all subsidiary memory (regardless of
the previous state of the object).  Or you can call jpeg_destroy(), which
works for either compression or decompression objects --- this may be more
convenient if you are sharing code between compression and decompression
cases.  (Actually, these routines are equivalent except for the declared type
of the passed pointer.  To avoid gripes from ANSI C compilers, jpeg_destroy()
should be passed a j_common_ptr.)

If you allocated the jpeg_compress_struct structure from malloc(), freeing
it is your responsibility --- jpeg_destroy() won't.  Ditto for the error
handler structure.

Typical code:

	jpeg_destroy_compress(&cinfo);


8. Aborting.

If you decide to abort a compression cycle before finishing, you can clean up
in either of two ways:

* If you don't need the JPEG object any more, just call
  jpeg_destroy_compress() or jpeg_destroy() to release memory.  This is
  legitimate at any point after calling jpeg_create_compress() --- in fact,
  it's safe even if jpeg_create_compress() fails.

* If you want to re-use the JPEG object, call jpeg_abort_compress(), or call
  jpeg_abort() which works on both compression and decompression objects.
  This will return the object to an idle state, releasing any working memory.
  jpeg_abort() is allowed at any time after successful object creation.

Note that cleaning up the data destination, if required, is your
responsibility; neither of these routines will call term_destination().
(See "Compressed data handling", below, for more about that.)

jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG
object that has reported an error by calling error_exit (see "Error handling"
for more info).  The internal state of such an object is likely to be out of
whack.  Either of these two routines will return the object to a known state.


Decompression details
---------------------

Here we revisit the JPEG decompression outline given in the overview.

1. Allocate and initialize a JPEG decompression object.

This is just like initialization for compression, as discussed above,
except that the object is a "struct jpeg_decompress_struct" and you
call jpeg_create_decompress().  Error handling is exactly the same.

Typical code:

	struct jpeg_decompress_struct cinfo;
	struct jpeg_error_mgr jerr;
	...
	cinfo.err = jpeg_std_error(&jerr);
	jpeg_create_decompress(&cinfo);

(Both here and in the IJG code, we usually use variable name "cinfo" for
both compression and decompression objects.)


2. Specify the source of the compressed data (eg, a file).

As previously mentioned, the JPEG library reads compressed data from a "data
source" module.  The library includes one data source module which knows how
to read from a stdio stream.  You can use your own source module if you want
to do something else, as discussed later.

If you use the standard source module, you must open the source stdio stream
beforehand.  Typical code for this step looks like:

	FILE * infile;
	...
	if ((infile = fopen(filename, "rb")) == NULL) {
	    fprintf(stderr, "can't open %s\n", filename);
	    exit(1);

src/Source/LibJPEG/libjpeg.txt  view on Meta::CPAN

routines will cause a message to be printed on stderr, followed by exit().
You can supply your own error handling routines to override this behavior
and to control the treatment of nonfatal warnings and trace/debug messages.
The file example.c illustrates the most common case, which is to have the
application regain control after an error rather than exiting.

The JPEG library never writes any message directly; it always goes through
the error handling routines.  Three classes of messages are recognized:
  * Fatal errors: the library cannot continue.
  * Warnings: the library can continue, but the data is corrupt, and a
    damaged output image is likely to result.
  * Trace/informational messages.  These come with a trace level indicating
    the importance of the message; you can control the verbosity of the
    program by adjusting the maximum trace level that will be displayed.

You may, if you wish, simply replace the entire JPEG error handling module
(jerror.c) with your own code.  However, you can avoid code duplication by
only replacing some of the routines depending on the behavior you need.
This is accomplished by calling jpeg_std_error() as usual, but then overriding
some of the method pointers in the jpeg_error_mgr struct, as illustrated by
example.c.

All of the error handling routines will receive a pointer to the JPEG object
(a j_common_ptr which points to either a jpeg_compress_struct or a
jpeg_decompress_struct; if you need to tell which, test the is_decompressor
field).  This struct includes a pointer to the error manager struct in its
"err" field.  Frequently, custom error handler routines will need to access
additional data which is not known to the JPEG library or the standard error
handler.  The most convenient way to do this is to embed either the JPEG
object or the jpeg_error_mgr struct in a larger structure that contains
additional fields; then casting the passed pointer provides access to the
additional fields.  Again, see example.c for one way to do it.  (Beginning
with IJG version 6b, there is also a void pointer "client_data" in each
JPEG object, which the application can also use to find related data.
The library does not touch client_data at all.)

The individual methods that you might wish to override are:

error_exit (j_common_ptr cinfo)
	Receives control for a fatal error.  Information sufficient to
	generate the error message has been stored in cinfo->err; call
	output_message to display it.  Control must NOT return to the caller;
	generally this routine will exit() or longjmp() somewhere.
	Typically you would override this routine to get rid of the exit()
	default behavior.  Note that if you continue processing, you should
	clean up the JPEG object with jpeg_abort() or jpeg_destroy().

output_message (j_common_ptr cinfo)
	Actual output of any JPEG message.  Override this to send messages
	somewhere other than stderr.  Note that this method does not know
	how to generate a message, only where to send it.

format_message (j_common_ptr cinfo, char * buffer)
	Constructs a readable error message string based on the error info
	stored in cinfo->err.  This method is called by output_message.  Few
	applications should need to override this method.  One possible
	reason for doing so is to implement dynamic switching of error message
	language.

emit_message (j_common_ptr cinfo, int msg_level)
	Decide whether or not to emit a warning or trace message; if so,
	calls output_message.  The main reason for overriding this method
	would be to abort on warnings.  msg_level is -1 for warnings,
	0 and up for trace messages.

Only error_exit() and emit_message() are called from the rest of the JPEG
library; the other two are internal to the error handler.

The actual message texts are stored in an array of strings which is pointed to
by the field err->jpeg_message_table.  The messages are numbered from 0 to
err->last_jpeg_message, and it is these code numbers that are used in the
JPEG library code.  You could replace the message texts (for instance, with
messages in French or German) by changing the message table pointer.  See
jerror.h for the default texts.  CAUTION: this table will almost certainly
change or grow from one library version to the next.

It may be useful for an application to add its own message texts that are
handled by the same mechanism.  The error handler supports a second "add-on"
message table for this purpose.  To define an addon table, set the pointer
err->addon_message_table and the message numbers err->first_addon_message and
err->last_addon_message.  If you number the addon messages beginning at 1000
or so, you won't have to worry about conflicts with the library's built-in
messages.  See the sample applications cjpeg/djpeg for an example of using
addon messages (the addon messages are defined in cderror.h).

Actual invocation of the error handler is done via macros defined in jerror.h:
	ERREXITn(...)	for fatal errors
	WARNMSn(...)	for corrupt-data warnings
	TRACEMSn(...)	for trace and informational messages.
These macros store the message code and any additional parameters into the
error handler struct, then invoke the error_exit() or emit_message() method.
The variants of each macro are for varying numbers of additional parameters.
The additional parameters are inserted into the generated message using
standard printf() format codes.

See jerror.h and jerror.c for further details.


Compressed data handling (source and destination managers)
----------------------------------------------------------

The JPEG compression library sends its compressed data to a "destination
manager" module.  The default destination manager just writes the data to a
memory buffer or to a stdio stream, but you can provide your own manager to
do something else.  Similarly, the decompression library calls a "source
manager" to obtain the compressed data; you can provide your own source
manager if you want the data to come from somewhere other than a memory
buffer or a stdio stream.

In both cases, compressed data is processed a bufferload at a time: the
destination or source manager provides a work buffer, and the library invokes
the manager only when the buffer is filled or emptied.  (You could define a
one-character buffer to force the manager to be invoked for each byte, but
that would be rather inefficient.)  The buffer's size and location are
controlled by the manager, not by the library.  For example, the memory
source manager just makes the buffer pointer and length point to the original
data in memory.  In this case the buffer-reload procedure will be invoked
only if the decompressor ran off the end of the datastream, which would
indicate an erroneous datastream.

The work buffer is defined as an array of datatype JOCTET, which is generally

src/Source/LibJPEG/libjpeg.txt  view on Meta::CPAN

number at that time, which implies that you've skipped the output scans
corresponding to the input scans that were completed while you processed the
previous output scan.  In this way, the decoder automatically adapts its
speed to the arriving data, by skipping output scans as necessary to keep up
with the arriving data.

When using this strategy, you'll want to be sure that you perform a final
output pass after receiving all the data; otherwise your last display may not
be full quality across the whole screen.  So the right outer loop logic is
something like this:
	do {
	    absorb any waiting input by calling jpeg_consume_input()
	    final_pass = jpeg_input_complete(&cinfo);
	    adjust output decompression parameters if required
	    jpeg_start_output(&cinfo, cinfo.input_scan_number);
	    ...
	    jpeg_finish_output()
	} while (! final_pass);
rather than quitting as soon as jpeg_input_complete() returns TRUE.  This
arrangement makes it simple to use higher-quality decoding parameters
for the final pass.  But if you don't want to use special parameters for
the final pass, the right loop logic is like this:
	for (;;) {
	    absorb any waiting input by calling jpeg_consume_input()
	    jpeg_start_output(&cinfo, cinfo.input_scan_number);
	    ...
	    jpeg_finish_output()
	    if (jpeg_input_complete(&cinfo) &&
	        cinfo.input_scan_number == cinfo.output_scan_number)
	      break;
	}
In this case you don't need to know in advance whether an output pass is to
be the last one, so it's not necessary to have reached EOF before starting
the final output pass; rather, what you want to test is whether the output
pass was performed in sync with the final input scan.  This form of the loop
will avoid an extra output pass whenever the decoder is able (or nearly able)
to keep up with the incoming data.

When the data transmission speed is high, you might begin a display pass,
then find that much or all of the file has arrived before you can complete
the pass.  (You can detect this by noting the JPEG_REACHED_EOI return code
from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().)
In this situation you may wish to abort the current display pass and start a
new one using the newly arrived information.  To do so, just call
jpeg_finish_output() and then start a new pass with jpeg_start_output().

A variant strategy is to abort and restart display if more than one complete
scan arrives during an output pass; this can be detected by noting
JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number.  This
idea should be employed with caution, however, since the display process
might never get to the bottom of the image before being aborted, resulting
in the lower part of the screen being several passes worse than the upper.
In most cases it's probably best to abort an output pass only if the whole
file has arrived and you want to begin the final output pass immediately.

When receiving data across a communication link, we recommend always using
the current input scan number for the output target scan number; if a
higher-quality final pass is to be done, it should be started (aborting any
incomplete output pass) as soon as the end of file is received.  However,
many other strategies are possible.  For example, the application can examine
the parameters of the current input scan and decide whether to display it or
not.  If the scan contains only chroma data, one might choose not to use it
as the target scan, expecting that the scan will be small and will arrive
quickly.  To skip to the next scan, call jpeg_consume_input() until it
returns JPEG_REACHED_SOS or JPEG_REACHED_EOI.  Or just use the next higher
number as the target scan for jpeg_start_output(); but that method doesn't
let you inspect the next scan's parameters before deciding to display it.


In buffered-image mode, jpeg_start_decompress() never performs input and
thus never suspends.  An application that uses input suspension with
buffered-image mode must be prepared for suspension returns from these
routines:
* jpeg_start_output() performs input only if you request 2-pass quantization
  and the target scan isn't fully read yet.  (This is discussed below.)
* jpeg_read_scanlines(), as always, returns the number of scanlines that it
  was able to produce before suspending.
* jpeg_finish_output() will read any markers following the target scan,
  up to the end of the file or the SOS marker that begins another scan.
  (But it reads no input if jpeg_consume_input() has already reached the
  end of the file or a SOS marker beyond the target output scan.)
* jpeg_finish_decompress() will read until the end of file, and thus can
  suspend if the end hasn't already been reached (as can be tested by
  calling jpeg_input_complete()).
jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress()
all return TRUE if they completed their tasks, FALSE if they had to suspend.
In the event of a FALSE return, the application must load more input data
and repeat the call.  Applications that use non-suspending data sources need
not check the return values of these three routines.


It is possible to change decoding parameters between output passes in the
buffered-image mode.  The decoder library currently supports only very
limited changes of parameters.  ONLY THE FOLLOWING parameter changes are
allowed after jpeg_start_decompress() is called:
* dct_method can be changed before each call to jpeg_start_output().
  For example, one could use a fast DCT method for early scans, changing
  to a higher quality method for the final scan.
* dither_mode can be changed before each call to jpeg_start_output();
  of course this has no impact if not using color quantization.  Typically
  one would use ordered dither for initial passes, then switch to
  Floyd-Steinberg dither for the final pass.  Caution: changing dither mode
  can cause more memory to be allocated by the library.  Although the amount
  of memory involved is not large (a scanline or so), it may cause the
  initial max_memory_to_use specification to be exceeded, which in the worst
  case would result in an out-of-memory failure.
* do_block_smoothing can be changed before each call to jpeg_start_output().
  This setting is relevant only when decoding a progressive JPEG image.
  During the first DC-only scan, block smoothing provides a very "fuzzy" look
  instead of the very "blocky" look seen without it; which is better seems a
  matter of personal taste.  But block smoothing is nearly always a win
  during later stages, especially when decoding a successive-approximation
  image: smoothing helps to hide the slight blockiness that otherwise shows
  up on smooth gradients until the lowest coefficient bits are sent.
* Color quantization mode can be changed under the rules described below.
  You *cannot* change between full-color and quantized output (because that
  would alter the required I/O buffer sizes), but you can change which
  quantization method is used.

When generating color-quantized output, changing quantization method is a
very useful way of switching between high-speed and high-quality display.
The library allows you to change among its three quantization methods:
1. Single-pass quantization to a fixed color cube.
   Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL.
2. Single-pass quantization to an application-supplied colormap.
   Selected by setting cinfo.colormap to point to the colormap (the value of
   two_pass_quantize is ignored); also set cinfo.actual_number_of_colors.

src/Source/LibJPEG/libjpeg.txt  view on Meta::CPAN

Abbreviated datastreams and multiple images
-------------------------------------------

A JPEG compression or decompression object can be reused to process multiple
images.  This saves a small amount of time per image by eliminating the
"create" and "destroy" operations, but that isn't the real purpose of the
feature.  Rather, reuse of an object provides support for abbreviated JPEG
datastreams.  Object reuse can also simplify processing a series of images in
a single input or output file.  This section explains these features.

A JPEG file normally contains several hundred bytes worth of quantization
and Huffman tables.  In a situation where many images will be stored or
transmitted with identical tables, this may represent an annoying overhead.
The JPEG standard therefore permits tables to be omitted.  The standard
defines three classes of JPEG datastreams:
  * "Interchange" datastreams contain an image and all tables needed to decode
     the image.  These are the usual kind of JPEG file.
  * "Abbreviated image" datastreams contain an image, but are missing some or
    all of the tables needed to decode that image.
  * "Abbreviated table specification" (henceforth "tables-only") datastreams
    contain only table specifications.
To decode an abbreviated image, it is necessary to load the missing table(s)
into the decoder beforehand.  This can be accomplished by reading a separate
tables-only file.  A variant scheme uses a series of images in which the first
image is an interchange (complete) datastream, while subsequent ones are
abbreviated and rely on the tables loaded by the first image.  It is assumed
that once the decoder has read a table, it will remember that table until a
new definition for the same table number is encountered.

It is the application designer's responsibility to figure out how to associate
the correct tables with an abbreviated image.  While abbreviated datastreams
can be useful in a closed environment, their use is strongly discouraged in
any situation where data exchange with other applications might be needed.
Caveat designer.

The JPEG library provides support for reading and writing any combination of
tables-only datastreams and abbreviated images.  In both compression and
decompression objects, a quantization or Huffman table will be retained for
the lifetime of the object, unless it is overwritten by a new table definition.


To create abbreviated image datastreams, it is only necessary to tell the
compressor not to emit some or all of the tables it is using.  Each
quantization and Huffman table struct contains a boolean field "sent_table",
which normally is initialized to FALSE.  For each table used by the image, the
header-writing process emits the table and sets sent_table = TRUE unless it is
already TRUE.  (In normal usage, this prevents outputting the same table
definition multiple times, as would otherwise occur because the chroma
components typically share tables.)  Thus, setting this field to TRUE before
calling jpeg_start_compress() will prevent the table from being written at
all.

If you want to create a "pure" abbreviated image file containing no tables,
just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the
tables.  If you want to emit some but not all tables, you'll need to set the
individual sent_table fields directly.

To create an abbreviated image, you must also call jpeg_start_compress()
with a second parameter of FALSE, not TRUE.  Otherwise jpeg_start_compress()
will force all the sent_table fields to FALSE.  (This is a safety feature to
prevent abbreviated images from being created accidentally.)

To create a tables-only file, perform the same parameter setup that you
normally would, but instead of calling jpeg_start_compress() and so on, call
jpeg_write_tables(&cinfo).  This will write an abbreviated datastream
containing only SOI, DQT and/or DHT markers, and EOI.  All the quantization
and Huffman tables that are currently defined in the compression object will
be emitted unless their sent_tables flag is already TRUE, and then all the
sent_tables flags will be set TRUE.

A sure-fire way to create matching tables-only and abbreviated image files
is to proceed as follows:

	create JPEG compression object
	set JPEG parameters
	set destination to tables-only file
	jpeg_write_tables(&cinfo);
	set destination to image file
	jpeg_start_compress(&cinfo, FALSE);
	write data...
	jpeg_finish_compress(&cinfo);

Since the JPEG parameters are not altered between writing the table file and
the abbreviated image file, the same tables are sure to be used.  Of course,
you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence
many times to produce many abbreviated image files matching the table file.

You cannot suppress output of the computed Huffman tables when Huffman
optimization is selected.  (If you could, there'd be no way to decode the
image...)  Generally, you don't want to set optimize_coding = TRUE when
you are trying to produce abbreviated files.

In some cases you might want to compress an image using tables which are
not stored in the application, but are defined in an interchange or
tables-only file readable by the application.  This can be done by setting up
a JPEG decompression object to read the specification file, then copying the
tables into your compression object.  See jpeg_copy_critical_parameters()
for an example of copying quantization tables.


To read abbreviated image files, you simply need to load the proper tables
into the decompression object before trying to read the abbreviated image.
If the proper tables are stored in the application program, you can just
allocate the table structs and fill in their contents directly.  For example,
to load a fixed quantization table into table slot "n":

    if (cinfo.quant_tbl_ptrs[n] == NULL)
      cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo);
    quant_ptr = cinfo.quant_tbl_ptrs[n];	/* quant_ptr is JQUANT_TBL* */
    for (i = 0; i < 64; i++) {
      /* Qtable[] is desired quantization table, in natural array order */
      quant_ptr->quantval[i] = Qtable[i];
    }

Code to load a fixed Huffman table is typically (for AC table "n"):

    if (cinfo.ac_huff_tbl_ptrs[n] == NULL)
      cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo);
    huff_ptr = cinfo.ac_huff_tbl_ptrs[n];	/* huff_ptr is JHUFF_TBL* */
    for (i = 1; i <= 16; i++) {
      /* counts[i] is number of Huffman codes of length i bits, i=1..16 */

src/Source/LibJPEG/libjpeg.txt  view on Meta::CPAN

interleaved MCUs at the right or bottom edges of the image are discarded
during reading and are not stored in the block arrays.  (The size of each
block array can be determined from the width_in_blocks and height_in_blocks
fields of the component's comp_info entry.)  This is also the data format
expected by jpeg_write_coefficients().

When you are done using the virtual arrays, call jpeg_finish_decompress()
to release the array storage and return the decompression object to an idle
state; or just call jpeg_destroy() if you don't need to reuse the object.

If you use a suspending data source, jpeg_read_coefficients() will return
NULL if it is forced to suspend; a non-NULL return value indicates successful
completion.  You need not test for a NULL return value when using a
non-suspending data source.

It is also possible to call jpeg_read_coefficients() to obtain access to the
decoder's coefficient arrays during a normal decode cycle in buffered-image
mode.  This frammish might be useful for progressively displaying an incoming
image and then re-encoding it without loss.  To do this, decode in buffered-
image mode as discussed previously, then call jpeg_read_coefficients() after
the last jpeg_finish_output() call.  The arrays will be available for your use
until you call jpeg_finish_decompress().


To write the contents of a JPEG file as DCT coefficients, you must provide
the DCT coefficients stored in virtual block arrays.  You can either pass
block arrays read from an input JPEG file by jpeg_read_coefficients(), or
allocate virtual arrays from the JPEG compression object and fill them
yourself.  In either case, jpeg_write_coefficients() is substituted for
jpeg_start_compress() and jpeg_write_scanlines().  Thus the sequence is
  * Create compression object
  * Set all compression parameters as necessary
  * Request virtual arrays if needed
  * jpeg_write_coefficients()
  * jpeg_finish_compress()
  * Destroy or re-use compression object
jpeg_write_coefficients() is passed a pointer to an array of virtual block
array descriptors; the number of arrays is equal to cinfo.num_components.

The virtual arrays need only have been requested, not realized, before
jpeg_write_coefficients() is called.  A side-effect of
jpeg_write_coefficients() is to realize any virtual arrays that have been
requested from the compression object's memory manager.  Thus, when obtaining
the virtual arrays from the compression object, you should fill the arrays
after calling jpeg_write_coefficients().  The data is actually written out
when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes
the file header.

When writing raw DCT coefficients, it is crucial that the JPEG quantization
tables and sampling factors match the way the data was encoded, or the
resulting file will be invalid.  For transcoding from an existing JPEG file,
we recommend using jpeg_copy_critical_parameters().  This routine initializes
all the compression parameters to default values (like jpeg_set_defaults()),
then copies the critical information from a source decompression object.
The decompression object should have just been used to read the entire
JPEG input file --- that is, it should be awaiting jpeg_finish_decompress().

jpeg_write_coefficients() marks all tables stored in the compression object
as needing to be written to the output file (thus, it acts like
jpeg_start_compress(cinfo, TRUE)).  This is for safety's sake, to avoid
emitting abbreviated JPEG files by accident.  If you really want to emit an
abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables'
individual sent_table flags, between calling jpeg_write_coefficients() and
jpeg_finish_compress().


Progress monitoring
-------------------

Some applications may need to regain control from the JPEG library every so
often.  The typical use of this feature is to produce a percent-done bar or
other progress display.  (For a simple example, see cjpeg.c or djpeg.c.)
Although you do get control back frequently during the data-transferring pass
(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes
will occur inside jpeg_finish_compress or jpeg_start_decompress; those
routines may take a long time to execute, and you don't get control back
until they are done.

You can define a progress-monitor routine which will be called periodically
by the library.  No guarantees are made about how often this call will occur,
so we don't recommend you use it for mouse tracking or anything like that.
At present, a call will occur once per MCU row, scanline, or sample row
group, whichever unit is convenient for the current processing mode; so the
wider the image, the longer the time between calls.  During the data
transferring pass, only one call occurs per call of jpeg_read_scanlines or
jpeg_write_scanlines, so don't pass a large number of scanlines at once if
you want fine resolution in the progress count.  (If you really need to use
the callback mechanism for time-critical tasks like mouse tracking, you could
insert additional calls inside some of the library's inner loops.)

To establish a progress-monitor callback, create a struct jpeg_progress_mgr,
fill in its progress_monitor field with a pointer to your callback routine,
and set cinfo->progress to point to the struct.  The callback will be called
whenever cinfo->progress is non-NULL.  (This pointer is set to NULL by
jpeg_create_compress or jpeg_create_decompress; the library will not change
it thereafter.  So if you allocate dynamic storage for the progress struct,
make sure it will live as long as the JPEG object does.  Allocating from the
JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.)  You
can use the same callback routine for both compression and decompression.

The jpeg_progress_mgr struct contains four fields which are set by the library:
	long pass_counter;	/* work units completed in this pass */
	long pass_limit;	/* total number of work units in this pass */
	int completed_passes;	/* passes completed so far */
	int total_passes;	/* total number of passes expected */
During any one pass, pass_counter increases from 0 up to (not including)
pass_limit; the step size is usually but not necessarily 1.  The pass_limit
value may change from one pass to another.  The expected total number of
passes is in total_passes, and the number of passes already completed is in
completed_passes.  Thus the fraction of work completed may be estimated as
		completed_passes + (pass_counter/pass_limit)
		--------------------------------------------
				total_passes
ignoring the fact that the passes may not be equal amounts of work.

When decompressing, pass_limit can even change within a pass, because it
depends on the number of scans in the JPEG file, which isn't always known in
advance.  The computed fraction-of-work-done may jump suddenly (if the library
discovers it has overestimated the number of scans) or even decrease (in the
opposite case).  It is not wise to put great faith in the work estimate.