1Libnetpbm PPM Drawing FunctiLoinbrMaarnyuaFlu(n3cL)tiibonnestpMbamnuPaPlM Drawing Function Manual(3)
2
3
4
5       Table Of Contents ⟨#toc⟩
6

NAME

8       libnetpbm_draw \- Libnetpbm PPM Drawing Function Manual
9

DESCRIPTION

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
20

Basic Functions

22       The functions are all declared in the ppmdraw.h header file.
23
24
25   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

Drawprocs

36       Drawprocs  are functions that tell how to draw a point.  You pass draw‐
37       procs to drawing functions that require them.
38
39       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
44
45   ppmd_point_drawproc
46       This simply fills in a single pixel.  This is usually what you want.
47
48
49
50   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
55
56   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
60
61

Path Filling Function

63   ppmd_fill_path
64       Synopsis
65
66       void
67       ppmd_fill_path(pixel **      pixels,
68                      int           cols,
69                      int           rows,
70                      pixval        maxval,
71                      ppmd_path *   pathP,
72                      pixel         color);
73
74       Description
75
76       This fills a closed path.
77
78       pixels, cols, rows, and maxval describe the canvas on which to draw.
79
80       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
87       color  is  the fill color.  ppmd_fill_path makes every pixel within the
88       closed path that color.
89
90       ppmd_fill is more general, but harder to use.  With that, you can  fill
91       with a pattern.
92
93       This function was new in Netpbm 10.34 (June 2006).
94
95
96   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
101       This function was new in Netbm 10.78 (March 2017).
102
103
104

Path Builder

106       The  functions  in this section are for building a path (ppmd_path) for
107       use with ppmd_fill_path.
108
109       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
113       Here is an example that generates a filled rectangle:
114
115           pixels = ppm_allocarray(100, 100);
116
117           unsigned int row;
118
119           /* 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
126           /* Create a rectangular path */
127           ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
128
129           ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
130
131           ppmd_pathbuilder_addLineLeg(pathBuilderP,
132                                       ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
133
134           ppmd_pathbuilder_addLineLeg(pathBuilderP,
135                                       ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
136
137           ppmd_pathbuilder_addLineLeg(pathBuilderP,
138                                       ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
139
140           ppmd_pathbuilder_addLineLeg(pathBuilderP,
141                                       ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
142
143           /* 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
148           /* Destroy the path */
149           ppmd_pathbuilder_destroy(pathBuilderP);
150
151       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
156       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
160       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
163
164   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
169
170
171   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
175       Synopsis
176
177           void
178           ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
179
180
181   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
186       Example
187
188           ppmd_pathleg legs[4];
189
190           ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
191
192       Synopsis
193
194           void
195           ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
196                                        ppmd_pathleg *     legs,
197                                        unsigned int       legCount);
198
199       Description
200
201       pathBuilderP is the handle of the path builder object.
202
203       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
206       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
210       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
214
215   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
221       Synopsis
222
223           void
224           ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
225                                             unsigned int       legCount);
226
227       Description
228
229       pathBuilderP is the handle of the path builder object.
230
231       legCount is how many legs' worth of space to allocate.
232
233       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
237
238
239   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
244       Synopsis
245
246           void
247           ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
248                                        ppmd_piont         begPoint);
249
250       Description
251
252       pathBuilderP is the handle of the path builder object.
253
254       begPoint is the beginning point of the path.
255
256
257
258   ppmd_pathbuilder_addLineLeg
259       This adds a line segment leg to the path.
260
261       Synopsis
262
263           void
264           ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
265                                       ppmd_pathleg       leg);
266
267       Description
268
269       pathBuilderP is the handle of the path builder object.
270
271       leg is the leg to add.
272
273       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
277
278   ppmd_pathbuilder_pathP
279       This is a pointer to the path that the path builder has built.
280
281       Synopsis
282
283           void
284           ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
285
286       Description
287
288       pathBuilderP is the handle of the path builder object.
289
290       The  data structure belongs to the path builder, so you must not use it
291       after you have destroyed the ppmd_pathbuilder object.
292
293       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
297
298

Fonts

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
306       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
311       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
315       Use the ppmddumpfont program to dump the contents of a Ppmdfont file in
316       human readable format.
317
318       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
322       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
331
332

Font File Format

334       The font file starts with the characters "ppmdfont" (without the quota‐
335       tion marks) in ASCII.
336
337       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
342
343

Font Control Functions

345       These functions are declared in the header file ppmdfont.h.
346
347
348   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
354
355   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
360
361   ppmd_get_font
362       This function returns the handle of the currently selected font.
363
364
365   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

DOCUMENT SOURCE

371       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
372       source.  The master documentation is at
373
374              http://netpbm.sourceforge.net/doc/libnetpbm_draw.html
375
376netpbm documentation             FebruaLriybn2e0t1p7bm PPM Drawing Function Manual(3)
Impressum