## 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.