diff --git a/ANNOUNCE b/ANNOUNCE index fe6203783..109bbd7c1 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -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 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): -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 (subscription required; visit diff --git a/CHANGES b/CHANGES index adb62cb7c..651919ed2 100644 --- a/CHANGES +++ b/CHANGES @@ -5305,7 +5305,10 @@ Version 1.6.18rc03 [July 15, 2015] Version 1.6.18 [July 23, 2015] 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 (subscription required; visit diff --git a/libpng-manual.txt b/libpng-manual.txt index 8a92a16b3..5286a9fcc 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -1,6 +1,6 @@ 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 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: - 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 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: - 1) Declare a 'png_image' structure (see below) on the - stack and memset() it to all zero. + 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 - format and allocate a buffer for the image. + 3) Set the png_image 'format' member to the required sample format. - 4) Call png_image_finish_read to read the image into - your buffer. + 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. +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: @@ -3739,34 +3744,35 @@ To write a PNG file using the simplified API: 2) Initialize the members of the structure that describe 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 - 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 -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: + png_controlp opaque Initialize to NULL, free with png_image_free png_uint_32 version Set to PNG_IMAGE_VERSION png_uint_32 width Image width in pixels (columns) png_uint_32 height Image height in pixels (rows) png_uint_32 format Image format as defined below 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 warning_or_error; 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 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 are multiple warnings, only the first one is recorded. -The upper 30 bits of this value are reserved; the low two bits contain -a two bit code such that a value more than 1 indicates a failure in the API -just called: +The upper 30 bits of the "warning_or_error" value are reserved; the low two +bits contain a two bit code such that a value more than 1 indicates a failure +in the API just called: 0 - no warning or error 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 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 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 value. -When a color-mapped image is used as a result of calling -png_image_read_colormap or png_image_write_colormap the channels are encoded -in the color-map and the descriptions above apply to the color-map entries. -The image data is encoded as small integers, value 0..255, that index the -entries in the color-map. One integer (one byte) is stored for each pixel. +The samples are either contained directly in the image data, between 1 and 8 +bytes per pixel according to the encoding, or are held in a color-map indexed +by bytes in the image data. In the case of a color-map the color-map entries +are individual samples, encoded as above, and the image data has one byte per +pixel to select the relevant sample from the color-map. PNG_FORMAT_* 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 -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 -valid: use the bit flag values below for testing a format returned by the -read APIs, but set formats from the derived values. +A format is built up using single bit flag values. All combinations are +valid. Formats can be built up from the flag values or you can use one of +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 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 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 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 -read or just write; in that case you may see an error at run time. You can -guard against this by checking for the definition of: +read or just write; in that case you may see an error at run time. +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_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale - PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte - PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only + PNG_FORMAT_FLAG_LINEAR 0x04 2-byte channels else 1-byte + PNG_FORMAT_FLAG_COLORMAP 0x08 image data is color-mapped PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB 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 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_GA PNG_FORMAT_FLAG_ALPHA @@ -3864,7 +3878,7 @@ components in the linear format. The components are 16-bit integers in the native byte order for your platform, and there is no provision for swapping the bytes to a different endian condition. - PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR + PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR PNG_FORMAT_LINEAR_Y_ALPHA (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA) PNG_FORMAT_LINEAR_RGB @@ -3873,13 +3887,17 @@ swapping the bytes to a different endian condition. (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR| PNG_FORMAT_FLAG_ALPHA) -Color-mapped formats are obtained by calling png_image_{read,write}_colormap, -as appropriate after setting png_image::format to the format of the color-map -to be read or written. Applications may check the value of -PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The -format of the color-map may be extracted using the following macro. +With color-mapped formats the image data is one byte for each pixel. The byte +is an index into the color-map which is formatted as above. To obtain a +color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP +to one of the above definitions, or you can use one of the definitions below. - 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 @@ -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 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 -for the pixels and will always return 1 after a call to -png_image_{read,write}_colormap. The remaining macros return information -about the rows in the image and the complete image. +for the pixels and will always return 1 for color-mapped formats. The +remaining macros return information about the rows in the image and the +complete image. 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 @@ -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 they can be used in #if tests. -First the information about the samples. - PNG_IMAGE_SAMPLE_CHANNELS(fmt) Returns the total number of channels in a given format: 1..4 PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) 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) 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 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) 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 a fixed number determined by the format so can easily be allocated on the 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 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. PNG_IMAGE_BUFFER_SIZE(image, row_stride) - Returns 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 - macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE - when the image has 2-byte components. + 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. + + 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 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. - PNG_IMAGE_FLAG_COLORMAP == 0x02 - The PNG is color-mapped. If this flag is set png_image_read_colormap - can be used without further loss of image information. If it is not set - png_image_read_colormap will cause significant loss if the image has any + PNG_IMAGE_FLAG_FAST == 0x02 + On write emphasise speed over compression; the resultant PNG file will be + larger but will be produced significantly faster, particular for large + 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 @@ -5262,7 +5310,7 @@ Other rules can be inferred by inspecting the libpng source. 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 an official declaration. diff --git a/libpng.3 b/libpng.3 index e24465c33..305d8c099 100644 --- a/libpng.3 +++ b/libpng.3 @@ -1,4 +1,4 @@ -.TH LIBPNG 3 "July 24, 2015" +.TH LIBPNG 3 "July 25, 2015" .SH NAME libpng \- Portable Network Graphics (PNG) Reference Library 1.6.19beta01 .SH SYNOPSIS @@ -508,7 +508,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng. .SH LIBPNG.TXT 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 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: - 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 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: - 1) Declare a 'png_image' structure (see below) on the - stack and memset() it to all zero. + 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 - format and allocate a buffer for the image. + 3) Set the png_image 'format' member to the required sample format. - 4) Call png_image_finish_read to read the image into - your buffer. + 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. +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: @@ -4247,34 +4252,35 @@ To write a PNG file using the simplified API: 2) Initialize the members of the structure that describe 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 - 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 -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: + png_controlp opaque Initialize to NULL, free with png_image_free png_uint_32 version Set to PNG_IMAGE_VERSION png_uint_32 width Image width in pixels (columns) png_uint_32 height Image height in pixels (rows) png_uint_32 format Image format as defined below 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 warning_or_error; 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 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 are multiple warnings, only the first one is recorded. -The upper 30 bits of this value are reserved; the low two bits contain -a two bit code such that a value more than 1 indicates a failure in the API -just called: +The upper 30 bits of the "warning_or_error" value are reserved; the low two +bits contain a two bit code such that a value more than 1 indicates a failure +in the API just called: 0 - no warning or error 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 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 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 value. -When a color-mapped image is used as a result of calling -png_image_read_colormap or png_image_write_colormap the channels are encoded -in the color-map and the descriptions above apply to the color-map entries. -The image data is encoded as small integers, value 0..255, that index the -entries in the color-map. One integer (one byte) is stored for each pixel. +The samples are either contained directly in the image data, between 1 and 8 +bytes per pixel according to the encoding, or are held in a color-map indexed +by bytes in the image data. In the case of a color-map the color-map entries +are individual samples, encoded as above, and the image data has one byte per +pixel to select the relevant sample from the color-map. PNG_FORMAT_* 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 -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 -valid: use the bit flag values below for testing a format returned by the -read APIs, but set formats from the derived values. +A format is built up using single bit flag values. All combinations are +valid. Formats can be built up from the flag values or you can use one of +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 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 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 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 -read or just write; in that case you may see an error at run time. You can -guard against this by checking for the definition of: +read or just write; in that case you may see an error at run time. +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_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale - PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte - PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only + PNG_FORMAT_FLAG_LINEAR 0x04 2-byte channels else 1-byte + PNG_FORMAT_FLAG_COLORMAP 0x08 image data is color-mapped PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB 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 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_GA PNG_FORMAT_FLAG_ALPHA @@ -4372,7 +4386,7 @@ components in the linear format. The components are 16-bit integers in the native byte order for your platform, and there is no provision for swapping the bytes to a different endian condition. - PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR + PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR PNG_FORMAT_LINEAR_Y_ALPHA (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA) PNG_FORMAT_LINEAR_RGB @@ -4381,13 +4395,17 @@ swapping the bytes to a different endian condition. (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR| PNG_FORMAT_FLAG_ALPHA) -Color-mapped formats are obtained by calling png_image_{read,write}_colormap, -as appropriate after setting png_image::format to the format of the color-map -to be read or written. Applications may check the value of -PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The -format of the color-map may be extracted using the following macro. +With color-mapped formats the image data is one byte for each pixel. The byte +is an index into the color-map which is formatted as above. To obtain a +color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP +to one of the above definitions, or you can use one of the definitions below. - 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 @@ -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 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 -for the pixels and will always return 1 after a call to -png_image_{read,write}_colormap. The remaining macros return information -about the rows in the image and the complete image. +for the pixels and will always return 1 for color-mapped formats. The +remaining macros return information about the rows in the image and the +complete image. 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 @@ -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 they can be used in #if tests. -First the information about the samples. - PNG_IMAGE_SAMPLE_CHANNELS(fmt) Returns the total number of channels in a given format: 1..4 PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) 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) 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 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) 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 a fixed number determined by the format so can easily be allocated on the 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 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. PNG_IMAGE_BUFFER_SIZE(image, row_stride) - Returns 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 - macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE - when the image has 2-byte components. + 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. + + 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 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. - PNG_IMAGE_FLAG_COLORMAP == 0x02 - The PNG is color-mapped. If this flag is set png_image_read_colormap - can be used without further loss of image information. If it is not set - png_image_read_colormap will cause significant loss if the image has any + PNG_IMAGE_FLAG_FAST == 0x02 + On write emphasise speed over compression; the resultant PNG file will be + larger but will be produced significantly faster, particular for large + 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 @@ -5770,7 +5818,7 @@ Other rules can be inferred by inspecting the libpng source. .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 an official declaration. @@ -6091,7 +6139,7 @@ possible without all of you. 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. 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. -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 distributed according to the same disclaimer and license as libpng-1.0.6 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 glennrp at users.sourceforge.net -July 24, 2015 +July 25, 2015 .\" end of man page diff --git a/png.h b/png.h index 99223f37d..ef0894511 100644 --- a/png.h +++ b/png.h @@ -1,7 +1,7 @@ /* 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 * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger) @@ -12,7 +12,7 @@ * Authors and maintainers: * 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.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. * * Note about libpng version numbers: @@ -251,7 +251,7 @@ * * 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 * distributed according to the same disclaimer and license as libpng-1.0.6 * with the following individuals added to the list of Contributing Authors: @@ -360,7 +360,7 @@ * Y2K compliance in libpng: * ========================= * - * July 24, 2015 + * July 25, 2015 * * Since the PNG Development group is an ad-hoc body, we can't make * an official declaration. @@ -430,7 +430,7 @@ /* Version information for png.h - this should match the version in png.c */ #define PNG_LIBPNG_VER_STRING "1.6.19beta01" #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_DLLNUM 16 @@ -2882,7 +2882,7 @@ typedef struct * 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! * - * 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 * 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 @@ -2894,7 +2894,7 @@ typedef struct */ #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_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 */ #ifdef PNG_FORMAT_BGR_SUPPORTED