Alien-FreeImage
view release on metacpan or search on metacpan
src/Source/LibJPEG/libjpeg.txt view on Meta::CPAN
right. The component values for each pixel are adjacent in the row; for
example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an
array of data type JSAMPLE --- which is typically "unsigned char", unless
you've changed jmorecfg.h. (You can also change the RGB pixel layout, say
to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in
that file before doing so.)
A 2-D array of pixels is formed by making a list of pointers to the starts of
scanlines; so the scanlines need not be physically adjacent in memory. Even
if you process just one scanline at a time, you must make a one-element
pointer array to conform to this structure. Pointers to JSAMPLE rows are of
type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY.
The library accepts or supplies one or more complete scanlines per call.
It is not possible to process part of a row at a time. Scanlines are always
processed top-to-bottom. You can process an entire image in one call if you
have it all in memory, but usually it's simplest to process one scanline at
a time.
For best results, source data values should have the precision specified by
BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress
data that's only 6 bits/channel, you should left-justify each value in a
byte before passing it to the compressor. If you need to compress data
that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 9 to 12.
(See "Library compile-time options", later.)
The data format returned by the decompressor is the same in all details,
except that colormapped output is supported. (Again, a JPEG file is never
colormapped. But you can ask the decompressor to perform on-the-fly color
quantization to deliver colormapped output.) If you request colormapped
output then the returned data array contains a single JSAMPLE per pixel;
its value is an index into a color map. The color map is represented as
a 2-D JSAMPARRAY in which each row holds the values of one color component,
that is, colormap[i][j] is the value of the i'th color component for pixel
value (map index) j. Note that since the colormap indexes are stored in
JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE
(ie, at most 256 colors for an 8-bit JPEG library).
Compression details
-------------------
Here we revisit the JPEG compression outline given in the overview.
1. Allocate and initialize a JPEG compression object.
A JPEG compression object is a "struct jpeg_compress_struct". (It also has
a bunch of subsidiary structures which are allocated via malloc(), but the
application doesn't control those directly.) This struct can be just a local
variable in the calling routine, if a single routine is going to execute the
whole JPEG compression sequence. Otherwise it can be static or allocated
from malloc().
You will also need a structure representing a JPEG error handler. The part
of this that the library cares about is a "struct jpeg_error_mgr". If you
are providing your own error handler, you'll typically want to embed the
jpeg_error_mgr struct in a larger structure; this is discussed later under
"Error handling". For now we'll assume you are just using the default error
handler. The default error handler will print JPEG error/warning messages
on stderr, and it will call exit() if a fatal error occurs.
You must initialize the error handler structure, store a pointer to it into
the JPEG object's "err" field, and then call jpeg_create_compress() to
initialize the rest of the JPEG object.
Typical code for this step, if you are using the default error handler, is
struct jpeg_compress_struct cinfo;
struct jpeg_error_mgr jerr;
...
cinfo.err = jpeg_std_error(&jerr);
jpeg_create_compress(&cinfo);
jpeg_create_compress allocates a small amount of memory, so it could fail
if you are out of memory. In that case it will exit via the error handler;
that's why the error handler must be initialized first.
2. Specify the destination for the compressed data (eg, a file).
As previously mentioned, the JPEG library delivers compressed data to a
"data destination" module. The library includes one data destination
module which knows how to write to a stdio stream. You can use your own
destination module if you want to do something else, as discussed later.
If you use the standard destination module, you must open the target stdio
stream beforehand. Typical code for this step looks like:
FILE * outfile;
...
if ((outfile = fopen(filename, "wb")) == NULL) {
fprintf(stderr, "can't open %s\n", filename);
exit(1);
}
jpeg_stdio_dest(&cinfo, outfile);
where the last line invokes the standard destination module.
WARNING: it is critical that the binary compressed data be delivered to the
output file unchanged. On non-Unix systems the stdio library may perform
newline translation or otherwise corrupt binary data. To suppress this
behavior, you may need to use a "b" option to fopen (as shown above), or use
setmode() or another routine to put the stdio stream in binary mode. See
cjpeg.c and djpeg.c for code that has been found to work on many systems.
You can select the data destination after setting other parameters (step 3),
if that's more convenient. You may not change the destination between
calling jpeg_start_compress() and jpeg_finish_compress().
3. Set parameters for compression, including image size & colorspace.
You must supply information about the source image by setting the following
fields in the JPEG object (cinfo structure):
image_width Width of image, in pixels
image_height Height of image, in pixels
input_components Number of color channels (samples per pixel)
in_color_space Color space of source image
The image dimensions are, hopefully, obvious. JPEG supports image dimensions
of 1 to 64K pixels in either direction. The input color space is typically
RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special
color spaces", later, for more info.) The in_color_space field must be
assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or
JCS_GRAYSCALE.
JPEG has a large number of compression parameters that determine how the
image is encoded. Most applications don't need or want to know about all
these parameters. You can set all the parameters to reasonable defaults by
calling jpeg_set_defaults(); then, if there are particular values you want
to change, you can do so after that. The "Compression parameter selection"
section tells about all the parameters.
You must set in_color_space correctly before calling jpeg_set_defaults(),
because the defaults depend on the source image colorspace. However the
other three source image parameters need not be valid until you call
jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more
than once, if that happens to be convenient.
Typical code for a 24-bit RGB source image is
cinfo.image_width = Width; /* image width and height, in pixels */
cinfo.image_height = Height;
cinfo.input_components = 3; /* # of color components per pixel */
cinfo.in_color_space = JCS_RGB; /* colorspace of input image */
jpeg_set_defaults(&cinfo);
/* Make optional parameter settings here */
4. jpeg_start_compress(...);
src/Source/LibJPEG/libjpeg.txt view on Meta::CPAN
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);
}
jpeg_stdio_src(&cinfo, infile);
where the last line invokes the standard source module.
WARNING: it is critical that the binary compressed data be read unchanged.
On non-Unix systems the stdio library may perform newline translation or
otherwise corrupt binary data. To suppress this behavior, you may need to use
a "b" option to fopen (as shown above), or use setmode() or another routine to
put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that
has been found to work on many systems.
You may not change the data source between calling jpeg_read_header() and
jpeg_finish_decompress(). If you wish to read a series of JPEG images from
a single source file, you should repeat the jpeg_read_header() to
jpeg_finish_decompress() sequence without reinitializing either the JPEG
object or the data source module; this prevents buffered input data from
being discarded.
3. Call jpeg_read_header() to obtain image info.
Typical code for this step is just
jpeg_read_header(&cinfo, TRUE);
This will read the source datastream header markers, up to the beginning
of the compressed data proper. On return, the image dimensions and other
info have been stored in the JPEG object. The application may wish to
consult this information before selecting decompression parameters.
More complex code is necessary if
* A suspending data source is used --- in that case jpeg_read_header()
may return before it has read all the header data. See "I/O suspension",
below. The normal stdio source manager will NOT cause this to happen.
* Abbreviated JPEG files are to be processed --- see the section on
abbreviated datastreams. Standard applications that deal only in
interchange JPEG files need not be concerned with this case either.
It is permissible to stop at this point if you just wanted to find out the
image dimensions and other header info for a JPEG file. In that case,
call jpeg_destroy() when you are done with the JPEG object, or call
jpeg_abort() to return it to an idle state before selecting a new data
source and reading another header.
4. Set parameters for decompression.
jpeg_read_header() sets appropriate default decompression parameters based on
the properties of the image (in particular, its colorspace). However, you
may well want to alter these defaults before beginning the decompression.
For example, the default is to produce full color output from a color file.
If you want colormapped output you must ask for it. Other options allow the
returned image to be scaled and allow various speed/quality tradeoffs to be
selected. "Decompression parameter selection", below, gives details.
If the defaults are appropriate, nothing need be done at this step.
Note that all default values are set by each call to jpeg_read_header().
src/Source/LibJPEG/libjpeg.txt view on Meta::CPAN
is not one of the ones supported by the interchange standards.
jpeg_set_colorspace() will set the compression parameters to include or omit
the APPn markers properly, so long as it is told the truth about the JPEG
color space. For example, if you are writing some random 3-component color
space without conversion, don't try to fake out the library by setting
in_color_space and jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN.
You may want to write an APPn marker of your own devising to identify
the colorspace --- see "Special markers", below.
When told that the color space is UNKNOWN, the library will default to using
luminance-quality compression parameters for all color components. You may
well want to change these parameters. See the source code for
jpeg_set_colorspace(), in jcparam.c, for details.
For decompression, the JPEG file's color space is given in jpeg_color_space,
and this is transformed to the output color space out_color_space.
jpeg_read_header's setting of jpeg_color_space can be relied on if the file
conforms to JFIF or Adobe conventions, but otherwise it is no better than a
guess. If you know the JPEG file's color space for certain, you can override
jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also
selects a default output color space based on (its guess of) jpeg_color_space;
set out_color_space to override this. Again, you must select a supported
transformation. jdcolor.c currently supports
YCbCr => RGB
YCbCr => GRAYSCALE
BG_YCC => RGB
BG_YCC => GRAYSCALE
RGB => GRAYSCALE
GRAYSCALE => RGB
YCCK => CMYK
as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an
application can force grayscale JPEGs to look like color JPEGs if it only
wants to handle one case.)
The two-pass color quantizer, jquant2.c, is specialized to handle RGB data
(it weights distances appropriately for RGB colors). You'll need to modify
the code if you want to use it for non-RGB output color spaces. Note that
jquant2.c is used to map to an application-supplied colormap as well as for
the normal two-pass colormap selection process.
CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG
files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect.
This is arguably a bug in Photoshop, but if you need to work with Photoshop
CMYK files, you will have to deal with it in your application. We cannot
"fix" this in the library by inverting the data during the CMYK<=>YCCK
transform, because that would break other applications, notably Ghostscript.
Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK
data in the same inverted-YCCK representation used in bare JPEG files, but
the surrounding PostScript code performs an inversion using the PS image
operator. I am told that Photoshop 3.0 will write uninverted YCCK in
EPS/JPEG files, and will omit the PS-level inversion. (But the data
polarity used in bare JPEG files will not change in 3.0.) In either case,
the JPEG library must not invert the data itself, or else Ghostscript would
read these EPS files incorrectly.
Error handling
--------------
When the default error handler is used, any error detected inside the JPEG
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
( run in 0.596 second using v1.01-cache-2.11-cpan-63c85eba8c4 )