view release on metacpan or  search on metacpan

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

 This document is released under the libpng license.
 For conditions of distribution and use, see the disclaimer
 and license in png.h

 Based on:

 libpng versions 0.97, January 1998, through 1.6.16 - December 22, 2014
 Updated and distributed by Glenn Randers-Pehrson
 Copyright (c) 1998-2014 Glenn Randers-Pehrson

 libpng 1.0 beta 6 - version 0.96 - May 28, 1997
 Updated and distributed by Andreas Dilger
 Copyright (c) 1996, 1997 Andreas Dilger

 libpng 1.0 beta 2 - version 0.88 - January 26, 1996
 For conditions of distribution and use, see copyright
 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
 Schalnat, Group 42, Inc.

 Updated/rewritten per request in the libpng FAQ
 Copyright (c) 1995, 1996 Frank J. T. Wojcik
 December 18, 1995 & January 20, 1996

 TABLE OF CONTENTS

    I. Introduction
   II. Structures
  III. Reading
   IV. Writing
    V. Simplified API
   VI. Modifying/Customizing libpng
  VII. MNG support
 VIII. Changes to Libpng from version 0.88
   IX. Changes to Libpng from version 1.0.x to 1.2.x
    X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
   XI. Changes to Libpng from version 1.4.x to 1.5.x
  XII. Changes to Libpng from version 1.5.x to 1.6.x
 XIII. Detecting libpng
  XIV. Source code repository
   XV. Coding style
  XVI. Y2K Compliance in libpng

I. Introduction

This file describes how to use and modify the PNG reference library
(known as libpng) for your own use.  In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need.  We assume that libpng is already installed; see the
INSTALL file for instructions on how to configure and install libpng.

For examples of libpng usage, see the files "example.c", "pngtest.c",
and the files in the "contrib" directory, all of which are included in
the libpng distribution.

Libpng was written as a companion to the PNG specification, as a way
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.

The PNG specification (second edition), November 2003, is available as
a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
<http://www.w3.org/TR/2003/REC-PNG-20031110/
The W3C and ISO documents have identical technical content.

The PNG-1.2 specification is available at
<http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
to the PNG specification (second edition) but has some additional material.

The PNG-1.0 specification is available
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.

Some additional chunks are described in the special-purpose public chunks
documents at <http://www.libpng.org/pub/png/documents/>.

Other information
about PNG, and the latest version of libpng, can be found at the PNG home
page, <http://www.libpng.org/pub/png/>.

Most users will not have to modify the library significantly; advanced
users may want to modify it more.  All attempts were made to make it as
complete as possible, while keeping the code easy to understand.
Currently, this library only supports C.  Support for other languages
is being considered.

Libpng has been designed to handle multiple sessions at one time,
to be easily modifiable, to be portable to the vast majority of
machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
to use.  The ultimate goal of libpng is to promote the acceptance of
the PNG file format in whatever way possible.  While there is still
work to be done (see the TODO file), libpng should cover the
majority of the needs of its users.

Libpng uses zlib for its compression and decompression of PNG files.
Further information about zlib, and the latest version of zlib, can
be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
The zlib compression utility is a general purpose utility that is
useful for more than PNG files, and can be used without libpng.
See the documentation delivered with zlib for more details.
You can usually find the source files for the zlib utility wherever you
find the libpng source files.

Libpng is thread safe, provided the threads are using different
instances of the structures.  Each thread should have its own
png_struct and png_info instances, and thus its own image.
Libpng does not protect itself against two threads using the
same instance of a structure.

II. Structures

There are two main structures that are important to libpng, png_struct
and png_info.  Both are internal structures that are no longer exposed
in the libpng interface (as of libpng 1.5.0).

The png_info structure is designed to provide information about the
PNG file.  At one time, the fields of png_info were intended to be
directly accessible to the user.  However, this tended to cause problems
with applications using dynamically loaded libraries, and as a result
a set of interface functions for png_info (the png_get_*() and png_set_*()
functions) was developed, and direct access to the png_info fields was
deprecated..

The png_struct structure is the object used by the library to decode a
single image.  As of 1.5.0 this structure is also not exposed.

Almost all libpng APIs require a pointer to a png_struct as the first argument.
Many (in particular the png_set and png_get APIs) also require a pointer

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

