LibJPEG library integration API

The libjpeg API wrapper is an RDR-discoverable interface that provides access to the libjpeg library directly. More...

Files
file	libjpegapi.h
	Header file defining the LibJPEG library integration API.
file	libjpegrdr.h
	Functions for registering and deregistering the LibJPEG API instances.

Data Structures
struct	sw_libjpeg_api_20201226
	The LibJPEG API version 20201226. More...

Macros
#define	jpeg_create_compress(cinfo)
	Create a JPEG compression context using the default LibJPEG version and JPEG compression context size. More...
#define	jpeg_create_decompress(cinfo)
	Create a JPEG decompression context using the default LibJPEG version and JPEG decompression context size. More...
#define	jpeg_std_error   libjpeg_api->jpeg_std_error
	Initialize a default error manager. More...
#define	jpeg_CreateDecompress   libjpeg_api->jpeg_CreateDecompress
	Create a LibJPEG decompression context. More...
#define	jpeg_read_header   libjpeg_api->jpeg_read_header
	Read a LibJPEG decompression context. More...
#define	jpeg_start_decompress   libjpeg_api->jpeg_start_decompress
	Start decompression with LibJPEG, freeing working memory. More...
#define	jpeg_read_scanlines   libjpeg_api->jpeg_read_scanlines
	Decompress a number of scanlines. More...
#define	jpeg_finish_decompress   libjpeg_api->jpeg_finish_decompress
	Finish decompression with LibJPEG, freeing working memory. More...
#define	jpeg_destroy_decompress   libjpeg_api->jpeg_destroy_decompress
	Destroy a LibJPEG decompression context, freeing all memory allocations. More...
#define	jpeg_CreateCompress   libjpeg_api->jpeg_CreateCompress
	Create a LibJPEG compression context. More...
#define	jpeg_set_defaults   libjpeg_api->jpeg_set_defaults
	Set the default values of optional LibJPEG compression parameters. More...
#define	jpeg_set_quality   libjpeg_api->jpeg_set_quality
	Set the quality for LibJPEG compression parameters. More...
#define	jpeg_start_compress   libjpeg_api->jpeg_start_compress
	Start compression with LibJPEG. More...
#define	jpeg_write_scanlines   libjpeg_api->jpeg_write_scanlines
	compress a number of scanlines. More...
#define	jpeg_finish_compress   libjpeg_api->jpeg_finish_compress
	Finish compression with LibJPEG, freeing working memory. More...
#define	jpeg_destroy_compress   libjpeg_api->jpeg_destroy_compress
	Destroy a LibJPEG compression context, freeing all memory allocations. More...

Detailed Description

The libjpeg API wrapper is an RDR-discoverable interface that provides access to the libjpeg library directly.

These calls are based on the libjpeg library API, but not all calls in the libjpeg API are exposed through this API.

Discovering LibJPEG

A libjpeg API pointer must be discovered using RDR using class RDR_CLASS_API and type RDR_API_LIBJPEG and assigned to a suitably-named API pointer variable before the API macros are used. The libjpeg API is automatically registered when the Harlequin RIP is started. It is deregistered when the Harlequin RIP is shutdown.

LibJPEG Contexts

LibJPEG uses context structures for compression and decompression. The contexts share common fields for error management, memory management, progress reporting, and client data.

You are responsible for allocating the compression or decompression context object, of type struct jpeg_compress_struct or struct jpeg_decompress_struct respectively. The raw structures are initialized by calling jpeg_create_compress() or jpeg_create_decompress(), and destroyed by calling jpeg_destroy_compress() or jpeg_destroy_decompress(). These structures must have a lifetime at least as long as all of the calls to compress or decompress JPEG data.

Error management

LibJPEG compression and decompression contexts need an error manager pointer initialized before construction.

jpeg_std_error() will set up a default error manager that outputs messages to standard output or standard error, and will exit the process in case of an unrecoverable JPEG error. This is probably not what you want, but you might use it to initialize a default error manager and then override methods. The methods you may 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 context by destroying it.

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 error manager structure is fully documented in the libjpeg.txt file in the LibJPEG source code.

The error manager structure must have a lifetime at least as long as the compression or decompression context that refers to it.

Data sources and sinks

LibJPEG reads data when decompressing using methods from a struct jpeg_source_mgr object referenced from the context's src field. This object is defined in the jpeglib.h header file. It contains a buffer pointer and size that are managed by LibJPEG, and the methods:

init_source(j_decompress_ptr cinfo)

Initialize source. This is called by jpeg_read_header() before any data is actually read. This is often a no-op.

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

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.

