GXSetVtxDesc

C Specification

#include <revolution/gx.h>
void GXSetVtxDesc( GXAttr attr, GXAttrType type );

Arguments

attr specifies the attribute name
Specifiable attribute data must be sent in ascending order as shown below:
Attribute Ascending Vertex Order Description
GX_VA_PNMTXIDX 0 position coordinate/normal line matrix index
GX_VA_TEX0MTXIDX 1 The GX_TEXCOORD0 matrix index.
GX_VA_TEX1MTXIDX 2 The GX_TEXCOORD1 matrix index.
GX_VA_TEX2MTXIDX 3 The GX_TEXCOORD2 matrix index.
GX_VA_TEX3MTXIDX 4 The GX_TEXCOORD3 matrix index.
GX_VA_TEX4MTXIDX 5 The GX_TEXCOORD4 matrix index.
GX_VA_TEX5MTXIDX 6 The GX_TEXCOORD5 matrix index.
GX_VA_TEX6MTXIDX 7 The GX_TEXCOORD6 matrix index.
GX_VA_TEX7MTXIDX 8 The GX_TEXCOORD7 matrix index.
GX_VA_POS 9 the position coordinate
GX_VA_NRM or
GX_VA_NBT		 10 the normal or NBT (normal/binormal/tangent)
GX_VA_CLR0 11 color 0
GX_VA_CLR1 12 color 1
GX_VA_TEX0 13 texture coordinate 0
GX_VA_TEX1 14 texture coordinate 1
GX_VA_TEX2 15 texture coordinate 2
GX_VA_TEX3 16 texture coordinate 3
GX_VA_TEX4 17 texture coordinate 4
GX_VA_TEX5 18 texture coordinate 5
GX_VA_TEX6 19 texture coordinate 6
GX_VA_TEX7 20 texture coordinate 7
type specifies the method used to reference the attribute
Accepted values are:
Name Description
GX_NONE no data for this attribute
GX_DIRECT the direct reference data
GX_INDEX8 the eight-bit index reference
GX_INDEX16 the sixteen-bit index reference
Only GX_NONE and GX_DIRECT can be applied with GX_VA_PNMTXIDX and GX_VA_TEX*MTXIDX.

Return Values

None.

Description

This function sets the type of a single attribute (attr) in the current vertex descriptor. The current vertex descriptor defines which attributes are present in a vertex and how each attribute is referenced. The current vertex descriptor is used by the graphics processor (GP) to interpret the graphics command stream produced by the GX API. In particular, the current vertex descriptor is used to parse vertex data present in the command stream.

Attributes

GX_VA_POSMTXIDX

The attr argument names the attribute. The GX_VA_POSMTXIDX attribute is used to specify a matrix index (8 bits) per vertex. This index is used to index position (and normal, when lighting is used) matrices in matrix memory. Providing a matrix index per vertex allows character skinning.

GX_VA_TEX0MTXIDX-GX_VA_TEX7MTXIDX

You may also specify a texture matrix index per vertex, using GX_VA_TEX0MTXIDX through GX_VA_TEX7MTXIDX. Each matrix index is an eight-bit value that is the row address of the texture matrix in matrix memory. The matrix index number corresponds to the generated texture coordinate used in GXSetTexCoordGen. For example, GX_VA_TEX3MTXIDX indicates the matrix used when generating GX_TEXCOORD3. You must provide texture matrix indices in sequential order, but it is possible to skip matrix indices. For example, you can assign GX_VA_TEX0MTXIDX and GX_VA_TEX2MTXIDX. The texture coordinate GX_TEXCOORD1 will use the matrix specified in GXSetTexCoordGen. In other words, the default texture matrix index provided by GXSetTexCoordGen will be overridden by a per-vertex matrix index if one is provided. Providing texture matrix indices per vertex may be necessary when generating texture coordinates from a skinned (stitching) model, for example, when reflection-mapping a skinned model.

GX_VA_POS

The GX_VA_POS attribute is used for position. Position is the only attribute required for each vertex. 

GX_VA_NRM, GX_VA_NBT

The GX_VA_NRM attribute is used for the normals of three elements. GX_VA_NBT is enabled when the tri-norm vectors (normal, binormal, and tangent) are required, such as for bump mapping. GX_VA_NRM and GX_VA_NBT should not be enabled at the same time. GX_VA_NRM and GX_VA_NBT will share the same format in the vertex attribute format. See the GXSetVtxAttrFmt function.

Attribute Order within a Vertex

The attribute data is specified in a particular order for each vertex. The required order is specified in the Arguments section for attr. Be aware that any attributes can be enabled for a vertex, but when drawing a primitive (see GXBegin), the enabled attributes must be specified in the ascending order shown in the table above.(See also GXMatrixIndex, GXPosition, GXColor, GXNormal and GXTexCoord.)

Texture coordinates must be enabled consecutively from GX_VA_TEX0.

If GX_VA_CLR1 is enabled, GX_VA_CLR0 cannot also be enabled. The vertex color will be interpreted as GX_COLOR0A0 for lighting. See the GXSetChanCtrl function.

Attribute Types

The attribute type GX_NONE indicates that no data or index is sent for this attribute. The attribute GX_DIRECT indicates that the data for this attribute will be passed directly in the graphics command stream (as opposed to being indexed).

The attribute type GX_INDEX8 indicates that an eight-bit index will be sent in the command stream. The eight-bit index 0xff is a reserved value. It's used to disable the vertex in the graphics processor. You can use this to disable certain triangles in a display list, without having to regenerate a new display list. The graphics processor will use the index, along with the attribute's array base pointer and stride (see GXSetArray), to look up the attribute's data. The GX_INDEX16 attribute indicates a 16-bit index is present in the vertex data. The 16-bit index 0xffff is a reserved value used to disable the vertex in the graphics processor.

GXInit clears the current vertex descriptor using GXClearVtxDesc.

See Also

GXClearVtxDesc, GXSetVtxDescv, GXSetVtxAttrFmt, GXSetVtxAttrFmtv, GXSetArray, GXBegin

Revision History

2006/03/01 Initial version.

CONFIDENTIAL