GXInitLightAttnK

C Specification

#include <revolution/gx.h>

void GXInitLightAttnK(
GXLightObj* lt_obj,
f32         k0,
f32         k1,
f32         k2 );

Arguments

`lt_obj`	pointer to a light object
`k0`	distance attenuation coefficient
`k1`	distance attenuation coefficient
`k2`	distance 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 coefficients k0, k1 and k2 are used for distance 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 coefficients a0, a1 and a2 can be set with GXInitLightAttnA. Both the a0, a1 and a2 and the k0, k1 and k2 coefficients can be set simultaneously using 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 GXSetChanCtrl).

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 GXLoadLightObjImm or GXLoadLightObjIndx.

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

Revision History