term_source(j_decompress_ptr cinfo)

Terminate source is called by jpeg_finish_decompress() after all data has been read. This is often a no-op.

The data source object must have a lifetime as long as the decompression context.

Similarly, when compressing data LibJPEG writes data using methods from a struct jpeg_destination_mgr object referenced from the context's dest field. A data destination manager provides three methods:

init_destination(j_compress_ptr cinfo)

Initialize destination. This is called by jpeg_start_compress() before any data is actually written. It must initialize next_output_byte and free_in_buffer. free_in_buffer must be initialized to a positive value.

empty_output_buffer(j_compress_ptr cinfo)

This is called whenever the buffer has filled (free_in_buffer reaches zero). In typical applications, it should write out the entire buffer (use the saved start address and buffer length; ignore the current state of next_output_byte and free_in_buffer). Then reset the pointer & count to the start of the buffer, and return TRUE indicating that the buffer has been dumped. 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 (see the LibJPEG documentation for this operating mode).

term_destination(j_compress_ptr cinfo)

Terminate destination is 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.

The data destination object must have a lifetime as long as the compression context.

The data sources and sinks are fully documented in the libjpeg.txt file in the LibJPEG source code.

Client data

Both compression and decompression contexts support an arbitrary client data pointer, in the client_data field. This is passed as part of the context to the source or destination data callback functions. You can use this to pass a data pointer through to a set of methods used to access the JPEG data. This pointer may be set up before creating the compression or decompression context.

Reading JPEGs

To decompress a JPEG image with LibJPEG, you should:

• Allocate a struct jpeg_decompress_struct context with a suitable scope and lifetime to encapsulate all of the calls below.
• Initialize an error manager and store it in the decompression context's err field.
• Initialize the decompression context by calling jpeg_create_decompress().
• Set up the source of the compressed data.
• Read the JPEG header using jpeg_read_header() to determine how much data there is to read, and other parameters. Some parameters can be overridden after reading the header.
• Begin decompression by calling jpeg_start_decompress(). After this call, the final output image dimensions, colormap, and other parameters are available in the JPEG decompression context.
• Call jpeg_read_scanlines() for all scanlines you want to read.
• Call jpeg_finish_decompress() to finish decompression and free working memory.
• Destroy the decompression context by calling jpeg_destroy_decompress().

Writing JPEGs

To compress a JPEG image with LibJPEG, you should:

• Allocate a struct jpeg_compress_struct context with a suitable scope and lifetime to encapsulate all of the calls below.
• Initialize an error manager and store it in the compression context's err field.
• Initialize the compression context by calling jpeg_create_compress().
• Set up the destination of the compressed data.
• Set required parameters for compression, including the image size, colorspace, and the number of input components. These parameters are set in the compression context directly.
• Set all of the optional parameters to reasonable values by calling jpeg_set_defaults(). You may then modify optional parameter values (e.g., by calling jpeg_set_quality() to change the quality setting).
• Begin compression by calling jpeg_start_compress().
• Call jpeg_write_scanlines() for all scanlines you want to write.
• Call jpeg_finish_compress() to finish compression and free working memory.
• Destroy the compression context by calling jpeg_destroy_compress().

Macro Definition Documentation

jpeg_create_compress

#define jpeg_create_compress

(

cinfo

)

Value:

    jpeg_CreateCompress((cinfo), JPEG_LIB_VERSION, \
                        (size_t) sizeof(struct jpeg_compress_struct))

Create a JPEG compression context using the default LibJPEG version and JPEG compression context size.

This macro is defined by LibJPEG. It calls the jpeg_CreateCompress() API method using the default LibJPEG version JPEG_LIB_VERSION and the size of the jpeg_compress_struct compression context.

Parameters

[out]

cinfo

A pointer to a struct jpeg_compress_struct compression context.

Note

You must set up the LibJPEG error manager by calling jpeg_std_error() before calling this function.

jpeg_create_decompress

#define jpeg_create_decompress

(

cinfo

)

Value:

    jpeg_CreateDecompress((cinfo), JPEG_LIB_VERSION, \
                          (size_t) sizeof(struct jpeg_decompress_struct))

Create a JPEG decompression context using the default LibJPEG version and JPEG decompression context size.

This macro is defined by LibJPEG. It calls the jpeg_CreateDecompress() API method using the default LibJPEG version JPEG_LIB_VERSION and the size of the jpeg_decompress_struct compression context.

Parameters

[out]

cinfo

A pointer to a struct jpeg_decompress_struct decompression context.

Note

You must set up the LibJPEG error manager by calling jpeg_std_error() before calling this function.

jpeg_CreateCompress

