GXPosition

C Specification

#include <revolution/gx.h>

void GXPosition3f32( f32 x, f32 y, f32 z );
void GXPosition3u16( u16 x, u16 y, u16 z );
void GXPosition3s16( s16 x, s16 y, s16 z );
void GXPosition3u8 ( u8  x, u8  y, u8  z );
void GXPosition3s8 ( s8  x, s8  y, s8  z );

void GXPosition2f32( f32 x, f32 y );
void GXPosition2u16( u16 x, u16 y );
void GXPosition2s16( s16 x, s16 y );
void GXPosition2u8 ( u8  x, u8  y );
void GXPosition2s8 ( s8  x, s8  y );

void GXPosition1x16( u16 index );
void GXPosition1x8 ( u8  index );

Arguments

Will depend on function used.

Return Values

None.

Description

These functions are used to specify position data for a vertex. It can only be called between GXBegin and GXEnd. Function names take the following format:

GXPosition[n][t]

The function name parameter n is a number from 1 through 3 and describes the number of function arguments. The function name parameter t describes the type of each argument to the function and can be one of the following values: s8, u8, s16, u16, f32, x8, or x16. The type letter indicates signed (s), unsigned (u), floating point (f), and index (x) data types. The subsequent number indicates the data's size in bits, For example, u8 indicates an unsigned 8-bit quantity. For example, GXPosition3f32 expects three floating point arguments.

The selected function must correspond to the current vertex descriptor and the vertex attribute format specified in the GXBegin function. The current vertex descriptor is set using the GXSetVtxDesc function. The vertex attribute format is set using GXSetVtxAttrFmt.

The order in which vertex functions must be called is specified by the GXSetVtxDesc function. Each vertex must send attributes (positions, colors, normals, etc.) in the specified order to guarantee proper interpretation by the graphics hardware.

When an attribute is indexed (i.e., its type, set by GXSetVtxDesc, is GX_INDEX8 or GX_INDEX16), the vertex function will specify an index to the data, not the data itself. The location of the array that will be indexed is described using GXSetArray. When an attribute is direct (i.e., its type, set by GXSetVtxDesc, is GX_DIRECT), the vertex function sends the data. No vertex function should be called for an attribute which is disabled (i.e., its type, set by GXSetVtxDesc, is GX_NONE). However, every vertex must at least enable GX_VA_POS.

The GXPosition[n][t] functions are implemented as inline functions in the non-debug version of the GX library for optimal performance. The GXNormal[n][t] functions are implemented as functions in the debug version of the library so it can verify the correct order of vertex function calls between GXBegin and GXEnd (a common source of errors).

Revision History