.TH gSPModifyVertex 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPModifyVertex, gsSPModifyVertex
\- Modify a vertex after it is loaded into the RSP.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gSPModifyVertex(Gfx *gdl, unsigned int vtx, unsigned int where, int val)

gsSPModifyVertex(unsigned int vtx, unsigned int where, int val)

gsSPNearClip(nc)
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I vtx
Which of the RSP's vertices (0-15) to modify.
.TP
.I where
What part of the vertex to modify.  One of:
.PD 0
.RS 13
G_MWO_POINT_RGBA
.PP
G_MWO_POINT_ST
.PP
G_MWO_POINT_XYSCREEN
.PP
G_MWO_POINT_ZSCREEN
.PD 1
.RE

.TP
.I val
New value for that part of the vertex (a 32 bit integer number).

.SH DESCRIPTION
This is an advanced command.  A good understanding of how
vertices work in the RSP microcode is suggested before using
this command (see
.I gSPVertex (3P)).
.PP
This command allows you to modify certain sections of a 
vertex after it has been sent to the RSP (with the
.I gSPVertex (3P)
command).  This is useful for vertices which are shared between 
2 or more triangles, but which must have different properties
when associated with one triangle than when associated with a
different triangle.  For example two adjacent triangles which
both need smooth shaded color, but one is smooth shaded red-to-yellow
and the other is smooth shaded green-to-cyan.  In this case the vertex
which is shared by both triangles is sent (using the
.I gSPVertex (3P))
command with red/yellow color; the first triangle is drawn; the
.I gSPModifyVertex (3P)
command is used to change the color to green/cyan;  and the second
triangle is drawn.  The primary use of the 
.I gSPModifyVertex (3P)
command is for modifying the texture coordinate of a vertex so
that a vertex which is shared by 2 triangles with different textures
and different texture coordinate spaces can contain the texture
coordinate for the first texture, and then be modified to contain
the texture coordinate for the second texture.
.PP
The 
.I gSPModifyVertex (3P)
command is faster than sending a new Vertex command with a different but
similar vertex because no transformations or lighting are done to
the vertex when the 
.I gSPModifyVertex (3P)
command is used.
.PP
The where parameter specifies which part of the vertex is to be modified:
.PD 0
.RS 3
.TP 4
G_MWO_POINT_RGBA
change the color of the vertex.  The
.I val
parameter is interpreted as 4 bytes: red (high byte), green, blue, and
alpha (low byte).
.PP
.TP 4
G_MWO_POINT_ST
change the S and T values (texture coordinates of the vertex).  The
high 16 bits of 
.I val
is the S coordinate, and the low 16 bits are the T coordinate.
Each coordinate is an S10.5 number.
.PP
.TP 4
G_MWO_POINT_XYSCREEN
change the screen coordinates of the vertex.  The high 16 bits of 
.I val
are the X coordinate and the low 16 bits are the Y coordinate.
Both coordinates are S13.2 numbers with 0,0 being the upper left of the
screen, positive X going right, and positive Y going down.
.PP
.TP 4
G_MWO_POINT_ZSCREEN
change the screen Z coordinate of the vertex.  The entire 32 bit
.I val
is taken as the new screen Z value.  It is a 16.16 number in the 
range 0x00000000 to 0x03ff0000.
.PD 1
.RE

.SH NOTE
Lighting is not performed after a
.I gSPModifyVertex (3P)
command, so modifying the color of the vertex with G_MWO_POINT_RGBA
is just that - modifying the actual color which will be output, and not
a modification of normal values. This means it cannot be used
to update vertex normals for lighting.
.PP
The S and T coordinates supplied in the
.I gSPModifyVertex (3P)
command are never multiplied by the texture scale (from the
.I gSPTexture (3P)
command), so they must be prescaled by you before being sent.  For
example if you want to use a texture scale of 1/2 (0x8000) then 
the S and T values you send with the 
.I gSPModifyVertex (3P)
command should be half the value of the equivalent values used with the
.I gSPVertex (3P)
command.

.SH EXAMPLE
To share a vertex between 2 triangles with different textures and
texture coordinates on the 2 triangles:
.PD 0
.RS 5

/* load the vertices with gSPVertex */
.PP
gSPVertex(...);

/* load the texture for triangle 1 */
.PP
gDPLoadTextureBlock(...);

/* draw triangle 1 which uses vertex #3 */
.PP
gSP1Triangle(glistp++, 1,2,3,0);

/* make vertex #3 have values S=3.0  T=2.5 */
.PP
gSPModifyVertex(glistp++, 3, G_MWO_POINT_ST, 0x00600050);

/* load the texture for triangle 2 */
.PP
gDPLoadTextureBlock(...);

/* draw triangle 2 which also uses vertex #3 */
.PP
gSP1Triangle(glistp++, 1,2,3,0);
.PD 1
.RE

.SH SEE ALSO
.IR gSPVertex (3P),
.IR gSPTexture (3P),
.IR gSP1Triangle (3P),