1
===========================
2
PNG: The Definitive Guide
3
===========================
7
Chapters 13, 14 and 15 of "PNG: The Definitive Guide" discuss three free,
8
cross-platform demo programs that show how to use the libpng reference
9
library: rpng, rpng2 and wpng. rpng and rpng2 are viewers; the first is
10
a very simple example that that shows how a standard file-viewer might use
11
libpng, while the second is designed to process streaming data and shows
12
how a web browser might be written. wpng is a simple command-line program
13
that reads binary PGM and PPM files (the ``raw'' grayscale and RGB subsets
14
of PBMPLUS/NetPBM) and converts them to PNG.
16
The source code for all three demo programs currently compiles under
17
Unix, OpenVMS, and 32-bit Windows. (Special thanks to Martin Zinser,
18
zinser@decus.de, for making the necessary changes for OpenVMS and for
19
providing an appropriate build script.) Build instructions can be
25
README.w32 additional Windows-specific information
26
LICENSE terms of distribution and reuse (BSD-like)
28
Makefile.unx Unix makefile
29
Makefile.w32 Windows (MSVC) makefile
30
makevms.com OpenVMS build script
32
rpng-win.c Windows front end for the basic viewer
33
rpng-x.c X Window System (Unix, OpenVMS) front end
34
readpng.c generic back end for the basic viewer
35
readpng.h header file for the basic viewer
37
rpng2-win.c Windows front end for the progressive viewer
38
rpng2-x.c X front end for the progressive viewer
39
readpng2.c generic back end for the progressive viewer
40
readpng2.h header file for the progressive viewer
42
wpng.c generic (text) front end for the converter
43
writepng.c generic back end for the converter
44
writepng.h header file for the converter
46
toucan.png transparent PNG for testing (by Stefan Schneider)
48
Note that the programs are designed to be functional, but their primary
49
purpose is to demonstrate how to use libpng to add PNG support to other
50
programs. As such, their user interfaces are crude and definitely not
51
intended for everyday use.
53
Please see http://www.cdrom.com/pub/png/pngbook.html for further infor-
54
mation and links to the latest version of the source code, and Chapters
55
13-15 of the book for detailed discussion of the three programs.
65
- zlib ftp://ftp.cdrom.com/pub/infozip/zlib/zlib.html
66
- libpng http://www.cdrom.com/pub/png/pngcode.html
67
- pngbook http://www.cdrom.com/pub/png/book/sources.html
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.
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.
84
Unpack the latest pngbook sources (which should correspond to this
85
README file) into a directory and change into that directory.
87
Copy Makefile.unx to Makefile and edit the PNG* and Z* variables
88
appropriately (possibly also the X* variables if necessary).
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.
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.
105
For MSVC, set up the necessary environment variables by invoking
107
%devstudio%\vc\bin\vcvars32.bat
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.
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.
125
Do the build by typing
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. Unlike the Unix versions, the two windowed programs
132
(rpng and rpng2) do not display a usage screen when invoked without
133
command-line arguments; see README.w32 for brief help or the book for
134
details. Note that the programs use the Unix-style "-" character to
135
specify options, instead of the more common DOS/Windows "/" character.
140
Unpack the pngbook sources into a subdirectory and change into that
143
Edit makevms.com appropriately, specifically the zpath and pngpath
148
To run the programs, they probably first need to be set up as "foreign
149
symbols," with "disk" and "dir" set appropriately:
151
$ rpng == "$disk:[dir]rpng-x.exe"
152
$ rpng2 == "$disk:[dir]rpng2-x.exe"
153
$ wpng == "$disk:[dir]wpng.exe"
155
All three will print a basic usage screen when run without any command-
156
line arguments; see the book for more details. Note that the options
157
style is Unix-like, i.e., preceded by "-" rather than "/".
160
RUNNING THE PROGRAMS: (VERY) BRIEF INTRO
162
rpng is a simple PNG viewer that can display transparent PNGs with a
163
specified background color; for example,
165
rpng -bgcolor #ff0000 toucan.png
167
would display the image with a red background. rpng2 is a progressive
168
viewer that simulates a web browser in some respects; it can display
169
images against either a background color or a dynamically generated
170
background image. For example:
172
rpng2 -bgpat 16 toucan.png
174
wpng is a purely command-line image converter from binary PBMPLUS/NetPBM
175
format (.pgm or .ppm) to PNG; for example,
177
wpng -time < toucan.ppm > toucan.png
179
would convert the specified PPM file (using redirection) to PNG, auto-
180
matically setting the PNG modification-time chunk.
182
All options can be abbreviated to the shortest unique value; for example,
183
"-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma.
added
removed
gdchart0.94c/gd-1.8.3/libpng-1.0.8/contrib/gregbook/README
