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>GXNormal[n][t]</TITLE> 9</HEAD> 10<BODY> 11<H1 align="left">GXNormal</H1> 12 13<H2>Syntax</H2> 14<dl><dd><pre class="construction"> 15#include <revolution/gx.h> 16 17void GXNormal3f32( f32 x, f32 y, f32 z ); 18void GXNormal3s16( s16 x, s16 y, s16 z ); 19void GXNormal3s8 ( s8 x, s8 y, s8 z ); 20 21void GXNormal1x16( u16 index ); 22void GXNormal1x8 ( u8 index ); 23</pre></dd></dl> 24 25<H2>Arguments</H2> 26<P>Depends on the function being called.</P> 27 28<H2>Return Values</H2> 29<P>None.</P> 30 31<H2>Description</H2> 32<P>These functions are used to specify normal data for a vertex. They can be called only between the <a href="GXBegin.html"><code>GXBegin</code></a> and <a href="GXEnd.html"><code>GXEnd</code></a> functions. Function names take the following format:</P> 33<P><CODE>GXNormal[n][t]</CODE></P> 34<P> </P> 35<P>The function name parameter <CODE>n</CODE> is one of {1, 3} and indicates 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 (<CODE>s</CODE>), floating point (<CODE>f</CODE>), and index (<CODE>x</CODE>) data types. The subsequent number indicates the data size in bits, so <code>s8</code> indicates a signed 8-bit quantity. Consequently, the <CODE>GXNormal3f32</CODE> function takes 3 floating-point arguments.</P> 36<P>The selected function must correspond to the current vertex descriptor and the vertex attribute format specified in <CODE>GXBegin</CODE>. The current vertex descriptor is set using the <A href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function. The vertex attribute format is set using the <A href="GXSetVtxAttrFmt.html"><CODE>GXSetVtxAttrFmt</CODE></A> function.</P> 37<P>Normals come in two flavors, <CODE>GX_VA_NRM</CODE> and <CODE>GX_VA_NBT</CODE>. The attribute <CODE>GX_VA_NRM </CODE> is a 3-element normal (that is, one normalized vector). The attribute <CODE>GX_VA_NBT</CODE> actually specifies 3 normalized vectors: normal, binormal, and tangent. Each of these has three elements. These three vectors are usually orthogonal and used for bump mapping and other special rendering techniques. To specify directly referenced data for a <CODE>GX_VA_NBT</CODE> attribute, simply call the appropriate <CODE>GXNormal[n][t]</CODE> function three times.</P> 38<P><CODE>GXBegin(GX_TRIANGLES, GX_VTXFMT0, n);<BR> GXPosition3f32 ( px, py, pz );<BR> GXNormal3f32 ( nx, ny, nz );<BR> GXNormal3f32 ( bx, by, bz );<BR> GXNormal3f32 ( tx, ty, tz );<BR> // ...<BR> GXEnd();</CODE></P> 39<P><CODE>GX_VA_NBT</CODE> can specify divided index reference data for each normal vector. Furthermore, for each of the three normal vectors that comprise the NBT there are tacit offsets. For divided indices, the attribute address is computed as follows:</P> 40 41<P><SUB><IMG border="0" src="../images/image115.gif" width="784" height="85"></SUB></P> 42<P>For the application, <CODE>GXSetVtxAttrFmt</CODE> specifies the number of components in <CODE>GX_NRM_NBT3</CODE>, which specifies the divided NBT indices. For the vertex descriptor that specifies a normal vector index reference, a single index is replaced with a specification for three divided indices.</P> 43<P>There are two ways to set the normal vector table for NBT normal vectors. One method sets the table as an arrangement of the three normal vectors in interleave fashion. The internalized NBT offsets are used to select the correct values from this interleaved table, making this method very clean. The other method (and regardless of names, normal vectors are normal vectors) sets a single table. To implement this method, the NBT offset must be considered, adjusting the indices to counterbalance the NBT offset. In other words, it would be as follows.</P> 44<P><SUB><IMG border="0" src="../images/image116.gif" width="509" height="116"></SUB></P> 45 46<P>Vertex functions must be called in the order specified by the <A href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function. Each vertex must send attributes (position coordinates, colors, normals, and so forth) in the specified order to guarantee proper parsing by the graphics hardware.</P> 47<P>When an attribute is indexed (meaning its type, set by the <A href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function, is <CODE>GX_INDEX8</CODE> or <CODE>GX_INDEX16</CODE>), the vertex function specifies an index to the data, not the data itself. The location of the array that will be indexed is described using the <A href="GXSetArray.html"><CODE>GXSetArray</CODE></A> function. If an attribute is direct (meaning its type, set by the <A href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function, is <CODE>GX_DIRECT</CODE>), the vertex function sends the data. No vertex function should be called for an attribute that is disabled (that is, its type, set by the <A href="GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function, is <CODE>GX_NONE</CODE>). However, every vertex must at least enable <CODE>GX_VA_POS</CODE>.</P> 48<P>The <CODE>GXNormal[n][t]</CODE> functions are implemented as inline functions in the non-debug version of the GX library for optimal performance. The <CODE>GXNormal[n][t]</CODE> functions are implemented as actual functions in the debug version of the GX library so the library can verify the correct order of vertex function calls between <A href="GXBegin.html"><CODE>GXBegin</CODE></A> and <A href="GXEnd.html"><CODE>GXEnd</CODE></A> (a common source of errors).</P> 49 50<H2>See Also</H2> 51<P class="reference"> 52<A href="GXBegin.html">GXBegin</A>, 53<A href="GXEnd.html">GXEnd</A>, 54<A href="GXSetVtxDesc.html">GXSetVtxDesc</A>, 55<A href="GXSetVtxAttrFmt.html">GXSetVtxAttrFmt</A> 56</P> 57 58<H2>Revision History</H2> 59<P> 602006/03/01 Initial version.<br> 61</P> 62 63<hr><p>CONFIDENTIAL</p></body> 64</html>
