Check libpng directly into third_party/

third_party/libpng/contrib/gregbook/README

Index: third_party/libpng/contrib/gregbook/README
diff --git a/third_party/libpng/contrib/gregbook/README b/third_party/libpng/contrib/gregbook/README
new file mode 100644
index 0000000000000000000000000000000000000000..7b1f6a3ea62e3d3c564995dba904f74727de6038
--- /dev/null
+++ b/third_party/libpng/contrib/gregbook/README
@@ -0,0 +1,186 @@
+                     ===========================
+                      PNG: The Definitive Guide
+                     ===========================
+
+                             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 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
+   LICENSE            terms of distribution and reuse (BSD-like or GNU GPL)
+   COPYING            GNU General Public License (GPL)
+
+   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, although the programs are designed to be functional, their
+primary purpose is to illustrate how to use libpng to add PNG support to
+other programs.  As such, their user interfaces are crude and definitely
+are not intended for everyday use.
+
+Please see http://www.libpng.org/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
+http://pobox.com/~newt/greg_contact.html
+16 March 2008
+
+
+BUILD INSTRUCTIONS
+
+ - Prerequisites (in order of compilation):
+
+      - zlib            http://zlib.net/
+      - libpng          http://www.libpng.org/pub/png/libpng.html
+      - pngbook         http://www.libpng.org/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.  Like the Unix versions, the two windowed programs
+     (rpng and rpng2) now display a usage screen in a console window when
+     invoked without command-line arguments; this is new behavior as of
+     the June 2001 release.  Note that the programs use the Unix-style "-"
+     character to specify options, instead of the more common DOS/Windows
+     "/" character.  (For example:  "rpng2-win -bgpat 4 foo.png", not
+     "rpng2-win /bgpat 4 foo.png")
+
+
+ - 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-notrans.ppm > toucan-notrans.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.