libpgm

libpgm - functions to support portable graymap (PGM) programs

#include <pgm.h> void pgm_init( I int * argcP , I char * argv [] ); gray ** pgm_allocarray( I int cols , I int rows ); gray * pgm_allocrow( I int cols ); void pgm_freearray( I gray ** grays , I int rows ); void pgm_freerow( I gray * grayrow ); void pgm_readpgminit( I FILE * fp , I int * colsP , I int * rowsP , I gray * maxvalP , I int * formatP ); void pgm_readpgmrow( I FILE * fp , I gray * grayrow , I int cols , I gray maxval , I int format ); gray ** pgm_readpgm( I FILE * fp , I int * colsP , I int * rowsP , I gray * maxvalP ); void pgm_writepgminit( FILE * fp , I int cols , I int rows , I gray maxval , I int forceplain ); void pgm_writepgmrow( I FILE * fp , I gray * grayrow , I int cols , I gray maxval , I int forceplain ); void pgm_writepgm( I FILE * fp , I gray ** grays , I int cols , I int rows , I gray maxval , I int forceplain ); void pgm_writepgm( I FILE * fp , I gray ** grays , I int cols , I int rows , I gray maxval , I int forceplain ); void pgm_nextimage( I FILE * file , I int * const eofP ); void pgm_check( I FILE * file , I const enum pm_check_type check_type , I const int format , I const int cols , I const int rows , I const int maxval , I enum pm_check_code * const retval ); typedef ... gray; #define PGM_MAXMAXVAL ... #define PGM_OVERALLMAXVAL ... extern gray pgm_pbmmaxval; #define PGM_FORMAT ... #define RPGM_FORMAT ... #define PGM_TYPE PGM_FORMAT #define I PGM_FORMAT_TYPE( format ) ...

TYPES AND CONSTANTS

Each gray should contain only the values between 0 and R PGM_OVERALLMAXVAL . 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. PGM_OVERALLMAXVAL is the maximum value of a maxval in a PGM file. 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 PGM_MAXMAXVAL cannot be read or generated by old PGM processing programs and requires more file space. PGM_FORMAT is the format code for a Plain PGM format image file. RPGM_FORMAT is the format code for a Raw PGM format image file. PGM_TYPE is the format type code for the PGM formats. 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.

INITIALIZATION

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

MEMORY MANAGEMENT

pgm_allocarray() allocates an array of grays. pgm_allocrow() allocates a row of the given number of grays. pgm_freearray() frees the array allocated with pgm_allocarray() containing the given number of rows. pgm_freerow() frees a row of grays allocated with R pgm_allocrow() .

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 format value returned by pgm_readpgminit() is, however, not translated. It represents the actual format of the PBM file. 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. pgm_readpgmrow() reads a row of grays into the grayrow array. R format , R cols , and maxval are the values returned by R pgm_readpgminit() . 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 R rows , R cols , and R maxval . This function combines R pgm_readpgminit() , R pgm_allocarray() , and R pgm_readpgmrow() .

WRITING FILES

pgm_writepgminit() writes the header for a PGM file and leaves it positioned just after the header. forceplain is a logical value that tells pgm_writepgminit() to write a header for a plain PGM format file, as opposed to a raw PGM format file. pgm_writepgmrow() writes the row grayrow to a PGM file. For meaningful results, R cols , R maxval , and forceplain must be the same as was used with R pgm_writepgminit() . pgm_writepgm() write the header and all data for a PGM image. This function combines pgm_writepgminit() and R pgm_writepgmrow() .

MISCELLANEOUS

pgm_nextimage() positions a PGM input file to the next image in it (so that a subsequent pgm_readpgminit() reads its header). pgm_nextimage() is analogous to R pbm_nextimage() , but works on PGM and PBM files. pgm_check() checks for the common file integrity error where the file is the wrong size to contain all the image data. pgm_check() is analogous to R pbm_check() , but works on PGM and PBM files.

libpbm(3), libppm(3), libpnm(3)