Harlequin RIP SDK

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

Files

file  libpngapi.h
 Header file defining the LibPNG interface API.
 
file  libpngrdr.h
 Functions to register and deregister the LibPNG API.
 

Data Structures

struct  sw_libpng_api_20201229
 The LibPNG API version 20201229. More...
 

Macros

#define png_sig_cmp   libpng_api->png_sig_cmp
 Check PNG signature bytes to see if it's a PNG file. More...
 
#define png_set_longjmp_fn   libpng_api->png_set_longjmp_fn
 Set a callback that will be used to catch unrecoverable errors. More...
 
#define png_longjmp   libpng_api->png_longjmp
 Invoke the LibPNG error callback, with an error value . More...
 
#define png_error   libpng_api->png_error
 Invoke a LibPNG error. More...
 
#define png_create_info_struct   libpng_api->png_create_info_struct
 Create a PNG information structure. More...
 
#define png_create_read_struct_2   libpng_api->png_create_read_struct_2
 Create a structure handle for reading a PNG image. More...
 
#define png_destroy_read_struct   libpng_api->png_destroy_read_struct
 Destroy a PNG structure handle and associated information structures. More...
 
#define png_get_IHDR   libpng_api->png_get_IHDR
 Get header information from a PNG image. More...
 
#define png_get_color_type   libpng_api->png_get_color_type
 Get the color type from a PNG image. More...
 
#define png_get_iCCP   libpng_api->png_get_iCCP
 Get the ICC profile information from a PNG image. More...
 
#define png_get_io_ptr   libpng_api->png_get_io_ptr
 Get the reader/writer I/O data pointer. More...
 
#define png_get_pHYs   libpng_api->png_get_pHYs
 Get the image resolution information from a PNG image. More...
 
#define png_get_rowbytes   libpng_api->png_get_rowbytes
 Get the number of bytes to store a transformed row of a PNG image. More...
 
#define png_get_tRNS   libpng_api->png_get_tRNS
 Get the transparency information from a PNG image. More...
 
#define png_get_valid   libpng_api->png_get_valid
 Determine if one or more information chunks are valid. More...
 
#define png_read_image   libpng_api->png_read_image
 Read all of the data in an image. More...
 
#define png_read_info   libpng_api->png_read_info
 Read the information chunks from an image. More...
 
#define png_read_row   libpng_api->png_read_row
 Read one row of data from an image. More...
 
#define png_read_update_info   libpng_api->png_read_update_info
 Update the PNG information structure after setting transformations. More...
 
#define png_set_interlace_handling   libpng_api->png_set_interlace_handling
 Request that LibPNG handles de-interlacing. More...
 
#define png_set_invert_alpha   libpng_api->png_set_invert_alpha
 Request that LibPNG invert opacity to transparency. More...
 
#define png_set_palette_to_rgb   libpng_api->png_set_palette_to_rgb
 Request that LibPNG expands palettized images to RGB. More...
 
#define png_set_read_fn   libpng_api->png_set_read_fn
 Set a callback function and data pointer to read PNG images. More...
 
#define png_set_strip_alpha   libpng_api->png_set_strip_alpha
 Request that LibPNG removes the alpha channel from transformed data. More...
 
#define png_set_swap_alpha   libpng_api->png_set_swap_alpha
 Request that LibPNG swaps the alpha channel in transformed data from RGBA to ARGB or vice-versa. More...
 
#define png_set_tRNS_to_alpha   libpng_api->png_set_tRNS_to_alpha
 Request that LibPNG expands tRNS chunk to a full alpha channel in transformed data. More...
 
#define png_create_write_struct_2   libpng_api->png_create_write_struct_2
 Create a structure handle for writing a PNG image. More...
 
#define png_destroy_write_struct   libpng_api->png_destroy_write_struct
 Destroy a PNG structure handle and associated information structures. More...
 
#define png_write_info   libpng_api->png_write_info
 Write information chunks to a PNG image. More...
 
#define png_write_row   libpng_api->png_write_row
 Write a row of data to a PNG image. More...
 
#define png_write_end   libpng_api->png_write_end
 Finish writing a PNG image, including any information comments. More...
 
#define png_set_write_fn   libpng_api->png_set_write_fn
 Set a callback function and data pointer to write PNG images. More...
 
#define png_set_IHDR   libpng_api->png_set_IHDR
 Set the header information for a PNG image. More...
 
