README
1 ===========================
2 PNG: The Definitive Guide
3 ===========================
4
5 Source Code
6
7Chapters 13, 14 and 15 of "PNG: The Definitive Guide" discuss three free,
8cross-platform demo programs that show how to use the libpng reference
9library: rpng, rpng2 and wpng. rpng and rpng2 are viewers; the first is
10a very simple example that that shows how a standard file-viewer might use
11libpng, while the second is designed to process streaming data and shows
12how a web browser might be written. wpng is a simple command-line program
13that reads binary PGM and PPM files (the ``raw'' grayscale and RGB subsets
14of PBMPLUS/NetPBM) and converts them to PNG.
15
16The source code for all three demo programs currently compiles under
17Unix, OpenVMS, and 32-bit Windows. (Special thanks to Martin Zinser,
18zinser@decus.de, for making the necessary changes for OpenVMS and for
19providing an appropriate build script.) Build instructions can be found
20below.
21
22Files:
23
24 README this file
25 LICENSE terms of distribution and reuse (BSD-like)
26
27 Makefile.unx Unix makefile
28 Makefile.w32 Windows (MSVC) makefile
29 makevms.com OpenVMS build script
30
31 rpng-win.c Windows front end for the basic viewer
32 rpng-x.c X Window System (Unix, OpenVMS) front end
33 readpng.c generic back end for the basic viewer
34 readpng.h header file for the basic viewer
35
36 rpng2-win.c Windows front end for the progressive viewer
37 rpng2-x.c X front end for the progressive viewer
38 readpng2.c generic back end for the progressive viewer
39 readpng2.h header file for the progressive viewer
40
41 wpng.c generic (text) front end for the converter
42 writepng.c generic back end for the converter
43 writepng.h header file for the converter
44
45 toucan.png transparent PNG for testing (by Stefan Schneider)
46
47Note that, although the programs are designed to be functional, their
48primary purpose is to illustrate how to use libpng to add PNG support to
49other programs. As such, their user interfaces are crude and definitely
50are not intended for everyday use.
51
52Please see http://www.libpng.org/pub/png/pngbook.html for further infor-
53mation and links to the latest version of the source code, and Chapters
5413-15 of the book for detailed discussion of the three programs.
55
56Greg Roelofs
57newt@pobox.com
5830 June 2001
59
60
61BUILD INSTRUCTIONS
62
63 - Prerequisites (in order of compilation):
64
65 - zlib http://www.gzip.org/zlib/
66 - libpng http://www.libpng.org/pub/png/libpng.html
67 - pngbook http://www.libpng.org/pub/png/book/sources.html
68
69 The pngbook demo programs are explicitly designed to demonstrate proper
70 coding techniques for using the libpng reference library. As a result,
71 you need to download and build both zlib (on which libpng depends) and
72 libpng. A common build setup is to place the zlib, libpng and pngbook
73 subdirectory trees ("folders") in the same parent directory. Then the
74 libpng build can refer to files in ../zlib (or ..\zlib or [-.zlib]),
75 and similarly for the pngbook build.
76
77 Note that all three packages are designed to be built from a command
78 line by default; those who wish to use a graphical or other integrated
79 development environments are on their own.
80
81
82 - Unix:
83
84 Unpack the latest pngbook sources (which should correspond to this
85 README file) into a directory and change into that directory.
86
87 Copy Makefile.unx to Makefile and edit the PNG* and Z* variables
88 appropriately (possibly also the X* variables if necessary).
89
90 make
91
92 There is no "install" target, so copy the three executables somewhere
93 in your path or run them from the current directory. All three will
94 print a basic usage screen when run without any command-line arguments;
95 see the book for more details.
96
97
98 - Windows:
99
100 Unpack the latest pngbook sources (which should correspond to this
101 README file) into a folder, open a "DOS shell" or "command prompt"
102 or equivalent command-line window, and cd into the folder where you
103 unpacked the source code.
104
105 For MSVC, set up the necessary environment variables by invoking
106
107 %devstudio%\vc\bin\vcvars32.bat
108
109 where where %devstudio% is the installation directory for MSVC /
110 DevStudio. If you get "environment out of space" errors under 95/98,
111 create a desktop shortcut with "c:\windows\command.com /e:4096" as
112 the program command line and set the working directory to the pngbook
113 directory. Then double-click to open the new DOS-prompt window with
114 a bigger environment and retry the commands above.
115
116 Copy Makefile.w32 to Makefile and edit the PNGPATH and ZPATH variables
117 appropriately (possibly also the "INC" and "LIB" variables if needed).
118 Note that the names of the dynamic and static libpng and zlib libraries
119 used in the makefile may change in later releases of the libraries.
120 Also note that, as of libpng version 1.0.5, MSVC DLL builds do not work.
121 This makefile therefore builds statically linked executables, but if
122 the DLL problems ever get fixed, uncommenting the appropriate PNGLIB
123 and ZLIB lines will build dynamically linked executables instead.
124
125 Do the build by typing
126
127 nmake
128
129 The result should be three executables: rpng-win.exe, rpng2-win.exe,
130 and wpng.exe. Copy them somewhere in your PATH or run them from the
131 current folder. Like the Unix versions, the two windowed programs
132 (rpng and rpng2) now display a usage screen in a console window when
133 invoked without command-line arguments; this is new behavior as of
134 the June 2001 release. Note that the programs use the Unix-style "-"
135 character to specify options, instead of the more common DOS/Windows
136 "/" character. (For example: "rpng2-win -bgpat 4 foo.png", not
137 "rpng2-win /bgpat 4 foo.png")
138
139
140 - OpenVMS:
141
142 Unpack the pngbook sources into a subdirectory and change into that
143 subdirectory.
144
145 Edit makevms.com appropriately, specifically the zpath and pngpath
146 variables.
147
148 @makevms
149
150 To run the programs, they probably first need to be set up as "foreign
151 symbols," with "disk" and "dir" set appropriately:
152
153 $ rpng == "$disk:[dir]rpng-x.exe"
154 $ rpng2 == "$disk:[dir]rpng2-x.exe"
155 $ wpng == "$disk:[dir]wpng.exe"
156
157 All three will print a basic usage screen when run without any command-
158 line arguments; see the book for more details. Note that the options
159 style is Unix-like, i.e., preceded by "-" rather than "/".
160
161
162RUNNING THE PROGRAMS: (VERY) BRIEF INTRO
163
164 rpng is a simple PNG viewer that can display transparent PNGs with a
165 specified background color; for example,
166
167 rpng -bgcolor #ff0000 toucan.png
168
169 would display the image with a red background. rpng2 is a progressive
170 viewer that simulates a web browser in some respects; it can display
171 images against either a background color or a dynamically generated
172 background image. For example:
173
174 rpng2 -bgpat 16 toucan.png
175
176 wpng is a purely command-line image converter from binary PBMPLUS/NetPBM
177 format (.pgm or .ppm) to PNG; for example,
178
179 wpng -time < toucan.ppm > toucan.png
180
181 would convert the specified PPM file (using redirection) to PNG, auto-
182 matically setting the PNG modification-time chunk.
183
184 All options can be abbreviated to the shortest unique value; for example,
185 "-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma.
186
