pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)NAME
pfLight, pfGetCurLights - Create, modify and query lights
FUNCTION SPECIFICATION
#include <Performer/pr/pfLight.h>
pfLight::pfLight()
static pfType * pfLight::getClassType(void);
void pfLight::setColor(int which, float r, float g,
float b);
void pfLight::getColor(int which, float *r, float *g,
float *b);
void pfLight::setAtten(float constant, float linear,
float quadratic);
void pfLight::getAtten(float *constant, float *linear,
float *quadratic);
void pfLight::setPos(float x, float y, float z, float w);
void pfLight::getPos(float *x, float *y, float *z,
float *w);
void pfLight::setSpotDir(float x, float y, float z);
void pfLight::getSpotDir(float *x, float *y, float *z);
void pfLight::setSpotCone(float exponent, float spread);
void pfLight::getSpotCone(float *exponent, float *spread);
void pfLight::on(void);
void pfLight::off(void);
int pfLight::isOn(void);
void pfLight::setAmbient(float r, float g, float b);
void pfLight::getAmbient(float *r, float *g, float *b);
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. This is also true for
ancestor classes of class pfObject.
Page 1
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
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.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
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.
new(arena) allocates a pfLight from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfLight from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfLights cannot be created statically, automatically on the stack or in
arrays. pfLights should be deleted with pfDelete rather than the delete
operator.
pfLight::getClassType returns the pfType* for the class pfLight. The
pfType* returned by pfLight::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
Page 2
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
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 the member function isOfType 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.
pfLight::setColor 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.
pfLight::getColor copies the requested light color values for the given
light source and color attribute into the parameters r, g, and b.
pfLight::setAtten sets the attenuation parameters of the pfLight. 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. pfLight::getAtten returns the
attenuation parameters of the pfLight in constant, linear, and quadratic.
See the pfLightModel::setAtten man page for more information.
pfLight::setSpotDir 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. pfLight::getSpotDir copies
the x, y, and z direction vectors into the parameters x, y, and z.
pfLight::setSpotCone 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.
pfLight::getSpotCone copies the current exponent and spread of the cone
into the parameters f1 and f2.
pfLight::setPos 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. pfLight::getPos copies the x, y, z and w
coordinates of the light source into the parameters x, y, z and w,
respectively.
pfLight::on enables the pfLight 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 a pfLight do not have effect until pfLight::on is
Page 3
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
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: pfLightModel::apply
3. A pfMaterial must be applied: pfMaterial::apply
4. One or more pfLights must be on: pfLight::on
5. Illuminated geometry must have normals: pfGeoSet::setAttr,
PFGS_NORMAL3
pfLight::on 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 pfLight::setPos. Calling pfLight::on 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:
viewerLight->setPos(0.0, 0.0, 1.0, 0.0);
/*
* viewerLight always points in direction of view, i.e. - down -Z axis.
*/
pfPushIdentMatrix();
viewerLight->on();
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:
sunLight->setPos(0.0, 1.0, 0.0, 0.0);
pfPushIdentMatrix();
/* viewer is at origin looking +30 degrees 'up' */
pfRotate(PF_X, -30.0f);
/* sunLight always points straight down on scene */
sunLight->on();
Page 4
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
/* 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:
headLight->setPos(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.
*/
headLight->on();
/* Draw scene */
pfPopMatrix();
pfLight::off disables the pfLight so that it does not contribute to scene
illumination.
pfLight::isOn returns a boolean indicating whether the pfLight 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 pfGeoState::setAttr to set the light array of a
pfGeoState and with pfOverride to override subsequent light source
changes:
pfLight::setAmbient is provided for compatibility with previous versions
of 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
Page 5
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
ambient red, green, and blue values of 0.0. pfLight::getAmbient copies
the ambient light values for the given light source into the parameters
r, g, and b. For future compatibility, calls to:
lt->setAmbient(r, g, b);
should be replaced by
lt->setColor(PFLT_AMBIENT, r, g, b);
and calls to:
lt->getAmbient(&r, &g, &b);
should be replaced by
lt->getColor(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 */
gstate->setMode(PFSTATE_ENLIGHTING, PF_ON);
gstate->setAttr(PFSTATE_LIGHT, lightArray);
/* Attach gstate to gset */
gset->setGState(gstate);
/* Set normal array. 'gset' is non-indexed */
gset->setAttr(PFGS_NORMAL3, PFGS_PER_VERTEX, norms, NULL);
/* Draw specially-lit gset */
gset->draw();
Example 2:
Page 6
pfLight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfLight(3pf)
light0->on();
light1->on();
/*
* 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 pfGeoState::setAttr 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.
pfLight::on and pfLight::off are display-listable commands. If a
pfDispList has been opened by pfDispList::open, pfLight::on and
pfLight::off will not have immediate effect but will be captured by the
pfDispList and will only have effect when that pfDispList is later drawn
with pfDispList::draw.
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
