libpnm(3)                                               libpnm(3)


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 PNMMAXMAXVAL ...
       extern xelval pnmpbmmaxval;

       Each xel contains three xelvals, each of which should con-
       tain  only  the  values  between  0   and   PNMMAXMAXVAL.
       pnmpbmmaxval  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 PNMGET1( 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 PPMGETR(), PPMGETG(), and PPMGETB().

       void PNMASSIGN1( 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 PPMASSIGN().

       int PNMEQUAL( xel x, xel y )

       This macro checks two xels for equality.

       int PNMFORMATTYPE( int format )

       For distinguishing different file types.

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

       All PNM programs must call this routine.

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

       Allocate an array of xels.

       xel* pnmallocrow( int cols )




                                                                1

libpnm(3)                                               libpnm(3)


       Allocate a row of the given number of xels.

       void pnmfreearray( xel** xels, int rows )

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

       void pnmfreerow( xel* xelrow )

       Free a row of xels.

   READING FILES
       void pnmreadpnminit( 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 pnmreadpnmrow( 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 pnmreadpnminit().

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

       Read an entire anymap  file  into  memory,  returning  the
       allocated array and filling in the rows, cols, maxval, and
       format     variables.      This     function      combines
       pnmreadpnminit(),  pnmallocarray() and pnmreadpnmrow().
       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 pnmwritepnminit( 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 pnmwritepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, int forceplain )

       Write a row from a portable anymap.

       void pnmwritepnm( 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       pnmwritepnminit()       and
       pnmwritepnmrow().

   FORMAT PROMOTION
       void pnmpromoteformatrow( 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



                                                                2

libpnm(3)                                               libpnm(3)


       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 pnmpromoteformat( xel** xels, int cols, int rows, xelval maxval, int format, xelval newmaxval, int newformat )

       Promote an entire anymap.

   XEL MANIPULATION
       xel pnmwhitexel( xelval maxval, int format )
       xel pnmblackxel( xelval maxval, int format )

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

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

       Invert an xel.

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

       Figure out an appropriate background  xel  based  on  this
       row.

       xel pnmbackgroundxel( 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
       pnmbackgroundxelrow().

SEE ALSO
       pbm(3), pgm(3), ppm(3)

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






















                                                                3