man > pamtris(1)

Che Dong

Pamtris User Manual(1) General Commands Manual Pamtris User Manual(1)

NAME
pamtris - triangle rasterizer featuring perspective-correct interpolation of generic vertex
attributes and depth buffering

SYNOPSIS
pamtris

-width=width

-height=height

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

[ -maxval=maxval ]

All options can be abbreviated to their shortest unique prefix. You may use two hyphens in‐
stead of one to designate an option. You may use either white space or an equals sign be‐
tween an option name and its value.

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 out‐
puts its results as a (potentially multi-image) PAM stream on Standard Output.

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

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 us‐
age, 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 tu‐
ple 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.

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.

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 incom‐
ing 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 &#8804; i < num_attribs, of the tuple in the corresponding po‐
sition 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.

The frame buffer is initially set so that all samples in every tuple of the image buffer con‐
tain 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 in‐
terpretation ascribed to them (except for the last image plane, which is deliberately sup‐
posed to represent tuple opacity information); one may ascribe any suitable meaning to them,
such as that of colors, texture coordinates, surface normals, light interaction characteris‐
tics, texture influence coefficients for multi-texturing, etc.

EXAMPLES
Fan Mode
The following command generates the image from the fan mode example at the top of the ]8;;#description\DE‐
SCRIPTION]8;;\ 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.

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 ]8;;#antialias\anti-aliased]8;;\ 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
In addition to the options common to all programs based on libnetpbm (most notably -quiet,
see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pamtris recognizes the following command line options:

-width=width
Sets the width of the internal frame buffer and, by extension, of the output PAM im‐
ages, given in number of columns. This must be an integer in the closed range [1,
8192].

This option is mandatory.

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

This option is mandatory.

-num_attribs=attributes_per_vertex
This is the number of attributes per vertex. The depth of the output PAM images equals
this value plus one (to accommodate the alpha plane). The argument must be an integer
in the closed range [1, 20].