LIBNETPBM_DRAW(3)

okay bestie welcome to the Libnetpbm ...tion Manual(3) — aka the Library Functions Manual, section 3, drawing edition 💅

---

🎀 Table Of Contents 🎀

the whole vibe, in order:

• NAME
• DESCRIPTION
  • Basic Functions
  • Drawprocs
  • Path Filling Function
  • Path Builder
  • Fonts

---

✨ NAME ✨

libnetpbm_draw — the Libnetpbm PPM Drawing Function Manual 💖

---

🌈 DESCRIPTION 🌈

okay so this reference manual covers the functions in the libnetpbm library that draw images, using the PPM image format and the libnetpbm in-memory image formats. that's the whole brief 🦋

ngl, we actually have very little information here. fr fr — this is mainly a framework for adding documentation later, if someone ever becomes interested in this facility. 😭

✨ heads up: the Netpbm program ppmdraw is essentially a command-line interface to the functions of this library. so you can use that program's source code as an example, or just invoke that program instead of calling these functions. and the netpbm program ppmlabel is another good example of using these functions. 🫶

---

🌸 Basic Functions 🌸

all of these are declared in the ppmdraw.h header file. periodt.

• 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 the drawing functions that require them. simple as.

there are two types: ppmd_drawprocp and ppmd_drawproc. the only difference between them 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 instead. that's it, that's the tea ☕

🎀 ppmd_point_drawproc 🎀

this simply fills in a single pixel. this is usually what you want. main character behaviour honestly 👑

🎀 ppmd_fill_drawprocp 🎀

this Drawproc is useful for filling, in that it not only draws on the canvas, but also remembers where it's been — outlining an area that you can fill with ppmd_fill. it's giving "trail of breadcrumbs" 🍓

🎀 ppmd_fill_drawproc 🎀

this is the same thing as ppmd_fill_drawprocp, except that it's a ppmd_drawproc function instead of a ppmd_drawprocp. literally the same, just a different signature vibe.

---

🔥 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 — that creates multiple closed areas, and ppmd_fill_path fills every single one of them. 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. 💀 no cap, it will just end you.

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 one, 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's 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 — only through the functions in this section. iykyk, hands off the internals bestie 🙈

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. pick your fighter 💅

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. lowkey a glow-up for performance ✨

🆕 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. no takebacks 🫶

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. so it's optional, bestie — do it for the efficiency if you want 🦋

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. 👀 remember that, it matters.

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. so like, don't be clingy with it 💀

---

🎨 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. iconic, honestly 🌈

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 🎀

ok so a font file? it starts with the literal ASCII characters "ppmdfont" — no quotation marks, bestie, those are just the manpage being polite ✨

the rest of the format is not yet documented 😭 but like, the vibe of it is: for every code point, it holds a whole sequence of straight line plotting commands that draw the glyph for that character. so it's a vector font, not a raster one. no pixels here, only math 💅

---

✨ Font Control Functions ✨

these ones live in the header file ppmdfont.h 🫶

ppmd_read_font 🦋

this function associates a Ppmdfont file — which you point at by naming the Ppmdfont file — with a handle. that handle is your little friendship bracelet that lets you introduce the font to all the other functions 💖

technically speaking, this function reads the font into memory. that's the whole bit.

ppmd_free_font 🌸

this function releases the handle you got from ppmd_read_font. it frees up the resources that were hanging out with it, and after that? the handle is done. you can't use it anymore. periodt 💀

ppmd_get_font ⭐

this function returns the handle of the currently selected font. simple as that, queen 👑

ppmd_set_font 💅

this function sets the currently selected font. you tell it which font to switch to by handing it a handle — like one you got from ppmd_read_font or ppmd_get_font. glow-up for your text fr fr ✨

---

📜 DOCUMENT SOURCE 📜

this manual page was generated by the Netpbm tool 'makeman' from HTML source, iykyk. the master documentation is living its main character era over at:

http://netpbm.sourceforge.net/doc/libnetpbm_draw.html

---

and that's a wrap bestie 🎀🫶 this whole thing came to you from netpbm documentation, dated April 2018, and yes, it really does say Libnetpbm ...tion Manual(3) in the footer — the truncated title is iconic in its own way 💜 no cap, go draw something pretty 🌈