Home | History | Annotate | only in /external/libpng/contrib/gregbook
Up to higher level directory
NameDateSize
COPYING09-Oct-201317.6K
LICENSE09-Oct-20132.3K
Makefile.mingw3209-Oct-20133.8K
Makefile.sgi09-Oct-20132.9K
Makefile.unx09-Oct-20133.9K
Makefile.w3209-Oct-20133.3K
makevms.com09-Oct-20133.5K
README09-Oct-20137.6K
readpng.c09-Oct-20139.5K
readpng.h09-Oct-20133.2K
readpng2.c09-Oct-201324.2K
readpng2.h09-Oct-20133.8K
readppm.c09-Oct-20135.3K
rpng-win.c09-Oct-201322.4K
rpng-x.c09-Oct-201330.1K
rpng2-win.c09-Oct-201344.2K
rpng2-x.c09-Oct-201380.3K
toucan.png09-Oct-201312.6K
wpng.c09-Oct-201330.3K
writepng.c09-Oct-201312.5K
writepng.h09-Oct-20134.1K

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 (a] 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 or GNU GPL)
     26    COPYING            GNU General Public License (GPL)
     27 
     28    Makefile.unx       Unix makefile
     29    Makefile.w32       Windows (MSVC) makefile
     30    makevms.com        OpenVMS build script
     31 
     32    rpng-win.c         Windows front end for the basic viewer
     33    rpng-x.c           X Window System (Unix, OpenVMS) front end
     34    readpng.c          generic back end for the basic viewer
     35    readpng.h          header file for the basic viewer
     36 
     37    rpng2-win.c        Windows front end for the progressive viewer
     38    rpng2-x.c          X front end for the progressive viewer
     39    readpng2.c         generic back end for the progressive viewer
     40    readpng2.h         header file for the progressive viewer
     41 
     42    wpng.c             generic (text) front end for the converter
     43    writepng.c         generic back end for the converter
     44    writepng.h         header file for the converter
     45 
     46    toucan.png         transparent PNG for testing (by Stefan Schneider)
     47 
     48 Note that, although the programs are designed to be functional, their
     49 primary purpose is to illustrate how to use libpng to add PNG support to
     50 other programs.  As such, their user interfaces are crude and definitely
     51 are not intended for everyday use.
     52 
     53 Please see http://www.libpng.org/pub/png/pngbook.html for further infor-
     54 mation and links to the latest version of the source code, and Chapters
     55 13-15 of the book for detailed discussion of the three programs.
     56 
     57 Greg Roelofs
     58 http://pobox.com/~newt/greg_contact.html
     59 16 March 2008
     60 
     61 
     62 BUILD INSTRUCTIONS
     63 
     64  - Prerequisites (in order of compilation):
     65 
     66       - zlib		http://zlib.net/
     67       - libpng		http://www.libpng.org/pub/png/libpng.html
     68       - pngbook		http://www.libpng.org/pub/png/book/sources.html
     69 
     70      The pngbook demo programs are explicitly designed to demonstrate proper
     71      coding techniques for using the libpng reference library.  As a result,
     72      you need to download and build both zlib (on which libpng depends) and
     73      libpng.  A common build setup is to place the zlib, libpng and pngbook
     74      subdirectory trees ("folders") in the same parent directory.  Then the
     75      libpng build can refer to files in ../zlib (or ..\zlib or [-.zlib]),
     76      and similarly for the pngbook build.
     77 
     78      Note that all three packages are designed to be built from a command
     79      line by default; those who wish to use a graphical or other integrated
     80      development environments are on their own.
     81 
     82 
     83  - Unix:
     84 
     85      Unpack the latest pngbook sources (which should correspond to this
     86      README file) into a directory and change into that directory.
     87 
     88      Copy Makefile.unx to Makefile and edit the PNG* and Z* variables
     89      appropriately (possibly also the X* variables if necessary).
     90 
     91      make
     92 
     93      There is no "install" target, so copy the three executables somewhere
     94      in your path or run them from the current directory.  All three will
     95      print a basic usage screen when run without any command-line arguments;
     96      see the book for more details.
     97 
     98 
     99  - Windows:
    100 
    101      Unpack the latest pngbook sources (which should correspond to this
    102      README file) into a folder, open a "DOS shell" or "command prompt"
    103      or equivalent command-line window, and cd into the folder where you
    104      unpacked the source code.
    105 
    106      For MSVC, set up the necessary environment variables by invoking
    107  
    108         %devstudio%\vc\bin\vcvars32.bat
    109 
    110      where where %devstudio% is the installation directory for MSVC /
    111      DevStudio.  If you get "environment out of space" errors under 95/98,
    112      create a desktop shortcut with "c:\windows\command.com /e:4096" as
    113      the program command line and set the working directory to the pngbook
    114      directory.  Then double-click to open the new DOS-prompt window with
    115      a bigger environment and retry the commands above.
    116 
    117      Copy Makefile.w32 to Makefile and edit the PNGPATH and ZPATH variables
    118      appropriately (possibly also the "INC" and "LIB" variables if needed).
    119      Note that the names of the dynamic and static libpng and zlib libraries
    120      used in the makefile may change in later releases of the libraries.
    121      Also note that, as of libpng version 1.0.5, MSVC DLL builds do not work.
    122      This makefile therefore builds statically linked executables, but if
    123      the DLL problems ever get fixed, uncommenting the appropriate PNGLIB
    124      and ZLIB lines will build dynamically linked executables instead.
    125 
    126      Do the build by typing
    127 
    128         nmake
    129 
    130      The result should be three executables:  rpng-win.exe, rpng2-win.exe,
    131      and wpng.exe.  Copy them somewhere in your PATH or run them from the
    132      current folder.  Like the Unix versions, the two windowed programs
    133      (rpng and rpng2) now display a usage screen in a console window when
    134      invoked without command-line arguments; this is new behavior as of
    135      the June 2001 release.  Note that the programs use the Unix-style "-"
    136      character to specify options, instead of the more common DOS/Windows
    137      "/" character.  (For example:  "rpng2-win -bgpat 4 foo.png", not
    138      "rpng2-win /bgpat 4 foo.png")
    139 
    140 
    141  - OpenVMS:
    142 
    143      Unpack the pngbook sources into a subdirectory and change into that
    144      subdirectory.
    145 
    146      Edit makevms.com appropriately, specifically the zpath and pngpath
    147      variables.
    148 
    149      @makevms
    150 
    151      To run the programs, they probably first need to be set up as "foreign
    152      symbols," with "disk" and "dir" set appropriately:
    153 
    154      $ rpng  == "$disk:[dir]rpng-x.exe"
    155      $ rpng2 == "$disk:[dir]rpng2-x.exe"
    156      $ wpng  == "$disk:[dir]wpng.exe"
    157 
    158      All three will print a basic usage screen when run without any command-
    159      line arguments; see the book for more details.  Note that the options
    160      style is Unix-like, i.e., preceded by "-" rather than "/".
    161 
    162 
    163 RUNNING THE PROGRAMS:  (VERY) BRIEF INTRO
    164 
    165      rpng is a simple PNG viewer that can display transparent PNGs with a
    166      specified background color; for example,
    167 
    168 	rpng -bgcolor #ff0000 toucan.png
    169 
    170      would display the image with a red background.  rpng2 is a progressive
    171      viewer that simulates a web browser in some respects; it can display
    172      images against either a background color or a dynamically generated
    173      background image.  For example:
    174 
    175 	rpng2 -bgpat 16 toucan.png
    176 
    177      wpng is a purely command-line image converter from binary PBMPLUS/NetPBM
    178      format (.pgm or .ppm) to PNG; for example,
    179 
    180 	wpng -time < toucan-notrans.ppm > toucan-notrans.png
    181 
    182      would convert the specified PPM file (using redirection) to PNG, auto-
    183      matically setting the PNG modification-time chunk.
    184 
    185      All options can be abbreviated to the shortest unique value; for example,
    186      "-bgc" for -bgcolor (versus "-bgp" for -bgpat), or "-g" for -gamma.
    187