1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 9<title><CODE>GXSetArray</CODE></title> 10</head> 11 12<body> 13 14<h1 align="left"><CODE>GXSetArray</CODE></h1> 15 16<h2>C Specification</h2> 17 18<dl> 19<dd><pre><CODE>#include <revolution/gx.h></CODE></pre> 20 </dd> 21<dd><pre><CODE>void GXSetArray( <A href="../Enumerated_Types/GXAttr.html">GXAttr</A> attr, const void* base_ptr, u8 stride )</CODE></pre> 22 </dd> 23</dl> 24 25<h2>Arguments</h2> 26<TABLE border="1" cellpadding="3" cellspacing="0.1"> 27 <tr> 28<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE><STRONG><EM><CODE>attr</CODE></EM></STRONG></font></strong></em></TD> 29<TD width="520">specifies the attribute array name <BR>Accepted values are:<BR> 30 <TABLE border="1" width="500" cellspacing="0.1"> 31 32 <tr> 33<TD width="150" bgcolor="#C0C0C0">Attributes</TD> 34<TD width="350" bgcolor="#C0C0C0">Description</TD> 35 </tr> 36 <tr> 37<TD width="150"><code>GX_POS_MTX_ARRAY</code></TD> 38<TD width="350">position matrix array</TD> 39 </tr> 40 <tr> 41<TD width="150"><code>GX_NRM_MTX_ARRAY</code></TD> 42<TD width="350">normal matrix array</TD> 43 </tr> 44 <tr> 45<TD width="150"><code>GX_TEX_MTX_ARRAY</code></TD> 46<TD width="350">texture matrix array</TD> 47 </tr> 48 <tr> 49<TD width="150"><code>GX_LIGHT_ARRAY</code></TD> 50<TD width="350">light object array</TD> 51 </tr> 52 <tr> 53<TD width="150"><code>GX_VA_POS</code></TD> 54<TD width="350">position array</TD> 55 </tr> 56 <tr> 57<TD width="150"><CODE>GX_VA_NRM</CODE> or<br> <CODE>GX_VA_NBT</CODE></TD> 58<TD width="350">normal or normal/binormal/tangent array</TD> 59 </tr> 60 <tr> 61<TD width="150"><code>GX_VA_CLR0</code></TD> 62<TD width="350">color 0 array</TD> 63 </tr> 64 <tr> 65<TD width="150"><code>GX_VA_CLR1</code></TD> 66<TD width="350">color 1 array</TD> 67 </tr> 68 <tr> 69<TD width="150"><code>GX_VA_TEX0</code></TD> 70<TD width="350">texture coordinate 0 array</TD> 71 </tr> 72 <tr> 73<TD width="150"><code>GX_VA_TEX1</code></TD> 74<TD width="350">texture coordinate 1 array</TD> 75 </tr> 76 <tr> 77<TD width="150"><code>GX_VA_TEX2</code></TD> 78<TD width="350">texture coordinate 2 array</TD> 79 </tr> 80 <tr> 81<TD width="150"><code>GX_VA_TEX3</code></TD> 82<TD width="350">texture coordinate 3 array</TD> 83 </tr> 84 <tr> 85<TD width="150"><code>GX_VA_TEX4</code></TD> 86<TD width="350">texture coordinate 4 array</TD> 87 </tr> 88 <tr> 89<TD width="150"><code>GX_VA_TEX5</code></TD> 90<TD width="350">texture coordinate 5 array</TD> 91 </tr> 92 <tr> 93<TD width="150"><code>GX_VA_TEX6</code></TD> 94<TD width="350">texture coordinate 6 array</TD> 95 </tr> 96 <tr> 97<TD width="150"><code>GX_VA_TEX7</code></TD> 98<TD width="350">texture coordinate 7 array</TD> 99 </tr> 100 101 </TABLE> 102 </TD> 103 </tr> 104 <tr> 105<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE><STRONG><EM><CODE>base_ptr</CODE></EM></STRONG></font></strong></em></TD> 106<TD width="520">pointer to the first element in the attribute data array</TD> 107 </tr> 108 <tr> 109<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE><STRONG><EM><CODE>stride</CODE></EM></STRONG></font></strong></em></TD> 110<TD width="520">the stride in bytes between the attribute data elements</TD> 111 </tr> 112</TABLE> 113<h2>Return Values</h2> 114 115<p>None.</p> 116<H2>Description</H2> 117<P>This function sets the array base pointer and stride for a single attribute. The array base and stride are used to calculate the address of the indexed attribute data using the following equation:</P> 118<P>attr_addr = <STRONG><EM><CODE>base_ptr</CODE></EM></STRONG> + attr_idx * <STRONG><EM><CODE>stride</CODE></EM></STRONG></P> 119<P>When drawing a graphics primitive that has been enabled to use indexed attributes (see <a href="GXSetVtxDesc.html"><code>GXSetVtxDesc</code></a>), <em>attr_idx </em>is supplied in the vertex data. The format and size of the data in the array must also be described using <a href="GXSetVtxAttrFmt.html"><code>GXSetVtxAttrFmt</code></a>.</P> 120<P>You can also index other data, such as matrices (see <a href="../Transform/GXLoadPosMtxIndx.html"><code>GXLoadPosMtxIndx</code></a>, <a href="../Transform/GXLoadNrmMtxIndx3x3.html"><code>GXLoadNrmMtxIndx3x3</code></a>, and <a href="../Transform/GXLoadTexMtxIndx.html"><code>GXLoadTexMtxIndx</code></a>), and light objects (see <a href="../Lighting/GXLoadLightObjIndx.html"><code>GXLoadLightObjIndx</code></a>). For matrices and light objects, the size and format of the data to be loaded is implied by the function call.</P> 121<P>There is a base pointer, <code>base_ptr</code>, for each type of attribute as well as for light data and matrices. Each attribute can be stored in its own array for maximum data compression (i.e., removal of redundant attribute data). The <code><strong><em>stride</em></strong></code> is in byte units and is the distance between attributes in the array.</P> 122<P>Indexed data is loaded into a vertex cache in the graphics processor. The vertex cache fetches 32 bytes of data for each cache miss. As a result, there is a small performance benefit in aligning attribute arrays to 32 bytes, and in arranging vertex data so that it doesn't span 32-byte boundaries. Conveniently enough, <a href="../../os/Alloc/OSAlloc.html"><code>OSAlloc</code></a> returns 32-byte aligned pointers. For static data arrays, the <code>ATTRIBUTE_ALIGN(32)</code> macro (for the MetroWerks compiler) can be used to align <code>base_ptr</code> to 32 bytes, as in:</P> 123<P><code>u32 mydata[] ATTRIBUTE_ALIGN(32) = {<br> // initialize data<br> };</code></P> 124 125<h2>See Also</h2> 126 127<p><a href="GXSetVtxAttrFmt.html"><CODE>GXSetVtxAttrFmt</CODE></a><br> <a href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</A></CODE></p> 128<H2>Revision History</H2> 129<P>8/10/2006 Corrected mistake with enum type.<br>03/01/2006 Initial version.</P> 130<hr> 131<P>CONFIDENTIAL</p> 132</BODY> 133</HTML>