| 1 |
README for libpng version 1.6.54 |
| 2 |
================================ |
| 3 |
|
| 4 |
See the note about version numbers near the top of `png.h`. |
| 5 |
See `INSTALL` for instructions on how to install libpng. |
| 6 |
|
| 7 |
Libpng comes in several distribution formats. Get `libpng-*.tar.gz` |
| 8 |
or `libpng-*.tar.xz` if you want UNIX-style line endings in the text |
| 9 |
files, or `lpng*.7z` or `lpng*.zip` if you want DOS-style line endings. |
| 10 |
|
| 11 |
For a detailed description on using libpng, read `libpng-manual.txt`. |
| 12 |
For examples of libpng in a program, see `example.c` and `pngtest.c`. |
| 13 |
For usage information and restrictions (what little they are) on libpng, |
| 14 |
see `png.h`. For a description on using zlib (the compression library |
| 15 |
used by libpng) and zlib's restrictions, see `zlib.h`. |
| 16 |
|
| 17 |
You should use zlib 1.0.4 or later to run this, but it _may_ work with |
| 18 |
versions as old as zlib 0.95. Even so, there are bugs in older zlib |
| 19 |
versions which can cause the output of invalid compression streams for |
| 20 |
some images. |
| 21 |
|
| 22 |
You should also note that zlib is a compression library that is useful |
| 23 |
for more things than just PNG files. You can use zlib as a drop-in |
| 24 |
replacement for `fread()` and `fwrite()`, if you are so inclined. |
| 25 |
|
| 26 |
zlib should be available at the same place that libpng is, or at |
| 27 |
https://zlib.net . |
| 28 |
|
| 29 |
You may also want a copy of the PNG specification. It is available |
| 30 |
as an RFC, a W3C Recommendation, and an ISO/IEC Standard. You can find |
| 31 |
these at http://www.libpng.org/pub/png/pngdocs.html . |
| 32 |
|
| 33 |
This code is currently being archived at https://libpng.sourceforge.io |
| 34 |
in the download area, and at http://libpng.download/src . |
| 35 |
|
| 36 |
This release, based in a large way on Glenn's, Guy's and Andreas' |
| 37 |
earlier work, was created and will be supported by myself and the PNG |
| 38 |
development group. |
| 39 |
|
| 40 |
Send comments, corrections and commendations to `png-mng-implement` |
| 41 |
at `lists.sourceforge.net`. (Subscription is required; visit |
| 42 |
https://lists.sourceforge.net/lists/listinfo/png-mng-implement |
| 43 |
to subscribe.) |
| 44 |
|
| 45 |
Send general questions about the PNG specification to `png-mng-misc` |
| 46 |
at `lists.sourceforge.net`. (Subscription is required; visit |
| 47 |
https://lists.sourceforge.net/lists/listinfo/png-mng-misc |
| 48 |
to subscribe.) |
| 49 |
|
| 50 |
Historical notes |
| 51 |
---------------- |
| 52 |
|
| 53 |
The libpng library has been in extensive use and testing since mid-1995. |
| 54 |
Version 0.89, published a year later, was the first official release. |
| 55 |
By late 1997, it had finally gotten to the stage where there hadn't |
| 56 |
been significant changes to the API in some time, and people have a bad |
| 57 |
feeling about libraries with versions below 1.0. Version 1.0.0 was |
| 58 |
released in March 1998. |
| 59 |
|
| 60 |
Note that some of the changes to the `png_info` structure render this |
| 61 |
version of the library binary incompatible with libpng-0.89 or |
| 62 |
earlier versions if you are using a shared library. The type of the |
| 63 |
`filler` parameter for `png_set_filler()` has changed from `png_byte` |
| 64 |
to `png_uint_32`, which will affect shared-library applications that |
| 65 |
use this function. |
| 66 |
|
| 67 |
To avoid problems with changes to the internals of the `info_struct`, |
| 68 |
new APIs have been made available in 0.95 to avoid direct application |
| 69 |
access to `info_ptr`. These functions are the `png_set_<chunk>` and |
| 70 |
`png_get_<chunk>` functions. These functions should be used when |
| 71 |
accessing/storing the `info_struct` data, rather than manipulating it |
| 72 |
directly, to avoid such problems in the future. |
| 73 |
|
| 74 |
It is important to note that the APIs did not make current programs |
| 75 |
that access the info struct directly incompatible with the new |
| 76 |
library, through libpng-1.2.x. In libpng-1.4.x, which was meant to |
| 77 |
be a transitional release, members of the `png_struct` and the |
| 78 |
`info_struct` can still be accessed, but the compiler will issue a |
| 79 |
warning about deprecated usage. Since libpng-1.5.0, direct access |
| 80 |
to these structs is not allowed, and the definitions of the structs |
| 81 |
reside in private `pngstruct.h` and `pnginfo.h` header files that are |
| 82 |
not accessible to applications. It is strongly suggested that new |
| 83 |
programs use the new APIs (as shown in `example.c` and `pngtest.c`), |
| 84 |
and older programs be converted to the new format, to facilitate |
| 85 |
upgrades in the future. |
| 86 |
|
| 87 |
The additions since 0.89 include the ability to read from a PNG stream |
| 88 |
which has had some (or all) of the signature bytes read by the calling |
| 89 |
application. This also allows the reading of embedded PNG streams that |
| 90 |
do not have the PNG file signature. As well, it is now possible to set |
| 91 |
the library action on the detection of chunk CRC errors. It is possible |
| 92 |
to set different actions based on whether the CRC error occurred in a |
| 93 |
critical or an ancillary chunk. |
| 94 |
|
| 95 |
The additions since 0.90 include the ability to compile libpng as a |
| 96 |
Windows DLL, and new APIs for accessing data in the `info_struct`. |
| 97 |
Experimental functions included the ability to set weighting and cost |
| 98 |
factors for row filter selection, direct reads of integers from buffers |
| 99 |
on big-endian processors that support misaligned data access, faster |
| 100 |
methods of doing alpha composition, and more accurate 16-to-8 bit color |
| 101 |
conversion. Some of these experimental functions, such as the weighted |
| 102 |
filter heuristics, have since been removed. |
| 103 |
|
| 104 |
Files included in this distribution |
| 105 |
----------------------------------- |
| 106 |
|
| 107 |
ANNOUNCE => Announcement of this version, with recent changes |
| 108 |
AUTHORS => List of contributing authors |
| 109 |
CHANGES => Description of changes between libpng versions |
| 110 |
INSTALL => Instructions to install libpng |
| 111 |
LICENSE => License to use and redistribute libpng |
| 112 |
README => This file |
| 113 |
TODO => Things not implemented in the current library |
| 114 |
TRADEMARK => Trademark information |
| 115 |
example.c => Example code for using libpng functions |
| 116 |
libpng.3 => Manual page for libpng (includes libpng-manual.txt) |
| 117 |
libpng-manual.txt => Description of libpng and its functions |
| 118 |
libpngpf.3 => Manual page for libpng's private functions (deprecated) |
| 119 |
png.5 => Manual page for the PNG format |
| 120 |
png.c => Basic interface functions common to library |
| 121 |
png.h => Library function and interface declarations (public) |
| 122 |
pngpriv.h => Library function and interface declarations (private) |
| 123 |
pngconf.h => System specific library configuration (public) |
| 124 |
pngstruct.h => png_struct declaration (private) |
| 125 |
pnginfo.h => png_info struct declaration (private) |
| 126 |
pngdebug.h => debugging macros (private) |
| 127 |
pngerror.c => Error/warning message I/O functions |
| 128 |
pngget.c => Functions for retrieving info from struct |
| 129 |
pngmem.c => Memory handling functions |
| 130 |
pngbar.png => PNG logo, 88x31 |
| 131 |
pngnow.png => PNG logo, 98x31 |
| 132 |
pngpread.c => Progressive reading functions |
| 133 |
pngread.c => Read data/helper high-level functions |
| 134 |
pngrio.c => Lowest-level data read I/O functions |
| 135 |
pngrtran.c => Read data transformation functions |
| 136 |
pngrutil.c => Read data utility functions |
| 137 |
pngset.c => Functions for storing data into the info_struct |
| 138 |
pngtest.c => Library test program |
| 139 |
pngtest.png => Library test sample image |
| 140 |
pngtrans.c => Common data transformation functions |
| 141 |
pngwio.c => Lowest-level write I/O functions |
| 142 |
pngwrite.c => High-level write functions |
| 143 |
pngwtran.c => Write data transformations |
| 144 |
pngwutil.c => Write utility functions |
| 145 |
arm/ => Optimized code for ARM Neon |
| 146 |
intel/ => Optimized code for INTEL SSE2 |
| 147 |
loongarch/ => Optimized code for LoongArch LSX |
| 148 |
mips/ => Optimized code for MIPS MSA and MIPS MMI |
| 149 |
powerpc/ => Optimized code for PowerPC VSX |
| 150 |
riscv/ => Optimized code for the RISC-V platform |
| 151 |
ci/ => Scripts for continuous integration |
| 152 |
contrib/ => External contributions |
| 153 |
arm-neon/ => Optimized code for the ARM-NEON platform |
| 154 |
mips-msa/ => Optimized code for the MIPS-MSA platform |
| 155 |
powerpc-vsx/ => Optimized code for the POWERPC-VSX platform |
| 156 |
examples/ => Examples of libpng usage |
| 157 |
gregbook/ => Source code for PNG reading and writing, from |
| 158 |
"PNG: The Definitive Guide" by Greg Roelofs, |
| 159 |
O'Reilly, 1999 |
| 160 |
libtests/ => Test programs |
| 161 |
pngexif/ => Program to inspect the EXIF information in PNG files |
| 162 |
pngminim/ => Minimal decoder, encoder, and progressive decoder |
| 163 |
programs demonstrating the use of pngusr.dfa |
| 164 |
pngminus/ => Simple pnm2png and png2pnm programs |
| 165 |
pngsuite/ => Test images |
| 166 |
riscv-rvv/ => Optimized code for the RISC-V Vector platform |
| 167 |
testpngs/ => Test images |
| 168 |
tools/ => Various tools |
| 169 |
visupng/ => VisualPng, a Windows viewer for PNG images |
| 170 |
projects/ => Project files and workspaces for various IDEs |
| 171 |
owatcom/ => OpenWatcom project |
| 172 |
visualc71/ => Microsoft Visual C++ 7.1 workspace |
| 173 |
vstudio/ => Microsoft Visual Studio workspace |
| 174 |
scripts/ => Scripts and makefiles for building libpng |
| 175 |
(see scripts/README.txt for the complete list) |
| 176 |
tests/ => Test scripts |
| 177 |
|
| 178 |
Good luck, and happy coding! |
| 179 |
|
| 180 |
* Cosmin Truta (current maintainer, since 2018) |
| 181 |
* Glenn Randers-Pehrson (former maintainer, 1998-2018) |
| 182 |
* Andreas Eric Dilger (former maintainer, 1996-1997) |
| 183 |
* Guy Eric Schalnat (original author and former maintainer, 1995-1996) |
| 184 |
(formerly of Group 42, Inc.) |