Ubuntu Manpage: pamtris - triangle rasterizer featuring perspective-correct interpolation of generic vertex attributes

Provided by: netpbm_11.05.02-1.1build1_amd64

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 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 &#8804; 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 accommodate the alpha plane). The argument must be an integer in the closed range [1,
20].