mewin/libpng
1
0
Fork 0
mirror of https://git.code.sf.net/p/libpng/code.git synced 2025-07-10 18:04:09 +02:00
Code Issues Projects Releases Wiki Activity

[libpng16] Updated obsolete information about the simplified API macros in the

Browse Source 
manual pages (Bug report by Arc Riley).
This commit is contained in:
Glenn Randers-Pehrson 2015-07-25 08:01:34 -05:00
parent 476250ebd2
commit e10b7e73db
5 changed files with 256 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ANNOUNCE
View File

@ -1,4 +1,4 @@
Libpng 1.6.19beta01 - July 24, 2015 Libpng 1.6.19beta01 - July 25, 2015
This is not intended to be a public release. It will be replaced This is not intended to be a public release. It will be replaced
within a few weeks by a public version or by another test version. within a few weeks by a public version or by another test version.
@ -25,8 +25,11 @@ Other information:
Changes since the last public release (1.6.18): Changes since the last public release (1.6.18):
Version 1.6.19beta01 [July 24, 2015] Version 1.6.19beta01 [July 25, 2015]
Updated obsolete information about the simplified API macros in the
manual pages (Bug report by Arc Riley).
Avoid potentially dereferencing NULL info_ptr in png_info_init_3().
Send comments/corrections/commendations to png-mng-implement at lists.sf.net Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit (subscription required; visit

5
CHANGES
View File

@ -5305,7 +5305,10 @@ Version 1.6.18rc03 [July 15, 2015]
Version 1.6.18 [July 23, 2015] Version 1.6.18 [July 23, 2015]
No changes. No changes.
Version 1.6.19beta01 [July 24, 2015] Version 1.6.19beta01 [July 25, 2015]
Updated obsolete information about the simplified API macros in the
manual pages (Bug report by Arc Riley).
Avoid potentially dereferencing NULL info_ptr in png_info_init_3().
Send comments/corrections/commendations to png-mng-implement at lists.sf.net Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit (subscription required; visit

186
libpng-manual.txt
View File

@ -1,6 +1,6 @@
libpng-manual.txt - A description on how to use and modify libpng libpng-manual.txt - A description on how to use and modify libpng
libpng version 1.6.19beta01 - July 24, 2015 libpng version 1.6.19beta01 - July 25, 2015
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2015 Glenn Randers-Pehrson Copyright (c) 1998-2015 Glenn Randers-Pehrson
@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.6.19beta01 - July 24, 2015 libpng versions 0.97, January 1998, through 1.6.19beta01 - July 25, 2015
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2015 Glenn Randers-Pehrson Copyright (c) 1998-2015 Glenn Randers-Pehrson
@ -3716,21 +3716,26 @@ as a wide variety of APIs to manipulate ancilliary information.
To read a PNG file using the simplified API: To read a PNG file using the simplified API:
1) Declare a 'png_image' structure (see below) on the 1) Declare a 'png_image' structure (see below) on the stack, set the
stack and memset() it to all zero. 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. 2) Call the appropriate png_image_begin_read... function.
3) Set the png_image 'format' member to the required 3) Set the png_image 'format' member to the required sample format.
format and allocate a buffer for the image.
4) Call png_image_finish_read to read the image into 4) Allocate a buffer for the image and, if required, the color-map.
your buffer.
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 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 color types, bit depths, and interlace methods are acceptable, and the
input image is transformed as necessary to the requested in-memory format input image is transformed as necessary to the requested in-memory format
during the png_image_finish_read() step. 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: To write a PNG file using the simplified API:
@ -3739,34 +3744,35 @@ To write a PNG file using the simplified API:
2) Initialize the members of the structure that describe the 2) Initialize the members of the structure that describe the
image, setting the 'format' member to the format of the image, setting the 'format' member to the format of the
image in memory. image samples.
3) Call the appropriate png_image_write... function with a 3) Call the appropriate png_image_write... function with a
pointer to the image to write the PNG data. 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 png_image is a structure that describes the in-memory format of an image
when it is being read or define the in-memory format of an image that you when it is being read or defines the in-memory format of an image that you
need to write. The "png_image" structure contains the following members: need to write. The "png_image" structure contains the following members:
png_controlp opaque Initialize to NULL, free with png_image_free
png_uint_32 version Set to PNG_IMAGE_VERSION png_uint_32 version Set to PNG_IMAGE_VERSION
png_uint_32 width Image width in pixels (columns) png_uint_32 width Image width in pixels (columns)
png_uint_32 height Image height in pixels (rows) png_uint_32 height Image height in pixels (rows)
png_uint_32 format Image format as defined below png_uint_32 format Image format as defined below
png_uint_32 flags A bit mask containing informational flags png_uint_32 flags A bit mask containing informational flags
png_controlp opaque Initialize to NULL, free with png_image_free
png_uint_32 colormap_entries; Number of entries in the color-map png_uint_32 colormap_entries; Number of entries in the color-map
png_uint_32 warning_or_error; png_uint_32 warning_or_error;
char message[64]; char message[64];
In the event of an error or warning the following field warning_or_error In the event of an error or warning the "warning_or_error"
field will be set to a non-zero value and the 'message' field will contain field will be set to a non-zero value and the 'message' field will contain
a '\0' terminated string with the libpng error or warning message. If both a '\0' terminated string with the libpng error or warning message. If both
warnings and an error were encountered, only the error is recorded. If there warnings and an error were encountered, only the error is recorded. If there
are multiple warnings, only the first one is recorded. are multiple warnings, only the first one is recorded.
The upper 30 bits of this value are reserved; the low two bits contain The upper 30 bits of the "warning_or_error" value are reserved; the low two
a two bit code such that a value more than 1 indicates a failure in the API bits contain a two bit code such that a value more than 1 indicates a failure
just called: in the API just called:
0 - no warning or error 0 - no warning or error
1 - warning 1 - warning
@ -3798,45 +3804,53 @@ channels are linear. Color channels use the RGB encoding (RGB end-points) of
the sRGB specification. This encoding is identified by the the sRGB specification. This encoding is identified by the
PNG_FORMAT_FLAG_LINEAR flag below. PNG_FORMAT_FLAG_LINEAR flag below.
When the simplified API needs to convert between sRGB and linear colorspaces,
the actual sRGB transfer curve defined in the sRGB specification (see the
article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
approximation used elsewhere in libpng.
When an alpha channel is present it is expected to denote pixel coverage When an alpha channel is present it is expected to denote pixel coverage
of the color or luminance channels and is returned as an associated alpha of the color or luminance channels and is returned as an associated alpha
channel: the color/gray channels are scaled (pre-multiplied) by the alpha channel: the color/gray channels are scaled (pre-multiplied) by the alpha
value. value.
When a color-mapped image is used as a result of calling The samples are either contained directly in the image data, between 1 and 8
png_image_read_colormap or png_image_write_colormap the channels are encoded bytes per pixel according to the encoding, or are held in a color-map indexed
in the color-map and the descriptions above apply to the color-map entries. by bytes in the image data. In the case of a color-map the color-map entries
The image data is encoded as small integers, value 0..255, that index the are individual samples, encoded as above, and the image data has one byte per
entries in the color-map. One integer (one byte) is stored for each pixel. pixel to select the relevant sample from the color-map.
PNG_FORMAT_* PNG_FORMAT_*
The #defines to be used in png_image::format. Each #define identifies a The #defines to be used in png_image::format. Each #define identifies a
particular layout of channel data and, if present, alpha values. There are particular layout of channel data and, if present, alpha values. There are
separate defines for each of the two channel encodings. separate defines for each of the two component encodings.
A format is built up using single bit flag values. Not all combinations are A format is built up using single bit flag values. All combinations are
valid: use the bit flag values below for testing a format returned by the valid. Formats can be built up from the flag values or you can use one of
read APIs, but set formats from the derived values. the predefined values below. When testing formats always use the FORMAT_FLAG
macros to test for individual features - future versions of the library may
add new flags.
When reading or writing color-mapped images the format should be set to the When reading or writing color-mapped images the format should be set to the
format of the entries in the color-map then png_image_{read,write}_colormap format of the entries in the color-map then png_image_{read,write}_colormap
called to read or write the color-map and set the format correctly for the called to read or write the color-map and set the format correctly for the
image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly! image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
NOTE: libpng can be built with particular features disabled, if you see NOTE: libpng can be built with particular features disabled. If you see
compiler errors because the definition of one of the following flags has been compiler errors because the definition of one of the following flags has been
compiled out it is because libpng does not have the required support. It is compiled out it is because libpng does not have the required support. It is
possible, however, for the libpng configuration to enable the format on just possible, however, for the libpng configuration to enable the format on just
read or just write; in that case you may see an error at run time. You can read or just write; in that case you may see an error at run time.
guard against this by checking for the definition of: You can guard against this by checking for the definition of the
appropriate "_SUPPORTED" macro, one of:
PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel
PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale
PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte PNG_FORMAT_FLAG_LINEAR 0x04 2-byte channels else 1-byte
PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only PNG_FORMAT_FLAG_COLORMAP 0x08 image data is color-mapped
PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB
PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first
@ -3845,7 +3859,7 @@ formats; for compatibility with older versions simply check if the format
macro is defined using #ifdef. These defines describe the in-memory layout macro is defined using #ifdef. These defines describe the in-memory layout
of the components of the pixels of the image. of the components of the pixels of the image.
First the single byte formats: First the single byte (sRGB) formats:
PNG_FORMAT_GRAY 0 PNG_FORMAT_GRAY 0
PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA
@ -3873,13 +3887,17 @@ swapping the bytes to a different endian condition.
(PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR| (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
PNG_FORMAT_FLAG_ALPHA) PNG_FORMAT_FLAG_ALPHA)
Color-mapped formats are obtained by calling png_image_{read,write}_colormap, With color-mapped formats the image data is one byte for each pixel. The byte
as appropriate after setting png_image::format to the format of the color-map is an index into the color-map which is formatted as above. To obtain a
to be read or written. Applications may check the value of color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP
PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The to one of the above definitions, or you can use one of the definitions below.
format of the color-map may be extracted using the following macro.
PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP) #define PNG_FORMAT_RGB_COLORMAP (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGR_COLORMAP (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_RGBA_COLORMAP (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ARGB_COLORMAP (PNG_FORMAT_ARGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGRA_COLORMAP (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ABGR_COLORMAP (PNG_FORMAT_ABGR|PNG_FORMAT_FLAG_COLORMAP)
PNG_IMAGE macros PNG_IMAGE macros
@ -3887,9 +3905,9 @@ These are convenience macros to derive information from a png_image
structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
actual image sample values - either the entries in the color-map or the actual image sample values - either the entries in the color-map or the
pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values
for the pixels and will always return 1 after a call to for the pixels and will always return 1 for color-mapped formats. The
png_image_{read,write}_colormap. The remaining macros return information remaining macros return information about the rows in the image and the
about the rows in the image and the complete image. complete image.
NOTE: All the macros that take a png_image::format parameter are compile time NOTE: All the macros that take a png_image::format parameter are compile time
constants if the format parameter is, itself, a constant. Therefore these constants if the format parameter is, itself, a constant. Therefore these
@ -3897,42 +3915,37 @@ macros can be used in array declarations and case labels where required.
Similarly the macros are also pre-processor constants (sizeof is not used) so Similarly the macros are also pre-processor constants (sizeof is not used) so
they can be used in #if tests. they can be used in #if tests.
First the information about the samples.
PNG_IMAGE_SAMPLE_CHANNELS(fmt) PNG_IMAGE_SAMPLE_CHANNELS(fmt)
Returns the total number of channels in a given format: 1..4 Returns the total number of channels in a given format: 1..4
PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
Returns the size in bytes of a single component of a pixel or color-map Returns the size in bytes of a single component of a pixel or color-map
entry (as appropriate) in the image. entry (as appropriate) in the image: 1 or 2.
PNG_IMAGE_SAMPLE_SIZE(fmt) PNG_IMAGE_SAMPLE_SIZE(fmt)
This is the size of the sample data for one sample. If the image is This is the size of the sample data for one sample. If the image is
color-mapped it is the size of one color-map entry (and image pixels are color-mapped it is the size of one color-map entry (and image pixels are
one byte in size), otherwise it is the size of one image pixel. one byte in size), otherwise it is the size of one image pixel.
PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)
The maximum size of the color-map required by the format expressed in a
count of components. This can be used to compile-time allocate a
color-map:
png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
information from one of the png_image_begin_read_ APIs and dynamically
allocate the required memory.
PNG_IMAGE_COLORMAP_SIZE(fmt) PNG_IMAGE_COLORMAP_SIZE(fmt)
The size of the color-map required by the format; this is the size of the The size of the color-map required by the format; this is the size of the
color-map buffer passed to the png_image_{read,write}_colormap APIs, it is color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
a fixed number determined by the format so can easily be allocated on the a fixed number determined by the format so can easily be allocated on the
stack if necessary. stack if necessary.
#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
(PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
/* The maximum size of the color-map required by the format expressed in a
* count of components. This can be used to compile-time allocate a
* color-map:
*
* png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
*
* png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
*
* Alternatively, use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
* information from one of the png_image_begin_read_ APIs and dynamically
* allocate the required memory.
*/
Corresponding information about the pixels Corresponding information about the pixels
PNG_IMAGE_PIXEL_(test,fmt) PNG_IMAGE_PIXEL_(test,fmt)
@ -3962,19 +3975,54 @@ Information about the whole row, or whole image
to start the next row on a 4-byte boundary. to start the next row on a 4-byte boundary.
PNG_IMAGE_BUFFER_SIZE(image, row_stride) PNG_IMAGE_BUFFER_SIZE(image, row_stride)
Returns the size, in bytes, of an image buffer given a png_image and a row Return the size, in bytes, of an image buffer given a png_image and a row
stride - the number of components to leave space for in each row. This stride - the number of components to leave space for in each row.
macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE
when the image has 2-byte components. PNG_IMAGE_SIZE(image)
Return the size, in bytes, of the image in memory given just a png_image;
the row stride is the minimum stride required for the image.
PNG_IMAGE_COLORMAP_SIZE(image)
Return the size, in bytes, of the color-map of this image. If the image
format is not a color-map format this will return a size sufficient for
256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
you don't want to allocate a color-map in this case.
PNG_IMAGE_FLAG_*
Flags containing additional information about the image are held in
the 'flags' field of png_image.
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01 PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
This indicates the the RGB values of the in-memory bitmap do not This indicates the the RGB values of the in-memory bitmap do not
correspond to the red, green and blue end-points defined by sRGB. correspond to the red, green and blue end-points defined by sRGB.
PNG_IMAGE_FLAG_COLORMAP == 0x02 PNG_IMAGE_FLAG_FAST == 0x02
The PNG is color-mapped. If this flag is set png_image_read_colormap On write emphasise speed over compression; the resultant PNG file will be
can be used without further loss of image information. If it is not set larger but will be produced significantly faster, particular for large
png_image_read_colormap will cause significant loss if the image has any images. Do not use this option for images which will be distributed, only
used it when producing intermediate files that will be read back in
repeatedly. For a typical 24-bit image the option will double the read
speed at the cost of increasing the image size by 25%, however for many
more compressible images the PNG file can be 10 times larger with only a
slight speed gain.
PNG_IMAGE_FLAG_16BIT_sRGB == 0x04
On read if the image is a 16-bit per component image and there is no gAMA
or sRGB chunk assume that the components are sRGB encoded. Notice that
images output by the simplified API always have gamma information; setting
this flag only affects the interpretation of 16-bit images from an
external source. It is recommended that the application expose this flag
to the user; the user can normally easily recognize the difference between
linear and sRGB encoding. This flag has no effect on write - the data
passed to the write APIs must have the correct encoding (as defined
above.)
If the flag is not set (the default) input 16-bit per component data is
assumed to be linear.
NOTE: the flag can only be set after the png_image_begin_read_ call,
because that call initializes the 'flags' field.
READ APIs READ APIs
@ -5262,7 +5310,7 @@ Other rules can be inferred by inspecting the libpng source.
XVI. Y2K Compliance in libpng XVI. Y2K Compliance in libpng
July 24, 2015 July 25, 2015
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.

194
libpng.3
View File

@ -1,4 +1,4 @@
.TH LIBPNG 3 "July 24, 2015" .TH LIBPNG 3 "July 25, 2015"
.SH NAME .SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.6.19beta01 libpng \- Portable Network Graphics (PNG) Reference Library 1.6.19beta01
.SH SYNOPSIS .SH SYNOPSIS
@ -508,7 +508,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
.SH LIBPNG.TXT .SH LIBPNG.TXT
libpng-manual.txt - A description on how to use and modify libpng libpng-manual.txt - A description on how to use and modify libpng
libpng version 1.6.19beta01 - July 24, 2015 libpng version 1.6.19beta01 - July 25, 2015
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2015 Glenn Randers-Pehrson Copyright (c) 1998-2015 Glenn Randers-Pehrson
@ -519,7 +519,7 @@ libpng-manual.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.6.19beta01 - July 24, 2015 libpng versions 0.97, January 1998, through 1.6.19beta01 - July 25, 2015
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2015 Glenn Randers-Pehrson Copyright (c) 1998-2015 Glenn Randers-Pehrson
@ -4224,21 +4224,26 @@ as a wide variety of APIs to manipulate ancilliary information.
To read a PNG file using the simplified API: To read a PNG file using the simplified API:
1) Declare a 'png_image' structure (see below) on the 1) Declare a 'png_image' structure (see below) on the stack, set the
stack and memset() it to all zero. 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. 2) Call the appropriate png_image_begin_read... function.
3) Set the png_image 'format' member to the required 3) Set the png_image 'format' member to the required sample format.
format and allocate a buffer for the image.
4) Call png_image_finish_read to read the image into 4) Allocate a buffer for the image and, if required, the color-map.
your buffer.
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 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 color types, bit depths, and interlace methods are acceptable, and the
input image is transformed as necessary to the requested in-memory format input image is transformed as necessary to the requested in-memory format
during the png_image_finish_read() step. 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: To write a PNG file using the simplified API:
@ -4247,34 +4252,35 @@ To write a PNG file using the simplified API:
2) Initialize the members of the structure that describe the 2) Initialize the members of the structure that describe the
image, setting the 'format' member to the format of the image, setting the 'format' member to the format of the
image in memory. image samples.
3) Call the appropriate png_image_write... function with a 3) Call the appropriate png_image_write... function with a
pointer to the image to write the PNG data. 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 png_image is a structure that describes the in-memory format of an image
when it is being read or define the in-memory format of an image that you when it is being read or defines the in-memory format of an image that you
need to write. The "png_image" structure contains the following members: need to write. The "png_image" structure contains the following members:
png_controlp opaque Initialize to NULL, free with png_image_free
png_uint_32 version Set to PNG_IMAGE_VERSION png_uint_32 version Set to PNG_IMAGE_VERSION
png_uint_32 width Image width in pixels (columns) png_uint_32 width Image width in pixels (columns)
png_uint_32 height Image height in pixels (rows) png_uint_32 height Image height in pixels (rows)
png_uint_32 format Image format as defined below png_uint_32 format Image format as defined below
png_uint_32 flags A bit mask containing informational flags png_uint_32 flags A bit mask containing informational flags
png_controlp opaque Initialize to NULL, free with png_image_free
png_uint_32 colormap_entries; Number of entries in the color-map png_uint_32 colormap_entries; Number of entries in the color-map
png_uint_32 warning_or_error; png_uint_32 warning_or_error;
char message[64]; char message[64];
In the event of an error or warning the following field warning_or_error In the event of an error or warning the "warning_or_error"
field will be set to a non-zero value and the 'message' field will contain field will be set to a non-zero value and the 'message' field will contain
a '\0' terminated string with the libpng error or warning message. If both a '\0' terminated string with the libpng error or warning message. If both
warnings and an error were encountered, only the error is recorded. If there warnings and an error were encountered, only the error is recorded. If there
are multiple warnings, only the first one is recorded. are multiple warnings, only the first one is recorded.
The upper 30 bits of this value are reserved; the low two bits contain The upper 30 bits of the "warning_or_error" value are reserved; the low two
a two bit code such that a value more than 1 indicates a failure in the API bits contain a two bit code such that a value more than 1 indicates a failure
just called: in the API just called:
0 - no warning or error 0 - no warning or error
1 - warning 1 - warning
@ -4306,45 +4312,53 @@ channels are linear. Color channels use the RGB encoding (RGB end-points) of
the sRGB specification. This encoding is identified by the the sRGB specification. This encoding is identified by the
PNG_FORMAT_FLAG_LINEAR flag below. PNG_FORMAT_FLAG_LINEAR flag below.
When the simplified API needs to convert between sRGB and linear colorspaces,
the actual sRGB transfer curve defined in the sRGB specification (see the
article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
approximation used elsewhere in libpng.
When an alpha channel is present it is expected to denote pixel coverage When an alpha channel is present it is expected to denote pixel coverage
of the color or luminance channels and is returned as an associated alpha of the color or luminance channels and is returned as an associated alpha
channel: the color/gray channels are scaled (pre-multiplied) by the alpha channel: the color/gray channels are scaled (pre-multiplied) by the alpha
value. value.
When a color-mapped image is used as a result of calling The samples are either contained directly in the image data, between 1 and 8
png_image_read_colormap or png_image_write_colormap the channels are encoded bytes per pixel according to the encoding, or are held in a color-map indexed
in the color-map and the descriptions above apply to the color-map entries. by bytes in the image data. In the case of a color-map the color-map entries
The image data is encoded as small integers, value 0..255, that index the are individual samples, encoded as above, and the image data has one byte per
entries in the color-map. One integer (one byte) is stored for each pixel. pixel to select the relevant sample from the color-map.
PNG_FORMAT_* PNG_FORMAT_*
The #defines to be used in png_image::format. Each #define identifies a The #defines to be used in png_image::format. Each #define identifies a
particular layout of channel data and, if present, alpha values. There are particular layout of channel data and, if present, alpha values. There are
separate defines for each of the two channel encodings. separate defines for each of the two component encodings.
A format is built up using single bit flag values. Not all combinations are A format is built up using single bit flag values. All combinations are
valid: use the bit flag values below for testing a format returned by the valid. Formats can be built up from the flag values or you can use one of
read APIs, but set formats from the derived values. the predefined values below. When testing formats always use the FORMAT_FLAG
macros to test for individual features - future versions of the library may
add new flags.
When reading or writing color-mapped images the format should be set to the When reading or writing color-mapped images the format should be set to the
format of the entries in the color-map then png_image_{read,write}_colormap format of the entries in the color-map then png_image_{read,write}_colormap
called to read or write the color-map and set the format correctly for the called to read or write the color-map and set the format correctly for the
image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly! image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
NOTE: libpng can be built with particular features disabled, if you see NOTE: libpng can be built with particular features disabled. If you see
compiler errors because the definition of one of the following flags has been compiler errors because the definition of one of the following flags has been
compiled out it is because libpng does not have the required support. It is compiled out it is because libpng does not have the required support. It is
possible, however, for the libpng configuration to enable the format on just possible, however, for the libpng configuration to enable the format on just
read or just write; in that case you may see an error at run time. You can read or just write; in that case you may see an error at run time.
guard against this by checking for the definition of: You can guard against this by checking for the definition of the
appropriate "_SUPPORTED" macro, one of:
PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel
PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale
PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte PNG_FORMAT_FLAG_LINEAR 0x04 2-byte channels else 1-byte
PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only PNG_FORMAT_FLAG_COLORMAP 0x08 image data is color-mapped
PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB
PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first
@ -4353,7 +4367,7 @@ formats; for compatibility with older versions simply check if the format
macro is defined using #ifdef. These defines describe the in-memory layout macro is defined using #ifdef. These defines describe the in-memory layout
of the components of the pixels of the image. of the components of the pixels of the image.
First the single byte formats: First the single byte (sRGB) formats:
PNG_FORMAT_GRAY 0 PNG_FORMAT_GRAY 0
PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA
@ -4381,13 +4395,17 @@ swapping the bytes to a different endian condition.
(PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR| (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
PNG_FORMAT_FLAG_ALPHA) PNG_FORMAT_FLAG_ALPHA)
Color-mapped formats are obtained by calling png_image_{read,write}_colormap, With color-mapped formats the image data is one byte for each pixel. The byte
as appropriate after setting png_image::format to the format of the color-map is an index into the color-map which is formatted as above. To obtain a
to be read or written. Applications may check the value of color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP
PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The to one of the above definitions, or you can use one of the definitions below.
format of the color-map may be extracted using the following macro.
PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP) #define PNG_FORMAT_RGB_COLORMAP (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGR_COLORMAP (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_RGBA_COLORMAP (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ARGB_COLORMAP (PNG_FORMAT_ARGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGRA_COLORMAP (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ABGR_COLORMAP (PNG_FORMAT_ABGR|PNG_FORMAT_FLAG_COLORMAP)
PNG_IMAGE macros PNG_IMAGE macros
@ -4395,9 +4413,9 @@ These are convenience macros to derive information from a png_image
structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
actual image sample values - either the entries in the color-map or the actual image sample values - either the entries in the color-map or the
pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values
for the pixels and will always return 1 after a call to for the pixels and will always return 1 for color-mapped formats. The
png_image_{read,write}_colormap. The remaining macros return information remaining macros return information about the rows in the image and the
about the rows in the image and the complete image. complete image.
NOTE: All the macros that take a png_image::format parameter are compile time NOTE: All the macros that take a png_image::format parameter are compile time
constants if the format parameter is, itself, a constant. Therefore these constants if the format parameter is, itself, a constant. Therefore these
@ -4405,42 +4423,37 @@ macros can be used in array declarations and case labels where required.
Similarly the macros are also pre-processor constants (sizeof is not used) so Similarly the macros are also pre-processor constants (sizeof is not used) so
they can be used in #if tests. they can be used in #if tests.
First the information about the samples.
PNG_IMAGE_SAMPLE_CHANNELS(fmt) PNG_IMAGE_SAMPLE_CHANNELS(fmt)
Returns the total number of channels in a given format: 1..4 Returns the total number of channels in a given format: 1..4
PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
Returns the size in bytes of a single component of a pixel or color-map Returns the size in bytes of a single component of a pixel or color-map
entry (as appropriate) in the image. entry (as appropriate) in the image: 1 or 2.
PNG_IMAGE_SAMPLE_SIZE(fmt) PNG_IMAGE_SAMPLE_SIZE(fmt)
This is the size of the sample data for one sample. If the image is This is the size of the sample data for one sample. If the image is
color-mapped it is the size of one color-map entry (and image pixels are color-mapped it is the size of one color-map entry (and image pixels are
one byte in size), otherwise it is the size of one image pixel. one byte in size), otherwise it is the size of one image pixel.
PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)
The maximum size of the color-map required by the format expressed in a
count of components. This can be used to compile-time allocate a
color-map:
png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
information from one of the png_image_begin_read_ APIs and dynamically
allocate the required memory.
PNG_IMAGE_COLORMAP_SIZE(fmt) PNG_IMAGE_COLORMAP_SIZE(fmt)
The size of the color-map required by the format; this is the size of the The size of the color-map required by the format; this is the size of the
color-map buffer passed to the png_image_{read,write}_colormap APIs, it is color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
a fixed number determined by the format so can easily be allocated on the a fixed number determined by the format so can easily be allocated on the
stack if necessary. stack if necessary.
#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
(PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
/* The maximum size of the color-map required by the format expressed in a
* count of components. This can be used to compile-time allocate a
* color-map:
*
* png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
*
* png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
*
* Alternatively, use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
* information from one of the png_image_begin_read_ APIs and dynamically
* allocate the required memory.
*/
Corresponding information about the pixels Corresponding information about the pixels
PNG_IMAGE_PIXEL_(test,fmt) PNG_IMAGE_PIXEL_(test,fmt)
@ -4470,19 +4483,54 @@ Information about the whole row, or whole image
to start the next row on a 4-byte boundary. to start the next row on a 4-byte boundary.
PNG_IMAGE_BUFFER_SIZE(image, row_stride) PNG_IMAGE_BUFFER_SIZE(image, row_stride)
Returns the size, in bytes, of an image buffer given a png_image and a row Return the size, in bytes, of an image buffer given a png_image and a row
stride - the number of components to leave space for in each row. This stride - the number of components to leave space for in each row.
macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE
when the image has 2-byte components. PNG_IMAGE_SIZE(image)
Return the size, in bytes, of the image in memory given just a png_image;
the row stride is the minimum stride required for the image.
PNG_IMAGE_COLORMAP_SIZE(image)
Return the size, in bytes, of the color-map of this image. If the image
format is not a color-map format this will return a size sufficient for
256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
you don't want to allocate a color-map in this case.
PNG_IMAGE_FLAG_*
Flags containing additional information about the image are held in
the 'flags' field of png_image.
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01 PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
This indicates the the RGB values of the in-memory bitmap do not This indicates the the RGB values of the in-memory bitmap do not
correspond to the red, green and blue end-points defined by sRGB. correspond to the red, green and blue end-points defined by sRGB.
PNG_IMAGE_FLAG_COLORMAP == 0x02 PNG_IMAGE_FLAG_FAST == 0x02
The PNG is color-mapped. If this flag is set png_image_read_colormap On write emphasise speed over compression; the resultant PNG file will be
can be used without further loss of image information. If it is not set larger but will be produced significantly faster, particular for large
png_image_read_colormap will cause significant loss if the image has any images. Do not use this option for images which will be distributed, only
used it when producing intermediate files that will be read back in
repeatedly. For a typical 24-bit image the option will double the read
speed at the cost of increasing the image size by 25%, however for many
more compressible images the PNG file can be 10 times larger with only a
slight speed gain.
PNG_IMAGE_FLAG_16BIT_sRGB == 0x04
On read if the image is a 16-bit per component image and there is no gAMA
or sRGB chunk assume that the components are sRGB encoded. Notice that
images output by the simplified API always have gamma information; setting
this flag only affects the interpretation of 16-bit images from an
external source. It is recommended that the application expose this flag
to the user; the user can normally easily recognize the difference between
linear and sRGB encoding. This flag has no effect on write - the data
passed to the write APIs must have the correct encoding (as defined
above.)
If the flag is not set (the default) input 16-bit per component data is
assumed to be linear.
NOTE: the flag can only be set after the png_image_begin_read_ call,
because that call initializes the 'flags' field.
READ APIs READ APIs
@ -5770,7 +5818,7 @@ Other rules can be inferred by inspecting the libpng source.
.SH XVI. Y2K Compliance in libpng .SH XVI. Y2K Compliance in libpng
July 24, 2015 July 25, 2015
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.
@ -6091,7 +6139,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation. Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.6.19beta01 - July 24, 2015: Libpng version 1.6.19beta01 - July 25, 2015:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@ -6114,7 +6162,7 @@ this sentence.
This code is released under the libpng license. This code is released under the libpng license.
libpng versions 1.0.7, July 1, 2000, through 1.6.19beta01, July 24, 2015, are libpng versions 1.0.7, July 1, 2000, through 1.6.19beta01, July 25, 2015, are
Copyright (c) 2000-2002, 2004, 2006-2015 Glenn Randers-Pehrson, and are Copyright (c) 2000-2002, 2004, 2006-2015 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.0.6 distributed according to the same disclaimer and license as libpng-1.0.6
with the following individuals added to the list of Contributing Authors: with the following individuals added to the list of Contributing Authors:
@ -6208,7 +6256,7 @@ the additional disclaimers inserted at version 1.0.7.
Glenn Randers-Pehrson Glenn Randers-Pehrson
glennrp at users.sourceforge.net glennrp at users.sourceforge.net
July 24, 2015 July 25, 2015
.\" end of man page .\" end of man page

14
png.h
View File

@ -1,7 +1,7 @@
/* png.h - header file for PNG reference library /* png.h - header file for PNG reference library
* *
* libpng version 1.6.19beta01, July 24, 2015 * libpng version 1.6.19beta01, July 25, 2015
* *
* Copyright (c) 1998-2015 Glenn Randers-Pehrson * Copyright (c) 1998-2015 Glenn Randers-Pehrson
* (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger) * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
@ -12,7 +12,7 @@
* Authors and maintainers: * Authors and maintainers:
* libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat * libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
* libpng versions 0.89, June 1996, through 0.96, May 1997: Andreas Dilger * libpng versions 0.89, June 1996, through 0.96, May 1997: Andreas Dilger
* libpng versions 0.97, January 1998, through 1.6.19beta01, July 24, 2015: Glenn * libpng versions 0.97, January 1998, through 1.6.19beta01, July 25, 2015: Glenn
* See also "Contributing Authors", below. * See also "Contributing Authors", below.
* *
* Note about libpng version numbers: * Note about libpng version numbers:
@ -251,7 +251,7 @@
* *
* This code is released under the libpng license. * This code is released under the libpng license.
* *
* libpng versions 1.0.7, July 1, 2000, through 1.6.19beta01, July 24, 2015, are * libpng versions 1.0.7, July 1, 2000, through 1.6.19beta01, July 25, 2015, are
* Copyright (c) 2000-2002, 2004, 2006-2015 Glenn Randers-Pehrson, and are * Copyright (c) 2000-2002, 2004, 2006-2015 Glenn Randers-Pehrson, and are
* distributed according to the same disclaimer and license as libpng-1.0.6 * distributed according to the same disclaimer and license as libpng-1.0.6
* with the following individuals added to the list of Contributing Authors: * with the following individuals added to the list of Contributing Authors:
@ -360,7 +360,7 @@
* Y2K compliance in libpng: * Y2K compliance in libpng:
* ========================= * =========================
* *
* July 24, 2015 * July 25, 2015
* *
* Since the PNG Development group is an ad-hoc body, we can't make * Since the PNG Development group is an ad-hoc body, we can't make
* an official declaration. * an official declaration.
@ -430,7 +430,7 @@
/* Version information for png.h - this should match the version in png.c */ /* Version information for png.h - this should match the version in png.c */
#define PNG_LIBPNG_VER_STRING "1.6.19beta01" #define PNG_LIBPNG_VER_STRING "1.6.19beta01"
#define PNG_HEADER_VERSION_STRING \ #define PNG_HEADER_VERSION_STRING \
" libpng version 1.6.19beta01 - July 24, 2015\n" " libpng version 1.6.19beta01 - July 25, 2015\n"
#define PNG_LIBPNG_VER_SONUM 16 #define PNG_LIBPNG_VER_SONUM 16
#define PNG_LIBPNG_VER_DLLNUM 16 #define PNG_LIBPNG_VER_DLLNUM 16
@ -2882,7 +2882,7 @@ typedef struct
* called to read or write the color-map and set the format correctly for the * called to read or write the color-map and set the format correctly for the
* image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly! * image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
* *
* NOTE: libpng can be built with particular features disabled, if you see * NOTE: libpng can be built with particular features disabled. If you see
* compiler errors because the definition of one of the following flags has been * compiler errors because the definition of one of the following flags has been
* compiled out it is because libpng does not have the required support. It is * compiled out it is because libpng does not have the required support. It is
* possible, however, for the libpng configuration to enable the format on just * possible, however, for the libpng configuration to enable the format on just
@ -2894,7 +2894,7 @@ typedef struct
*/ */
#define PNG_FORMAT_FLAG_ALPHA 0x01U /* format with an alpha channel */ #define PNG_FORMAT_FLAG_ALPHA 0x01U /* format with an alpha channel */
#define PNG_FORMAT_FLAG_COLOR 0x02U /* color format: otherwise grayscale */ #define PNG_FORMAT_FLAG_COLOR 0x02U /* color format: otherwise grayscale */
#define PNG_FORMAT_FLAG_LINEAR 0x04U /* 2 byte channels else 1 byte */ #define PNG_FORMAT_FLAG_LINEAR 0x04U /* 2-byte channels else 1-byte */
#define PNG_FORMAT_FLAG_COLORMAP 0x08U /* image data is color-mapped */ #define PNG_FORMAT_FLAG_COLORMAP 0x08U /* image data is color-mapped */
#ifdef PNG_FORMAT_BGR_SUPPORTED #ifdef PNG_FORMAT_BGR_SUPPORTED