gSPSetLightsM [Macro]

Function

gSPSetLightsM

Loads LightsM structure into the RSP

Syntax

#include <ultra64.h>        /* gbi.h */
gSPSetLightsM(Gfx *gdl, LightsM lites)
gsSPSetLightsM(         LightsM lites)

* Number of diffuse lights (integer 0~7) will be set for M.

Arguments

gdl

the display list pointer.

lites

LightsM structure to load into the RSP

Description

It loads LightsM structures for ambient and diffuse lights into the light buffer. The last character in the macro, indicated by M above, represents the number of diffuse lights to set. You specify proper macros from the 8 macros such as gSPSetLights0, gSPSetLights1, gSPSetLights2,..., and gSPSetLights7 to load a structure. For instance, if you use 3 diffuse lights, use gSPSetLights3 and the corresponding structure would be Lights3.

Once the lights are activated, they remain on until the next call to gSPSetLightsM. Whenever a new structure of LightM is activated, the old structure of LightM is overwritten.

In the LightsM structure, Ambient a is the ambient light structure, and Light l[M] is an array of M diffuse light structures. The LightsM structure can be set up by calling gdSPDefLights with the parameters defining the lights as inputs. The individual LightsM structures combine the color of the light with the color of the material.

For more information, please see the section 11.7.3 "Lighting by ambient light and diffuse light" in the N64 programmers' guide.

Note

To change the color of some or all of the lights after the light has been used one or more times, you should use the more efficient gSPLight macro instead of this macro. See gSPLight for more information about this.

Comment

The LightM 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 struct {
        unsigned char	col[3];	/* Ambient light value (RGBA) */
        char		pad1;
        unsigned char	colc[3];/* Copy of ambient light value (RGBA) */
        char		pad2;
} Ambient_t;
typedef union {
        Light_t		l;
        long long int	force_structure_alignment[2];
} Light;
typedef union {
        Ambient_t	l;
        long long int	force_structure_alignment[1];
} Ambient;
typedef struct {
        Ambient		a;	/* Ambient light */
        Light		l[M];	/* Diffuse light */
} LightsM;
* Number of diffuse lights (integer 0~7) will be set for M.

Example

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

See Also

gdSPDefLights, gSPLight, and gSPLightColor

Revision History

02/01/99 Completely rewritten.