.TH gSPLine3D 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPLine3D, gsSPLine3D
gSPLineW3D, gsSPLineW3D
\- single line command
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gSPLine3D(Gfx *gdl, int v0, int v1, int flag)

gsSPLine3D(int v0, int v1, int flag)

gSPLineW3D(Gfx *gdl, int v0, int v1, int wd, int flag)

gsSPLineW3D(int v0, int v1, int wd, int flag)
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I v0, v1
vertex cache indices.
.TP
.I wd
line width in half-pixel units.
.TP
.I flag
line flat shading index.
.SH DESCRIPTION
This command generates one line,
using the vertices v0, v1 in the internal vertex buffer loaded by
.IR gSPVertex (3P).
.PP
The
.I wd
parameter is the width in half-pixel units. It ranges from 0 to
255. This width is added to 1.5 to generate the final line
width. The minimum line thickness of 0 maps to 1.5, 1 maps to 2.0,
2 maps to 2.5, etc.
.PP
The
.I flag
should be either 0, or 1 to identify which of the two vertices
should be used as the color of the line (for flat shading).
.PP
The command only works if the line microcode is loaded.
.SH NOTE
When the line microcode is loaded, the 
.B gSPTriangle1 (3P)
does not function, it is interpreted as a no-op. Likewise,
parts of the geometry state,
.B gSPSetGeometryMode (3P)
are not useful, 
.B G_CULL_FRONT, G_CULL_BACK, 
and
.B G_CULL_BOTH.

Only a few of the rdp render modes are valid for lines. The 
most commonly used ones would be \f3RM_AA_XLU_LINE\f1 or 
\f3RM_AA_ZB_XLU_LINE\f1.
Consult gbi.h for more line related render modes. 

When using
\f3RM_AA_ZB_XLU_LINE\f1, the ZBuffer is read but not written into, thus
lines should be drawn after polygons in order for proper ZBuffering
to occur. Lines will not self-occlude.

The line microcode modifies the RDP scissoring coordinates, thus they
will need to be reset to desired values by subsequent display lists.

Since the lines are rendered as trapezoids, "end cap" problems are
visible when drawing thick lines.

.SH SEE ALSO
.IR gSPVertex (3P)