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

[devel] Fix typos and indentation in new material in the documentation.

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2011-05-12 22:18:23 -05:00
parent cb0b29631f
commit 593fc04096
2 changed files with 204 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
libpng-manual.txt
View File

@ -697,11 +697,11 @@ you may need to call png_set_alpha_mode:
png_set_alpha_mode(png_ptr, mode, screen_gamma); png_set_alpha_mode(png_ptr, mode, screen_gamma);
The screen_gamma value is the same as the argument to png_set_gamma, however how The screen_gamma value is the same as the argument to png_set_gamma, however how
it effects the output depends on the mode. png_set_alpha_mode sets the file it affects the output depends on the mode. png_set_alpha_mode() sets the file
gamma default to 1/screen_gamma, so normally you don't need to call gamma default to 1/screen_gamma, so normally you don't need to call
png_set_gamma. If you need different defaults call png_set_gamma before png_set_gamma. If you need different defaults call png_set_gamma() before
png_set_alpha_mode - if you call it after it will override the settings made by png_set_alpha_mode() - if you call it after it will override the settings made
png_set_alpha_mode. by png_set_alpha_mode().
The mode is as follows: The mode is as follows:
@ -721,7 +721,7 @@ The mode is as follows:
to remove the gamma encoding and multiply out the alpha to remove the gamma encoding and multiply out the alpha
channel. See the PNG specification for more detail. It is channel. See the PNG specification for more detail. It is
important to note that when an image with an alpha channel is important to note that when an image with an alpha channel is
scaled linear encoded, pre-multiplied, component values must scaled, linear encoded, pre-multiplied component values must
be used! be used!
The remaining modes assume you don't need to do any further color correction or The remaining modes assume you don't need to do any further color correction or
@ -730,7 +730,7 @@ probably doesn't!)
PNG_ALPHA_STANDARD: The data libpng produces is encoded in the standard way PNG_ALPHA_STANDARD: The data libpng produces is encoded in the standard way
assumed by most correctly written graphics software. assumed by most correctly written graphics software.
The gamma encodiing will be removed by libpng and the The gamma encoding will be removed by libpng and the
linear component values will be pre-multiplied by the linear component values will be pre-multiplied by the
alpha channel. alpha channel.
@ -745,14 +745,14 @@ probably doesn't!)
screen_gamma value is, however, used as a default for screen_gamma value is, however, used as a default for
the file gamma if the PNG file has no gamma information. the file gamma if the PNG file has no gamma information.
If you call png_set_gamma after png_set_alpha_mode you If you call png_set_gamma() after png_set_alpha_mode() you
will override the linear encoding. Instead the will override the linear encoding. Instead the
pre-multiplied pixel values will be gamma encoded but pre-multiplied pixel values will be gamma encoded but
the alpha channel will still be linear. This may the alpha channel will still be linear. This may
actually match the requirements of some broken software, actually match the requirements of some broken software,
but it is unlikely. but it is unlikely.
While linear 8 bit data is often used it has While linear 8-bit data is often used it has
insufficient precision for any image with a reasonable insufficient precision for any image with a reasonable
dynamic range. To avoid problems, and if your software dynamic range. To avoid problems, and if your software
supports it, use png_set_expand_16() to force all supports it, use png_set_expand_16() to force all
@ -772,13 +772,13 @@ probably doesn't!)
In normal compositing, where the alpha channel encodes In normal compositing, where the alpha channel encodes
partial pixel coverage (as opposed to broad area partial pixel coverage (as opposed to broad area
translucency), the inaccuracies of the 8 bit translucency), the inaccuracies of the 8-bit
representation of non-opaque pixels are irrelevant. representation of non-opaque pixels are irrelevant.
You can also try this format if your software is broken; You can also try this format if your software is broken;
it might look better. it might look better.
PNG_ALPHA_BROKEN This is PNG_ALPHA_STANDARD however all component values, PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD however all component values,
including the alpha channel are gamma encoded. This is including the alpha channel are gamma encoded. This is
an appropriate format to try if your software, or more an appropriate format to try if your software, or more
likely hardware, is totally broken: if it performs likely hardware, is totally broken: if it performs
@ -791,35 +791,41 @@ separate from the background, as though it had been cut out of paper and pasted
on afterward. on afterward.
If you don't have to deal with bugs in software or hardware, or if you can fix If you don't have to deal with bugs in software or hardware, or if you can fix
them, there are three recommended ways of using png_set_alpha_mode: them, there are three recommended ways of using png_set_alpha_mode():
png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
screen_gamma);
png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG, screen_gamma);
You can do color correction on the result (libpng does not currently You can do color correction on the result (libpng does not currently
support color correction internally.) When you handle the alpha channel support color correction internally.) When you handle the alpha channel
you need to undo the gamma encoding and multipy out the alpha. you need to undo the gamma encoding and multiply out the alpha.
png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD, screen_gamma); png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
screen_gamma);
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
If you are using the high level interface don't call png_set_expand_16,
If you are using the high level interface don't call png_set_expand_16();
instead pass PNG_TRANSFORM_EXPAND_16 to the interface. instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
With this mode you can't do color corrrection, but you can do arithmetic, With this mode you can't do color correction, but you can do arithmetic,
including composition and scaling, on the data without further processing. including composition and scaling, on the data without further processing.
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMZED, screen_gamma); png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
You can avoid the expansion to 16 bit components with this mode, but you screen_gamma);
You can avoid the expansion to 16-bit components with this mode, but you
lose the ability to scale the image or perform other linear arithmetic. lose the ability to scale the image or perform other linear arithmetic.
All you can do is compose the result onto a matching output. Since this All you can do is compose the result onto a matching output. Since this
mode is libpng specific you also need to write your own composition mode is libpng specific you also need to write your own composition
software. software.
If you don't need, or can't handle, the alpha channel you can call If you don't need, or can't handle, the alpha channel you can call
png_set_background to remove it by compositing against a fixed color. Don't png_set_background() to remove it by compositing against a fixed color. Don't
call png_set_strip_alpha to do this - it will leave spurious pixel values in call png_set_strip_alpha() to do this - it will leave spurious pixel values in
transparent parts of this image. transparent parts of this image.
png_set_background(png_ptr, &background_color, PNG_BACKGROUND_GAMMA_SCREEN, png_set_background(png_ptr, &background_color,
0, 1); PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
The background_color is an RGB or grayscale value according to the data format The background_color is an RGB or grayscale value according to the data format
libpng will produce for you. Because you don't yet know the format of the PNG libpng will produce for you. Because you don't yet know the format of the PNG
@ -864,7 +870,7 @@ you want to do are limited to the following set:
PNG_TRANSFORM_IDENTITY No transformation PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
8 bits 8-bit
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
samples to bytes samples to bytes
@ -1428,7 +1434,7 @@ severe accuracy loss.
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
PNG can have files with 16 bits per channel. If you only can handle PNG can have files with 16 bits per channel. If you only can handle
8 bits per channel, this will strip the pixels down to 8 bit. 8 bits per channel, this will strip the pixels down to 8-bit.
if (bit_depth == 16) if (bit_depth == 16)
png_set_strip_16(png_ptr); png_set_strip_16(png_ptr);
@ -1649,10 +1655,11 @@ to convey this information, however only two combinations are like to be useful:
The second call was described above - my_background is in the format of the The second call was described above - my_background is in the format of the
final, display, output produced by libpng. Because you now know the format of final, display, output produced by libpng. Because you now know the format of
the PNG it is possible to avoid the need to choose either 8 or 16 bit output and the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
to retain palette images (the palette colors will be modified appropriately and output and to retain palette images (the palette colors will be modified
the tRNS chunk removed.) However, if you are doing this, take great care not to appropriately and the tRNS chunk removed.) However, if you are doing this,
ask for transformations without checking first that they apply! take great care not to ask for transformations without checking first that
they apply!
In the first call the background color has the original bit depth and color type In the first call the background color has the original bit depth and color type
of the PNG file. So, for palette images the color is supplied as a palette of the PNG file. So, for palette images the color is supplied as a palette
@ -1727,7 +1734,7 @@ This function can also be used to invert grayscale and gray-alpha images:
color_type == PNG_COLOR_TYPE_GRAY_ALPHA) color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_invert_mono(png_ptr); png_set_invert_mono(png_ptr);
PNG files store 16 bit pixels in network byte order (big-endian, PNG files store 16-bit pixels in network byte order (big-endian,
ie. most significant bits first). This code changes the storage to the ie. most significant bits first). This code changes the storage to the
other way (little-endian, i.e. least significant bits first, the other way (little-endian, i.e. least significant bits first, the
way PCs store them): way PCs store them):
@ -3040,7 +3047,7 @@ is required by PNG.
png_set_shift(png_ptr, &sig_bit); png_set_shift(png_ptr, &sig_bit);
PNG files store 16 bit pixels in network byte order (big-endian, PNG files store 16-bit pixels in network byte order (big-endian,
ie. most significant bits first). This code would be used if they are ie. most significant bits first). This code would be used if they are
supplied the other way (little-endian, i.e. least significant bits supplied the other way (little-endian, i.e. least significant bits
first, the way PCs store them): first, the way PCs store them):
@ -3456,7 +3463,7 @@ the simpler ones to get an idea of how they work. Try to find a similar
transformation to the one you want to add and copy off of it. More details transformation to the one you want to add and copy off of it. More details
can be found in the comments inside the code itself. can be found in the comments inside the code itself.
Configuring for 16 bit platforms Configuring for 16-bit platforms
You will want to look into zconf.h to tell zlib (and thus libpng) that You will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory it cannot allocate more then 64K at a time. Even if you can, the memory

