gSPVertex [Macro]

Function

gSPVertex

Loads vertices

Syntax

#include <ultra64.h>        /* gbi.h */
gSPVertex(Gfx *gdl, Vtx *v, u32 n, u32 v0)
gsSPVertex(         Vtx *v, u32 n, u32 v0)

Arguments

gdl

the display list pointer.

v

the segment address of vertex list.

n

the number of vertices (1~32)

Note: For the F3DEX2 microcode group (F3DEX2, F3DLX2, F3DLP2, and L3DEX2), the values are as follow:

F3DEX2 F3DEX2.NoN F3DLX2 F3DLX2.NoN L3DEX2	1~32
F3DEX2.Rej F3DLX2.Rej	1~64

v0

Starting index in vertex buffer where vertices are to be loaded

F3DEX F3DEX.NoN F3DLX F3DLX.NoN L3DEX	0~31
F3DLX.Rej	0~63
F3DLP.Rej	0~79

Note: For the F3DEX2 microcode group (F3DEX2, F3DLX2, F3DLP2, and L3DEX2), the values are as follow:

F3DEX2 F3DEX2.NoN F3DLX2 F3DLX2.NoN L3DEX2	0~31
F3DEX2.Rej F3DLX2.Rej	0~63

Description

Loads into the RSP vertex buffer the vertices that will be used by the gSP1Triangle commands that generates polygons.

The following table shows the vertex buffer size and the values of the n and v0 arguments used in each microcode. Since no more than 32 vertices can be loaded at one time, you must divide up the job and use this macro two or more times in order to load more than this number of vertices.

(*)To load 33 or more vertices, use gSPVertex more than once.

Accompanying the change from F3DEX to F3DEX2, the vertex buffer size and values of the n and v0 arguments were changed as follows:

Note: Some microcode was added and deleted accompanying the change. For details, please refer to the "3D Graphics" in the Microcode manual.

A vertex has either color or a normal (for shading). Therefore, which Vtx structure element to use (v or n) depends on whether color or normal is being used for the vertex. For details, please see Section 11.4, "Vertex State" in the N64 Online Programming Manual.

Note

The coordinates of the normal range from -1.0 to 1.0. In other words, -128 must be specified for the -1.0 value, and 128 must be specified for the 1.0 value. However, since the precision is signed 8-bit, the maximum positive value is actually 127, so the 1.0 value cannot be represented exactly. Thus, 0.992 is the maximum positive value.

Since the RSP geometry transformation engine uses a vertex list (triangle list architecture), it is extremely powerful and exhibits its maximum performance when processing a simple, single triangle. In the N64, triangles are generated by connecting dots after the vertex buffer has been transformed, and performance usually is increased by reusing vertices that have already been transformed for each triangle (these vertices are not re-transformed). Therefore, performance can be increased more by raising the polygon-to-vertex ratio (number of triangles/number of vertices) than by performing triangle stripping (decreasing the number of triangles).

For the actual transformation processing, the maximum amount of vectorization is performed by the RSP geometry engine.

Comment

The vertex coordinates x, y, z are transformed by the 4x4 projection matrix and the model view matrix. The texture coordinates s, t are transformed using the scale defined by gSPTexture.

When lighting is on, one can conceptually think of shading being performed according to the lighting calculation after the vertex normal has been transformed by the rotation component of the current model view matrix (not the projection matrix), even if the calculation is actually completed using a different method. The lighting calculation is only executed when the appropriate state is set when the vertices are loaded.

The vertices within the buffer are not transformed again even when a new matrix is loaded. This optimization can be used for special effects. For example, geometry can be easily created from changing points using different matrices, such as for a figure's joints.

* The Vtx structure is as follows:

typedef struct {
	short		ob[3];	/* x, y, z (signed 16-bit integer) */
	unsigned short	flag;	/* Currently has no meaning */
	short		tc[2];	/* Texture coordinates (s10.5) */
	unsigned char	cn[4];	/* Color & alpha (0~255, unsigned 8-bit) */
} Vtx_t;
typedef struct {
	short		ob[3];	/* x, y, z  (signed 16-bit integer) */
	unsigned short	flag; 	/* Currently has no meaning */
	short		tc[2];	/* Texture coordinates (s10.5) */
	signed char	n[3];	/* Normal (-128~127, signed 8-bit) */
	unsigned char	a;	/* Alpha (0~255, unsigned 8-bit) */
} Vtx_tn;
typedef union {
	Vtx_t		v;	/* Color */
	Vtx_tn		n;	/* Normal */
	long long int	force_structure_alignment; 
} Vtx;

Example

To load the vertex buffer entries 2, 3, and 4, you would specify the following:

gSPVertex(glistp++, v, 3, 2);

See Also

gSP1Triangle

Revision History

02/01/99 Entirely revised.