blob: 972635ddb04cd7e2675c77c3e802dededf5ae47f [file] [log] [blame]
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -06001README for libpng 1.0.5s - February 18, 2000 (shared library 2.1)
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -06002See the note about version numbers near the top of png.h
Andreas Dilger02ad0ef1997-01-17 01:34:35 -06003
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -06004See INSTALL for instructions on how to install libpng.
Glenn Randers-Pehrson2687fcc1998-01-07 20:54:20 -06005
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -06006Libpng comes in two distribution formats. Get libpng-*.tar.gz if you
7want UNIX-style line endings in the text files, or lpng*.zip if you want
8DOS-style line endings.
9
Glenn Randers-Pehrson860ab2b1999-10-14 07:43:10 -050010Version 0.89 was the first official release of libpng. Don't let the
11fact that it's the first release fool you. The libpng library has been in
12extensive use and testing since mid-1995. By late 1997 it had
13finally gotten to the stage where there hadn't been significant
Glenn Randers-Pehrsonb6ce43d1998-01-01 07:13:13 -060014changes to the API in some time, and people have a bad feeling about
Glenn Randers-Pehrson860ab2b1999-10-14 07:43:10 -050015libraries with versions < 1.0. Version 1.0.0 was released in
16March 1998.
Glenn Randers-Pehrsonb6ce43d1998-01-01 07:13:13 -060017
Andreas Dilger47a0c421997-05-16 02:46:07 -050018****
19Note that some of the changes to the png_info structure render this
20version of the library binary incompatible with libpng-0.89 or
21earlier versions if you are using a shared library. The type of the
22"filler" parameter for png_set_filler() has changed from png_byte to
Glenn Randers-Pehrson2687fcc1998-01-07 20:54:20 -060023png_uint_32, which will affect shared-library applications that use
Andreas Dilger47a0c421997-05-16 02:46:07 -050024this function.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060025
Andreas Dilger47a0c421997-05-16 02:46:07 -050026To avoid problems with changes to the internals of png_info_struct,
27new APIs have been made available in 0.95 to avoid direct application
28access to info_ptr. These functions are the png_set_<chunk> and
29png_get_<chunk> functions. These functions should be used when
30accessing/storing the info_struct data, rather than manipulating it
31directly, to avoid such problems in the future.
Glenn Randers-Pehrsonb6ce43d1998-01-01 07:13:13 -060032
33It is important to note that the APIs do not make current programs
Glenn Randers-Pehrson2687fcc1998-01-07 20:54:20 -060034that access the info struct directly incompatible with the new
Glenn Randers-Pehrsonb6ce43d1998-01-01 07:13:13 -060035library. However, it is strongly suggested that new programs use
Glenn Randers-Pehrson860ab2b1999-10-14 07:43:10 -050036the new APIs (as shown in example.c and pngtest.c), and older programs
37be converted to the new format, to facilitate upgrades in the future.
Andreas Dilger47a0c421997-05-16 02:46:07 -050038****
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060039
Andreas Dilger47a0c421997-05-16 02:46:07 -050040Additions since 0.90 include the ability to compile libpng as a
41Windows DLL, and new APIs for accessing data in the info struct.
42Experimental functions include the ability to set weighting and cost
43factors for row filter selection, direct reads of integers from buffers
44on big-endian processors that support misaligned data access, faster
45methods of doing alpha composition, and more accurate 16->8 bit color
46conversion.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060047
Andreas Dilger47a0c421997-05-16 02:46:07 -050048The additions since 0.89 include the ability to read from a PNG stream
49which has had some (or all) of the signature bytes read by the calling
50application. This also allows the reading of embedded PNG streams that
51do not have the PNG file signature. As well, it is now possible to set
52the library action on the detection of chunk CRC errors. It is possible
53to set different actions based on whether the CRC error occurred in a
54critical or an ancillary chunk.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060055
56The changes made to the library, and bugs fixed are based on discussions
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -050057on the PNG implementation mailing list <png-implement@ccrc.wustl.edu>
Glenn Randers-Pehrson860ab2b1999-10-14 07:43:10 -050058and not on material submitted privately to Guy, Andreas, or Glenn. They will
59forward any good suggestions to the list.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060060
61For a detailed description on using libpng, read libpng.txt. For
Andreas Dilger47a0c421997-05-16 02:46:07 -050062examples of libpng in a program, see example.c and pngtest.c. For usage
63information and restrictions (what little they are) on libpng, see
64png.h. For a description on using zlib (the compression library used by
65libpng) and zlib's restrictions, see zlib.h
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060066
Andreas Dilger47a0c421997-05-16 02:46:07 -050067I have included a general makefile, as well as several machine and
68compiler specific ones, but you may have to modify one for your own needs.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060069
70You should use zlib 1.0.4 or later to run this, but it MAY work with
71versions as old as zlib 0.95. Even so, there are bugs in older zlib
72versions which can cause the output of invalid compression streams for
73some images. You will definitely need zlib 1.0.4 or later if you are
74taking advantage of the MS-DOS "far" structure allocation for the small
75and medium memory models. You should also note that zlib is a
76compression library that is useful for more things than just PNG files.
77You can use zlib as a drop-in replacement for fread() and fwrite() if
78you are so inclined.
79
80zlib should be available at the same place that libpng is.
81If not, it should be at ftp.uu.net in /graphics/png
82Eventually, it will be at ftp.uu.net in /pub/archiving/zip/zlib
83
84You may also want a copy of the PNG specification. It is available
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -060085as an RFC and a W3C Recommendation. Failing
Andreas Dilger02ad0ef1997-01-17 01:34:35 -060086these resources you can try ftp.uu.net in the /graphics/png directory.
87
88This code is currently being archived at ftp.uu.net in the
89/graphics/png directory, and on CompuServe, Lib 20 (PNG SUPPORT)
90at GO GRAPHSUP. If you can't find it in any of those places,
91e-mail me, and I'll help you find it.
92
93If you have any code changes, requests, problems, etc., please e-mail
94them to me. Also, I'd appreciate any make files or project files,
95and any modifications you needed to make to get libpng to compile,
96along with a #define variable to tell what compiler/system you are on.
97If you needed to add transformations to libpng, or wish libpng would
98provide the image in a different way, drop me a note (and code, if
99possible), so I can consider supporting the transformation.
100Finally, if you get any warning messages when compiling libpng
101(note: not zlib), and they are easy to fix, I'd appreciate the
102fix. Please mention "libpng" somewhere in the subject line. Thanks.
103
104This release was created and will be supported by myself (of course
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600105based in a large way on Guy's and Andreas' earlier work), and the PNG group.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600106
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500107randeg@alum.rpi.edu
108png-implement@ccrc.wustl.edu
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600109
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600110You can't reach Guy, the original libpng author, at the addresses
Glenn Randers-Pehrson46f61e21998-01-30 21:45:12 -0600111given in previous versions of this document. He and Andreas will read mail
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600112addressed to the png-implement list, however.
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600113
114Please do not send general questions about PNG. Send them to
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600115the address in the specification (png-group@w3.org). At the same
116time, please do not send libpng questions to that address, send them to me
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500117or to png-implement@ccrc.wustl.edu. I'll
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600118get them in the end anyway. If you have a question about something
119in the PNG specification that is related to using libpng, send it
120to me. Send me any questions that start with "I was using libpng,
121and ...". If in doubt, send questions to me. I'll bounce them
122to others, if necessary.
123
124Please do not send suggestions on how to change PNG. We have
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600125been discussing PNG for three years now, and it is official and
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600126finished. If you have suggestions for libpng, however, I'll
127gladly listen. Even if your suggestion is not used for version
1281.0, it may be used later.
129
130Files in this distribution:
131
Andreas Dilger47a0c421997-05-16 02:46:07 -0500132 CHANGES => Description of changes between libpng versions
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600133 README => This file
134 TODO => Things not implemented in the current library
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600135 build.bat => MS-DOS batch file for Borland compiler
136 descrip.mms => VMS project file
137 example.c => Example code for using libpng functions
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600138 libpng.3 => manual page for libpng
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600139 libpng.txt => Description of libpng and its functions
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600140 libpngpf.3 => manual page for libpng's private functions
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600141 png.5 => manual page for the PNG format
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600142 png.c => Basic interface functions common to library
143 png.h => Library function and interface declarations
144 pngconf.h => System specific library configuration
145 pngerror.c => Error/warning message I/O functions
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600146 pngget.c => Functions for retrieving info from struct
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600147 pngmem.c => Memory handling functions
148 pngpread.c => Progressive reading functions
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600149 pngread.c => Read data/helper high-level functions
150 pngrio.c => Lowest-level data read I/O functions
151 pngrtran.c => Read data transformation functions
152 pngrutil.c => Read data utility functions
Andreas Dilger47a0c421997-05-16 02:46:07 -0500153 pngset.c => Functions for storing data into the info_struct
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600154 pngtest.c => Library test program
155 pngtest.png => Library test sample image
156 pngtrans.c => Common data transformation functions
157 pngwio.c => Lowest-level write I/O functions
158 pngwrite.c => High-level write functions
159 pngwtran.c => Write data transformations
160 pngwutil.c => Write utility functions
Glenn Randers-Pehrson860ab2b1999-10-14 07:43:10 -0500161 contrib => Contributions
162 gregbook => source code for PNG reading and writing, from
163 Greg Roelofs' "PNG: The Definitive Guide",
164 O'Reilly, 1999
Glenn Randers-Pehrson6d8f3b01999-10-23 08:39:18 -0500165 pngminus => Simple pnm2png and png2pnm programs
166 pngsuite => Test images
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600167 scripts => Directory containing scripts for building libpng:
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500168 descrip.mms => VMS makefile for MMS or MMK
169 makefile.std => Generic UNIX makefile
170 makefile.knr => Archaic UNIX Makefile that converts files with
171 ansi2knr (Requires ansi2knr.c from
172 ftp://ftp.cs.wisc.edu/ghost)
173 makefile.dec => DEC Alpha UNIX makefile
174 makefile.hpux => HPUX (10.20 and 11.00) makefile
175 makefile.sgi => Silicon Graphics IRIX makefile
176 makefile.sunos => Sun makefile
177 makefile.solaris => Solaris 2.X makefile
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600178 (gcc, creates libpng.so.2.1.0.5s)
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500179 makefile.linux => Linux/ELF makefile
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600180 (gcc, creates libpng.so.2.1.0.5s)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600181 makefile.gcmmx => Linux/ELF makefile (gcc, creates
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600182 libpng.so.2.1.0.5s, uses assembler code
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600183 tuned for Intel MMX platform)
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500184 makefile.sco => For SCO OSr5 ELF and Unixware 7 with Native cc
185 makefile.mips => MIPS makefile
186 makefile.acorn => Acorn makefile
187 makefile.amiga => Amiga makefile
188 smakefile.ppc => AMIGA smakefile for SAS C V6.58/7.00 PPC
189 compiler (Requires SCOPTIONS, copied from
190 scripts/SCOPTIONS.ppc)
191 makefile.atari => Atari makefile
192 makefile.beos => BEOS makefile for X86
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600193 makefile.borland => Borland makefile (uses bcc)
194 makefile.bd32 => To make a png32bd.dll with Borland C++ 4.5
195 makefile.turboc3 => Turbo C 3.0 makefile
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500196 build.bat => MS-DOS batch file for Borland compiler
197 makefile.dj2 => DJGPP 2 makefile
198 makefile.msc => Microsoft C makefile
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500199 makefile.vcawin32 => makefile for Microsoft Visual C++ 5.0 and
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600200 later (uses assembler code tuned for Intel MMX
201 platform)
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500202 makefile.vcwin32 => makefile for Microsoft Visual C++ 4.0 and
203 later (does not use assembler code)
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500204 makefile.os2 => OS/2 Makefile (gcc and emx, requires pngos2.def)
205 pngos2.def => OS/2 module definition file used by makefile.os2
206 makefile.watcom => Watcom 10a+ Makefile, 32-bit flat memory model
207 makevms.com => VMS build script
Glenn Randers-Pehrsonf8b008c1999-09-18 10:54:36 -0500208 pngdef.pas => Defines for a png32bd.dll with Borland C++ 4.5
209 SCOPTIONS.ppc => Used with smakefile.ppc
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600210
211Good luck, and happy coding.
212
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600213-Glenn Randers-Pehrson
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500214 Internet: randeg@alum.rpi.edu
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600215 Web: http://www.rpi.edu/~randeg/index.html
216
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600217-Andreas Eric Dilger
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600218 Internet: adilger@enel.ucalgary.ca
Andreas Dilger47a0c421997-05-16 02:46:07 -0500219 Web: http://www-mddsp.enel.ucalgary.ca/People/adilger/
Andreas Dilger02ad0ef1997-01-17 01:34:35 -0600220
221-Guy Eric Schalnat
Glenn Randers-Pehrsonc4a2ae61998-01-16 22:06:18 -0600222 (formerly of Group 42, Inc)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600223 Internet: gschal@infinet.com