PAMTRIS(1)

📦

version 11.13.03 · 7 versions

11.13.03 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
11.9.3 · opensuse-leap 16.0
10.95.00 · centos-stream 9
10.86.51 · arch rolling
11.05.02 · ubuntu noble
11.13.00 · centos-stream 10, fedora 43, fedora 44
11.01.00 · debian bookworm

, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Pamtris User Manual 💖

Okay so bestie, welcome to the General Commands Manual section, where we're talking about a lil program called pamtris and honestly? It eats. Come sit with me. 🫶

✨ NAME ✨

pamtris — a triangle rasterizer featuring perspective-correct interpolation of generic vertex attributes and depth buffering. Yeah that's a lot of words, we'll unpack all of them, don't even worry. 👑

🌈 SYNOPSIS 🌈

pamtris

-width=width

-height=height

{ -num_attribs=attributes_per_vertex [ -tupletype=tupletype ] | -rgb |
-grayscale }

[ -maxval=maxval ]

Little notes on how the options work around here, because the parser is flexible and honestly kinda iconic:

Every option can be abbreviated to its shortest unique prefix. Slay, efficiency. 💅
You may use two hyphens instead of one to designate an option. Either vibe is fine.
You may use either white space or an equals sign between an option name and its value. No cap, both work.

🌸 DESCRIPTION 🌸

This program is part of Netpbm(1). 🎀

pamtris can be used to draw a great variety of 2D and 3D graphics by composing arbitrarily complex pictures out of separate triangles, triangle strips and triangle fans. The program reads instructions written in a simple command script notation from Standard Input and outputs its results as a (potentially multi-image) PAM stream on Standard Output. Obsessed with a one-in-one-out workflow honestly. ✨

For example, the following input:

mode fan
attribs 0 128 0
vertex 0 0 1
attribs 0 0 128
vertex 200 0 1
attribs 50 20 103
vertex 190 61 1
attribs 100 40 78
vertex 161 117 1
attribs 150 60 53
vertex 117 161 1
attribs 200 80 28
vertex 61 190 1
attribs 250 100 3
vertex 0 200 1
print

produces this:

Example pamtris output for FAN mode 🦋

So the deets, bestie: the input file gives triangle data by setting the appropriate drawing mode (if necessary), and then providing a list of vertices. Each vertex is also associated with a list of up to 20 "attributes," which are integer values between 0 and a given maxval. In the most common usage, you use pamtris to draw a visual image and a vertex has three attributes, which are an RGB specification of a color. Such attribute lists may be provided on a per-vertex basis. 👛

Prior to effectively writing a PAM image to Standard Output, pamtris first rasterizes it onto an internal frame buffer, which consists of an "image buffer" and a "depth buffer."

The image buffer consists of a sequence of height rows containing a sequence of width tuples. There is one sample for each vertex attribute in every tuple plus an opacity (alpha) sample. Each tuple in the image buffer is also associated with an integer depth in the depth buffer, which determines whether subsequent drawing operations affect that particular tuple or not. This provides a way of depth-sorting graphical objects which is adequate for many purposes in 2D and 3D computer graphics.

One prominent shortcoming of such an approach to depth-sorting, however, is that it does not automatically work with objects which are intended to appear "translucent," therefore requiring more elaborate strategies to incorporate said objects into pictures generated using this technique. 💀 So like, plan accordingly.

The opacity sample is the last sample of the tuple. pamtris manipulates opacity internally and for any tuple it is always either 0 or the maxval. The program does not provide the user direct control over the alpha image plane. Sorry babes, that plane is off-limits. 🚫✨

pamtris rasterizes triangles by approximating their visible area as a collection of tuples at particular positions in the frame buffer, and to each sample of every such tuple it assigns a value which is a perspective-correct interpolation between the values of the corresponding attribute for each vertex of the triangle. Whenever a tuple within the area of the frame buffer is produced, it is written to the corresponding position in the frame buffer if and only if it passes a depth test. This test works as follows: the depth value of every incoming tuple (which is itself an interpolation between the Z-coordinates of the vertices of the corresponding triangle) is compared against the value in the corresponding position in the depth buffer. If the depth value of the incoming tuple equals or is smaller than the depth value already present in said position in the depth buffer, the following happens.

Every sample i, where 0 ≤ i < num_attribs, of the tuple in the corresponding position in the image buffer is set to equal the value of the respective sample of the incoming tuple; and the alpha sample (the last one) is updated to the maxval;
The depth value in the corresponding position in the depth buffer is updated to a depth value directly proportional to that of the incoming tuple.

Otherwise, that particular tuple effects no change at all in the frame buffer. Rude but fair. 🙈

