GXInitLightAttn

Syntax

#include <revolution/gx.h>

void GXInitLightAttn(
    GXLightObj* lt_obj,
    f32         a0,
    f32         a1,
    f32         a2,
    f32         k0,
    f32         k1,
    f32         k2 );

Arguments

Return Values

None.

Description

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

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

where aattn is the cosine of the angle between the light direction and the vector from the light position to the vertex. Likewise, d is the distance from the light position to the vertex when the channel attenuation function is GX_AF_SPOT. The light color will be multiplied by the atten coefficient 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.

The GXInitLightSpot function is a convenient way to set the angle attenuation coefficients based on several spotlight types. The GXInitLightDistAttn function is a handy way to set the distance attenuation coefficients using one of several common attenuation functions.

When the channel attenuation function is set to GX_AF_SPEC, the aattn and d arguments are equal to the dot product of the visual space vertex normal and the half-angle vector set by the GXInitSpecularDir function.

The GXInitLightShininess macro can be easily used to set attenuation parameters for specular lights.

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.

See Also

GXInitLightAttnA, GXInitLightAttnK, GXInitLightSpot, GXInitLightDistAttn, GXInitLightShininess, GXSetChanCtrl, GXLightObj Initialization Flow

Revision History

2006/03/01 Initial version.

CONFIDENTIAL