#define png_set_compression_level   libpng_api->png_set_compression_level
 Set the compression level of a PNG image. More...
 
#define png_set_text   libpng_api->png_set_text
 Set a text comment for a PNG image. More...
 

Detailed Description

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

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

Discovering LibPNG

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

Error handling

LibPNG uses the C setjmp() and longjmp() functions to handle errors. If an unrecoverable error happens in LibPNG, the png_longjmp() or png_error() functions will be called. These functions may also be used by functions called from the LibPNG library. png_error() invokes an error reporting function, providing it with a text error string, and then calls png_longjmp(). png_longjmp() invokes a callback function set by the user to invoke longjmp(), jumping to a stack frame that encompasses the PNG processing.

The png_set_longjmp_fn() function is used to prepare LibPNG with a callback function that will invoke longjmp(), returning a buffer that is passed to setjmp(). The png_longjmp() function executes this callback function. On Windows, there is a complication: the setjmp() target buffer must be 16-byte aligned. This in turn means that the PNG handle structure in which the jump buffer is contained must be 16-byte aligned. It is your responsibility to ensure this is the case when preparing to catch errors from LibPNG.

Reading PNGs

The expected sequence of function calls on this API to read a PNG file is:

Writing PNGs

The expected sequence of function calls on this API to write a PNG file is:

Macro Definition Documentation

◆ png_create_info_struct

#define png_create_info_struct   libpng_api->png_create_info_struct

Create a PNG information structure.

Parameters
[in,out]png_ptrA PNG structure handle.
Returns
A pointer to the created information structure, or NULL on failure.

Both reading and writing PNGs need an information structure created. If creating the information structure fails, you should destroy the PNG structure handle and take suitable error actions.

See the LibPNG manual for more information.

◆ png_create_read_struct_2

#define png_create_read_struct_2   libpng_api->png_create_read_struct_2

Create a structure handle for reading a PNG image.

Parameters
[in]user_png_verSet this to PNG_LIBPNG_VER_STRING
[in]error_ptrA client data pointer that can be retrieved by error_fn or warn_fn.
[in]error_fnA function called when an unrecoverable error is encountered.
[in]warn_fnA function called when a warning is encountered.
[in]mem_ptrA client data pointer that can be retrieved by malloc_fn and free_fn.
[in]malloc_fnA function to allocate memory for LibPNG.
[in]free_fnA function to free memory allocated by alloc_fn.
Returns
A PNG structure handle, or NULL on failure.
Note
On Windows, you must align the PNG handle to 16 bytes for png_set_longjmp_fn() and png_longjmp() to work. This can be accomplished by passing malloc_fn and corresponding free_fn that align the returned pointers to a suitable boundary.
Global Graphics recommends using a malloc_fn and free_fn function that allocate from the RIP or Skin's memory pools, such as SwAlloc() and SwFree() for RIP pools, or MemAlloc() and MemFree() for skin pools.

See the LibPNG manual for more information.

◆ png_create_write_struct_2

#define png_create_write_struct_2   libpng_api->png_create_write_struct_2

Create a structure handle for writing a PNG image.

Parameters
[in]user_png_verSet this to PNG_LIBPNG_VER_STRING
[in]error_ptrA client data pointer that can be retrieved by error_fn or warn_fn.
[in]error_fnA function called when an unrecoverable error is encountered.
[in]warn_fnA function called when a warning is encountered.
[in]mem_ptrA client data pointer that can be retrieved by malloc_fn and free_fn.
[in]malloc_fnA function to allocate memory for LibPNG.
[in]free_fnA function to free memory allocated by alloc_fn.
Returns
A PNG structure handle, or NULL on failure.
Note
On Windows, you must align the PNG handle to 16 bytes for png_set_longjmp_fn() and png_longjmp() to work. This can be accomplished by passing malloc_fn and corresponding free_fn that align the returned pointers to a suitable boundary.
Global Graphics recommends using a malloc_fn and free_fn function that allocate from the RIP or Skin's memory pools, such as SwAlloc() and SwFree() for RIP pools, or MemAlloc() and MemFree() for skin pools.

See the LibPNG manual for more information.

◆ png_destroy_read_struct

#define png_destroy_read_struct   libpng_api->png_destroy_read_struct

Destroy a PNG structure handle and associated information structures.