The frame buffer is initially set so that all samples in every tuple of the image buffer contain the value 0, and all entries in the depth buffer contain the maximum permitted depth value.

The attributes' values, and therefore the samples in the output PAM images, have no fixed interpretation ascribed to them (except for the last image plane, which is deliberately supposed to represent tuple opacity information); one may ascribe any suitable meaning to them, such as that of colors, texture coordinates, surface normals, light interaction characteristics, texture influence coefficients for multi-texturing, etc. You literally get to decide, main character energy. 👑

🔥 EXAMPLES 🔥

🎀 Fan Mode 🎀

The following command generates the image from the fan mode example at the top of the DESCRIPTION section. If the file fan.tris contains that code, you could process it with:

$ pamtris -height=200 -width=200 -rgb <fan.tris >fan.pam

🧚 Strip Mode 🧚

The following is an example of strip mode:

mode strip
attribs 255 0 0   # red
vertex   0 200 1
vertex  50   0 1
attribs 0 0 0     # black
vertex 100 200 1
attribs 0 205 205 # cyan
vertex 150 0 1
attribs 0 0 255   # blue
vertex 200 200 1
vertex 250   0 1
print

Save the above code in a file named strip.tris (for instance) and process it with:

$ pamtris -height=200 -width=200 -rgb <strip.tris >strip.pam

to yield:

Example pamtris output for STRIP mode 🍓

💜 Triangle Mode 💜

The following is an example of triangle mode:

# yellow square
mode strip
attrib 155 155 0
vertex 50  50 100
vertex 50 200 100
vertex 200 50 100
vertex 200 200 100

# blue triangle
mode triangles
attrib 0 205 205
vertex 20 125 70
attrib 0 0 140
vertex 230  70 120 # Change "120" and see what happens
vertex 230 180 120 #
print

Save the above code in a file named pierce.tris (for instance) and process it with:

$ pamtris -height=200 -width=200 -rgb <pierce.tris >pierce.pam

to yield:

Example pamtris output for TRIANGLES mode ⭐

🌈 Meta-programming 🌈

The pamtris command language is much too rudimentary to be used directly for any serious drawing; you will probably want to use a general purpose programming language to generate a temporary pamtris command file. (Hand-writing all those vertices by hand? Not the vibe, ngl. 😭)

For example, the draw_polygon procedure in the C program below outputs pamtris instructions to draw a regular polygon. It does this by generating a number of vertex instructions tracing around the perimeter of the corresponding circumscribed circle. (Note: The PAM image produced by piping the output of the below program into pamtris was subsequently downscaled through pamscale -linear -xscale 0.25 -yscale 0.25 to achieve an anti-aliased effect.) 🦋

Regular Polygons

/* ----------------------- *
 * width       = 512       *
 * height      = 512       *
 * num_attribs = 3         *
 * tupletype   = RGB_ALPHA *
 * ----------------------- */

#include <math.h>
#include <stdio.h>
#include <stdlib.h>

#define PI 3.14159265358979323844

void draw_polygon
(int const center_x, int const center_y, int const radius, int const sides)
{
    printf("mode fan\n"
           "vertex %d %d 0\n", center_x, center_y);

    for(int i = 0; i <= sides; i++)
    {
        int const x = round(center_x + radius * cos(i*2.0*PI / sides));
        int const y = round(center_y - radius * sin(i*2.0*PI / sides));

        printf("vertex %d %d 0\n", x, y);
    }
}

int main(void)
{
    puts("attribs 0 185 80");       /* color: green   */
    draw_polygon(300, 210, 150, 5); /* draws pentagon */

    puts("attribs 255 15 240");     /* color: magenta */
    draw_polygon(150, 320, 100, 7); /* draws heptagon */

    puts("!");
}

🌈 OPTIONS 🌈

okay so on top of all the options that every libnetpbm-based program just has (most importantly -quiet, go peek at Common Options bestie), pamtris also takes these 💅

-width=width — sets the width of the internal frame buffer and, by extension, of the output PAM images, given in number of columns. Gotta be an integer in the closed range [1, 8192].

This option is mandatory. Like, you literally cannot run without it, it's not a vibe-optional thing. 😭

-height=height — the height of the internal frame buffer and, by extension, of the output PAM images, given in number of rows. Gotta be an integer in the closed range [1, 8192].

This option is mandatory too. Yeah. Both of them. Every single time. 🫶

-num_attribs=attributes_per_vertex — this is how many attributes each vertex has. The depth of the output PAM images equals this value plus one (that extra one is there to accommodate the alpha plane, okurrr). The argument must be an integer in the closed range [1, 20].