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<h2>Syntax</h2> 17<dl><dd><pre class="construction"> 18#include <revolution/gx.h> 19 20void GXSetChanCtrl( 21 <a href="../Enumerated_Types/GXChannelID.html">GXChannelID</a> chan, 22 <a href="../Enumerated_Types/GXBool.html">GXBool</a> enable, 23 <a href="../Enumerated_Types/GXColorSrc.html">GXColorSrc</a> amb_src, 24 <a href="../Enumerated_Types/GXColorSrc.html">GXColorSrc</a> mat_src, 25 <a href="../Enumerated_Types/GXLightID.html">GXLightID</a> light_mask, 26 <a href="../Enumerated_Types/GXDiffuseFn.html">GXDiffuseFn</a> diff_fn, 27 <a href="../Enumerated_Types/GXAttnFn.html">GXAttnFn</a> attn_fn ); 28</pre></dd></dl> 29 30<h2>Arguments</h2> 31<TABLE class="arguments" border="1" > 32 <tr> 33<TH>chan</TH> 34<TD>Color <a href="../Enumerated_Types/GXChannelID.html">channel</a>. Accepted values are:<BR> 35 <TABLE class="arguments" border="1" > 36 <tr> 37<TD bgcolor="#C0C0C0">Name</TD> 38<TD bgcolor="#C0C0C0">Target channel</TD> 39 </tr> 40 <tr> 41<TH>GX_COLOR0</TH> 42<TD>Color channel 0.</TD> 43 </tr> 44 <tr> 45<TH>GX_ALPHA0</TH> 46<TD>Alpha channel 0.</TD> 47 </tr> 48 <tr> 49<TH>GX_COLOR1</TH> 50<TD>Color channel 1.</TD> 51 </tr> 52 <tr> 53<TH>GX_ALPHA1</TH> 54<TD>Alpha channel 1.</TD> 55 </tr> 56 <tr> 57<TH>GX_COLOR0A0</TH> 58<TD>The same setting is simultaneously made for color channel 0 and alpha channel 0.</TD> 59 </tr> 60 <tr> 61<TH>GX_COLOR1A1</TH> 62<TD>The same setting is simultaneously made for color channel 1 and alpha channel 1.</TD> 63 </tr> 64 </TABLE> 65 </TD> 66 </tr> 67 <tr> 68<TH>enable</TH> 69<TD>If <SPAN class="argument">enable</SPAN> = <CODE>GX_ENABLE</CODE>, lighting for this color channel is enabled.</TD> 70 </tr> 71 <tr> 72<TH>amb_src</TH> 73<TD>Ambient color <a href="../Enumerated_Types/GXColorSrc.html">source</a>. Accepted values are:<BR> 74 <TABLE class="arguments" border="1" > 75 <tr> 76<TD bgcolor="#C0C0C0">Name</TD> 77<TD bgcolor="#C0C0C0">Source</TD> 78 </tr> 79 <tr> 80<TH>GX_SRC_REG</TH> 81<TD>Use the ambient color register.</TD> 82 </tr> 83 <tr> 84<TH>GX_SRC_VTX</TH> 85<TD>Use the vertex color.</TD> 86 </tr> 87 </TABLE> 88 </TD> 89 </tr> 90 <tr> 91<TH>mat_src</TH> 92<TD>Material color <A href="../Enumerated_Types/GXColorSrc.html">source</A>. Accepted values are:<BR> 93 <TABLE class="arguments" border="1" > 94 <tr> 95<TD bgcolor="#C0C0C0">Name</TD> 96<TD bgcolor="#C0C0C0">Source</TD> 97 </tr> 98 <tr> 99<TH>GX_SRC_REG</TH> 100<TD>Use the material color register.</TD> 101 </tr> 102 <tr> 103<TH>GX_SRC_VTX</TH> 104<TD>Use the vertex color.</TD> 105 </tr> 106 </TABLE> 107 </TD> 108 </tr> 109 <tr> 110<TH>light_mask</TH> 111<TD>The light used for this channel used by the light formula. This is the bitwise OR of <CODE>GX_LIGHT0, GX_LIGHT1, GX_LIGHT2, ... , GX_LIGHT7</CODE>.</TD> 112 </tr> 113 <tr> 114<TH>diff_fn</TH> 115<TD><a href="../Enumerated_Types/GXDiffuseFn.html">Diffusion function</a> for lighting. Accepted values are:<BR> 116 <TABLE class="arguments" border="1" > 117 <tr> 118<TD bgcolor="#C0C0C0">Name</TD> 119<TD bgcolor="#C0C0C0">Type of diffuse function</TD> 120 </tr> 121 <tr> 122<TH>GX_DF_NONE</TH> 123<TD>No diffuse function.</TD> 124 </tr> 125 <tr> 126<TH>GX_DF_CLAMP</TH> 127<TD>Clamp type diffuse function (for conventional use).</TD> 128 </tr> 129 <tr> 130<TH>GX_DF_SIGN</TH> 131<TD>Sign type diffuse function (for special use).</TD> 132 </tr> 133 </TABLE> 134 </TD> 135 </tr> 136 <tr> 137<TH>attn_fn</TH> 138<TD><a href="../Enumerated_Types/GXAttnFn.html">Attenuation function</a> for lighting. Accepted values are:<BR> 139 <TABLE class="arguments" border="1" > 140 <tr> 141<TD bgcolor="#C0C0C0">Name</TD> 142<TD bgcolor="#C0C0C0">Type of attenuation function</TD> 143 </tr> 144 <tr> 145<TH>GX_AF_NONE</TH> 146<TD>Consider the light to be a plain (unattenuated) point of light. Attenuation coefficients for each light object do not work under this setting.</TD> 147 </tr> 148 <tr> 149<TH>GX_AF_SPOT</TH> 150<TD>Angular attenuation and distance attenuation are applied to each light.</TD> 151 </tr> 152 <tr> 153<TH>GX_AF_SPEC</TH> 154<TD>The light is taken as a specular light.</TD> 155 </tr> 156 </TABLE> 157 </TD> 158 </tr> 159</TABLE> 160 161<h2>Return Values</h2> 162<p>None.</p> 163 164<H2>Description</H2> 165<P>This function sets the lighting controls for a color channel. Color channels can have one or more lights associated with them, set using <SPAN class="argument">light_mask</SPAN>. The <SPAN class="argument">diff_fn</SPAN> and <SPAN class="argument">attn_fn</SPAN> parameters control the lighting equation for all lights associated with this channel. The <SPAN class="argument">amb_src</SPAN> and <SPAN class="argument">mat_src</SPAN> can be used to select whether the input source colors come from register colors or vertex colors. When <SPAN class="argument">enable</SPAN> is set to <CODE>GX_FALSE</CODE> for the channel, the material color source (set by <SPAN class="argument">mat_src</SPAN>) is passed as the channel's output color. When the channel <SPAN class="argument">enable</SPAN> is <code>GX_TRUE</code>, the output color depends on the settings of the other controls (i.e., the lighting equation). <a href="../Management/GXInit.html"><code>GXInit</code></a> sets the <SPAN class="argument">enable</SPAN> for all channels to <code>GX_FALSE</code>. The <A href="GXSetChanCtrl.html"><CODE>GXSetChanCtrl</CODE></A> function only configures the lighting channel. To output the results of channel calculations, use the <A href="GXSetNumChans.html"><CODE>GXSetNumChans</CODE></A> function.</P> 166<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, effectively <CODE>GX_COLOR0A0</CODE>. The same is true for <CODE>GX_COLOR1</CODE> and <CODE>GX_ALPHA1</CODE> — effectively, 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> 167<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 either only <CODE>GX_VA_CLR0</CODE> or only <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> 168<P>When <SPAN class="argument">amb_src</SPAN> is set to <CODE>GX_SRC_REG</CODE>, the color set by the <A href="GXSetChanAmbColor.html"><CODE>GXSetChanAmbColor</CODE></A> function is used as the ambient color. When <SPAN class="argument">mat_src</SPAN> is <CODE>GX_SRC_REG</CODE>, the color set by the <A href="GXSetChanMatColor.html"><CODE>GXSetChanMatColor</CODE></A> function is used as the material color.</P> 169 170<H3>Example: Local Diffuse Spot Lighting</H3> 171<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 the 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, <SPAN class="argument">diff_fn</SPAN> is set to <CODE>GX_DF_CLAMP</CODE>. Since this is a spot light, <SPAN class="argument">attn_fn</SPAN> is set to <CODE>GX_AF_SPOT</CODE>. The type of spot light angle attenuation function is determined here by the light set by the <A href="GXInitLightSpot.html"><CODE>GXInitLightSpot</CODE></A> function. The distance attenuation function is set using the <A href="GXInitLightDistAttn.html"><CODE>GXInitLightDistAttn</CODE></A> function.</P> 172<dl><dd><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></dd></dl> 173 174<H3>Example: Specular Lighting</H3> 175<P>This example demonstrates how to set up the <CODE>GX_COLOR0</CODE> channel for specular lighting. The function <a href="GXInitSpecularDir.html"><code>GXInitSpecularDir</code></a> is used to set the 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 the <A href="GXInitLightShininess.html"><CODE>GXInitLightShininess</CODE></A> function to control how shiny the lighted material appears (set the attenuation parameters). The <SPAN class="argument">attn_fn</SPAN> argument is set to <CODE>GX_AF_SPEC</CODE>, enabling the specular computation.</P> 176<dl><dd><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></dd></dl> 177 178<H3>Example: Parallel Diffuse Lighting</H3> 179<P>Although the hardware doesn't support parallel diffuse lights, it is possible to obtain an "almost parallel" light by putting a light very far away from all objects to be lit. If the light's position is sufficiently distant from the object, all rays can be considered parallel.</P> 180<dl><dd><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></dd></dl> 181 182<H3>Using Both Diffuse and Specular Lighting</H3> 183<P>The channel controls determine which calculations, either local-diffuse or specular, are performed in a channel. The parameters for the light associated with the channel are normally configured with one of these sets of 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 the <A href="GXInitSpecularDir.html"><CODE>GXInitSpecularDir</CODE></A> function.</P> 184 185<H3>Example: Per-Vertex Lighting using Pre-Lighting</H3> 186<P>This example will add a pre-lit color (already computed by the CG tool) supplied as the per-vertex <CODE>GX_VA_CLR0</CODE> (see the <A href="../Geometry/GXSetVtxDesc.html"><CODE>GXSetVtxDesc</CODE></A> function) to the result of a diffuse local light. In this example we want to implement the equation:</P> 187<dl><dd><EM><CODE>lit_clr = pre_lit_clr * (amb_scale + diff_scale * other_atten * lit_color)</CODE></EM></dd></dl> 188<P>The ambient scale defines the minimum amount of pre-lit color when no lights are shining on an object. Because the sum of <EM>amb_scale</EM> and <EM>diff_scale</EM> must be equal to 1.0, when an object is in the brightest light, its vertex color is equivalent to pre-lit color.</P> 189<P>The material color is set to be the vertex color (pre-lit color). The ambient color register is set to be equivalent to <EM>amb_scale</EM>. The light color is scaled by <EM>diff_scale</EM>.</P> 190<dl><dd><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></dd></dl> 191<dl><dd><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></dd></dl> 192 193<H3>Example: Four Attenuations for Projected Lighting</H3> 194<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 <FONT color="009000">apparently</FONT> 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 texture environment (TEV) unit.</P> 195<dl><dd><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></dd></dl> 196 197<h2>See Also</h2> 198<p class="reference"> 199<a href="GXSetChanMatColor.html">GXSetChanMatColor</a>, <a href="GXSetChanAmbColor.html">GXSetChanAmbColor</a>, <a href="GXSetNumChans.html">GXSetNumChans</a> 200</p> 201 202<H2>Revision History</H2> 203<P> 2042006/03/01 Initial version.<br> 205</P> 206 207<hr><p>CONFIDENTIAL</p></body> 208</html>