NAME

     libpnm - functions to support portable anymap programs

SYNOPSIS

     #include <pnm.h>
     cc ... libpnm.a libppm.a libpgm.a libpbm.a

DESCRIPTION

  TYPES AND CONSTANTS
     typedef ... xel;
     typedef ... xelval;
     #define PNM_MAXMAXVAL ...
     extern xelval pnm_pbmmaxval;

     Each xel contains three xelvals, each of which  should  con-
     tain   only   the   values   between  0  and  PNM_MAXMAXVAL.
     pnm_pbmmaxval is the maxval used when a PNM program reads  a
     PBM  file.   Normally it is 1; however, for some programs, a
     larger value gives better results.

  XEL MANIPULATIONS
     xelval PNM_GET1( xel x )

     This macro extracts a single value from  an  xel,  when  you
     know  it's  from  a  PBM  or PGM file.  When it's from a PPM
     file, use PPM_GETR(), PPM_GETG(), and PPM_GETB().

     void PNM_ASSIGN1( xel x, xelval v )

     This macro assigns a single value to an xel, when  you  know
     it's from a PBM or PGM file.  When it's from a PPM file, use
     PPM_ASSIGN().

     int PNM_EQUAL( xel x, xel y )

     This macro checks two xels for equality.

     int PNM_FORMAT_TYPE( int format )

     For distinguishing different file types.

  INITIALIZATION
     void pnm_init( int* argcP, char* argv[] )

     All PNM programs must call this routine.

  MEMORY MANAGEMENT
     xel** pnm_allocarray( int cols, int rows )

     Allocate an array of xels.

     xel* pnm_allocrow( int cols )

     Allocate a row of the given number of xels.

     void pnm_freearray( xel** xels, int rows )

     Free the array allocated  with  pnm_allocarray()  containing
     the given number of rows.

     void pnm_freerow( xel* xelrow )

     Free a row of xels.

  READING FILES
     void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )

     Read the header from a PNM file, filling in the rows,  cols,
     maxval and format variables.

     void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format )

     Read a row of xels into the xelrow array.  Format, cols, and
     maxval were filled in by pnm_readpnminit().

     xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )

     Read an entire anymap file into memory, returning the  allo-
     cated  array and filling in the rows, cols, maxval, and for-
     mat variables.  This  function  combines  pnm_readpnminit(),
     pnm_allocarray()    and    pnm_readpnmrow().    Unlike   the
     equivalent functions in PBM, PGM, and PPM,  it  returns  the
     format so you can tell what type the file is.

  WRITING FILES
     void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxval, int format, int forceplain )

     Write the header for a portable  anymap  file.   Unlike  the
     equivalent  functions  in  PBM,  PGM,  and  PPM, you have to
     specify the output  type.   The  forceplain  flag  forces  a
     plain-format  file to be written, as opposed to a raw-format
     one.

     void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, int forceplain )

     Write a row from a portable anymap.

     void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, int forceplain )

     Write the header and all data for a portable  anymap.   This
     function combines pnm_writepnminit() and pnm_writepnmrow().

  FORMAT PROMOTION
     void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval newmaxval, int newformat )

     Promote a row of xels from one maxval and format  to  a  new
     set.   Used  when  combining  multiple  anymaps of different
     types - just take the max of the maxvals and the max of  the
     formats, and promote them all to that.

     void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, int format, xelval newmaxval, int newformat )

     Promote an entire anymap.

  XEL MANIPULATION
     xel pnm_whitexel( xelval maxval, int format )
     xel pnm_blackxel( xelval maxval, int format )

     Return a white or black xel for the given maxval and format.

     void pnm_invertxel( xel* x, xelval maxval, int format )

     Invert an xel.

     xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format )

     Figure out an appropriate background xel based on this row.

     xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, int format )

     Figure out a background xel based on an entire anymap.  This
     can do a slightly better job than pnm_backgroundxelrow().

SEE ALSO

     pbm(3), pgm(3), ppm(3)

AUTHOR

     Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.