Debian Codegraph @

upstream/debian-unstable/man1/pamtris.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pamtris User Manual" 1 "15 April 2021" "netpbm documentation"
7 .PP
8 .SH NAME
9 pamtris - triangle rasterizer featuring perspective-correct
10 interpolation of generic vertex attributes and depth buffering
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpamtris\fP
16
17 \fB-width=\fP\fIwidth\fP
18
19 \fB-height=\fP\fIheight\fP
20
21 {\ \fB-num_attribs=\fP\fIattributes_per_vertex\fP
22 [\ \fB-tupletype=\fP\fItupletype\fP\ ]
23 | \fB-rgb\fP
24 | \fB-grayscale\fP\ }
25
26 [\ \fB-maxval=\fP\fImaxval\fP\ ]
27 .PP
28 All options can be abbreviated to their shortest unique prefix.
29 You may use two hyphens instead of one to designate an option. You
30 may use either white space or an equals sign between an option name
31 and its value.
32
33 .UN description
34 .SH DESCRIPTION
35 .PP
36 This program is part of
37 .BR "Netpbm" (1)\c
38 \&.
39 .PP
40 \fBpamtris\fP can be used to draw a great variety of 2D and 3D graphics by
41 composing arbitrarily complex pictures out of separate triangles, triangle
42 strips and triangle fans. The program reads instructions written in a simple
43 command script notation from Standard Input and outputs its results
44 as a (potentially multi-image) PAM stream on Standard Output.
45 .PP
46 For example, the following input
47
48 .nf
49 \f(CW
50 mode fan
51 attribs 0 128 0
52 vertex 0 0 1
53 attribs 0 0 128
54 vertex 200 0 1
55 attribs 50 20 103
56 vertex 190 61 1
57 attribs 100 40 78
58 vertex 161 117 1
59 attribs 150 60 53
60 vertex 117 161 1
61 attribs 200 80 28
62 vertex 61 190 1
63 attribs 250 100 3
64 vertex 0 200 1
65 print
66 \fP
67
68 .fi
69
70 .PP
71 produces this:
72 .PP
73 .B Example pamtris output for FAN mode
74 .IMG -C pamtris_fan.png
75
76 .PP
77 The input file gives triangle data by setting the appropriate drawing mode,
78 if necessary, and then providing a list of vertices. Each vertex is also
79 associated with a list of up to 20 "attributes," which are integer
80 values between 0 and a given maxval. In the most common usage, you use
81 \fBpamtris\fP to draw a visual image and a vertex has three attributes, which
82 are an RGB specification of a color. Such attribute lists may be provided on
83 a per-vertex basis.
84 .PP
85 Prior to effectively writing a PAM image to Standard Output, \fBpamtris\fP
86 first rasterizes it onto an internal frame buffer, which consists of an
87 "image buffer" and a "depth buffer." The image buffer consists of a sequence
88 of \fIheight\fP rows containing a sequence of \fIwidth\fP tuples. There is
89 one sample for each vertex attribute in every tuple plus an opacity (alpha)
90 sample. Each tuple in the image buffer is also associated with an integer
91 depth in the depth buffer, which determines whether subsequent drawing
92 operations affect that particular tuple or not. This provides a way of
93 depth-sorting graphical objects which is adequate for many purposes in 2D
94 and 3D computer graphics. One prominent shortcoming of such an approach
95 to depth-sorting, however, is that it does not automatically work with
96 objects which are intended to appear "translucent," therefore requiring
97 more elaborate strategies to incorporate said objects into pictures
98 generated using this technique.
99 .PP
100 The opacity sample is the last sample of the tuple. \fBpamtris\fP
101 manipulates opacity internally and for any tuple it is always either 0 or the
102 maxval. The program does not provide the user direct control over the alpha
103 image plane.
104 .PP
105 \fBpamtris\fP rasterizes triangles by approximating their visible area as
106 a collection of tuples at particular positions in the frame buffer, and to
107 each sample of every such tuple it assigns a value which is a
108 perspective-correct interpolation between the values of the corresponding
109 attribute for each vertex of the triangle. Whenever a tuple within the area
110 of the frame buffer is produced, it is written to the corresponding position
111 in the frame buffer if and only if it passes a depth test. This test works
112 as follows: the depth value of every incoming tuple (which is itself an
113 interpolation between the Z-coordinates of the vertices of the
114 corresponding triangle) is compared against the value in the corresponding
115 position in the depth buffer. If the depth value of the incoming tuple
116 equals or is smaller than the depth value already present in said position in
117 the depth buffer, the following happens.
118
119
120 .IP \(bu
121 Every sample \fIi\fP, where 0 &#8804; \fIi\fP < \fInum_attribs\fP,
122 of the tuple in the corresponding position in the image buffer is set to equal
123 the value of the respective sample of the incoming tuple; and the alpha
124 sample (the last one) is updated to the \fImaxval\fP;
125
126 .IP \(bu
127 The depth value in the corresponding position in the depth buffer is
128 updated to a depth value directly proportional to that of the incoming
129 tuple.
130
131 .PP
132 Otherwise, that particular tuple effects no change at all in the frame
133 buffer.
134 .PP
135 The frame buffer is initially set so that all samples in every tuple of the
136 image buffer contain the value 0, and all entries in the depth buffer contain
137 the maximum permitted depth value.
138 .PP
139 The attributes' values, and therefore the samples in the output
140 PAM images, have no fixed interpretation ascribed to them (except for the
141 last image plane, which is deliberately supposed to represent tuple opacity
142 information); one may ascribe any suitable meaning to them, such as that of
143 colors, texture coordinates, surface normals, light interaction
144 characteristics, texture influence coefficients for multi-texturing, etc.
145
146
147 .UN examples
148 .SH EXAMPLES
149
150 .UN examples_fan
151 .SS Fan Mode
152 .PP
153 The following command generates the image from the fan mode example at the
154 top of the
155 .UR #description
156 DESCRIPTION
157 .UE
158 \& section. If the file
159 \fBfan.tris\fP contains that code, you could process it with:
160
161 .nf
162 \f(CW
163 $ pamtris -height=200 -width=200 -rgb <fan.tris >fan.pam
164 \fP
165
166 .fi
167
168 .UN examples_strip
169 .SS Strip Mode
170 .PP
171 The following is an example of strip mode:
172
173 .nf
174 \f(CW
175 mode strip
176 attribs 255 0 0 # red
177 vertex 0 200 1
178 vertex 50 0 1
179 attribs 0 0 0 # black
180 vertex 100 200 1
181 attribs 0 205 205 # cyan
182 vertex 150 0 1
183 attribs 0 0 255 # blue
184 vertex 200 200 1
185 vertex 250 0 1
186 print
187 \fP
188
189 .fi
190 .PP
191 Save the above code in a file named \fBstrip.tris\fP (for instance)
192 and process it with:
193
194 .nf
195 \f(CW
196 $ pamtris -height=200 -width=200 -rgb <strip.tris >strip.pam
197 \fP
198
199 .fi
200
201 to yield:
202 .PP
203 .B Example pamtris output for STRIP mode
204 .IMG -C pamtris_strip.png
205
206 .UN examples_triangles
207 .SS Triangle Mode
208 .PP
209 The following is an example of triangle mode:
210
211 .nf
212 \f(CW
213 # yellow square
214 mode strip
215 attrib 155 155 0
216 vertex 50 50 100
217 vertex 50 200 100
218 vertex 200 50 100
219 vertex 200 200 100
220
221 # blue triangle
222 mode triangles
223 attrib 0 205 205
224 vertex 20 125 70
225 attrib 0 0 140
226 vertex 230 70 120 # Change "120" and see what happens
227 vertex 230 180 120 #
228 print
229 \fP
230
231 .fi
232 .PP
233 Save the above code in a file named \fBpierce.tris\fP (for instance)
234 and process it with:
235
236 .nf
237 \f(CW
238 $ pamtris -height=200 -width=200 -rgb <pierce.tris >pierce.pam
239 \fP
240
241 .fi
242
243 to yield:
244 .PP
245 .B Example pamtris output for TRIANGLES mode
246 .IMG -C pamtris_pierce.png
247
248
249 .UN pamtris_c
250 .SS Meta-programming
251 .PP
252 The \fBpamtris\fP command language is much too rudimentary to be used
253 directly for any serious drawing; you will probably want to use a general
254 purpose programming language to generate a temporary \fBpamtris\fP command
255 file.
256 .PP
257 For example, the \fBdraw_polygon\fP procedure in the C program below
258 outputs \fBpamtris\fP instructions to draw a regular polygon. It does this
259 by generating a number of \fBvertex\fP instructions tracing around the
260 perimeter of the corresponding circumscribed circle. (Note: The PAM image
261 produced by piping the output of the below program into \fBpamtris\fP was
262 subsequently downscaled through
263 \fBpamscale\ -linear\ -xscale\ 0.25\ -yscale\ 0.25\fP
264 to achieve an
265 .UR #antialias
266 anti-aliased
267 .UE
268 \& effect.)
269 .PP
270 .B Regular Polygons
271 .IMG -C pamtris_polygons.png
272
273 .nf
274 \f(CW
275 /* ----------------------- *
276 * width = 512 *
277 * height = 512 *
278 * num_attribs = 3 *
279 * tupletype = RGB_ALPHA *
280 * ----------------------- */
281
282 #include <math.h>
283 #include <stdio.h>
284 #include <stdlib.h>
285
286 #define PI 3.14159265358979323844
287
288 void draw_polygon
289 (int const center_x, int const center_y, int const radius, int const sides)
290 {
291 printf("mode fan\en"
292 "vertex %d %d 0\en", center_x, center_y);
293
294 for(int i = 0; i <= sides; i++)
295 {
296 int const x = round(center_x + radius * cos(i*2.0*PI / sides));
297 int const y = round(center_y - radius * sin(i*2.0*PI / sides));
298
299 printf("vertex %d %d 0\en", x, y);
300 }
301 }
302
303 int main(void)
304 {
305 puts("attribs 0 185 80"); /* color: green */
306 draw_polygon(300, 210, 150, 5); /* draws pentagon */
307
308 puts("attribs 255 15 240"); /* color: magenta */
309 draw_polygon(150, 320, 100, 7); /* draws heptagon */
310
311 puts("!");
312 }
313 \fP
314
315 .fi
316
317 .UN options
318 .SH OPTIONS
319 .PP
320 In addition to the options common to all programs based on libnetpbm
321 (most notably \fB-quiet\fP, see
322 .UR index.html#commonoptions
323 Common Options
324 .UE
325 \&), \fBpamtris\fP recognizes the following
326 command line options:
327
328 <dl compact="compact">
329 .TP
330 \fB-width=\fP\fIwidth\fP
331 Sets the width of the internal frame buffer and, by extension, of the
332 output PAM images, given in number of columns. This must be an integer in the
333 closed range [1, 8192].
334 .sp
335 This option is mandatory.
336
337 .TP
338 \fB-height=\fP\fIheight\fP
339 This is the height of the internal frame buffer and, by extension, of the
340 output PAM images, given in number of rows. This must be an integer in
341 the closed range [1, 8192].
342 .sp
343 This option is mandatory.
344
345 .TP
346 \fB-num_attribs=\fP\fIattributes_per_vertex\fP
347 This is the number of attributes per vertex. The depth of the output
348 PAM images equals this value plus one (to accommodate the alpha plane). The
349 argument must be an integer in the closed range [1, 20].
350 .sp
351 The input instruction stream may override this with a \fBreset\fP
352 command.
353 .sp
354 You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
355 and \fB-grayscale\fP.
356
357
358 .TP
359 \fB-tupletype=\fP\fItupletype\fP
360 This is the tuple type for the output PAM images. The argument is a string
361 which may be no longer than 255 characters.
362 .sp
363 The input instruction stream may override this with a \fBreset\fP
364 command.
365 .sp
366 The default is a null string.
367 .sp
368 This option cannot be specified together with \fB-rgb\fP or
369 \fB-grayscale\fP.
370
371
372
373 .TP
374 \fB-rgb\fP
375 This is a convenience option which simply serves as an alias for
376 \fB-num_attribs=\fP3 \fB-tupletype=\fPRGB_ALPHA. In other words, this option
377 is a quick way to specify that you are going to use \fBpamtris\fP to draw
378 RGB(_ALPHA) color images directly, and the three vertex attributes are the
379 red, green and blue levels of the color associated with the vertex, in that
380 order.
381 .sp
382 The input instruction stream may override this with a \fBreset\fP
383 command.
384 .sp
385 You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
386 and \fB-grayscale\fP.
387 .sp
388 This option was new in Netpbm 10.85 (December 2018).
389
390 .TP
391 \fB-grayscale\fP
392 Another convenience option, similar to \fB-rgb\fP; except this one is an
393 alias for \fB-num_attribs=\fP1 \fB-tupletype=GRAYSCALE_ALPHA\fP. The one
394 vertex attribute is the gray level associated with the vertex.
395 .sp
396 The input instruction stream may override this with a \fBreset\fP
397 command.
398 .sp
399 You must specify exactly one of \fB-num_attribs\fP, \fB-rgb\fP,
400 and \fB-grayscale\fP.
401 .sp
402 This option was new in Netpbm 10.85 (December 2018).
403
404 .TP
405 \fB-maxval=\fP\fImaxval\fP
406 Sets the maxval of the output PAM images, which is also the maximum
407 permitted value for each vertex attribute. This must be an integer in the
408 closed range [1, 65535].
409 .sp
410 The default value is 255.
411 .sp
412 The input instruction stream may override this with a
413 \fBreset\fP command.
414
415
416
417 .UN instruction_code
418 .SH INSTRUCTION CODE
419 .PP
420 The input for \fBpamtris\fP consists of a stream of text lines read from
421 Standard Input.
422 .PP
423 Empty lines or lines that contain only white space characters are called
424 blank lines and are ignored.
425 .PP
426 When a \fB#\fP occurs anywhere in a line, \fBpamtris\fP ignores it
427 along with every character after it. In other words, everything from the
428 \fB#\fP until the end of the line receives the same treatment as white
429 space.
430 .PP
431 Lines which are not blank must contain a sequence of strings, called
432 tokens, separated by white space. The first such token must be one of the
433 commands recognized by \fBpamtris\fP, and all further tokens are interpreted
434 as the arguments for that command, if it takes any. When an insufficient
435 number of arguments is provided for a command, the line is considered invalid
436 and is given the same treatment as a blank line. The same happens when an out
437 of range argument or one of a kind different of what is expected is given (for
438 example, when you give a string of letters where a numerical value is
439 expected), or when an unrecognized command/argument is found. When a number of
440 arguments greater than that required for a particular command is provided,
441 only the portion of the line up to the last required argument is considered
442 and any further tokens are ignored.
443 .PP
444 \fBpamtris\fP is case-insensitive. That is, \fBmode\fP, \fBMODE\fP,
445 \fBmODe\fP, etc. are all treated the same way.
446 .PP
447 The commands recognized by \fBpamtris\fP are:
448
449 .TP
450 \fBmode\fP
451 .TP
452 \fBattribs\fP
453 .TP
454 \fBvertex\fP
455 .TP
456 \fBprint\fP
457 .TP
458 \fBclear\fP
459 .TP
460 \fBreset\fP
461 .TP
462 \fBquit\fP
463
464 .PP
465 You may use a minimum unique abbreviation of a command name. You may use
466 an exclamation mark (\fB!\fP) in place of the \fBprint\fP command name and an
467 asterisk (\fB*\fP) in place of \fBclear\fP.
468 .PP
469 The functions of the commands are as follows.
470
471
472 .TP
473 \fBmode\fP { triangles | strip | fan }
474 .sp
475 This makes \fBpamtris\fP enter a new drawing mode. The argument is a word
476 which specifies the mode to change to. Instead of a full argument name, it is
477 permissible to provide a minimum unique abbreviation, which has the same
478 effect. The drawing mode will remain the same until the next \fBmode\fP
479 command is given.
480 .sp
481 This command also resets the current vertex list, which is
482 (re)initialized to an empty state after the command is executed. One may add
483 new vertices to this list through successive invocations of the \fBvertex\fP
484 command (see below). You do not have to worry about providing "too many"
485 vertices, since the vertex list is virtualized: \fBpamtris\fP maintains only
486 the state pertaining to three vertices at any one time. The current vertex
487 list is initially empty.
488 .sp
489 It is permissible to give \fBpamtris\fP a \fBmode\fP command which
490 instructs it to enter a drawing mode it is currently already in. One might
491 use this approach to reset the current vertex list without changing the
492 current drawing mode.
493 .sp
494 Regardless of the current drawing mode, the program immediately rasterizes
495 a new triangle into the frame buffer as soon as you provide the necessary
496 vertices for it through the current vertex list. (If you reset the vertex list
497 before giving all the vertices necessary to draw a new triangle, the program
498 effectively discards from the list any vertices that might have been pushed
499 into the vertex list up to that point without using them to draw any new
500 triangles.)
501 .sp
502 In the following descriptions of each drawing mode, triangles' and
503 vertices' indices (ordinal numbers) are 0-based.
504 .sp
505 The \fBtriangles\fP argument instructs \fBpamtris\fP to enter the
506 "TRIANGLES" drawing mode. While in this mode, a series of separate triangles
507 is constructed. Every three vertices pushed into the current vertex list
508 specify a new triangle. Formally, this means that every
509 \fIN\uth\d\fP triangle is specified by vertices 3*\fIN\fP,
510 3*\fIN\fP\ +\ 1, and 3*\fIN\fP\ +\ 2. This is the default
511 initial mode and is therefore not required to be set explicitly before
512 drawing any triangles.
513 .sp
514 The \fBstrip\fP argument instructs \fBpamtris\fP to enter the "STRIP"
515 drawing mode. While in this mode, \fBpamtris\fP constructs a "triangle
516 strip." That is, the first three vertices pushed into the current vertex
517 list specify the first triangle, and every new vertex pushed after that
518 specifies, together with the previous two, the next triangle. Formally, this
519 means that every \fIN\fP\uth\d triangle is specified by vertices
520 \fIN\fP, \fIN\fP\ +\ 1, and \fIN\fP\ +\ 2.
521 .sp
522 The \fBfan\fP argument instructs \fBpamtris\fP to enter the "FAN"
523 drawing mode. While in this mode, a so-called "triangle fan" is constructed.
524 That is, the first three vertices pushed into the current vertex list specify
525 the first triangle, and every new vertex pushed after that specifies, together
526 with the previous vertex and the first one, the next triangle. Formally, this
527 means that every \fIN\fP\uth\d triangle is specified by vertices
528 \fI0\fP, \fIN\fP\ +\ 1, and \fIN\fP\ +\ 2.
529
530
531 .TP
532
533 \fBattribs\fP \fIa<sub>0\fP \fIa<sub>1\fP
534 \fIa<sub>2\fP ... \fIa<sub>num_attribs - 1\fP
535 .sp
536 This updates the current attribute values list. This command takes as
537 arguments a sequence of \fInum_attribs\fP integers which represent the
538 values of the attributes to be associated with the next vertex. This
539 sequence of values is the just mentioned "current attribute values list."
540 .sp
541 Each \fIi\uth\d\fP argument, where 0 &#8804; \fIi\fP <
542 \fInum_attribs\fP, indicates the value to be assigned to the
543 \fIi\fP\uth\d attribute of the current attribute values list. All
544 arguments must be integer values in the closed range [0, \fImaxval\fP].
545 If a number of arguments less than the current value of \fInum_attribs\fP
546 is given, the command is considered invalid and is therefore ignored.
547 .sp
548 The current attribute values list remains unchanged until the next valid
549 \fBattribs\fP or \fBreset\fP command is given. The \fBattribs\fP command
550 allows one to change the values of each attribute individually, while the
551 \fBreset\fP command is not specifically designed for that function, but it
552 has the side effect of setting all values in the current attribute values
553 list to the \fImaxval\fP (see below).
554 .sp
555 All values in the current attribute values list are initially set to the
556 \fImaxval\fP.
557
558 <dt id="cmd_vertex">\fBvertex\fP \fIx\fP \fIy\fP \fIz\fP [\fIw\fP]
559 .sp
560 Adds a new vertex to the current vertex list (see the \fBmode\fP
561 command above), assigning the values of the arguments to its respective
562 coordinates, and the values in the current attribute values list (see the
563 \fBattribs\fP command above) to the respective entries in the
564 attribute list associated with the vertex.
565 .sp
566 \fIx\fP, \fIy\fP and \fIz\fP
567 must be integer values in the closed range [-32767, 32767].
568 \fIx\fP and \fIy\fP represent, respectively, the column and row of the
569 tuple which corresponds to the location of the vertex. Such values may
570 correspond to tuples outside the limits of the frame buffer. The origin of
571 the coordinate system is at the top-left tuple of the frame buffer. The
572 X-axis goes from left to right, and the Y-axis from top to bottom. A
573 negative value for \fIx\fP indicates a column that many tuples to the
574 left of the leftmost column of the frame buffer. Likewise, a negative
575 value for \fIy\fP indicates a row that many tuples above the uppermost
576 row of the frame buffer. Observe that those coordinates correspond
577 directly to a particular point in the coordinate system delineated
578 above, regardless of whether you are trying to draw an image which is
579 supposed to look as if viewed "in perspective" or not; \fBpamtris\fP
580 does \fInot\fP "warp" the coordinates you give in any way.
581 Therefore, if you want to draw images in perspective, you must compute
582 values for \fIx\fP and \fIy\fP already projected into \fBpamtris\fP'
583 coordinate system yourself, using an external perspective projection
584 method, prior to giving them to the program.
585 .sp
586 The \fIz\fP parameter represents the Z-coordinate of the vertex, which
587 is used to compute depth values for tuples within the areas of rasterized
588 triangles. Intuitively, smaller values for \fIz\fP mean "closer to
589 the viewer," and larger ones mean "farther away from the viewer" (but
590 remember: as said above, the \fIx\fP and \fIy\fP coordinates are not
591 warped in any way, which implies that they are not affected by \fIz\fP;
592 neither by the next parameter, for that matter).
593 .sp
594 Optionally, you may provide a \fIw\fP parameter which represents a
595 "perspective correction factor" used to properly interpolate vertex attributes
596 across the area of the corresponding triangle. This must be an integer value
597 in the closed range [1, 1048575]. If you don't provide a value for it, the
598 default value of 1 is used (hence, if you want to nullify the effects of
599 perspective correction on a triangle so the output samples are computed as if
600 just linearly interpolated, simply do not provide a value for \fIw\fP for any
601 vertex of the triangle). If, however, you intend to draw 3D geometry in
602 perspective, you must provide an appropriate value for this parameter,
603 otherwise the output images might look very wrong. \fIw\fP was new in Netpbm
604 10.85 (December 2018).
605 .sp
606 Consider the
607 .UR https://en.wikipedia.org/wiki/Viewing_frustum
608 typical model
609 .UE
610 \& of the so-called "viewing frustum" used to project vertices
611 in 3D "world space" onto a planar "image space." If we adopt the convention
612 that a "z-plane" means any plane parallel to the view-plane (a.k.a. picture
613 plane, a.k.a. near plane), the value of \fIw\fP for a vertex should then be
614 the (smallest/euclidean/orthogonal) distance in pixels between the projection
615 reference point (PRP, or "eye") and the z-plane containing the vertex. One
616 way to compute this value amounts to simply taking the dot product between
617 the 3D vector \fBr\fP and the 3D unit vector \fBn\fP, where \fBr\fP is
618 the vector which goes from the projection reference point (PRP, or "eye") to
619 the vertex, and \fBn\fP is a view-plane normal (VPN) of unit length which
620 points away from the PRP. In other words, this is equal to the length of the
621 orthogonal projection of \fBr\fP on the line "determined" by \fBn\fP.
622 .sp
623 (Note: For any two 3D vectors \fBa\fP and \fBb\fP, with respective real
624 scalar components a<sub>x, a<sub>y, a<sub>z and
625 b<sub>x, b<sub>y, b<sub>z, the dot product between \fBa\fP
626 and \fBb\fP is simply
627 a<sub>x*b<sub>x\ +\ a<sub>y*b<sub>y\ +\ a<sub>z*b<sub>z.)
628
629
630 .TP
631 \fBprint\fP
632 .sp
633 This writes a PAM image to Standard Output whose raster is a copy of the
634 current contents of the image buffer. The values of the WIDTH and HEIGHT
635 fields are the same as the width and height, respectively, of the frame
636 buffer, which were given on the command line during program invocation. The
637 MAXVAL field is equal to the current maxval; the DEPTH field is equal to
638 the current value of \fInum_attribs\fP + 1; and the TUPLTYPE field is
639 equal to the current tupletype.
640 .sp
641 This command has no effect upon the current drawing state. E. g. it does
642 not modify the current drawing mode, the current vertex list, etc.
643 .sp
644 One may issue an arbitrary number of \fBprint\fP commands at different
645 positions in the input instruction sequence to produce a multi-image PAM
646 stream.
647
648 .TP
649 \fBclear\fP [ image | depth ]
650 .sp
651 Clears the frame buffer. That is, all samples in the image buffer are once
652 again set to 0, and all entries in the depth buffer are once again set to the
653 maximum permitted depth value.
654 .sp
655 Optionally, one may provide an argument to only clear either the image
656 buffer or the depth buffer individually, while leaving the other intact. With
657 the \fBimage\fP argument, only the image buffer is cleared; with the
658 \fBdepth\fP argument, only the depth buffer is cleared. Instead of full
659 argument names, one may provide a minimum unique abbreviation, which has the
660 same effect. The single character \fBz\fP is also accepted as an alias for
661 \fBdepth\fP.
662 .sp
663 Like the \fBprint\fP command, this command has no effect upon the
664 current drawing state either.
665
666
667 .TP
668 \fBreset\fP \fImaxval\fP \fInum_attribs\fP [\fItupletype\fP]
669 .sp
670 This updates the current maxval and number of attributes per vertex
671 (num_attribs), resetting the <u>image</u> buffer with a new maxval and number
672 of samples per tuple while at it. The parameter \fImaxval\fP must be an
673 integer in the closed range [1, 65535], and \fInum_attribs\fP must be an
674 integer in the closed range [1, 20].
675 .sp
676 Optionally, after the second argument, one may provide a string to be
677 assigned to the current \fItupletype\fP. The string goes from the first
678 character after the second argument which is not white space and continues
679 until (and including) the last character before the end of the line which is
680 not white space. If a new tupletype is not provided, or the provided string
681 is longer than 255 characters, the empty string is assigned to the current
682 \fItupletype\fP.
683 .sp
684 The side effects of running this command are
685
686
687 .IP \(bu
688 The new image buffer is completely cleared once the command is executed.
689
690 .IP \(bu
691 All values in the current attribute values list are set to the new maxval.
692
693 .IP \(bu
694 The current vertex list is reset.
695
696
697 .sp
698 However, it does not touch the depth buffer: it is left the same way as it
699 was found before the command. Also the drawing mode remains the same (e. g. if
700 \fBpamtris\fP was in FAN mode, it will continue in that same mode, etc.).
701 .sp
702 If this command is given with an invalid value for \fImaxval\fP or
703 \fInum_attribs\fP, it is ignored and therefore none of the above side
704 effects apply, nor do the current maxval, num_attribs or tupletype change at
705 all.
706 .sp
707 It is permissible to give a value for \fImaxval\fP and \fInum_attribs\fP
708 equal to the current maxval and num_attribs, respectively, although the above
709 side effects will still apply even in such cases.
710 .sp
711 Since this command deals with memory allocation, it may fail to execute
712 successfully. If that happens, no lines of input will be read anymore and
713 \fBpamtris\fP will be terminated as if the \fBquit\fP command was given.
714 .TP
715 \fBquit\fP
716 .sp
717 This terminates \fBpamtris\fP. It will not read any more lines of input
718 after this command.
719
720
721
722
723 .UN tips
724 .SH TIPS
725
726 .SS Texturing
727 .PP
728 It is possible to apply so-called "textures" to images produced with
729 \fBpamtris\fP by using a pair of vertex attributes as texture
730 coordinates, then using
731 .BR "\fBpamchannel\fP" (1)\c
732 \& to
733 select the appropriate channels in the output image(s), and finally
734 processing the result through
735 .BR "\fBpamlookup\fP" (1)\c
736 \&,
737 providing the desired texture file as a "lookup table." If you are drawing
738 pictures in perspective, make sure to provide adequate values for the
739 \fIw\fP parameter to your vertex commands
740 (
741 .UR #cmd_vertex
742 see above
743 .UE
744 \&) so that the resulting samples in
745 the images produced by \fBpamtris\fP are perspective-correct. You might
746 want to consider using
747 .BR "\fBpnmtile\fP" (1)\c
748 \& to make
749 textures which are inteded to be "repeated" along triangle meshes.
750 .PP
751 The animated GIF below is an example of what can be achieved using the
752 technique described above (Earth texture from
753 .UR https://visibleearth.nasa.gov/view.php?id=73580
754 nasa.gov
755 .UE
756 \&).
757 .PP
758 .B Rotating Earth
759 .IMG -C pamtris_earth.gif
760
761 .UN antialias
762 .SS Anti-aliased edges
763 .PP
764 \fBpamtris\fP performs no anti-aliasing on triangle edges by itself.
765 However, it is possible to obtain anti-aliased images through a
766 "super-sampling" approach: draw your image(s) at a size larger than
767 the desired final size, and then, when all postprocessing is done,
768 downscale the final image(s) to the desired size. Drawing images with
769 twice the desired width and height, then downscaling them to the intended
770 size while disregarding gamma (i.e. what \fBpamscale\ -linear\fP does)
771 often produces good enough results; but the larger the ratio \fI
772 "size\ of\ original\ image"\ /\ "size\ of\ downscaled\ image"
773 \fP, the better the quality of the anti-aliasing effect.
774
775 .UN seealso
776 .SH SEE ALSO
777 .BR "pampick" (1)\c
778 \&
779 .BR "pamchannel" (1)\c
780 \&
781 .BR "pamstack" (1)\c
782 \&
783 .BR "pamlookup" (1)\c
784 \&
785 .BR "pamarith" (1)\c
786 \&
787 .BR "pamscale" (1)\c
788 \&
789 .BR "pamdepth" (1)\c
790 \&
791 .BR "pamexec" (1)\c
792 \&
793 .BR "pam" (1)\c
794 \&
795
796 .UN history
797 .SH HISTORY
798 .PP
799 \fBpamtris\fP was new in Netpbm 10.84 (September 2018).
800 .SH DOCUMENT SOURCE
801 This manual page was generated by the Netpbm tool 'makeman' from HTML
802 source. The master documentation is at
803 .IP
804 .B http://netpbm.sourceforge.net/doc/pamtris.html
805 .PP