API has the same name as the floating point one with "_fixed" appended.
The actual range of values permitted in the APIs is frequently less than
the full range of (png_fixed_point) (-21474 to +21474).  When APIs require
a non-negative argument the type is recorded as png_uint_32 above.  Consult
the header file and the text below for more information.

Special care must be take with sCAL chunk handling because the chunk itself
uses non-integral values encoded as strings containing decimal floating point
numbers.  See the comments in the header file.

Configuration

The main header file function declarations are frequently protected by C
preprocessing directives of the form:

    #ifdef PNG_feature_SUPPORTED
    declare-function
    #endif
    ...
    #ifdef PNG_feature_SUPPORTED
    use-function
    #endif

The library can be built without support for these APIs, although a
standard build will have all implemented APIs.  Application programs
should check the feature macros before using an API for maximum
portability.  From libpng 1.5.0 the feature macros set during the build
of libpng are recorded in the header file "pnglibconf.h" and this file
is always included by png.h.

If you don't need to change the library configuration from the default, skip to
the next section ("Reading").

Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
of the build project files in the 'projects' directory simply copy
scripts/pnglibconf.h.prebuilt to pnglibconf.h.  This means that these build
systems do not permit easy auto-configuration of the library - they only
support the default configuration.

The easiest way to make minor changes to the libpng configuration when
auto-configuration is supported is to add definitions to the command line
using (typically) CPPFLAGS.  For example:

CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC

will change the internal libpng math implementation for gamma correction and
other arithmetic calculations to fixed point, avoiding the need for fast
floating point support.  The result can be seen in the generated pnglibconf.h -
make sure it contains the changed feature macro setting.

If you need to make more extensive configuration changes - more than one or two
feature macro settings - you can either add -DPNG_USER_CONFIG to the build
command line and put a list of feature macro settings in pngusr.h or you can set
DFA_XTRA (a makefile variable) to a file containing the same information in the
form of 'option' settings.

A. Changing pnglibconf.h

A variety of methods exist to build libpng.  Not all of these support
reconfiguration of pnglibconf.h.  To reconfigure pnglibconf.h it must either be
rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.

Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
pnglibconf.h and changing the lines defining the supported features, paying
very close attention to the 'option' information in scripts/pnglibconf.dfa
that describes those features and their requirements.  This is easy to get
wrong.

B. Configuration using DFA_XTRA

Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
variant such as 'nawk' or 'gawk', is available.  The configure build will
automatically find an appropriate awk and build pnglibconf.h.
The scripts/pnglibconf.mak file contains a set of make rules for doing the
same thing if configure is not used, and many of the makefiles in the scripts
directory use this approach.

When rebuilding simply write a new file containing changed options and set
DFA_XTRA to the name of this file.  This causes the build to append the new file
to the end of scripts/pnglibconf.dfa.  The pngusr.dfa file should contain lines
of the following forms:

everything = off

This turns all optional features off.  Include it at the start of pngusr.dfa to
make it easier to build a minimal configuration.  You will need to turn at least
some features on afterward to enable either reading or writing code, or both.

option feature on
option feature off

Enable or disable a single feature.  This will automatically enable other
features required by a feature that is turned on or disable other features that
require a feature which is turned off.  Conflicting settings will cause an error
message to be emitted by awk.

setting feature default value

Changes the default value of setting 'feature' to 'value'.  There are a small
number of settings listed at the top of pnglibconf.h, they are documented in the
source code.  Most of these values have performance implications for the library
but most of them have no visible effect on the API.  Some can also be overridden
from the API.

This method of building a customized pnglibconf.h is illustrated in
contrib/pngminim/*.  See the "$(PNGCONF):" target in the makefile and
pngusr.dfa in these directories.

C. Configuration using PNG_USER_CONFIG

If -DPNG_USER_CONFIG is added to the CPPFLAGS when pnglibconf.h is built,
the file pngusr.h will automatically be included before the options in
scripts/pnglibconf.dfa are processed.  Your pngusr.h file should contain only
macro definitions turning features on or off or setting settings.

Apart from the global setting "everything = off" all the options listed above
can be set using macros in pngusr.h:

#define PNG_feature_SUPPORTED

is equivalent to:

option feature on