.TH libpgm 3
.SH NAME
libpgm - functions to support portable graymap (PGM) programs

.SH SYNOPSIS
.B #include <pgm.h>

.B void pgm_init( 
.BI "int *" argcP , 
.BI "char *" argv []
.B );

.B gray ** pgm_allocarray(
.BI "int " cols , 
.BI "int " rows " );"

.B "gray * pgm_allocrow("
.BI int cols " );"

.B void pgm_freearray(
.BI "gray **" grays , 
.BI int rows " );"

.B void pgm_freerow(
.BI "gray *" grayrow ");"

.B void pgm_readpgminit( 
.BI "FILE *" fp , 
.BI "int *" colsP , 
.BI "int *" rowsP , 
.BI "gray *" maxvalP , 
.BI "int *" formatP " );"

.B void pgm_readpgmrow( 
.BI "FILE *" fp , 
.BI "gray *" grayrow , 
.BI "int " cols , 
.BI "gray " maxval , 
.BI "int " format " );"

.B gray ** pgm_readpgm( 
.BI "FILE *" fp , 
.BI "int *" colsP , 
.BI "int *" rowsP , 
.BI "gray *" maxvalP " );"

.B void pgm_writepgminit( 
.B "FILE * " fp , 
.BI "int " cols , 
.BI "int " rows , 
.BI "gray " maxval , 
.BI "int " forceplain " );"

.B void pgm_writepgmrow( 
.BI "FILE *" fp ,  
.BI "gray *" grayrow , 
.BI "int "cols , 
.BI "gray " maxval , 
.BI "int " forceplain " );"

.B void pgm_writepgm( 
.BI "FILE *" fp , 
.BI "gray **" grays , 
.BI "int " cols , 
.BI "int " rows , 
.BI "gray " maxval , 
.BI "int " forceplain " );"

.B void pgm_nextimage(
.BI "FILE *" file ,
.BI "int * const " eofP );

.B void pgm_check(
.BI "FILE * " file ,
.BI "const enum pm_check_type " check_type , 
.BI "const int " format , 
.BI "const int " cols , 
.BI "const int " rows ,
.BI "const int " maxval ,
.BI "enum pm_check_code * const " retval );

.B typedef ... gray;

.B #define PGM_MAXMAXVAL ...

.B #define PGM_OVERALLMAXVAL ...

.B extern gray pgm_pbmmaxval;

.B #define PGM_FORMAT ...

.B #define RPGM_FORMAT ...

.B #define PGM_TYPE PGM_FORMAT

.B #define 
.BI PGM_FORMAT_TYPE( format )
.B ...


.SH DESCRIPTION
.SS TYPES AND CONSTANTS
Each
.B gray
should contain only the values between
.B 0
and
.BR PGM_OVERALLMAXVAL .
.B pgm_pbmmaxval
is the maxval used when a PGM program reads a PBM file.
Normally it is 1; however, for some programs, a larger value gives better
results.

.B PGM_OVERALLMAXVAL
is the maximum value of a maxval in a PGM file.
.B PGM_MAXMAXVAL
is the maximum value of a maxval in a PGM file that is compatible with
the PGM format as it existed before April 2000.  It is also the
maximum value of a maxval that results in the minimum possible raster
size for a particular image.  I.e an image with a maxval higher than 
.B PGM_MAXMAXVAL
cannot be read or generated by old PGM processing programs and requires 
more file space.

.B PGM_FORMAT 
is the format code for a Plain PGM format image file.
.B RPGM_FORMAT
is the format code for a Raw PGM format image file.
.B PGM_TYPE 
is the format type code for the PGM formats.
.B PGM_FORMAT_TYPE
is a macro that generates code to compute the format type code of a
PBM or PGM format from the format code which is its argument.

.SS INITIALIZATION

All PGM programs must call
.B pgm_init() 
just after invocation, before they process their arguments.

.SS MEMORY MANAGEMENT
.B pgm_allocarray()
allocates an array of grays.

.B pgm_allocrow()
allocates a row of the given number of grays.

.B pgm_freearray()
frees the array allocated with
.B pgm_allocarray()
containing the given number of rows.

.B pgm_freerow()
frees a row of grays allocated with 
.BR pgm_allocrow() .

.SS READING FILES

If a function in this section is called on a PBM format file, it
translates the PBM file into a PGM file on the fly and functions as if
it were called on the equivalent PGM file.  The 
.I format
value returned by 
.B pgm_readpgminit() 
is, however, not translated.  It represents the actual format of the
PBM file.

.B pgm_readpgminit()
reads the header of a PGM file, returning all the information from the header
and leaving the file positioned just after the header.

.B pgm_readpgmrow()
reads a row of grays into the 
.I grayrow 
array.  
.IR format , 
.IR cols , 
and 
.I maxval 
are the values returned by 
.BR pgm_readpgminit() .

.B pgm_readpgm()
reads an entire PGM image into memory, returning the allocated array
as its return value and returning the information from the header as
.IR rows , 
.IR cols , 
and
.IR maxval .
This function combines
.BR pgm_readpgminit() ,
.BR pgm_allocarray() ,
and
.BR pgm_readpgmrow() .

.SS WRITING FILES
.B pgm_writepgminit()
writes the header for a PGM file and leaves it positioned just after
the header.

.I forceplain
is a logical value that tells
.B pgm_writepgminit() 
to write a header for a plain PGM format file, as opposed to a raw PGM
format file.

.B pgm_writepgmrow()
writes the row 
.I grayrow
to a PGM file.  For meaningful results, 
.IR cols ,
.IR maxval ,
and
.I forceplain
must be the same as was used with
.BR pgm_writepgminit() .

.B pgm_writepgm()
write the header and all data for a PGM image.  This function combines
.B pgm_writepgminit()
and
.BR pgm_writepgmrow() .

.SS MISCELLANEOUS

.B pgm_nextimage()
positions a PGM input file to the next image in it (so that a subsequent
.B pgm_readpgminit()
reads its header).

.B pgm_nextimage()
is analogous to 
.BR pbm_nextimage() ,
but works on PGM and PBM files.

.B pgm_check() 
checks for the common file integrity error where the file is the wrong
size to contain all the image data.

.B pgm_check() 
is analogous to 
.BR pbm_check() ,
but works on PGM and PBM files.

.SH "SEE ALSO"
.BR libpbm (3), 
.BR libppm (3), 
.BR libpnm (3)