cheng/libpng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[libpng16] Revised INSTALL and libpng-manual.txt

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2014-03-16 20:29:11 -05:00
parent c2a15d01af
commit 7017c4078d
5 changed files with 1048 additions and 587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ANNOUNCE
View File

@ -1,5 +1,5 @@
Libpng 1.6.11beta01 - March 16, 2014
Libpng 1.6.11beta01 - March 17, 2014
This is not intended to be a public release. It will be replaced
within a few weeks by a public version or by another test version.
@ -26,7 +26,7 @@ Other information:
Changes since the last public release (1.6.10):
Version 1.6.11beta01 [March 16, 2014]
Version 1.6.11beta01 [March 17, 2014]
Use "if (value != 0)" instead of "if (value)" consistently.
Changed ZlibSrcDir from 1.2.5 to 1.2.8 in projects/vstudio.
Moved configuration information from the manual to the INSTALL file.

2
CHANGES
View File

@ -4875,7 +4875,7 @@ Version 1.6.10rc03 [March 4, 2014]
Version 1.6.10 [March 6, 2014]
No changes.
Version 1.6.11beta01 [March 16, 2014]
Version 1.6.11beta01 [March 17, 2014]
Use "if (value != 0)" instead of "if (value)" consistently.
Changed ZlibSrcDir from 1.2.5 to 1.2.8 in projects/vstudio.
Moved configuration information from the manual to the INSTALL file.

250
INSTALL
View File

