Browser Client

Development Platform:

Unix_Linux

libjpeg.doc：Code Content

free_in_buffer must be set to a positive value when TRUE is
returned. A FALSE return should only be used when I/O suspension is
desired (this operating mode is discussed in the next section).
term_destination (j_compress_ptr cinfo)
Terminate destination --- called by jpeg_finish_compress() after all
data has been written. In most applications, this must flush any
data remaining in the buffer. Use either next_output_byte or
free_in_buffer to determine how much data is in the buffer.
term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you
want the destination manager to be cleaned up during an abort, you must do it
yourself.
You will also need code to create a jpeg_destination_mgr struct, fill in its
method pointers, and insert a pointer to the struct into the "dest" field of
the JPEG compression object. This can be done in-line in your setup code if
you like, but it's probably cleaner to provide a separate routine similar to
the jpeg_stdio_dest() routine of the supplied destination manager.
Decompression source managers follow a parallel design, but with some
additional frammishes. The source manager struct contains a pointer and count
defining the next byte to read from the work buffer and the number of bytes
remaining:
const JOCTET * next_input_byte; /* => next byte to read from buffer */
size_t bytes_in_buffer; /* # of bytes remaining in buffer */
The library increments the pointer and decrements the count until the buffer
is emptied. The manager's fill_input_buffer method must reset the pointer and
count. In most applications, the manager must remember the buffer's starting
address and total size in private fields not visible to the library.
A data source manager provides five methods:
init_source (j_decompress_ptr cinfo)
Initialize source. This is called by jpeg_read_header() before any
data is actually read. Unlike init_destination(), it may leave
bytes_in_buffer set to 0 (in which case a fill_input_buffer() call
will occur immediately).
fill_input_buffer (j_decompress_ptr cinfo)
This is called whenever bytes_in_buffer has reached zero and more
data is wanted. In typical applications, it should read fresh data
into the buffer (ignoring the current state of next_input_byte and
bytes_in_buffer), reset the pointer & count to the start of the
buffer, and return TRUE indicating that the buffer has been reloaded.
It is not necessary to fill the buffer entirely, only to obtain at
least one more byte. bytes_in_buffer MUST be set to a positive value
if TRUE is returned. A FALSE return should only be used when I/O
suspension is desired (this mode is discussed in the next section).
skip_input_data (j_decompress_ptr cinfo, long num_bytes)
Skip num_bytes worth of data. The buffer pointer and count should
be advanced over num_bytes input bytes, refilling the buffer as
needed. This is used to skip over a potentially large amount of
uninteresting data (such as an APPn marker). In some applications
it may be possible to optimize away the reading of the skipped data,
but it's not clear that being smart is worth much trouble; large
skips are uncommon. bytes_in_buffer may be zero on return.
A zero or negative skip count should be treated as a no-op.
resync_to_restart (j_decompress_ptr cinfo, int desired)
This routine is called only when the decompressor has failed to find
a restart (RSTn) marker where one is expected. Its mission is to
find a suitable point for resuming decompression. For most
applications, we recommend that you just use the default resync
procedure, jpeg_resync_to_restart(). However, if you are able to back
up in the input data stream, or if you have a-priori knowledge about
the likely location of restart markers, you may be able to do better.
Read the read_restart_marker() and jpeg_resync_to_restart() routines
in jdmarker.c if you think you'd like to implement your own resync
procedure.
term_source (j_decompress_ptr cinfo)
Terminate source --- called by jpeg_finish_decompress() after all
data has been read. Often a no-op.
For both fill_input_buffer() and skip_input_data(), there is no such thing
as an EOF return. If the end of the file has been reached, the routine has
a choice of exiting via ERREXIT() or inserting fake data into the buffer.
In most cases, generating a warning message and inserting a fake EOI marker
is the best course of action --- this will allow the decompressor to output
however much of the image is there. In pathological cases, the decompressor
may swallow the EOI and again demand data ... just keep feeding it fake EOIs.
jdatasrc.c illustrates the recommended error recovery behavior.
term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want
the source manager to be cleaned up during an abort, you must do it yourself.
You will also need code to create a jpeg_source_mgr struct, fill in its method
pointers, and insert a pointer to the struct into the "src" field of the JPEG
decompression object. This can be done in-line in your setup code if you
like, but it's probably cleaner to provide a separate routine similar to the
jpeg_stdio_src() routine of the supplied source manager.
For more information, consult the stdio source and destination managers
in jdatasrc.c and jdatadst.c.
I/O suspension
--------------
Some applications need to use the JPEG library as an incremental memory-to-
memory filter: when the compressed data buffer is filled or emptied, they want
control to return to the outer loop, rather than expecting that the buffer can
be emptied or reloaded within the data source/destination manager subroutine.
The library supports this need by providing an "I/O suspension" mode, which we
describe in this section.
The I/O suspension mode is not a panacea: nothing is guaranteed about the
maximum amount of time spent in any one call to the library, so it will not
eliminate response-time problems in single-threaded applications. If you
need guaranteed response time, we suggest you "bite the bullet" and implement
a real multi-tasking capability.
To use I/O suspension, cooperation is needed between the calling application
and the data source or destination manager; you will always need a custom
source/destination manager. (Please read the previous section if you haven't
already.) The basic idea is that the empty_output_buffer() or
fill_input_buffer() routine is a no-op, merely returning FALSE to indicate
that it has done nothing. Upon seeing this, the JPEG library suspends
operation and returns to its caller. The surrounding application is
responsible for emptying or refilling the work buffer before calling the
JPEG library again.
Compression suspension:
For compression suspension, use an empty_output_buffer() routine that returns
FALSE; typically it will not do anything else. This will cause the
compressor to return to the caller of jpeg_write_scanlines(), with the return
value indicating that not all the supplied scanlines have been accepted.
The application must make more room in the output buffer, adjust the output
buffer pointer/count appropriately, and then call jpeg_write_scanlines()
again, pointing to the first unconsumed scanline.
When forced to suspend, the compressor will backtrack to a convenient stopping
point (usually the start of the current MCU); it will regenerate some output
data when restarted. Therefore, although empty_output_buffer() is only
called when the buffer is filled, you should NOT write out the entire buffer
after a suspension. Write only the data up to the current position of
next_output_byte/free_in_buffer. The data beyond that point will be
regenerated after resumption.
Because of the backtracking behavior, a good-size output buffer is essential
for efficiency; you don't want the compressor to suspend often. (In fact, an
overly small buffer could lead to infinite looping, if a single MCU required
more data than would fit in the buffer.) We recommend a buffer of at least
several Kbytes. You may want to insert explicit code to ensure that you don't
call jpeg_write_scanlines() unless there is a reasonable amount of space in
the output buffer; in other words, flush the buffer before trying to compress
more data.
The compressor does not allow suspension while it is trying to write JPEG
markers at the beginning and end of the file. This means that:
* At the beginning of a compression operation, there must be enough free
space in the output buffer to hold the header markers (typically 600 or
so bytes). The recommended buffer size is bigger than this anyway, so
this is not a problem as long as you start with an empty buffer. However,
this restriction might catch you if you insert large special markers, such
as a JFIF thumbnail image, without flushing the buffer afterwards.
* When you call jpeg_finish_compress(), there must be enough space in the
output buffer to emit any buffered data and the final EOI marker. In the
current implementation, half a dozen bytes should suffice for this, but
for safety's sake we recommend ensuring that at least 100 bytes are free
before calling jpeg_finish_compress().
A more significant restriction is that jpeg_finish_compress() cannot suspend.
This means you cannot use suspension with multi-pass operating modes, namely
Huffman code optimization and multiple-scan output. Those modes write the
whole file during jpeg_finish_compress(), which will certainly result in
buffer overrun. (Note that this restriction applies only to compression,
not decompression. The decompressor supports input suspension in all of its
operating modes.)
Decompression suspension:
For decompression suspension, use a fill_input_buffer() routine that simply
returns FALSE (except perhaps during error recovery, as discussed below).
This will cause the decompressor to return to its caller with an indication
that suspension has occurred. This can happen at four places:
* jpeg_read_header(): will return JPEG_SUSPENDED.
* jpeg_start_decompress(): will return FALSE, rather than its usual TRUE.
* jpeg_read_scanlines(): will return the number of scanlines already
completed (possibly 0).
* jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE.
The surrounding application must recognize these cases, load more data into
the input buffer, and repeat the call. In the case of jpeg_read_scanlines(),
increment the passed pointers past any scanlines successfully read.
Just as with compression, the decompressor will typically backtrack to a
convenient restart point before suspending. When fill_input_buffer() is
called, next_input_byte/bytes_in_buffer point to the current restart point,
which is where the decompressor will backtrack to if FALSE is returned.
The data beyond that position must NOT be discarded if you suspend; it needs
to be re-read upon resumption. In most implementations, you'll need to shift
this data down to the start of your work buffer and then load more data after
it. Again, this behavior means that a several-Kbyte work buffer is essential
for decent performance; furthermore, you should load a reasonable amount of
new data before resuming decompression. (If you loaded, say, only one new
byte each time around, you could waste a LOT of cycles.)
The skip_input_data() source manager routine requires special care in a
suspension scenario. This routine is NOT granted the ability to suspend the
decompressor; it can decrement bytes_in_buffer to zero, but no more. If the
requested skip distance exceeds the amount of data currently in the input
buffer, then skip_input_data() must set bytes_in_buffer to zero and record the
additional skip distance somewhere else. The decompressor will immediately
call fill_input_buffer(), which should return FALSE, which will cause a
suspension return. The surrounding application must then arrange to discard
the recorded number of bytes before it resumes loading the input buffer.
(Yes, this design is rather baroque, but it avoids complexity in the far more
common case where a non-suspending source manager is used.)
If the input data has been exhausted, we recommend that you emit a warning
and insert dummy EOI markers just as a non-suspending data source manager
would do. This can be handled either in the surrounding application logic or
within fill_input_buffer(); the latter is probably more efficient. If
fill_input_buffer() knows that no more data is available, it can set the
pointer/count to point to a dummy EOI marker and then return TRUE just as
though it had read more data in a non-suspending situation.
The decompressor does not attempt to suspend within any JPEG marker; it will
backtrack to the start of the marker. Hence the input buffer must be large
enough to hold the longest marker in the file. We recommend at least a 2K
buffer. The buffer would need to be 64K to allow for arbitrary COM or APPn
markers, but the decompressor does not actually try to read these; it just
skips them by calling skip_input_data(). If you provide a special marker
handling routine that does look at such markers, coping with buffer overflow
is your problem. Ordinary JPEG markers should normally not exceed a few
hundred bytes each (DHT tables are typically the longest). For robustness
against damaged marker length counts, you may wish to insert a test in your
application for the case that the input buffer is completely full and yet the
decoder has suspended without consuming any data --- otherwise, if this
situation did occur, it would lead to an endless loop.
Multiple-buffer management:
In some applications it is desirable to store the compressed data in a linked
list of buffer areas, so as to avoid data copying. This can be handled by
having empty_output_buffer() or fill_input_buffer() set the pointer and count
to reference the next available buffer; FALSE is returned only if no more
buffers are available. Although seemingly straightforward, there is a
pitfall in this approach: the backtrack that occurs when FALSE is returned
could back up into an earlier buffer. For example, when fill_input_buffer()
is called, the current pointer & count indicate the backtrack restart point.
Since fill_input_buffer() will set the pointer and count to refer to a new
buffer, the restart position must be saved somewhere else. Suppose a second
call to fill_input_buffer() occurs in the same library call, and no
additional input data is available, so fill_input_buffer must return FALSE.
If the JPEG library has not moved the pointer/count forward in the current
buffer, then *the correct restart point is the saved position in the prior
buffer*. Prior buffers may be discarded only after the library establishes
a restart point within a later buffer. Similar remarks apply for output into
a chain of buffers.
The library will never attempt to backtrack over a skip_input_data() call,
so any skipped data can be permanently discarded. You still have to deal
with the case of skipping not-yet-received data, however.
It's much simpler to use only a single buffer; when fill_input_buffer() is
called, move any unconsumed data (beyond the current pointer/count) down to
the beginning of this buffer and then load new data into the remaining buffer
space. This approach requires a little more data copying but is far easier
to get right.
Progressive JPEG support
------------------------
Progressive JPEG rearranges the stored data into a series of scans of
increasing quality. In situations where a JPEG file is transmitted across a
slow communications link, a decoder can generate a low-quality image very
quickly from the first scan, then gradually improve the displayed quality as
more scans are received. The final image after all scans are complete is
identical to that of a regular (sequential) JPEG file of the same quality
setting. Progressive JPEG files are often slightly smaller than equivalent
sequential JPEG files, but the possibility of incremental display is the main
reason for using progressive JPEG.
The IJG encoder library generates progressive JPEG files when given a
suitable "scan script" defining how to divide the data into scans.
Creation of progressive JPEG files is otherwise transparent to the encoder.
Progressive JPEG files can also be read transparently by the decoder library.
If the decoding application simply uses the library as defined above, it
will receive a final decoded image without any indication that the file was
progressive. Of course, this approach does not allow incremental display.
To perform incremental display, an application needs to use the decoder
library's "buffered-image" mode, in which it receives a decoded image
multiple times.
Each displayed scan requires about as much work to decode as a full JPEG
image of the same size, so the decoder must be fairly fast in relation to the
data transmission rate in order to make incremental display useful. However,
it is possible to skip displaying the image and simply add the incoming bits
to the decoder's coefficient buffer. This is fast because only Huffman
decoding need be done, not IDCT, upsampling, colorspace conversion, etc.
The IJG decoder library allows the application to switch dynamically between
displaying the image and simply absorbing the incoming bits. A properly
coded application can automatically adapt the number of display passes to
suit the time available as the image is received. Also, a final
higher-quality display cycle can be performed from the buffered data after
the end of the file is reached.
Progressive compression:
To create a progressive JPEG file (or a multiple-scan sequential JPEG file),
set the scan_info cinfo field to point to an array of scan descriptors, and
perform compression as usual. Instead of constructing your own scan list,
you can call the jpeg_simple_progression() helper routine to create a
recommended progression sequence; this method should be used by all
applications that don't want to get involved in the nitty-gritty of
progressive scan sequence design. (If you want to provide user control of
scan sequences, you may wish to borrow the scan script reading code found
in rdswitch.c, so that you can read scan script files just like cjpeg's.)
When scan_info is not NULL, the compression library will store DCT'd data
into a buffer array as jpeg_write_scanlines() is called, and will emit all
the requested scans during jpeg_finish_compress(). This implies that
multiple-scan output cannot be created with a suspending data destination
manager, since jpeg_finish_compress() does not support suspension. We
should also note that the compressor currently forces Huffman optimization
mode when creating a progressive JPEG file, because the default Huffman
tables are unsuitable for progressive files.
Progressive decompression:
When buffered-image mode is not used, the decoder library will read all of
a multi-scan file during jpeg_start_decompress(), so that it can provide a
final decoded image. (Here "multi-scan" means either progressive or
multi-scan sequential.) This makes multi-scan files transparent to the
decoding application. However, existing applications that used suspending
input with version 5 of the IJG library will need to be modified to check
for a suspension return from jpeg_start_decompress().
To perform incremental display, an application must use the library's
buffered-image mode. This is described in the next section.
Buffered-image mode
-------------------
In buffered-image mode, the library stores the partially decoded image in a
coefficient buffer, from which it can be read out as many times as desired.
This mode is typically used for incremental display of progressive JPEG files,
but it can be used with any JPEG file. Each scan of a progressive JPEG file
adds more data (more detail) to the buffered image. The application can
display in lockstep with the source file (one display pass per input scan),
or it can allow input processing to outrun display processing. By making
input and display processing run independently, it is possible for the
application to adapt progressive display to a wide range of data transmission
rates.
The basic control flow for buffered-image decoding is
jpeg_create_decompress()
set data source
jpeg_read_header()
set overall decompression parameters
cinfo.buffered_image = TRUE; /* select buffered-image mode */
jpeg_start_decompress()
for (each output pass) {
adjust output decompression parameters if required
jpeg_start_output() /* start a new output pass */
for (all scanlines in image) {
jpeg_read_scanlines()
display scanlines
}
jpeg_finish_output() /* terminate output pass */
}
jpeg_finish_decompress()
jpeg_destroy_decompress()
This differs from ordinary unbuffered decoding in that there is an additional
level of looping. The application can choose how many output passes to make
and how to display each pass.
The simplest approach to displaying progressive images is to do one display
pass for each scan appearing in the input file. In this case the outer loop
condition is typically
while (! jpeg_input_complete(&cinfo))
and the start-output call should read
jpeg_start_output(&cinfo, cinfo.input_scan_number);
The second parameter to jpeg_start_output() indicates which scan of the input
file is to be displayed; the scans are numbered starting at 1 for this
purpose. (You can use a loop counter starting at 1 if you like, but using
the library's input scan counter is easier.) The library automatically reads
data as necessary to complete each requested scan, and jpeg_finish_output()
advances to the next scan or end-of-image marker (hence input_scan_number
will be incremented by the time control arrives back at jpeg_start_output()).
With this technique, data is read from the input file only as needed, and
input and output processing run in lockstep.
After reading the final scan and reaching the end of the input file, the
buffered image remains available; it can be read additional times by
repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output()
sequence. For example, a useful technique is to use fast one-pass color
quantization for display passes made while the image is arriving, followed by
a final display pass using two-pass quantization for highest quality. This
is done by changing the library parameters before the final output pass.
Changing parameters between passes is discussed in detail below.
In general the last scan of a progressive file cannot be recognized as such
until after it is read, so a post-input display pass is the best approach if
you want special processing in the final pass.
When done with the image, be sure to call jpeg_finish_decompress() to release
the buffered image (or just use jpeg_destroy_decompress()).
If input data arrives faster than it can be displayed, the application can
cause the library to decode input data in advance of what's needed to produce
output. This is done by calling the routine jpeg_consume_input().
The return value is one of the following:
JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan)
JPEG_REACHED_EOI: reached the EOI marker (end of image)
JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data
JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan
JPEG_SUSPENDED: suspended before completing any of the above
(JPEG_SUSPENDED can occur only if a suspending data source is used.) This
routine can be called at any time after initializing the JPEG object. It
reads some additional data and returns when one of the indicated significant
events occurs. (If called after the EOI marker is reached, it will
immediately return JPEG_REACHED_EOI without attempting to read more data.)
The library's output processing will automatically call jpeg_consume_input()
whenever the output processing overtakes the input; thus, simple lockstep
display requires no direct calls to jpeg_consume_input(). But by adding
calls to jpeg_consume_input(), you can absorb data in advance of what is
being displayed. This has two benefits:
* You can limit buildup of unprocessed data in your input buffer.
* You can eliminate extra display passes by paying attention to the
state of the library's input processing.
The first of these benefits only requires interspersing calls to
jpeg_consume_input() with your display operations and any other processing
you may be doing. To avoid wasting cycles due to backtracking, it's best to
call jpeg_consume_input() only after a hundred or so new bytes have arrived.
This is discussed further under "I/O suspension", above. (Note: the JPEG
library currently is not thread-safe. You must not call jpeg_consume_input()
from one thread of control if a different library routine is working on the
same JPEG object in another thread.)
When input arrives fast enough that more than one new scan is available
before you start a new output pass, you may as well skip the output pass
corresponding to the completed scan. This occurs for free if you pass
cinfo.input_scan_number as the target scan number to jpeg_start_output().
The input_scan_number field is simply the index of the scan currently being
consumed by the input processor. You can ensure that this is up-to-date by
emptying the input buffer just before calling jpeg_start_output(): call
jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or
JPEG_REACHED_EOI.
The target scan number passed to jpeg_start_output() is saved in the
cinfo.output_scan_number field. The library's output processing calls
jpeg_consume_input() whenever the current input scan number and row within
the scan is less than or equal to the current output scan number and row.
Thus, input processing can "get ahead" of the output processing but is not
allowed to "fall behind". You can achieve several different effects by
manipulating this interlock rule. For example, if you pass a target scan
number greater than the current input scan number, the output processor will
wait until that scan starts to arrive before producing any output. (To avoid
an infinite loop, the target scan number is automatically reset to the last
scan number when the end of image is reached. Thus, if you specify a large
target scan number, the library will just absorb the entire input file and
then perform an output pass. This is effectively the same as what
jpeg_start_decompress() does when you don't select buffered-image mode.)
When you pass a target scan number equal to the current input scan number,
the image is displayed no faster than the current input scan arrives. The
final possibility is to pass a target scan number less than the current input
scan number; this disables the input/output interlock and causes the output
processor to simply display whatever it finds in the image buffer, without
waiting for input. (However, the library will not accept a target scan
number less than one, so you can't avoid waiting for the first scan.)
When using jpeg_consume_input(), you'll typically 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
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 image 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 image or the SOS marker that begins another scan.
(But it reads no input if jpeg_consume_input() has already reached the
end of the image or a SOS marker beyond the target output scan.)
* jpeg_finish_decompress() will read until the end of image, 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.
3. Two-pass quantization to a colormap chosen specifically for the image.
Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL.
(This is the default setting selected by jpeg_read_header, but it is
probably NOT what you want for the first pass of progressive display!)
These methods offer successively better quality and lesser speed. However,
only the first method is available for quantizing in non-RGB color spaces.
IMPORTANT: because the different quantizer methods have very different
working-storage requirements, the library requires you to indicate which
one(s) you intend to use before you call jpeg_start_decompress(). (If we did
not require this, the max_memory_to_use setting would be a complete fiction.)
You do this by setting one or more of these three cinfo fields to TRUE:
enable_1pass_quant Fixed color cube colormap
enable_external_quant Externally-supplied colormap
enable_2pass_quant Two-pass custom colormap
All three are initialized FALSE by jpeg_read_header(). But
jpeg_start_decompress() automatically sets TRUE the one selected by the
current two_pass_quantize and colormap settings, so you only need to set the
enable flags for any other quantization methods you plan to change to later.
After setting the enable flags correctly at jpeg_start_decompress() time, you
can change to any enabled quantization method by setting two_pass_quantize
and colormap properly just before calling jpeg_start_output(). The following
special rules apply:
1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass
or 2-pass mode from a different mode, or when you want the 2-pass
quantizer to be re-run to generate a new colormap.
2. To switch to an external colormap, or to change to a different external
colormap than was used on the prior pass, you must call
jpeg_new_colormap() after setting cinfo.colormap.
NOTE: if you want to use the same colormap as was used in the prior pass,
you should not do either of these things. This will save some nontrivial
switchover costs.
(These requirements exist because cinfo.colormap will always be non-NULL
after completing a prior output pass, since both the 1-pass and 2-pass
quantizers set it to point to their output colormaps. Thus you have to
do one of these two things to notify the library that something has changed.
Yup, it's a bit klugy, but it's necessary to do it this way for backwards
compatibility.)
Note that in buffered-image mode, the library generates any requested colormap
during jpeg_start_output(), not during jpeg_start_decompress().
When using two-pass quantization, jpeg_start_output() makes a pass over the
buffered image to determine the optimum color map; it therefore may take a
significant amount of time, whereas ordinarily it does little work. The
progress monitor hook is called during this pass, if defined. It is also
important to realize that if the specified target scan number is greater than
or equal to the current input scan number, jpeg_start_output() will attempt
to consume input as it makes this pass. If you use a suspending data source,
you need to check for a FALSE return from jpeg_start_output() under these
conditions. The combination of 2-pass quantization and a not-yet-fully-read
target scan is the only case in which jpeg_start_output() will consume input.
Application authors who support buffered-image mode may be tempted to use it
for all JPEG images, even single-scan ones. This will work, but it is
inefficient: there is no need to create an image-sized coefficient buffer for
single-scan images. Requesting buffered-image mode for such an image wastes
memory. Worse, it can cost time on large images, since the buffered data has
to be swapped out or written to a temporary file. If you are concerned about
maximum performance on baseline JPEG files, you should use buffered-image
mode only when the incoming file actually has multiple scans. This can be
tested by calling jpeg_has_multiple_scans(), which will return a correct
result at any time after jpeg_read_header() completes.
It is also worth noting that when you use jpeg_consume_input() to let input
processing get ahead of output processing, the resulting pattern of access to
the coefficient buffer is quite nonsequential. It's best to use the memory
manager jmemnobs.c if you can (ie, if you have enough real or virtual main
memory). If not, at least make sure that max_memory_to_use is set as high as
possible. If the JPEG memory manager has to use a temporary file, you will
probably see a lot of disk traffic and poor performance. (This could be
improved with additional work on the memory manager, but we haven't gotten
around to it yet.)
In some applications it may be convenient to use jpeg_consume_input() for all
input processing, including reading the initial markers; that is, you may
wish to call jpeg_consume_input() instead of jpeg_read_header() during
startup. This works, but note that you must check for JPEG_REACHED_SOS and
JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes.
Once the first SOS marker has been reached, you must call
jpeg_start_decompress() before jpeg_consume_input() will consume more input;
it'll just keep returning JPEG_REACHED_SOS until you do. If you read a
tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI
without ever returning JPEG_REACHED_SOS; be sure to check for this case.
If this happens, the decompressor will not read any more input until you call
jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not
using buffered-image mode, but in that case it's basically a no-op after the
initial markers have been read: it will just return JPEG_SUSPENDED.
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.
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. More commonly
you'd want to read the tables from a tables-only file. The jpeg_read_header()
call is sufficient to read a tables-only file. You must pass a second
parameter of FALSE to indicate that you do not require an image to be present.
Thus, the typical scenario is
create JPEG decompression object
set source to tables-only file
jpeg_read_header(&cinfo, FALSE);
set source to abbreviated image file
jpeg_read_header(&cinfo, TRUE);
set decompression parameters
jpeg_start_decompress(&cinfo);
read data...
jpeg_finish_decompress(&cinfo);
In some cases, you may want to read a file without knowing whether it contains
an image or just tables. In that case, pass FALSE and check the return value
from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found,
JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value,
JPEG_SUSPENDED, is possible when using a suspending data source manager.)
Note that jpeg_read_header() will not complain if you read an abbreviated
image for which you haven't loaded the missing tables; the missing-table check
occurs later, in jpeg_start_decompress().
It is possible to read a series of images from a single source file by
repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence,
without releasing/recreating the JPEG object or the data source module.
(If you did reinitialize, any partial bufferload left in the data source
buffer at the end of one image would be discarded, causing you to lose the
start of the next image.) When you use this method, stored tables are
automatically carried forward, so some of the images can be abbreviated images
that depend on tables from earlier images.
If you intend to write a series of images into a single destination file,
you might want to make a specialized data destination module that doesn't
flush the output buffer at term_destination() time. This would speed things
up by some trifling amount. Of course, you'd need to remember to flush the
buffer after the last image. You can make the later images be abbreviated
ones by passing FALSE to jpeg_start_compress().
Special markers
---------------
Some applications may need to insert or extract special data in the JPEG
datastream. The JPEG standard provides marker types "COM" (comment) and
"APP0" through "APP15" (application) to hold application-specific data.
Unfortunately, the use of these markers is not specified by the standard.
COM markers are fairly widely used to hold user-supplied text. The JFIF file
format spec uses APP0 markers with specified initial strings to hold certain
data. Adobe applications use APP14 markers beginning with the string "Adobe"
for miscellaneous data. Other APPn markers are rarely seen, but might
contain almost anything.
If you wish to store user-supplied text, we recommend you use COM markers
and place readable 7-bit ASCII text in them. Newline conventions are not
standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR
(Mac style). A robust COM reader should be able to cope with random binary
garbage, including nulls, since some applications generate COM markers
containing non-ASCII junk. (But yours should not be one of them.)
For program-supplied data, use an APPn marker, and be sure to begin it with an
identifying string so that you can tell whether the marker is actually yours.
It's probably best to avoid using APP0 or APP14 for any private markers.
(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you
not use APP8 markers for any private purposes, either.)
Keep in mind that at most 65533 bytes can be put into one marker, but you
can have as many markers as you like.
By default, the IJG compression library will write a JFIF APP0 marker if the
selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if
the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but
we don't recommend it. The decompression library will recognize JFIF and
Adobe markers and will set the JPEG colorspace properly when one is found.
You can write special markers immediately following the datastream header by
calling jpeg_write_marker() after jpeg_start_compress() and before the first
call to jpeg_write_scanlines(). When you do this, the markers appear after
the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before
all else. Specify the marker type parameter as "JPEG_COM" for COM or
"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write
any marker type, but we don't recommend writing any other kinds of marker.)
For example, to write a user comment string pointed to by comment_text:
jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));
Or if you prefer to synthesize the marker byte sequence yourself, you can
just cram it straight into the data destination module.
For decompression, you can supply your own routine to process COM or APPn
markers by calling jpeg_set_marker_processor(). Usually you'd call this
after creating a decompression object and before calling jpeg_read_header(),
because the markers of interest will normally be scanned by jpeg_read_header.
Once you've supplied a routine, it will be used for the life of that
decompression object. A separate routine may be registered for COM and for
each APPn marker code.
A marker processor routine must have the signature
boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)
Although the marker code is not explicitly passed, the routine can find it
in cinfo->unread_marker. At the time of call, the marker proper has been
read from the data source module. The processor routine is responsible for
reading the marker length word and the remaining parameter bytes, if any.
Return TRUE to indicate success. (FALSE should be returned only if you are
using a suspending data source and it tells you to suspend. See the standard
marker processors in jdmarker.c for appropriate coding methods if you need to
use a suspending data source.)
If you override the default APP0 or APP14 processors, it is up to you to
recognize JFIF and Adobe markers if you want colorspace recognition to occur
properly. We recommend copying and extending the default processors if you
want to do that.
A simple example of an external COM processor can be found in djpeg.c.
Raw (downsampled) image data
----------------------------
Some applications need to supply already-downsampled image data to the JPEG
compressor, or to receive raw downsampled data from the decompressor. The
library supports this requirement by allowing the application to write or
read raw data, bypassing the normal preprocessing or postprocessing steps.
The interface is different from the standard one and is somewhat harder to
use. If your interest is merely in bypassing color conversion, we recommend
that you use the standard interface and simply set jpeg_color_space =
in_color_space (or jpeg_color_space = out_color_space for decompression).
The mechanism described in this section is necessary only to supply or
receive downsampled image data, in which not all components have the same
dimensions.
To compress raw data, you must supply the data in the colorspace to be used
in the JPEG file (please read the earlier section on Special color spaces)
and downsampled to the sampling factors specified in the JPEG parameters.
You must supply the data in the format used internally by the JPEG library,
namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional
arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one
color component. This structure is necessary since the components are of
different sizes. If the image dimensions are not a multiple of the MCU size,
you must also pad the data correctly (usually, this is done by replicating
the last column and/or row). The data must be padded to a multiple of a DCT
block in each component: that is, each downsampled row must contain a
multiple of 8 valid samples, and there must be a multiple of 8 sample rows
for each component. (For applications such as conversion of digital TV
images, the standard image size is usually a multiple of the DCT block size,
so that no padding need actually be done.)
The procedure for compression of raw data is basically the same as normal
compression, except that you call jpeg_write_raw_data() in place of
jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do
the following:
* Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().)
This notifies the library that you will be supplying raw data.
* Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace()
call is a good idea. Note that since color conversion is bypassed,
in_color_space is ignored, except that jpeg_set_defaults() uses it to
choose the default jpeg_color_space setting.
* Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and
cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the
dimensions of the data you are supplying, it's wise to set them
explicitly, rather than assuming the library's defaults are what you want.
To pass raw data to the library, call jpeg_write_raw_data() in place of
jpeg_write_scanlines(). The two routines work similarly except that
jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY.
The scanlines count passed to and returned from jpeg_write_raw_data is
measured in terms of the component with the largest v_samp_factor.
jpeg_write_raw_data() processes one MCU row per call, which is to say
v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines
value must be at least max_v_samp_factor*DCTSIZE, and the return value will
be exactly that amount (or possibly some multiple of that amount, in future
library versions). This is true even on the last call at the bottom of the
image; don't forget to pad your data as necessary.
The required dimensions of the supplied data can be computed for each
component as
cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row
cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image
after jpeg_start_compress() has initialized those fields. If the valid data
is smaller than this, it must be padded appropriately. For some sampling
factors and image sizes, additional dummy DCT blocks are inserted to make
the image a multiple of the MCU dimensions. The library creates such dummy
blocks itself; it does not read them from your supplied data. Therefore you
need never pad by more than DCTSIZE samples. An example may help here.
Assume 2h2v downsampling of YCbCr data, that is
cinfo->comp_info[0].h_samp_factor = 2 for Y
cinfo->comp_info[0].v_samp_factor = 2
cinfo->comp_info[1].h_samp_factor = 1 for Cb
cinfo->comp_info[1].v_samp_factor = 1
cinfo->comp_info[2].h_samp_factor = 1 for Cr
cinfo->comp_info[2].v_samp_factor = 1
and suppose that the nominal image dimensions (cinfo->image_width and
cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will
compute downsampled_width = 101 and width_in_blocks = 13 for Y,
downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same
for the height fields). You must pad the Y data to at least 13*8 = 104
columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The
MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16
scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual
sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed,
so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row
of Y data is dummy, so it doesn't matter what you pass for it in the data
arrays, but the scanlines count must total up to 112 so that all of the Cb
and Cr data gets passed.
Output suspension is supported with raw-data compression: if the data
destination module suspends, jpeg_write_raw_data() will return 0.
In this case the same data rows must be passed again on the next call.
Decompression with raw data output implies bypassing all postprocessing:
you cannot ask for rescaling or color quantization, for instance. More
seriously, you must deal with the color space and sampling factors present in
the incoming file. If your application only handles, say, 2h1v YCbCr data,
you must check for and fail on other color spaces or other sampling factors.
The library will not convert to a different color space for you.
To obtain raw data output, set cinfo->raw_data_out = TRUE before
jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to
verify that the color space and sampling factors are ones you can handle.
Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The
decompression process is otherwise the same as usual.
jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a
buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is
the same as for raw-data compression). The buffer you pass must be large
enough to hold the actual data plus padding to DCT-block boundaries. As with
compression, any entirely dummy DCT blocks are not processed so you need not
allocate space for them, but the total scanline count includes them. The
above example of computing buffer dimensions for raw-data compression is
equally valid for decompression.
Input suspension is supported with raw-data decompression: if the data source
module suspends, jpeg_read_raw_data() will return 0. You can also use
buffered-image mode to read raw data in multiple passes.
Really raw data: DCT coefficients
---------------------------------
It is possible to read or write the contents of a JPEG file as raw DCT
coefficients. This facility is mainly intended for use in lossless
transcoding between different JPEG file formats. Other possible applications
include lossless cropping of a JPEG image, lossless reassembly of a
multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc.
To read the contents of a JPEG file as DCT coefficients, open the file and do
jpeg_read_header() as usual. But instead of calling jpeg_start_decompress()
and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the
entire image into a set of virtual coefficient-block arrays, one array per
component. The return value is a pointer to an array of virtual-array
descriptors. Each virtual array can be accessed directly using the JPEG
memory manager's access_virt_barray method (see Memory management, below,
and also read structure.doc's discussion of virtual array handling). Or,
for simple transcoding to a different JPEG file format, the array list can
just be handed directly to 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.
Each block in the block arrays contains quantized coefficient values in
normal array order (not JPEG zigzag order). The block arrays contain only
DCT blocks containing real data; any entirely-dummy blocks added to fill out
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().
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.
When using the decompressor's buffered-image mode, the progress monitor work
estimate is likely to be completely unhelpful, because the library has no way
to know how many output passes will be demanded of it. Currently, the library
sets total_passes based on the assumption that there will be one more output
pass if the input file end hasn't yet been read (jpeg_input_complete() isn't
TRUE), but no more output passes if the file end has been reached when the
output pass is started. This means that total_passes will rise as additional
output passes are requested. If you have a way of determining the input file
size, estimating progress based on the fraction of the file that's been read
will probably be more useful than using the library's value.
Memory management
-----------------
This section covers some key facts about the JPEG library's built-in memory
manager. For more info, please read structure.doc's section about the memory
manager, and consult the source code if necessary.
All memory and temporary file allocation within the library is done via the
memory manager. If necessary, you can replace the "back end" of the memory
manager to control allocation yourself (for example, if you don't want the
library to use malloc() and free() for some reason).
Some data is allocated "permanently" and will not be freed until the JPEG
object is destroyed. Most data is allocated "per image" and is freed by
jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the
memory manager yourself to allocate structures that will automatically be
freed at these times. Typical code for this is
ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size);
Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object.
Use alloc_large instead of alloc_small for anything bigger than a few Kbytes.
There are also alloc_sarray and alloc_barray routines that automatically
build 2-D sample or block arrays.
The library's minimum space requirements to process an image depend on the
image's width, but not on its height, because the library ordinarily works
with "strip" buffers that are as wide as the image but just a few rows high.
Some operating modes (eg, two-pass color quantization) require full-image
buffers. Such buffers are treated as "virtual arrays": only the current strip
need be in memory, and the rest can be swapped out to a temporary file.
If you use the simplest memory manager back end (jmemnobs.c), then no
temporary files are used; virtual arrays are simply malloc()'d. Images bigger
than memory can be processed only if your system supports virtual memory.
The other memory manager back ends support temporary files of various flavors
and thus work in machines without virtual memory. They may also be useful on
Unix machines if you need to process images that exceed available swap space.
When using temporary files, the library will make the in-memory buffers for
its virtual arrays just big enough to stay within a "maximum memory" setting.
Your application can set this limit by setting cinfo->mem->max_memory_to_use
after creating the JPEG object. (Of course, there is still a minimum size for
the buffers, so the max-memory setting is effective only if it is bigger than
the minimum space needed.) If you allocate any large structures yourself, you
must allocate them before jpeg_start_compress() or jpeg_start_decompress() in
order to have them counted against the max memory limit. Also keep in mind
that space allocated with alloc_small() is ignored, on the assumption that
it's too small to be worth worrying about; so a reasonable safety margin
should be left when setting max_memory_to_use.
If you use the jmemname.c or jmemdos.c memory manager back end, it is
important to clean up the JPEG object properly to ensure that the temporary
files get deleted. (This is especially crucial with jmemdos.c, where the
"temporary files" may be extended-memory segments; if they are not freed,
DOS will require a reboot to recover the memory.) Thus, with these memory
managers, it's a good idea to provide a signal handler that will trap any
early exit from your program. The handler should call either jpeg_abort()
or jpeg_destroy() for any active JPEG objects. A handler is not needed with
jmemnobs.c, and shouldn't be necessary with jmemansi.c either, since the C
library is supposed to take care of deleting files made with tmpfile().
Library compile-time options
----------------------------
A number of compile-time options are available by modifying jmorecfg.h.
The JPEG standard provides for both the baseline 8-bit DCT process and
a 12-bit DCT process. 12-bit lossy JPEG is supported if you define
BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be
larger than a char, so it affects the surrounding application's image data.
The sample applications cjpeg and djpeg can support 12-bit mode only for PPM
and GIF file formats; you must disable the other file formats to compile a
12-bit cjpeg or djpeg. (install.doc has more information about that.)
At present, a 12-bit library can handle *only* 12-bit images, not both
precisions. (If you need to include both 8- and 12-bit libraries in a single
application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES
for just one of the copies. You'd have to access the 8-bit and 12-bit copies
from separate application source files. This is untested ... if you try it,
we'd like to hear whether it works!)
Note that a 12-bit library always compresses in Huffman optimization mode,
in order to generate valid Huffman tables. This is necessary because our
default Huffman tables only cover 8-bit data. If you need to output 12-bit
files in one pass, you'll have to supply suitable default Huffman tables.
The maximum number of components (color channels) in the image is determined
by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we
expect that few applications will need more than four or so.
On machines with unusual data type sizes, you may be able to improve
performance or reduce memory space by tweaking the various typedefs in
jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s
is quite slow; consider trading memory for speed by making JCOEF, INT16, and
UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int.
You probably don't want to make JSAMPLE be int unless you have lots of memory
to burn.
You can reduce the size of the library by compiling out various optional
functions. To do this, undefine xxx_SUPPORTED symbols as necessary.
Portability considerations
--------------------------
The JPEG library has been written to be extremely portable; the sample
applications cjpeg and djpeg are slightly less so. This section summarizes
the design goals in this area. (If you encounter any bugs that cause the
library to be less portable than is claimed here, we'd appreciate hearing
about them.)
The code works fine on both ANSI and pre-ANSI C compilers, using any of the
popular system include file setups, and some not-so-popular ones too. See
install.doc for configuration procedures.
The code is not dependent on the exact sizes of the C data types. As
distributed, we make the assumptions that
char is at least 8 bits wide
short is at least 16 bits wide
int is at least 16 bits wide
long is at least 32 bits wide
(These are the minimum requirements of the ANSI C standard.) Wider types will
work fine, although memory may be used inefficiently if char is much larger
than 8 bits or short is much bigger than 16 bits. The code should work
equally well with 16- or 32-bit ints.
In a system where these assumptions are not met, you may be able to make the
code work by modifying the typedefs in jmorecfg.h. However, you will probably
have difficulty if int is less than 16 bits wide, since references to plain
int abound in the code.
char can be either signed or unsigned, although the code runs faster if an
unsigned char type is available. If char is wider than 8 bits, you will need
to redefine JOCTET and/or provide custom data source/destination managers so
that JOCTET represents exactly 8 bits of data on external storage.
The JPEG library proper does not assume ASCII representation of characters.
But some of the image file I/O modules in cjpeg/djpeg do have ASCII
dependencies in file-header manipulation; so does cjpeg's select_file_type()
routine.
The JPEG library does not rely heavily on the C library. In particular, C
stdio is used only by the data source/destination modules and the error
handler, all of which are application-replaceable. (cjpeg/djpeg are more
heavily dependent on stdio.) malloc and free are called only from the memory
manager "back end" module, so you can use a different memory allocator by
replacing that one file.
The code generally assumes that C names must be unique in the first 15
characters. However, global function names can be made unique in the
first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES.
More info about porting the code may be gleaned by reading jconfig.doc,
jmorecfg.h, and jinclude.h.
Notes for MS-DOS implementors
-----------------------------
The IJG code is designed to work efficiently in 80x86 "small" or "medium"
memory models (i.e., data pointers are 16 bits unless explicitly declared
"far"; code pointers can be either size). You may be able to use small
model to compile cjpeg or djpeg by itself, but you will probably have to use
medium model for any larger application. This won't make much difference in
performance. You *will* take a noticeable performance hit if you use a
large-data memory model (perhaps 10%-25%), and you should avoid "huge" model
if at all possible.
The JPEG library typically needs 2Kb-3Kb of stack space. It will also
malloc about 20K-30K of near heap space while executing (and lots of far
heap, but that doesn't count in this calculation). This figure will vary
depending on selected operating mode, and to a lesser extent on image size.
There is also about 5Kb-6Kb of constant data which will be allocated in the
near data segment (about 4Kb of this is the error message table).
Thus you have perhaps 20K available for other modules' static data and near
heap space before you need to go to a larger memory model. The C library's
static data will account for several K of this, but that still leaves a good
deal for your needs. (If you are tight on space, you could reduce the sizes
of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to
1K. Another possibility is to move the error message table to far memory;
this should be doable with only localized hacking on jerror.c.)
About 2K of the near heap space is "permanent" memory that will not be
released until you destroy the JPEG object. This is only an issue if you
save a JPEG object between compression or decompression operations.
Far data space may also be a tight resource when you are dealing with large
images. The most memory-intensive case is decompression with two-pass color
quantization, or single-pass quantization to an externally supplied color
map. This requires a 128Kb color lookup table plus strip buffers amounting
to about 50 bytes per column for typical sampling ratios (eg, about 32000
bytes for a 640-pixel-wide image). You may not be able to process wide
images if you have large data structures of your own.
Of course, all of these concerns vanish if you use a 32-bit flat-memory-model
compiler, such as DJGPP or Watcom C. We highly recommend flat model if you
can use it; the JPEG library is significantly faster in flat model.