Provided by: libnetpbm-dev_11.05.02-1.1build1_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
netpbm documentation April 2018 Libnetpbm PPM Drawing Function Manual(3)