view release on metacpan or  search on metacpan

src/Source/LibPNG/libpng-manual.txt  view on Meta::CPAN

              PNG_FILTER_PAETH | PNG_ALL_FILTERS;

    png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
       filters);
              The second parameter can also be
              PNG_INTRAPIXEL_DIFFERENCING if you are
              writing a PNG to be embedded in a MNG
              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.

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\n", 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.

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.

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