NAME¶
libpgm - functions to support portable graymap (PGM) programs
SYNOPSIS¶
#include <pgm.h>
void pgm_init( int *argcP, char
*argv[] );
gray ** pgm_allocarray( int cols, int
rows );
gray * pgm_allocrow( intcols );
void pgm_freearray( gray **grays,
introws );
void pgm_freerow( gray *grayrow);
void pgm_readpgminit( FILE *fp, int
*colsP, int *rowsP, gray
*maxvalP, int *formatP );
void pgm_readpgmrow( FILE *fp, gray
*grayrow, int cols, gray
maxval, int format );
gray ** pgm_readpgm( FILE *fp, int
*colsP, int *rowsP, gray
*maxvalP );
void pgm_writepgminit( FILE * fp , int cols,
int rows, gray maxval, int
forceplain );
void pgm_writepgmrow( FILE *fp, gray
*grayrow, int cols, gray
maxval, int forceplain );
void pgm_writepgm( FILE *fp, gray
**grays, int cols, int
rows, gray maxval, int
forceplain );
void pgm_nextimage( FILE *file, int * const
eofP);
void pgm_check( FILE * file, const enum
pm_check_type check_type, const int
format, const int cols, const int
rows, const int maxval, 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 PGM_FORMAT_TYPE(format) ...
DESCRIPTION¶
TYPES AND CONSTANTS¶
Each
gray should contain only the values between
0 and
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
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.
format,
cols, and
maxval are the values returned by
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
rows,
cols, and
maxval. This function combines
pgm_readpgminit(),
pgm_allocarray(), and
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,
cols,
maxval, and
forceplain must be
the same as was used with
pgm_writepgminit().
pgm_writepgm() write the header and all data for a PGM image. This
function combines
pgm_writepgminit() and
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
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
pbm_check(), but works on PGM and PBM
files.
SEE ALSO¶
libpbm(3),
libppm(3),
libpnm(3)