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>GXSetChanCtrl</title> 10</head> 11 12<body> 13 14<h1 align="left">GXSetChanCtrl</h1> 15 16 17<h2>C Specification</h2> 18 19<dl> 20 <dd><pre><CODE>#include <revolution/gx.h></CODE></pre> 21 </dd> 22 <dd><pre><CODE>void GXSetChanCtrl( 23 <a href="../Enumerated_Types/GXChannelID.html">GXChannelID</a> chan, 24 <a href="../Enumerated_Types/GXBool.html">GXBool</a> enable, 25 <a href="../Enumerated_Types/GXColorSrc.html">GXColorSrc</a> amb_src, 26 <a href="../Enumerated_Types/GXColorSrc.html">GXColorSrc</a> mat_src, 27 <a href="../Enumerated_Types/GXLightID.html">GXLightID</a> light_mask, 28 <a href="../Enumerated_Types/GXDiffuseFn.html">GXDiffuseFn</a> diff_fn, 29 <a href="../Enumerated_Types/GXAttnFn.html">GXAttnFn</a> attn_fn );</CODE></pre> 30 </dd> 31</dl> 32 33<h2>Arguments</h2> 34<TABLE border="1" cellpadding="3" cellspacing="0.1"> 35 <tr> 36<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>chan<CODE></strong></em></TD> 37<TD width="520">the color <a href="../Enumerated_Types/GXChannelID.html">channel</a> <BR>Accepted values are:<br> 38 <TABLE width="500" border="1" cellspacing="0.1"> 39 40 <tr> 41<TD width="150" bgcolor="#C0C0C0">Name</TD> 42<TD width="350" bgcolor="#C0C0C0">Target Channel</TD> 43 </tr> 44 <tr> 45<TD width="150" height="7"><code>GX_COLOR0</code></TD> 46<TD width="350" height="7">color channel 0</TD> 47 </tr> 48 <tr> 49<TD width="150" height="19"><code>GX_ALPHA0</code></TD> 50<TD width="350" height="19">alpha channel 0</TD> 51 </tr> 52 <tr> 53<TD width="150"><code>GX_COLOR1</code></TD> 54<TD width="350">color channel 1</TD> 55 </tr> 56 <tr> 57<TD width="150"><code>GX_ALPHA1</code></TD> 58<TD width="350">alpha channel 1</TD> 59 </tr> 60 <tr> 61<TD width="150"><code>GX_COLOR0A0</code></TD> 62<TD width="350">The same setting is made simultaneously for color channel 0 and alpha channel 0.</TD> 63 </tr> 64 <tr> 65<TD width="150"><code>GX_COLOR1A1</code></TD> 66<TD width="350">The same setting is made simultaneously for color channel 1 and alpha channel 1.</TD> 67 </tr> 68 69 </TABLE> 70 </TD> 71 </tr> 72 <tr> 73<TD width="120" valign="top" bgcolor="#ffffe8"><CODE>enable</CODE>></TD> 74<TD width="520">If <CODE>enable = GX_ENABLE</CODE>, lighting for this color channel is enabled.</TD> 75 </tr> 76 <tr> 77<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>amb_src</CODE></strong></em></TD> 78<TD width="520">the ambient color <a href="../Enumerated_Types/GXColorSrc.html">source</a><BR>Accepted values are:<br> 79 <TABLE width="500" border="1" cellspacing="0.1"> 80 81 <tr> 82<TD width="150" bgcolor="#C0C0C0">Name</TD> 83<TD width="350" bgcolor="#C0C0C0">Source</TD> 84 </tr> 85 <tr> 86<TD width="150" height="7"><code>GX_SRC_REG</code></TD> 87<TD width="350" height="7">uses the ambient color register</TD> 88 </tr> 89 <tr> 90<TD width="150" height="17"><code>GX_SRC_VTX</code></TD> 91<TD width="350" height="17">uses the vertex color</TD> 92 </tr> 93 94 </TABLE> 95 </TD> 96 </tr> 97 <tr> 98<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>mat_src</CODE></strong></em></TD> 99<TD width="520">the material color <A href="../Enumerated_Types/GXColorSrc.html">source</A><BR>Accepted values are:<br> 100 <TABLE width="500" border="1" cellspacing="0.1"> 101 102 <tr> 103<TD width="150" bgcolor="#C0C0C0">Name</TD> 104<TD width="350" bgcolor="#C0C0C0">Source</TD> 105 </tr> 106 <tr> 107<TD width="150" height="7"><code>GX_SRC_REG</code></TD> 108<TD width="350" height="7">uses the material color register</TD> 109 </tr> 110 <tr> 111<TD width="150" height="17"><code>GX_SRC_VTX</code></TD> 112<TD width="350" height="17">uses the vertex color</TD> 113 </tr> 114 115 </TABLE> 116 </TD> 117 </tr> 118 <tr> 119<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>light_mask</CODE></strong></em></TD> 120<TD width="520">Which lights to use in the lighting equation for this channel.<CODE><BR>This is the bitwise <CODE>OR</CODE> of <CODE>GX_LIGHT0, GX_LIGHT1,GX_LIGHT2,..., GX_LIGHT7</CODE>.</TD> 121 </tr> 122 <tr> 123<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>diff_fn<CODE></strong></em></TD> 124<TD width="520">the <a href="../Enumerated_Types/GXDiffuseFn.html">diffusion function</a> for lighting <BR>Accepted values are:<br> 125 <TABLE width="500" border="1" cellspacing="0.1"> 126 127 <tr> 128<TD width="150" bgcolor="#C0C0C0">Name</TD> 129<TD width="350" bgcolor="#C0C0C0">Type of Diffusion Function</TD> 130 </tr> 131 <tr> 132<TD width="150" height="7"><code>GX_DF_NONE</code></TD> 133<TD width="350" height="7">no diffusion function</TD> 134 </tr> 135 <tr> 136<TD width="150" height="17"><code>GX_DF_CLAMP</code></TD> 137<TD width="350" height="17">clamp type diffusion function (for normal use)</TD> 138 </tr> 139 <tr> 140<TD width="150" height="17"><code>GX_DF_SIGN</code></TD> 141<TD width="350" height="17">clamp type diffusion function (for special effects)</TD> 142 </tr> 143 144 </TABLE> 145 </TD> 146 </tr> 147 <tr> 148<TD width="120" valign="top" bgcolor="#ffffe8"><em><strong><CODE>attn_fn</CODE></strong></em></TD> 149<TD width="520">the <a href="../Enumerated_Types/GXAttnFn.html">attenuation function</a> for lighting <BR>Accepted values are:<br> 150 <TABLE width="500" border="1" cellspacing="0.1"> 151 152 <tr> 153<TD width="150" bgcolor="#C0C0C0">Name</TD> 154<TD width="350" bgcolor="#C0C0C0">Type of Attenuation Function</TD> 155 </tr> 156 <tr> 157<TD width="150" height="7"><code>GX_AF_NONE</code></TD> 158<TD width="350" height="7">the light is considered to be a plain (unattenuated) point light <BR>Light object attenuation coefficients will not not work for this setting.</TD> 159 </tr> 160 <tr> 161<TD width="150" height="17"><code>GX_AF_SPOT</code></TD> 162<TD width="350" height="17">angular attenuation and distance attenuation applied to each light</TD> 163 </tr> 164 <tr> 165<TD width="150" height="17"><code>GX_AF_SPEC</code></TD> 166<TD width="350" height="17">the light is used as a specular light</TD> 167 </tr> 168 169 </TABLE> 170 </TD> 171 </tr> 172</TABLE> 173<h2>Return Values</h2> 174 175<p>None.</p> 176<H2>Description</H2> 177<P>This function sets the lighting controls for a color channel. The color channel can have one or more (up to eight) lights associated with it, set using <CODE><EM><STRONG>light_mask</STRONG></EM></CODE>. The <CODE><EM><STRONG>diff_fn</STRONG></EM></CODE> and <CODE><EM><STRONG>attn_fn</STRONG></EM></CODE> arguments control the lighting equation for all lights associated with this channel. The <CODE><EM><STRONG>amb_src</STRONG></EM></CODE> and <CODE><EM><STRONG>mat_src</STRONG></EM></CODE> parameters can be used to select whether input source colors come from register or vertex colors. When <CODE><EM><STRONG>enable</STRONG></EM></CODE> for the channel is set to <code>GX_FALSE</code>, the material color source (set by <CODE><EM><STRONG>mat_src</STRONG></EM></CODE>) is passed as the channel's output color. When <CODE><EM><STRONG>enable</STRONG></EM></CODE> for the channel is set to <code>GX_TRUE</code>, the output color will depend on the other controls's settings (i.e., the lighting equation). <a href="../Management/GXInit.html"><code>GXInit</code></a> sets <CODE><EM><STRONG>enable</STRONG></EM></CODE> for all channels to <code>GX_FALSE</code>. This function, however, only configures the lighting channel. To output the results of channel calculations, use the <a href="GXSetNumChans.html"><code>GXSetNumChans</code></a> function.</P> 178<P>Even though channels <code>GX_COLOR0</code> and <code>GX_ALPHA0</code> are controlled separately for lighting, they are rasterized together as one RGBA color, <code>GX_COLOR0A0</code>. The same is true for <code>GX_COLOR1</code> and <code>GX_ALPHA1</code>—they are rasterized as <code>GX_COLOR1A1</code>. Since there is only one rasterizer for color in the graphics hardware, you must choose which color to rasterize for each stage in the Texture Environment (TEV) unit. This is accomplished using the <a href="../Tev/GXSetTevOrder.html"><code>GXSetTevOrder</code></a> function.</P> 179<P>In order to use a vertex color in channel <code>GX_COLOR1A1</code>, two colors per vertex are needed. Therefore both <code>GX_VA_CLR0</code> and <code>GX_VA_CLR1</code> must be enabled in the <a href="../Geometry/GXSetVtxDesc.html">current vertex descriptor</a>. If only either <code>GX_VA_CLR0</code> or <code>GX_VA_CLR1</code> is enabled in the current vertex descriptor, the vertex color is directed to the <code>GX_VA_COLOR0A0</code> channel.</P> 180<P>When <CODE><EM><STRONG>amb_src</STRONG></EM></CODE> is set to <code>GX_SRC_REG</code>, the color set by <a href="GXSetChanAmbColor.html"><code>GXSetChanAmbColor</code></a> is used as the ambient color. When <CODE><EM><STRONG>mat_src</STRONG></EM></CODE> is <code>GX_SRC_REG</code>, the color set by <a href="GXSetChanMatColor.html"><code>GXSetChanMatColor</code></a> is used as the material color.</P> 181<H3>Example: Local Diffuse Spot Lighting</H3> 182<P>This example demonstrates how to configure the <code>GX_COLOR0</code> channel to light the vertex color with a local diffuse spot light. The functions <a href="GXInitLightPos.html"><code>GXInitLightPos</code></a> and <a href="GXInitLightDir.html"><code>GXInitLightDir</code></a> are used to initialize light position and direction. The light direction and position are assumed to have been transformed into the view space prior to setting the light object. In order to enable diffuse lighting, <CODE><EM><STRONG>diff_fn</STRONG></EM></CODE> is set to <code>GX_DF_CLAMP</code>. Since this is a spot light, <CODE><EM><STRONG>attn_fn</STRONG></EM></CODE> is set to <code>GX_AF_SPOT</code>. The type of spot light angle attenuation function is determined by the light, set here by <a href="GXInitLightSpot.html"><code>GXInitLightSpot</code></a>. The distance attenuation function is set using <a href="GXInitLightDistAttn.html"><code>GXInitLightDistAttn</code></a>.</P> 183<P><FONT size="2"><CODE>// Assumes vertex will supply color0.<BR> <BR> // init light position, direction, atten functions<BR> GXInitLightPosv( &myLightObj, &pos );<BR> GXInitLightDirv( &myLightObj, &dir );<BR> GXInitLightSpot( &myLightObj, 30.0f, GX_SP_COS2 );<BR> GXInitLightDistAttn( &myLightObj, 100.0f, 0.5f, GX_DA_GENTLE );<BR> <BR> GXLoadLightObjImm( &myLightObj, GX_LIGHT0 );<BR> GXSetChanAmbColor( GX_COLOR0, black );<BR> GXSetChanCtrl(<BR> GX_COLOR0,<BR> GX_TRUE, // enable lighting<BR> GX_SRC_REG, // ambient = 0<BR> GX_SRC_VTX, // material color<BR> GX_LIGHT0,<BR> GX_DF_CLAMP, // normal diffuse light<BR> GX_AF_SPOT ); // spot light attenuation<BR> <BR> // Set number of channels to light<BR> GXSetNumChans( 1 );</CODE></FONT></P> 184<H3>Example: Specular Lighting</H3> 185<P>This example demonstrates how to set the <code>GX_COLOR0</code> channel for specular lighting. The function <a href="GXInitSpecularDir.html"><code>GXInitSpecularDir</code></a> is used to set light direction. The direction must be transformed to the view space prior to initializing the light object. Specular lights are considered to be infinitely far away, so a position argument is not necessary. The angle attenuation and distance attenuation functions are used to approximate an exponential attenuation function for specular lights. Call <a href="GXInitLightShininess.html"><code>GXInitLightShininess</code></a> (to set the attenuation coefficient) to control how shiny the lighted material appears. The <code>attn_fn</code> parameter is set to <code>GX_AF_SPEC</code>, enabling specular calculations.</P> 186<P><FONT size="2"><CODE>// Assumes vertex will supply color0.<BR> <BR> // init light direction, attn functions<BR> GXInitSpecularDirv( &myLightObj, &dir );<BR> GXInitLightShininess( &myLightObj, 5.0f );<BR> GXLoadLightObjImm( &myLightObj, GX_LIGHT0 );<BR> GXSetChanAmbColor( GX_COLOR0, black );<BR> GXSetChanCtrl(<BR> GX_COLOR0,<BR> GX_TRUE, // enable lighting<BR> GX_SRC_REG, // ambient = 0<BR> GX_SRC_VTX, // material color<BR> GX_LIGHT0,<BR> GX_DF_NONE, // no diffuse light<BR> GX_AF_SPEC ); // specular light<BR> <BR> // Set number of channels to light<BR> GXSetNumChans( 1 );</CODE></FONT></P> 187<H3>Example: Parallel Diffuse Lighting</H3> 188<P>Although the hardware doesn't support parallel diffuse lighting, it is possible to obtain <EM>nearly</EM> parallel lighting by putting a light very far away from every object to be lit. If the light's position is sufficiently distant from the object, all rays can be considered parallel.</P> 189<P><FONT size="2"><CODE>// prepares large number<br> #define LARGE_NUMBER 1.0E+18F<br> <br> // light direction on view space<br> // the 3D vector (dx, dy, dz) is supposed to be normalized.<br> f32 dx, dy, dz;<br> <br> // init light parameters<br> GXInitLightPos(<br> &myLightObj,<br> - dx * LARGE_NUMBER,<br> - dy * LARGE_NUMBER,<br> - dz * LARGE_NUMBER );<br> GXInitLightColor( &myLightObj, white );<br> GXLoadLightObjImm( &myLightObj, GX_LIGHT0 );<br> GXSetChanAmbColor( GX_COLOR0, ambColor );<br> GXSetChanMatColor( GX_COLOR0, matColor );<br> GXSetChanCtrl(<br> GX_COLOR0,<br> GX_TRUE, // enable lighting<br> GX_SRC_REG, // ambient = black<br> GX_SRC_REG, // material color<br> GX_LIGHT0,<br> GX_DF_CLAMP, // normal diffuse light<br> GX_AF_NONE ); // no attenuation<br> <br> // Set number of channels to light<br> GXSetNumChans( 1 );</CODE></FONT></P> 190<H3>Using Both Diffuse and Specular Lighting</H3> 191<P>The channel controls determine which calculations, either local-diffuse or specular, are performed in a channel. The arguments for the light (associated with the channel) are normally set with either of these calculations in mind. For example, a position and direction is set for local diffuse lights (used with a diffuse channel) and only the direction is set for a specular light (used with a specular channel). However, if you only need a directional diffuse light (when the light's position is so far away that its rays are considered parallel), then the same light's arguments can be used for both specular and diffuse channels. In this case, initialize the light's arguments using <a href="GXInitSpecularDir.html"><code>GXInitSpecularDir</code></a>.</P> 192<H3>Example: Per-Vertex Lighting using Pre-Lighting</H3> 193<P>This example will add a pre-lit color (calculated by the CG tool) as a per-vertex <code>GX_VA_CLR0</code> (see <a href="../Geometry/GXSetVtxDesc.html"><code>GXSetVtxDesc</code></a>) to the result for a diffuse local light. In this example we want to implement the equation:</P> 194<P><EM><CODE>lit_clr = pre_lit_clr * (amb_scale + diff_scale * other_atten * lit_color)</CODE></EM></P> 195<P>The ambient scale defines the minimum amount of pre-lit color when no lights are shining on an object. The sum of <CODE>amb_scale</CODE> and <CODE>diff_scale</CODE> should equal 1.0; when the object is in the brightest light, the vertex color is equal to the pre-lit color.</P> 196<P>The material color is set to be the vertex color (pre-lit color). The ambient color register is set to be equal to <CODE>amb_scale</CODE>. The light color is scaled by <CODE>diff_scale</CODE>.</P> 197<P><FONT size="2"><CODE>//<BR> // Assumes vertex will supply color0 = pre-lit color.<BR> //<BR> GXInitLightColor(<BR> myLightObj,<BR> ScaleColor(myLitClr, 0.75)); // diffuse scale<BR> //<BR> // init light position, direction, atten functions<BR> // not shown<BR> GXLoadLightObjImm(<BR> myLightObj,<BR> GX_LIGHT0);</CODE></FONT></P> 198<P><FONT size="2"><CODE>GXSetChanAmbColor(<BR> GX_COLOR0,<BR> ScaleColor(white, 0.25)); // ambient scale<BR> GXSetChanCtrl(<BR> GX_COLOR0,<BR> GX_TRUE, // enable lighting<BR> GX_SRC_REG, // ambient scale<BR> GX_SRC_VTX, // material color = pre-lit color(vtx)<BR> GX_LIGHT0,<BR> GX_DF_CLAMP, // normal diffuse light<BR> GX_AF_SPOT ); // spot light attenuation<BR> //<BR> // Set the material color register<BR> GXSetChanMatColor( GX_COLOR0, (GXColor){0xff,0x00,0x80,0xff} );<BR> GXSetNumChans( 1 );</CODE></FONT></P> 199<H3>Example: Four Attenuations for Projected Lighting</H3> 200<P>This example shows how to compute local-light attenuation values for four projected texture lights. No colors are passed to the vertices. The material color comes from the channel material register and is set to pass the attenuation (multiply by 1.0). There is no contribution from the ambient color. Each channel can be used to attenuate a projected texture in the TEV unit.</P> 201<P><FONT size="2"><CODE>// Assumes that 4 light objects have been initialized and loaded<BR> // <BR> GXSetChanCtrl(<BR> GX_COLOR0,<BR> GX_TRUE,<BR> GX_SRC_REG,<BR> GX_SRC_REG,<BR> GX_LIGHT0,<BR> GX_DF_CLAMP,<BR> GX_AF_SPOT );<BR> GXSetChanCtrl(<BR> GX_ALPHA0,<BR> GX_TRUE,<BR> GX_SRC_REG,<BR> GX_SRC_REG,<BR> GX_LIGHT1,<BR> GX_DF_CLAMP,<BR> GX_AF_SPOT );<BR> GXSetChanCtrl(<BR> GX_COLOR1,<BR> GX_TRUE,<BR> GX_SRC_REG,<BR> GX_SRC_REG,<BR> GX_LIGHT2,<BR> GX_DF_CLAMP,<BR> GX_AF_SPOT );<BR> GXSetChanCtrl(<BR> GX_ALPHA1,<BR> GX_TRUE,<BR> GX_SRC_REG,<BR> GX_SRC_REG,<BR> GX_LIGHT3,<BR> GX_DF_CLAMP,<BR> GX_AF_SPOT );<BR> GXSetChanMatColor( GX_COLOR0A0, WhiteOpaque );<BR> GXSetChanMatColor( GX_COLOR1A1, WhiteOpaque );<BR> GXSetChanAmbColor( GX_COLOR0A0, BlackXlu );<BR> GXSetChanAmbColor( GX_COLOR1A1, BlackXlu );<BR> GXSetNumChans( 2 );</CODE></FONT></P> 202<h2>See Also</h2> 203 204<p><code><a href="GXSetChanMatColor.html">GXSetChanMatColor</a><br> <a href="GXSetChanAmbColor.html">GXSetChanAmbColor</a><br> <a href="GXSetNumChans.html">GXSetNumChans</a></code></p> 205<H2>Revision History</H2> 206<P>2006/03/01 Initial version.</P><hr> 207<P>CONFIDENTIAL</p> 208</BODY> 209</HTML>