<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>User manual for old pgm functions</TITLE>
<META NAME="manual_section" CONTENT="3">
</HEAD>
<BODY>
<H1>pgm Functions</H1>
Updated: 8 September 2007
<BR>
<A HREF="#index">Table Of Contents</A>
<H2>NAME</H2>
libpgm - libnetpbm functions to read and write PGM image files
<H2 id="synopsis">SYNOPSIS</H2>
<B>#include <netpbm/pgm.h></B>
<P>
<B>void pgm_init( </B>
<B>int *</B><I>argcP</I><B>,</B>
<B>char *</B><I>argv</I><B>[]</B>
<B>);</B>
<P>
<B>gray ** pgm_allocarray(</B>
<B>int </B><I>cols</I><B>,</B>
<B>int </B><I>rows</I><B> );</B>
<P>
<B>gray * pgm_allocrow(</B>
<B>int</B><I>cols</I><B> );</B>
<P>
<B>void pgm_freearray(</B>
<B>gray **</B><I>grays</I><B>,</B>
<B>int</B><I>rows</I><B> );</B>
<P>
<B>void pgm_freerow(</B>
<B>gray *</B><I>grayrow</I><B>);</B>
<P>
<B>void pgm_readpgminit( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>int *</B><I>colsP</I><B>,</B>
<B>int *</B><I>rowsP</I><B>,</B>
<B>gray *</B><I>maxvalP</I><B>,</B>
<B>int *</B><I>formatP</I><B> );</B>
<P>
<B>void pgm_readpgmrow( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>gray *</B><I>grayrow</I><B>,</B>
<B>int </B><I>cols</I><B>,</B>
<B>gray </B><I>maxval</I><B>,</B>
<B>int </B><I>format</I><B> );</B>
<P>
<B>gray ** pgm_readpgm( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>int *</B><I>colsP</I><B>,</B>
<B>int *</B><I>rowsP</I><B>,</B>
<B>gray *</B><I>maxvalP</I><B> );</B>
<P>
<B>void pgm_writepgminit( </B>
<B>FILE * fp , </B>
<B>int </B><I>cols</I><B>,</B>
<B>int </B><I>rows</I><B>,</B>
<B>gray </B><I>maxval</I><B>,</B>
<B>int </B><I>forceplain</I><B> );</B>
<P>
<B>void pgm_writepgmrow( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>gray *</B><I>grayrow</I><B>,</B>
<B>int cols</B><I>,</I>
<B>gray </B><I>maxval</I><B>,</B>
<B>int </B><I>forceplain</I><B> );</B>
<P>
<B>void pgm_writepgm( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>gray ** </B><I>grays</I><B>,</B>
<B>int </B><I>cols</I><B>,</B>
<B>int </B><I>rows</I><B>,</B>
<B>gray </B><I>maxval</I><B>,</B>
<B>int </B><I>forceplain</I><B> );</B>
<P>
<B>void pgm_writepgm( </B>
<B>FILE *</B><I>fp</I><B>,</B>
<B>gray **</B><I>grays</I><B>,</B>
<B>int </B><I>cols</I><B>,</B>
<B>int </B><I>rows</I><B>,</B>
<B>gray </B><I>maxval</I><B>,</B>
<B>int </B><I>forceplain</I><B> );</B>
<P>
<B>void pgm_nextimage(</B>
<B>FILE *</B><I>file</I><B>,</B>
<B>int * const </B><I>eofP</I><B>);</B>
<P>
<B>void pgm_check(</B>
<B>FILE * </B><I>file</I><B>,</B>
<B>const enum pm_check_type </B><I>check_type</I><B>,</B>
<B>const int </B><I>format</I><B>,</B>
<B>const int </B><I>cols</I><B>,</B>
<B>const int </B><I>rows</I><B>,</B>
<B>const int </B><I>maxval</I><B>,</B>
<B>enum pm_check_code * const </B><I>retval</I><B>);</B>
<P>
<B>typedef ... gray;</B>
<P>
<B>#define PGM_MAXMAXVAL ...</B>
<P>
<B>#define PGM_OVERALLMAXVAL ...</B>
<P>
<B>#define PGM_FORMAT ...</B>
<P>
<B>#define RPGM_FORMAT ...</B>
<P>
<B>#define PGM_TYPE PGM_FORMAT</B>
<P>
<B>#define </B>
<B>PGM_FORMAT_TYPE(</B><I>format</I><B>)</B>
<B>...</B>
<H2 id="description">DESCRIPTION</H2>
<p>These library functions are part of <a href="index.html">Netpbm</a>.
<H3 id="types">TYPES AND CONSTANTS</H3>
<P>Each <B>gray</B> should contain only the values between <B>0</B>
and <B>PGM_OVERALLMAXVAL</B>.
<P><B>PGM_OVERALLMAXVAL</B> is the maximum value of a maxval in a PGM
file. <B>PGM_MAXMAXVAL</B> 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</B> cannot be read or
generated by old PGM processing programs and requires more file space.
<P><B>PGM_FORMAT </B> is the format code for a Plain PGM format image
file. <B>RPGM_FORMAT</B> is the format code for a Raw PGM format
image file. <B>PGM_TYPE </B> is the format type code for the PGM
formats. <B>PGM_FORMAT_TYPE</B> 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.
<H3 id="initialization">INITIALIZATION</H3>
<p><b>pgm_init()</b> is obsolete (at least since Netpbm 9.25 (March 2002)).
Use <a href="libpm.html#initialization"><b>pm_proginit()</b></a> instead.
<P><b>pgm_init()</b> is identical to <b>pm_proginit</b>.
<H3 id="memorymanagement">MEMORY MANAGEMENT</H3>
<B>pgm_allocarray()</B> allocates an array of grays.
<P><B>pgm_allocrow()</B> allocates a row of the given number of grays.
<P><B>pgm_freearray()</B> frees the array allocated with
<B>pgm_allocarray()</B> containing the given number of rows.
<P><B>pgm_freerow()</B> frees a row of grays allocated with
<B>pgm_allocrow()</B>.
<H3 id="reading">READING FILES</H3>
<P>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</I> value
returned by <B>pgm_readpgminit()</B> is, however, not translated. It
represents the actual format of the PBM file.
<P><B>pgm_readpgminit()</B> reads the header of a PGM file, returning
all the information from the header and leaving the file positioned
just after the header.
<P><B>pgm_readpgmrow()</B> reads a row of grays into the <I>grayrow
</I> array. <I>format</I>, <I>cols</I>, and <I>maxval </I> are the
values returned by <B>pgm_readpgminit()</B>.
<P><B>pgm_readpgm()</B> reads an entire PGM image into memory,
returning the allocated array as its return value and returning the
information from the header as <I>rows</I>, <I>cols</I>, and
<I>maxval</I>. This function combines <B>pgm_readpgminit()</B>,
<B>pgm_allocarray()</B>, and <B>pgm_readpgmrow()</B>.
<p><b>pgm_readpgminit()</b> and <b>pgm_readpgm</b> abort the program with
a message to Standard Error if the PGM image header is not syntactically
valid, including if it contains a number too large to be processed using
the system's normal data structures (to wit, a number that won't fit in
a C 'int').
<H3 id="writing">WRITING FILES</H3>
<B>pgm_writepgminit()</B> writes the header for a PGM file and leaves
it positioned just after the header.
<P><I>forceplain</I> is a logical value that tells
<B>pgm_writepgminit() </B> to write a header for a plain PGM format
file, as opposed to a raw PGM format file.
<P><B>pgm_writepgmrow()</B> writes the row <I>grayrow</I> to a PGM
file. For meaningful results, <I>cols</I>, <I>maxval</I>, and
<I>forceplain</I> must be the same as was used with
<B>pgm_writepgminit()</B>.
<P><B>pgm_writepgm()</B> write the header and all data for a PGM
image. This function combines <B>pgm_writepgminit()</B> and
<B>pgm_writepgmrow()</B>.
<H3 id="miscellaneous">MISCELLANEOUS</H3>
<P><B>pgm_nextimage()</B> positions a PGM input file to the next image
in it (so that a subsequent <B>pgm_readpgminit()</B> reads its
header).
<P><B>pgm_nextimage()</B> is analogous to <B>pbm_nextimage()</B>, but
works on PGM and PBM files.
<P><B>pgm_check() </B> checks for the common file integrity error
where the file is the wrong size to contain all the image data.
<P><B>pgm_check() </B> is analogous to <B>pbm_check()</B>, but works
on PGM and PBM files.
<H2 id="seealso">SEE ALSO</H2>
<B><A HREF="libpbm.html">libpbm</A></B>,
<B><A HREF="libppm.html">libppm</A></B>,
<B><A HREF="libpnm.html">libpnm</A></B>
<HR>
<H2 id="index">Table Of Contents</H2>
<UL>
<LI><A HREF="#synopsis">SYNOPSIS</A>
<LI><A HREF="#description">DESCRIPTION</A>
<UL>
<LI><A HREF="#types">TYPES AND CONSTANTS</A>
<LI><A HREF="#initialization">INITIALIZATION</A>
<LI><A HREF="#memorymanagement">MEMORY MANAGEMENT</A>
<LI><A HREF="#reading">READING FILES</A>
<LI><A HREF="#writing">WRITING FILES</A>
<LI><A HREF="#miscellaneous">MISCELLANEOUS</A>
</UL>
<LI><A HREF="#seealso">SEE ALSO</A>
</UL>
</BODY>
</HTML>