1User manual for old pbm funcLtiibornasr(y3)FunctionUsseMranmuaanlual for old pbm functions(3)
2
6 libpbm - libnetpbm functions to read and write PBM image files
7
10 #include <netpbm/pbm.h>
11 bit **pbm_allocarray(int cols, int rows);
13 bit *pbm_allocrow(int cols);
15 pbm_freearray(bit **bits, int rows);
17 pbm_freerow(bit *bitrow);
19 void pbm_readpbminit(FILE * fp, int *colsP, int *rowsP, int *formatP);
21 void pbm_readpbmrow(FILE * fp, bit *bitrow, int cols, int format);
23 void pbm_readpbmrow_packed(FILE * fp, unsigned char * const
25 packed_bits, const int cols, const int format);
26 void bit** pbm_readpbm(FILE * fp, int *colsP, int *rowsP);
28 void pbm_writepbminit(FILE * fp, int cols, int rows, int forceplain);
30 void pbm_writepbmrow(FILE * fp, bit *bitrow, int cols, int forceplain);
32 void pbm_writepbmrow_packed(FILE * fp, unsigned char * const
34 packed_bits, const int cols, const int forceplain);
35 void pbm_writepbm(FILE * fp, bit **bits, int cols, int rows, int force‐
37 plain);
38 #define pbm_packed_bytes(cols) ...
40 void pbm_nextimage( FILE *file, int * const eofP);
42 void pbm_check( FILE * file, const enum pm_check_type check_type, const
44 int format, const int cols, const int rows, enum pm_check_code * const
45 retval);
46
50 These library functions are part of Netpbm(1).
51 TYPES AND CONSTANTS
54 typedef ... bit;
55 #define PBM_WHITE ...
57 #define PBM_BLACK ...
59 Each bit should contain only the values of PBM_WHITE or PBM_BLACK.
61 #define PBM_FORMAT ...
63 #define RPBM_FORMAT ...
65 #define PBM_TYPE PBM_FORMAT
67 #define PBM_FORMAT_TYPE(f) ...
69 These are for distinguishing different file formats and types.
71 INITIALIZATION
74 pbm_init() is obsolete (at least since Netpbm 9.25 (March 2002)). Use
75 pm_proginit() ⟨libpm.html#initialization⟩ instead.
76 pbm_init() is identical to pm_proginit.
78 MEMORY MANAGEMENT
81 pbm_allocarray() allocates an array of bits. pbm_allocrow() allocates
82 a row of the given number of bits. pbm_freearray() frees the array
83 allocated with pbm_allocarray() containing the given number of rows.
84 pbm_freerow() frees a row of bits.
85 READING PBM IMAGE FILES
89 pbm_readpbminit() reads the header from a PBM image in a PBM file,
90 filling in the rows, cols and format variables. pbm_readpbmrow() reads
91 a row of bits into the bitrow array. Format and cols were filled in by
92 pbm_readpbminit().
93 pbm_readpbmrow_packed() is like pbm_readpbmrow() except instead of
95 returning a bits array, it returns an array packed_bits of bytes with
96 the pixels of the image row packed into them. The pixels are in order
97 from left to right across the row and from the beginning of the array
98 to the end. Within a byte, the bits are in order from the most signif‐
99 icant bit to the least significant bit. If the number of pixels in the
100 row is not a multiple of 8, the last byte returned is padded on the
101 least significant bit side with undefined bits. White is represented
102 by a PBM_WHITE bit; black by PBM_BLACK.
103 pbm_readpbm() reads an entire bitmap file into memory, returning the
105 allocated array and filling in the rows and cols variables. This func‐
106 tion combines pbm_readpbminit(), pbm_allocarray() and pbm_readpbmrow().
107 pbm_readpbminit() and pbm_readpbm abort the program with a message to
109 Standard Error if the PBM image header is not syntactically valid,
110 including if it contains a number too large to be processed using the
111 system's normal data structures (to wit, a number that won't fit in a C
112 'int').
113 ppm_readppminit() and ppm_readppm abort the program with a message to
115 Standard Error if the PPM image header is not syntactically valid,
116 including if it contains a number too large to be processed using the
117 system's normal data structures (to wit, a number that won't fit in a C
118 'int').
119 WRITING PBM IMAGE FILES
122 pbm_writepbminit() writes the header for a PBM image in a PBM file.
123 forceplain is a boolean value specifying that a plain format (text)
124 file to be written, as opposed to a raw format (binary) one.
125 pbm_writepbmrow() writes a row to a PBM file. pbm_writepbmrow_packed()
126 is the same as pbm_writepbmrow() except that you supply the row to
127 write as an array of bytes packed with bits instead of as a bits array.
128 The format of packed_bits is the same as that returned by pbm_readpbm‐
129 row().
130 pbm_writepbm() writes the header and all data for a PBM image to a PBM
132 file. This function combines pbm_writepbminit() and pbm_writepbmrow().
133 MISCELLANEOUS
136 pbm_nextimage() positions a PBM input file to the next image in it (so
137 that a subsequent pbm_readpbminit() reads its header).
138 Immediately before a call to pbm_nextimage(), the file must be posi‐
140 tioned either at its beginning (i.e. nothing has been read from the
141 file yet) or just after an image (i.e. as left by a pbm_readpbmrow()
142 of the last row in the image).
143 Note that in the raw PNM and PAM format, the next image always starts
145 immediately after the previous image, so all pbm_nextimage() really
146 does is test whether there is a next image or the file is positioned at
147 end-of-file. In plain PNM, though, there may be white space between
148 images.
149 If pbm_nextimage() successfully positions to the next image, it
151 returns *eofP false (0). If there is no next image in the file, it
152 returns *eofP true . If it can't position or determine the file status
153 because of a file error, it throws an error ⟨liberror.html#error⟩ .
154 pbm_check() checks for the common file integrity error where the file
156 is the wrong size to contain all the image data. pbm_check() assumes
157 the file is positioned after an image header (as if pbm_readpbminit()
158 was the last operation on the file). It checks the file size to see if
159 the number of bytes left in the file are the number required to contain
160 the image raster. If the file is too short, pbm_check() causes the
161 program t throws an error ⟨liberror.html#error⟩ . Otherwise, it
162 returns one of the following values (enumerations of the enum
163 pm_check_code type) as *retval:
164 PM_CHECK_OK
168 The file's size is exactly what is required to hold the image
169 raster.
170 PM_CHECK_UNKNOWN_TYPE
173 format is not a format whose size pbm_check() can anticipate.
174 The only format with which pbm_check() can deal is raw PBM for‐
175 mat.
176 PM_CHECK_TOO_LONG
179 The file is longer than it needs to be to contain the image
180 raster. The extra data might be another image.
181 PM_CHECK_UNCHECKABLE
184 The file is not a kind that has a predictable size, so there is
185 no simple way for pbm_check() to know if it is the right size.
186 Only a regular file has predictable size. A pipe is a common
187 example of a file that does not.
188 check_type must have the value PM_CHECK_BASIC (an enumerated value of
192 the pm_check_type enumerated type). Otherwise, the effect of
193 pbm_check() is unpredictable. This argument exists for future backward
194 compatible expansion of the function of pbm_check().
195
198 libpgm(1), libppm(1), libpnm(1), pbm(1)
199
202 Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
203
205 This manual page was generated by the Netpbm tool 'makeman' from HTML
206 source. The master documentation is at
207 http://netpbm.sourceforge.net/doc/libpbm.html
209netpbm documentation 08 SeptemberUs2e0r07manual for old pbm functions(3)