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 in‐
20 terface 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
82 This fills a closed path.
84 pixels, cols, rows, and maxval describe the canvas on which to draw.
86 pathP identifies a closed path on that canvas. If it does not end on
88 the same point at which it starts, ppmd_fill_path aborts the program
89 with a call to pm_error. The path may cross itself, though, creating
90 multiple closed areas, each of which ppmd_fill_path fills. The path
91 must fit within the cols x rows dimensions. If it does not,
92 ppmd_fill_path aborts the program with a call to pm_error.
93 color is the fill color. ppmd_fill_path makes every pixel within the
95 closed path that color.
96 ppmd_fill is more general, but harder to use. With that, you can fill
98 with a pattern.
99 This function was new in Netpbm 10.34 (June 2006).
101 ppmd_makeLineLeg
104 This function returns a data structure of type ppmd_pathleg, to be used
105 in a data structure of type ppmd_path, to be use with function
106 ppmd_fill_path.
107 This function was new in Netbm 10.78 (March 2017).
109
113 The functions in this section are for building a path (ppmd_path) for
114 use with ppmd_fill_path.
115 It is an object-oriented set of functions, where the object involved is
117 of type ppmd_path_builder. This is an opaque structure that you should
118 not access directly, but only through the functions in this section.
119 Here is an example that generates a filled rectangle:
121 pixels = ppm_allocarray(100, 100);
123 unsigned int row;
125 /* Initialize the canvas to all black */
127 for (row = 0; row < 100; ++row) {
128 unsigned int col;
129 for (col = 0; col < 100; ++col)
130 pixels[row][col] = ppm_blackpixel();
131 }
132 /* Create a rectangular path */
134 ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
135 ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
137 ppmd_pathbuilder_addLineLeg(pathBuilderP,
139 ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
140 ppmd_pathbuilder_addLineLeg(pathBuilderP,
142 ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
143 ppmd_pathbuilder_addLineLeg(pathBuilderP,
145 ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
146 ppmd_pathbuilder_addLineLeg(pathBuilderP,
148 ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
149 /* Fill the area enclosed by that path with white */
151 ppmd_fill_path(pixels, 100, 100, PPM_MAXMAXVAL,
152 ppmd_pathbuilder_pathP(pathBuilderP),
153 ppm_whitepixel(PPM_MAXMAXVAL));
154 /* Destroy the path */
156 ppmd_pathbuilder_destroy(pathBuilderP);
157 There are two ways to manage the space in which the leg array of the
160 ppmd_path structure resides. Either you supply a fixed-length array
161 and the path builder just uses it or you have the path builder allocate
162 the storage automatically.
163 If you let the path builder allocate the space automatically, you can
165 nonetheless tell the path builder how much space to allocate initially,
166 to make the path building more efficient.
167 This facility was new in Netpbm 10.78 (March 2017). Before that, you
169 have to build the ppmd_path by directly setting its members.
170 ppmd_path_builder
173 This creates a ppmd_path_builder object (i.e. allocates memory for it
174 and initializes it). You must ultimately destroy it with
175 ppmd_path_builder_destroy.
176 ppmd_path_builder_destroy
180 This destroys a ppmd_path_builder object created with
181 ppmd_path_builder_create (i.e. frees the memory).
182 Synopsis
184 void
186 ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
187 ppmd_pathbuilder_setLegArray
191 With this function you supply the array of legs that the path builder
192 will fill. The array has a fixed size, so you must know in advance how
193 long the path you build might be.
194 Example
196 ppmd_pathleg legs[4];
198 ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
200 Synopsis
203 void
205 ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
206 ppmd_pathleg * legs,
207 unsigned int legCount);
208 Description
211 pathBuilderP is the handle of the path builder object.
213 legs is the array you are supplying for the object to fill in. This is
215 just space; no value the array has upon invocation is meaningful.
216 legCount is the number of elements of space exist in legs. I.e. this
218 is the maximum number of legs the builder can put in the array. Any
219 attempt to put more legs than this in the array fails.
220 This fails if the leg array is already set up, which could be because
222 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
223 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
224 ppmd_pathbuilder_preallocLegArray
227 This causes the object to allocate some space for the array of path
228 legs the path builder will create. If it needs more space, it will re‐
229 allocate. In fact, you need not call this at all, because the path
230 builder will allocate space the first time it needs it.
231 Synopsis
233 void
235 ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
236 unsigned int legCount);
237 Description
240 pathBuilderP is the handle of the path builder object.
242 legCount is how many legs' worth of space to allocate.
244 This fails if the leg array is already set up, which could be because
246 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
247 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
248 ppmd_pathbuilder_setBegPoint
252 This sets the beginning point for the path. Note that to use the path
253 for filling, you must also make this the point at which the last leg of
254 the path ends.
255 Synopsis
257 void
259 ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
260 ppmd_piont begPoint);
261 Description
264 pathBuilderP is the handle of the path builder object.
266 begPoint is the beginning point of the path.
268 ppmd_pathbuilder_addLineLeg
272 This adds a line segment leg to the path.
273 Synopsis
275 void
277 ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
278 ppmd_pathleg leg);
279 Description
282 pathBuilderP is the handle of the path builder object.
284 leg is the leg to add.
286 The leg begins wherever the end of the path currently is (i.e. where
288 the most recently added leg ends, or the beginning point if you have
289 not added any paths yet).
290 ppmd_pathbuilder_pathP
293 This is a pointer to the path that the path builder has built.
294 Synopsis
296 void
298 ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
299 Description
302 pathBuilderP is the handle of the path builder object.
304 The data structure belongs to the path builder, so you must not use it
306 after you have destroyed the ppmd_pathbuilder object.
307 The pointer is valid only until you call the next path builder method
309 other than ppmd_pathbuilder_pathP. You normally don't get the pointer
310 until you are done building the path.
311
315 The ppmd_text and ppmd_text_box functions use fonts. You control the
316 fonts using functions described in this section. There is one font
317 that comes with Netpbm, called "standard". It is built into the func‐
318 tion library and is the default font. You can create additional fonts
319 and use them instead.
320 In a program that uses Netpbm drawing facilities, there is a "current
322 font." all drawing of text uses the current font. When the program
323 starts, the current font is "standard"; you can change it after that by
324 calling the ppmd_set_font function.
325 Other than a built-in font, a font lives in file in a format special to
327 Netpbm called Ppmdfont. The file typically has a name that ends in
328 ".ppmdfont".
329 Use the ppmddumpfont program to dump the contents of a Ppmdfont file in
331 human readable format.
332 Use the ppmdmkfont program to generate the "standard" font as a Ppmd‐
334 font file. You don't normally need to do this, because "standard" is
335 built into libnetpbm.
336 Use the ppmdcfont program to turn a Ppmdfont file into a C source file
338 that you can compile into a program as a built-in font. Though we
339 don't give full instructions here on how to do that, libnetpbm's built-
340 in "standard" font is a good example. In Netpbm source code, you will
341 find the C source file standardppmdfont.c, which was generated from the
342 file standard.ppmdfont by ppmdcfont. You simply use a pointer to the
343 structure that the C file defines as a font handle, just like one you
344 would get from ppmd_read_font.
345
349 The font file starts with the characters "ppmdfont" (without the quota‐
350 tion marks) in ASCII.
351 The rest of the format is not yet documented, but it generally de‐
353 scribes, for each code point, a sequence of straight line plotting com‐
354 mands to form the glyph for the indicated character. I.e. it is a vec‐
355 tor, not raster, font.
356
360 These functions are declared in the header file ppmdfont.h.
361 ppmd_read_font
364 This function associates a Ppmdfont file, which you identify by naming
365 the Ppmdfont file, with a handle that you can use to identify the font
366 to other functions. Technically, this function reads the font into
367 memory.
368 ppmd_free_font
371 This function releases the handle that you get from ppmd_read_font. It
372 frees resources associated with it; you can't use the handle after
373 this.
374 ppmd_get_font
377 This function returns the handle of the currently selected font.
378 ppmd_set_font
381 This function sets the currently selected font. You identify the font
382 to which to set it with a handle such as you get from ppmd_read_font or
383 ppmd_get_font.
384
386 This manual page was generated by the Netpbm tool 'makeman' from HTML
387 source. The master documentation is at
388 http://netpbm.sourceforge.net/doc/libnetpbm_draw.html
390netpbm documentation AprilLi2b0n1e8tpbm PPM Drawing Function Manual(3)