Alien-FreeImage

 view release on metacpan or  search on metacpan

src/Source/LibPNG/libpng.3  view on Meta::CPAN

just called:

   0 - no warning or error
   1 - warning
   2 - error
   3 - error preceded by warning

The pixels (samples) of the image have one to four channels whose components
have original values in the range 0 to 1.0:

  1: A single gray or luminance channel (G).
  2: A gray/luminance channel and an alpha channel (GA).
  3: Three red, green, blue color channels (RGB).
  4: Three color channels and an alpha channel (RGBA).

The channels are encoded in one of two ways:

  a) As a small integer, value 0..255, contained in a single byte.  For the
alpha channel the original value is simply value/255.  For the color or
luminance channels the value is encoded according to the sRGB specification
and matches the 8-bit format expected by typical display devices.

The color/gray channels are not scaled (pre-multiplied) by the alpha
channel and are suitable for passing to color management software.

  b) As a value in the range 0..65535, contained in a 2-byte integer, in
the native byte order of the platform on which the application is running.
All channels can be converted to the original value by dividing by 65535; all
channels are linear.  Color channels use the RGB encoding (RGB end-points) of
the sRGB specification.  This encoding is identified by the
PNG_FORMAT_FLAG_LINEAR flag below.

When an alpha channel is present it is expected to denote pixel coverage
of the color or luminance channels and is returned as an associated alpha
channel: the color/gray channels are scaled (pre-multiplied) by the alpha
value.

When a color-mapped image is used as a result of calling
png_image_read_colormap or png_image_write_colormap the channels are encoded
in the color-map and the descriptions above apply to the color-map entries.
The image data is encoded as small integers, value 0..255, that index the
entries in the color-map.  One integer (one byte) is stored for each pixel.

PNG_FORMAT_*

The #defines to be used in png_image::format.  Each #define identifies a
particular layout of channel data and, if present, alpha values.  There are
separate defines for each of the two channel encodings.

A format is built up using single bit flag values.  Not all combinations are
valid: use the bit flag values below for testing a format returned by the
read APIs, but set formats from the derived values.

When reading or writing color-mapped images the format should be set to the
format of the entries in the color-map then png_image_{read,write}_colormap
called to read or write the color-map and set the format correctly for the
image data.  Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!

NOTE: libpng can be built with particular features disabled, if you see
compiler errors because the definition of one of the following flags has been
compiled out it is because libpng does not have the required support.  It is
possible, however, for the libpng configuration to enable the format on just
read or just write; in that case you may see an error at run time.  You can
guard against this by checking for the definition of:

   PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED

   PNG_FORMAT_FLAG_ALPHA    0x01 format with an alpha channel
   PNG_FORMAT_FLAG_COLOR    0x02 color format: otherwise grayscale
   PNG_FORMAT_FLAG_LINEAR   0x04 png_uint_16 channels else png_byte
   PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only
   PNG_FORMAT_FLAG_BGR      0x10 BGR colors, else order is RGB
   PNG_FORMAT_FLAG_AFIRST   0x20 alpha channel comes first

Supported formats are as follows.  Future versions of libpng may support more
formats; for compatibility with older versions simply check if the format
macro is defined using #ifdef.  These defines describe the in-memory layout
of the components of the pixels of the image.

First the single byte formats:

   PNG_FORMAT_GRAY 0
   PNG_FORMAT_GA   PNG_FORMAT_FLAG_ALPHA
   PNG_FORMAT_AG   (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST)
   PNG_FORMAT_RGB  PNG_FORMAT_FLAG_COLOR
   PNG_FORMAT_BGR  (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
   PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
   PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
   PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
   PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)

Then the linear 2-byte formats.  When naming these "Y" is used to
indicate a luminance (gray) channel.  The component order within the pixel
is always the same - there is no provision for swapping the order of the
components in the linear format.  The components are 16-bit integers in
the native byte order for your platform, and there is no provision for
swapping the bytes to a different endian condition.

   PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
   PNG_FORMAT_LINEAR_Y_ALPHA
      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA)
   PNG_FORMAT_LINEAR_RGB
      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR)
   PNG_FORMAT_LINEAR_RGB_ALPHA
      (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
      PNG_FORMAT_FLAG_ALPHA)

Color-mapped formats are obtained by calling png_image_{read,write}_colormap,
as appropriate after setting png_image::format to the format of the color-map
to be read or written.  Applications may check the value of
PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API.  The
format of the color-map may be extracted using the following macro.

   PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP)

PNG_IMAGE macros

These are convenience macros to derive information from a png_image
structure.  The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
actual image sample values - either the entries in the color-map or the
pixels in the image.  The PNG_IMAGE_PIXEL_ macros return corresponding values

src/Source/LibPNG/libpng.3  view on Meta::CPAN

for normal use and may result in writing an invalid PNG file.  See
zlib.h for more information on what these mean.

    #include zlib.h
    png_set_compression_strategy(png_ptr,
        strategy);

    png_set_compression_window_bits(png_ptr,
        window_bits);

    png_set_compression_method(png_ptr, method);

This controls the size of the IDAT chunks (default 8192):

    png_set_compression_buffer_size(png_ptr, size);