#define jpeg_CreateCompress   libjpeg_api->jpeg_CreateCompress

Create a LibJPEG compression context.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_compress_struct context to initialize. On entry, the err and client_data fields should be initialized. All other fields are reset.
[in]	version	The LibJPEG version number.
[in]	structsize	The size of the structure pointed to by cinfo.

See the jpeglib.h header file and libjpeg.txt file for more information.

The LibJPEG jpeg_create_compress() macro should be used instead of calling this macro.

jpeg_CreateDecompress

#define jpeg_CreateDecompress   libjpeg_api->jpeg_CreateDecompress

Create a LibJPEG decompression context.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_decompress_struct context to initialize. On entry, the err and client_data fields should be initialized. All other fields are reset.
[in]	version	The LibJPEG version number.
[in]	structsize	The size of the structure pointed to by cinfo.

See the jpeglib.h header file and libjpeg.txt file for more information.

The LibJPEG jpeg_create_decompress() macro should be used instead of calling this macro.

jpeg_destroy_compress

#define jpeg_destroy_compress   libjpeg_api->jpeg_destroy_compress

Destroy a LibJPEG compression context, freeing all memory allocations.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_compress_struct context to destroy.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_destroy_decompress

#define jpeg_destroy_decompress   libjpeg_api->jpeg_destroy_decompress

Destroy a LibJPEG decompression context, freeing all memory allocations.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_decompress_struct context to destroy.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_finish_compress

#define jpeg_finish_compress   libjpeg_api->jpeg_finish_compress

Finish compression with LibJPEG, freeing working memory.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_compress_struct context.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_finish_decompress

#define jpeg_finish_decompress   libjpeg_api->jpeg_finish_decompress

Finish decompression with LibJPEG, freeing working memory.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_decompress_struct context.

Returns

Only relevant for decompression suspension. See the full LibJPEG documentation for details.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_read_header

#define jpeg_read_header   libjpeg_api->jpeg_read_header

Read a LibJPEG decompression context.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_decompress_struct context to initialize. On entry, the err and client_data fields should be initialized. All other fields are reset.
[in]	version	The LibJPEG version number.
[in]	structsize	The size of the structure pointed to by cinfo.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_read_scanlines

#define jpeg_read_scanlines   libjpeg_api->jpeg_read_scanlines

Decompress a number of scanlines.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_decompress_struct context.
[out]	scanlines	A pointer to a buffer to store decompressed scanline data in.
[in]	max_lines	The maximum number of lines to read.

Returns

The number of scanlines read.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_set_defaults

#define jpeg_set_defaults   libjpeg_api->jpeg_set_defaults

Set the default values of optional LibJPEG compression parameters.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_compress_struct context.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_set_quality

#define jpeg_set_quality   libjpeg_api->jpeg_set_quality

Set the quality for LibJPEG compression parameters.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_compress_struct context.
[in]	quality	A quality value from 0-100.
[in]	force_baseline	If TRUE, the the quantization table entries are constrained to the range 1-255 for full JPEG baseline compatibility.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_start_compress

#define jpeg_start_compress   libjpeg_api->jpeg_start_compress

Start compression with LibJPEG.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_compress_struct context.
[in]	write_all_tables	Normally TRUE to write a complete JPEG interchange datastream.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_start_decompress

#define jpeg_start_decompress   libjpeg_api->jpeg_start_decompress

Start decompression with LibJPEG, freeing working memory.

Parameters

[in,out]

cinfo

A pointer to a struct jpeg_decompress_struct context.

Returns

Only relevant for decompression suspension. See the full LibJPEG documentation for details.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_std_error

#define jpeg_std_error   libjpeg_api->jpeg_std_error

Initialize a default error manager.

JPEG compression and decompression contexts must have the err field set to point to an error manager structure on initialization. The default error manager outputs messages to standard output or standard error, and will exit the process in case of an unrecoverable JPEG error. This is probably not what you want, but you may wish to initialize and error manager with it and then override methods.

Parameters

[out]

err

The error manager structure to initialize.

Returns

The error structure passed in as err.

See the jpeglib.h header file and libjpeg.txt file for more information.

jpeg_write_scanlines

#define jpeg_write_scanlines   libjpeg_api->jpeg_write_scanlines

compress a number of scanlines.

Parameters

[in,out]	cinfo	A pointer to a struct jpeg_compress_struct context.
[out]	scanlines	A pointer to a buffer containing uncompressed scanline to write.
[in]	num_lines	The maximum number of lines to write.

Returns

The number of scanlines written.

See the jpeglib.h header file and libjpeg.txt file for more information.