guPosLight [Function]

Function

guPosLight

Creates a Light structure for a positional light

Syntax

#include <ultra64.h>        /* gu.h */
void guPosLight(
        PositionalLight *pl,
        Light *l,
        float xOb,
        float yOb,
        float zOb);

Arguments

pl

Pointer to PositionalLight structure

l

Pointer to the resulting Light structure

xOb

x-coordinate in center of object to be lit (absolute coordinate)

yOb

y-coordinate in center of object to be lit (absolute coordinate)

zOb

z-coordinate in center of object to be lit (absolute coordinate)

Returned value

None

Description

Gets the PositionalLight structure (the parameters of which have been set by the user), and returns it to the Light structure indicated by l. The light direction and intensity are determined by the positional relationship (distance and direction) between the light and the object being lit.

This function returns a Light structure for one positional light, and does not calculate the value for a specular highlight. Use the guPosLightHilite to return Light structures for two positional lights and to return the Hilite structure and the LookAt structure for the rendering of specular highlights.

Note

Use this function to create the effect of an attenuating positional light. The function works well with small lighted objects (especially moving objects), but not with large objects (like terrain and walls). If there are numerous small moving objects, call this function for every moving object and use a separate Light structure for each.

Comment

The PositionalLight structure looks like this:

typedef struct {
     float  col[3];         /* Color (and intensity) */
     float  pos[3];         /* Position (absolute coordinates)*/
     float  a1, a2;         /* Attenuation rate */
     /* Actual color = col/(a1* distance + a2) */
} PositionalLight;

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

See also

gdSPDefLights, gSPLightColor, gSPNumLights, gSPSetLightsM, and guPosLightHilite

Revision history

03/01/99 Completely revised.