Alien-FreeImage
view release on metacpan or search on metacpan
src/Source/LibPNG/libpng.3 view on Meta::CPAN
\fBint, png_image_begin_read_from_memory (png_imagep \fP\fIimage\fP\fB, png_const_voidp \fP\fImemory\fP\fB, png_size_t \fIsize\fP\fB);\fP
\fBint png_image_finish_read (png_imagep \fP\fIimage\fP\fB, png_colorp \fP\fIbackground\fP\fB, void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap\fP\fB);\fP
\fBvoid png_image_free (png_imagep \fIimage\fP\fB);\fP
\fBint png_image_write_to_file (png_imagep \fP\fIimage\fP\fB, const char \fP\fI*file\fP\fB, int \fP\fIconvert_to_8bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap\fP\fB);\fP
\fBint png_image_write_to_stdio (png_imagep \fP\fIimage\fP\fB, FILE \fP\fI*file\fP\fB, int \fP\fIconvert_to_8_bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fP\fIrow_stride\fP\fB, void \fI*colormap)\fP\fB);\fP
\fBvoid png_info_init_3 (png_infopp \fP\fIinfo_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP
\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
\fBvoid png_longjmp (png_structp \fP\fIpng_ptr\fP\fB, int \fIval\fP\fB);\fP
\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
\fBpng_voidp png_malloc_default (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
\fBpng_voidp png_malloc_warn (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
\fBpng_uint_32 png_permit_mng_features (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fImng_features_permitted\fP\fB);\fP
\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP
\fBpng_size_t png_process_data_pause \fP\fI(png_structp\fP\fB, int \fIsave\fP\fB);\fP
\fBpng_uint_32 png_process_data_skip \fI(png_structp\fP\fB);\fP
\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP
\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fBint png_reset_zstream (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
\fBvoid png_set_alpha_mode (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, double \fIoutput_gamma\fP\fB);\fP
\fBvoid png_set_alpha_mode_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, png_fixed_point \fIoutput_gamma\fP\fB);\fP
\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP
\fBvoid png_set_background_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, png_uint_32 \fIbackground_gamma\fP\fB);\fP
\fBvoid png_set_benign_errors (png_structp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP
\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP
\fBvoid png_set_check_for_invalid_index(png_structrp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP
\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB,...
\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\...
\fBvoid png_set_cHRM_XYZ (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIred_X\fP\fB, double \fP\fIred_Y\fP\fB, double \fP\fIred_Z\fP\fB, double \fP\fIgreen_X\fP\fB, double \fP\fIgreen_Y\fP\fB, double \fP\fIgreen_Z\fP\f...
\fBvoid png_set_cHRM_XYZ_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_fixed_point \fP\fIint_red_X\fP\fB, png_fixed_point \fP\fIint_red_Y\fP\fB, png_fixed_point \fP\fIint_red_Z\fP\fB, png_fixed_point \fP\fIint_green_X\fP...
\fBvoid png_set_chunk_cache_max (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIuser_chunk_cache_max\fP\fB);\fP
\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP
\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP
\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_expand_16 (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP
\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP
\fBvoid png_set_filter_heuristics_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_fixed_point_p \fP\fIfilter_weights\fP\fB, png_fixed_point_p \fIfilter_costs\fP\fB);\fP
\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP
\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP
\fBvoid png_set_gamma_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIscreen_gamma\fP\fB, png_uint_32 \fIdefault_file_gamma\fP\fB);\fP
\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP
\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP
\fBvoid png_set_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP
\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_const_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_const_bytep \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcom...
\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP
\fBjmp_buf* png_set_longjmp_fn (png_structp \fP\fIpng_ptr\fP\fB, png_longjmp_ptr \fP\fIlongjmp_fn\fP\fB, size_t \fIjmp_buf_size\fP\fB);\fP
\fBvoid png_set_chunk_malloc_max (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIuser_chunk_cache_max\fP\fB);\fP
\fBvoid png_set_compression_buffer_size (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
\fBvoid png_set_mem_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP
\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_palette_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, pn...
\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP
\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP
src/Source/LibPNG/libpng.3 view on Meta::CPAN
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
isolated, therefore typically the accuracy loss in storing 8-bit linear
values is acceptable. (This is not true if the alpha channel is used to
simulate transparency over large areas - use 16 bits or the PNG mode in
this case!) This is the 'OPTIMIZED' mode. For this mode a pixel is
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.
.SS 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);
src/Source/LibPNG/libpng.3 view on Meta::CPAN
PNG_AFTER_IDAT (0x08)
The data from the pHYs chunk can be retrieved in several convenient
forms:
res_x = png_get_x_pixels_per_meter(png_ptr,
info_ptr)
res_y = png_get_y_pixels_per_meter(png_ptr,
info_ptr)
res_x_and_y = png_get_pixels_per_meter(png_ptr,
info_ptr)
res_x = png_get_x_pixels_per_inch(png_ptr,
info_ptr)
res_y = png_get_y_pixels_per_inch(png_ptr,
info_ptr)
res_x_and_y = png_get_pixels_per_inch(png_ptr,
info_ptr)
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
info_ptr)
Each of these returns 0 [signifying "unknown"] if
the data is not present or if res_x is 0;
res_x_and_y is 0 if res_x != res_y
Note that because of the way the resolutions are
stored internally, the inch conversions won't
come out to exactly even number. For example,
72 dpi is stored as 0.28346 pixels/meter, and
when this is retrieved it is 71.9988 dpi, so
be sure to round the returned value appropriately
if you want to display a reasonable-looking result.
The data from the oFFs chunk can be retrieved in several convenient
forms:
x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
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().
.SS 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 ||
color_type == PNG_COLOR_TYPE_GRAY)
png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
where "filler" contains the alpha value to assign to each pixel.
This function was added in libpng-1.2.7.
If you are reading an image with an alpha channel, and you need the
data as ARGB instead of the normal PNG format RGBA:
if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_swap_alpha(png_ptr);
For some uses, you may want a grayscale image to be represented as
RGB. This code will do that conversion:
if (color_type == PNG_COLOR_TYPE_GRAY ||
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_gray_to_rgb(png_ptr);
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
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
{
src/Source/LibPNG/libpng.3 view on Meta::CPAN
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.
.SS 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
breaks down an image into seven smaller images of varying size, based
on an 8x8 grid. This number is defined (from libpng 1.5) as
PNG_INTERLACE_ADAM7_PASSES in png.h
libpng can fill out those images or it can give them to you "as is".
It is almost always better to have libpng handle the interlacing for you.
If you want the images filled out, there are two ways to do that. The one
mentioned in the PNG specification is to expand each pixel to cover
those pixels that have not been read yet (the "rectangle" method).
This results in a blocky image for the first pass, which gradually
smooths out as more pixels are read. The other method is the "sparkle"
method, where pixels are drawn only in their final locations, with the
rest of the image remaining whatever colors they were initialized to
before the start of the read. The first method usually looks better,
but tends to be slower, as there are more pixels to put in the rows.
If, as is likely, you want libpng to expand the images, call this before
calling png_start_read_image() or png_read_update_info():
if (interlace_type == PNG_INTERLACE_ADAM7)
number_of_passes
= png_set_interlace_handling(png_ptr);
This will return the number of passes needed. Currently, this is seven,
but may change if another interlace type is added. This function can be
called even if the file is not interlaced, where it will return one pass.
You then need to read the whole image 'number_of_passes' times. Each time
will distribute the pixels from the current pass to the correct place in
the output image, so you need to supply the same rows to png_read_rows in
each pass.
If you are not going to display the image after each pass, but are
going to wait until the entire image is read in, use the sparkle
effect. This effect is faster and the end result of either method
is exactly the same. If you are planning on displaying the image
after each pass, the "rectangle" effect is generally considered the
better looking one.
If you only want the "sparkle" effect, just call png_read_rows() as
normal, with the third parameter NULL. Make sure you make pass over
the image number_of_passes times, and you don't change the data in the
rows between calls. You can change the locations of the data, just
not the data. Each pass only writes the pixels appropriate for that
pass, and assumes the data from previous passes is still valid.
png_read_rows(png_ptr, row_pointers, NULL,
number_of_rows);
If you only want the first effect (the rectangles), do the same as
before except pass the row buffer in the third parameter, and leave
the second parameter NULL.
png_read_rows(png_ptr, NULL, row_pointers,
number_of_rows);
If you don't want libpng to handle the interlacing details, just call
png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
Each of the images is a valid image by itself; however, you will almost
certainly need to distribute the pixels from each sub-image to the
correct place. This is where everything gets very tricky.
If you want to retrieve the separate images you must pass the correct
number of rows to each successive call of png_read_rows(). The calculation
gets pretty complicated for small images, where some sub-images may
not even exist because either their width or height ends up zero.
libpng provides two macros to help you in 1.5 and later versions:
png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
Respectively these tell you the width and height of the sub-image
corresponding to the numbered pass. 'pass' is in in the range 0 to 6 -
this can be confusing because the specification refers to the same passes
as 1 to 7! Be careful, you must check both the width and height before
calling png_read_rows() and not call it for that pass if either is zero.
You can, of course, read each sub-image row by row. If you want to
src/Source/LibPNG/libpng.3 view on Meta::CPAN
datastream. This parameter must be the
same as the value of filter_method used
in png_set_IHDR().
It is also possible to influence how libpng chooses from among the
available filters. This is done in one or both of two ways - by
telling it how important it is to keep the same filter for successive
rows, and by telling it the relative computational costs of the filters.
double weights[3] = {1.5, 1.3, 1.1},
costs[PNG_FILTER_VALUE_LAST] =
{1.0, 1.3, 1.3, 1.5, 1.7};
png_set_filter_heuristics(png_ptr,
PNG_FILTER_HEURISTIC_WEIGHTED, 3,
weights, costs);
The weights are multiplying factors that indicate to libpng that the
row filter should be the same for successive rows unless another row filter
is that many times better than the previous filter. In the above example,
if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
"sum of absolute differences" 1.5 x 1.3 times higher than other filters
and still be chosen, while the NONE filter could have a sum 1.1 times
higher than other filters and still be chosen. Unspecified weights are
taken to be 1.0, and the specified weights should probably be declining
like those above in order to emphasize recent filters over older filters.
The filter costs specify for each filter type a relative decoding cost
to be considered when selecting row filters. This means that filters
with higher costs are less likely to be chosen over filters with lower
costs, unless their "sum of absolute differences" is that much smaller.
The costs do not necessarily reflect the exact computational speeds of
the various filters, since this would unduly influence the final image
size.
Note that the numbers above were invented purely for this example and
are given only to help explain the function usage. Little testing has
been done to find optimum values for either the costs or the weights.
.SS Requesting debug printout
The macro definition PNG_DEBUG can be used to request debugging
printout. Set it to an integer value in the range 0 to 3. Higher
numbers result in increasing amounts of debugging information. The
information is printed to the "stderr" file, unless another file
name is specified in the PNG_DEBUG_FILE macro definition.
When PNG_DEBUG > 0, the following functions (macros) become available:
png_debug(level, message)
png_debug1(level, message, p1)
png_debug2(level, message, p1, p2)
in which "level" is compared to PNG_DEBUG to decide whether to print
the message, "message" is the formatted string to be printed,
and p1 and p2 are parameters that are to be embedded in the string
according to printf-style formatting directives. For example,
png_debug1(2, "foo=%d", foo);
is expanded to
if (PNG_DEBUG > 2)
fprintf(PNG_DEBUG_FILE, "foo=%d\en", foo);
When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
can still use PNG_DEBUG to control your own debugging:
#ifdef PNG_DEBUG
fprintf(stderr, ...
#endif
When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
having level = 0 will be printed. There aren't any such statements in
this version of libpng, but if you insert some they will be printed.
.SH VII. MNG support
The MNG specification (available at http://www.libpng.org/pub/mng) allows
certain extensions to PNG for PNG images that are embedded in MNG datastreams.
Libpng can support some of these extensions. To enable them, use the
png_permit_mng_features() function:
feature_set = png_permit_mng_features(png_ptr, mask)
mask is a png_uint_32 containing the bitwise OR of the
features you want to enable. These include
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
feature_set is a png_uint_32 that is the bitwise AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
It is an error to use this function when reading or writing a standalone
PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
and the MHDR and MEND chunks. Libpng does not provide support for these
or any other MNG chunks; your application must provide its own support for
them. You may wish to consider using libmng (available at
http://www.libmng.com) instead.
.SH VIII. Changes to Libpng from version 0.88
It should be noted that versions of libpng later than 0.96 are not
distributed by the original libpng author, Guy Schalnat, nor by
Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
distributed versions 0.89 through 0.96, but rather by another member
of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
still alive and well, but they have moved on to other things.
The old libpng functions png_read_init(), png_write_init(),
png_info_init(), png_read_destroy(), and png_write_destroy() have been
moved to PNG_INTERNAL in version 0.95 to discourage their use. These
functions will be removed from libpng version 1.4.0.
The preferred method of creating and initializing the libpng structures is
via the png_create_read_struct(), png_create_write_struct(), and
png_create_info_struct() because they isolate the size of the structures
from the application, allow version error checking, and also allow the
src/Source/LibPNG/libpng.3 view on Meta::CPAN
png_destroy_write_struct() if you feel there is too much system overhead
allocating and freeing the png_struct for each image read.
Setting the error callbacks via png_set_message_fn() before
png_read_init() as was suggested in libpng-0.88 is no longer supported
because this caused applications that do not use custom error functions
to fail if the png_ptr was not initialized to zero. It is still possible
to set the error callbacks AFTER png_read_init(), or to change them with
png_set_error_fn(), which is essentially the same function, but with a new
name to force compilation errors with applications that try to use the old
method.
Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6;
however, iTXt support was not enabled by default.
Starting with version 1.0.7, you can find out which version of the library
you are using at run-time:
png_uint_32 libpng_vn = png_access_version_number();
The number libpng_vn is constructed from the major version, minor
version with leading zero, and release number with leading zero,
(e.g., libpng_vn for version 1.0.7 is 10007).
Note that this function does not take a png_ptr, so you can call it
before you've created one.
You can also check which version of png.h you used when compiling your
application:
png_uint_32 application_vn = PNG_LIBPNG_VER;
.SH IX. Changes to Libpng from version 1.0.x to 1.2.x
Support for user memory management was enabled by default. To
accomplish this, the functions png_create_read_struct_2(),
png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
png_malloc_default(), and png_free_default() were added.
Support for the iTXt chunk has been enabled by default as of
version 1.2.41.
Support for certain MNG features was enabled.
Support for numbered error messages was added. However, we never got
around to actually numbering the error messages. The function
png_set_strip_error_numbers() was added (Note: the prototype for this
function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
builds of libpng-1.2.15. It was restored in libpng-1.2.36).
The png_malloc_warn() function was added at libpng-1.2.3. This issues
a png_warning and returns NULL instead of aborting when it fails to
acquire the requested memory allocation.
Support for setting user limits on image width and height was enabled
by default. The functions png_set_user_limits(), png_get_user_width_max(),
and png_get_user_height_max() were added at libpng-1.2.6.
The png_set_add_alpha() function was added at libpng-1.2.7.
The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
deprecated.
A number of macro definitions in support of runtime selection of
assembler code features (especially Intel MMX code support) were
added at libpng-1.2.0:
PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
PNG_ASM_FLAG_MMX_READ_INTERLACE
PNG_ASM_FLAG_MMX_READ_FILTER_SUB
PNG_ASM_FLAG_MMX_READ_FILTER_UP
PNG_ASM_FLAG_MMX_READ_FILTER_AVG
PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
PNG_ASM_FLAGS_INITIALIZED
PNG_MMX_READ_FLAGS
PNG_MMX_FLAGS
PNG_MMX_WRITE_FLAGS
PNG_MMX_FLAGS
We added the following functions in support of runtime
selection of assembler code features:
png_get_mmx_flagmask()
png_set_mmx_thresholds()
png_get_asm_flags()
png_get_mmx_bitdepth_threshold()
png_get_mmx_rowbytes_threshold()
png_set_asm_flags()
We replaced all of these functions with simple stubs in libpng-1.2.20,
when the Intel assembler code was removed due to a licensing issue.
These macros are deprecated:
PNG_READ_TRANSFORMS_NOT_SUPPORTED
PNG_PROGRESSIVE_READ_NOT_SUPPORTED
PNG_NO_SEQUENTIAL_READ_SUPPORTED
PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
They have been replaced, respectively, by:
PNG_NO_READ_TRANSFORMS
PNG_NO_PROGRESSIVE_READ
PNG_NO_SEQUENTIAL_READ
PNG_NO_WRITE_TRANSFORMS
PNG_NO_READ_ANCILLARY_CHUNKS
PNG_NO_WRITE_ANCILLARY_CHUNKS
PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
deprecated since libpng-1.0.16 and libpng-1.2.6.
The function
png_check_sig(sig, num)
was replaced with
!png_sig_cmp(sig, 0, num)
It has been deprecated since libpng-0.90.
The function
png_set_gray_1_2_4_to_8()
which also expands tRNS to alpha was replaced with
png_set_expand_gray_1_2_4_to_8()
which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
.SH X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
Private libpng prototypes and macro definitions were moved from
png.h and pngconf.h into a new pngpriv.h header file.
Functions png_set_benign_errors(), png_benign_error(), and
png_chunk_benign_error() were added.
Support for setting the maximum amount of memory that the application
will allocate for reading chunks was added, as a security measure.
The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
were added to the library.
We implemented support for I/O states by adding png_ptr member io_state
and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
input transforms.
Checking for and reporting of errors in the IHDR chunk is more thorough.
Support for global arrays was removed, to improve thread safety.
Some obsolete/deprecated macros and functions have been removed.
Typecasted NULL definitions such as
#define png_voidp_NULL (png_voidp)NULL
were eliminated. If you used these in your application, just use
NULL instead.
The png_struct and info_struct members "trans" and "trans_values" were
changed to "trans_alpha" and "trans_color", respectively.
The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
were removed.
The PNG_1_0_X and PNG_1_2_X macros were eliminated.
The PNG_LEGACY_SUPPORTED macro was eliminated.
Many WIN32_WCE #ifdefs were removed.
The functions png_read_init(info_ptr), png_write_init(info_ptr),
png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
have been removed. They have been deprecated since libpng-0.95.
The png_permit_empty_plte() was removed. It has been deprecated
since libpng-1.0.9. Use png_permit_mng_features() instead.
We removed the obsolete stub functions png_get_mmx_flagmask(),
png_set_mmx_thresholds(), png_get_asm_flags(),
png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
png_set_asm_flags(), and png_mmx_supported()
We removed the obsolete png_check_sig(), png_memcpy_check(), and
png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(),
and memset(), respectively.
The function png_set_gray_1_2_4_to_8() was removed. It has been
deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
png_set_expand_gray_1_2_4_to_8() because the former function also
expanded any tRNS chunk to an alpha channel.
Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
were added and are used by default instead of the corresponding
functions. Unfortunately,
from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
function) incorrectly returned a value of type png_uint_32.
We changed the prototype for png_malloc() from
png_malloc(png_structp png_ptr, png_uint_32 size)
to
png_malloc(png_structp png_ptr, png_alloc_size_t size)
This also applies to the prototype for the user replacement malloc_fn().
The png_calloc() function was added and is used in place of
of "png_malloc(); memset();" except in the case in png_read_png()
where the array consists of pointers; in this case a "for" loop is used
after the png_malloc() to set the pointers to NULL, to give robust.
behavior in case the application runs out of memory part-way through
the process.
We changed the prototypes of png_get_compression_buffer_size() and
png_set_compression_buffer_size() to work with png_size_t instead of
png_uint_32.
Support for numbered error messages was removed by default, since we
never got around to actually numbering the error messages. The function
png_set_strip_error_numbers() was removed from the library by default.
The png_zalloc() and png_zfree() functions are no longer exported.
The png_zalloc() function no longer zeroes out the memory that it
allocates. Applications that called png_zalloc(png_ptr, number, size)
can call png_calloc(png_ptr, number*size) instead, and can call
png_free() instead of png_zfree().
Support for dithering was disabled by default in libpng-1.4.0, because
it has not been well tested and doesn't actually "dither".
The code was not
removed, however, and could be enabled by building libpng with
PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
was re-enabled, but the function was renamed png_set_quantize() to
reflect more accurately what it actually does. At the same time,
the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
was renamed to PNG_READ_QUANTIZE_SUPPORTED.
We removed the trailing '.' from the warning and error messages.
.SH XI. Changes to Libpng from version 1.4.x to 1.5.x
From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
function) incorrectly returned a value of type png_uint_32.
The incorrect macro was removed from libpng-1.4.5.
Checking for invalid palette index on write was added at libpng
1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues
a benign error. This is enabled by default because this condition is an
error according to the PNG specification, Clause 11.3.2, but the error can
be ignored in each png_ptr with
( run in 1.515 second using v1.01-cache-2.11-cpan-5b529ec07f3 )