Parameters
[out]png_ptr_ptrA pointer to a PNG structure handle created with png_create_read_struct_2().
[out]info_ptr_ptrA pointer to a PNG information structure handle created with png_create_info_struct().
[out]end_info_ptr_ptrA pointer to a PNG information structure handle, or NULL if no end information structure was created.

See the LibPNG manual for more information.

◆ png_destroy_write_struct

#define png_destroy_write_struct   libpng_api->png_destroy_write_struct

Destroy a PNG structure handle and associated information structures.

Parameters
[out]png_ptr_ptrA pointer to a PNG structure handle created with png_create_write_struct_2().
[out]info_ptr_ptrA pointer to a PNG information structure handle created with png_create_info_struct().
[out]end_info_ptr_ptrA pointer to a PNG information structure handle, or NULL if no end information structure was created.

◆ png_error

#define png_error   libpng_api->png_error

Invoke a LibPNG error.

Parameters
[in,out]png_ptrA PNG structure handle.
[in]error_messageAn error message

This function calls the error function supplied to png_create_read_struct_2() or png_create_write_struct_2(), and then uses png_longjmp() to stop LibPNG processing.

See the LibPNG manual for more information.

◆ png_get_color_type

#define png_get_color_type   libpng_api->png_get_color_type

Get the color type from a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
Returns
The color and alpha channels (PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB, or PNG_COLOR_TYPE_RGB_ALPHA).

This is the same as the color type returned by png_get_IHDR().

See the LibPNG manual for more information.

◆ png_get_iCCP

#define png_get_iCCP   libpng_api->png_get_iCCP

Get the ICC profile information from a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[out]nameA location to store the profile name.
[out]compression_typeAn optional location to store the compression type. The compression type is always PNG_COMPRESSION_TYPE_BASE.
[out]profileA location to store a pointer to the ICC profile data.
[out]proflenA location to store the length of the ICC profile data.
Returns
PNG_INFO_iCCP if a profile was successfully extracted, 0 otherwise.

See the LibPNG manual for more information.

◆ png_get_IHDR

#define png_get_IHDR   libpng_api->png_get_IHDR

Get header information from a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[out]widthA location to store the image width.
[out]heightA location to store the image height.
[out]bit_depthA location to store the image bit depth.
[out]color_typeA location to store the color and alpha channels (PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB, or PNG_COLOR_TYPE_RGB_ALPHA).
[out]interlace_methodA location to store the interlace type (PNG_INTERLACE_NONE or PNG_INTERFACE_ADAM7).
[out]compression_methodA location to store the compression type (PNG_COMPRESSION_TYPE_BASE only).
[out]filter_methodA location to store the filter method (PNG_FILTER_TYPE_BASE only).
Returns
FALSE if there was an error extracting data, TRUE if data was extracted successfully.

See the LibPNG manual for more information.

◆ png_get_io_ptr

#define png_get_io_ptr   libpng_api->png_get_io_ptr

Get the reader/writer I/O data pointer.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
Returns
The I/O data pointer set by calling png_set_read_fn() or png_set_write_fn()

See the LibPNG manual for more information.

◆ png_get_pHYs

#define png_get_pHYs   libpng_api->png_get_pHYs

Get the image resolution information from a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[out]res_xA location to store the X resolution.
[out]res_yA location to store the Y resolution.
[out]unit_typeA location to store the resolution unit (PNG_RESOLUTION_METER for pixels per meter, PNG_RESOLUTION_UNKNOWN for unknown units to set the aspect ratio).
Returns
PNG_INFO_pHYs if resolution data was successfully extracted, 0 otherwise.

See the LibPNG manual for more information.

◆ png_get_rowbytes

#define png_get_rowbytes   libpng_api->png_get_rowbytes

Get the number of bytes to store a transformed row of a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
Returns
The number of bytes to store a row of transformed data.

See the LibPNG manual for more information.

◆ png_get_tRNS

#define png_get_tRNS   libpng_api->png_get_tRNS

Get the transparency information from a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[out]trans_alphaA location to store an array of alpha values for the palette, or store NULL if not a palettized image.
[out]num_transA location to store the number of alpha or color values stored.
[out]trans_colorA location to store an array of gray or color values of the transparent color for non palettized images, or store NULL if a palettized image.
Returns
PNG_INFO_tRNS if transparency data was successfully extracted, 0 otherwise.

See the LibPNG manual for more information.

