1\
2.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
4.\" the corresponding HTML page on the Netpbm website, generate a patch
5.\" against that, and send it to the Netpbm maintainer.
6.TH "User manual for old pgm functions" 3 "8 September 2007" "netpbm documentation"
7
8.SH NAME
9libpgm - libnetpbm functions to read and write PGM image files
10
11.UN synopsis
12.SH SYNOPSIS
13
14\fB#include <netpbm/pgm.h>\fP
15.PP
16\fBvoid pgm_init( \fP
17\fBint *\fP\fIargcP\fP\fB,\fP
18\fBchar *\fP\fIargv\fP\fB[]\fP
19\fB);\fP
20.PP
21\fBgray ** pgm_allocarray(\fP
22\fBint \fP\fIcols\fP\fB,\fP
23\fBint \fP\fIrows\fP\fB );\fP
24.PP
25\fBgray * pgm_allocrow(\fP
26\fBint\fP\fIcols\fP\fB );\fP
27.PP
28\fBvoid pgm_freearray(\fP
29\fBgray **\fP\fIgrays\fP\fB,\fP
30\fBint\fP\fIrows\fP\fB );\fP
31.PP
32\fBvoid pgm_freerow(\fP
33\fBgray *\fP\fIgrayrow\fP\fB);\fP
34.PP
35\fBvoid pgm_readpgminit( \fP
36\fBFILE *\fP\fIfp\fP\fB,\fP
37\fBint *\fP\fIcolsP\fP\fB,\fP
38\fBint *\fP\fIrowsP\fP\fB,\fP
39\fBgray *\fP\fImaxvalP\fP\fB,\fP
40\fBint *\fP\fIformatP\fP\fB );\fP
41.PP
42\fBvoid pgm_readpgmrow( \fP
43\fBFILE *\fP\fIfp\fP\fB,\fP
44\fBgray *\fP\fIgrayrow\fP\fB,\fP
45\fBint \fP\fIcols\fP\fB,\fP
46\fBgray \fP\fImaxval\fP\fB,\fP
47\fBint \fP\fIformat\fP\fB );\fP
48.PP
49\fBgray ** pgm_readpgm( \fP
50\fBFILE *\fP\fIfp\fP\fB,\fP
51\fBint *\fP\fIcolsP\fP\fB,\fP
52\fBint *\fP\fIrowsP\fP\fB,\fP
53\fBgray *\fP\fImaxvalP\fP\fB );\fP
54.PP
55\fBvoid pgm_writepgminit( \fP
56\fBFILE *  fp , \fP
57\fBint \fP\fIcols\fP\fB,\fP
58\fBint \fP\fIrows\fP\fB,\fP
59\fBgray \fP\fImaxval\fP\fB,\fP
60\fBint \fP\fIforceplain\fP\fB );\fP
61.PP
62\fBvoid pgm_writepgmrow( \fP
63\fBFILE *\fP\fIfp\fP\fB,\fP
64\fBgray *\fP\fIgrayrow\fP\fB,\fP
65\fBint cols\fP\fI,\fP
66\fBgray \fP\fImaxval\fP\fB,\fP
67\fBint \fP\fIforceplain\fP\fB );\fP
68.PP
69\fBvoid pgm_writepgm( \fP
70\fBFILE *\fP\fIfp\fP\fB,\fP
71\fBgray ** \fP\fIgrays\fP\fB,\fP
72\fBint \fP\fIcols\fP\fB,\fP
73\fBint \fP\fIrows\fP\fB,\fP
74\fBgray \fP\fImaxval\fP\fB,\fP
75\fBint \fP\fIforceplain\fP\fB );\fP
76.PP
77\fBvoid pgm_writepgm( \fP
78\fBFILE *\fP\fIfp\fP\fB,\fP
79\fBgray **\fP\fIgrays\fP\fB,\fP
80\fBint \fP\fIcols\fP\fB,\fP
81\fBint \fP\fIrows\fP\fB,\fP
82\fBgray \fP\fImaxval\fP\fB,\fP
83\fBint \fP\fIforceplain\fP\fB );\fP
84.PP
85\fBvoid pgm_nextimage(\fP
86\fBFILE *\fP\fIfile\fP\fB,\fP
87\fBint * const \fP\fIeofP\fP\fB);\fP
88.PP
89\fBvoid pgm_check(\fP
90\fBFILE * \fP\fIfile\fP\fB,\fP
91\fBconst enum pm_check_type \fP\fIcheck_type\fP\fB,\fP
92\fBconst int \fP\fIformat\fP\fB,\fP
93\fBconst int \fP\fIcols\fP\fB,\fP
94\fBconst int \fP\fIrows\fP\fB,\fP
95\fBconst int \fP\fImaxval\fP\fB,\fP
96\fBenum pm_check_code * const \fP\fIretval\fP\fB);\fP
97.PP
98\fBtypedef ... gray;\fP
99.PP
100\fB#define PGM_MAXMAXVAL ...\fP
101.PP
102\fB#define PGM_OVERALLMAXVAL ...\fP
103.PP
104\fB#define PGM_FORMAT ...\fP
105.PP
106\fB#define RPGM_FORMAT ...\fP
107.PP
108\fB#define PGM_TYPE PGM_FORMAT\fP
109.PP
110\fB#define \fP
111
112\fBPGM_FORMAT_TYPE(\fP\fIformat\fP\fB)\fP
113\fB...\fP
114
115.UN description
116.SH DESCRIPTION
117.PP
118These library functions are part of
119.BR "Netpbm" (1)\c
120\&.
121
122.UN types
123.SS TYPES AND CONSTANTS
124.PP
125Each \fBgray\fP should contain only the values between \fB0\fP
126and \fBPGM_OVERALLMAXVAL\fP.
127.PP
128\fBPGM_OVERALLMAXVAL\fP is the maximum value of a maxval in a PGM
129file.  \fBPGM_MAXMAXVAL\fP is the maximum value of a maxval in a PGM
130file that is compatible with the PGM format as it existed before April
1312000.  It is also the maximum value of a maxval that results in the
132minimum possible raster size for a particular image.  I.e an image
133with a maxval higher than \fBPGM_MAXMAXVAL\fP cannot be read or
134generated by old PGM processing programs and requires more file space.
135.PP
136\fBPGM_FORMAT \fP is the format code for a Plain PGM format image
137file.  \fBRPGM_FORMAT\fP is the format code for a Raw PGM format
138image file.  \fBPGM_TYPE \fP is the format type code for the PGM
139formats.  \fBPGM_FORMAT_TYPE\fP is a macro that generates code to
140compute the format type code of a PBM or PGM format from the format
141code which is its argument.
142
143.UN initialization
144.SS INITIALIZATION
145.PP
146\fBpgm_init()\fP is obsolete (at least since Netpbm 9.25 (March 2002)).
147Use
148.UR libpm.html#initialization
149\fBpm_proginit()\fP
150.UE
151\& instead.
152.PP
153\fBpgm_init()\fP is identical to \fBpm_proginit\fP.
154
155
156.UN memorymanagement
157.SS MEMORY MANAGEMENT
158
159\fBpgm_allocarray()\fP allocates an array of grays.
160.PP
161\fBpgm_allocrow()\fP allocates a row of the given number of grays.
162.PP
163\fBpgm_freearray()\fP frees the array allocated with
164\fBpgm_allocarray()\fP containing the given number of rows.
165.PP
166\fBpgm_freerow()\fP frees a row of grays allocated with
167\fBpgm_allocrow()\fP.
168
169.UN reading
170.SS READING FILES
171.PP
172If a function in this section is called on a PBM format file, it
173translates the PBM file into a PGM file on the fly and functions as if
174it were called on the equivalent PGM file.  The \fIformat\fP value
175returned by \fBpgm_readpgminit()\fP is, however, not translated.  It
176represents the actual format of the PBM file.
177.PP
178\fBpgm_readpgminit()\fP reads the header of a PGM file, returning
179all the information from the header and leaving the file positioned
180just after the header.
181.PP
182\fBpgm_readpgmrow()\fP reads a row of grays into the \fIgrayrow
183\fP array.  \fIformat\fP, \fIcols\fP, and \fImaxval \fP are the
184values returned by \fBpgm_readpgminit()\fP.
185.PP
186\fBpgm_readpgm()\fP reads an entire PGM image into memory,
187returning the allocated array as its return value and returning the
188information from the header as \fIrows\fP, \fIcols\fP, and
189\fImaxval\fP.  This function combines \fBpgm_readpgminit()\fP,
190\fBpgm_allocarray()\fP, and \fBpgm_readpgmrow()\fP.
191.PP
192\fBpgm_readpgminit()\fP and \fBpgm_readpgm\fP abort the program with
193a message to Standard Error if the PGM image header is not syntactically
194valid, including if it contains a number too large to be processed using
195the system's normal data structures (to wit, a number that won't fit in
196a C 'int').
197
198
199.UN writing
200.SS WRITING FILES
201
202\fBpgm_writepgminit()\fP writes the header for a PGM file and leaves
203it positioned just after the header.
204.PP
205\fIforceplain\fP is a logical value that tells
206\fBpgm_writepgminit() \fP to write a header for a plain PGM format
207file, as opposed to a raw PGM format file.
208.PP
209\fBpgm_writepgmrow()\fP writes the row \fIgrayrow\fP to a PGM
210file.  For meaningful results, \fIcols\fP, \fImaxval\fP, and
211\fIforceplain\fP must be the same as was used with
212\fBpgm_writepgminit()\fP.
213.PP
214\fBpgm_writepgm()\fP write the header and all data for a PGM
215image.  This function combines \fBpgm_writepgminit()\fP and
216\fBpgm_writepgmrow()\fP.
217
218.UN miscellaneous
219.SS MISCELLANEOUS
220.PP
221\fBpgm_nextimage()\fP positions a PGM input file to the next image
222in it (so that a subsequent \fBpgm_readpgminit()\fP reads its
223header).
224.PP
225\fBpgm_nextimage()\fP is analogous to \fBpbm_nextimage()\fP, but
226works on PGM and PBM files.
227.PP
228\fBpgm_check() \fP checks for the common file integrity error
229where the file is the wrong size to contain all the image data.
230.PP
231\fBpgm_check() \fP is analogous to \fBpbm_check()\fP, but works
232on PGM and PBM files.
233
234.UN seealso
235.SH SEE ALSO
236.BR "libpbm" (3)\c
237\&,
238.BR "libppm" (3)\c
239\&,
240.BR "libpnm" (3)\c
241\&
242.SH DOCUMENT SOURCE
243This manual page was generated by the Netpbm tool 'makeman' from HTML
244source.  The master documentation is at
245.IP
246.B http://netpbm.sourceforge.net/doc/libpgm.html
247.PP