1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html>
<head>
<title>User manual for old pbm functions</title>
<meta name="manual_section" content="3">
</head>
<body>
<h1>pbm Functions</h1>
Updated: 08 September 2007
<br>
<a href="#index">Table Of Contents</a>
<h2>NAME</h2>
libpbm - libnetpbm functions to read and write PBM image files
<h2 id="synopsis">SYNOPSIS</h2>
<b>#include <netpbm/pbm.h></b>
<p>
<b>bit **pbm_allocarray(int</b>
<i>cols</i><b>, int </b><i>rows</i><b>);</b>
<p>
<b>bit *pbm_allocrow(int</b>
<i>cols</i><b>);</b>
<p>
<b>pbm_freearray(bit </b>
<b>**</b><i>bits</i><b>, int </b><i>rows</i><b>);</b>
<p>
<b>pbm_freerow(bit</b>
<b>*</b><i>bitrow</i><b>);</b>
<p>
<b>void pbm_readpbminit(FILE *</b>
<i>fp</i><b>,
int *</b><i>colsP</i><b>,
int *</b><i>rowsP</i><b>,
int *</b><i>formatP</i><b>);</b>
<p>
<b>void pbm_readpbmrow(FILE *</b>
<i>fp</i><b>,
bit *</b><i>bitrow</i><b>,
int </b><i>cols</i><b>,
int </b><i>format</i><b>);</b>
<p>
<b>void pbm_readpbmrow_packed(FILE *</b>
<i>fp</i><b>,</b>
<br>
<b>unsigned char * const </b><i>packed_bits</i><b>,</b>
<b>const int </b><i>cols</i><b>,</b>
<b>const int </b><i>format</i><b>);</b>
<p>
<b>void bit** pbm_readpbm(FILE *</b>
<i>fp</i><b>, int *</b><i>colsP</i><b>, int *</b><i>rowsP</i><b>);</b>
<p>
<b>void pbm_writepbminit(FILE *</b>
<i>fp</i><b>,
int </b><i>cols</i><b>,
int </b><i>rows</i><b>,
int </b><i>forceplain</i><b>);</b>
<p>
<b>void pbm_writepbmrow(FILE *</b>
<i>fp</i><b>,
bit *</b><i>bitrow</i><b>,
int </b><i>cols</i><b>,
int </b><i>forceplain</i><b>);</b>
<p>
<b>void pbm_writepbmrow_packed(FILE *</b>
<i>fp</i><b>,</b>
<br>
<b>unsigned char * const </b><i>packed_bits</i><b>,</b>
<b>const int </b><i>cols</i><b>,</b>
<b>const int </b><i>forceplain</i><b>);</b>
<p>
<b>void pbm_writepbm(FILE *</b>
<i>fp</i><b>,
bit **</b><i>bits</i><b>,
int </b><i>cols</i><b>,
int </b><i>rows</i><b>,
int </b><i>forceplain</i><b>);</b>
<p>
<b>#define pbm_packed_bytes(</b><i>cols</i><b>) ...</b>
<p>
<b>void pbm_nextimage(</b>
<b>FILE *</b><i>file</i><b>,</b>
<b>int * const </b><i>eofP</i><b>);</b>
<p>
<b>void pbm_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>enum pm_check_code * const </b><i>retval</i><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>
<b>typedef ... bit;</b>
<p>
<b>#define PBM_WHITE ...</b>
<p>
<b>#define PBM_BLACK ...</b>
<p>Each <b>bit</b> should contain only the values of <b>PBM_WHITE</b>
or <b>PBM_BLACK</b>.
<p><b>#define PBM_FORMAT ...</b>
<p><b>#define RPBM_FORMAT ...</b>
<p><b>#define PBM_TYPE PBM_FORMAT</b>
<p><b>#define </b>
<b>PBM_FORMAT_TYPE(</b><i>f</i><b>) ...</b>
<p>These are for distinguishing different file formats and types.
<h3 id="initialization">INITIALIZATION</h3>
<p><b>pbm_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>pbm_init()</b> is identical to <b>pm_proginit</b>.
<h3 id="memorymanagement">MEMORY MANAGEMENT</h3>
<b>pbm_allocarray()</b> allocates an array of bits.
<b>pbm_allocrow()</b> allocates a row of the given number of bits.
<b>pbm_freearray()</b> frees the array allocated with
<b>pbm_allocarray()</b> containing the given number of rows.
<b>pbm_freerow()</b> frees a row of bits.
<h3 id="reading">READING PBM IMAGE FILES</h3>
<p><b>pbm_readpbminit()</b> reads the header from a PBM image in a PBM
file, filling in the rows, cols and format variables.
<b>pbm_readpbmrow()</b> reads a row of bits into the <i>bitrow </i>
array. Format and cols were filled in by <b>pbm_readpbminit()</b>.
<b>pbm_readpbmrow_packed()</b> is like <b>pbm_readpbmrow()</b> except
instead of returning a <b>bits</b> array, it returns an array
<i>packed_bits</i> of bytes with the pixels of the image row packed
into them. The pixels are in order from left to right across the row
and from the beginning of the array to the end. Within a byte, the
bits are in order from the most significant bit to the least
significant bit. If the number of pixels in the row is not a multiple
of 8, the last byte returned is padded on the least significant bit
side with undefined bits. White is represented by a <b>PBM_WHITE</b>
bit; black by <b>PBM_BLACK</b>.
<p><b>pbm_readpbm()</b> reads an entire bitmap file into memory,
returning the allocated array and filling in the rows and cols
variables. This function combines <b>pbm_readpbminit()</b>,
<b>pbm_allocarray()</b> and <b>pbm_readpbmrow()</b>.
<p><b>pbm_readpbminit()</b> and <b>pbm_readpbm</b> abort the program with
a message to Standard Error if the PBM 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').
<p><b>ppm_readppminit()</b> and <b>ppm_readppm</b> abort the program with
a message to Standard Error if the PPM 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 PBM IMAGE FILES</h3>
<b>pbm_writepbminit()</b> writes the header for a PBM image in a PBM
file. <i>forceplain</i> is a boolean value specifying that a plain
format (text) file to be written, as opposed to a raw format (binary)
one. <b>pbm_writepbmrow()</b> writes a row to a PBM file.
<b>pbm_writepbmrow_packed()</b> is the same as
<b>pbm_writepbmrow()</b> except that you supply the row to write as an
array of bytes packed with bits instead of as a <b>bits</b> array.
The format of <i>packed_bits </i> is the same as that returned by
<b>pbm_readpbmrow()</b>.
<p><b>pbm_writepbm()</b> writes the header and all data for a PBM
image to a PBM file. This function combines <b>pbm_writepbminit()</b>
and <b>pbm_writepbmrow()</b>.
<h3 id="miscellaneous">MISCELLANEOUS</h3>
<p><b>pbm_nextimage()</b> positions a PBM input file to the next image
in it (so that a subsequent <b>pbm_readpbminit()</b> reads its
header).
<p>Immediately before a call to <b>pbm_nextimage()</b>, the file must
be positioned either at its beginning (i.e. nothing has been read from
the file yet) or just after an image (i.e. as left by a
<b>pbm_readpbmrow() </b> of the last row in the image).
<p>Note that in the raw PNM and PAM format, the next image always
starts immediately after the previous image, so all
<b>pbm_nextimage()</b> really does is test whether there is a next
image or the file is positioned at end-of-file. In plain PNM, though,
there may be white space between images.
<p>If <b>pbm_nextimage() </b> successfully positions to the next
image, it returns <b>*</b><i>eofP</i> false (0). If there is no next
image in the file, it returns <b>*</b><i>eofP</i> true . If it can't
position or determine the file status because of a file error, it
<a href="liberror.html#error">throws an error</a>.
<p><b>pbm_check()</b> checks for the common file integrity error where
the file is the wrong size to contain all the image data.
<b>pbm_check()</b> assumes the file is positioned after an image
header (as if <b>pbm_readpbminit() </b> was the last operation on the
file). It checks the file size to see if the number of bytes left in
the file are the number required to contain the image raster. If the
file is too short, <b>pbm_check()</b> causes the program t <a
href="liberror.html#error">throws an error</a>. Otherwise, it returns
one of the following values (enumerations of the <b>enum
pm_check_code</b> type) as <b>*</b><i>retval</i>:
<dl compact>
<dt><b>PM_CHECK_OK</b>
<dd>The file's size is exactly what is required to hold the image raster.
<dt><b>PM_CHECK_UNKNOWN_TYPE</b>
<dd><i>format</i> is not a format whose size <b>pbm_check()</b> can
anticipate. The only format with which <b>pbm_check()</b> can deal is
raw PBM format.
<dt><b>PM_CHECK_TOO_LONG</b>
<dd>The file is longer than it needs to be to contain the image
raster. The extra data might be another image.
<dt><b>PM_CHECK_UNCHECKABLE</b>
<dd>The file is not a kind that has a predictable size, so there is no
simple way for <b>pbm_check()</b> to know if it is the right size.
Only a regular file has predictable size. A pipe is a common example
of a file that does not.
</dl>
<p><i>check_type</i> must have the value <b>PM_CHECK_BASIC </b> (an
enumerated value of the <b>pm_check_type</b> enumerated type).
Otherwise, the effect of <b>pbm_check()</b> is unpredictable. This
argument exists for future backward compatible expansion of the
function of <b>pbm_check()</b>.
<h2 id="seealso">SEE ALSO</h2>
<b><a href="libpgm.html">libpgm</a></b>,
<b><a href="libppm.html">libppm</a></b>,
<b><a href="libpnm.html">libpnm</a></b>,
<b><a href="pbm.html">pbm</a></b>
<h2 id="author">AUTHOR</h2>
Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
<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 PBM IMAGE FILES</a>
<li><a href="#writing">WRITING PBM IMAGE FILES</a>
<li><a href="#miscellaneous">MISCELLANEOUS</a>
</ul>
<li><a href="#seealso">SEE ALSO</a>
<li><a href="#author">AUTHOR</a>
</ul>
</body>
</html>
|
