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       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

Basic Functions

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

Drawprocs

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

Path Filling Function

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

Path Builder

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

Fonts

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

Font File Format

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

Font Control Functions

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

DOCUMENT SOURCE

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)
Impressum