@ -1,6 +1,27 @@
Installing libpng
Contents
I. Simple installation
II. Rebuilding the configure scripts
III. Using scripts/makefile*
IV. Using cmake
V. Directory structure
VI. Building with project files
VII. Building with makefiles
VIII. Configuring libpng for 16-bit platforms
IX. Configuring for DOS
X. Configuring for Medium Model
XI. Prepending a prefix to exported symbols
XII. Configuring for compiler xxx:
XIII Removing unwanted object code
XIV. Changes to the build and configuration of libpng in libpng-1.5.x
XV. Configuring libpng for multiprocessing
XVI. Other sources of information about libpng:
I. Simple installation
On Unix/Linux and similar systems, you can simply type
./configure [--prefix=/path]
@ -9,6 +30,8 @@ On Unix/Linux and similar systems, you can simply type
and ignore the rest of this document.
II. Rebuilding the configure scripts
If configure does not work on your system, or if you have a need to
change configure.ac or Makefile.am, and you have a reasonably
up-to-date set of tools, running ./autogen.sh in a git clone before
@ -24,6 +47,8 @@ aren't using any of the included pre-built scripts, you can do this:
make install
make check
III. Using scripts/makefile*
Instead, you can use one of the custom-built makefiles in the
"scripts" directory
@ -41,19 +66,37 @@ is not already on your system. zlib can usually be found
wherever you got libpng. zlib can be placed in another directory,
at the same level as libpng.
If your system already has a preinstalled zlib you will still need
to have access to the zlib.h and zconf.h include files that
correspond to the version of zlib that's installed.
If you wish to test with a particular zlib that is not first in the
standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS,
and LD_LIBRARY_PATH in your environment before running "make test"
or "make distcheck":
ZLIBLIB=/path/to/lib export ZLIBLIB
ZLIBINC=/path/to/include export ZLIBINC
CPPFLAGS="-I$ZLIBINC" export CPPFLAGS
LDFLAGS="-L$ZLIBLIB" export LDFLAGS
LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH
If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC
in your environment and type "make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test".
IV. Using cmake
If you want to use "cmake" (see www.cmake.org), type
cmake . -DCMAKE_INSTALL_PREFIX=/path
make
make install
If your system already has a preinstalled zlib you will still need
to have access to the zlib.h and zconf.h include files that
correspond to the version of zlib that's installed.
V. Directory structure
You can rename the directories that you downloaded (they
might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.5"
or "zlib125") so that you have directories called "zlib" and "libpng".
might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.7"
or "zlib127") so that you have directories called "zlib" and "libpng".
Your directory structure should look like this:
@ -71,6 +114,7 @@ Your directory structure should look like this:
depcomp, install-sh, mkinstalldirs, test-pngtest.sh
contrib
gregbook
libtests
pngminim
pngminus
pngsuite
@ -95,6 +139,8 @@ If the line endings in the files look funny, you may wish to get the other
distribution of libpng. It is available in both tar.gz (UNIX style line
endings) and zip (DOS style line endings) formats.
VI. Building with project files
If you are building libpng with MSVC, you can enter the
libpng projects\visualc6 or visualc71 directory and follow the instructions
in README.txt.
@ -103,6 +149,8 @@ Otherwise enter the zlib directory and follow the instructions in zlib/README,
then come back here and run "configure" or choose the appropriate
makefile.sys in the scripts directory.
VII. Building with makefiles
Copy the file (or files) that you need from the
scripts directory into this directory, for example
@ -130,6 +178,198 @@ do that, run "make install" in the zlib directory first if necessary).
Some also allow you to run "make test-installed" after you have
run "make install".
VIII. Configuring libpng for 16-bit platforms
You will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
IX. Configuring for DOS
For DOS users who only have access to the lower 640K, you will
have to limit zlib's memory usage via a png_set_compression_mem_level()
call. See zlib.h or zconf.h in the zlib library for more information.
X. Configuring for Medium Model
Libpng's support for medium model has been tested on most of the popular
compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
defined, and FAR gets defined to far in pngconf.h, and you should be
all set. Everything in the library (except for zlib's structure) is
expecting far data. You must use the typedefs with the p or pp on
the end for pointers (or at least look at them and be careful). Make
note that the rows of data are defined as png_bytepp, which is
an "unsigned char far * far *".
XI. Prepending a prefix to exported symbols
Starting with libpng-1.6.0, you can configure libpng (when using the
"configure" script) to prefix all exported symbols by means of the
configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
string beginning with a letter and containing only uppercase
and lowercase letters, digits, and the underscore (i.e., a C language
identifier). This creates a set of macros in pnglibconf.h, so this is
transparent to applications; their function calls get transformed by
the macros to use the modified names.
XII. Configuring for compiler xxx:
All includes for libpng are in pngconf.h. If you need to add, change
or delete an include, this is the place to do it.
The includes that are not needed outside libpng are placed in pngpriv.h,
which is only used by the routines inside libpng itself.
The files in libpng proper only include pngpriv.h and png.h, which
in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
As of libpng-1.5.0, pngpriv.h also includes three other private header
files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
that previously appeared in the public headers.
XIII. Removing unwanted object code
There are a bunch of #define's in pngconf.h that control what parts of
libpng are compiled. All the defines end in _SUPPORTED. If you are
never going to use a capability, you can change the #define to #undef
before recompiling libpng and save yourself code and data space, or
you can turn off individual capabilities with defines that begin with
PNG_NO_.
In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
You can also turn all of the transforms and ancillary chunk capabilities
off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four, along with directives to turn on any of the capabilities that
you do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
extra transformations but still leave the library fully capable of reading
and writing PNG files with all known public chunks. Use of the
PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
that is incapable of reading or writing ancillary chunks. If you are
not using the progressive reading capability, you can turn that off
with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
capability, which you'll still have).
All the reading and writing specific code are in separate files, so the
linker should only grab the files it needs. However, if you want to
make sure, or if you are building a stand alone library, all the
reading files start with "pngr" and all the writing files start with "pngw".
The files that don't match either (like png.c, pngtrans.c, etc.)
are used for both reading and writing, and always need to be included.
The progressive reader is in pngpread.c
If you are creating or distributing a dynamically linked library (a .so
or DLL file), you should not remove or disable any parts of the library,
as this will cause applications linked with different versions of the
library to fail if they call functions not available in your library.
The size of the library itself should not be an issue, because only
those sections that are actually used will be loaded into memory.
XIV. Changes to the build and configuration of libpng in libpng-1.5.x
Details of internal changes to the library code can be found in the CHANGES
file and in the GIT repository logs. These will be of no concern to the vast
majority of library users or builders; however, the few who configure libpng
to a non-default feature set may need to change how this is done.
There should be no need for library builders to alter build scripts if
these use the distributed build support - configure or the makefiles -
however, users of the makefiles may care to update their build scripts
to build pnglibconf.h where the corresponding makefile does not do so.
Building libpng with a non-default configuration has changed completely.
The old method using pngusr.h should still work correctly even though the
way pngusr.h is used in the build has been changed; however, library
builders will probably want to examine the changes to take advantage of
new capabilities and to simplify their build system.
A. Specific changes to library configuration capabilities
The library now supports a complete fixed point implementation and can
thus be used on systems that have no floating point support or very
limited or slow support. Previously gamma correction, an essential part
of complete PNG support, required reasonably fast floating point.
As part of this the choice of internal implementation has been made
independent of the choice of fixed versus floating point APIs and all the
missing fixed point APIs have been implemented.
The exact mechanism used to control attributes of API functions has
changed. A single set of operating system independent macro definitions
is used and operating system specific directives are defined in
pnglibconf.h
As part of this the mechanism used to choose procedure call standards on
those systems that allow a choice has been changed. At present this only
affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
running on Intel processors. As before, PNGAPI is defined where required
to control the exported API functions; however, two new macros, PNGCBAPI
and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
(PNGCAPI) for functions that must match a C library prototype (currently
only png_longjmp_ptr, which must match the C longjmp function.) The new
approach is documented in pngconf.h
Despite these changes, libpng 1.5.0 only supports the native C function
calling standard on those platforms tested so far (__cdecl on Microsoft
Windows). This is because the support requirements for alternative
calling conventions seem to no longer exist. Developers who find it
necessary to set PNG_API_RULE to 1 should advise the mailing list
(png-mng-implement) of this and library builders who use Openwatcom and
therefore set PNG_API_RULE to 2 should also contact the mailing list.
B. Changes to the configuration mechanism
Prior to libpng-1.5.0 library builders who needed to configure libpng
had either to modify the exported pngconf.h header file to add system
specific configuration or had to write feature selection macros into
pngusr.h and cause this to be included into pngconf.h by defining
PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
application built without PNG_USER_CONFIG defined would see the
unmodified, default, libpng API and thus would probably fail to link.
These mechanisms still work in the configure build and in any makefile
build that builds pnglibconf.h, although the feature selection macros
have changed somewhat as described above. In 1.5.0, however, pngusr.h is
processed only once, when the exported header file pnglibconf.h is built.
pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
build of pnglibconf.h and it is never included in an application build.
The rarely used alternative of adding a list of feature macros to the
CPPFLAGS setting in the build also still works; however, the macros will be
copied to pnglibconf.h and this may produce macro redefinition warnings
when the individual C files are compiled.
All configuration now only works if pnglibconf.h is built from
scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
(the original author of awk) maintains C source code of that awk and this
and all known later implementations (often called by subtly different
names - nawk and gawk for example) are adequate to build pnglibconf.h.
The Sun Microsystems (now Oracle) program 'awk' is an earlier version
and does not work; this may also apply to other systems that have a
functioning awk called 'nawk'.
Configuration options are now documented in scripts/pnglibconf.dfa. This
file also includes dependency information that ensures a configuration is
consistent; that is, if a feature is switched off dependent features are
also removed. As a recommended alternative to using feature macros in
pngusr.h a system builder may also define equivalent options in pngusr.dfa
(or, indeed, any file) and add that to the configuration by setting
DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
how to do this, and a case where pngusr.h is still required.
XV. Configuring libpng for multiprocessing
Libpng uses setjmp()/longjmp() for error handling. Unfortunately setjmp()
is known to be not thread-safe on some platforms and we don't know of
any platform where it is guaranteed to be thread-safe. Therefore, if
your application is going to be using multiple threads, you should
configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with
-DPNG_NO_SETJMP on your compile line, or with
#undef PNG_SETJMP_SUPPORTED
in your pnglibconf.h or pngusr.h.
XVI. Other sources of information about libpng:
Further information can be found in the README and libpng-manual.txt
files, in the individual makefiles, in png.h, and the manual pages
libpng.3 and png.5.

656
libpng-manual.txt
View File

@ -1,9 +1,9 @@
libpng-manual.txt - A description on how to use and modify libpng
libpng version 1.6.1beta01 - February 16, 2013
libpng version 1.6.11beta01 - March 17, 2014
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2013 Glenn Randers-Pehrson
Copyright (c) 1998-2014 Glenn Randers-Pehrson
This document is released under the libpng license.
For conditions of distribution and use, see the disclaimer
@ -11,9 +11,9 @@ libpng-manual.txt - A description on how to use and modify libpng
Based on:
libpng versions 0.97, January 1998, through 1.6.1beta01 - February 16, 2013
libpng versions 0.97, January 1998, through 1.6.11beta01 - March 17, 2014
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2013 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
@ -50,13 +50,11 @@ libpng-manual.txt - A description on how to use and modify libpng
I. Introduction
This file describes how to use and modify the PNG reference library
(known as libpng) for your own use. There are five sections to this
file: introduction, structures, reading, writing, and modification and
configuration notes for various special platforms. In addition to this
(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 install libpng.
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
@ -276,10 +274,10 @@ 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_USR_CONFIG
C. Configuration using PNG_USER_CONFIG
If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
pngusr.h will automatically be included before the options in
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.
@ -527,9 +525,14 @@ you can retrieve with
png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need
one or more of them. This behavior can be changed with the
png_set_keep_unknown_chunks() function, described below.
chunks which the callback does not handle will be saved when read. You can
cause them to be discarded by returning '1' ("handled") instead of '0'. This
behavior will change in libpng 1.7 and the default handling set by the
png_set_keep_unknown_chunks() function, described below, will be used when the
callback returns 0. If you want the existing behavior you should set the global
default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
@ -628,15 +631,17 @@ callback function:
...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
/* ignore all unknown chunks
* (use global setting "2" for libpng16 and earlier):
*/
png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
/* also ignore unused known chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
(int)sizeof(unused_chunks)/5);
(int)(sizeof unused_chunks)/5);
#endif
User limits
@ -707,12 +712,12 @@ value. You can also specify a default encoding for the PNG file in
case the required information is missing from the file. By default libpng
assumes that the PNG data matches your system, to keep this default call:
png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
png_set_gamma(png_ptr, screen_gamma, output_gamma);
or you can use the fixed point equivalent:
png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma,
PNG_FP_1/screen_gamma);
PNG_FP_1*output_gamma);
If you don't know the gamma for your system it is probably 2.2 - a good
approximation to the IEC standard for display systems (sRGB). If images are
@ -735,11 +740,75 @@ situations:
encoding.
You would use the linear (unencoded) value if you need to process the pixel
values further because this avoids the need to decode and reencode each
values further because this avoids the need to decode and re-encode each
component value whenever arithmetic is performed. A lot of graphics software
uses linear values for this reason, often with higher precision component values
to preserve overall accuracy.
The output_gamma value expresses how to decode the output values, not how
they are encoded. The values used correspond to the normal numbers used to
describe the overall gamma of a computer display system; for example 2.2 for
an sRGB conformant system. The values are scaled by 100000 in the _fixed
version of the API (so 220000 for sRGB.)
The inverse of the value is always used to provide a default for the PNG file
encoding if it has no gAMA chunk and if png_set_gamma() has not been called
to override the PNG gamma information.
When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode
opaque pixels however pixels with lower alpha values are not encoded,
regardless of the output gamma setting.
When the standard Porter Duff handling is requested with mode 1 the output
encoding is set to be linear and the output_gamma value is only relevant
as a default for input data that has no gamma information. The linear output
encoding will be overridden if png_set_gamma() is called - the results may be
highly unexpected!
The following numbers are derived from the sRGB standard and the research
behind it. sRGB is defined to be approximated by a PNG gAMA chunk value of
0.45455 (1/2.2) for PNG. The value implicitly includes any viewing
correction required to take account of any differences in the color
environment of the original scene and the intended display environment; the
value expresses how to *decode* the image for display, not how the original
data was *encoded*.
sRGB provides a peg for the PNG standard by defining a viewing environment.
sRGB itself, and earlier TV standards, actually use a more complex transform
(a linear portion then a gamma 2.4 power law) than PNG can express. (PNG is
limited to simple power laws.) By saying that an image for direct display on
an sRGB conformant system should be stored with a gAMA chunk value of 45455
(11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification
makes it possible to derive values for other display systems and
environments.
The Mac value is deduced from the sRGB based on an assumption that the actual
extra viewing correction used in early Mac display systems was implemented as
a power 1.45 lookup table.
Any system where a programmable lookup table is used or where the behavior of
the final display device characteristics can be changed requires system
specific code to obtain the current characteristic. However this can be
difficult and most PNG gamma correction only requires an approximate value.
By default, if png_set_alpha_mode() is not called, libpng assumes that all
values are unencoded, linear, values and that the output device also has a
linear characteristic. This is only very rarely correct - it is invariably
better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the
default if you don't know what the right answer is!
The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS
10.6) which used a correction table to implement a somewhat lower gamma on an
otherwise sRGB system.
Both these values are reserved (not simple gamma values) in order to allow
more precise correction internally in the future.
NOTE: the values can be passed to either the fixed or floating
point APIs, but the floating point API will also accept floating point
values.
The second thing you may need to tell libpng about is how your system handles
alpha channel information. Some, but not all, PNG files contain an alpha
channel. To display these files correctly you need to compose the data onto a
@ -764,11 +833,11 @@ by png_set_alpha_mode().
The mode is as follows:
PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red,
green and blue, or gray, components are gamma encoded color
values and are not premultiplied by the alpha value. The
alpha value is a linear measure of the contribution of the
pixel to the corresponding final output pixel.
PNG_ALPHA_PNG: The data is encoded according to the PNG
specification. Red, green and blue, or gray, components are
gamma encoded color values and are not premultiplied by the
alpha value. The alpha value is a linear measure of the
contribution of the pixel to the corresponding final output pixel.
You should normally use this format if you intend to perform
color correction on the color values; most, maybe all, color
@ -785,11 +854,35 @@ 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!)
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.
PNG_ALPHA_STANDARD: The data libpng produces
is encoded in the standard way
assumed by most correctly written graphics software.
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.
@ -818,9 +911,8 @@ 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
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.
@ -839,18 +931,16 @@ 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
an appropriate format to try if your software, or more
likely hardware, is totally broken, i.e., if it performs
linear arithmetic directly on gamma encoded values.
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.
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():
@ -881,6 +971,89 @@ 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
@ -988,7 +1161,7 @@ where row_pointers is an array of pointers to the pixel data for each row:
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/png_sizeof(png_byte))
if (height > PNG_UINT_32_MAX/(sizeof (png_byte)))
png_error (png_ptr,
"Image is too tall to process in memory");
@ -997,7 +1170,7 @@ row_pointers prior to calling png_read_png() with
"Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
height*png_sizeof(png_bytep));
height*(sizeof (png_bytep)));
for (int i=0; i<height, i++)
row_pointers[i]=NULL; /* security precaution */
@ -1211,7 +1384,7 @@ png_set_rgb_to_gray()).
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
srgb_intent - the rendering intent (PNG_INFO_sRGB)
The presence of the sRGB chunk
means that the pixel data is in the
sRGB color space. This chunk also
@ -2161,10 +2334,15 @@ how pngvalid.c does it.
Finishing a sequential read
After you are finished reading the image through the
low-level interface, you can finish reading the file. If you are
interested in comments or time, which may be stored either before or
after the image data, you should pass the separate png_info struct if
you want to keep the comments from before and after the image
low-level interface, you can finish reading the file.
If you want to use a different crc action for handling CRC errors in
chunks after the image data, you can call png_set_crc_action()
again at this point.
If you are interested in comments or time, which may be stored either
before or after the image data, you should pass the separate png_info
struct if you want to keep the comments from before and after the image
separate.
png_infop end_info = png_create_info_struct(png_ptr);
@ -2180,6 +2358,9 @@ separate.
If you are not interested, you should still call png_read_end()
but you can pass NULL, avoiding the need to create an end_info structure.
If you do this, libpng will not process any chunks after IDAT other than
skipping over them and perhaps (depending on whether you have called
png_set_crc_action) checking their CRCs while looking for the IEND chunk.
png_read_end(png_ptr, (png_infop)NULL);
@ -2284,7 +2465,7 @@ For a more compact example of reading a PNG image, see the file example.c.
Reading PNG files progressively
The progressive reader is slightly different then the non-progressive
The progressive reader is slightly different from the non-progressive
reader. Instead of calling png_read_info(), png_read_rows(), and
png_read_end(), you make one call to png_process_data(), which calls
callbacks when it has the info, a row, or the end of the image. You
@ -2455,7 +2636,7 @@ png_infop info_ptr;
png_progressive_combine_row(png_ptr, old_row,
new_row);
/* where old_row is what was displayed for
/* where old_row is what was displayed
previously for the row. Note that the first
pass (pass == 0, really) will completely cover
the old row, so the rows do not have to be
@ -3086,13 +3267,47 @@ a writeable buffer of at least 29 bytes.
Writing unknown chunks
You can use the png_set_unknown_chunks function to queue up chunks
for writing. You give it a chunk name, raw data, and a size; that's
all there is to it. The chunks will be written by the next following
png_write_info_before_PLTE, png_write_info, or png_write_end function.
Any chunks previously read into the info structure's unknown-chunk
list will also be written out in a sequence that satisfies the PNG
specification's ordering rules.
You can use the png_set_unknown_chunks function to queue up private chunks
for writing. You give it a chunk name, location, raw data, and a size. You
also must use png_set_keep_unknown_chunks() to ensure that libpng will
handle them. That's all there is to it. The chunks will be written by the
next following png_write_info_before_PLTE, png_write_info, or png_write_end
function, depending upon the specified location. Any chunks previously
read into the info structure's unknown-chunk list will also be written out
in a sequence that satisfies the PNG specification's ordering rules.
Here is an example of writing two private chunks, prVt and miNE:
#ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED
/* Set unknown chunk data */
png_unknown_chunk unk_chunk[2];
strcpy((char *) unk_chunk[0].name, "prVt";
unk_chunk[0].data = (unsigned char *) "PRIVATE DATA";
unk_chunk[0].size = strlen(unk_chunk[0].data)+1;
unk_chunk[0].location = PNG_HAVE_IHDR;
strcpy((char *) unk_chunk[1].name, "miNE";
unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA";
unk_chunk[1].size = strlen(unk_chunk[0].data)+1;
unk_chunk[1].location = PNG_AFTER_IDAT;
png_set_unknown_chunks(write_ptr, write_info_ptr,
unk_chunk, 2);
/* Needed because miNE is not safe-to-copy */
png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS,
(png_bytep) "miNE", 1);
# if PNG_LIBPNG_VER < 10600
/* Deal with unknown chunk location bug in 1.5.x and earlier */
png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR);
png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT);
# endif
# if PNG_LIBPNG_VER < 10500
/* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0,
* one before IDAT and another after IDAT, so don't use it; only use
* PNG_HAVE_IHDR location. This call resets the location previously
* set by assignment and png_set_unknown_chunk_location() for chunk 1.
*/
png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR);
# endif
#endif
The high-level write interface
@ -3496,7 +3711,7 @@ The simplified API, which became available in libpng-1.6.0, hides the details
of both libpng and the PNG file format itself.
It allows PNG files to be read into a very limited number of
in-memory bitmap formats or to be written from the same formats. If these
formats do not accomodate your needs then you can, and should, use the more
formats do not accommodate your needs then you can, and should, use the more
sophisticated APIs above - these support a wide variety of in-memory formats
and a wide variety of sophisticated transformations to those formats as well
as a wide variety of APIs to manipulate ancilliary information.
@ -3578,8 +3793,9 @@ 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. All
channels can be converted to the original value by dividing by 65535; all
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.
@ -3646,7 +3862,9 @@ First the single byte formats:
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.
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
@ -3711,7 +3929,7 @@ First the information about the samples.
*
* png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
*
* Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
* Alternatively, use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
* information from one of the png_image_begin_read_ APIs and dynamically
* allocate the required memory.
*/
@ -3740,9 +3958,16 @@ Information about the whole row, or whole image
row. For a color-mapped image this is the minimum number of bytes in a
row.
If you need the stride measured in bytes, row_stride_bytes is
PNG_IMAGE_ROW_STRIDE(image) * PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)
plus any padding bytes that your application might need, for example
to start the next row on a 4-byte boundary.
PNG_IMAGE_BUFFER_SIZE(image, row_stride)
Returns the size, in bytes, of an image buffer given a png_image and a row
stride - the number of components to leave space for in each row.
stride - the number of components to leave space for in each row. This
macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE
when the image has 2-byte components.
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
This indicates the the RGB values of the in-memory bitmap do not
@ -3871,14 +4096,11 @@ clears the newly allocated memory to zero; note that png_calloc(png_ptr, size)
is not the same as the calloc(number, size) function provided by stdlib.h.
There is limited support for certain systems with segmented memory
architectures and the types of pointers declared by png.h match this; you
will have to use appropriate pointers in your application. Since it is
unlikely that the method of handling memory allocation on a platform
will change between applications, these functions must be modified in
the library at compile time. If you prefer to use a different method
of allocating and freeing data, you can use png_create_read_struct_2() or
png_create_write_struct_2() to register your own functions as described
above. These functions also provide a void pointer that can be retrieved
via
will have to use appropriate pointers in your application. If you prefer
to use a different method of allocating and freeing data, you can use
png_create_read_struct_2() or png_create_write_struct_2() to register your
own functions as described above. These functions also provide a void
pointer that can be retrieved via
mem_ptr=png_get_mem_ptr(png_ptr);
@ -3987,9 +4209,12 @@ as warnings.
png_set_benign_errors (png_ptr, int allowed);
allowed: 0: (default) treat png_benign_error() an error.
allowed: 0: treat png_benign_error() as an error.
1: treat png_benign_error() as a warning.
As of libpng-1.6.0, the default condition is to treat benign errors as
warnings while reading and as errors while writing.
Custom chunks
If you need to read or write custom chunks, you may need to get deeper
@ -4018,29 +4243,6 @@ the simpler ones to get an idea of how they work. Try to find a similar
transformation to the one you want to add and copy off of it. More details
can be found in the comments inside the code itself.
Configuring for 16-bit platforms
You will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
Configuring for DOS
For DOS users who only have access to the lower 640K, you will
have to limit zlib's memory usage via a png_set_compression_mem_level()
call. See zlib.h or zconf.h in the zlib library for more information.
Configuring for Medium Model
Libpng's support for medium model has been tested on most of the popular
compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
defined, and FAR gets defined to far in pngconf.h, and you should be
all set. Everything in the library (except for zlib's structure) is
expecting far data. You must use the typedefs with the p or pp on
the end for pointers (or at least look at them and be careful). Make
note that the rows of data are defined as png_bytepp, which is
an "unsigned char far * far *".
Configuring for gui/windowing platforms:
You will need to write new error and warning functions that use the GUI
@ -4050,18 +4252,6 @@ in order to have them available during the structure initialization.
They can be changed later via png_set_error_fn(). On some compilers,
you may also have to change the memory allocators (png_malloc, etc.).
Configuring for compiler xxx:
All includes for libpng are in pngconf.h. If you need to add, change
or delete an include, this is the place to do it.
The includes that are not needed outside libpng are placed in pngpriv.h,
which is only used by the routines inside libpng itself.
The files in libpng proper only include pngpriv.h and png.h, which
in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
As of libpng-1.5.0, pngpriv.h also includes three other private header
files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
that previously appeared in the public headers.
Configuring zlib:
There are special functions to configure the compression. Perhaps the
@ -4201,46 +4391,6 @@ 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.
Removing unwanted object code
There are a bunch of #define's in pngconf.h that control what parts of
libpng are compiled. All the defines end in _SUPPORTED. If you are
never going to use a capability, you can change the #define to #undef
before recompiling libpng and save yourself code and data space, or
you can turn off individual capabilities with defines that begin with
PNG_NO_.
In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
You can also turn all of the transforms and ancillary chunk capabilities
off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four,
along with directives to turn on any of the capabilities that you do
want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
transformations but still leave the library fully capable of reading
and writing PNG files with all known public chunks. Use of the
PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
that is incapable of reading or writing ancillary chunks. If you are
not using the progressive reading capability, you can turn that off
with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
capability, which you'll still have).
All the reading and writing specific code are in separate files, so the
linker should only grab the files it needs. However, if you want to
make sure, or if you are building a stand alone library, all the
reading files start with "pngr" and all the writing files start with "pngw".
The files that don't match either (like png.c, pngtrans.c, etc.)
are used for both reading and writing, and always need to be included.
The progressive reader is in pngpread.c
If you are creating or distributing a dynamically linked library (a .so
or DLL file), you should not remove or disable any parts of the library,
as this will cause applications linked with different versions of the
library to fail if they call functions not available in your library.
The size of the library itself should not be an issue, because only
those sections that are actually used will be loaded into memory.
Requesting debug printout
The macro definition PNG_DEBUG can be used to request debugging
@ -4260,7 +4410,7 @@ 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\n", foo);
png_debug1(2, "foo=%d", foo);
is expanded to
@ -4278,17 +4428,6 @@ 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.
Prepending a prefix to exported symbols
Starting with libpng-1.6.0, you can configure libpng (when using the
"configure" script) to prefix all exported symbols by means of the
configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
string beginning with a letter and containing only uppercase
and lowercase letters, digits, and the underscore (i.e., a C language
identifier). This creates a set of macros in pnglibconf.h, so this is
transparent to applications; their function calls get transformed by
the macros to use the modified names.
VII. MNG support
The MNG specification (available at http://www.libpng.org/pub/mng) allows
@ -4351,6 +4490,9 @@ 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:
@ -4567,7 +4709,7 @@ 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 reenabled, but the function was renamed png_set_quantize() to
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
@ -4579,12 +4721,13 @@ 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 read or write was added at libpng
1.5.10. When an invalid index is found, 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
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);
@ -4683,7 +4826,10 @@ 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.
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
@ -4703,15 +4849,10 @@ 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.
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. libpng 1.5.0
is consistent with the implementation in 1.4.5 and 1.2.x (where the macro
did not exist.)
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
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
@ -4725,7 +4866,10 @@ 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.
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
@ -4747,57 +4891,8 @@ limits are now
png_user_chunk_cache_max 0 (unlimited) 128
png_user_chunk_malloc_max 0 (unlimited) 8,000,000
B. Changes to the build and configuration of libpng
Details of internal changes to the library code can be found in the CHANGES
file and in the GIT repository logs. These will be of no concern to the vast
majority of library users or builders; however, the few who configure libpng
to a non-default feature set may need to change how this is done.
There should be no need for library builders to alter build scripts if
these use the distributed build support - configure or the makefiles -
however, users of the makefiles may care to update their build scripts
to build pnglibconf.h where the corresponding makefile does not do so.
Building libpng with a non-default configuration has changed completely.
The old method using pngusr.h should still work correctly even though the
way pngusr.h is used in the build has been changed; however, library
builders will probably want to examine the changes to take advantage of
new capabilities and to simplify their build system.
B.1 Specific changes to library configuration capabilities
The library now supports a complete fixed point implementation and can
thus be used on systems that have no floating point support or very
limited or slow support. Previously gamma correction, an essential part
of complete PNG support, required reasonably fast floating point.
As part of this the choice of internal implementation has been made
independent of the choice of fixed versus floating point APIs and all the
missing fixed point APIs have been implemented.
The exact mechanism used to control attributes of API functions has
changed. A single set of operating system independent macro definitions
is used and operating system specific directives are defined in
pnglibconf.h
As part of this the mechanism used to choose procedure call standards on
those systems that allow a choice has been changed. At present this only
affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
running on Intel processors. As before, PNGAPI is defined where required
to control the exported API functions; however, two new macros, PNGCBAPI
and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
(PNGCAPI) for functions that must match a C library prototype (currently
only png_longjmp_ptr, which must match the C longjmp function.) The new
approach is documented in pngconf.h
Despite these changes, libpng 1.5.0 only supports the native C function
calling standard on those platforms tested so far (__cdecl on Microsoft
Windows). This is because the support requirements for alternative
calling conventions seem to no longer exist. Developers who find it
necessary to set PNG_API_RULE to 1 should advise the mailing list
(png-mng-implement) of this and library builders who use Openwatcom and
therefore set PNG_API_RULE to 2 should also contact the mailing list.
The png_set_option() function (and the "options" member of the png struct) was
added to libpng-1.5.15.
A new test program, pngvalid, is provided in addition to pngtest.
pngvalid validates the arithmetic accuracy of the gamma correction
@ -4873,46 +4968,6 @@ even though the default is to use the macros - this allows applications
to choose at app buildtime whether or not to use macros (previously
impossible because the functions weren't in the default build.)
B.2 Changes to the configuration mechanism
Prior to libpng-1.5.0 library builders who needed to configure libpng
had either to modify the exported pngconf.h header file to add system
specific configuration or had to write feature selection macros into
pngusr.h and cause this to be included into pngconf.h by defining
PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
application built without PNG_USER_CONFIG defined would see the
unmodified, default, libpng API and thus would probably fail to link.
These mechanisms still work in the configure build and in any makefile
build that builds pnglibconf.h, although the feature selection macros
have changed somewhat as described above. In 1.5.0, however, pngusr.h is
processed only once, when the exported header file pnglibconf.h is built.
pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
build of pnglibconf.h and it is never included in an application build.
The rarely used alternative of adding a list of feature macros to the
CFLAGS setting in the build also still works; however, the macros will be
copied to pnglibconf.h and this may produce macro redefinition warnings
when the individual C files are compiled.
All configuration now only works if pnglibconf.h is built from
scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
(the original author of awk) maintains C source code of that awk and this
and all known later implementations (often called by subtly different
names - nawk and gawk for example) are adequate to build pnglibconf.h.
The Sun Microsystems (now Oracle) program 'awk' is an earlier version
and does not work; this may also apply to other systems that have a
functioning awk called 'nawk'.
Configuration options are now documented in scripts/pnglibconf.dfa. This
file also includes dependency information that ensures a configuration is
consistent; that is, if a feature is switched off dependent features are
also removed. As a recommended alternative to using feature macros in
pngusr.h a system builder may also define equivalent options in pngusr.dfa
(or, indeed, any file) and add that to the configuration by setting
DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
how to do this, and a case where pngusr.h is still required.
XII. Changes to Libpng from version 1.5.x to 1.6.x
A "simplified API" has been added (see documentation in png.h and a simple
@ -4940,20 +4995,19 @@ symbols, using the PNG_PREFIX macro.
We no longer include string.h in png.h. The include statement has been moved
to pngpriv.h, where it is not accessible by applications. Applications that
need access to information in string.h must add an '#include "string.h"'
need access to information in string.h must add an '#include <string.h>'
directive. It does not matter whether this is placed prior to or after
the '"#include png.h"' directive.
the '#include "png.h"' directive.
The following API are now DEPRECATED:
png_info_init_3()
png_convert_to_rfc1123() which has been replaced
with png_convert_to_rfc1123_buffer()
png_data_freer()
png_malloc_default()
png_free_default()
png_reset_zstream()
The following has been removed:
The following have been removed:
png_get_io_chunk_name(), which has been replaced
with png_get_io_chunk_type(). The new
function returns a 32-bit integer instead of
@ -4970,8 +5024,25 @@ where "rp" indicates a "restricted pointer".
Error detection in some chunks has improved; in particular the iCCP chunk
reader now does pretty complete validation of the basic format. Some bad
profiles that were previously accepted are now rejected, in particular the
very old broken Microsoft/HP sRGB profile.
profiles that were previously accepted are now accepted with a warning or
rejected, depending upon the png_set_benign_errors() setting, in particular the
very old broken Microsoft/HP 3144-byte sRGB profile. The PNG spec requirement
that only grayscale profiles may appear in images with color type 0 or 4 and
that even if the image only contains gray pixels, only RGB profiles may appear
in images with color type 2, 3, or 6, is now enforced. The sRGB chunk
is allowed to appear in images with any color type.
Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained
an empty language field or an empty translated keyword. Both of these
are allowed by the PNG specification, so these warnings are no longer issued.
The library now issues an error if the application attempts to set a
transform after it calls png_read_update_info() or if it attempts to call
both png_read_update_info() and png_start_read_image() or to call either
of them more than once.
The default condition for benign_errors is now to treat benign errors as
warnings while reading and as errors while writing.
The library now issues a warning if both background processing and RGB to
gray are used when gamma correction happens. As with previous versions of
@ -4989,6 +5060,26 @@ The machine-generated configure files are no longer included in branches
libpng16 and later of the GIT repository. They continue to be included
in the tarball releases, however.
Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT
stream to set the size of the sliding window for reading instead of using the
default 32-kbyte sliding window size. It was discovered that there are
hundreds of PNG files in the wild that have incorrect CMF bytes that caused
libpng to issue a "too far back" error and reject the file. Libpng-1.6.3 and
later calculate their own safe CMF from the image dimensions, provide a way
to revert to the libpng-1.5.x behavior (ignoring the CMF bytes and using a
32-kbyte sliding window), by using
png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW,
PNG_OPTION_ON);
and provide a tool (contrib/tools/pngfix) for optimizing the CMF bytes
correctly.
Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong
length, which resulted in PNG files that cannot be read beyond the bad iTXt
chunk. This error was fixed in libpng-1.6.3, and a tool (called
contrib/tools/png-fix-itxt) has been added to the libpng distribution.
XIII. Detecting libpng
The png_get_io_ptr() function has been present since libpng-0.88, has never
@ -5005,11 +5096,11 @@ control. The git repository was built from old libpng-x.y.z.tar.gz files
going back to version 0.70. You can access the git repository (read only)
at
git://libpng.git.sourceforge.net/gitroot/libpng
git://git.code.sf.net/p/libpng/code
or you can browse it via "gitweb" at
or you can browse it with a web browser by selecting the "code" button at
http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
https://sourceforge.net/projects/libpng
Patches can be sent to glennrp at users.sourceforge.net or to
png-mng-implement at lists.sourceforge.net or you can upload them to
@ -5087,6 +5178,9 @@ exported functions are marked with PNGAPI:
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
@ -5134,7 +5228,8 @@ left parenthesis that follows it:
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.
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).
@ -5142,6 +5237,9 @@ 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.
@ -5150,13 +5248,13 @@ Other rules can be inferred by inspecting the libpng source.
XVI. Y2K Compliance in libpng
February 16, 2013
March 17, 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.1beta01 are Y2K compliant. It is my belief that earlier
upward through 1.6.11beta01 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

723
libpng.3
View File

File diff suppressed because it is too large Load Diff