libjpeg.doc

game engine, which is useful for everyone who is interested in it. I hope you can enjoy it.

	1/1, or no scaling.  Currently, the only supported scaling ratios
	are 1/1, 1/2, 1/4, and 1/8.  (The library design allows for arbitrary
	scaling ratios but this is not likely to be implemented any time soon.)
	Smaller scaling ratios permit significantly faster decoding since
	fewer pixels need be processed and a simpler IDCT method can be used.

boolean quantize_colors
	If set TRUE, colormapped output will be delivered.  Default is FALSE,
	meaning that full-color output will be delivered.

The next three parameters are relevant only if quantize_colors is TRUE.

int desired_number_of_colors
	Maximum number of colors to use in generating a library-supplied color
	map (the actual number of colors is returned in a different field).
	Default 256.  Ignored when the application supplies its own color map.

boolean two_pass_quantize
	If TRUE, an extra pass over the image is made to select a custom color
	map for the image.  This usually looks a lot better than the one-size-
	fits-all colormap that is used otherwise.  Default is TRUE.  Ignored
	when the application supplies its own color map.

J_DITHER_MODE dither_mode
	Selects color dithering method.  Supported values are:
		JDITHER_NONE	no dithering: fast, very low quality
		JDITHER_ORDERED	ordered dither: moderate speed and quality
		JDITHER_FS	Floyd-Steinberg dither: slow, high quality
	Default is JDITHER_FS.  (At present, ordered dither is implemented
	only in the single-pass, standard-colormap case.  If you ask for
	ordered dither when two_pass_quantize is TRUE or when you supply
	an external color map, you'll get F-S dithering.)

When quantize_colors is TRUE, the target color map is described by the next
two fields.  colormap is set to NULL by jpeg_read_header().  The application
can supply a color map by setting colormap non-NULL and setting
actual_number_of_colors to the map size.  Otherwise, jpeg_start_decompress()
selects a suitable color map and sets these two fields itself.
[Implementation restriction: at present, an externally supplied colormap is
only accepted for 3-component output color spaces.]

JSAMPARRAY colormap
	The color map, represented as a 2-D pixel array of out_color_components
	rows and actual_number_of_colors columns.  Ignored if not quantizing.
	CAUTION: if the JPEG library creates its own colormap, the storage
	pointed to by this field is released by jpeg_finish_decompress().
	Copy the colormap somewhere else first, if you want to save it.

int actual_number_of_colors
	The number of colors in the color map.

Additional decompression parameters that the application may set include:

J_DCT_METHOD dct_method
	Selects the algorithm used for the DCT step.  Choices are the same
	as described above for compression.

boolean do_fancy_upsampling
	If TRUE, do careful upsampling of chroma components.  If FALSE,
	a faster but sloppier method is used.  Default is TRUE.  The visual
	impact of the sloppier method is often very small.

boolean do_block_smoothing
	If TRUE, interblock smoothing is applied in early stages of decoding
	progressive JPEG files; if FALSE, not.  Default is TRUE.  Early
	progression stages look "fuzzy" with smoothing, "blocky" without.
	In any case, block smoothing ceases to be applied after the first few
	AC coefficients are known to full accuracy, so it is relevant only
	when using buffered-image mode for progressive images.

boolean enable_1pass_quant
boolean enable_external_quant
boolean enable_2pass_quant
	These are significant only in buffered-image mode, which is
	described in its own section below.


The output image dimensions are given by the following fields.  These are
computed from the source image dimensions and the decompression parameters
by jpeg_start_decompress().  You can also call jpeg_calc_output_dimensions()
to obtain the values that will result from the current parameter settings.
This can be useful if you are trying to pick a scaling ratio that will get
close to a desired target size.  It's also important if you are using the
JPEG library's memory manager to allocate output buffer space, because you
are supposed to request such buffers *before* jpeg_start_decompress().

JDIMENSION output_width		Actual dimensions of output image.
JDIMENSION output_height
int out_color_components	Number of color components in out_color_space.
int output_components		Number of color components returned.
int rec_outbuf_height		Recommended height of scanline buffer.

When quantizing colors, output_components is 1, indicating a single color map
index per pixel.  Otherwise it equals out_color_components.  The output arrays
are required to be output_width * output_components JSAMPLEs wide.

rec_outbuf_height is the recommended minimum height (in scanlines) of the
buffer passed to jpeg_read_scanlines().  If the buffer is smaller, the
library will still work, but time will be wasted due to unnecessary data
copying.  In high-quality modes, rec_outbuf_height is always 1, but some
faster, lower-quality modes set it to larger values (typically 2 to 4).
If you are going to ask for a high-speed processing mode, you may as well
go to the trouble of honoring rec_outbuf_height so as to avoid data copying.
(An output buffer larger than rec_outbuf_height lines is OK, but won't
provide any material speed improvement over that height.)


Special color spaces
--------------------

The JPEG standard itself is "color blind" and doesn't specify any particular
color space.  It is customary to convert color data to a luminance/chrominance
color space before compressing, since this permits greater compression.  The
existing de-facto JPEG file format standards specify YCbCr or grayscale data
(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe).  For special
applications such as multispectral images, other color spaces can be used,
but it must be understood that such files will be unportable.

The JPEG library can handle the most common colorspace conversions (namely
RGB <=> YCbCr and CMYK <=> YCCK).  It can also deal with data of an unknown
color space, passing it through without conversion.  If you deal extensively
with an unusual color space, you can easily extend the library to understand
additional color spaces and perform appropriate conversions.

For compression, the source data's color space is specified by field
in_color_space.  This is transformed to the JPEG file's color space given
by jpeg_color_space.  jpeg_set_defaults() chooses a reasonable JPEG color
space depending on in_color_space, but you can override this by calling
jpeg_set_colorspace().  Of course you must select a supported transformation.
jccolor.c currently supports the following transformations:
	RGB => YCbCr
	RGB => GRAYSCALE
	YCbCr => GRAYSCALE
	CMYK => YCCK
plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB,
YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN.

The de-facto file format standards (JFIF and Adobe) specify APPn markers that
indicate the color space of the JPEG file.  It is important to ensure that
these are written correctly, or omitted if the JPEG file's color space is not
one of the ones supported by the de-facto 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 => GRAYSCALE
	YCbCr => RGB
	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 i