view release on metacpan or  search on metacpan

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

    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

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

    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

   png_set_check_for_invalid_index(png_ptr, allowed);

      allowed  - one of
                 0: disable benign error (accept the
                    invalid data without warning).
                 1: enable benign error (treat the
                    invalid data as an error or a
                    warning).

If the error is ignored, or if png_benign_error() treats it as a warning,
any invalid pixels are decoded as opaque black by the decoder and written
as-is by the encoder.

Retrieving the maximum palette index found was added at libpng-1.5.15.
This statement must appear after png_read_png() or png_read_image() while
reading, and after png_write_png() or png_write_image() while writing.

   int max_palette = png_get_palette_max(png_ptr, info_ptr);

This will return the maximum palette index found in the image, or "\-1" if
the palette was not checked, or "0" if no palette was found.  Note that this
does not account for any palette index used by ancillary chunks such as the
bKGD chunk; you must check those separately to determine the maximum
palette index actually used.

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