diff options
Diffstat (limited to 'contrib/gregbook/README')
| -rw-r--r-- | contrib/gregbook/README | 231 |
1 files changed, 181 insertions, 50 deletions
diff --git a/contrib/gregbook/README b/contrib/gregbook/README index fa3871a7d..a8bbc2874 100644 --- a/contrib/gregbook/README +++ b/contrib/gregbook/README @@ -1,52 +1,183 @@ -PNG: The Definitive Guide: Source Code + =========================== + PNG: The Definitive Guide + =========================== -Chapters 13, 14 and 15 of PNG: The Definitive Guide discuss three + Source Code + +Chapters 13, 14 and 15 of "PNG: The Definitive Guide" discuss three free, cross-platform demo programs that show how to use the libpng reference -library: rpng, rpng2 and wpng. rpng and rpng2 are viewers; the first is a -very simple example that that shows how a standard file-viewer might use -libpng, while the second is designed to process streaming data and shows how -a web browser might be written. wpng is a simple command-line program that -reads binary PPM files (the ``raw'' RGB subset of NetPBM) and converts them -to PNG. - -The source code for all three demo programs currently compiles only under -Unix and 32-bit Windows. It has been tested with gcc 2.7.2.3 under Linux and -Solaris and with Microsoft Visual C++ 5.0 under Windows 95. Brief -instructions for compiling the programs are included at the top of the -makefiles; makefile.unx is the Unix version, and makefile.w32 is (you -guessed it!) the version for 32-bit Windows. libpng and zlib are required. - ----------------------------------------------------------------------------- - -License - -The source code to the demo programs may be used and distributed freely -(even if you didn't buy the book--but feel free to do so at any time), -subject to the terms of the following BSD-like license: - - Copyright (c) 1998-1999 Greg Roelofs. All rights reserved. - - This software is provided "as is," without warranty of any kind, - express or implied. In no event shall the author or contributors - be held liable for any damages arising in any way from the use of - this software. - - Permission is granted to anyone to use this software for any - purpose, including commercial applications, and to alter it and - redistribute it freely, subject to the following restrictions: - - 1. Redistributions of source code must retain the above - copyright notice, disclaimer, and this list of conditions. - 2. Redistributions in binary form must reproduce the above - copyright notice, disclaimer, and this list of conditions in - the documentation and/or other materials provided with the - distribution. - 3. All advertising materials mentioning features or use of this - software must display the following acknowledgment: - - This product includes software developed by Greg Roelofs - and contributors for the book, "PNG: The Definitive - Guide," published by O'Reilly and Associates. - ----------------------------------------------------------- -http://www.cdrom.com/pub/png/book/sources.html +library: rpng, rpng2 and wpng. rpng and rpng2 are viewers; the first is +a very simple example that that shows how a standard file-viewer might use +libpng, while the second is designed to process streaming data and shows +how a web browser might be written. wpng is a simple command-line program +that reads binary PGM and PPM files (the ``raw'' grayscale and RGB subsets +of PBMPLUS/NetPBM) and converts them to PNG. + +The source code for all three demo programs currently compiles under +Unix, OpenVMS, and 32-bit Windows. (Special thanks to Martin Zinser, +zinser@decus.de, for making the necessary changes for OpenVMS and for +providing an appropriate build script.) Build instructions can be +found below. + +Files: + + README this file + README.w32 additional Windows-specific information + LICENSE terms of distribution and reuse (BSD-like) + + Makefile.unx Unix makefile + Makefile.w32 Windows (MSVC) makefile + makevms.com OpenVMS build script + + rpng-win.c Windows front end for the basic viewer + rpng-x.c X Window System (Unix, OpenVMS) front end + readpng.c generic back end for the basic viewer + readpng.h header file for the basic viewer + + rpng2-win.c Windows front end for the progressive viewer + rpng2-x.c X front end for the progressive viewer + readpng2.c generic back end for the progressive viewer + readpng2.h header file for the progressive viewer + + wpng.c generic (text) front end for the converter + writepng.c generic back end for the converter + writepng.h header file for the converter + + toucan.png transparent PNG for testing (by Stefan Schneider) + +Note that the programs are designed to be functional, but their primary +purpose is to demonstrate how to use libpng to add PNG support to other +programs. As such, their user interfaces are crude and definitely not +intended for everyday use. + +Please see http://www.cdrom.com/pub/png/pngbook.html for further infor- +mation and links to the latest version of the source code, and Chapters +13-15 of the book for detailed discussion of the three programs. + +Greg Roelofs +19 March 2000 + + +BUILD INSTRUCTIONS + + - Prerequisites: + + - zlib ftp://ftp.cdrom.com/pub/infozip/zlib/zlib.html + - libpng http://www.cdrom.com/pub/png/pngcode.html + - pngbook http://www.cdrom.com/pub/png/book/sources.html + + The pngbook demo programs are explicitly designed to demonstrate proper + coding techniques for using the libpng reference library. As a result, + you need to download and build both zlib (on which libpng depends) and + libpng. A common build setup is to place the zlib, libpng and pngbook + subdirectory trees ("folders") in the same parent directory. Then the + libpng build can refer to files in ../zlib (or ..\zlib or [-.zlib]), + and similarly for the pngbook build. + + Note that all three packages are designed to be built from a command + line by default; those who wish to use a graphical or other integrated + development environments are on their own. + + + - Unix: + + Unpack the latest pngbook sources (which should correspond to this + README file) into a directory and change into that directory. + + Copy Makefile.unx to Makefile and edit the PNG* and Z* variables + appropriately (possibly also the X* variables if necessary). + + make + + There is no "install" target, so copy the three executables somewhere + in your path or run them from the current directory. All three will + print a basic usage screen when run without any command-line arguments; + see the book for more details. + + + - Windows: + + Unpack the latest pngbook sources (which should correspond to this + README file) into a folder, open a "DOS shell" or "command prompt" + or equivalent command-line window, and cd into the folder where you + unpacked the source code. + + For MSVC, set up the necessary environment variables by invoking + + %devstudio%\vc\bin\vcvars32.bat + + where where %devstudio% is the installation directory for MSVC / + DevStudio. If you get "environment out of space" errors under 95/98, + create a desktop shortcut with "c:\windows\command.com /e:4096" as + the program command line and set the working directory to the pngbook + directory. Then double-click to open the new DOS-prompt window with + a bigger environment and retry the commands above. + + Copy Makefile.w32 to Makefile and edit the PNGPATH and ZPATH variables + appropriately (possibly also the "INC" and "LIB" variables if needed). + Note that the names of the dynamic and static libpng and zlib libraries + used in the makefile may change in later releases of the libraries. + Also note that, as of libpng version 1.0.5, MSVC DLL builds do not work. + This makefile therefore builds statically linked executables, but if + the DLL problems ever get fixed, uncommenting the appropriate PNGLIB + and ZLIB lines will build dynamically linked executables instead. + + Do the build by typing + + nmake + + The result should be three executables: rpng-win.exe, rpng2-win.exe, + and wpng.exe. Copy them somewhere in your PATH or run them from the + current folder. Unlike the Unix versions, the two windowed programs + (rpng and rpng2) do not display a usage screen when invoked without + command-line arguments; see README.w32 for brief help or the book for + details. Note that the programs use the Unix-style "-" character to + specify options, instead of the more common DOS/Windows "/" character. + + + - OpenVMS: + + Unpack the pngbook sources into a subdirectory and change into that + subdirectory. + + Edit makevms.com appropriately, specifically the zpath and pngpath + variables. + + @makevms + + To run the programs, they probably first need to be set up as "foreign + symbols," with "disk" and "dir" set appropriately: + + $ rpng == "$disk:[dir]rpng-x.exe" + $ rpng2 == "$disk:[dir]rpng2-x.exe" + $ wpng == "$disk:[dir]wpng.exe" + + All three will print a basic usage screen when run without any command- + line arguments; see the book for more details. Note that the options + style is Unix-like, i.e., preceded by "-" rather than "/". + + +RUNNING THE PROGRAMS: (VERY) BRIEF INTRO + + rpng is a simple PNG viewer that can display transparent PNGs with a + specified background color; for example, + + rpng -bgcolor #ff0000 toucan.png + + would display the image with a red background. rpng2 is a progressive + viewer that simulates a web browser in some respects; it can display + images against either a background color or a dynamically generated + background image. For example: + + rpng2 -bgpat 16 toucan.png + + wpng is a purely command-line image converter from binary PBMPLUS/NetPBM + format (.pgm or .ppm) to PNG; for example, + + wpng -time < toucan.ppm > toucan.png + + would convert the specified PPM file (using redirection) to PNG, auto- + matically setting the PNG modification-time chunk. + + All options can be abbreviated to the shortest unique value; for example, + "-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma. |