GXInitLightAttnA

Syntax

#include <revolution/gx.h>

void GXInitLightAttnA(
    GXLightObj* lt_obj,
    f32         a0,
    f32         a1,
    f32         a2 );

Arguments

lt_obj	Pointer to a light object.
a0	Angular attenuation coefficient.
a1	Angular attenuation coefficient.
a2	Angular attenuation coefficient.

Return Values

None.

Description

This function sets coefficients used in the lighting attenuation calculation in a given light object. The application must allocate memory for the light object. The parameters a0, a1 and a2 are used for angular (spotlight) attenuation. The attenuation function is:

atten = clamp0( a2 * cos(theta)^2 + a1 * cos(theta) + a0 )
k2 * d^2 + k1 * d + k0

Here cos(theta) is the cosine of the angle between the normal vector of the light and the vector from the light's position to the vertex. d is the distance from the light position to the vertex. The k0, k1 and k2 coefficients can be set using the GXInitLightAttnK function. You can set both the a0, a1, a2 and k0, k1, k2 coefficients with the GXInitLightAttn function. The light color will be multiplied by the atten factor when the attenuation function for the color channel referencing this light is set to GX_AF_SPOT (see the GXSetChanCtrl function).

All coefficients are represented with a 20-bit floating point format (1-bit sign, 8-bit exponent, and 11-bit significand) in the hardware, as for other arguments associated with vertex lighting. Be aware of possible rounding errors as a result.

Be aware that this function does not load any hardware registers directly. To load a light object into a hardware light, use the GXLoadLightObjImm or GXLoadLightObjIndx function.

The GXInitLightSpot function can conveniently be used to set the angle attenuation coefficients based on several spotlight types. The GXInitLightDistAttn function can be used to set the distance attenuation coefficients using one of several common attenuation functions.

Revision History

2006/03/01 Initial version.