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