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>GXInitLightDistAttn</TITLE>
9</HEAD>
10<BODY>
11<H1 align="left">GXInitLightDistAttn</H1>
12<H2>C Specification</H2>
13<DL>
14  <DD>
15<PRE><CODE>#include &lt;revolution/gx.h&gt;</CODE></PRE>
16  <DD>
17<PRE><CODE>void GXInitLightDistAttn(
18<A href="../Structures/GXLightObj.html">GXLightObj</A>* lt_obj,
19f32          ref_distance,
20f32          ref_brightness,
21<A href="../Enumerated_Types/GXDistAttnFn.html">GXDistAttnFn</A> dist_func );</CODE></PRE>
22  <DT>&nbsp;
23</DL>
24<H2>Arguments</H2>
25<TABLE border="1" cellpadding="3" cellspacing="0.1">
26  <TBODY>
27    <TR>
28<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>lt_obj</CODE></STRONG></EM></TD>
29<TD width="520">pointer to a light object</TD>
30    </TR>
31    <TR>
32<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>ref_distance</CODE></STRONG></EM></TD>
33<TD width="520">distance between the light and a reference point</TD>
34    </TR>
35    <TR>
36<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>ref_brightness</CODE></STRONG></EM></TD>
37<TD width="520">brightness of the reference point0 &lt; <CODE>ref_brightness</CODE> &lt; 1</TD>
38    </TR>
39    <TR>
40<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>dist_func</CODE></STRONG></EM></TD>
41<TD width="520">the type of brightness reduction function <BR>Accepted values are:<BR>
42      <TABLE width="500" border="1" cellspacing="0.1">
43        <TBODY>
44          <TR>
45<TD width="150" bgcolor="#C0C0C0">Name</TD>
46<TD width="350" bgcolor="#C0C0C0">Distance Attenuation Function Type</TD>
47          </TR>
48          <TR>
49<TD width="150"><CODE>GX_DA_OFF</CODE></TD>
50<TD width="350">no attenuation</TD>
51          </TR>
52          <TR>
53<TD width="150"><CODE>GX_DA_GENTLE</CODE></TD>
54<TD rowspan="3" width="350">See the figure below.</TD>
55          </TR>
56          <TR>
57<TD width="150"><CODE>GX_DA_MEDIUM</CODE></TD>
58          </TR>
59          <TR>
60<TD width="150"><CODE>GX_DA_STEEP</CODE></TD>
61          </TR>
62        </TBODY>
63      </TABLE>
64      </TD>
65    </TR>
66  </TBODY>
67</TABLE>
68<H2>Return Values</H2>
69<P>None.</P>
70<H2>Description</H2>
71<P>This function sets coefficients for distance attenuation in light objects. These can be also set using the <code><a href="GXInitLightAttn.html">GXInitLightAttn</a></code> function. This function uses three easy-to-control parameters instead of the <code>k0</code>, <code>k1</code> and <code>k2</code> used in <code><a href="GXInitLightAttn.html">GXInitLightAttn</a></code>.</P>
72<P>This function can specify the brightness on an assumed reference point. The argument <CODE>ref_distance</CODE> is the distance between the light and the reference point. The argument <CODE>ref_brightness</CODE> specifies the ratio of the brightness at the reference point. The value for <em><strong>ref_distance </strong></em>should be greater than 0 In addition, the value for <CODE>ref_brightness</CODE> must be within 0 &lt; <CODE>ref_brightness</CODE> &lt; 1. If not, distance attenuation will not work.</P>
73<P>The argument <CODE>dist_func</CODE> defines the type of brightness decrease over distance. The following graphs show curve shape of the decreasing functions given by acceptable values for <em><strong>dist_func</strong></em>. The value <code>GX_DA_OFF</code> turns distance attenuation feature off.</P>
74<DIV align="center">
75<CENTER>
76<TABLE border="1" width="128" cellpadding="0">
77  <TBODY>
78    <TR>
79<TD><IMG src="DistFn1.gif" alt="DistFn1.gif (1605 bytes)" width="128" height="128"></TD>
80<TD><IMG src="DistFn2.gif" alt="DistFn2.gif (1611 bytes)" width="128" height="128"></TD>
81<TD><IMG src="DistFn3.gif" alt="DistFn3.gif (1600 bytes)" width="128" height="128"></TD>
82    </TR>
83    <TR>
84      <TD>
85<P align="center"><CODE>GX_DA_GENTLE</CODE></P>
86      </TD>
87      <TD>
88<P align="center"><CODE>GX_DA_MEDIUM</CODE></P>
89      </TD>
90      <TD>
91<P align="center"><CODE>GX_DA_STEEP</CODE></P>
92      </TD>
93    </TR>
94  </TBODY>
95</TABLE>
96</CENTER>
97</DIV>
98<P>For more flexible control, use <code><a href="GXInitLightAttn.html">GXInitLightAttn</a></code> and calculate the appropriate coefficients.</P>
99<P>Be aware that this function sets parameters only for distance attenuation. Parameters for angular attenuation should be set using <code><a href="GXInitLightSpot.html">GXInitLightSpot</a></code> or <a href="GXInitLightAttnA.html"><code>GXInitLightAttnA</code></a>.</P>
100<P>This function does not load any hardware registers directly.&nbsp;To load a light object into a hardware light, use <a href="GXLoadLightObjImm.html"><code>GXLoadLightObjImm</code></a> or <a href="GXLoadLightObjIndx.html"><code>GXLoadLightObjIndx</code></a>.</P>
101<H2>See Also</H2>
102<P><code><a href="GXInitLightAttn.html">GXInitLightAttn</a></code><br> <code><a href="GXGetLightAttnA.html">GXInitLightAttnA</a><br> <a href="GXInitLightAttnK.html">GXInitLightAttnK</a><br> <a href="GXInitLightSpot.html">GXInitLightSpot</a></code></P>
103<P><A href="GXLightObjInitFlow.html"><CODE>GXLightObj</CODE> Initialization Flow</A></P>
104<H2>Revision History</H2>
105<P>03/01/2006 Initial version.</P>
106</BODY>
107</HTML>