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
22 The functions are all declared in the ppmdraw.h header file.
23 ppmd_setlinetype
26 ppmd_setlineclip
27 ppmd_line
28 ppmd_spline3
29 ppmd_polyspline
30 ppmd_circle
31 ppmd_filledrectangle
32 ppmd_fill
33 ppmd_text
34 ppmd_text_box
36 Drawprocs are functions that tell how to draw a point. You pass draw‐
37 procs to drawing functions that require them.
38 There are two types: ppmd_drawprocp and ppmd_drawproc. The only dif‐
40 ference is that the former takes the location at which to draw the
41 point as an argument of point type (ppmd_point), whereas the latter
42 takes integer column and row arguments.
43 ppmd_point_drawproc
46 This simply fills in a single pixel. This is usually what you want.
47 ppmd_fill_drawprocp
51 This Drawproc is useful for filling, in that it not only draws on the
52 canvas, but remembers where it's been, outlining an area that you can
53 fill with ppmd_fill.
54 ppmd_fill_drawproc
57 This is the same thing as ppmd_fill_drawprocp except that it is a
58 ppmd_drawproc function instead of ppmd_drawprocp.
59
63 ppmd_fill_path
64 Synopsis
65 void
67 ppmd_fill_path(pixel ** pixels,
68 int cols,
69 int rows,
70 pixval maxval,
71 ppmd_path * pathP,
72 pixel color);
73 Description
75 This fills a closed path.
77 pixels, cols, rows, and maxval describe the canvas on which to draw.
79 pathP identifies a closed path on that canvas. If it does not end on
81 the same point at which it starts, ppmd_fill_path aborts the program
82 with a call to pm_error. The path may cross itself, though, creating
83 multiple closed areas, each of which ppmd_fill_path fills. The path
84 must fit within the cols x rows dimensions. If it does not,
85 ppmd_fill_path aborts the program with a call to pm_error.
86 color is the fill color. ppmd_fill_path makes every pixel within the
88 closed path that color.
89 ppmd_fill is more general, but harder to use. With that, you can fill
91 with a pattern.
92 This function was new in Netpbm 10.34 (June 2006).
94 ppmd_makeLineLeg
97 This function returns a data structure of type ppmd_pathleg, to be used
98 in a data structure of type ppmd_path, to be use with function
99 ppmd_fill_path.
100 This function was new in Netbm 10.78 (March 2017).
102
106 The functions in this section are for building a path (ppmd_path) for
107 use with ppmd_fill_path.
108 It is an object-oriented set of functions, where the object involved is
110 of type ppmd_path_builder. This is an opaque structure that you should
111 not access directly, but only through the functions in this section.
112 Here is an example that generates a filled rectangle:
114 pixels = ppm_allocarray(100, 100);
116 unsigned int row;
118 /* Initialize the canvas to all black */
120 for (row = 0; row < 100; ++row) {
121 unsigned int col;
122 for (col = 0; col < 100; ++col)
123 pixels[row][col] = ppm_blackpixel();
124 }
125 /* Create a rectangular path */
127 ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
128 ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
130 ppmd_pathbuilder_addLineLeg(pathBuilderP,
132 ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
133 ppmd_pathbuilder_addLineLeg(pathBuilderP,
135 ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
136 ppmd_pathbuilder_addLineLeg(pathBuilderP,
138 ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
139 ppmd_pathbuilder_addLineLeg(pathBuilderP,
141 ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
142 /* Fill the area enclosed by that path with white */
144 ppmd_fill_path(pixels, 100, 100, PPM_MAXMAXVAL,
145 ppmd_pathbuilder_pathP(pathBuilderP),
146 ppm_whitepixel(PPM_MAXMAXVAL));
147 /* Destroy the path */
149 ppmd_pathbuilder_destroy(pathBuilderP);
150 There are two ways to manage the space in which the leg array of the
152 ppmd_path structure resides. Either you supply a fixed-length array
153 and the path builder just uses it or you have the path builder allocate
154 the storage automatically.
155 If you let the path builder allocate the space automatically, you can
157 nonetheless tell the path builder how much space to allocate initially,
158 to make the path building more efficient.
159 This facility was new in Netpbm 10.78 (March 2017). Before that, you
161 have to build the ppmd_path by directly setting its members.
162 ppmd_path_builder
165 This creates a ppmd_path_builder object (i.e. allocates memory for it
166 and initializes it). You must ultimately destroy it with
167 ppmd_path_builder_destroy.
168 ppmd_path_builder_destroy
172 This destroys a ppmd_path_builder object created with
173 ppmd_path_builder_create (i.e. frees the memory).
174 Synopsis
176 void
178 ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
179 ppmd_pathbuilder_setLegArray
182 With this function you supply the array of legs that the path builder
183 will fill. The array has a fixed size, so you must know in advance how
184 long the path you build might be.
185 Example
187 ppmd_pathleg legs[4];
189 ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
191 Synopsis
193 void
195 ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
196 ppmd_pathleg * legs,
197 unsigned int legCount);
198 Description
200 pathBuilderP is the handle of the path builder object.
202 legs is the array you are supplying for the object to fill in. This is
204 just space; no value the array has upon invocation is meaningful.
205 legCount is the number of elements of space exist in legs. I.e. this
207 is the maximum number of legs the builder can put in the array. Any
208 attempt to put more legs than this in the array fails.
209 This fails if the leg array is already set up, which could be because
211 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
212 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
213 ppmd_pathbuilder_preallocLegArray
216 This causes the object to allocate some space for the array of path
217 legs the path builder will create. If it needs more space, it will
218 reallocate. In fact, you need not call this at all, because the path
219 builder will allocate space the first time it needs it.
220 Synopsis
222 void
224 ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
225 unsigned int legCount);
226 Description
228 pathBuilderP is the handle of the path builder object.
230 legCount is how many legs' worth of space to allocate.
232 This fails if the leg array is already set up, which could be because
234 you previously called ppmd_pathbuilder_setLegArray, ppmd_path‐
235 builder_preallocLegArray, or ppmd_pathbuilder_addLineLeg.
236 ppmd_pathbuilder_setBegPoint
240 This sets the beginning point for the path. Note that to use the path
241 for filling, you must also make this the point at which the last leg of
242 the path ends.
243 Synopsis
245 void
247 ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
248 ppmd_piont begPoint);
249 Description
251 pathBuilderP is the handle of the path builder object.
253 begPoint is the beginning point of the path.
255 ppmd_pathbuilder_addLineLeg
259 This adds a line segment leg to the path.
260 Synopsis
262 void
264 ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
265 ppmd_pathleg leg);
266 Description
268 pathBuilderP is the handle of the path builder object.
270 leg is the leg to add.
272 The leg begins wherever the end of the path currently is (i.e. where
274 the most recently added leg ends, or the beginning point if you have
275 not added any paths yet).
276 ppmd_pathbuilder_pathP
279 This is a pointer to the path that the path builder has built.
280 Synopsis
282 void
284 ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
285 Description
287 pathBuilderP is the handle of the path builder object.
289 The data structure belongs to the path builder, so you must not use it
291 after you have destroyed the ppmd_pathbuilder object.
292 The pointer is valid only until you call the next path builder method
294 other than ppmd_pathbuilder_pathP. You normally don't get the pointer
295 until you are done building the path.
296
300 The ppmd_text and ppmd_text_box functions use fonts. You control the
301 fonts using functions described in this section. There is one font
302 that comes with Netpbm, called "standard". It is built into the func‐
303 tion library and is the default font. You can create additional fonts
304 and use them instead.
305 In a program that uses Netpbm drawing facilities, there is a "current
307 font." all drawing of text uses the current font. When the program
308 starts, the current font is "standard"; you can change it after that by
309 calling the ppmd_set_font function.
310 Other than a built-in font, a font lives in file in a format special to
312 Netpbm called Ppmdfont. The file typically has a name that ends in
313 ".ppmdfont".
314 Use the ppmddumpfont program to dump the contents of a Ppmdfont file in
316 human readable format.
317 Use the ppmdmkfont program to generate the "standard" font as a Ppmd‐
319 font file. You don't normally need to do this, because "standard" is
320 built into libnetpbm.
321 Use the ppmdcfont program to turn a Ppmdfont file into a C source file
323 that you can compile into a program as a built-in font. Though we
324 don't give full instructions here on how to do that, libnetpbm's built-
325 in "standard" font is a good example. In Netpbm source code, you will
326 find the C source file standardppmdfont.c, which was generated from the
327 file standard.ppmdfont by ppmdcfont. You simply use a pointer to the
328 structure that the C file defines as a font handle, just like one you
329 would get from ppmd_read_font.
330
334 The font file starts with the characters "ppmdfont" (without the quota‐
335 tion marks) in ASCII.
336 The rest of the format is not yet documented, but it generally
338 describes, for each code point, a sequence of straight line plotting
339 commands to form the glyph for the indicated character. I.e. it is a
340 vector, not raster, font.
341
345 These functions are declared in the header file ppmdfont.h.
346 ppmd_read_font
349 This function associates a Ppmdfont file, which you identify by naming
350 the Ppmdfont file, with a handle that you can use to identify the font
351 to other functions. Technically, this function reads the font into
352 memory.
353 ppmd_free_font
356 This function releases the handle that you get from ppmd_read_font. It
357 frees resources associated with it; you can't use the handle after
358 this.
359 ppmd_get_font
362 This function returns the handle of the currently selected font.
363 ppmd_set_font
366 This function sets the currently selected font. You identify the font
367 to which to set it with a handle such as you get from ppmd_read_font or
368 ppmd_get_font.
369
371 This manual page was generated by the Netpbm tool 'makeman' from HTML
372 source. The master documentation is at
373 http://netpbm.sourceforge.net/doc/libnetpbm_draw.html
375netpbm documentation FebruaLriybn2e0t1p7bm PPM Drawing Function Manual(3)