diff options
Diffstat (limited to 'libpgm.html')
| -rw-r--r-- | libpgm.html | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/libpgm.html b/libpgm.html new file mode 100644 index 00000000..9c89da8b --- /dev/null +++ b/libpgm.html @@ -0,0 +1,279 @@ +<!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: 22 July 2004 +<BR> +<A HREF="#index">Table Of Contents</A> +<A NAME="lbAB"> </A> +<H2>NAME</H2> +libpgm - libnetpbm functions to read and write PGM image files + +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>#include <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>extern gray pgm_pbmmaxval;</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> + +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<p>These library functions are part of <a href="index.html">Netpbm</a>. + +<A NAME="lbAE"> </A> +<H3>TYPES AND CONSTANTS</H3> + +<P>Each <B>gray</B> should contain only the values between <B>0</B> +and <B>PGM_OVERALLMAXVAL</B>. <B>pgm_pbmmaxval</B> 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. + +<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. + +<A NAME="lbAF"> </A> +<H3>INITIALIZATION</H3> + +<P><b>pgm_init</b> is identical to <b>pm_init()</b>. + +<A NAME="lbAG"> </A> +<H3>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>. + +<A NAME="lbAH"> </A> +<H3>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'). + + +<A NAME="lbAI"> </A> +<H3>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>. + +<A NAME="lbAJ"> </A> +<H3>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. + +<A NAME="lbAK"> </A> +<H2>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> +<A NAME="index"> </A><H2>Table Of Contents</H2> +<UL> +<LI><A HREF="#lbAB">NAME</A> +<LI><A HREF="#lbAC">SYNOPSIS</A> +<LI><A HREF="#lbAD">DESCRIPTION</A> +<UL> +<LI><A HREF="#lbAE">TYPES AND CONSTANTS</A> +<LI><A HREF="#lbAF">INITIALIZATION</A> +<LI><A HREF="#lbAG">MEMORY MANAGEMENT</A> +<LI><A HREF="#lbAH">READING FILES</A> +<LI><A HREF="#lbAI">WRITING FILES</A> +<LI><A HREF="#lbAJ">MISCELLANEOUS</A> +</UL> +<LI><A HREF="#lbAK">SEE ALSO</A> +</UL> +</BODY> +</HTML> |