GXSetVtxDesc

Syntax

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

Attributes	Ascending Vertex Order	Description
GX_VA_PNMTXIDX	0	Position coordinates/normal 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	Position coordinates.
GX_VA_NRM or GX_VA_NBT	10	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	Direct data.
GX_INDEX8	8-bit index reference.
GX_INDEX16	16-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_PNMTXIDX`

The attr argument names the attribute. The GX_VA_PNMTXIDX attribute is used to specify one 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 the GXSetTexCoordGen function. 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 the GXSetTexCoordGen function. In other words, the default texture matrix index provided by the GXSetTexCoordGen function 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 coordinates. Position is the only attribute required for each vertex.

`GX_VA_NRM, GX_VA_NBT`

The GX_VA_NRM attribute is used for three-element normals. GX_VA_NBT is enabled when three normals (normal, binormal, and tangent) are needed, 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 share the same format among the vertex attribute formats. 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 rendering a primitive (see the GXBegin function), the enabled attributes must be specified in the ascending order shown in the table above.(In addition, refer to 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.

Note: The Wii graphics processor cannot accurately handle vertices that have a single position coordinate index and one or more matrix indices. To accurately handle this type of vertex, it is necessary to append a color index or another component after the position coordinate index. It is not necessary to append these if the vertex has only a single position coordinate index with no matrix index.

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 is 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 the GXSetArray function), 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.

The GXInit function clears the current vertex descriptor using the GXClearVtxDesc function.

Revision History

2008/08/28 Added a note about handling vertices that have a position coordinate index and a matrix index.
2006/03/01 Initial version.

CONFIDENTIAL