◆ png_get_valid

#define png_get_valid   libpng_api->png_get_valid

Determine if one or more information chunks are valid.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[in]flagA bitmask of the information chunk IDs to test, e.g., PNG_INFO_tRNS, PNG_INFO_iCCP, PNG_INFO_pHYs, etc.
Returns
A bitmask of the information chunks present in the image. This will be flag if all requested chunks are valid, 0 if none are valid.

See the LibPNG manual for more information.

◆ png_longjmp

#define png_longjmp   libpng_api->png_longjmp

Invoke the LibPNG error callback, with an error value .

Parameters
[in,out]png_ptrA PNG structure handle.
[in]valAn error value to pass to the callback function set by png_set_longjmp_fn().

See the LibPNG manual for more information.

◆ png_read_image

#define png_read_image   libpng_api->png_read_image

Read all of the data in an image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[out]imageAn array of row pointers to store the start location of each transformed image data row. The array should be at least as long as the image height.

The reader function set by png_set_read_fn() will be invoked to read the whole source image. The image data stored in the row pointers is owned by LibPNG.

See the LibPNG manual for more information.

◆ png_read_info

#define png_read_info   libpng_api->png_read_info

Read the information chunks from an image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.

The reader function set by png_set_read_fn() will be invoked to read all of the chunks up to the image data.

See the LibPNG manual for more information.

◆ png_read_row

#define png_read_row   libpng_api->png_read_row

Read one row of data from an image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[out]rowA location to store a single row of transformed image data.
[out]display_rowThis is used when handling interlaced images. It is simpler call png_read_image() to fully transform interlaced images, and to set this to NULL when reading non-interlaced images.

The reader function set by png_set_read_fn() will be invoked to read one row of the image.

See the LibPNG manual for more information.

◆ png_read_update_info

#define png_read_update_info   libpng_api->png_read_update_info

Update the PNG information structure after setting transformations.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.

See the LibPNG manual for more information.

◆ png_set_compression_level

#define png_set_compression_level   libpng_api->png_set_compression_level

Set the compression level of a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]levelThe compression level of the image, from 0 (no compression) to 9. A default compression level of Z_DEFAULT_COMPRESSION is a reasonable compromise between compression speed and size.

See the LibPNG manual for more information.

◆ png_set_IHDR

#define png_set_IHDR   libpng_api->png_set_IHDR

Set the header information for a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[in]widthThe image width.
[in]heightThe image height.
[in]bit_depthThe image bit depth.
[in]color_typeThe color and alpha channels (PNG_COLOR_TYPE_GRAY, PNG_COLOR_TYPE_GRAY_ALPHA, PNG_COLOR_TYPE_PALETTE, PNG_COLOR_TYPE_RGB, or PNG_COLOR_TYPE_RGB_ALPHA).
[in]interlace_methodThe interlace type (PNG_INTERLACE_NONE or PNG_INTERFACE_ADAM7).
[in]compression_methodThe compression type (PNG_COMPRESSION_TYPE_BASE only).
[in]filter_methodThe filter method (PNG_FILTER_TYPE_BASE only).

See the LibPNG manual for more information.

◆ png_set_interlace_handling

#define png_set_interlace_handling   libpng_api->png_set_interlace_handling

Request that LibPNG handles de-interlacing.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
Returns
The number of passes that will be required to de-interlace. If you call png_read_image() to read the image data, you won't need to use this value.

See the LibPNG manual for more information.

◆ png_set_invert_alpha

#define png_set_invert_alpha   libpng_api->png_set_invert_alpha

Request that LibPNG invert opacity to transparency.

Parameters
[in]png_ptrA pointer to a PNG structure handle.

See the LibPNG manual for more information.

◆ png_set_longjmp_fn

#define png_set_longjmp_fn   libpng_api->png_set_longjmp_fn

Set a callback that will be used to catch unrecoverable errors.

Parameters
[in,out]png_ptrA PNG structure handle.
[in]longjmp_fnA callback function that will invoke longjmp().
[in]jmp_buf_sizeThe size of a setjmp()/longjmp() jump buffer, used to verify that the client and LibPNG are using compatible definitions.
Returns
The jump buffer built into png_ptr. This should be immediately passed to setjmp().
Note
On Windows, png_ptr must be 16-byte aligned. It is your responsibility to ensure this is the case, by suitably aligning the allocation used for png_create_read_struct_2() or png_create_write_struct_2().

