view release on metacpan or  search on metacpan

src/Source/LibPNG/libpng-manual.txt  view on Meta::CPAN

I. Introduction

This file describes how to use and modify the PNG reference library
(known as libpng) for your own use.  In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need.  We assume that libpng is already installed; see the
INSTALL file for instructions on how to configure and install libpng.

For examples of libpng usage, see the files "example.c", "pngtest.c",
and the files in the "contrib" directory, all of which are included in
the libpng distribution.

Libpng was written as a companion to the PNG specification, as a way
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.

The PNG specification (second edition), November 2003, is available as
a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
<http://www.w3.org/TR/2003/REC-PNG-20031110/
The W3C and ISO documents have identical technical content.

The PNG-1.2 specification is available at
<http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
to the PNG specification (second edition) but has some additional material.

The PNG-1.0 specification is available
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.

Some additional chunks are described in the special-purpose public chunks
documents at <http://www.libpng.org/pub/png/documents/>.

Other information
about PNG, and the latest version of libpng, can be found at the PNG home
page, <http://www.libpng.org/pub/png/>.

Most users will not have to modify the library significantly; advanced
users may want to modify it more.  All attempts were made to make it as
complete as possible, while keeping the code easy to understand.
Currently, this library only supports C.  Support for other languages
is being considered.

Libpng has been designed to handle multiple sessions at one time,
to be easily modifiable, to be portable to the vast majority of
machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
to use.  The ultimate goal of libpng is to promote the acceptance of
the PNG file format in whatever way possible.  While there is still
work to be done (see the TODO file), libpng should cover the
majority of the needs of its users.

Libpng uses zlib for its compression and decompression of PNG files.
Further information about zlib, and the latest version of zlib, can
be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
The zlib compression utility is a general purpose utility that is
useful for more than PNG files, and can be used without libpng.
See the documentation delivered with zlib for more details.
You can usually find the source files for the zlib utility wherever you
find the libpng source files.

Libpng is thread safe, provided the threads are using different
instances of the structures.  Each thread should have its own
png_struct and png_info instances, and thus its own image.
Libpng does not protect itself against two threads using the
same instance of a structure.

II. Structures

There are two main structures that are important to libpng, png_struct
and png_info.  Both are internal structures that are no longer exposed
in the libpng interface (as of libpng 1.5.0).

The png_info structure is designed to provide information about the
PNG file.  At one time, the fields of png_info were intended to be
directly accessible to the user.  However, this tended to cause problems
with applications using dynamically loaded libraries, and as a result
a set of interface functions for png_info (the png_get_*() and png_set_*()
functions) was developed, and direct access to the png_info fields was
deprecated..

The png_struct structure is the object used by the library to decode a
single image.  As of 1.5.0 this structure is also not exposed.

Almost all libpng APIs require a pointer to a png_struct as the first argument.
Many (in particular the png_set and png_get APIs) also require a pointer
to png_info as the second argument.  Some application visible macros
defined in png.h designed for basic data access (reading and writing
integers in the PNG format) don't take a png_info pointer, but it's almost
always safe to assume that a (png_struct*) has to be passed to call an API
function.

You can have more than one png_info structure associated with an image,
as illustrated in pngtest.c, one for information valid prior to the
IDAT chunks and another (called "end_info" below) for things after them.

The png.h header file is an invaluable reference for programming with libpng.
And while I'm on the topic, make sure you include the libpng header file:

#include <png.h>

and also (as of libpng-1.5.0) the zlib header file, if you need it:

#include <zlib.h>

Types

The png.h header file defines a number of integral types used by the
APIs.  Most of these are fairly obvious; for example types corresponding
to integers of particular sizes and types for passing color values.

One exception is how non-integral numbers are handled.  For application
convenience most APIs that take such numbers have C (double) arguments;
however, internally PNG, and libpng, use 32 bit signed integers and encode
the value by multiplying by 100,000.  As of libpng 1.5.0 a convenience
macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
which is simply (png_int_32).

All APIs that take (double) arguments also have a matching API that
takes the corresponding fixed point integer arguments.  The fixed point
API has the same name as the floating point one with "_fixed" appended.
The actual range of values permitted in the APIs is frequently less than
the full range of (png_fixed_point) (-21474 to +21474).  When APIs require
a non-negative argument the type is recorded as png_uint_32 above.  Consult
the header file and the text below for more information.

