1Libnetpbm PPM Drawing FunctiLoinbrMaarnyuaFlu(n3cL)tiibonnestpMbamnuPaPlM Drawing Function Manual(3)
2 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 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 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
28 The functions are all declared in the ppmdraw.h header file.
29 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 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 ppmd_point_drawproc
52 This simply fills in a single pixel. This is usually what you want.
53 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 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
69 ppmd_fill_path
70 Synopsis
71 void
73 ppmd_fill_path(pixel ** pixels,
74 int cols,
75 int rows,
76 pixval maxval,
77 ppmd_path * pathP,
78 pixel color);
79 Description
81 This fills a closed path.
83 pixels, cols, rows, and maxval describe the canvas on which to draw.
85 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 color is the fill color. ppmd_fill_path makes every pixel within the
94 closed path that color.
95 ppmd_fill is more general, but harder to use. With that, you can fill
97 with a pattern.
98 This function was new in Netpbm 10.34 (June 2006).
100 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 This function was new in Netbm 10.78 (March 2017).
108
112 The functions in this section are for building a path (ppmd_path) for
113 use with ppmd_fill_path.
114 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 Here is an example that generates a filled rectangle:
120 pixels = ppm_allocarray(100, 100);
122 unsigned int row;
124 /* 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 /* Create a rectangular path */
133 ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
134 ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
136 ppmd_pathbuilder_addLineLeg(pathBuilderP,
138 ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
139 ppmd_pathbuilder_addLineLeg(pathBuilderP,
141 ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
142 ppmd_pathbuilder_addLineLeg(pathBuilderP,
144 ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
145 ppmd_pathbuilder_addLineLeg(pathBuilderP,
147 ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
148 /* 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 /* Destroy the path */
155 ppmd_pathbuilder_destroy(pathBuilderP);
156 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 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 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 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 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 Synopsis
182 void
184 ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
185 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 Example
193 ppmd_pathleg legs[4];
195 ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
197 Synopsis
199 void
201 ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
202 ppmd_pathleg * legs,
203 unsigned int legCount);
204 Description
206 pathBuilderP is the handle of the path builder object.
208 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 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 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 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 Synopsis
228 void
230 ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
231 unsigned int legCount);
232 Description
234 pathBuilderP is the handle of the path builder object.
236 legCount is how many legs' worth of space to allocate.
238 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 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 Synopsis
251 void
253 ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
254 ppmd_piont begPoint);
255 Description
257 pathBuilderP is the handle of the path builder object.
259 begPoint is the beginning point of the path.
261 ppmd_pathbuilder_addLineLeg
265 This adds a line segment leg to the path.
266 Synopsis
268 void
270 ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
271 ppmd_pathleg leg);
272 Description
274 pathBuilderP is the handle of the path builder object.
276 leg is the leg to add.
278 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 ppmd_pathbuilder_pathP
285 This is a pointer to the path that the path builder has built.
286 Synopsis
288 void
290 ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
291 Description
293 pathBuilderP is the handle of the path builder object.
295 The data structure belongs to the path builder, so you must not use it
297 after you have destroyed the ppmd_pathbuilder object.
298 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
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 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 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 Use the ppmddumpfont program to dump the contents of a Ppmdfont file in
322 human readable format.
323 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 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
340 The font file starts with the characters "ppmdfont" (without the quota‐
341 tion marks) in ASCII.
342 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
351 These functions are declared in the header file ppmdfont.h.
352 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 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 ppmd_get_font
368 This function returns the handle of the currently selected font.
369 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 http://netpbm.sourceforge.net/doc/libnetpbm_draw.html
381netpbm documentation AprilLi2b0n1e8tpbm PPM Drawing Function Manual(3)