See the LibPNG manual for more information.

◆ png_set_palette_to_rgb

#define png_set_palette_to_rgb   libpng_api->png_set_palette_to_rgb

Request that LibPNG expands palettized images to RGB.

Parameters
[in]png_ptrA pointer to a PNG structure handle.

See the LibPNG manual for more information.

◆ png_set_read_fn

#define png_set_read_fn   libpng_api->png_set_read_fn

Set a callback function and data pointer to read PNG images.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]io_ptrA client data pointer that can be retrieved in read_data_fn by calling png_get_io_ptr().
[in]read_data_fnA callback function to read PNG source data. The callback function is passed png_ptr, a buffer to read data into, and the number of bytes to read. It may use png_get_io_ptr(png_ptr) to retrieve io_ptr. If the callback function cannot read the number of bytes specified, it should throw an error by calling png_error() or png_longjmp().

See the LibPNG manual for more information.

◆ png_set_strip_alpha

#define png_set_strip_alpha   libpng_api->png_set_strip_alpha

Request that LibPNG removes the alpha channel from transformed data.

Parameters
[in]png_ptrA pointer to a PNG structure handle.

See the LibPNG manual for more information.

◆ png_set_swap_alpha

#define png_set_swap_alpha   libpng_api->png_set_swap_alpha

Request that LibPNG swaps the alpha channel in transformed data from RGBA to ARGB or vice-versa.

Parameters
[in]png_ptrA pointer to a PNG structure handle.

See the LibPNG manual for more information.

◆ png_set_text

#define png_set_text   libpng_api->png_set_text

Set a text comment for a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.
[in]text_ptrAn array of text structures, each containing a compression type, keyword, the text, compressed text length, uncompressed text length, language of the comment, and UTF-8 keyword.
[in]num_textThe number of comments in text_ptr.

See the LibPNG manual for more information.

◆ png_set_tRNS_to_alpha

#define png_set_tRNS_to_alpha   libpng_api->png_set_tRNS_to_alpha

Request that LibPNG expands tRNS chunk to a full alpha channel in transformed data.

Parameters
[in]png_ptrA pointer to a PNG structure handle.

See the LibPNG manual for more information.

◆ png_set_write_fn

#define png_set_write_fn   libpng_api->png_set_write_fn

Set a callback function and data pointer to write PNG images.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]io_ptrA client data pointer that can be retrieved in write_data_fn and output_flush_fn by calling png_get_io_ptr().
[in]write_data_fnA callback function to write PNG output data. The callback function is passed png_ptr, a buffer to write data from, and the number of bytes to write. It may use png_get_io_ptr(png_ptr) to retrieve io_ptr. If the callback function cannot write the number of bytes specified, it should throw an error by calling png_error() or png_longjmp().
[in]output_flush_fnA callback function to flush PNG output data to storage. The callback function is passed png_ptr. It may use png_get_io_ptr(png_ptr) to retrieve io_ptr. If the callback function cannot flush any output data buffered, it should throw an error by calling png_error() or png_longjmp().

See the LibPNG manual for more information.

◆ png_sig_cmp

#define png_sig_cmp   libpng_api->png_sig_cmp

Check PNG signature bytes to see if it's a PNG file.

Parameters
[in]sigBuffer of data containing the PNG file.
[in]startThe start of the signature in sig.
[in]num_to_checkThe number of bytes remaining in the sig buffer after start.
Returns
0 if a PNG signature is present, non-zero if not present.

See the LibPNG manual for more information.

◆ png_write_end

#define png_write_end   libpng_api->png_write_end

Finish writing a PNG image, including any information comments.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.

The writer function set by png_set_write_fn() will be invoked to write all of the chunks up to the image data.

See the LibPNG manual for more information.

◆ png_write_info

#define png_write_info   libpng_api->png_write_info

Write information chunks to a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]info_ptrA pointer to a PNG information structure.

The writer function set by png_set_write_fn() will be invoked to write all of the chunks up to the image data.

See the LibPNG manual for more information.

◆ png_write_row

#define png_write_row   libpng_api->png_write_row

Write a row of data to a PNG image.

Parameters
[in]png_ptrA pointer to a PNG structure handle.
[in]rowA pointer to a row of data to the image.

The writer function set by png_set_write_fn() may be invoked to write image data.

See the LibPNG manual for more information.