pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)NAME
pfNewLight, pfGetLightClassType, pfLightColor, pfGetLightColor,
pfLightAtten, pfGetLightAtten, pfLightPos, pfGetLightPos, pfSpotLightDir,
pfGetSpotLightDir, pfSpotLightCone, pfGetSpotLightCone, pfLightOn,
pfLightOff, pfIsLightOn, pfLightAmbient, pfGetLightAmbient,
pfGetCurLights - Create, modify and query lights
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfLight * pfNewLight(void *arena);
pfType * pfGetLightClassType(void);
void pfLightColor(pfLight *lt, int which, float r, float g,
float b);
void pfGetLightColor(const pfLight *lt, int which, float *r,
float *g, float *b);
void pfLightAtten(pfLight* light, float constant, float linear,
float quadratic);
void pfGetLightAtten(pfLight* light, float *constant,
float *linear, float *quadratic);
void pfLightPos(pfLight *lt, float x, float y, float z, float w);
void pfGetLightPos(const pfLight *lt, float *x, float *y,
float *z, float *w);
void pfSpotLightDir(pfLight *lt, float x, float y, float z);
void pfGetSpotLightDir(const pfLight *lt, float *x, float *y,
float *z);
void pfSpotLightCone(pfLight *lt, float exponent, float spread);
void pfGetSpotLightCone(const pfLight *lt, float *exponent,
float *spread);
void pfLightOn(pfLight *lt);
void pfLightOff(pfLight *lt);
int pfIsLightOn(pfLight *lt);
void pfLightAmbient(pfLight *lt, float r, float g, float b);
void pfGetLightAmbient(const pfLight *lt, float *r, float *g,
float *b);
Page 1
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
int pfGetCurLights(pfLight *lights[PF_MAX_LIGHTS]);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfLight is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfLight. Casting an object of
class pfLight to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfLight can also be used with these functions
designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
lt identifies a pfLight.
DESCRIPTION
A pfLight is a light source that illuminates scene geometry, generating
realistic shading effects. A pfLight cannot itself be seen but its
effect is visible through its illuminative effect on scene geometry. See
the OpenGL glLight(3g) man page for more details on lights and individual
lighting parameters.
Page 2
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
pfNewLight creates and returns a handle to a pfLight. arena specifies a
malloc arena out of which the pfLight is allocated or NULL for allocation
off the process heap. A NULL pointer is returned to indicate failure.
pfLights can be deleted with pfDelete.
pfGetLightClassType returns the pfType* for the class pfLight. The
pfType* returned by pfGetLightClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfLight. Because
OpenGL Performer allows subclassing of built-in types, when decisions are
made based on the type of an object, it is usually better to use
pfIsOfType to test if an object is of a type derived from a Performer
type rather than to test for strict equality of the pfType*'s.
pfLightColor accepts a token for the color attribute to set (-
PFLT_AMBIENT, PFLT_DIFFUSE, or PFLT_SPECULAR) and three floating point
values (r, g, and b) in the range [0.0 .. 1.0] defining values for the
red, green, and blue components of the indicated attribute of the light
source. By default, the r, g, and b values are all 1.0. pfGetLightColor
copies the requested light color values for the given light source and
color attribute into the parameters r, g, and b.
pfLightAtten sets the attenuation parameters of light. The light
intensity is scaled at each vertex by:
1.0 / (constant + linear * dist + quadratic * dist^2)
where 'dist' is the distance from the light position to the lit vertex.
Note that 'dist' is 1.0 for infinite light sources. The default
attenuation values are constant = 1.0, linear = 0.0, quadratic = 0.0,
i.e., light attenuation is disabled. pfGetLightAtten returns the
attenuation parameters of light in constant, linear, and quadratic. See
the pfLModelAtten man page for more information.
pfSpotLightDir specifies the direction in which a spot light source emits
its light. It receives three floating point values, x, y, and z,
specifying the x, y, and z direction vectors. pfGetSpotLightDir copies
the x, y, and z direction vectors into the parameters x, y, and z.
pfSpotLightCone specifies the exponent and spread of the spot light cone,
and receives two floating point values, f1 and f2, to set the exponent
for the intensity, and the spread of the cone, respectively.
pfGetSpotLightCone copies the current exponent and spread of the cone
into the parameters f1 and f2.
pfLightPos receives four floating point values to set the x, y, z, and w,
coordinates for the position of the light source. Typically, the
homogeneous coordinate w is 0.0 to indicate that the light position is
infinitely far from the origin in the direction (x, y, z). Local light
sources are specified by a non-zero value for w and usually incur a
performance penalty. pfGetLightPos copies the x, y, z and w coordinates
of the light source into the parameters x, y, z and w, respectively.
Page 3
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
pfLightOn enables light so that its illumination will influence scene
geometry if lighting is properly enabled (See below). The maximum number
of active lights is determined by the particular graphics library
implementation but typically is at least eight.
Modifications made to light do not have effect until pfLightOn is called.
For geometry to be illuminated, the following must be true:
1. Lighting must be enabled: pfEnable(PFEN_LIGHTING)
2. A pfLightModel must be applied: pfApplyLModel
3. A pfMaterial must be applied: pfApplyMtl
4. One or more pfLights must be on: pfLightOn
5. Illuminated geometry must have normals: pfGSetAttr,
PFGS_NORMAL3
pfLightOn also affects the position of the light in the scene. When
called, the current graphics library ModelView matrix transforms the
position of the light set by pfLightPos. Calling pfLightOn when specific
transformations are on the stack will result in different light
behaviors, which are outlined in the following paragraphs.
To simulate a light attached to the viewer (simulating a miner's head-
mounted lamp) call pfLightOn only once with an identity matrix on the
stack:
pfLightPos(viewerLight, 0.0, 0.0, 1.0, 0.0);
/*
* viewerLight always points in direction of view, i.e. - down -Z axis.
*/
pfPushIdentMatrix();
pfLightOn(viewerLight);
pfPopMatrix();
/* Draw scene */
To simulate a light "attached" to the world (at a fixed location in
world-space coordinates like the sun or moon) call pfLightOn every frame
with only the viewing transformation on the stack:
pfLightPos(sunLight, 0.0, 1.0, 0.0, 0.0);
pfPushIdentMatrix();
/* viewer is at origin looking +30 degrees 'up' */
Page 4
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
pfRotate(PF_X, -30.0f);
/* sunLight always points straight down on scene */
pfLightOn(sunLight);
/* Draw scene */
pfPopMatrix();
To simulate a light attached to an object like the headlights of a car,
call pfLightOn every frame with the combined viewing and modeling
transformation on the stack:
pfLightPos(headLight, 2.0, 0.0, 0.0, 1.0);
pfPushIdentMatrix();
/* Viewer is at origin looking +30 degrees 'up' */
pfRotate(PF_X, -30.0f);
/* Car is at (100.0f, 100.0f, 100.0f) */
pfTranslate(100.0f, 100.0f, 100.0f);
/*
* carLight is a point light source at the front of the car
* provided the car is modeled such that the headlights are
* 2 units from the center of the car in the +X direction.
*/
pfLightOn(headLight);
/* Draw scene */
pfPopMatrix();
pfLightOff disables light so that it does not contribute to scene
illumination.
pfIsLightOn returns a boolean indicating whether light is on or not.
pfGetCurLights returns the number of currently active lights, n. The
array lights is filled with n pointers to the pfLight structures of the
light sources that are currently ``on''.
The light source state element is identified by the PFSTATE_LIGHT token.
Use this token with pfGStateAttr to set the light array of a pfGeoState
and with pfOverride to override subsequent light source changes:
pfLightAmbient is provided for compatibility with previous versions of
Page 5
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
OpenGL Performer. It accepts three floating point values in the range
from 0.0 through 1.0 to set the r, g, and b, values for the red, green,
and blue components of the ambient light. By default, lights have
ambient red, green, and blue values of 0.0. pfGetLightAmbient copies the
ambient light values for the given light source into the parameters r, g,
and b. For future compatibility, calls to:
pfLightAmbient(lt, r, g, b);
should be replaced by
pfLightColor(lt, PFLT_AMBIENT, r, g, b);
and calls to:
pfGetLightAmbient(lt, &r, &g, &b);
should be replaced by
pfGetLightColor(lt, PFLT_AMBIENT, &r, &g, &b);
EXAMPLES
Example 1:
pfLight *lightArray[PF_MAX_LIGHTS];
for (i=0; i<PF_MAX_LIGHTS; i++)
lightArray[i] = NULL;
lightArray[0] = light0;
lightArray[1] = light1;
/* Set up specially-lit pfGeoState */
pfGStateMode(gstate, PFSTATE_ENLIGHTING, PF_ON);
pfGStateAttr(gstate, PFSTATE_LIGHT, lightArray);
/* Attach gstate to gset */
pfGSetGState(gset, gstate);
/* Set normal array. 'gset' is non-indexed */
pfGSetAttr(gset, PFGS_NORMAL3, PFGS_PER_VERTEX, norms, NULL);
/* Draw specially-lit gset */
pfDrawGSet(gset);
Page 6
pfLight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfLight(3pf)
Example 2:
pfLightOn(light0);
pfLightOn(light1);
/*
* Override so that all geometry is lit with light0 and light1
* if lighting is otherwise properly enabled.
*/
pfOverride(PFSTATE_LIGHT, PF_ON);
The array of lights passed to pfGStateAttr should be PF_MAX_LIGHTS long
and should contain references to pfLights that are to be used by the
pfGeoState. Empty array elements should be set to NULL.
pfLightOn and pfLightOff are display-listable commands. If a pfDispList
has been opened by pfOpenDList, pfLightOn and pfLightOff will not have
immediate effect but will be captured by the pfDispList and will only
have effect when that pfDispList is later drawn with pfDrawDList.
NOTES
Local lighting results in improper shading of flat-shaded triangle and
line strips (PFGS_FLAT_TRISTRIPS, PFGS_LINE_TRISTRIPS) which often
manifests itself as "faceting" of planar polygons. The only solution is
either to use infinite lighting or not use FLAT primitives. Note that
when using the OpenGL Performer triangle meshing routine, pfdMeshGSet,
the construction of non-FLAT strips is easily enforced with
pfdMesherMode(PFDMESH_LOCAL_LIGHTING, 1).
SEE ALSO
pfDelete, pfDispList, pfGeoState, pfLightModel, pfMaterial, pfObject,
pfOverride, pfState, lmbind, lmcolor, lmdef, glLight, glColorMaterial
Page 7
