GXNormal

C Specification

#include <revolution/gx.h>

void GXNormal3f32( f32 x, f32 y, f32 z );
void GXNormal3s16( s16 x, s16 y, s16 z );
void GXNormal3s8 ( s8  x, s8  y, s8  z );

void GXNormal1x16( u16 index );
void GXNormal1x8 ( u8  index );

Arguments

Will depend on the function being called.

Return Values

None.

Description

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

GXNormal[n][t]

The function name parameter n is one of {1, 3} and describes the number of arguments to the function. The function name parameter t is one of {s8, s16, f32, x8, x16} and describes the type of each argument to the function. The type name indicates signed (s), floating point (f), and index (x) data types. The number after the type indicates the size in bits. E.g., s8 indicates a signed 8-bit quantity. Consequently, GXNormal3f32 takes 3 floating-point arguments.

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

There are two types for normals; GX_VA_NRM and GX_VA_NBT. The attribute GX_VA_NRM is a 3 element normal (i.e. one normalized vector). The attribute GX_VA_NBT specifies instead 3 normalized vectors (each with 3 components): normal, binormal and tangent. These three vectors are usually orthogonal and are used for bump mapping and other special rendering techniques. To specify directly referenced data for a GX_VA_NBT attribute, simply call the appropriate GXNormal[n][t] function three times. For example:

GXBegin(GX_TRIANGLES, GX_VTXFMT0, n); GXPosition3f32 ( px, py, pz ); GXNormal3f32 ( nx, ny, nz ); GXNormal3f32 ( bx, by, bz ); GXNormal3f32 ( tx, ty, tz ); // ... GXEnd();

For GX_VA_NBT, indexed data can be divided and specified for each normal. Furthermore, each of the three normals that comprise the NBT has an implicit offset. For divided indices, the attribute address is calculated as follows:

The application specifies separated NBT indices by specifying a component count of GX_NRM_NBT3 in GXSetVtxAttrFmt. When matched with a vertex descriptor that specifies indexed normals, this combination specifies that three separate indices will be provided instead of just one.

There are two ways to set up a normal table for NBT normals. One is to set up three interleaved tables. This method is straightforward, because the built-in NBT offset takes care of choosing the right value from the interleaved tables. The other method is to set up a single table (after all, a normal is a normal regardless of the name). To implement this method, you must take into account the NBT offsets and adjust the indices used in order to cancel out the offsets. In other words, it would be as follows.

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 disclosed 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 GXNormal[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