Alien-FreeImage
view release on metacpan or search on metacpan
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
The inverse of the value is always used to provide a default for the PNG file
encoding if it has no gAMA chunk and if png_set_gamma() has not been called
to override the PNG gamma information.
When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode
opaque pixels however pixels with lower alpha values are not encoded,
regardless of the output gamma setting.
When the standard Porter Duff handling is requested with mode 1 the output
encoding is set to be linear and the output_gamma value is only relevant
as a default for input data that has no gamma information. The linear output
encoding will be overridden if png_set_gamma() is called - the results may be
highly unexpected!
The following numbers are derived from the sRGB standard and the research
behind it. sRGB is defined to be approximated by a PNG gAMA chunk value of
0.45455 (1/2.2) for PNG. The value implicitly includes any viewing
correction required to take account of any differences in the color
environment of the original scene and the intended display environment; the
value expresses how to *decode* the image for display, not how the original
data was *encoded*.
sRGB provides a peg for the PNG standard by defining a viewing environment.
sRGB itself, and earlier TV standards, actually use a more complex transform
(a linear portion then a gamma 2.4 power law) than PNG can express. (PNG is
limited to simple power laws.) By saying that an image for direct display on
an sRGB conformant system should be stored with a gAMA chunk value of 45455
(11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification
makes it possible to derive values for other display systems and
environments.
The Mac value is deduced from the sRGB based on an assumption that the actual
extra viewing correction used in early Mac display systems was implemented as
a power 1.45 lookup table.
Any system where a programmable lookup table is used or where the behavior of
the final display device characteristics can be changed requires system
specific code to obtain the current characteristic. However this can be
difficult and most PNG gamma correction only requires an approximate value.
By default, if png_set_alpha_mode() is not called, libpng assumes that all
values are unencoded, linear, values and that the output device also has a
linear characteristic. This is only very rarely correct - it is invariably
better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the
default if you don't know what the right answer is!
The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS
10.6) which used a correction table to implement a somewhat lower gamma on an
otherwise sRGB system.
Both these values are reserved (not simple gamma values) in order to allow
more precise correction internally in the future.
NOTE: the values can be passed to either the fixed or floating
point APIs, but the floating point API will also accept floating point
values.
The second thing you may need to tell libpng about is how your system handles
alpha channel information. Some, but not all, PNG files contain an alpha
channel. To display these files correctly you need to compose the data onto a
suitable background, as described in the PNG specification.
Libpng only supports composing onto a single color (using png_set_background;
see below). Otherwise you must do the composition yourself and, in this case,
you may need to call png_set_alpha_mode:
#if PNG_LIBPNG_VER >= 10504
png_set_alpha_mode(png_ptr, mode, screen_gamma);
#else
png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
#endif
The screen_gamma value is the same as the argument to png_set_gamma; however,
how 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().
The mode is as follows:
PNG_ALPHA_PNG: The data is encoded according to the PNG
specification. Red, green and blue, or gray, components are
gamma encoded color values and are not premultiplied by the
alpha value. The alpha value is a linear measure of the
contribution of the pixel to the corresponding final output pixel.
You should normally use this format if you intend to perform
color correction on the color values; most, maybe all, color
correction software has no handling for the alpha channel and,
anyway, the math to handle pre-multiplied component values is
unnecessarily complex.
Before you do any arithmetic on the component values you need
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
be used!
The remaining modes assume you don't need to do any further color correction or
that if you do, your color correction software knows all about alpha (it
probably doesn't!). They 'associate' the alpha with the color information by
storing color channel values that have been scaled by the alpha. The
advantage is that the color channels can be resampled (the image can be
scaled) in this form. The disadvantage is that normal practice is to store
linear, not (gamma) encoded, values and this requires 16-bit channels for
still images rather than the 8-bit channels that are just about sufficient if
gamma encoding is used. In addition all non-transparent pixel values,
including completely opaque ones, must be gamma encoded to produce the final
image. These are the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' modes
described below (the latter being the two common names for associated alpha
color channels). Note that PNG files always contain non-associated color
channels; png_set_alpha_mode() with one of the modes causes the decoder to
convert the pixels to an associated form before returning them to your
application.
Since it is not necessary to perform arithmetic on opaque color values so
long as they are not to be resampled and are in the final color space it is
possible to optimize the handling of alpha by storing the opaque pixels in
the PNG format (adjusted for the output color space) while storing partially
opaque pixels in the standard, linear, format. The accuracy required for
standard alpha composition is relatively low, because the pixels are
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
treated as opaque only if the alpha value is equal to the maximum value.
PNG_ALPHA_STANDARD: The data libpng produces is encoded in the
standard way assumed by most correctly written graphics software.
The gamma encoding will be removed by libpng and the
linear component values will be pre-multiplied by the
alpha channel.
With this format the final image must be re-encoded to
match the display gamma before the image is displayed.
If your system doesn't do that, yet still seems to
perform arithmetic on the pixels without decoding them,
it is broken - check out the modes below.
With PNG_ALPHA_STANDARD libpng always produces linear
component values, whatever screen_gamma you supply. The
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
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
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
components to 16 bits.
PNG_ALPHA_OPTIMIZED: This mode is the same as PNG_ALPHA_STANDARD
except that completely opaque pixels are gamma encoded according to
the screen_gamma value. Pixels with alpha less than 1.0
will still have linear components.
Use this format if you have control over your
compositing software and so don't do other arithmetic
(such as scaling) on the data you get from libpng. Your
compositing software can simply copy opaque pixels to
the output but still has linear values for the
non-opaque pixels.
In normal compositing, where the alpha channel encodes
partial pixel coverage (as opposed to broad area
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, including the alpha channel are gamma encoded. This is
broken because, in practice, no implementation that uses this choice
correctly undoes the encoding before handling alpha composition. Use this
choice only if other serious errors in the software or hardware you use
mandate it. In most cases of broken software or hardware the bug in the
final display manifests as a subtle halo around composited parts of the
image. You may not even perceive this as a halo; the composited part of
the image may simply appear 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():
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 multiply out the alpha.
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();
instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
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_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.
The following are examples of calls to png_set_alpha_mode to achieve the
required overall gamma correction and, where necessary, alpha
premultiplication.
png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
This is the default libpng handling of the alpha channel - it is not
pre-multiplied into the color components. In addition the call states
that the output is for a sRGB system and causes all PNG files without gAMA
chunks to be assumed to be encoded using sRGB.
png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
In this case the output is assumed to be something like an sRGB conformant
display preceeded by a power-law lookup table of power 1.45. This is how
early Mac systems behaved.
png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR);
This is the classic Jim Blinn approach and will work in academic
environments where everything is done by the book. It has the shortcoming
of assuming that input PNG data with no gamma information is linear - this
is unlikely to be correct unless the PNG files where generated locally.
Most of the time the output precision will be so low as to show
significant banding in dark areas of the image.
png_set_expand_16(pp);
png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_DEFAULT_sRGB);
This is a somewhat more realistic Jim Blinn inspired approach. PNG files
are assumed to have the sRGB encoding if not marked with a gamma value and
the output is always 16 bits per component. This permits accurate scaling
and processing of the data. If you know that your input PNG files were
generated locally you might need to replace PNG_DEFAULT_sRGB with the
correct value for your system.
png_set_alpha_mode(pp, PNG_ALPHA_OPTIMIZED, PNG_DEFAULT_sRGB);
If you just need to composite the PNG image onto an existing background
and if you control the code that does this you can use the optimization
setting. In this case you just copy completely opaque pixels to the
output. For pixels that are not completely transparent (you just skip
those) you do the composition math using png_composite or png_composite_16
below then encode the resultant 8-bit or 16-bit values to match the output
encoding.
Other cases
If neither the PNG nor the standard linear encoding work for you because
of the software or hardware you use then you have a big problem. The PNG
case will probably result in halos around the image. The linear encoding
will probably result in a washed out, too bright, image (it's actually too
contrasty.) Try the ALPHA_OPTIMIZED mode above - this will probably
substantially reduce the halos. Alternatively try:
png_set_alpha_mode(pp, PNG_ALPHA_BROKEN, PNG_DEFAULT_sRGB);
This option will also reduce the halos, but there will be slight dark
halos round the opaque parts of the image where the background is light.
In the OPTIMIZED mode the halos will be light halos where the background
is dark. Take your pick - the halos are unavoidable unless you can get
your hardware/software fixed! (The OPTIMIZED approach is slightly
faster.)
When the default gamma of PNG files doesn't match the output gamma.
If you have PNG files with no gamma information png_set_alpha_mode allows
you to provide a default gamma, but it also sets the ouput gamma to the
matching value. If you know your PNG files have a gamma that doesn't
match the output you can take advantage of the fact that
png_set_alpha_mode always sets the output gamma but only sets the PNG
default if it is not already set:
png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
The first call sets both the default and the output gamma values, the
second call overrides the output gamma without changing the default. This
is easier than achieving the same effect with png_set_gamma. You must use
PNG_ALPHA_PNG for the first call - internal checking in png_set_alpha will
fire if more than one call to png_set_alpha_mode and png_set_background is
made in the same read operation, however multiple calls with PNG_ALPHA_PNG
are ignored.
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
transparent parts of this image.
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
file, if you call png_set_background at this point you must arrange for the
format produced by libpng to always have 8-bit or 16-bit components and then
store the color as an 8-bit or 16-bit color as appropriate. The color contains
separate gray and RGB component values, so you can let libpng produce gray or
RGB output according to the input format, but low bit depth grayscale images
must always be converted to at least 8-bit format. (Even though low bit depth
grayscale images can't have an alpha channel they can have a transparent
color!)
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
settings and API calls required are:
8-bit values:
PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
png_set_expand(png_ptr); png_set_scale_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_STRIP_16 and png_set_strip_16(png_ptr)
instead.
16-bit values:
PNG_TRANSFORM_EXPAND_16
png_set_expand_16(png_ptr);
In either case palette image data will be expanded to RGB. If you just want
color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
to the list.
Calling png_set_background before the PNG file header is read will not work
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
been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
used with the high level interface.
The high-level read interface
At this point there are two ways to proceed; through the high-level
read interface, or through a sequence of low-level read operations.
You can use the high-level interface if (a) you are willing to read
the entire image into memory, and (b) the input transformations
you want to do are limited to the following set:
PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to
8-bit accurately
PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to
8-bit less accurately
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
samples to bytes
PNG_TRANSFORM_PACKSWAP Change order of packed
pixels to LSB first
PNG_TRANSFORM_EXPAND Perform set_expand()
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
PNG_TRANSFORM_SHIFT Normalize pixels to the
sBIT depth
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
to BGRA
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
to AG
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
to RGB (or GA to RGBA)
PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits
(This excludes setting a background color, doing gamma transformation,
quantizing, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the bitwise OR of some
set of transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask,
then png_read_image(), and finally png_read_end().
(The final parameter of this call is not yet used. Someday it might point
to transformation parameters required by some future input transform.)
You must use png_transforms and not call any png_set_transform() functions
when you use png_read_png().
After you have called png_read_png(), you can retrieve the image data
with
row_pointers = png_get_rows(png_ptr, info_ptr);
where row_pointers is an array of pointers to the pixel data for each row:
png_bytep row_pointers[height];
If you know your image size and pixel size ahead of time, you can allocate
row_pointers prior to calling png_read_png() with
if (height > PNG_UINT_32_MAX/(sizeof (png_byte)))
png_error (png_ptr,
"Image is too tall to process in memory");
if (width > PNG_UINT_32_MAX/pixel_size)
png_error (png_ptr,
"Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
height*(sizeof (png_bytep)));
for (int i=0; i<height, i++)
row_pointers[i]=NULL; /* security precaution */
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
png_set_rows(png_ptr, info_ptr, &row_pointers);
Alternatively you could allocate your image in one big block and define
row_pointers[i] to point into the proper places in your block.
If you use png_set_rows(), the application is responsible for freeing
row_pointers (and row_pointers[i], if they were separately allocated).
If you don't allocate row_pointers ahead of time, png_read_png() will
do it, and it'll be free'ed by libpng when you call png_destroy_*().
The low-level read interface
If you are going the low-level route, you are now ready to read all
the file information up to the actual image data. You do this with a
call to png_read_info().
png_read_info(png_ptr, info_ptr);
This will process all chunks up to but not including the image data.
This also copies some of the data from the PNG file into the decode structure
for use in later transformations. Important information copied in is:
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.
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
resulting in unexpected behavior. Libpng-1.5.4 no longer does this.
3) The number of significant bits in each component value. Libpng uses this to
optimize gamma handling by reducing the internal lookup table sizes.
4) The transparent color information from a tRNS chunk. This can be modified by
a later call to png_set_tRNS.
Querying the info structure
Functions are used to get the information from the info_ptr once it
has been read. Note that these fields may not be completely filled
in until png_read_end() has read the chunk data following the image.
png_get_IHDR(png_ptr, info_ptr, &width, &height,
&bit_depth, &color_type, &interlace_type,
&compression_type, &filter_method);
width - holds the width of the image
in pixels (up to 2^31).
height - holds the height of the image
in pixels (up to 2^31).
bit_depth - holds the bit depth of one of the
image channels. (valid values are
1, 2, 4, 8, 16 and depend also on
the color_type. See also
significant bits (sBIT) below).
color_type - describes which color/alpha channels
are present.
PNG_COLOR_TYPE_GRAY
(bit depths 1, 2, 4, 8, 16)
PNG_COLOR_TYPE_GRAY_ALPHA
(bit depths 8, 16)
PNG_COLOR_TYPE_PALETTE
(bit depths 1, 2, 4, 8)
PNG_COLOR_TYPE_RGB
(bit_depths 8, 16)
PNG_COLOR_TYPE_RGB_ALPHA
(bit_depths 8, 16)
PNG_COLOR_MASK_PALETTE
PNG_COLOR_MASK_COLOR
PNG_COLOR_MASK_ALPHA
interlace_type - (PNG_INTERLACE_NONE or
PNG_INTERLACE_ADAM7)
compression_type - (must be PNG_COMPRESSION_TYPE_BASE
for PNG 1.0)
filter_method - (must be PNG_FILTER_TYPE_BASE
for PNG 1.0, and can also be
PNG_INTRAPIXEL_DIFFERENCING if
the PNG datastream is embedded in
a MNG-1.0 datastream)
Any or all of interlace_type, compression_type, or
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
the application's width and height variables.
This is an unsafe situation if these are 16-bit
variables. In such situations, the
png_get_image_width() and png_get_image_height()
functions described below are safer.
width = png_get_image_width(png_ptr,
info_ptr);
height = png_get_image_height(png_ptr,
info_ptr);
bit_depth = png_get_bit_depth(png_ptr,
info_ptr);
color_type = png_get_color_type(png_ptr,
info_ptr);
interlace_type = png_get_interlace_type(png_ptr,
info_ptr);
compression_type = png_get_compression_type(png_ptr,
info_ptr);
filter_method = png_get_filter_type(png_ptr,
info_ptr);
channels = png_get_channels(png_ptr, info_ptr);
channels - number of channels of info for the
color type (valid values are 1 (GRAY,
PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
4 (RGB_ALPHA or RGB + filler byte))
rowbytes = png_get_rowbytes(png_ptr, info_ptr);
rowbytes - number of bytes needed to hold a row
signature = png_get_signature(png_ptr, info_ptr);
signature - holds the signature read from the
file (if any). The data is kept in
the same offset it would be if the
whole signature were read (i.e. if an
application had already read in 4
bytes of signature before starting
libpng, the remaining 4 bytes would
be in signature[4] through signature[7]
(see png_set_sig_bytes())).
These are also important, but their validity depends on whether the chunk
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing. The parameters to the
png_get_<chunk> are set directly if they are simple data types, or a
pointer into the info_ptr is returned for any complex types.
The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
is simply returned to give the application information about how the
image was encoded. Libpng itself only does transformations using the file
gamma when combining semitransparent pixels with the background color, and,
since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels
within the simplified API. Libpng also uses the file gamma when converting
RGB to gray, beginning with libpng-1.0.5, if the application calls
png_set_rgb_to_gray()).
png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette);
palette - the palette for the file
(array of png_color)
num_palette - number of entries in the palette
png_get_gAMA(png_ptr, info_ptr, &file_gamma);
png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
file_gamma - the gamma at which the file is
written (PNG_INFO_gAMA)
int_file_gamma - 100,000 times the gamma at which the
file is written
png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x,
&red_y, &green_x, &green_y, &blue_x, &blue_y)
png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z,
&green_X, &green_Y, &green_Z, &blue_X, &blue_Y,
&blue_Z)
png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x,
&int_white_y, &int_red_x, &int_red_y,
&int_green_x, &int_green_y, &int_blue_x,
&int_blue_y)
png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
&int_red_Z, &int_green_X, &int_green_Y,
&int_green_Z, &int_blue_X, &int_blue_Y,
&int_blue_Z)
{white,red,green,blue}_{x,y}
A color space encoding specified using the
chromaticities of the end points and the
white point. (PNG_INFO_cHRM)
{red,green,blue}_{X,Y,Z}
A color space encoding specified using the
encoding end points - the CIE tristimulus
specification of the intended color of the red,
green and blue channels in the PNG RGB data.
The white point is simply the sum of the three
end points. (PNG_INFO_cHRM)
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
srgb_intent - the rendering intent (PNG_INFO_sRGB)
The presence of the sRGB chunk
means that the pixel data is in the
sRGB color space. This chunk also
implies specific values of gAMA and
cHRM.
png_get_iCCP(png_ptr, info_ptr, &name,
&compression_type, &profile, &proflen);
name - The profile name.
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
profile - International Color Consortium color
profile data. May contain NULs.
proflen - length of profile data in bytes.
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray,
red, green, and blue channels,
whichever are appropriate for the
given color type (png_color_16)
png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
&num_trans, &trans_color);
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
num_trans - number of transparent entries
(PNG_INFO_tRNS)
trans_color - graylevel or color sample values of
the single transparent color for
non-paletted images (PNG_INFO_tRNS)
png_get_hIST(png_ptr, info_ptr, &hist);
(PNG_INFO_hIST)
hist - histogram of palette (array of
png_uint_16)
png_get_tIME(png_ptr, info_ptr, &mod_time);
mod_time - time image was last modified
(PNG_VALID_tIME)
png_get_bKGD(png_ptr, info_ptr, &background);
background - background color (of type
png_color_16p) (PNG_VALID_bKGD)
valid 16-bit red, green and blue
values, regardless of color_type
num_comments = png_get_text(png_ptr, info_ptr,
&text_ptr, &num_text);
num_comments - number of comments
text_ptr - array of png_text holding image
comments
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
text_ptr[i].key - keyword for comment. Must contain
1-79 characters.
text_ptr[i].text - text comments for current
keyword. Can be empty.
text_ptr[i].text_length - length of text string,
after decompression, 0 for iTXt
text_ptr[i].itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
text_ptr[i].lang - language of comment (empty
string for unknown).
text_ptr[i].lang_key - keyword in UTF-8
(empty string for unknown).
Note that the itxt_length, lang, and lang_key
members of the text_ptr structure only exist when the
library is built with iTXt chunk support. Prior to
libpng-1.4.0 the library was built by default without
iTXt support. Also note that when iTXt is supported,
they contain NULL pointers when the "compression"
field contains PNG_TEXT_COMPRESSION_NONE or
PNG_TEXT_COMPRESSION_zTXt.
num_text - number of comments (same as
num_comments; you can put NULL here
to avoid the duplication)
Note while png_set_text() will accept text, language,
and translated keywords that can be NULL pointers, the
structure returned by png_get_text will always contain
regular zero-terminated C strings. They might be
empty strings but they will never be NULL pointers.
num_spalettes = png_get_sPLT(png_ptr, info_ptr,
&palette_ptr);
num_spalettes - number of sPLT chunks read.
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
Each of these returns 0 [signifying "unknown" if both
x and y are 0] if the data is not present or if the
chunk is present but the unit is the pixel. The
remark about inexact inch conversions applies here
as well, because a value in inches can't always be
converted to microns and back without some loss
of precision.
For more information, see the
PNG specification for chunk contents. Be careful with trusting
rowbytes, as some of the transformations could increase the space
needed to hold a row (expand, filler, gray_to_rgb, etc.).
See png_read_update_info(), below.
A quick word about text_ptr and num_text. PNG stores comments in
keyword/text pairs, one pair per chunk, with no limit on the number
of text chunks, and a 2^31 byte limit on their size. While there are
suggested keywords, there is no requirement to restrict the use to these
strings. It is strongly suggested that keywords and text be sensible
to humans (that's the point), so don't use abbreviations. Non-printing
symbols are not allowed. See the PNG specification for more details.
There is also no requirement to have text after the keyword.
Keywords should be limited to 79 Latin-1 characters without leading or
trailing spaces, but non-consecutive spaces are allowed within the
keyword. It is possible to have the same keyword any number of times.
The text_ptr is an array of png_text structures, each holding a
pointer to a language string, a pointer to a keyword and a pointer to
a text string. The text string, language code, and translated
keyword may be empty or NULL pointers. The keyword/text
pairs are put into the array in the order that they are received.
However, some or all of the text chunks may be after the image, so, to
make sure you have read all the text chunks, don't mess with these
until after you read the stuff after the image. This will be
mentioned again below in the discussion that goes with png_read_end().
Input transformations
After you've read the header information, you can set up the library
to handle any special transformations of the image data. The various
ways to transform the data will be described in the order that they
should occur. This is important, as some of these change the color
type and/or bit depth of the data, and some others only work on
certain color types and bit depths.
Transformations you request are ignored if they don't have any meaning for a
particular input data format. However some transformations can have an effect
as a result of a previous transformation. If you specify a contradictory set of
transformations, for example both adding and removing the alpha channel, you
cannot predict the final result.
The color used for the transparency values should be supplied in the same
format/depth as the current image data. It is stored in the same format/depth
as the image data in a tRNS chunk, so this is what libpng expects for this data.
The color used for the background value depends on the need_expand argument as
described below.
Data will be decoded into the supplied row buffers packed into bytes
unless the library has been told to transform it into another format.
For example, 4 bit/pixel paletted or grayscale data will be returned
2 pixels/byte with the leftmost pixel in the high-order bits of the
byte, unless png_set_packing() is called. 8-bit RGB data will be stored
in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
is called to insert filler bytes, either before or after each RGB triplet.
16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
byte of the color value first, unless png_set_scale_16() is called to
transform it to regular RGB RGB triplets, or png_set_filler() or
png_set_add alpha() is called to insert filler bytes, either before or
after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
or png_set_scale_16().
The following code transforms grayscale images of less than 8 to 8 bits,
changes paletted images to RGB, and adds a full alpha channel if there is
transparency information in a tRNS chunk. This is most useful on
grayscale images with bit depths of 2 or 4 or if there is a multiple-image
viewing application that wishes to treat all images in the same way.
if (color_type == PNG_COLOR_TYPE_PALETTE)
png_set_palette_to_rgb(png_ptr);
if (png_get_valid(png_ptr, info_ptr,
PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
if (color_type == PNG_COLOR_TYPE_GRAY &&
bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
The first two functions are actually aliases for png_set_expand(), added
in libpng version 1.0.4, with the function names expanded to improve code
readability. In some future version they may actually do different
things.
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added. It expands the sample depth without changing tRNS to alpha.
As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
png_set_expand(); however, the resultant channels have 16 bits rather than 8.
Use this when the output color or gray channels are made linear to avoid fairly
severe accuracy loss.
if (bit_depth < 16)
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.
if (bit_depth == 16)
#if PNG_LIBPNG_VER >= 10504
png_set_scale_16(png_ptr);
#else
png_set_strip_16(png_ptr);
#endif
(The more accurate "png_set_scale_16()" API became available in libpng version
1.5.4).
If you need to process the alpha channel on the image separately from the image
data (for example if you convert it to a bitmap mask) it is possible to have
libpng strip the channel leaving just RGB or gray data:
if (color_type & PNG_COLOR_MASK_ALPHA)
png_set_strip_alpha(png_ptr);
If you strip the alpha channel you need to find some other way of dealing with
the information. If, instead, you want to convert the image to an opaque
version with no alpha channel use png_set_background; see below.
As of libpng version 1.5.2, almost all useful expansions are supported, the
major ommissions are conversion of grayscale to indexed images (which can be
done trivially in the application) and conversion of indexed to grayscale (which
can be done by a trivial manipulation of the palette.)
In the following table, the 01 means grayscale with depth<8, 31 means
indexed with depth<8, other numerals represent the color type, "T" means
the tRNS chunk is present, A means an alpha channel is present, and O
means tRNS or alpha is present but all pixels in the image are opaque.
FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
TO
01 - [G] - - - - - - - - - - - - -
31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q
0 1 G + . . G G G G G G B B GB GB
0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt
0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt
2 C P C C C + . . C - - CB CB B B
2T Ct - Ct C C t + t - - - CBt CBt Bt Bt
2O Ct - Ct C C t t + - - - CBt CBt Bt Bt
3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q
3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt
3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt
4A lA G A T T GA GT GT GA GT GT + BA G GBA
4O lA GBA A T T GA GT GT GA GT GT BA + GBA G
6A CA PA CA C C A T tT PA P P C CBA + BA
6O CA PBA CA C C A tT T PA P P CBA C BA +
Within the matrix,
"+" identifies entries where 'from' and 'to' are the same.
"-" means the transformation is not supported.
"." means nothing is necessary (a tRNS chunk can just be ignored).
"t" means the transformation is obtained by png_set_tRNS.
"A" means the transformation is obtained by png_set_add_alpha().
"X" means the transformation is obtained by png_set_expand().
"1" means the transformation is obtained by
png_set_expand_gray_1_2_4_to_8() (and by png_set_expand()
if there is no transparency in the original or the final
format).
"C" means the transformation is obtained by png_set_gray_to_rgb().
"G" means the transformation is obtained by png_set_rgb_to_gray().
"P" means the transformation is obtained by
png_set_expand_palette_to_rgb().
"p" means the transformation is obtained by png_set_packing().
"Q" means the transformation is obtained by png_set_quantize().
"T" means the transformation is obtained by
png_set_tRNS_to_alpha().
"B" means the transformation is obtained by
png_set_background(), or png_strip_alpha().
When an entry has multiple transforms listed all are required to cause the
right overall transformation. When two transforms are separated by a comma
either will do the job. When transforms are enclosed in [] the transform should
do the job but this is currently unimplemented - a different format will result
if the suggested transformations are used.
In PNG files, the alpha channel in an image
is the level of opacity. If you need the alpha channel in an image to
be the level of transparency instead of opacity, you can invert the
alpha channel (or the tRNS chunk data) after it's read, so that 0 is
fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
images) is fully transparent, with
png_set_invert_alpha(png_ptr);
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
they can, resulting in, for example, 8 pixels per byte for 1 bit
files. This code expands to 1 pixel per byte without changing the
values of the pixels:
if (bit_depth < 8)
png_set_packing(png_ptr);
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
to 8 bits/sample in the range [0, 255]). However, it is also possible
to convert the PNG pixel data back to the original bit depth of the
image. This call reduces the pixels back down to the original bit depth:
png_color_8p sig_bit;
if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
png_set_shift(png_ptr, sig_bit);
PNG files store 3-color pixels in red, green, blue order. This code
changes the storage of the pixels to blue, green, red:
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_bgr(png_ptr);
PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
into 4 or 8 bytes for windowing systems that need them in this format:
if (color_type == PNG_COLOR_TYPE_RGB)
png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
you want the filler before the RGB or after. This transformation
does not affect images that already have full alpha channels. To add an
opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
will generate RGBA pixels.
Note that png_set_filler() does not change the color type. If you want
to do that, you can add a true alpha channel with
if (color_type == PNG_COLOR_TYPE_RGB ||
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
with alpha.
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_rgb_to_gray(png_ptr, error_action,
double red_weight, double green_weight);
error_action = 1: silently do the conversion
error_action = 2: issue a warning if the original
image has any pixel where
red != green or red != blue
error_action = 3: issue an error and abort the
conversion if the original
image has any pixel where
red != green or red != blue
red_weight: weight of red component
green_weight: weight of green component
If either weight is negative, default
weights are used.
In the corresponding fixed point API the red_weight and green_weight values are
simply scaled by 100,000:
png_set_rgb_to_gray(png_ptr, error_action,
png_fixed_point red_weight,
png_fixed_point green_weight);
If you have set error_action = 1 or 2, you can
later check whether the image really was gray, after processing
the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
It will return a png_byte that is zero if the image was gray or
1 if there were any non-gray pixels. Background and sBIT data
will be silently converted to grayscale, using the green channel
data for sBIT, regardless of the error_action setting.
The default values come from the PNG file cHRM chunk if present; otherwise, the
defaults correspond to the ITU-R recommendation 709, and also the sRGB color
space, as recommended in the Charles Poynton's Colour FAQ,
<http://www.poynton.com/>, in section 9:
<http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
Previous versions of this document, 1998 through 2002, recommended a slightly
different formula:
Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
Libpng uses an integer approximation:
Y = (6968 * R + 23434 * G + 2366 * B)/32768
The calculation is done in a linear colorspace, if the image gamma
can be determined.
The png_set_background() function has been described already; it tells libpng to
composite images with alpha or simple transparency against the supplied
background color. For compatibility with versions of libpng earlier than
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.
If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
you may use this color, or supply another color more suitable for
the current display (e.g., the background color from a web page). You
need to tell libpng how the color is represented, both the format of the
component values in the color (the number of bits) and the gamma encoding of the
color. The function takes two arguments, background_gamma_mode and need_expand
to convey this information; however, only two combinations are likely to be
useful:
png_color_16 my_background;
png_color_16p image_background;
if (png_get_bKGD(png_ptr, info_ptr, &image_background))
png_set_background(png_ptr, image_background,
PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
else
png_set_background(png_ptr, &my_background,
PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
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-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
index and for low bit greyscale images the color is a reduced bit value in
image_background->gray.
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
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
settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
supported then you can certainly do png_set_gamma() before reading the PNG
header.)
This API unconditionally sets the screen and file gamma values, so it will
override the value in the PNG file unless it is called before the PNG file
reading starts. For this reason you must always call it with the PNG file
value when you call it in this position:
if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
png_set_gamma(png_ptr, screen_gamma, file_gamma);
else
png_set_gamma(png_ptr, screen_gamma, 0.45455);
If you need to reduce an RGB file to a paletted file, or if a paletted
file has more entries then will fit on your screen, png_set_quantize()
will do that. Note that this is a simple match quantization that merely
finds the closest color available. This should work fairly well with
optimized palettes, but fairly badly with linear color cubes. If you
pass a palette that is larger than maximum_colors, the file will
reduce the number of colors in the palette so it will fit into
maximum_colors. If there is a histogram, libpng will use it to make
more intelligent choices when reducing the palette. If there is no
histogram, it may not do as good a job.
if (color_type & PNG_COLOR_MASK_COLOR)
{
if (png_get_valid(png_ptr, info_ptr,
PNG_INFO_PLTE))
{
png_uint_16p histogram = NULL;
png_get_hIST(png_ptr, info_ptr,
&histogram);
png_set_quantize(png_ptr, palette, num_palette,
max_screen_colors, histogram, 1);
}
else
{
png_color std_color_cube[MAX_SCREEN_COLORS] =
{ ... colors ... };
png_set_quantize(png_ptr, std_color_cube,
MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
NULL,0);
}
}
PNG files describe monochrome as black being zero and white being one.
The following code will reverse this (make black be one and white be
zero):
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
void read_transform_fn(png_structp png_ptr, png_row_infop
row_info, png_bytep data)
See pngtest.c for a working example. Your function will be called
after all of the other transformations have been processed. Take care with
interlaced images if you do the interlace yourself - the width of the row is the
width in 'row_info', not the overall image width.
If supported, libpng provides two information routines that you can use to find
where you are in processing the image:
png_get_current_pass_number(png_structp png_ptr);
png_get_current_row_number(png_structp png_ptr);
Don't try using these outside a transform callback - firstly they are only
supported if user transforms are supported, secondly they may well return
unexpected results unless the row is actually being processed at the moment they
are called.
With interlaced
images the value returned is the row in the input sub-image image. Use
PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
The discussion of interlace handling above contains more information on how to
use these values.
You can also set up a pointer to a user structure for use by your
callback function, and you can inform libpng that your transform
function will change the number of channels or bit depth with the
function
png_set_user_transform_info(png_ptr, user_ptr,
user_depth, user_channels);
The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.
You can retrieve the pointer via the function
png_get_user_transform_ptr(). For example:
voidp read_user_transform_ptr =
png_get_user_transform_ptr(png_ptr);
The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
of the interlaced image.
number_of_passes = png_set_interlace_handling(png_ptr);
After setting the transformations, libpng can update your png_info
structure to reflect any transformations you've requested with this
call.
png_read_update_info(png_ptr, info_ptr);
This is most useful to update the info structure's rowbytes
field so you can use it to allocate your image memory. This function
will also update your palette with the correct screen_gamma and
background if these have been given with the calls above. You may
only call png_read_update_info() once with a particular info_ptr.
After you call png_read_update_info(), you can allocate any
memory you need to hold the image. The row data is simply
raw byte data for all forms of images. As the actual allocation
varies among applications, no example will be given. If you
are allocating one large chunk, you will need to build an
array of pointers to each row, as it will be needed for some
of the functions below.
Remember: Before you call png_read_update_info(), the png_get_*()
functions return the values corresponding to the original PNG image.
After you call png_read_update_info the values refer to the image
that libpng will output. Consequently you must call all the png_set_
functions before you call png_read_update_info(). This is particularly
important for png_set_interlace_handling() - if you are going to call
png_read_update_info() you must call png_set_interlace_handling() before
it unless you want to receive interlaced output.
Reading image data
After you've allocated memory, you can read the image data.
The simplest way to do this is in one function call. If you are
allocating enough memory to hold the whole image, you can just
call png_read_image() and libpng will read in all the image data
and put it in the memory area supplied. You will need to pass in
an array of pointers to each row.
This function automatically handles interlacing, so you don't
need to call png_set_interlace_handling() (unless you call
png_read_update_info()) or call this function multiple times, or any
of that other stuff necessary with png_read_rows().
png_read_image(png_ptr, row_pointers);
where row_pointers is:
png_bytep row_pointers[height];
You can point to void or char or whatever you use for pixels.
If you don't want to read in the whole image at once, you can
use png_read_rows() instead. If there is no interlacing (check
interlace_type == PNG_INTERLACE_NONE), this is simple:
png_read_rows(png_ptr, row_pointers, NULL,
number_of_rows);
where row_pointers is the same as in the png_read_image() call.
If you are doing this just one row at a time, you can do this with
a single row_pointer instead of an array of row_pointers:
png_bytep row_pointer = row;
png_read_row(png_ptr, row_pointer, NULL);
If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
get somewhat harder. The only current (PNG Specification version 1.2)
interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
a somewhat complicated 2D interlace scheme, known as Adam7, that
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
srgb_intent);
srgb_intent - the rendering intent
(PNG_INFO_sRGB) The presence of the
sRGB chunk means that the pixel
data is in the sRGB color space.
This function also causes gAMA and
cHRM chunks with the specific values
that are consistent with sRGB to be
written.
png_set_iCCP(png_ptr, info_ptr, name, compression_type,
profile, proflen);
name - The profile name.
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
profile - International Color Consortium color
profile data. May contain NULs.
proflen - length of profile data in bytes.
png_set_sBIT(png_ptr, info_ptr, sig_bit);
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray, red,
green, and blue channels, whichever are
appropriate for the given color type
(png_color_16)
png_set_tRNS(png_ptr, info_ptr, trans_alpha,
num_trans, trans_color);
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
num_trans - number of transparent entries
(PNG_INFO_tRNS)
trans_color - graylevel or color sample values
(in order red, green, blue) of the
single transparent color for
non-paletted images (PNG_INFO_tRNS)
png_set_hIST(png_ptr, info_ptr, hist);
hist - histogram of palette (array of
png_uint_16) (PNG_INFO_hIST)
png_set_tIME(png_ptr, info_ptr, mod_time);
mod_time - time image was last modified
(PNG_VALID_tIME)
png_set_bKGD(png_ptr, info_ptr, background);
background - background color (of type
png_color_16p) (PNG_VALID_bKGD)
png_set_text(png_ptr, info_ptr, text_ptr, num_text);
text_ptr - array of png_text holding image
comments
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
text_ptr[i].key - keyword for comment. Must contain
1-79 characters.
text_ptr[i].text - text comments for current
keyword. Can be NULL or empty.
text_ptr[i].text_length - length of text string,
after decompression, 0 for iTXt
text_ptr[i].itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
text_ptr[i].lang - language of comment (NULL or
empty for unknown).
text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
or empty for unknown).
Note that the itxt_length, lang, and lang_key
members of the text_ptr structure only exist when the
library is built with iTXt chunk support. Prior to
libpng-1.4.0 the library was built by default without
iTXt support. Also note that when iTXt is supported,
they contain NULL pointers when the "compression"
field contains PNG_TEXT_COMPRESSION_NONE or
PNG_TEXT_COMPRESSION_zTXt.
num_text - number of comments
png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
num_spalettes);
palette_ptr - array of png_sPLT_struct structures
to be added to the list of palettes
in the info structure.
num_spalettes - number of palette structures to be
added.
png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
unit_type);
offset_x - positive offset from the left
edge of the screen
offset_y - positive offset from the top
edge of the screen
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
unit_type);
res_x - pixels/unit physical resolution
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
The number of separate channels (components) in a pixel; 1 for a
color-mapped image.
PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
The size, in bytes, of each component in a pixel; 1 for a color-mapped
image.
PNG_IMAGE_PIXEL_SIZE(fmt)
The size, in bytes, of a complete pixel; 1 for a color-mapped image.
Information about the whole row, or whole image
PNG_IMAGE_ROW_STRIDE(image)
Returns the total number of components in a single row of the image; this
is the minimum 'row stride', the minimum count of components between each
row. For a color-mapped image this is the minimum number of bytes in a
row.
If you need the stride measured in bytes, row_stride_bytes is
PNG_IMAGE_ROW_STRIDE(image) * PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)
plus any padding bytes that your application might need, for example
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.
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
READ APIs
The png_image passed to the read APIs must have been initialized by setting
the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
int png_image_begin_read_from_file( png_imagep image,
const char *file_name)
The named file is opened for read and the image header
is filled in from the PNG header in the file.
int png_image_begin_read_from_stdio (png_imagep image,
FILE* file)
The PNG header is read from the stdio FILE object.
int png_image_begin_read_from_memory(png_imagep image,
png_const_voidp memory, png_size_t size)
The PNG header is read from the given memory buffer.
int png_image_finish_read(png_imagep image,
png_colorp background, void *buffer,
png_int_32 row_stride, void *colormap));
Finish reading the image into the supplied buffer and
clean up the png_image structure.
row_stride is the step, in png_byte or png_uint_16 units
as appropriate, between adjacent rows. A positive stride
indicates that the top-most row is first in the buffer -
the normal top-down arrangement. A negative stride
indicates that the bottom-most row is first in the buffer.
background need only be supplied if an alpha channel must
be removed from a png_byte format and the removal is to be
done by compositing on a solid color; otherwise it may be
NULL and any composition will be done directly onto the
buffer. The value is an sRGB color to use for the
background, for grayscale output the green channel is used.
For linear output removing the alpha channel is always done
by compositing on black.
void png_image_free(png_imagep image)
Free any data allocated by libpng in image->opaque,
setting the pointer to NULL. May be called at any time
after the structure is initialized.
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.
WRITE APIS
For write you must initialize a png_image structure to describe the image to
be written:
version: must be set to PNG_IMAGE_VERSION
opaque: must be initialized to NULL
width: image width in pixels
height: image height in rows
format: the format of the data you wish to write
flags: set to 0 unless one of the defined flags applies; set
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images
where the RGB values do not correspond to the colors in sRGB.
colormap_entries: set to the number of entries in the color-map (0 to 256)
int png_image_write_to_file, (png_imagep image,
const char *file, int convert_to_8bit, const void *buffer,
png_int_32 row_stride, const void *colormap));
Write the image to the named file.
int png_image_write_to_stdio(png_imagep image, FILE *file,
int convert_to_8_bit, const void *buffer,
png_int_32 row_stride, const void *colormap)
Write the image to the given (FILE*).
With all write APIs if image is in one of the linear formats with
(png_uint_16) data then setting convert_to_8_bit will cause the output to be
a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
a 16-bit linear encoded PNG file is written.
With all APIs row_stride is handled as in the read APIs - it is the spacing
from one row to the next in component sized units (float) and if negative
indicates a bottom-up row layout in the buffer.
Note that the write API does not support interlacing, sub-8-bit pixels,
and indexed (paletted) images.
VI. Modifying/Customizing libpng
There are two issues here. The first is changing how libpng does
standard things like memory allocation, input/output, and error handling.
The second deals with more complicated things like adding new chunks,
adding new transformations, and generally changing how libpng works.
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
There are no substantial API changes between the non-deprecated parts of
the 1.4.5 API and the 1.5.0 API; however, the ability to directly access
members of the main libpng control structures, png_struct and png_info,
deprecated in earlier versions of libpng, has been completely removed from
libpng 1.5.
We no longer include zlib.h in png.h. The include statement has been moved
to pngstruct.h, where it is not accessible by applications. Applications that
need access to information in zlib.h will need to add the '#include "zlib.h"'
directive. It does not matter whether this is placed prior to or after
the '"#include png.h"' directive.
The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
and were removed.
We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp()
macros into a private header file (pngpriv.h) that is not accessible to
applications.
In png_get_iCCP, the type of "profile" was changed from png_charpp
to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
There are changes of form in png.h, including new and changed macros to
declare parts of the API. Some API functions with arguments that are
pointers to data not modified within the function have been corrected to
declare these arguments with PNG_CONST.
Much of the internal use of C macros to control the library build has also
changed and some of this is visible in the exported header files, in
particular the use of macros to control data and API elements visible
during application compilation may require significant revision to
application code. (It is extremely rare for an application to do this.)
Any program that compiled against libpng 1.4 and did not use deprecated
features or access internal library structures should compile and work
against libpng 1.5, except for the change in the prototype for
png_get_iCCP() and png_set_iCCP() API functions mentioned above.
libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
interlaced images. The macros return the number of rows and columns in
each pass and information that can be used to de-interlace and (if
absolutely necessary) interlace an image.
libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls
the application-provided png_longjmp_ptr on the internal, but application
initialized, longjmp buffer. It is provided as a convenience to avoid
the need to use the png_jmpbuf macro, which had the unnecessary side
effect of resetting the internal png_longjmp_ptr value.
libpng 1.5.0 includes a complete fixed point API. By default this is
present along with the corresponding floating point API. In general the
fixed point API is faster and smaller than the floating point one because
the PNG file format used fixed point, not floating point. This applies
even if the library uses floating point in internal calculations. A new
macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
uses floating point arithmetic (the default) or fixed point arithmetic
internally for performance critical calculations such as gamma correction.
In some cases, the gamma calculations may produce slightly different
results. This has changed the results in png_rgb_to_gray and in alpha
composition (png_set_background for example). This applies even if the
original image was already linear (gamma == 1.0) and, therefore, it is
not necessary to linearize the image. This is because libpng has *not*
been changed to optimize that case correctly, yet.
Fixed point support for the sCAL chunk comes with an important caveat;
the sCAL specification uses a decimal encoding of floating point values
and the accuracy of PNG fixed point values is insufficient for
representation of these values. Consequently a "string" API
(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
arbitrary sCAL chunks in the absence of either the floating point API or
internal floating point calculations. Starting with libpng-1.5.0, both
of these functions are present when PNG_sCAL_SUPPORTED is defined. Prior
to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED
being defined and PNG_FLOATING_POINT_SUPPORTED not being defined.
Applications no longer need to include the optional distribution header
file pngusr.h or define the corresponding macros during application
build in order to see the correct variant of the libpng API. From 1.5.0
application code can check for the corresponding _SUPPORTED macro:
#ifdef PNG_INCH_CONVERSIONS_SUPPORTED
/* code that uses the inch conversion APIs. */
#endif
This macro will only be defined if the inch conversion functions have been
compiled into libpng. The full set of macros, and whether or not support
has been compiled in, are available in the header file pnglibconf.h.
This header file is specific to the libpng build. Notice that prior to
1.5.0 the _SUPPORTED macros would always have the default definition unless
reset by pngusr.h or by explicit settings on the compiler command line.
These settings may produce compiler warnings or errors in 1.5.0 because
of macro redefinition.
Applications can now choose whether to use these macros or to call the
corresponding function by defining PNG_USE_READ_MACROS or
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
will lead to a link failure.
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.
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
use with textual data.
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.
This option can no longer be turned off, and the choice of accurate
or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
API for accurate scaling or the old png_set_strip_16_to_8() API for simple
chopping. In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8
macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two
png_set_*_16_to_8() functions separately.
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
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
increase the limits.
src/Source/LibPNG/libpng-manual.txt view on Meta::CPAN
The following API are now DEPRECATED:
png_info_init_3()
png_convert_to_rfc1123() which has been replaced
with png_convert_to_rfc1123_buffer()
png_malloc_default()
png_free_default()
png_reset_zstream()
The following have been removed:
png_get_io_chunk_name(), which has been replaced
with png_get_io_chunk_type(). The new
function returns a 32-bit integer instead of
a string.
The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and
png_memset() macros are no longer used in the libpng sources and
have been removed. These had already been made invisible to applications
(i.e., defined in the private pngpriv.h header file) since libpng-1.5.0.
The signatures of many exported functions were changed, such that
png_structp became png_structrp or png_const_structrp
png_infop became png_inforp or png_const_inforp
where "rp" indicates a "restricted pointer".
Error detection in some chunks has improved; in particular the iCCP chunk
reader now does pretty complete validation of the basic format. Some bad
profiles that were previously accepted are now accepted with a warning or
rejected, depending upon the png_set_benign_errors() setting, in particular
the very old broken Microsoft/HP 3144-byte sRGB profile. Starting with
libpng-1.6.11, recognizing and checking sRGB profiles can be avoided by
means of
#if defined(PNG_SKIP_sRGB_CHECK_PROFILE) && \
defined(PNG_SET_OPTION_SUPPORTED)
png_set_option(png_ptr, PNG_SKIP_sRGB_CHECK_PROFILE,
PNG_OPTION_ON);
#endif
It's not a good idea to do this if you are using the new "simplified API",
which needs to be able to recognize sRGB profiles conveyed via the iCCP
chunk.
The PNG spec requirement that only grayscale profiles may appear in images
with color type 0 or 4 and that even if the image only contains gray pixels,
only RGB profiles may appear in images with color type 2, 3, or 6, is now
enforced. The sRGB chunk is allowed to appear in images with any color type
and is interpreted by libpng to convey a one-tracer-curve gray profile or a
three-tracer-curve RGB profile as appropriate.
Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained
an empty language field or an empty translated keyword. Both of these
are allowed by the PNG specification, so these warnings are no longer issued.
The library now issues an error if the application attempts to set a
transform after it calls png_read_update_info() or if it attempts to call
both png_read_update_info() and png_start_read_image() or to call either
of them more than once.
The default condition for benign_errors is now to treat benign errors as
warnings while reading and as errors while writing.
The library now issues a warning if both background processing and RGB to
gray are used when gamma correction happens. As with previous versions of
the library the results are numerically very incorrect in this case.
There are some minor arithmetic changes in some transforms such as
png_set_background(), that might be detected by certain regression tests.
Unknown chunk handling has been improved internally, without any API change.
This adds more correct option control of the unknown handling, corrects
a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes
it possible to skip IDAT chunks in the sequential reader.
The machine-generated configure files are no longer included in branches
libpng16 and later of the GIT repository. They continue to be included
in the tarball releases, however.
Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT
stream to set the size of the sliding window for reading instead of using the
default 32-kbyte sliding window size. It was discovered that there are
hundreds of PNG files in the wild that have incorrect CMF bytes that caused
zlib to issue the "invalid distance too far back" error and reject the file.
Libpng-1.6.3 and later calculate their own safe CMF from the image dimensions,
provide a way to revert to the libpng-1.5.x behavior (ignoring the CMF bytes
and using a 32-kbyte sliding window), by using
png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW,
PNG_OPTION_ON);
and provide a tool (contrib/tools/pngfix) for rewriting a PNG file while
optimizing the CMF bytes in its IDAT chunk correctly.
Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong
length, which resulted in PNG files that cannot be read beyond the bad iTXt
chunk. This error was fixed in libpng-1.6.3, and a tool (called
contrib/tools/png-fix-itxt) has been added to the libpng distribution.
XIII. Detecting libpng
The png_get_io_ptr() function has been present since libpng-0.88, has never
changed, and is unaffected by conditional compilation macros. It is the
best choice for use in configure scripts for detecting the presence of any
libpng version since 0.88. In an autoconf "configure.in" you could use
AC_CHECK_LIB(png, png_get_io_ptr, ...
XV. Source code repository
Since about February 2009, version 1.2.34, libpng has been under "git" source
control. The git repository was built from old libpng-x.y.z.tar.gz files
going back to version 0.70. You can access the git repository (read only)
at
git://git.code.sf.net/p/libpng/code
or you can browse it with a web browser by selecting the "code" button at
https://sourceforge.net/projects/libpng
Patches can be sent to glennrp at users.sourceforge.net or to
png-mng-implement at lists.sourceforge.net or you can upload them to
the libpng bug tracker at
http://libpng.sourceforge.net
We also accept patches built from the tar or zip distributions, and
simple verbal discriptions of bug fixes, reported either to the
( run in 1.381 second using v1.01-cache-2.11-cpan-f56aa216473 )