As of libpng version 1.5.4, additional APIs became
available to set these separately for non-IDAT
compressed chunks such as zTXt, iTXt, and iCCP:

    #include zlib.h
    #if PNG_LIBPNG_VER >= 10504
    png_set_text_compression_level(png_ptr, level);

    png_set_text_compression_mem_level(png_ptr, level);

    png_set_text_compression_strategy(png_ptr,
        strategy);

    png_set_text_compression_window_bits(png_ptr,
        window_bits);

    png_set_text_compression_method(png_ptr, method);
    #endif

.SS Controlling row filtering

If you want to control whether libpng uses filtering or not, which
filters are used, and how it goes about picking row filters, you
can call one of these functions.  The selection and configuration
of row filters can have a significant impact on the size and
encoding speed and a somewhat lesser impact on the decoding speed
of an image.  Filtering is enabled by default for RGB and grayscale
images (with and without alpha), but not for paletted images nor
for any images with bit depths less than 8 bits/pixel.

The 'method' parameter sets the main filtering method, which is
currently only '0' in the PNG 1.2 specification.  The 'filters'
parameter sets which filter(s), if any, should be used for each
scanline.  Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
to turn filtering on and off, respectively.

Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
ORed together with '|' to specify one or more filters to use.
These filters are described in more detail in the PNG specification.
If you intend to change the filter type during the course of writing
the image, you should start with flags set for all of the filters
you intend to use so that libpng can initialize its internal
structures appropriately for all of the filter types.  (Note that this
means the first row must always be adaptively filtered, because libpng
currently does not allocate the filter buffers until png_write_row()
is called for the first time.)

    filters = PNG_FILTER_NONE | PNG_FILTER_SUB
              PNG_FILTER_UP | PNG_FILTER_AVG |
              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.

.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:

src/Source/LibPNG/libpng.3  view on Meta::CPAN

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.

Starting in libpng-1.5.10, the user limits can be set en masse with the

src/Source/LibPNG/libpng.3  view on Meta::CPAN

    #    define PNG_FEATURE_SUPPORTED
    #  endif
    #endif

Comments appear with the leading "/*" at the same indentation as
the statement that follows the comment:

    /* Single-line comment */
    statement;

    /* This is a multiple-line
     * comment.
     */
    statement;

Very short comments can be placed after the end of the statement
to which they pertain:

    statement;    /* comment */

We don't use C++ style ("//") comments. We have, however,
used them in the past in some now-abandoned MMX assembler
code.

Functions and their curly braces are not indented, and
exported functions are marked with PNGAPI:

 /* This is a public function that is visible to
  * application programmers. It does thus-and-so.
  */
 void PNGAPI
 png_exported_function(png_ptr, png_info, foo)
 {
    body;
 }

The return type and decorations are placed on a separate line
ahead of the function name, as illustrated above.

The prototypes for all exported functions appear in png.h,
above the comment that says

    /* Maintainer: Put new public prototypes here ... */

We mark all non-exported functions with "/* PRIVATE */"":

 void /* PRIVATE */
 png_non_exported_function(png_ptr, png_info, foo)
 {
    body;
 }

The prototypes for non-exported functions (except for those in
pngtest) appear in pngpriv.h above the comment that says

  /* Maintainer: Put new private prototypes here ^ */

To avoid polluting the global namespace, the names of all exported
functions and variables begin with "png_", and all publicly visible C
preprocessor macros begin with "PNG".  We request that applications that
use libpng *not* begin any of their own symbols with either of these strings.

We put a space after the "sizeof" operator and we omit the
optional parentheses around its argument when the argument
is an expression, not a type name, and we always enclose the
sizeof operator, with its argument, in parentheses:

  (sizeof (png_uint_32))
  (sizeof array)

Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as
though it were a function.

Control keywords if, for, while, and switch are always followed by a space
to distinguish them from function calls, which have no trailing space. 

We put a space after each comma and after each semicolon
in "for" statements, and we put spaces before and after each
C binary operator and after "for" or "while", and before
"?".  We don't put a space between a typecast and the expression
being cast, nor do we put one between a function name and the
left parenthesis that follows it:

    for (i = 2; i > 0; \-\-i)
       y[i] = a(x) + (int)b;

We prefer #ifdef and #ifndef to #if defined() and #if !defined()
when there is only one macro being tested.  We always use parentheses
with "defined".

We prefer to express integers that are used as bit masks in hex format,
with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).

We prefer to use underscores in variable names rather than camelCase, except
for a few type names that we inherit from zlib.h.

We prefer "if (something != 0)" and "if (something == 0)"
over "if (something)" and if "(!something)", respectively.

We do not use the TAB character for indentation in the C sources.

Lines do not exceed 80 characters.

Other rules can be inferred by inspecting the libpng source.

.SH XVI. Y2K Compliance in libpng

December 22, 2014

Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.

This is your unofficial assurance that libpng from version 0.71 and
upward through 1.6.16 are Y2K compliant.  It is my belief that earlier
versions were also Y2K compliant.

Libpng only has two year fields.  One is a 2-byte unsigned integer
that will hold years up to 65535.  The other, which is deprecated,
holds the date in text format, and will hold years up to 9999.

The integer is