Section 5: SIMPLIFIED API
******************************************************************************
Please read the documentation in libpng-manual.txt (TODO: write said
documentation) if you don't understand what follows.
The simplified API hides the details of both libpng and the PNG file format
itself. It allows PNG files to be read into a very limited number of
in-memory bitmap formats or to be written from the same formats. If these
formats do not accommodate your needs then you can, and should, use the more
sophisticated APIs above - these support a wide variety of in-memory formats
and a wide variety of sophisticated transformations to those formats as well
as a wide variety of APIs to manipulate ancillary information.
To read a PNG file using the simplified API:
1) Declare a 'png_image' structure (see below) on the stack, set the
version field to PNG_IMAGE_VERSION and the 'opaque' pointer to NULL
(this is REQUIRED, your program may crash if you don't do it.)
2) Call the appropriate png_image_begin_read... function.
3) Set the png_image 'format' member to the required sample format.
4) Allocate a buffer for the image and, if required, the color-map.
5) Call png_image_finish_read to read the image and, if required, the
color-map into your buffers.
There are no restrictions on the format of the PNG input itself; all valid
color types, bit depths, and interlace methods are acceptable, and the
input image is transformed as necessary to the requested in-memory format
during the png_image_finish_read() step. The only caveat is that if you
request a color-mapped image from a PNG that is full-color or makes
complex use of an alpha channel the transformation is extremely lossy and the
result may look terrible.
To write a PNG file using the simplified API:
1) Declare a 'png_image' structure on the stack and memset() it to all zero.
2) Initialize the members of the structure that describe the image, setting
the 'format' member to the format of the image samples.
3) Call the appropriate png_image_write... function with a pointer to the
image and, if necessary, the color-map to write the PNG data.
png_image is a structure that describes the in-memory format of an image
when it is being read or defines the in-memory format of an image that you
need to write:
Section 5: SIMPLIFIED API ******************************************************************************
Please read the documentation in libpng-manual.txt (TODO: write said documentation) if you don't understand what follows.
The simplified API hides the details of both libpng and the PNG file format itself. It allows PNG files to be read into a very limited number of in-memory bitmap formats or to be written from the same formats. If these formats do not accommodate your needs then you can, and should, use the more sophisticated APIs above - these support a wide variety of in-memory formats and a wide variety of sophisticated transformations to those formats as well as a wide variety of APIs to manipulate ancillary information.
To read a PNG file using the simplified API:
1) Declare a 'png_image' structure (see below) on the stack, set the version field to PNG_IMAGE_VERSION and the 'opaque' pointer to NULL (this is REQUIRED, your program may crash if you don't do it.) 2) Call the appropriate png_image_begin_read... function. 3) Set the png_image 'format' member to the required sample format. 4) Allocate a buffer for the image and, if required, the color-map. 5) Call png_image_finish_read to read the image and, if required, the color-map into your buffers.
There are no restrictions on the format of the PNG input itself; all valid color types, bit depths, and interlace methods are acceptable, and the input image is transformed as necessary to the requested in-memory format during the png_image_finish_read() step. The only caveat is that if you request a color-mapped image from a PNG that is full-color or makes complex use of an alpha channel the transformation is extremely lossy and the result may look terrible.
To write a PNG file using the simplified API:
1) Declare a 'png_image' structure on the stack and memset() it to all zero. 2) Initialize the members of the structure that describe the image, setting the 'format' member to the format of the image samples. 3) Call the appropriate png_image_write... function with a pointer to the image and, if necessary, the color-map to write the PNG data.
png_image is a structure that describes the in-memory format of an image when it is being read or defines the in-memory format of an image that you need to write: