gtkmm-osx/trunk/libpng-1.2.5/contrib/gregbook/README

   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@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)
  26
  27    Makefile.unx       Unix makefile
  28    Makefile.w32       Windows (MSVC) makefile
  29    makevms.com        OpenVMS build script
  30
  31    rpng-win.c         Windows front end for the basic viewer
  32    rpng-x.c           X Window System (Unix, OpenVMS) front end
  33    readpng.c          generic back end for the basic viewer
  34    readpng.h          header file for the basic viewer
  35
  36    rpng2-win.c        Windows front end for the progressive viewer
  37    rpng2-x.c          X front end for the progressive viewer
  38    readpng2.c         generic back end for the progressive viewer
  39    readpng2.h         header file for the progressive viewer
  40
  41    wpng.c             generic (text) front end for the converter
  42    writepng.c         generic back end for the converter
  43    writepng.h         header file for the converter
  44
  45    toucan.png         transparent PNG for testing (by Stefan Schneider)
  46
  47 Note that, although the programs are designed to be functional, their
  48 primary purpose is to illustrate how to use libpng to add PNG support to
  49 other programs.  As such, their user interfaces are crude and definitely
  50 are not intended for everyday use.
  51
  52 Please see http://www.libpng.org/pub/png/pngbook.html for further infor-
  53 mation and links to the latest version of the source code, and Chapters
  54 13-15 of the book for detailed discussion of the three programs.
  55
  56 Greg Roelofs
  57 newt@pobox.com
  58 30 June 2001
  59
  60
  61 BUILD INSTRUCTIONS
  62
  63  - Prerequisites (in order of compilation):
  64
  65       - zlib            http://www.gzip.org/zlib/
  66       - libpng          http://www.libpng.org/pub/png/libpng.html
  67       - pngbook         http://www.libpng.org/pub/png/book/sources.html
  68
  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.
  76
  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.
  80
  81
  82  - Unix:
  83
  84      Unpack the latest pngbook sources (which should correspond to this
  85      README file) into a directory and change into that directory.
  86
  87      Copy Makefile.unx to Makefile and edit the PNG* and Z* variables
  88      appropriately (possibly also the X* variables if necessary).
  89
  90      make
  91
  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.
  96
  97
  98  - Windows:
  99
 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.
 104
 105      For MSVC, set up the necessary environment variables by invoking
 106
 107         %devstudio%\vc\bin\vcvars32.bat
 108
 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.
 115
 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.
 124
 125      Do the build by typing
 126
 127         nmake
 128
 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.  Like the Unix versions, the two windowed programs
 132      (rpng and rpng2) now display a usage screen in a console window when
 133      invoked without command-line arguments; this is new behavior as of
 134      the June 2001 release.  Note that the programs use the Unix-style "-"
 135      character to specify options, instead of the more common DOS/Windows
 136      "/" character.  (For example:  "rpng2-win -bgpat 4 foo.png", not
 137      "rpng2-win /bgpat 4 foo.png")
 138
 139
 140  - OpenVMS:
 141
 142      Unpack the pngbook sources into a subdirectory and change into that
 143      subdirectory.
 144
 145      Edit makevms.com appropriately, specifically the zpath and pngpath
 146      variables.
 147
 148      @makevms
 149
 150      To run the programs, they probably first need to be set up as "foreign
 151      symbols," with "disk" and "dir" set appropriately:
 152
 153      $ rpng == "$disk:[dir]rpng-x.exe"
 154      $ rpng2 == "$disk:[dir]rpng2-x.exe"
 155      $ wpng == "$disk:[dir]wpng.exe"
 156
 157      All three will print a basic usage screen when run without any command-
 158      line arguments; see the book for more details.  Note that the options
 159      style is Unix-like, i.e., preceded by "-" rather than "/".
 160
 161
 162 RUNNING THE PROGRAMS:  (VERY) BRIEF INTRO
 163
 164      rpng is a simple PNG viewer that can display transparent PNGs with a
 165      specified background color; for example,
 166
 167         rpng -bgcolor #ff0000 toucan.png
 168
 169      would display the image with a red background.  rpng2 is a progressive
 170      viewer that simulates a web browser in some respects; it can display
 171      images against either a background color or a dynamically generated
 172      background image.  For example:
 173
 174         rpng2 -bgpat 16 toucan.png
 175
 176      wpng is a purely command-line image converter from binary PBMPLUS/NetPBM
 177      format (.pgm or .ppm) to PNG; for example,
 178
 179         wpng -time < toucan.ppm > toucan.png
 180
 181      would convert the specified PPM file (using redirection) to PNG, auto-
 182      matically setting the PNG modification-time chunk.
 183
 184      All options can be abbreviated to the shortest unique value; for example,
 185      "-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma.