1Libnetpbm PPM Drawing FunctiLoinbrMaarnyuaFlu(n3cL)tiibonnestpMbamnuPaPlM Drawing Function Manual(3)
2
3
4
5 Table Of Contents ⟨#toc⟩
6
8 libnetpbm_draw \- Libnetpbm PPM Drawing Function Manual
9
11 This reference manual covers functions in the libnetpbm library for
12 drawing images, using the PPM image format and the libnetpbm in-memory
13 image formats.
14
15 We actually have very little information here; this is mainly a frame‐
16 work for adding documentation later if someone becomes interested in
17 this facility.
18
19 Note that the Netpbm program ppmdraw is essentially a command-line
20 interface to the functions of this library. You can use that program's
21 source code as an example, or just invoke that program instead of call‐
22 ing these functions. The netpbm program ppmlabel is another good exam‐
23 ple of using these functions.
24
25
26
28 The functions are all declared in the ppmdraw.h header file.
29
30
31 ppmd_setlinetype
32 ppmd_setlineclip
33 ppmd_line
34 ppmd_spline3
35 ppmd_polyspline
36 ppmd_circle
37 ppmd_filledrectangle
38 ppmd_fill
39 ppmd_text
40 ppmd_text_box
42 Drawprocs are functions that tell how to draw a point. You pass draw‐
43 procs to drawing functions that require them.
44
45 There are two types: ppmd_drawprocp and ppmd_drawproc. The only dif‐
46 ference is that the former takes the location at which to draw the
47 point as an argument of point type (ppmd_point), whereas the latter
48 takes integer column and row arguments.
49
50
51 ppmd_point_drawproc
52 This simply fills in a single pixel. This is usually what you want.
53
54
55
56 ppmd_fill_drawprocp
57 This Drawproc is useful for filling, in that it not only draws on the
58 canvas, but remembers where it's been, outlining an area that you can
59 fill with ppmd_fill.
60
61
62 ppmd_fill_drawproc
63 This is the same thing as ppmd_fill_drawprocp except that it is a
64 ppmd_drawproc function instead of ppmd_drawprocp.
65
66
67
69 ppmd_fill_path
70 Synopsis
71
72 void
73 ppmd_fill_path(pixel ** pixels,
74 int cols,
75 int rows,
76 pixval maxval,
77 ppmd_path * pathP,
78 pixel color);
79
80 Description
81
82 This fills a closed path.
83
84 pixels, cols, rows, and maxval describe the canvas on which to draw.
85
86 pathP identifies a closed path on that canvas. If it does not end on
87 the same point at which it starts, ppmd_fill_path aborts the program
88 with a call to pm_error. The path may cross itself, though, creating
89 multiple closed areas, each of which ppmd_fill_path fills. The path
90 must fit within the cols x rows dimensions. If it does not,
91 ppmd_fill_path aborts the program with a call to pm_error.
92
93 color is the fill color. ppmd_fill_path makes every pixel within the
94 closed path that color.
95
96 ppmd_fill is more general, but harder to use. With that, you can fill
97 with a pattern.
98
99 This function was new in Netpbm 10.34 (June 2006).
100
101
102 ppmd_makeLineLeg
103 This function returns a data structure of type ppmd_pathleg, to be used
104 in a data structure of type ppmd_path, to be use with function
105 ppmd_fill_path.
106
107 This function was new in Netbm 10.78 (March 2017).
108
109
110
112 The functions in this section are for building a path (ppmd_path) for
113 use with ppmd_fill_path.
114
115 It is an object-oriented set of functions, where the object involved is
116 of type ppmd_path_builder. This is an opaque structure that you should
117 not access directly, but only through the functions in this section.
118
119 Here is an example that generates a filled rectangle:
120
121 pixels = ppm_allocarray(100, 100);
122
123 unsigned int row;
124
125 /* Initialize the canvas to all black */
126 for (row = 0; row < 100; ++row) {
127 unsigned int col;
128 for (col = 0; col < 100; ++col)
129 pixels[row][col] = ppm_blackpixel();
130 }
131
132 /* Create a rectangular path */
133 ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
134
135 ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
136
137 ppmd_pathbuilder_addLineLeg(pathBuilderP,
138 ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
139
140 ppmd_pathbuilder_addLineLeg(pathBuilderP,
141 ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
142
143 ppmd_pathbuilder_addLineLeg(pathBuilderP,
144 ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
145
146 ppmd_pathbuilder_addLineLeg(pathBuilderP,
147 ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
148
149 /* Fill the area enclosed by that path with white */
150 ppmd_fill_path(pixels, 100, 100, PPM_MAXMAXVAL,
151 ppmd_pathbuilder_pathP(pathBuilderP),
152 ppm_whitepixel(PPM_MAXMAXVAL));
153
154 /* Destroy the path */
155 ppmd_pathbuilder_destroy(pathBuilderP);
156
157 There are two ways to manage the space in which the leg array of the
158 ppmd_path structure resides. Either you supply a fixed-length array
159 and the path builder just uses it or you have the path builder allocate
160 the storage automatically.
161
162 If you let the path builder allocate the space automatically, you can
163 nonetheless tell the path builder how much space to allocate initially,
164 to make the path building more efficient.
165
166 This facility was new in Netpbm 10.78 (March 2017). Before that, you
167 have to build the ppmd_path by directly setting its members.
168
169
170 ppmd_path_builder
171 This creates a ppmd_path_builder object (i.e. allocates memory for it
172 and initializes it). You must ultimately destroy it with
173 ppmd_path_builder_destroy.
174
175
176
177 ppmd_path_builder_destroy
178 This destroys a ppmd_path_builder object created with
179 ppmd_path_builder_create (i.e. frees the memory).
180
181 Synopsis
182
183 void
184 ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
185
186
187 ppmd_pathbuilder_setLegArray
188 With this function you supply the array of legs that the path builder
189 will fill. The array has a fixed size, so you must know in advance how
190 long the path you build might be.
191
192 Example
193
194 ppmd_pathleg legs[4];
195
196 ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
197
198 Synopsis
199
200 void
201 ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
202 ppmd_pathleg * legs,
203 unsigned int legCount);
204
205 Description
206
207 pathBuilderP is the handle of the path builder object.
208
209 legs is the array you are supplying for the object to fill in. This is
210 just space; no value the array has upon invocation is meaningful.
211
212 legCount is the number of elements of space exist in legs. I.e. this
213 is the maximum number of legs the builder can put in the array. Any
214 attempt to put more legs than this in the array fails.
215
216 This fails if the leg array is already set up, which could be because
217 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
218 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
219
220
221 ppmd_pathbuilder_preallocLegArray
222 This causes the object to allocate some space for the array of path
223 legs the path builder will create. If it needs more space, it will
224 reallocate. In fact, you need not call this at all, because the path
225 builder will allocate space the first time it needs it.
226
227 Synopsis
228
229 void
230 ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
231 unsigned int legCount);
232
233 Description
234
235 pathBuilderP is the handle of the path builder object.
236
237 legCount is how many legs' worth of space to allocate.
238
239 This fails if the leg array is already set up, which could be because
240 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
241 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
242
243
244
245 ppmd_pathbuilder_setBegPoint
246 This sets the beginning point for the path. Note that to use the path
247 for filling, you must also make this the point at which the last leg of
248 the path ends.
249
250 Synopsis
251
252 void
253 ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
254 ppmd_piont begPoint);
255
256 Description
257
258 pathBuilderP is the handle of the path builder object.
259
260 begPoint is the beginning point of the path.
261
262
263
264 ppmd_pathbuilder_addLineLeg
265 This adds a line segment leg to the path.
266
267 Synopsis
268
269 void
270 ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
271 ppmd_pathleg leg);
272
273 Description
274
275 pathBuilderP is the handle of the path builder object.
276
277 leg is the leg to add.
278
279 The leg begins wherever the end of the path currently is (i.e. where
280 the most recently added leg ends, or the beginning point if you have
281 not added any paths yet).
282
283
284 ppmd_pathbuilder_pathP
285 This is a pointer to the path that the path builder has built.
286
287 Synopsis
288
289 void
290 ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
291
292 Description
293
294 pathBuilderP is the handle of the path builder object.
295
296 The data structure belongs to the path builder, so you must not use it
297 after you have destroyed the ppmd_pathbuilder object.
298
299 The pointer is valid only until you call the next path builder method
300 other than ppmd_pathbuilder_pathP. You normally don't get the pointer
301 until you are done building the path.
302
303
304
306 The ppmd_text and ppmd_text_box functions use fonts. You control the
307 fonts using functions described in this section. There is one font
308 that comes with Netpbm, called "standard". It is built into the func‐
309 tion library and is the default font. You can create additional fonts
310 and use them instead.
311
312 In a program that uses Netpbm drawing facilities, there is a "current
313 font." all drawing of text uses the current font. When the program
314 starts, the current font is "standard"; you can change it after that by
315 calling the ppmd_set_font function.
316
317 Other than a built-in font, a font lives in file in a format special to
318 Netpbm called Ppmdfont. The file typically has a name that ends in
319 ".ppmdfont".
320
321 Use the ppmddumpfont program to dump the contents of a Ppmdfont file in
322 human readable format.
323
324 Use the ppmdmkfont program to generate the "standard" font as a Ppmd‐
325 font file. You don't normally need to do this, because "standard" is
326 built into libnetpbm.
327
328 Use the ppmdcfont program to turn a Ppmdfont file into a C source file
329 that you can compile into a program as a built-in font. Though we
330 don't give full instructions here on how to do that, libnetpbm's built-
331 in "standard" font is a good example. In Netpbm source code, you will
332 find the C source file standardppmdfont.c, which was generated from the
333 file standard.ppmdfont by ppmdcfont. You simply use a pointer to the
334 structure that the C file defines as a font handle, just like one you
335 would get from ppmd_read_font.
336
337
338
340 The font file starts with the characters "ppmdfont" (without the quota‐
341 tion marks) in ASCII.
342
343 The rest of the format is not yet documented, but it generally
344 describes, for each code point, a sequence of straight line plotting
345 commands to form the glyph for the indicated character. I.e. it is a
346 vector, not raster, font.
347
348
349
351 These functions are declared in the header file ppmdfont.h.
352
353
354 ppmd_read_font
355 This function associates a Ppmdfont file, which you identify by naming
356 the Ppmdfont file, with a handle that you can use to identify the font
357 to other functions. Technically, this function reads the font into
358 memory.
359
360
361 ppmd_free_font
362 This function releases the handle that you get from ppmd_read_font. It
363 frees resources associated with it; you can't use the handle after
364 this.
365
366
367 ppmd_get_font
368 This function returns the handle of the currently selected font.
369
370
371 ppmd_set_font
372 This function sets the currently selected font. You identify the font
373 to which to set it with a handle such as you get from ppmd_read_font or
374 ppmd_get_font.
375
377 This manual page was generated by the Netpbm tool 'makeman' from HTML
378 source. The master documentation is at
379
380 http://netpbm.sourceforge.net/doc/libnetpbm_draw.html
381
382netpbm documentation AprilLi2b0n1e8tpbm PPM Drawing Function Manual(3)