.TH guPosLight 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
guPosLight, guPosLightHilite \- simulate a positional light source.
.SH SYNOPSIS
.nf
\f3#include <gu.h>

void guPosLight(PositionalLight *pl, 
                Light *l, 
                float xOb, float yOb, float zOb);

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);

typedef struct {
        float   col[3];
        float   pos[3];
        float   a1, a2;
} PositionalLight

\fP
.fi
.SH PARAMETERS
.TP 10
.I pl,pl1,pl1
The description of the positional light to use (input to the function).
.TP
.I l,l1,l2
The light structure to create (output of the function). 
.TP
.I xOB, yOB, zOB
The coordinates of the center of the object to be lit (in world coordinates).
.TP
.I l
Pointer to the LookAt struct (output of the function).  See
.B guLookAtHilite (3P).
.TP
.I h
Pointer to the Hilite struct  (output of the function).  See
.B guLookAtHilite (3P).
.TP
.I xEye, yEye, zEye
The position of the eye (same as used in the
.B guLookAt (3P)
function.
.TP
.I xUp, yUp, zUp
The up vector (same as used in the
.B guLookAt (3P)
function.
.TP
.I twidth, theight
The widht and height of the texture map which will be used for 
drawing the specular highlight.
.TP
.I col
The color (and intensity) of the positional light.
.TP
.I pos
The positon of the positional light (in world coordinates).
.TP
.I a1, a2
The attenuation.  The light intensity on the object will be: col/(a1*dist + a2)


\fP
.fi
.SH DESCRIPTION
.B guPosLight
and 
.B guPosLightHilite
take a 
.B PositionalLight
structure (which you define) and creates a light structure.  The light
direction and intensity depend on the distance and direction from the
light to the object being lit.  These functions are useful for creating 
the effect of a positional light with attenuation.  It works well for lighting 
small objects in a scene (especially moving objects), but it does not work 
very well for lighting 
large objects such as terrains, walls, or ground planes.
To use this function with multiple moving objects, call the function several
times: once for each object.  
Then use the various different light structures to light each object
respectively.
.PP
The 
.B guPosLightHilite
function calculates a light structure for 2 positional lights and their hilite
and lookat value for rendering specular highlights.
.PP
The 
.B guPosLight
function calculates a light structure for a single positional light without
calculating specular hilite related values.  
\fP
.fi
.SH SEE ALSO
.I gSPSetLights
(3P),
.I gdSPDefLights
(3P),
.I gSPNumLights
(3P),
.I gSPLightColor
(3P)