GXInitLightDistAttn

C Specification

#include <revolution/gx.h>

void GXInitLightDistAttn(
    GXLightObj*  lt_obj,
    f32          ref_distance,
    f32          ref_brightness,
    GXDistAttnFn dist_func );

Arguments

lt_obj pointer to a light object

ref_distance distance between the light and a reference point

ref_brightness brightness of the reference point0 < ref_brightness < 1

dist_func

the type of brightness reduction function
Accepted values are:

Name	Distance Attenuation Function Type
`GX_DA_OFF`	no attenuation
`GX_DA_GENTLE`	See the figure below.
`GX_DA_MEDIUM`
`GX_DA_STEEP`

Return Values

None.

Description

This function sets coefficients for distance attenuation in light objects. These can be also set using the GXInitLightAttn function. This function uses three easy-to-control parameters instead of the k0, k1 and k2 used in GXInitLightAttn.

This function can specify the brightness on an assumed reference point. The argument ref_distance is the distance between the light and the reference point. The argument ref_brightness specifies the ratio of the brightness at the reference point. The value for ref_distance should be greater than 0 In addition, the value for ref_brightness must be within 0 < ref_brightness < 1. If not, distance attenuation will not work.

The argument dist_func defines the type of brightness decrease over distance. The following graphs show curve shape of the decreasing functions given by acceptable values for dist_func. The value GX_DA_OFF turns distance attenuation feature off.


`GX_DA_GENTLE`	`GX_DA_MEDIUM`	`GX_DA_STEEP`

For more flexible control, use GXInitLightAttn and calculate the appropriate coefficients.

Be aware that this function sets parameters only for distance attenuation. Parameters for angular attenuation should be set using GXInitLightSpot or GXInitLightAttnA.

This function does not load any hardware registers directly. To load a light object into a hardware light, use GXLoadLightObjImm or GXLoadLightObjIndx.

Revision History

2006/03/01 Initial version.