gSPLight [Macro]

Function

gSPLight

Loads one Light structure to the RSP.

Syntax

#include <ultra64.h>        /* gbi.h */
gSPLight(Gfx *gdl, Light *l, s32 n)
gsSPLight(         Light *l, s32 n)

Arguments

gdl

the display list pointer.

l

the pointer to light structure.

n

the light number that is replaced (1~8)

Description

Loads one Light structure at the specified position in the light buffer. Use gSPNumLights to specify the number of lights to use in the lighting calculation. When gSPNumLights specifies N number of lights, the 1st to Nth lights are used as directional lights (color and direction), and N+1 light is used as the ambient light (color only).

The Light structure color is obtained by mixing the material color and the light color. This optimization improves the performance of the RSP geometry engine.

To change only the color of the light after the light has been set with gSPLight and used by gSPVertex, reset gSPLight, and re-execute gSPVertex. This method of changing the light color boosts performance efficiency. (The same method can be used to change the material color.) However, to change the light direction, you must not only set the light using gSPLight, but also use gSPNumLights to reset the number of lights (even if the number has not changed). For details, see Section 11.7.3 "Lighting With Ambient Light and Diffuse Light" in the N64 Programming

Note

To make the RSP geometry engine more efficient, two vertex lighting calculations are processed at a time. Therefore, the Light structure must have a copy of the diffuse light value. This optimization can be used for special effects.

For static light, it is more efficient to use gdSPDefLights together with gSPSetLightsM, rather than using gSPLight and gSPNumLights.

The Light structure is shown below.

typedef struct {
        unsigned char	col[3];	/* Diffuse light value (RGBA) */
        char		pad1;
        unsigned char	colc[3];/* Copy of diffuse light value (RGBA)  */
        char		pad2;
        signed char	dir[3];	/* Direction toward light source (normalized) */
        char		pad3;	/* Important:  Size of "dir" must not exceed 127 */
} Light_t;
typedef union {
        Light_t		l;
        long long int	force_structure_alignment[2];
} Light;

Example

Please refer to Section 11.7.3.6 "Note on Material Properties" in the N64 Programming Manual.

See Also

gdSPDefLights, gSPSetGeometryMode, gSPLightColor, gSPNumLights, gSPSetLightsM

Revision History

02/01/99 Entirely revised.