671242f350d172e106580348e24bab66b0d7e6a5vboxsync ===========================
671242f350d172e106580348e24bab66b0d7e6a5vboxsync PNG: The Definitive Guide
671242f350d172e106580348e24bab66b0d7e6a5vboxsync ===========================
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Source Code
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncChapters 13, 14 and 15 of "PNG: The Definitive Guide" discuss three free,
671242f350d172e106580348e24bab66b0d7e6a5vboxsynccross-platform demo programs that show how to use the libpng reference
671242f350d172e106580348e24bab66b0d7e6a5vboxsynclibrary: rpng, rpng2 and wpng. rpng and rpng2 are viewers; the first is
671242f350d172e106580348e24bab66b0d7e6a5vboxsynca very simple example that that shows how a standard file-viewer might use
671242f350d172e106580348e24bab66b0d7e6a5vboxsynclibpng, while the second is designed to process streaming data and shows
671242f350d172e106580348e24bab66b0d7e6a5vboxsynchow a web browser might be written. wpng is a simple command-line program
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncthat reads binary PGM and PPM files (the ``raw'' grayscale and RGB subsets
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncof PBMPLUS/NetPBM) and converts them to PNG.
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncThe source code for all three demo programs currently compiles under
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncUnix, OpenVMS, and 32-bit Windows. (Special thanks to Martin Zinser,
671242f350d172e106580348e24bab66b0d7e6a5vboxsynczinser@decus.de, for making the necessary changes for OpenVMS and for
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncproviding an appropriate build script.) Build instructions can be found
671242f350d172e106580348e24bab66b0d7e6a5vboxsync README this file
671242f350d172e106580348e24bab66b0d7e6a5vboxsync LICENSE terms of distribution and reuse (BSD-like)
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Makefile.unx Unix makefile
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Makefile.w32 Windows (MSVC) makefile
671242f350d172e106580348e24bab66b0d7e6a5vboxsync makevms.com OpenVMS build script
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng-win.c Windows front end for the basic viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng-x.c X Window System (Unix, OpenVMS) front end
671242f350d172e106580348e24bab66b0d7e6a5vboxsync readpng.c generic back end for the basic viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync readpng.h header file for the basic viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng2-win.c Windows front end for the progressive viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng2-x.c X front end for the progressive viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync readpng2.c generic back end for the progressive viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync readpng2.h header file for the progressive viewer
671242f350d172e106580348e24bab66b0d7e6a5vboxsync wpng.c generic (text) front end for the converter
671242f350d172e106580348e24bab66b0d7e6a5vboxsync writepng.c generic back end for the converter
671242f350d172e106580348e24bab66b0d7e6a5vboxsync writepng.h header file for the converter
671242f350d172e106580348e24bab66b0d7e6a5vboxsync toucan.png transparent PNG for testing (by Stefan Schneider)
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncNote that, although the programs are designed to be functional, their
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncprimary purpose is to illustrate how to use libpng to add PNG support to
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncother programs. As such, their user interfaces are crude and definitely
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncare not intended for everyday use.
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncPlease see http://www.libpng.org/pub/png/pngbook.html for further infor-
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncmation and links to the latest version of the source code, and Chapters
671242f350d172e106580348e24bab66b0d7e6a5vboxsync13-15 of the book for detailed discussion of the three programs.
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncGreg Roelofs
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncnewt@pobox.com
671242f350d172e106580348e24bab66b0d7e6a5vboxsync30 June 2001
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncBUILD INSTRUCTIONS
671242f350d172e106580348e24bab66b0d7e6a5vboxsync - Prerequisites (in order of compilation):
671242f350d172e106580348e24bab66b0d7e6a5vboxsync - pngbook http://www.libpng.org/pub/png/book/sources.html
671242f350d172e106580348e24bab66b0d7e6a5vboxsync The pngbook demo programs are explicitly designed to demonstrate proper
671242f350d172e106580348e24bab66b0d7e6a5vboxsync coding techniques for using the libpng reference library. As a result,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync you need to download and build both zlib (on which libpng depends) and
671242f350d172e106580348e24bab66b0d7e6a5vboxsync libpng. A common build setup is to place the zlib, libpng and pngbook
671242f350d172e106580348e24bab66b0d7e6a5vboxsync subdirectory trees ("folders") in the same parent directory. Then the
671242f350d172e106580348e24bab66b0d7e6a5vboxsync libpng build can refer to files in ../zlib (or ..\zlib or [-.zlib]),
671242f350d172e106580348e24bab66b0d7e6a5vboxsync and similarly for the pngbook build.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Note that all three packages are designed to be built from a command
671242f350d172e106580348e24bab66b0d7e6a5vboxsync line by default; those who wish to use a graphical or other integrated
671242f350d172e106580348e24bab66b0d7e6a5vboxsync development environments are on their own.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Unpack the latest pngbook sources (which should correspond to this
671242f350d172e106580348e24bab66b0d7e6a5vboxsync README file) into a directory and change into that directory.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Copy Makefile.unx to Makefile and edit the PNG* and Z* variables
671242f350d172e106580348e24bab66b0d7e6a5vboxsync appropriately (possibly also the X* variables if necessary).
671242f350d172e106580348e24bab66b0d7e6a5vboxsync There is no "install" target, so copy the three executables somewhere
671242f350d172e106580348e24bab66b0d7e6a5vboxsync in your path or run them from the current directory. All three will
671242f350d172e106580348e24bab66b0d7e6a5vboxsync print a basic usage screen when run without any command-line arguments;
671242f350d172e106580348e24bab66b0d7e6a5vboxsync see the book for more details.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Unpack the latest pngbook sources (which should correspond to this
671242f350d172e106580348e24bab66b0d7e6a5vboxsync README file) into a folder, open a "DOS shell" or "command prompt"
671242f350d172e106580348e24bab66b0d7e6a5vboxsync or equivalent command-line window, and cd into the folder where you
671242f350d172e106580348e24bab66b0d7e6a5vboxsync unpacked the source code.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync For MSVC, set up the necessary environment variables by invoking
671242f350d172e106580348e24bab66b0d7e6a5vboxsync %devstudio%\vc\bin\vcvars32.bat
671242f350d172e106580348e24bab66b0d7e6a5vboxsync where where %devstudio% is the installation directory for MSVC /
671242f350d172e106580348e24bab66b0d7e6a5vboxsync DevStudio. If you get "environment out of space" errors under 95/98,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync create a desktop shortcut with "c:\windows\command.com /e:4096" as
671242f350d172e106580348e24bab66b0d7e6a5vboxsync the program command line and set the working directory to the pngbook
671242f350d172e106580348e24bab66b0d7e6a5vboxsync directory. Then double-click to open the new DOS-prompt window with
671242f350d172e106580348e24bab66b0d7e6a5vboxsync a bigger environment and retry the commands above.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Copy Makefile.w32 to Makefile and edit the PNGPATH and ZPATH variables
671242f350d172e106580348e24bab66b0d7e6a5vboxsync appropriately (possibly also the "INC" and "LIB" variables if needed).
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Note that the names of the dynamic and static libpng and zlib libraries
671242f350d172e106580348e24bab66b0d7e6a5vboxsync used in the makefile may change in later releases of the libraries.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Also note that, as of libpng version 1.0.5, MSVC DLL builds do not work.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync This makefile therefore builds statically linked executables, but if
671242f350d172e106580348e24bab66b0d7e6a5vboxsync the DLL problems ever get fixed, uncommenting the appropriate PNGLIB
671242f350d172e106580348e24bab66b0d7e6a5vboxsync and ZLIB lines will build dynamically linked executables instead.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Do the build by typing
671242f350d172e106580348e24bab66b0d7e6a5vboxsync The result should be three executables: rpng-win.exe, rpng2-win.exe,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync and wpng.exe. Copy them somewhere in your PATH or run them from the
671242f350d172e106580348e24bab66b0d7e6a5vboxsync current folder. Like the Unix versions, the two windowed programs
671242f350d172e106580348e24bab66b0d7e6a5vboxsync (rpng and rpng2) now display a usage screen in a console window when
671242f350d172e106580348e24bab66b0d7e6a5vboxsync invoked without command-line arguments; this is new behavior as of
671242f350d172e106580348e24bab66b0d7e6a5vboxsync the June 2001 release. Note that the programs use the Unix-style "-"
671242f350d172e106580348e24bab66b0d7e6a5vboxsync character to specify options, instead of the more common DOS/Windows
671242f350d172e106580348e24bab66b0d7e6a5vboxsync "/" character. (For example: "rpng2-win -bgpat 4 foo.png", not
671242f350d172e106580348e24bab66b0d7e6a5vboxsync "rpng2-win /bgpat 4 foo.png")
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Unpack the pngbook sources into a subdirectory and change into that
671242f350d172e106580348e24bab66b0d7e6a5vboxsync subdirectory.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync Edit makevms.com appropriately, specifically the zpath and pngpath
671242f350d172e106580348e24bab66b0d7e6a5vboxsync To run the programs, they probably first need to be set up as "foreign
671242f350d172e106580348e24bab66b0d7e6a5vboxsync symbols," with "disk" and "dir" set appropriately:
671242f350d172e106580348e24bab66b0d7e6a5vboxsync $ rpng == "$disk:[dir]rpng-x.exe"
671242f350d172e106580348e24bab66b0d7e6a5vboxsync $ rpng2 == "$disk:[dir]rpng2-x.exe"
671242f350d172e106580348e24bab66b0d7e6a5vboxsync $ wpng == "$disk:[dir]wpng.exe"
671242f350d172e106580348e24bab66b0d7e6a5vboxsync All three will print a basic usage screen when run without any command-
671242f350d172e106580348e24bab66b0d7e6a5vboxsync line arguments; see the book for more details. Note that the options
671242f350d172e106580348e24bab66b0d7e6a5vboxsync style is Unix-like, i.e., preceded by "-" rather than "/".
671242f350d172e106580348e24bab66b0d7e6a5vboxsyncRUNNING THE PROGRAMS: (VERY) BRIEF INTRO
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng is a simple PNG viewer that can display transparent PNGs with a
671242f350d172e106580348e24bab66b0d7e6a5vboxsync specified background color; for example,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng -bgcolor #ff0000 toucan.png
671242f350d172e106580348e24bab66b0d7e6a5vboxsync would display the image with a red background. rpng2 is a progressive
671242f350d172e106580348e24bab66b0d7e6a5vboxsync viewer that simulates a web browser in some respects; it can display
671242f350d172e106580348e24bab66b0d7e6a5vboxsync images against either a background color or a dynamically generated
671242f350d172e106580348e24bab66b0d7e6a5vboxsync background image. For example:
671242f350d172e106580348e24bab66b0d7e6a5vboxsync rpng2 -bgpat 16 toucan.png
671242f350d172e106580348e24bab66b0d7e6a5vboxsync wpng is a purely command-line image converter from binary PBMPLUS/NetPBM
671242f350d172e106580348e24bab66b0d7e6a5vboxsync format (.pgm or .ppm) to PNG; for example,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync would convert the specified PPM file (using redirection) to PNG, auto-
671242f350d172e106580348e24bab66b0d7e6a5vboxsync matically setting the PNG modification-time chunk.
671242f350d172e106580348e24bab66b0d7e6a5vboxsync All options can be abbreviated to the shortest unique value; for example,
671242f350d172e106580348e24bab66b0d7e6a5vboxsync "-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma.