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