.TH gSPVertex 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPVertex, gsSPVertex
\- load vertices into the on chip vertex cache.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

typedef struct {
	short		ob[3];	/* x, y, z */
	unsigned short	flag;
	short		tc[2];	/* texture coord */
	unsigned char	cn[4];	/* color & alpha */
} Vtx_t;

typedef struct {
	short		ob[3];	/* x, y, z */
	unsigned short	flag;
	short		tc[2];	/* texture coord */
	signed char	n[3];	/* normal */
	unsigned char	a;   	/* alpha  */
} Vtx_tn;

typedef union {
    Vtx_t 		v;	/* Use this one for colors  */
    Vtx_tn		n;	/* Use this one for normals */
    long long int	force_structure_alignment;
} Vtx;

gSPVertex(Gfx *gdl, Vtx *v, unsigned int n, unsigned int v0)

gsSPVertex(Vtx *v, unsigned int n, unsigned int v0)

\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I v
vertex list pointer (segmented address).
.TP
.I n
number of vertices (1-16).
.TP
.I v0
load vertices starting at index v0 (0-15) in the vertex buffer.
.SH DESCRIPTION
This command loads an internal vertex buffer in the RSP with
points that are used by
.IR gSP1Triangle (3P),
commands to generate polygons.
This vertex cache can holds up to 16 vertices,
and the vertex loading can begin at any entry (index) within the cache. 
.PP
The vertex coordinates (x,y,z) are encoded in signed 2's complement 16
bit integers.
.PP
The texture coordinates (s,t) are encoded in S10.5 format.
.PP
A vertex either has a color or a normal (for shading).  These values
are 8-bit values.  The colors and alphas are treated as 8-bit unsigned
values (0-255), but the normals are treated as 8-bit signed values
(-128 to 127).  Thus, the appropriate member of the union to use (.v. or .n.)
depends on whether you are using colors or normals.
Normal coordinates range from -1.0 to 1.0; A value of -1.0 is represented
as -128, and a value of 1.0 should be represented as 128, but since the
maximum positive value of a signed byte is 127, a value of 1.0 can't be
exactly represented.  Thus, 0.992 is the maximum representable positive
value -- good enough for this purpose.
.PP
The
.I flag
value of the 
.I Vtx
structure currently has no meaning.
.PP
(x,y,z) are transformed using the current 4x4 projection and modelview
matrices.  (s,t) are tranformed using the scale defined by
.IR gSPTexture (3P).
.PP
When lighting is enabled you can conceptually think
of the vertex normal being transformed by the rotation component of the
modelview matrix (but NOT the projection matrix) before the lighting
computation, although in fact the computation is done in a different manner.
.SH EXAMPLE
To load vertex cache entry 2,3,4:
.Ex
gSPVertex(glistp++, v, 3, 2);
.Ee
.SH NOTE
Since the RSP geometry tranformation engine uses a vertex list,
triangle list architecture, it is quite powerful.  A simple one
triangle command retains maximum performance.  Triangle strips do not
increase performance on this machine because strips typically gain
their performance by not transforming the previous 2 vertices of every
triangle.  The RSP can transform a block of 16 vertices and then connect the
dots to build triangles.  We can actually get a higher polygon/vertex
ratio than triangle strips easily.  Therefore, you want to find the
"cloud" of vertices that can give you the most triangles to increase the
tranformation speed.
.PP
Actual transformation is heavily vectorized in the RSP geometry
engine.
.PP
Lighting calculations are performed at vertex load time, only if
the appropriate state is set.
.PP
Vertices in the buffer are not re-transformed when a new matrix
is loaded. This optimization may be exploited for 'special effects'.
It would be trivial, for example, to construct geometry out of
points which are transformed by different matrices, such as the
joints of an articulated figure.
.SH SEE ALSO
.IR gSP1Triangle (3P),  
.IR gSPLine3D (3P),
.IR gSPTexture (3P)