Provided by: libnetpbm11-dev_10.97.00-2_amd64 
NAME
libnetpbm_draw \- Libnetpbm PPM Drawing Function Manual
DESCRIPTION
This reference manual covers functions in the libnetpbm library for drawing images, using
the PPM image format and the libnetpbm in-memory image formats.
We actually have very little information here; this is mainly a framework for adding
documentation later if someone becomes interested in this facility.
Note that the Netpbm program ppmdraw is essentially a command-line interface to the
functions of this library. You can use that program's source code as an example, or just
invoke that program instead of calling these functions. The netpbm program ppmlabel is
another good example of using these functions.
Basic Functions
The functions are all declared in the ppmdraw.h header file.
ppmd_setlinetype
ppmd_setlineclip
ppmd_line
ppmd_spline3
ppmd_polyspline
ppmd_circle
ppmd_filledrectangle
ppmd_fill
ppmd_text
ppmd_text_box
Drawprocs
Drawprocs are functions that tell how to draw a point. You pass drawprocs to drawing
functions that require them.
There are two types: ppmd_drawprocp and ppmd_drawproc. The only difference is that the
former takes the location at which to draw the point as an argument of point type
(ppmd_point), whereas the latter takes integer column and row arguments.
ppmd_point_drawproc
This simply fills in a single pixel. This is usually what you want.
ppmd_fill_drawprocp
This Drawproc is useful for filling, in that it not only draws on the canvas, but
remembers where it's been, outlining an area that you can fill with ppmd_fill.
ppmd_fill_drawproc
This is the same thing as ppmd_fill_drawprocp except that it is a ppmd_drawproc function
instead of ppmd_drawprocp.
Path Filling Function
ppmd_fill_path
Synopsis
void
ppmd_fill_path(pixel ** pixels,
int cols,
int rows,
pixval maxval,
ppmd_path * pathP,
pixel color);
Description
This fills a closed path.
pixels, cols, rows, and maxval describe the canvas on which to draw.
pathP identifies a closed path on that canvas. If it does not end on the same point at
which it starts, ppmd_fill_path aborts the program with a call to pm_error. The path may
cross itself, though, creating multiple closed areas, each of which ppmd_fill_path fills.
The path must fit within the cols x rows dimensions. If it does not, ppmd_fill_path
aborts the program with a call to pm_error.
color is the fill color. ppmd_fill_path makes every pixel within the closed path that
color.
ppmd_fill is more general, but harder to use. With that, you can fill with a pattern.
This function was new in Netpbm 10.34 (June 2006).
ppmd_makeLineLeg
This function returns a data structure of type ppmd_pathleg, to be used in a data
structure of type ppmd_path, to be use with function ppmd_fill_path.
This function was new in Netbm 10.78 (March 2017).
Path Builder
The functions in this section are for building a path (ppmd_path) for use with
ppmd_fill_path.
It is an object-oriented set of functions, where the object involved is of type
ppmd_path_builder. This is an opaque structure that you should not access directly, but
only through the functions in this section.
Here is an example that generates a filled rectangle:
pixels = ppm_allocarray(100, 100);
unsigned int row;
/* Initialize the canvas to all black */
for (row = 0; row < 100; ++row) {
unsigned int col;
for (col = 0; col < 100; ++col)
pixels[row][col] = ppm_blackpixel();
}
/* Create a rectangular path */
ppmd_pathbuilder * const pathBuilderP = ppmd_pathbuilder_create();
ppmd_pathbuilder_setBegPoint(pathBuilderP, ppmd_makePoint(5, 5));
ppmd_pathbuilder_addLineLeg(pathBuilderP,
ppmd_makeLineLeg(ppmd_makePoint(5, 50)));
ppmd_pathbuilder_addLineLeg(pathBuilderP,
ppmd_makeLineLeg(ppmd_makePoint(50, 50)));
ppmd_pathbuilder_addLineLeg(pathBuilderP,
ppmd_makeLineLeg(ppmd_makePoint(50, 5)));
ppmd_pathbuilder_addLineLeg(pathBuilderP,
ppmd_makeLineLeg(ppmd_makePoint(5, 5)));
/* Fill the area enclosed by that path with white */
ppmd_fill_path(pixels, 100, 100, PPM_MAXMAXVAL,
ppmd_pathbuilder_pathP(pathBuilderP),
ppm_whitepixel(PPM_MAXMAXVAL));
/* Destroy the path */
ppmd_pathbuilder_destroy(pathBuilderP);
There are two ways to manage the space in which the leg array of the ppmd_path structure
resides. Either you supply a fixed-length array and the path builder just uses it or you
have the path builder allocate the storage automatically.
If you let the path builder allocate the space automatically, you can nonetheless tell the
path builder how much space to allocate initially, to make the path building more
efficient.
This facility was new in Netpbm 10.78 (March 2017). Before that, you have to build the
ppmd_path by directly setting its members.
ppmd_path_builder
This creates a ppmd_path_builder object (i.e. allocates memory for it and initializes it).
You must ultimately destroy it with ppmd_path_builder_destroy.
ppmd_path_builder_destroy
This destroys a ppmd_path_builder object created with ppmd_path_builder_create (i.e. frees
the memory).
Synopsis
void
ppmd_pathbuilder_destroy(ppmd_pathbuilder * pathBuilderP);
ppmd_pathbuilder_setLegArray
With this function you supply the array of legs that the path builder will fill. The
array has a fixed size, so you must know in advance how long the path you build might be.
Example
ppmd_pathleg legs[4];
ppmd_pathbuilder_setLegArray(pathBuilderP, legs, 4);
Synopsis
void
ppmd_pathbuilder_setLegArray(ppmd_pathbuilder * pathBuilderP,
ppmd_pathleg * legs,
unsigned int legCount);
Description
pathBuilderP is the handle of the path builder object.
legs is the array you are supplying for the object to fill in. This is just space; no
value the array has upon invocation is meaningful.
legCount is the number of elements of space exist in legs. I.e. this is the maximum
number of legs the builder can put in the array. Any attempt to put more legs than this
in the array fails.
This fails if the leg array is already set up, which could be because you previously
called ppmd_pathbuilder_setLegArray, ppmd_pathbuilder_preallocLegArray, or
ppmd_pathbuilder_addLineLeg.
ppmd_pathbuilder_preallocLegArray
This causes the object to allocate some space for the array of path legs the path builder
will create. If it needs more space, it will reallocate. In fact, you need not call this
at all, because the path builder will allocate space the first time it needs it.
Synopsis
void
ppmd_pathbuilder_preallocLegArray(ppmd_pathbuilder * pathBuilderP,
unsigned int legCount);
Description
pathBuilderP is the handle of the path builder object.
legCount is how many legs' worth of space to allocate.
This fails if the leg array is already set up, which could be because you previously
called ppmd_pathbuilder_setLegArray, ppmd_pathbuilder_preallocLegArray, or
ppmd_pathbuilder_addLineLeg.
ppmd_pathbuilder_setBegPoint
This sets the beginning point for the path. Note that to use the path for filling, you
must also make this the point at which the last leg of the path ends.
Synopsis
void
ppmd_pathbuilder_setBegPoint(ppmd_pathbuilder * pathBuilderP,
ppmd_piont begPoint);
Description
pathBuilderP is the handle of the path builder object.
begPoint is the beginning point of the path.
ppmd_pathbuilder_addLineLeg
This adds a line segment leg to the path.
Synopsis
void
ppmd_pathbuilder_addLineLeg(ppmd_pathbuilder * pathBuilderP,
ppmd_pathleg leg);
Description
pathBuilderP is the handle of the path builder object.
leg is the leg to add.
The leg begins wherever the end of the path currently is (i.e. where the most recently
added leg ends, or the beginning point if you have not added any paths yet).
ppmd_pathbuilder_pathP
This is a pointer to the path that the path builder has built.
Synopsis
void
ppmd_pathbuilder_pathP(ppmd_pathbuilder * pathBuilderP);
Description
pathBuilderP is the handle of the path builder object.
The data structure belongs to the path builder, so you must not use it after you have
destroyed the ppmd_pathbuilder object.
The pointer is valid only until you call the next path builder method other than
ppmd_pathbuilder_pathP. You normally don't get the pointer until you are done building
the path.
Fonts
The ppmd_text and ppmd_text_box functions use fonts. You control the fonts using
functions described in this section. There is one font that comes with Netpbm, called
"standard". It is built into the function library and is the default font. You can
create additional fonts and use them instead.
In a program that uses Netpbm drawing facilities, there is a "current font." all drawing
of text uses the current font. When the program starts, the current font is "standard";
you can change it after that by calling the ppmd_set_font function.
Other than a built-in font, a font lives in file in a format special to Netpbm called
Ppmdfont. The file typically has a name that ends in ".ppmdfont".
Use the ppmddumpfont program to dump the contents of a Ppmdfont file in human readable
format.
Use the ppmdmkfont program to generate the "standard" font as a Ppmdfont file. You don't
normally need to do this, because "standard" is built into libnetpbm.
Use the ppmdcfont program to turn a Ppmdfont file into a C source file that you can
compile into a program as a built-in font. Though we don't give full instructions here on
how to do that, libnetpbm's built-in "standard" font is a good example. In Netpbm source
code, you will find the C source file standardppmdfont.c, which was generated from the
file standard.ppmdfont by ppmdcfont. You simply use a pointer to the structure that the C
file defines as a font handle, just like one you would get from ppmd_read_font.
Font File Format
The font file starts with the characters "ppmdfont" (without the quotation marks) in
ASCII.
The rest of the format is not yet documented, but it generally describes, for each code
point, a sequence of straight line plotting commands to form the glyph for the indicated
character. I.e. it is a vector, not raster, font.
Font Control Functions
These functions are declared in the header file ppmdfont.h.
ppmd_read_font
This function associates a Ppmdfont file, which you identify by naming the Ppmdfont file,
with a handle that you can use to identify the font to other functions. Technically, this
function reads the font into memory.
ppmd_free_font
This function releases the handle that you get from ppmd_read_font. It frees resources
associated with it; you can't use the handle after this.
ppmd_get_font
This function returns the handle of the currently selected font.
ppmd_set_font
This function sets the currently selected font. You identify the font to which to set it
with a handle such as you get from ppmd_read_font or ppmd_get_font.
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML source. The master
documentation is at
http://netpbm.sourceforge.net/doc/libnetpbm_draw.html