cheng/libpng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[devel] Added information about "chop_16" to the manual.

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2011-06-15 13:21:01 -05:00
parent ef217b76a3
commit 733b131545
2 changed files with 46 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
libpng-manual.txt
View File

@ -647,12 +647,12 @@ If you intend to display the PNG or to incorporate it in other image data you
need to tell libpng information about your display or drawing surface so that need to tell libpng information about your display or drawing surface so that
libpng can convert the values in the image to match the display. libpng can convert the values in the image to match the display.
From libpng-1.5.3 this information can be set before reading the PNG file From libpng-1.5.4 this information can be set before reading the PNG file
header. In earlier versions png_set_gamma() existed but behaved incorrectly if header. In earlier versions png_set_gamma() existed but behaved incorrectly if
called before the PNG file header had been read and png_set_alpha_mode() did not called before the PNG file header had been read and png_set_alpha_mode() did not
exist. exist.
If you need to support versions prior to libpng-1.5.3 test the version number If you need to support versions prior to libpng-1.5.4 test the version number
and follow the procedures described in the appropriate manual page. and follow the procedures described in the appropriate manual page.
You give libpng the encoding expected by your system expressed as a 'gamma' You give libpng the encoding expected by your system expressed as a 'gamma'
@ -673,7 +673,7 @@ documentation!
Many systems permit the system gamma to be changed via a lookup table in the Many systems permit the system gamma to be changed via a lookup table in the
display driver, a few systems, including older Macs, change the response by display driver, a few systems, including older Macs, change the response by
default. As of 1.5.3 three special values are available to handle common default. As of 1.5.4 three special values are available to handle common
situations: situations:
PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1 PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
@ -844,12 +844,17 @@ color!)
You set the transforms you need later, either as flags to the high level You set the transforms you need later, either as flags to the high level
interface or libpng API calls for the low level interface. For reference the interface or libpng API calls for the low level interface. For reference the
settings required are: settings and API calls required are:
8-bit values: 8-bit values:
PNG_TRANSFORM_STRIP_16 | PNG_EXPAND PNG_TRANSFORM_STRIP_16 | PNG_EXPAND
png_set_expand(png_ptr); png_set_strip_16(png_ptr); png_set_expand(png_ptr); png_set_strip_16(png_ptr);
If you must get exactly the same inaccurate results
produced by default in versions prior to libpng-1.5.4,
use PNG_TRANSFORM_CHOP_16 and png_set_chop_16(png_ptr)
instead.
16-bit values: 16-bit values:
PNG_TRANSFORM_EXPAND_16 PNG_TRANSFORM_EXPAND_16
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
@ -859,9 +864,9 @@ color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
to the list. to the list.
Calling png_set_background before the PNG file header is read will not work Calling png_set_background before the PNG file header is read will not work
prior to libpng-1.5.3. Because the failure may result in unexpected warnings or prior to libpng-1.5.4. Because the failure may result in unexpected warnings or
errors it is therefore much safer to call png_set_background after the head has errors it is therefore much safer to call png_set_background after the head has
been read. Unfortunately this means that prior to libpng-1.5.3 it cannot be been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
used with the high level interface. used with the high level interface.
The high-level read interface The high-level read interface
@ -968,9 +973,9 @@ for use in later transformations. Important information copied in is:
1) The PNG file gamma from the gAMA chunk. This overwrites the default value 1) The PNG file gamma from the gAMA chunk. This overwrites the default value
provided by an earlier call to png_set_gamma or png_set_alpha_mode. provided by an earlier call to png_set_gamma or png_set_alpha_mode.
2) Prior to libpng-1.5.3 the background color from a bKGd chunk. This 2) Prior to libpng-1.5.4 the background color from a bKGd chunk. This
damages the information provided by an earlier call to png_set_background damages the information provided by an earlier call to png_set_background
resulting in expected behavior. Libpng-1.5.3 no longer does this. resulting in expected behavior. Libpng-1.5.4 no longer does this.
3) The number of significant bits in each component value. Libpng uses this to 3) The number of significant bits in each component value. Libpng uses this to
optimize gamma handling by reducing the internal lookup table sizes. optimize gamma handling by reducing the internal lookup table sizes.
@ -1634,7 +1639,7 @@ can be determined.
The png_set_background() function has been described already, it tells libpng to The png_set_background() function has been described already, it tells libpng to
composite images with alpha or simple transparency against the supplied composite images with alpha or simple transparency against the supplied
background color. For compatibility with versions of libpng earlier than background color. For compatibility with versions of libpng earlier than
libpng-1.5.3 it is recommended that you call the function after reading the file libpng-1.5.4 it is recommended that you call the function after reading the file
header, even if you don't want to use the color in a bKGD chunk, if one exists. header, even if you don't want to use the color in a bKGD chunk, if one exists.
If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
@ -1671,7 +1676,7 @@ image_background->gray.
If you didn't call png_set_gamma() before reading the file header, for example If you didn't call png_set_gamma() before reading the file header, for example
if you need your code to remain compatible with older versions of libpng prior if you need your code to remain compatible with older versions of libpng prior
to libpng-1.5.3, this is the place to call it. to libpng-1.5.4, this is the place to call it.
Do not call it if you called png_set_alpha_mode(); doing so will damage the Do not call it if you called png_set_alpha_mode(); doing so will damage the
settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
@ -4090,20 +4095,23 @@ PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0 only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0
will lead to a link failure. will lead to a link failure.
Prior to libpng-1.5.3, the zlib compressor used the same set of parameters Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
when compressing the IDAT data and textual data such as zTXt and iCCP. when compressing the IDAT data and textual data such as zTXt and iCCP.
In libpng-1.5.3 we reinitialized the zlib stream for each type of data. In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
We added five png_set_text_*() functions for setting the parameters to We added five png_set_text_*() functions for setting the parameters to
use with textual data. use with textual data.
Prior to libpng-1.5.3, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
option was off by default, and slightly inaccurate scaling occurred. option was off by default, and slightly inaccurate scaling occurred.
This option can no longer be turned off, and 16-to-8 scaling is always This option can no longer be turned off, and 16-to-8 scaling is always
accurate. This change will result in some different results while accurate. This change will result in some different results while
reading 16-bit images, with none of the pixels being off-by-one any reading 16-bit images, with none of the pixels being off-by-one any
longer (see Clause 13.12 of the PNG specification). longer (see Clause 13.12 of the PNG specification). If you must
have exactly the same inaccurate results that libpng produced by
default previously, then you can use the png_set_chop_16() API instead
of png_set_strip_16().
Prior to libpng-1.5.3, the png_set_user_limits() function could only be Prior to libpng-1.5.4, the png_set_user_limits() function could only be
used to reduce the width and height limits from the value of used to reduce the width and height limits from the value of
PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
that it could be used to override them. Now this function will reduce or that it could be used to override them. Now this function will reduce or

