view release on metacpan or  search on metacpan

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

block in each component: that is, each downsampled row must contain a
multiple of block_size valid samples, and there must be a multiple of
block_size 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.
    Furthermore, set cinfo->do_fancy_downsampling to FALSE if you want to use
    real downsampled data.  (It is set TRUE by jpeg_set_defaults().)
  * 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*block_size sample rows of each component.  The passed num_lines
value must be at least max_v_samp_factor*block_size, 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*block_size  samples per row
	cinfo->comp_info[i].height_in_blocks*block_size 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 block_size 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 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.
Furthermore, set cinfo->do_fancy_upsampling = FALSE if you want to get real
downsampled data (it is set TRUE by jpeg_read_header()).
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*block_size 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.txt'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().

Each block in the block arrays contains quantized coefficient values in

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

	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
-----------------------------

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 40 bytes per column for typical sampling ratios (eg, about 25600
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.