view release on metacpan or  search on metacpan

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

	Allocate and initialize a JPEG decompression object
	Specify the source of the compressed data (eg, a file)
	Call jpeg_read_header() to obtain image info
	Set parameters for decompression
	jpeg_start_decompress(...);
	while (scan lines remain to be read)
		jpeg_read_scanlines(...);
	jpeg_finish_decompress(...);
	Release the JPEG decompression object

This is comparable to the compression outline except that reading the
datastream header is a separate step.  This is helpful because information
about the image's size, colorspace, etc is available when the application
selects decompression parameters.  For example, the application can choose an
output scaling ratio that will fit the image into the available screen size.

The decompression library obtains compressed data by calling a data source
manager, which typically will read the data from a file; but other behaviors
can be obtained with a custom source manager.  Decompressed data is delivered
into in-memory buffers passed to jpeg_read_scanlines().

It is possible to abort an incomplete compression or decompression operation
by calling jpeg_abort(); or, if you do not need to retain the JPEG object,
simply release it by calling jpeg_destroy().

JPEG compression and decompression objects are two separate struct types.
However, they share some common fields, and certain routines such as
jpeg_destroy() can work on either type of object.

The JPEG library has no static variables: all state is in the compression
or decompression object.  Therefore it is possible to process multiple
compression and decompression operations concurrently, using multiple JPEG
objects.

Both compression and decompression can be done in an incremental memory-to-
memory fashion, if suitable source/destination managers are used.  See the
section on "I/O suspension" for more details.


BASIC LIBRARY USAGE
===================

Data formats
------------

Before diving into procedural details, it is helpful to understand the
image data format that the JPEG library expects or returns.

The standard input image format is a rectangular array of pixels, with each
pixel having the same number of "component" or "sample" values (color
channels).  You must specify how many components there are and the colorspace
interpretation of the components.  Most applications will use RGB data
(three components per pixel) or grayscale data (one component per pixel).
PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE.
A remarkable number of people manage to miss this, only to find that their
programs don't work with grayscale JPEG files.

There is no provision for colormapped input.  JPEG files are always full-color
or full grayscale (or sometimes another colorspace such as CMYK).  You can
feed in a colormapped image by expanding it to full-color format.  However
JPEG often doesn't work very well with source data that has been colormapped,
because of dithering noise.  This is discussed in more detail in the JPEG FAQ
and the other references mentioned in the README file.

Pixels are stored by scanlines, with each scanline running from left to
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

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

If you need more detailed information about memory usage in a particular
situation, you can enable the MEM_STATS code in jmemmgr.c.


Library compile-time options
----------------------------

A number of compile-time options are available by modifying jmorecfg.h.

The IJG code currently supports 8-bit to 12-bit sample data precision by
defining BITS_IN_JSAMPLE as 8, 9, 10, 11, or 12.
Note that a value larger than 8 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 deeper than 8-bit data
only for PPM and GIF file formats; you must disable the other file formats
to compile a 9-bit to 12-bit cjpeg or djpeg.  (install.txt has more
information about that.)
Run-time selection and conversion of data precision are currently not
supported and may be added later.
Exception:  The transcoding part (jpegtran) supports all settings in a
single instance, since it operates on the level of DCT coefficients and
not sample values.
(If you need to include an 8-bit library and a 9-bit to 12-bit library for
compression or decompression 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 the 9-bit to 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 the standard Huffman tables are only valid for 8-bit data precision.
If you selected more than 8-bit data precision, cjpeg uses arithmetic coding
by default.  The Huffman encoder normally uses entropy optimization to
compute usable tables for higher precision.  Otherwise, you'll have to
supply different default Huffman tables.  You may also want to supply your
own DCT quantization tables; the existing quality-scaling code has been
developed for 8-bit use, and probably doesn't generate especially good tables
for 9-bit to 12-bit.

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.

You can also save a few K by not having text error messages in the library;
the standard error message table occupies about 5Kb.  This is particularly
reasonable for embedded applications where there's no good way to display 
a message anyway.  To do this, remove the creation of the message table
(jpeg_std_message_table[]) from jerror.c, and alter format_message to do
something reasonable without it.  You could output the numeric value of the
message code number, for example.  If you do this, you can also save a couple
more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing;
you don't need trace capability anyway, right?


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 ANSI C, C++, and pre-ANSI C compilers, using any of
the popular system include file setups, and some not-so-popular ones too.
See install.txt 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.txt,
jmorecfg.h, and jinclude.h.


Notes for MS-DOS implementors
-----------------------------