guPosLightHilite [Function]

Function

guPosLightHilite

Creates Light structures for positional lights and also sets the LookAt/Hilite structures

Syntax

#include <ultra64.h>        /* gu.h */
void guPosLightHilite(
        PositionalLight *pl1,
        PositionalLight *pl2,
        Light *l1,
        Light *l2,
        LookAt *l,
        Hilite *h,
        float xEye,
        float yEye,
        float zEye,
        float xOb,
        float yOb,
        float zOb,
        float xUp,
        float yUp,
        float zUp,
        int twidth,
        int theight);

Arguments

pl1

Pointer to first PositionalLight structure

pl2

Pointer to second PositionalLight structure

l1

Pointer to first Light structure resulting from calculation

l2

Pointer to second Light structure resulting from calculation

l

Pointer to LookAt structure resulting from calculation

h

Pointer to Hilite structure resulting from calculation

xEye

x-coordinate of viewpoint

yEye

y-coordinate of viewpoint

zEye

z-coordinate of viewpoint

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)

xUp

x component of upward vector

yUp

y component of upward vector

zUp

z component of upward vector

twidth

Width of texture for specular highlight

theight

Height of texture for specular highlight

Returned value

None

Description

Gets the PositionalLight structures (the parameters of which have been set by the user), and returns them to the Light structures indicated by l1, l2. 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 Light structures for two positional lights, and sets the x,y screen coordinate directions in the LookAt structure in order to render specular highlights. It also sets the texture offsets used for the rendering of two specular highlights in the Hilite structure. To return a Light structure for just one positional light without calculating values for specular highlights, you can use the guPosLight function.

To learn more about specular highlighting, see Section 11.7.4 "Specular Highlights" in the N64 Programming Manual.

Note

Use this function to create the effect of attenuating positional lights. 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. Note that both twidth and theight must be powers of 2.

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;

The LookAt structure looks like this:

typedef struct {
     Light  l[2];
} LookAt;

The Hilite structure looks like this:

typedef struct {
     int       x1, y1, x2, y2; /* Texture offsets for highlight */
} Hilite_t;
typedef union {
     Hilite_t  h;
     long int  force_structure_alignment[4];
} Hilite;

See also

gdSPDefLights, gSPLightColor, gSPNumLights, gSPSetLightsM, guLookAtHilite, and guPosLight

Revision history

03/01/99 Completely rewritten.