38
libpng.3
View File

@ -1602,12 +1602,12 @@ If you intend to display the PNG or to incorporate it in other image data you
need to tell libpng information about your display or drawing surface so that need to tell libpng information about your display or drawing surface so that
libpng can convert the values in the image to match the display. libpng can convert the values in the image to match the display.
From libpng-1.5.3 this information can be set before reading the PNG file From libpng-1.5.4 this information can be set before reading the PNG file
header. In earlier versions png_set_gamma() existed but behaved incorrectly if header. In earlier versions png_set_gamma() existed but behaved incorrectly if
called before the PNG file header had been read and png_set_alpha_mode() did not called before the PNG file header had been read and png_set_alpha_mode() did not
exist. exist.
If you need to support versions prior to libpng-1.5.3 test the version number If you need to support versions prior to libpng-1.5.4 test the version number
and follow the procedures described in the appropriate manual page. and follow the procedures described in the appropriate manual page.
You give libpng the encoding expected by your system expressed as a 'gamma' You give libpng the encoding expected by your system expressed as a 'gamma'
@ -1628,7 +1628,7 @@ documentation!
Many systems permit the system gamma to be changed via a lookup table in the Many systems permit the system gamma to be changed via a lookup table in the
display driver, a few systems, including older Macs, change the response by display driver, a few systems, including older Macs, change the response by
default. As of 1.5.3 three special values are available to handle common default. As of 1.5.4 three special values are available to handle common
situations: situations:
PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1 PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
@ -1799,12 +1799,17 @@ color!)
You set the transforms you need later, either as flags to the high level You set the transforms you need later, either as flags to the high level
interface or libpng API calls for the low level interface. For reference the interface or libpng API calls for the low level interface. For reference the
settings required are: settings and API calls required are:
8-bit values: 8-bit values:
PNG_TRANSFORM_STRIP_16 | PNG_EXPAND PNG_TRANSFORM_STRIP_16 | PNG_EXPAND
png_set_expand(png_ptr); png_set_strip_16(png_ptr); png_set_expand(png_ptr); png_set_strip_16(png_ptr);
If you must get exactly the same inaccurate results
produced by default in versions prior to libpng-1.5.4,
use PNG_TRANSFORM_CHOP_16 and png_set_chop_16(png_ptr)
instead.
16-bit values: 16-bit values:
PNG_TRANSFORM_EXPAND_16 PNG_TRANSFORM_EXPAND_16
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
@ -1814,9 +1819,9 @@ color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
to the list. to the list.
Calling png_set_background before the PNG file header is read will not work Calling png_set_background before the PNG file header is read will not work
prior to libpng-1.5.3. Because the failure may result in unexpected warnings or prior to libpng-1.5.4. Because the failure may result in unexpected warnings or
errors it is therefore much safer to call png_set_background after the head has errors it is therefore much safer to call png_set_background after the head has
been read. Unfortunately this means that prior to libpng-1.5.3 it cannot be been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
used with the high level interface. used with the high level interface.
.SS The high-level read interface .SS The high-level read interface
@ -1923,9 +1928,9 @@ for use in later transformations. Important information copied in is:
1) The PNG file gamma from the gAMA chunk. This overwrites the default value 1) The PNG file gamma from the gAMA chunk. This overwrites the default value
provided by an earlier call to png_set_gamma or png_set_alpha_mode. provided by an earlier call to png_set_gamma or png_set_alpha_mode.
2) Prior to libpng-1.5.3 the background color from a bKGd chunk. This 2) Prior to libpng-1.5.4 the background color from a bKGd chunk. This
damages the information provided by an earlier call to png_set_background damages the information provided by an earlier call to png_set_background
resulting in expected behavior. Libpng-1.5.3 no longer does this. resulting in expected behavior. Libpng-1.5.4 no longer does this.
3) The number of significant bits in each component value. Libpng uses this to 3) The number of significant bits in each component value. Libpng uses this to
optimize gamma handling by reducing the internal lookup table sizes. optimize gamma handling by reducing the internal lookup table sizes.
@ -2589,7 +2594,7 @@ can be determined.
The png_set_background() function has been described already, it tells libpng to The png_set_background() function has been described already, it tells libpng to
composite images with alpha or simple transparency against the supplied composite images with alpha or simple transparency against the supplied
background color. For compatibility with versions of libpng earlier than background color. For compatibility with versions of libpng earlier than
libpng-1.5.3 it is recommended that you call the function after reading the file libpng-1.5.4 it is recommended that you call the function after reading the file
header, even if you don't want to use the color in a bKGD chunk, if one exists. header, even if you don't want to use the color in a bKGD chunk, if one exists.
If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
@ -2626,7 +2631,7 @@ image_background->gray.
If you didn't call png_set_gamma() before reading the file header, for example If you didn't call png_set_gamma() before reading the file header, for example
if you need your code to remain compatible with older versions of libpng prior if you need your code to remain compatible with older versions of libpng prior
to libpng-1.5.3, this is the place to call it. to libpng-1.5.4, this is the place to call it.
Do not call it if you called png_set_alpha_mode(); doing so will damage the Do not call it if you called png_set_alpha_mode(); doing so will damage the
settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
@ -5045,20 +5050,23 @@ PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0 only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0
will lead to a link failure. will lead to a link failure.
Prior to libpng-1.5.3, the zlib compressor used the same set of parameters Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
when compressing the IDAT data and textual data such as zTXt and iCCP. when compressing the IDAT data and textual data such as zTXt and iCCP.
In libpng-1.5.3 we reinitialized the zlib stream for each type of data. In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
We added five png_set_text_*() functions for setting the parameters to We added five png_set_text_*() functions for setting the parameters to
use with textual data. use with textual data.
Prior to libpng-1.5.3, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
option was off by default, and slightly inaccurate scaling occurred. option was off by default, and slightly inaccurate scaling occurred.
This option can no longer be turned off, and 16-to-8 scaling is always This option can no longer be turned off, and 16-to-8 scaling is always
accurate. This change will result in some different results while accurate. This change will result in some different results while
reading 16-bit images, with none of the pixels being off-by-one any reading 16-bit images, with none of the pixels being off-by-one any
longer (see Clause 13.12 of the PNG specification). longer (see Clause 13.12 of the PNG specification). If you must
have exactly the same inaccurate results that libpng produced by
default previously, then you can use the png_set_chop_16() API instead
of png_set_strip_16().
Prior to libpng-1.5.3, the png_set_user_limits() function could only be Prior to libpng-1.5.4, the png_set_user_limits() function could only be
used to reduce the width and height limits from the value of used to reduce the width and height limits from the value of
PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
that it could be used to override them. Now this function will reduce or that it could be used to override them. Now this function will reduce or