[devel] Fix typos and indentation in new material in the documentation.
This commit is contained in:
Glenn Randers-Pehrson
parent
cb0b29631f
commit
593fc04096
@ -697,11 +697,11 @@ you may need to call png_set_alpha_mode:
|
||||
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
|
||||
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
|
||||
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.
|
||||
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().
|
||||
|
||||
The mode is as follows:
|
||||
|
||||
@ -721,7 +721,7 @@ The mode is as follows:
|
||||
to remove the gamma encoding and multiply out the alpha
|
||||
channel. See the PNG specification for more detail. It 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!
|
||||
|
||||
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
|
||||
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
|
||||
alpha channel.
|
||||
|
||||
@ -745,14 +745,14 @@ probably doesn't!)
|
||||
screen_gamma value is, however, used as a default for
|
||||
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
|
||||
pre-multiplied pixel values will be gamma encoded but
|
||||
the alpha channel will still be linear. This may
|
||||
actually match the requirements of some broken software,
|
||||
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
|
||||
dynamic range. To avoid problems, and if your software
|
||||
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
|
||||
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.
|
||||
|
||||
You can also try this format if your software is broken;
|
||||
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
|
||||
an appropriate format to try if your software, or more
|
||||
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.
|
||||
|
||||
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
|
||||
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);
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMZED, screen_gamma);
|
||||
You can avoid the expansion to 16 bit components with this mode, but you
|
||||
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
|
||||
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.
|
||||
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
|
||||
software.
|
||||
|
||||
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
|
||||
call png_set_strip_alpha to do this - it will leave spurious pixel values in
|
||||
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
|
||||
transparent parts of this image.
|
||||
|
||||
png_set_background(png_ptr, &background_color, PNG_BACKGROUND_GAMMA_SCREEN,
|
||||
0, 1);
|
||||
png_set_background(png_ptr, &background_color,
|
||||
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
|
||||
|
||||
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
|
||||
@ -864,7 +870,7 @@ you want to do are limited to the following set:
|
||||
|
||||
PNG_TRANSFORM_IDENTITY No transformation
|
||||
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
|
||||
8 bits
|
||||
8-bit
|
||||
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
|
||||
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
|
||||
samples to bytes
|
||||
@ -1428,7 +1434,7 @@ severe accuracy loss.
|
||||
png_set_expand_16(png_ptr);
|
||||
|
||||
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)
|
||||
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
|
||||
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
|
||||
to retain palette images (the palette colors will be modified appropriately and
|
||||
the tRNS chunk removed.) However, if you are doing this, take great care not to
|
||||
ask for transformations without checking first that they apply!
|
||||
the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
|
||||
output and to retain palette images (the palette colors will be modified
|
||||
appropriately and the tRNS chunk removed.) However, if you are doing this,
|
||||
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
|
||||
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)
|
||||
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
|
||||
other way (little-endian, i.e. least significant bits first, the
|
||||
way PCs store them):
|
||||
@ -3040,7 +3047,7 @@ is required by PNG.
|
||||
|
||||
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
|
||||
supplied the other way (little-endian, i.e. least significant bits
|
||||
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
|
||||
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
|
||||
it cannot allocate more then 64K at a time. Even if you can, the memory
|
||||
|
||||
69
libpng.3
69
libpng.3
@ -1648,11 +1648,11 @@ you may need to call png_set_alpha_mode:
|
||||
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
|
||||
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
|
||||
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.
|
||||
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().
|
||||
|
||||
The mode is as follows:
|
||||
|
||||
@ -1672,7 +1672,7 @@ The mode is as follows:
|
||||
to remove the gamma encoding and multiply out the alpha
|
||||
channel. See the PNG specification for more detail. It 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!
|
||||
|
||||
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
|
||||
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
|
||||
alpha channel.
|
||||
|
||||
@ -1696,14 +1696,14 @@ probably doesn't!)
|
||||
screen_gamma value is, however, used as a default for
|
||||
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
|
||||
pre-multiplied pixel values will be gamma encoded but
|
||||
the alpha channel will still be linear. This may
|
||||
actually match the requirements of some broken software,
|
||||
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
|
||||
dynamic range. To avoid problems, and if your software
|
||||
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
|
||||
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.
|
||||
|
||||
You can also try this format if your software is broken;
|
||||
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
|
||||
an appropriate format to try if your software, or more
|
||||
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.
|
||||
|
||||
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
|
||||
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);
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMZED, screen_gamma);
|
||||
You can avoid the expansion to 16 bit components with this mode, but you
|
||||
png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
|
||||
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.
|
||||
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
|
||||
software.
|
||||
|
||||
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
|
||||
call png_set_strip_alpha to do this - it will leave spurious pixel values in
|
||||
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
|
||||
transparent parts of this image.
|
||||
|
||||
png_set_background(png_ptr, &background_color, PNG_BACKGROUND_GAMMA_SCREEN,
|
||||
0, 1);
|
||||
png_set_background(png_ptr, &background_color,
|
||||
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
|
||||
|
||||
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
|
||||
@ -1815,7 +1821,7 @@ you want to do are limited to the following set:
|
||||
|
||||
PNG_TRANSFORM_IDENTITY No transformation
|
||||
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
|
||||
8 bits
|
||||
8-bit
|
||||
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
|
||||
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
|
||||
samples to bytes
|
||||
@ -2379,7 +2385,7 @@ severe accuracy loss.
|
||||
png_set_expand_16(png_ptr);
|
||||
|
||||
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)
|
||||
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
|
||||
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
|
||||
to retain palette images (the palette colors will be modified appropriately and
|
||||
the tRNS chunk removed.) However, if you are doing this, take great care not to
|
||||
ask for transformations without checking first that they apply!
|
||||
the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
|
||||
output and to retain palette images (the palette colors will be modified
|
||||
appropriately and the tRNS chunk removed.) However, if you are doing this,
|
||||
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
|
||||
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)
|
||||
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
|
||||
other way (little-endian, i.e. least significant bits first, the
|
||||
way PCs store them):
|
||||
@ -3991,7 +3998,7 @@ is required by PNG.
|
||||
|
||||
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
|
||||
supplied the other way (little-endian, i.e. least significant bits
|
||||
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
|
||||
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
|
||||
it cannot allocate more then 64K at a time. Even if you can, the memory
|
||||
|
||||
Loading…
Reference in New Issue
Block a user