pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
NAME
pfNewLPoint, pfGetLPointClassType, pfGetNumLPoints, pfLPointSize,
pfGetLPointSize, pfLPointColor, pfGetLPointColor, pfLPointRot,
pfGetLPointRot, pfLPointShape, pfGetLPointShape, pfLPointFogScale,
pfGetLPointFogScale, pfLPointPos, pfGetLPointPos, pfGetLPointGSet - Set
and get pfLightPoint size, color, shape, rotation and position.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfLightPoint * pfNewLPoint(int num);
pfType * pfGetLPointClassType(void);
int pfGetNumLPoints(const pfLightPoint *lpoint);
void pfLPointSize(pfLightPoint *lpoint, float size);
float pfGetLPointSize(const pfLightPoint *lpoint);
void pfLPointColor(pfLightPoint *lpoint, int index,
pfVec4 clr);
void pfGetLPointColor(const pfLightPoint *lpoint, int index,
pfVec4 clr);
void pfLPointRot(pfLightPoint *lpoint, float azim,
float elev, float roll);
void pfGetLPointRot(const pfLightPoint *lpoint, float *azim,
float *elev, float *roll);
void pfLPointShape(pfLightPoint *lpoint, int dir, float henv,
float venv, float falloff);
void pfGetLPointShape(const pfLightPoint *lpoint, int *dir,
float *henv, float *venv, float *falloff);
void pfLPointFogScale(pfLightPoint *lpoint, float onsetScale,
float opaqueScale);
void pfGetLPointFogScale(const pfLightPoint *lpoint,
float *onsetScale, float *opaqueScale);
void pfLPointPos(pfLightPoint *lpoint, int index,
pfVec3 pos);
void pfGetLPointPos(const pfLightPoint *lpoint, int index,
pfVec3 pos);
Page 1
pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
pfGeoSet* pfGetLPointGSet(const pfLightPoint *lpoint);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfLightPoint is derived from the parent class
pfNode, so each of these member functions of class pfNode are also
directly usable with objects of class pfLightPoint. Casting an object of
class pfLightPoint to an object of class pfNode is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfNode.
pfGroup * pfGetParent(const pfNode *node, int i);
int pfGetNumParents(const pfNode *node);
void pfNodeBSphere(pfNode *node, pfSphere *bsph, int mode);
int pfGetNodeBSphere(pfNode *node, pfSphere *bsph);
pfNode* pfClone(pfNode *node, int mode);
pfNode* pfBufferClone(pfNode *node, int mode, pfBuffer *buf);
int pfFlatten(pfNode *node, int mode);
int pfNodeName(pfNode *node, const char *name);
const char * pfGetNodeName(const pfNode *node);
pfNode* pfFindNode(pfNode *node, const char *pathName,
pfType *type);
pfNode* pfLookupNode(const char *name, pfType* type);
int pfNodeIsectSegs(pfNode *node, pfSegSet *segSet,
pfHit **hits[]);
void pfNodeTravMask(pfNode *node, int which, uint mask,
int setMode, int bitOp);
uint pfGetNodeTravMask(const pfNode *node, int which);
void pfNodeTravFuncs(pfNode* node, int which,
pfNodeTravFuncType pre, pfNodeTravFuncType post);
void pfGetNodeTravFuncs(const pfNode* node, int which,
pfNodeTravFuncType *pre, pfNodeTravFuncType *post);
void pfNodeTravData(pfNode *node, int which, void *data);
void * pfGetNodeTravData(const pfNode *node, int which);
void pfNodeTravMode(pfNode* node, int which, int mode,
int val);
int pfGetNodeTravMode(const pfNode* node, int which,
int mode);
Since the class pfNode is itself derived from the parent class pfObject,
objects of class pfLightPoint can also be used with these functions
designed for objects 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);
Page 2
pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfLightPoint 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
lpoint identifies a pfLightPoint.
DESCRIPTION
pfLightPoint is now obsoleted in favor of the libpr primitive
pfLPointState. pfGetLPointGSet returns the underlying pfGeoSet of lpoint
from which the pfLPointState can be found:
gset = pfGetLPointGSet(lpoint);
gstate = pfGetGSetGState(gset);
lpstate = pfGetGStateAttr(gstate, PFSTATE_LPOINTSTATE);
A pfLightPoint is a pfNode that contains one or more light points. The
light point node is quite different from a pfLightSource; it is visible
as one or more self-illuminated small points but these points do not
illuminate surrounding objects. In contrast to this, a pfLightSource does
illuminate scene contents but is itself not a visible object. All the
light points in a pfLightPoint node share all their attributes except
point location and color.
pfNewLPoint creates and returns a handle to a pfLightPoint. Like other
pfNodes, pfLightPoints are always allocated from shared memory and can be
deleted using pfDelete. num specifies the maximum number of individual
light points the node may contain. The function pfGetNumLPoints returns
Page 3
pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
this maximum number of light points that the pfLightPoint node lpoint can
hold. This is the value set when the light point node was created using
pfNewLPoint and is the size of the internal position and color arrays
used to represent the light points.
pfGetLPointClassType returns the pfType* for the class pfLightPoint. The
pfType* returned by pfGetLPointClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfLightPoint.
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.
pfLPointSize sets the screen size of each point of light in lpoint. size
is specified in pixels and is used as the argument to pntsizef. Whenever
possible, antialiased points are used but the actual representation of a
light point depends on the hardware being used. See the pntsizef man
page for a description of available light point sizes on OpenGL hardware.
pfGetLPointSize returns the size of lpoint.
pfLPointColor sets the color of light point index in lpoint to clr. The
actual color displayed depends on light point direction, shape, position,
and fog. clr specifies red, green, blue and alpha in the range 0.0 to
1.0. A pfLightPoint is turned off with an alpha of 0.0 since it will be
rendered as completely transparent. pfGetLPointColor copies the indexth
color into clr.
pfLPointRot is used for directional lights. The direction of all light
points in lpoint is the positive Y axis, rotated about the X axis by elev
then rotated about the Z axis by azim. roll only affects the light
envelope as described below. The direction vector is rotated by any
transformations (see pfSCS, pfDCS) above lpoint in the hierarchy.
pfGetLPointRot copies lpoint's rotation into azim, elev, and roll.
pfLPointShape describes the intensity distribution of a light point about
its direction vector. dir is a symbolic token:
PFLP_OMNIDIRECTIONAL
lpoint will be drawn as omnidirectional light points. Light
distribution is equal in all directions. All other arguments
are ignored.
PFLP_UNIDIRECTIONAL
lpoint will be drawn as unidirectional point lights. Light
distribution is an elliptical cone centered about the light
direction vector.
PFLP_BIDIRECTIONAL
lpoint will be drawn as bidirectional light points. Light
distribution is two elliptical cones centered about the
positive and negative light direction vectors.
Page 4
pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
henv and venv are total angles (not half-angles) in degrees which specify
the horizontal and vertical envelopes about the direction vector. An
envelope is a symmetric angular spread in a specific plane about the
light direction vector. The default direction is along the positive Y
axis so the horizontal envelope is in the X plane and the vertical in the
Z plane. Both direction and envelopes are rotated by the pfLPointRot and
any inherited transformations. The default envelope angles are 360.0
degrees which is equivalent to an omnidirectional light.
When the vector from the eyepoint to the light position is outside a
light's envelope, the light point is not displayed. If within, the
intensity of the light point is computed based on the location of the eye
within the elliptical cone. Intensity ranges from 1.0 when the eye lies
on the light direction vector to 0.0 on the edge of the cone. falloff is
an exponent which modifies the intensity. A value of 0 indicates that
there is no falloff and values > 0 increase the falloff rate. The
default falloff is 4. As intensity decreases, the light point's
transparency increases.
pfGetLPointShape copies lpoint's shape parameters into dir, henv, venv,
and falloff.
In general, the real world intensity of emissive light points is much
greater than that of reflective surfaces. Consequently, when fog is
active, light points should be more visible through the fog.
pfLPointFogScale sets the fog range scale factors that affects all light
points in lpoint. onsetScale and opaqueScale multiply the onset and
opaque ranges (pfFogRange) of the currently active fog. Thus if the
scale factors are greater than 1.0, the light points will be more visible
through fog than reflective surfaces. The default fog scale factors are
both 4.0. pfGetLPointFogScale copies the fog scale factors of lpoint
into onsetScale and opaqueScale.
pfLPointPos sets the position of light point with index index to pos.
index is clamped to the range [0, num-1]. All positions are transformed
by any inherited transformations. The final position and orientation of
a light point i is transformed by R * T[index] * M where R is a rotation
matrix defined by pfLPointRot, T[i] is the position of light point i, and
M is the transformation inherited by lpoint from its hierarchy.
pfGetLPointPos copies the indexth position into pos.
NOTES
Light point processing in OpenGL Performer has been subsumed by the new
pfLPointState mechanism, which is both more powerful and more efficient.
Application developers are encouraged to transition to these new light
point facilities.
pfLightPoint nodes, unlike pfLPointState GeoSets, do not provide size or
intensity modulation based on distance to the viewer and the viewport
size. Also, directional lights are significantly more expensive to cull
than omnidirectional lights.
Page 5
pfLightPoint(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages
Falloff distribution is cosine(incidence angle) ^ falloff.
When sorting is enabled (see pfChanTravMode and PFCULL_SORT), light
points are drawn after opaque geometry unless the pfLightPoint node has a
pre-draw or post-draw callback (see pfNodeTravFuncs).
SEE ALSO
pfLookupNode, pfNode, pfLPointState
Page 6