69
libpng.3
View File

@ -1648,11 +1648,11 @@ you may need to call png_set_alpha_mode:
png_set_alpha_mode(png_ptr, mode, screen_gamma); png_set_alpha_mode(png_ptr, mode, screen_gamma);
The screen_gamma value is the same as the argument to png_set_gamma, however how The screen_gamma value is the same as the argument to png_set_gamma, however how
it effects the output depends on the mode. png_set_alpha_mode sets the file it affects the output depends on the mode. png_set_alpha_mode() sets the file
gamma default to 1/screen_gamma, so normally you don't need to call gamma default to 1/screen_gamma, so normally you don't need to call
png_set_gamma. If you need different defaults call png_set_gamma before png_set_gamma. If you need different defaults call png_set_gamma() before
png_set_alpha_mode - if you call it after it will override the settings made by png_set_alpha_mode() - if you call it after it will override the settings made
png_set_alpha_mode. by png_set_alpha_mode().
The mode is as follows: The mode is as follows:
@ -1672,7 +1672,7 @@ The mode is as follows:
to remove the gamma encoding and multiply out the alpha to remove the gamma encoding and multiply out the alpha
channel. See the PNG specification for more detail. It is channel. See the PNG specification for more detail. It is
important to note that when an image with an alpha channel is important to note that when an image with an alpha channel is
scaled linear encoded, pre-multiplied, component values must scaled, linear encoded, pre-multiplied component values must
be used! be used!
The remaining modes assume you don't need to do any further color correction or The remaining modes assume you don't need to do any further color correction or
@ -1681,7 +1681,7 @@ probably doesn't!)
PNG_ALPHA_STANDARD: The data libpng produces is encoded in the standard way PNG_ALPHA_STANDARD: The data libpng produces is encoded in the standard way
assumed by most correctly written graphics software. assumed by most correctly written graphics software.
The gamma encodiing will be removed by libpng and the The gamma encoding will be removed by libpng and the
linear component values will be pre-multiplied by the linear component values will be pre-multiplied by the
alpha channel. alpha channel.
@ -1696,14 +1696,14 @@ probably doesn't!)
screen_gamma value is, however, used as a default for screen_gamma value is, however, used as a default for
the file gamma if the PNG file has no gamma information. the file gamma if the PNG file has no gamma information.
If you call png_set_gamma after png_set_alpha_mode you If you call png_set_gamma() after png_set_alpha_mode() you
will override the linear encoding. Instead the will override the linear encoding. Instead the
pre-multiplied pixel values will be gamma encoded but pre-multiplied pixel values will be gamma encoded but
the alpha channel will still be linear. This may the alpha channel will still be linear. This may
actually match the requirements of some broken software, actually match the requirements of some broken software,
but it is unlikely. but it is unlikely.
While linear 8 bit data is often used it has While linear 8-bit data is often used it has
insufficient precision for any image with a reasonable insufficient precision for any image with a reasonable
dynamic range. To avoid problems, and if your software dynamic range. To avoid problems, and if your software
supports it, use png_set_expand_16() to force all supports it, use png_set_expand_16() to force all
@ -1723,13 +1723,13 @@ probably doesn't!)
In normal compositing, where the alpha channel encodes In normal compositing, where the alpha channel encodes
partial pixel coverage (as opposed to broad area partial pixel coverage (as opposed to broad area
translucency), the inaccuracies of the 8 bit translucency), the inaccuracies of the 8-bit
representation of non-opaque pixels are irrelevant. representation of non-opaque pixels are irrelevant.
You can also try this format if your software is broken; You can also try this format if your software is broken;
it might look better. it might look better.
PNG_ALPHA_BROKEN This is PNG_ALPHA_STANDARD however all component values, PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD however all component values,
including the alpha channel are gamma encoded. This is including the alpha channel are gamma encoded. This is
an appropriate format to try if your software, or more an appropriate format to try if your software, or more
likely hardware, is totally broken: if it performs likely hardware, is totally broken: if it performs
@ -1742,35 +1742,41 @@ separate from the background, as though it had been cut out of paper and pasted
on afterward. on afterward.
If you don't have to deal with bugs in software or hardware, or if you can fix If you don't have to deal with bugs in software or hardware, or if you can fix
them, there are three recommended ways of using png_set_alpha_mode: them, there are three recommended ways of using png_set_alpha_mode():
png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
screen_gamma);
png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG, screen_gamma);
You can do color correction on the result (libpng does not currently You can do color correction on the result (libpng does not currently
support color correction internally.) When you handle the alpha channel support color correction internally.) When you handle the alpha channel
you need to undo the gamma encoding and multipy out the alpha. you need to undo the gamma encoding and multiply out the alpha.
png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD, screen_gamma); png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
screen_gamma);
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
If you are using the high level interface don't call png_set_expand_16,
If you are using the high level interface don't call png_set_expand_16();
instead pass PNG_TRANSFORM_EXPAND_16 to the interface. instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
With this mode you can't do color corrrection, but you can do arithmetic, With this mode you can't do color correction, but you can do arithmetic,
including composition and scaling, on the data without further processing. including composition and scaling, on the data without further processing.
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMZED, screen_gamma); png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
You can avoid the expansion to 16 bit components with this mode, but you screen_gamma);
You can avoid the expansion to 16-bit components with this mode, but you
lose the ability to scale the image or perform other linear arithmetic. lose the ability to scale the image or perform other linear arithmetic.
All you can do is compose the result onto a matching output. Since this All you can do is compose the result onto a matching output. Since this
mode is libpng specific you also need to write your own composition mode is libpng specific you also need to write your own composition
software. software.
If you don't need, or can't handle, the alpha channel you can call If you don't need, or can't handle, the alpha channel you can call
png_set_background to remove it by compositing against a fixed color. Don't png_set_background() to remove it by compositing against a fixed color. Don't
call png_set_strip_alpha to do this - it will leave spurious pixel values in call png_set_strip_alpha() to do this - it will leave spurious pixel values in
transparent parts of this image. transparent parts of this image.
png_set_background(png_ptr, &background_color, PNG_BACKGROUND_GAMMA_SCREEN, png_set_background(png_ptr, &background_color,
0, 1); PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
The background_color is an RGB or grayscale value according to the data format The background_color is an RGB or grayscale value according to the data format
libpng will produce for you. Because you don't yet know the format of the PNG libpng will produce for you. Because you don't yet know the format of the PNG
@ -1815,7 +1821,7 @@ you want to do are limited to the following set:
PNG_TRANSFORM_IDENTITY No transformation PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
8 bits 8-bit
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
samples to bytes samples to bytes
@ -2379,7 +2385,7 @@ severe accuracy loss.
png_set_expand_16(png_ptr); png_set_expand_16(png_ptr);
PNG can have files with 16 bits per channel. If you only can handle PNG can have files with 16 bits per channel. If you only can handle
8 bits per channel, this will strip the pixels down to 8 bit. 8 bits per channel, this will strip the pixels down to 8-bit.
if (bit_depth == 16) if (bit_depth == 16)
png_set_strip_16(png_ptr); png_set_strip_16(png_ptr);
@ -2600,10 +2606,11 @@ to convey this information, however only two combinations are like to be useful:
The second call was described above - my_background is in the format of the The second call was described above - my_background is in the format of the
final, display, output produced by libpng. Because you now know the format of final, display, output produced by libpng. Because you now know the format of
the PNG it is possible to avoid the need to choose either 8 or 16 bit output and the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
to retain palette images (the palette colors will be modified appropriately and output and to retain palette images (the palette colors will be modified
the tRNS chunk removed.) However, if you are doing this, take great care not to appropriately and the tRNS chunk removed.) However, if you are doing this,
ask for transformations without checking first that they apply! take great care not to ask for transformations without checking first that
they apply!
In the first call the background color has the original bit depth and color type In the first call the background color has the original bit depth and color type
of the PNG file. So, for palette images the color is supplied as a palette of the PNG file. So, for palette images the color is supplied as a palette
@ -2678,7 +2685,7 @@ This function can also be used to invert grayscale and gray-alpha images:
color_type == PNG_COLOR_TYPE_GRAY_ALPHA) color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_invert_mono(png_ptr); png_set_invert_mono(png_ptr);
PNG files store 16 bit pixels in network byte order (big-endian, PNG files store 16-bit pixels in network byte order (big-endian,
ie. most significant bits first). This code changes the storage to the ie. most significant bits first). This code changes the storage to the
other way (little-endian, i.e. least significant bits first, the other way (little-endian, i.e. least significant bits first, the
way PCs store them): way PCs store them):
@ -3991,7 +3998,7 @@ is required by PNG.
png_set_shift(png_ptr, &sig_bit); png_set_shift(png_ptr, &sig_bit);
PNG files store 16 bit pixels in network byte order (big-endian, PNG files store 16-bit pixels in network byte order (big-endian,
ie. most significant bits first). This code would be used if they are ie. most significant bits first). This code would be used if they are
supplied the other way (little-endian, i.e. least significant bits supplied the other way (little-endian, i.e. least significant bits
first, the way PCs store them): first, the way PCs store them):
@ -4407,7 +4414,7 @@ the simpler ones to get an idea of how they work. Try to find a similar
transformation to the one you want to add and copy off of it. More details transformation to the one you want to add and copy off of it. More details
can be found in the comments inside the code itself. can be found in the comments inside the code itself.
.SS Configuring for 16 bit platforms .SS Configuring for 16-bit platforms
You will want to look into zconf.h to tell zlib (and thus libpng) that You will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory it cannot allocate more then 64K at a time. Even if you can, the memory