src/Source/LibPNG/libpng-manual.txt  view on Meta::CPAN

    png_get_mmx_rowbytes_threshold()
    png_set_asm_flags()

We replaced all of these functions with simple stubs in libpng-1.2.20,
when the Intel assembler code was removed due to a licensing issue.

These macros are deprecated:

    PNG_READ_TRANSFORMS_NOT_SUPPORTED
    PNG_PROGRESSIVE_READ_NOT_SUPPORTED
    PNG_NO_SEQUENTIAL_READ_SUPPORTED
    PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
    PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
    PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED

They have been replaced, respectively, by:

    PNG_NO_READ_TRANSFORMS
    PNG_NO_PROGRESSIVE_READ
    PNG_NO_SEQUENTIAL_READ
    PNG_NO_WRITE_TRANSFORMS
    PNG_NO_READ_ANCILLARY_CHUNKS
    PNG_NO_WRITE_ANCILLARY_CHUNKS

PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
deprecated since libpng-1.0.16 and libpng-1.2.6.

The function
    png_check_sig(sig, num)
was replaced with
    !png_sig_cmp(sig, 0, num)
It has been deprecated since libpng-0.90.

The function
    png_set_gray_1_2_4_to_8()
which also expands tRNS to alpha was replaced with
    png_set_expand_gray_1_2_4_to_8()
which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.

X.  Changes to Libpng from version 1.0.x/1.2.x to 1.4.x

Private libpng prototypes and macro definitions were moved from
png.h and pngconf.h into a new pngpriv.h header file.

Functions png_set_benign_errors(), png_benign_error(), and
png_chunk_benign_error() were added.

Support for setting the maximum amount of memory that the application
will allocate for reading chunks was added, as a security measure.
The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
were added to the library.

We implemented support for I/O states by adding png_ptr member io_state
and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c

We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
input transforms.

Checking for and reporting of errors in the IHDR chunk is more thorough.

Support for global arrays was removed, to improve thread safety.

Some obsolete/deprecated macros and functions have been removed.

Typecasted NULL definitions such as
   #define png_voidp_NULL            (png_voidp)NULL
were eliminated.  If you used these in your application, just use
NULL instead.

The png_struct and info_struct members "trans" and "trans_values" were
changed to "trans_alpha" and "trans_color", respectively.

The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
were removed.

The PNG_1_0_X and PNG_1_2_X macros were eliminated.

The PNG_LEGACY_SUPPORTED macro was eliminated.

Many WIN32_WCE #ifdefs were removed.

The functions png_read_init(info_ptr), png_write_init(info_ptr),
png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
have been removed.  They have been deprecated since libpng-0.95.

The png_permit_empty_plte() was removed. It has been deprecated
since libpng-1.0.9.  Use png_permit_mng_features() instead.

We removed the obsolete stub functions png_get_mmx_flagmask(),
png_set_mmx_thresholds(), png_get_asm_flags(),
png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
png_set_asm_flags(), and png_mmx_supported()

We removed the obsolete png_check_sig(), png_memcpy_check(), and
png_memset_check() functions.  Instead use !png_sig_cmp(), memcpy(),
and memset(), respectively.

The function png_set_gray_1_2_4_to_8() was removed. It has been
deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
png_set_expand_gray_1_2_4_to_8() because the former function also
expanded any tRNS chunk to an alpha channel.

Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
were added and are used by default instead of the corresponding
functions. Unfortunately,
from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
function) incorrectly returned a value of type png_uint_32.

We changed the prototype for png_malloc() from
    png_malloc(png_structp png_ptr, png_uint_32 size)
to
    png_malloc(png_structp png_ptr, png_alloc_size_t size)

This also applies to the prototype for the user replacement malloc_fn().

The png_calloc() function was added and is used in place of
of "png_malloc(); memset();" except in the case in png_read_png()
where the array consists of pointers; in this case a "for" loop is used
after the png_malloc() to set the pointers to NULL, to give robust.
behavior in case the application runs out of memory part-way through
the process.