N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

## gSPVertex

Syntax

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

Arguments

- gdl is the display list pointer.

- v is the segment address of vertex list.

- n is the number of vertices (1~32)

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

  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 follows:

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

Explanation
Loads into the RSP vertex buffer the vertices that will be used by the gSP1Triangle commands to generate 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.

Microcode | Vertex Buffer Size | Range of n | Range of v0
F3DEX, F3DEX.NoN | 32 | 1~32 | 0~31
F3DLX, F3DLX.NoN | 32 | 1~32 | 0~31
F3DLX.Rej | 64 | 1~32 (*) | 0~63
F3DLP.Rej | 80 | 1~32 (*) | 0~79
L3DEX | 32 | 1~32 | 0~31

(*) 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:

Microcode | Vertex Buffer Size | Range of n | Range of v0
F3DEX2 F3DEX2.NoN | 32 | 1~32 | 0~31
F3DLX2, F3DLX2.NoN | 32 | 1~32 | 0~31
F3DEX2.Rej | 64 | 1~64 | 0~63
F3DLX2.Rej | 64 | 1~64 | 0~63
L3DEX2 | 32 | 1~32 | 0~31

Note: Some microcode was added and deleted accompanying the change. For details, please refer to Section 25.1, "3D Graphics" in the N64 Online Programming 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.

Comments
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 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
2/1/1999 Completely rewritten.

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated March 1999