pamtris - Man Page

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 instead of one to designate an option. You may use either white space or an equals sign between 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 outputs 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 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.

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 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.

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.

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.

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

In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options ), pamtris recognizes the following command line options:

-width=width

Sets the width of the internal frame buffer and, by extension, of the output PAM images, 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 accomodate the alpha plane). The argument must be an integer in the closed range [1, 20].