1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>GXSetVtxDesc</TITLE> 9</HEAD> 10<BODY> 11<H1 align="left">GXSetVtxDesc</H1> 12 13<H2>Syntax</H2> 14<dl><dd><pre class="construction"> 15#include <revolution/gx.h> 16 17void GXSetVtxDesc( <A href="../Enumerated_Types/GXAttr.html">GXAttr</A> attr, <A href="../Enumerated_Types/GXAttrType.html">GXAttrType</A> type ); 18</pre></dd></dl> 19 20<H2><A name="Arguments">Arguments</A></H2> 21<TABLE class="arguments" border="1" > 22 <TBODY> 23 <TR> 24<TH><A name="attr">attr</A></TH> 25<TD>Attribute name. <BR>Specifiable attribute data must be sent in ascending order as shown below. 26 <TABLE class="arguments" border="1" > 27 <TBODY> 28 <TR> 29 <TD bgcolor="#C0C0C0">Attributes</TD> 30 <TD width="150" bgcolor="#C0C0C0">Ascending Vertex Order</TD> 31 <TD bgcolor="#C0C0C0">Description</TD> 32 </TR> 33 <TR> 34 <TH>GX_VA_PNMTXIDX</TH> 35 <TD>0</TD> 36 <TD>Position coordinates/normal matrix index.</TD> 37 </TR> 38 <TR> 39 <TH>GX_VA_TEX0MTXIDX</TH> 40 <TD>1</TD> 41 <TD>The <CODE>GX_TEXCOORD0</CODE> matrix index.</TD> 42 </TR> 43 <TR> 44 <TH>GX_VA_TEX1MTXIDX</TH> 45 <TD>2</TD> 46 <TD>The <CODE>GX_TEXCOORD1</CODE> matrix index.</TD> 47 </TR> 48 <TR> 49 <TH>GX_VA_TEX2MTXIDX</TH> 50 <TD>3</TD> 51 <TD>The <CODE>GX_TEXCOORD2</CODE> matrix index.</TD> 52 </TR> 53 <TR> 54 <TH>GX_VA_TEX3MTXIDX</TH> 55 <TD>4</TD> 56 <TD>The <CODE>GX_TEXCOORD3</CODE> matrix index.</TD> 57 </TR> 58 <TR> 59 <TH>GX_VA_TEX4MTXIDX</TH> 60 <TD>5</TD> 61 <TD>The <CODE>GX_TEXCOORD4</CODE> matrix index.</TD> 62 </TR> 63 <TR> 64 <TH>GX_VA_TEX5MTXIDX</TH> 65 <TD>6</TD> 66 <TD>The <CODE>GX_TEXCOORD5</CODE> matrix index.</TD> 67 </TR> 68 <TR> 69 <TH>GX_VA_TEX6MTXIDX</TH> 70 <TD>7</TD> 71 <TD>The <CODE>GX_TEXCOORD6</CODE> matrix index.</TD> 72 </TR> 73 <TR> 74 <TH>GX_VA_TEX7MTXIDX</TH> 75 <TD>8</TD> 76 <TD>The <CODE>GX_TEXCOORD7</CODE> matrix index.</TD> 77 </TR> 78 <TR> 79 <TH>GX_VA_POS</TH> 80 <TD>9</TD> 81 <TD>Position coordinates.</TD> 82 </TR> 83 <TR> 84 <TH>GX_VA_NRM or<BR> 85 GX_VA_NBT</TH> 86 <TD>10</TD> 87 <TD>Normal, or NBT (normal/binormal/tangent).</TD> 88 </TR> 89 <TR> 90 <TH>GX_VA_CLR0</TH> 91 <TD>11</TD> 92 <TD>Color 0.</TD> 93 </TR> 94 <TR> 95 <TH>GX_VA_CLR1</TH> 96 <TD>12</TD> 97 <TD>Color 1.</TD> 98 </TR> 99 <TR> 100 <TH>GX_VA_TEX0</TH> 101 <TD>13</TD> 102 <TD>Texture coordinate 0.</TD> 103 </TR> 104 <TR> 105 <TH>GX_VA_TEX1</TH> 106 <TD>14</TD> 107 <TD>Texture coordinate 1.</TD> 108 </TR> 109 <TR> 110 <TH>GX_VA_TEX2</TH> 111 <TD>15</TD> 112 <TD>Texture coordinate 2.</TD> 113 </TR> 114 <TR> 115 <TH>GX_VA_TEX3</TH> 116 <TD>16</TD> 117 <TD>Texture coordinate 3.</TD> 118 </TR> 119 <TR> 120 <TH>GX_VA_TEX4</TH> 121 <TD>17</TD> 122 <TD>Texture coordinate 4.</TD> 123 </TR> 124 <TR> 125 <TH>GX_VA_TEX5</TH> 126 <TD>18</TD> 127 <TD>Texture coordinate 5.</TD> 128 </TR> 129 <TR> 130 <TH>GX_VA_TEX6</TH> 131 <TD>19</TD> 132 <TD>Texture coordinate 6.</TD> 133 </TR> 134 <TR> 135 <TH><CODE>GX_VA_TEX7</CODE></TH> 136 <TD>20</TD> 137 <TD>Texture coordinate 7.</TD> 138 </TR> 139 </TBODY> 140 </TABLE> 141 </TD> 142 </TR> 143 <TR> 144<TH>type</TH> 145<TD>Method used to reference the attribute. Accepted values are:<BR> 146 <TABLE class="arguments" border="1" > 147 <tr> 148 <TD bgcolor="#C0C0C0">Name</TD> 149 <TD bgcolor="#C0C0C0">Description</TD> 150 </tr> 151 <tr> 152 <TH>GX_NONE</TH> 153 <TD>No data for this attribute.</TD> 154 </tr> 155 <tr> 156 <TH>GX_DIRECT</TH> 157 <TD>Direct data.</TD> 158 </tr> 159 <tr> 160 <TH>GX_INDEX8</TH> 161 <TD>8-bit index reference.</TD> 162 </tr> 163 <tr> 164 <TH>GX_INDEX16</TH> 165 <TD>16-bit index reference.</TD> 166 </tr> 167 168 </TABLE> 169 Only <code>GX_NONE</code> and <code>GX_DIRECT</code> can be applied with <code>GX_VA_PNMTXIDX</code> and <code>GX_VA_TEX*MTXIDX</code>.</TD> 170 </TR> 171 </TBODY> 172</TABLE> 173 174<H2>Return Values</H2> 175<P>None.</P> 176 177<H2>Description</H2> 178<P>Sets the <SPAN class="argument">type</SPAN> of a single attribute (<SPAN class="argument">attr</SPAN>) 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 <FONT color="009000">by the graphics processor</FONT> (GP) to interpret the graphics command stream <FONT color="009000">produced by the GX API</FONT>. In particular, the current vertex descriptor is used to parse vertex data present in the command stream.</P> 179 180<H3>Attributes</H3> 181<H4><CODE>GX_VA_PNMTXIDX</CODE></H4> 182<P>The <SPAN class="argument">attr</SPAN> argument names the attribute. The <CODE>GX_VA_PNMTXIDX</CODE> attribute is used to specify one matrix index (8 bits) per vertex. This index is used to index position (and normal, when <a href="../../gx.html#Lighting">lighting</a> is used) matrices in matrix memory. Providing a matrix index per vertex allows character skinning.</P> 183 184<H4><CODE>GX_VA_TEX0MTXIDX-GX_VA_TEX7MTXIDX</CODE></H4> 185<P>You may also specify a texture matrix index per vertex, using <CODE>GX_VA_TEX0MTXIDX</CODE> through <CODE>GX_VA_TEX7MTXIDX</CODE>. 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 <A href="../TexCoordGen/GXSetTexCoordGen.html"><CODE>GXSetTexCoordGen</CODE></A> function. For example, <CODE>GX_VA_TEX3MTXIDX</CODE> indicates the matrix used when generating <CODE>GX_TEXCOORD3</CODE>. You must provide texture matrix indices in sequential order, but it is possible to skip matrix indices. For example, you can assign <CODE>GX_VA_TEX0MTXIDX</CODE> and <CODE>GX_VA_TEX2MTXIDX</CODE>. The texture coordinate <CODE>GX_TEXCOORD1</CODE> will use the matrix specified in the <A href="../TexCoordGen/GXSetTexCoordGen.html"><CODE>GXSetTexCoordGen</CODE></A> function. In other words, the default texture matrix index provided by the <A href="../TexCoordGen/GXSetTexCoordGen.html"><CODE>GXSetTexCoordGen</CODE></A> 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.</P> 186 187<H4><CODE>GX_VA_POS</CODE></H4> 188<P>The <CODE>GX_VA_POS</CODE> attribute is used for position coordinates. Position is the only attribute required for each vertex. </P> 189 190<H4><CODE>GX_VA_NRM, GX_VA_NBT</CODE></H4> 191<P>The <CODE>GX_VA_NRM</CODE> attribute is used for three-element normals. <CODE>GX_VA_NBT</CODE> is enabled when three normals (normal, binormal, and tangent) are needed, such as for bump mapping. <CODE>GX_VA_NRM</CODE> and <CODE>GX_VA_NBT</CODE> should not be enabled at the same time. <CODE>GX_VA_NRM</CODE> and <CODE>GX_VA_NBT</CODE> share the same format among the vertex attribute formats. See the <A href="GXSetVtxAttrFmt.html"><CODE>GXSetVtxAttrFmt</CODE></A> function.</P> 192 193<H3>Attribute Order within a Vertex</H3> 194<P>The attribute data is specified in a particular order for each vertex. The required order is specified in the <EM>Arguments</EM> section for <SPAN class="argument">attr</SPAN>. Be aware that any attributes can be enabled for a vertex, but when rendering a primitive (see the <A href="GXBegin.html"><CODE>GXBegin</CODE></A> function), the enabled attributes must be specified in the ascending order shown in the table above.(In addition, refer to <a href="GXMatrixIndex.html"><code>GXMatrixIndex</code></a>, <a href="GXPosition.html"><code>GXPosition</code></a>, <a href="GXColor.html"><code>GXColor</code></a>, <a href="GXNormal.html"><code>GXNormal</code></a>, and <a href="GXTexCoord.html"><code>GXTexCoord</code></a>.)</P> 195<P>Texture coordinates must be enabled consecutively from <CODE>GX_VA_TEX0</CODE>.</P> 196<P>If <CODE>GX_VA_CLR1</CODE> is enabled, <CODE>GX_VA_CLR0</CODE> cannot also be enabled. The vertex color will be interpreted as <CODE>GX_COLOR0A0</CODE> for lighting. See the <A href="../Lighting/GXSetChanCtrl.html"><CODE>GXSetChanCtrl</CODE></A> function.</P> 197 198<P> 199<STRONG>Note:</STRONG> 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. 200</P> 201 202<H3>Attribute Types</H3> 203<P>The attribute type <CODE>GX_NONE</CODE> indicates that no data or index is sent for this attribute. The attribute <CODE>GX_DIRECT</CODE> indicates that the data for this attribute will be passed directly in the graphics command stream (as opposed to being indexed).</P> 204<P>The attribute type <CODE>GX_INDEX8</CODE> indicates that an eight-bit index will be sent in the command stream. The eight-bit index <strong>0xff</strong> 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 <A href="GXSetArray.html"><CODE>GXSetArray</CODE></A> function), to look up the attribute's data. The <CODE>GX_INDEX16</CODE> attribute indicates a 16-bit index is present in the vertex data. The 16-bit index <strong>0xffff</strong> is a reserved value used to disable the vertex in the graphics processor.</P> 205<P>The <A href="../Management/GXInit.html"><CODE>GXInit</CODE></A> function clears the current vertex descriptor using the <A href="GXClearVtxDesc.html"><CODE>GXClearVtxDesc</CODE></A> function.</P> 206 207<H2>See Also</H2> 208<P> 209<A href="GXClearVtxDesc.html"><CODE>GXClearVtxDesc</CODE></A><BR> <A href="GXSetVtxDescv.html"><CODE>GXSetVtxDescv</CODE></A><BR> <A href="GXSetVtxAttrFmt.html"><CODE>GXSetVtxAttrFmt</CODE></A><BR> <A href="GXSetVtxAttrFmtv.html"><CODE>GXSetVtxAttrFmtv</CODE></A><BR> <A href="GXSetArray.html"><CODE>GXSetArray</CODE></A><BR> <A href="GXBegin.html"><CODE>GXBegin</CODE></A> 210</P> 211 212<H2>Revision History</H2> 213<P> 2142008/08/28 Added a note about handling vertices that have a position coordinate index and a matrix index.<br>2006/03/01 Initial version. 215</P> 216 217<hr><p>CONFIDENTIAL</p></body> 218</HTML>