pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfLPointState, pfGetCurLPState - Set and get pfLPointState size,
transparency, directionality, shape, and fog attributes.
FUNCTION SPECIFICATION
#include <Performer/pr/pfLPointState.h>
pfLPointState::pfLPointState()
static pfType * pfLPointState::getClassType(void);
void pfLPointState::setMode(int mode, int val);
int pfLPointState::getMode(int mode);
void pfLPointState::setVal(int attr, float val);
float pfLPointState::getVal(int attr);
void pfLPointState::setShape(float horiz, float vert,
float roll, float falloff, float ambient);
void pfLPointState::getShape(float *horiz, float *vert,
float *roll, float *falloff, float *ambient);
void pfLPointState::setBackColor(float r, float g, float b,
float a);
void pfLPointState::getBackColor(float *r, float *g,
float *b, float *a);
void pfLPointState::apply(void);
void pfLPointState::makeRangeTex(pfTexture *tex, int size,
pfFog* fog);
void pfLPointState::makeShapeTex(pfTexture *tex, int size);
void -
pfLPointState::setRasterFunc(pfRasterFuncType rasterCallback,
void *rasterData);
void -
pfLPointState::getRasterFunc(pfRasterFuncType *rasterCallback,
void **rasterData);
void -
pfLPointState::setCalligFunc(pfCalligFuncType calligCallback,
void *calligData);
Page 1
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void -
pfLPointState::getCalligFunc(pfCalligFuncType *calligCallback,
void **calligData);
pfLPointState* pfGetCurLPState(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfLPointState is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfLPointState. This is also true
for ancestor classes of class pfObject.
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 pfLPointState 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 pfLPointState is a libpr data structure which, in conjunction with a
pfGeoSet of type PFGS_POINTS, supports a sophisticated light point
primitive type. Examples of light points are stars, beacons, strobes,
runway edge and end illumination, taxiway lights, visual approach slope
Page 2
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
indicators (VASI), precision approach path indicators (PAPI), and street
lights when viewed from a great distance.
Light points should not be confused with light sources, such as a
pfLight. A light point is visible as one or more self-illuminated small
points that do not illuminate surrounding objects. By comparison, a
pfLight does illuminate scene contents but is itself not a visible
object.
When a pfLPointState is applied with pfLPointState::apply or through its
parent pfGeoState (See pfGeoSet::draw and pfGeoState::apply), any
pfGeoSet of type PFGS_POINTS will be rendered with the following special
light point characteristics (if enabled):
1. Perspective size. Light points can be assigned a real world size
and exhibit perspective behavior, e.g., points closer to the eye
will be rendered larger than those points farther away.
2. Perspective fading. Once a light point reaches a minimum size, it
may be made more transparent in order to enhance the perspective
illusion. Fading is often more realistic than simply shrinking
the point size to 0.
3. Fog punch-through. Since light points are emissive objects, they
must shine through fog more than non-emissive objects.
4. Directionality. Light points can be assigned a direction as well
as vertical and horizontal envelopes (or lobes) about this
direction vector. Directional light point intensity is then view
position-dependent. Light point direction is defined by the
normals (PFGS_NORMAL3) supplied by PFGS_POINTS pfGeoSets.
5. Intensity. Normally, light point color and transparency are
defined by the colors (PFGS_COLOR4) supplied by PFGS_POINTS
pfGeoSets. pfLPointStates provide the additional capability of
modifying the intensity of all points in a light point pfGeoSet
by scaling the alpha of all point colors.
At a minimum, light point usage requires a configuration based on three
linked libpr objects: a pfGeoSet, a pfGeoState attached to that pfGeoSet,
and a pfLPointState attached to the pfGeoState. Here are the details:
1. A pfGeoSet of type PFGS_POINTS. This pfGeoSet must have a
PFGS_COLOR4 attribute binding of PFGS_PER_VERTEX in some
situations and should have supplied normals (PFGS_NORMAL3) if the
light points are directional.
2. A pfGeoState which is usually attached to the pfGeoSet and
which references a pfLPointState. The pfGeoState should almost
always enable transparency since all light point effects except
perspective size require transparency.
Page 3
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
3. A pfLPointState configured appropriately and attached to the
pfGeoState listed in step two.
The following example illustrates how to build a comprehensive light
point structure that uses texture mapping to accelerate directionality
computations:
/*
* Create pfLPointState and pfGeoState.
*/
pfGeoState *gst = new pfGeoState;
pfLPointState *lps = new pfLPointState;
gst->setMode(PFSTATE_ENLPOINTSTATE, 1);
gst->setAttr(PFSTATE_LPOINTSTATE, lps);
/*
* Light point projected diameter is computed on CPU. Real world
* size is 0.07 database units and projected size is clamped be
* between 0.25 and 4 pixels.
*/
lps->setMode(PFLPS_SIZE_MODE, PFLPS_SIZE_MODE_ON);
lps->setVal(PFLPS_SIZE_MIN_PIXEL, 0.25f);
lps->setVal(PFLPS_SIZE_ACTUAL, 0.07f);
lps->setVal(PFLPS_SIZE_MAX_PIXEL, 4.0f);
/*
* Light points become transparent when their projected diameter is
* < 2 pixels. The transparency falloff rate is linear with
* projected size with a scale factor of 0.6. The transparency
* multiplier, NOT the light point transparency, is clamped to 0.1.
*/
lps->setVal(PFLPS_TRANSP_PIXEL_SIZE, 2.0f);
lps->setVal(PFLPS_TRANSP_EXPONENT, 1.0f);
lps->setVal(PFLPS_TRANSP_SCALE, 0.6f);
lps->setVal(PFLPS_TRANSP_CLAMP, 0.1f);
/*
* Light points will be fogged as if they were 4 times
* nearer to the eye than actual to achieve punch-through.
*/
lps->setVal(PFLPS_FOG_SCALE, 0.25f);
/* Range to light points computed on CPU is true range */
lps->setMode(PFLPS_RANGE_MODE, PFLPS_RANGE_MODE_TRUE);
/*
* Light points are bidirectional but have different (magenta)
* back color. Front color is provided by pfGeoSet colors.
*/
lps->setMode(PFLPS_SHAPE_MODE, PFLPS_SHAPE_MODE_BI_COLOR);
lps->setBackColor(1.0f, 0.0f, 1.0f, 1.0f);
Page 4
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
/*
* 60 degrees horizontal and 30 degrees vertical envelope.
* Envelope is rotated -25 degrees about the light point
* direction. Falloff rate is linear and ambient intensity is 0.1.
*/
lps->setShape(60.0f, 30.0f, -25.0f, 1.0f, 0.1f);
/*
* Specify that light points should use texturing hardware to simulate
* directionality and use CPU to compute light point transparency and
* fog punch-through. Note that if light points are omnidirectional,
* you should use PFLPS_TRANSP_MODE_TEX and PFLPS_FOG_MODE_TEX instead.
*/
lps->setMode(PFLPS_DIR_MODE, PFLPS_DIR_MODE_TEX);
lps->setMode(PFLPS_TRANSP_MODE, PFLPS_TRANSP_MODE_ALPHA);
lps->setMode(PFLPS_FOG_MODE, PFLPS_FOG_MODE_ALPHA);
/*
* Make directionality environment map of size 64 x 64 and attach
* it to the light point pfGeoState. We assume that a pfTexEnv of
* type PFTE_MODULATE has been globally applied with pfApplyTEnv.
*/
tex = new pfTexture;
lps->makeShapeTex(tex, 64);
gst->setAttr(PFSTATE_TEXTURE, tex);
gst->setMode(PFSTATE_ENTEXTURE, 1);
/*
* Make SPHERE_MAP pfTexGen and attach to light point pfGeoState.
* pfGeoSet normals define the per-light light point direction.
*/
tgen = new pfTexGen;
tgen->setMode(PF_S, PFTG_SPHERE_MAP);
tgen->setMode(PF_T, PFTG_SPHERE_MAP);
gst->setAttr(PFSTATE_TEXGEN, tgen);
gst->setMode(PFSTATE_ENTEXGEN, 1);
/*
* Configure light point transparency. Use PFTR_BLEND_ALPHA for high
* quality transparency. Set pfAlphaFunc so that light points are not
* drawn unless their alphas exceed 1 when using 8-bit color resolution.
*/
gst->setMode(PFSTATE_TRANSPARENCY, PFTR_BLEND_ALPHA);
gst->setVal(PFSTATE_ALPHAREF, 1.0/255.0);
gst->setMode(PFSTATE_ALPHAFUNC, PFAF_GREATER);
/*
* Disable pfFog effects since light points are fogged by
* the pfLPointState.
*/
gst->setMode(PFSTATE_ENFOG, 0);
/*
Page 5
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
* Disable lighting effects since light points are completely
* emissive.
*/
gst->setMode(PFSTATE_ENLIGHTING, 0);
/*
* Attach the pfGeoState to a pfGeoSet of type PFGS_POINTS and
* you've got light points!
*/
gset->setPrimType(PFGS_POINTS);
gset->setGState(gst);
pfLPointState Modes
Each of the five light point characteristics listed earlier may be
achieved through the Graphics Library in different ways depending on the
available graphics hardware. pfLPointState::setMode/pfLPointState::setVal
provide control over feature implementation. Modes and their
corresponding values accepted by pfLPointState::setMode are:
PFLPS_SIZE_MODE /* Perspective size */
PFLPS_SIZE_MODE_ON - Enable perspective light point size.
Perspective size is computed on the CPU.
PFLPS_SIZE_MODE_OFF - Disable perspective light point size.
PFLPS_TRANSP_MODE /* Perspective fading */
PFLPS_TRANSP_MODE_ON - Enable default (CPU-based) light point
fading.
PFLPS_TRANSP_MODE_OFF - Disable light point fading.
PFLPS_TRANSP_MODE_ALPHA - Enable light point fading. Compute fade
value on CPU and modify light point alpha. This mode requires
that pfGeoSets have a PFGS_COLOR4 binding of PFGS_PER_VERTEX and
that there be a unique color for each point.
PFLPS_TRANSP_MODE_TEX - Enable light point fading. Use texture
mapping to simulate fading.
PFLPS_FOG_MODE /* Fog punch-through */
PFLPS_FOG_MODE_ON - Enable default (CPU-based) fog punch-through.
PFLPS_FOG_MODE_OFF - Disable fog punch-through.
PFLPS_FOG_MODE_ALPHA - Enable fog punch-through. Compute fog
value on CPU and modify light point alpha. This mode requires
that pfGeoSets have a PFGS_COLOR4 binding of PFGS_PER_VERTEX and
that there be a unique color for each point.
Page 6
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFLPS_FOG_MODE_TEX - Enable fog punch-through. Use texture
mapping to simulate fog.
(Normal fogging should be disabled (pfDisable(PFEN_FOG) or
pfGeoState::setMode(PFSTATE_ENFOG, 0)) when PFLPS_FOG_MODE is not
PFLPS_FOG_MODE_OFF since the pfLPointState will fog the points)
PFLPS_DIR_MODE /* Directionality enable */
PFLPS_DIR_MODE_ON - Enable default (CPU-based) directional light
points.
PFLPS_DIR_MODE_OFF - Disable directional light points.
PFLPS_DIR_MODE_ALPHA - Enable directional light points. Compute
directionality on CPU and modify light point alpha. This mode
requires that pfGeoSets have a PFGS_COLOR4 binding of
PFGS_PER_VERTEX and that there be a unique color for each point.
PFLPS_DIR_MODE_TEX - Enable directional light points. Use texture
mapping to simulate directionality.
PFLPS_SHAPE_MODE /* Directionality shape */
PFLPS_SHAPE_MODE_UNI - Directional light points are
unidirectional. Light distribution is an elliptical cone
specified by pfLPointState::setShape, centered about the light
direction vector.
PFLPS_SHAPE_MODE_BI - Directional light points are bidirectional
with identical front and back colors. Light distribution is two
elliptical cones, specified by pfLPointState::setShape, centered
about the positive and negative light direction vectors.
PFLPS_SHAPE_MODE_BI_COLOR - Directional light points are
bidirectional with back color specified by
pfLPointState::setBackColor. Light distribution is two elliptical
cones, specified by pfLPointState::setShape, centered about the
positive and negative light direction vectors.
PFLPS_RANGE_MODE
PFLPS_RANGE_MODE_DEPTH - Range to light point is approximated by
depth from eye. This may be faster, but less accurate than
PFLPS_RANGE_MODE_TRUE.
PFLPS_RANGE_MODE_TRUE - Range to light point is true, slanted
range to eye. This may be slower, but more accurate than
PFLPS_RANGE_MODE_DEPTH.
pfLPointState Values
pfLPointState::setVal sets the attribute of the pfLPointState identified
by which to val. pfLPointState::getVal returns the attribute of the
Page 7
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfLPointState identified by which.
Values associated with PFLPS_SIZE_MODE and which have effect only when
PFLPS_SIZE_MODE is PFLPS_SIZE_MODE_ON are the following:
PFLPS_SIZE_MIN_PIXEL
val specifies the minimum diameter, in pixels, of light points.
Default value is 0.25. Note that actual minimum point size is
clamped to the minimum supported by the graphics hardware.
PFLPS_SIZE_MAX_PIXEL
val specifies the maximum diameter, in pixels, of light points.
Default value is 4.0. Note that actual maximum point size is
clamped to the maximum supported by the graphics hardware.
PFLPS_SIZE_ACTUAL
val specifies light point diameter in eye coordinates. Scales
do not affect the actual light point size. Default value is
0.25.
In pseudo-code, the size of a light point is determined as follows:
/* NearPixelDistance is described below */
computedSize = PFLPS_SIZE_ACTUAL * NearPixelDistance / rangeToEye;
if (PFLPS_SIZE_MODE == PFLPS _SIZE_MODE_ON)
{
/* Clamp pixel size of point */
if (computedSize < PFLPS_SIZE_MIN_PIXEL)
computedSize = PFLPS_SIZE_MIN_PIXEL;
else
if (computedSize > PFLPS_SIZE_MAX_PIXEL)
computedSize = PFLPS_SIZE_MAX_PIXEL;
lightPointSize = computedSize;
}
Values associated with PFLPS_TRANSP_MODE and which have effect only when
PFLPS_TRANSP_MODE is not PFLPS_TRANSP_MODE_OFF.
PFLPS_TRANSP_PIXEL_SIZE
val specifies the threshold diameter, in pixels, at which light
point alphas are decreased so that they become more transparent
once computed light point size is less than val. Default value
is 0.25.
PFLPS_TRANSP_EXPONENT
val specifies an exponential falloff for light point fading and
should be >= 0.0. Values > 0 and < 1 make the falloff curve
flatter while values > 1 make it sharper. Default value is 1.0
Page 8
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
for a linear falloff based on projected pixel size.
PFLPS_TRANSP_SCALE
val specifies a scale factor for the light point fade
multiplier. Values > 0 and < 1 decrease the falloff rate while
values > 1 increase it. Default value is 1.0.
PFLPS_TRANSP_CLAMP - val specifies the minimum fade multiplier.
In pseudo-code, the transparency of a light point is determined as
follows:
if (PFLPS_TRANSP_MODE == PFLPS_TRANSP_MODE_ALPHA &&
PFLPS_TRANSP_PIXEL_SIZE > computedSize)
{
float a;
a = 1.0f - PFLPS_TRANSP_SCALE *
powf(PFLPS_TRANSP_PIXEL_SIZE - computedSize,
PFLPS_TRANSP_EXPONENT);
/* Clamp alpha multiplier, not alpha */
if (a < PFLPS_TRANSP_CLAMP)
a = PFLPS_TRANSP_CLAMP;
lightPointAlpha *= a;
}
PFLPS_FOG_SCALE
val specifies a scale factor that multiplies the range from eye to
light point before fogging. Values > 0.0 and < 1.0 cause light
points to punch through fog more than non-emissive surfaces.
Default value is 0.25.
In pseudo-code, the fog of a light point is determined as follows:
/* fogFunction ranges from 0 (no fog) to 1 (completely fogged) */
lightPointAlpha *= 1.0f - fogFunction(rangeToEye * PFLPS_FOG_SCALE);
PFLPS_INTENSITY
val multiplies all light point alphas. Default value is 1.0.
PFLPS_SIZE_DIFF_THRESH
val specifies the threshold, in pixels, at which a new point size
should be specified to the Graphics Library. It is strictly a
tuning parameter which trades off speed for image quality. Default
value is 0.1. Higher values improve performance but may degrade
Page 9
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
light point image quality.
PFLPS_TRANSP_MODE, PFLPS_FOG_MODE, and PFLPS_DIR_MODE modes each have
possible values of ALPHA and TEX which dictate the mechanism used to
simulate the effect. The ALPHA mechanism is the default and uses the CPU
to compute the effect which is then realized by modifying the alpha of
light point colors. pfGeoSets of type PFGS_POINTS which use an ALPHA
mechanism should have a PFGS_COLOR4 binding of PFGS_PER_VERTEX even if
all point colors are the same, since the light point alphas will be
different based on ALPHA computation by the pfLPointState.
While ALPHA mechanisms are graphics hardware-independent, they may be
slower than TEX mechanisms on machines which provide hardware texture
mapping. By supplying an appropriate pfTexture, pfTexGen, and pfTexEnv
(usually attached to the pfGeoState to which the pfLPointState is
attached), you can use the texture mapping hardware to efficiently
simulate directionality or fog punch-through and perspective fading. At
this time it is not possible to support all TEX mechanisms at once:
1. Only PFLPS_DIR_MODE_TEX or,
2. PFLPS_TRANSP_MODE_TEX and/or PFLPS_FOG_MODE_TEX
It is recommended that directional light points use PFLPS_DIR_MODE_TEX
since directionality is the most expensive effect to compute on the CPU.
Two convenience routines, pfLPointState::makeRangeTex and
pfLPointState::makeShapeTex are provided to compute a texture image which
accurately mimics certain characteristics of the pfLPointState.
pfLPointState::makeRangeTex should be used in conjunction with
PFLPS_TRANSP_MODE_TEX and/or PFLPS_FOG_MODE_TEX and will set a computed
image on the supplied pfTexture, tex. The image will be a 2D array of
size by size if both PFLPS_TRANSP_MODE_TEX and PFLPS_FOG_MODE_TEX are set
on lpstate or the image will be a 1D array of length size if only 1 of
PFLPS_TRANSP_MODE_TEX and PFLPS_FOG_MODE_TEX is set.
When using PFLPS_TRANSP_MODE_TEX and/or PFLPS_FOG_MODE_TEX, you must
supply a pfTexGen structure which computes the S (and T if both
PFLPS_TRANSP_MODE_TEX and PFLPS_FOG_MODE_TEX are set) texture coordinates
as distance from the Z = 0 plane in eye coordinates. For example:
tgen = new pfTexGen;
tgen->setPlane(PF_S, 0.0f, 0.0f, 1.0f, 0.0f);
tgen->setPlane(PF_T, 0.0f, 0.0f, 1.0f, 0.0f);
tgen->setMode(PF_S, PFTG_EYE_PLANE);
tgen->setMode(PF_T, PFTG_EYE_PLANE);
pfLPointState::makeRangeTex takes into account only the following values
of the pfLPointState when building the texture image and should be called
again whenever they change:
Page 10
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFLPS_TRANSP_PIXEL_SIZE
PFLPS_TRANSP_EXPONENT
PFLPS_TRANSP_SCALE
PFLPS_TRANSP_CLAMP
pfLPointState::makeShapeTex computes an environment map which
approximates the directional characteristics of the pfLPointState. The
computed image is assigned to tex and its dimensions are size by size.
When using PFLPS_DIR_MODE_TEX, you must supply a pfTexGen structure which
uses PFTG_SPHERE_MAP to compute both S and T. For example:
tgen = new pfTexGen;
tgen->setMode(PF_S, PFTG_SPHERE_MAP);
tgen->setMode(PF_T, PFTG_SPHERE_MAP);
pfLPointState::makeShapeTex takes into account only the PFLPS_SHAPE_MODE
modes and those values specified by pfLPointState::setShape.
Consequently, pfLPointState::makeShapeTex should be called whenever these
modes/values change.
fog should represent the desired fog ramp, e.g. PFFOG_LINEAR,
PFFOG_SPLINE, if PFLPS_FOG_MODE_TEX is set or NULL if not set. The fog
ranges are ignored and fog is not modified.
Each of the four main light point features (size, transparency, fog, and
directionality) are view-dependent effects. Consequently, knowledge
about the viewing and modeling transformations is required in certain
situations:
1. When not using libpf. Otherwise, libpf automatically informs
libpr of the viewing and modeling transformations.
2. When using an ALPHA mechanism, e.g., PFLPS_DIR_MODE_ALPHA.
3. When PFLPS_SIZE_MODE is PFLPS_SIZE_MODE_ON.
Use pfViewMat and pfModelMat to specify the viewing and modeling matrices
respectively. For best performance, these routines should be called only
when the corresponding matrix changes. Additionally you may call
pfInvModelMat to specify the inverse of the modeling matrix if you've
already computed it for some other reason. When using PFLPS_SIZE_MODE_ON,
use pfNearPixDist to specify the distance, in pixels, from the eye to the
near clip plane. pfLPointState needs this parameter to map world size to
pixel size (but only if not using libpf). pfViewMat, pfModelMat,
pfInvModelMat, and pfNearPixDist are all display-listable commands which
may be captured by an open pfDispList.
new(arena) allocates a pfLPointState from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfLPointState
from the default memory arena (see pfGetSharedArena). Like other
Page 11
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfObjects, pfLPointStates cannot be created statically, automatically on
the stack or in arrays. pfLPointStates should be deleted with pfDelete
rather than the delete operator.
pfLPointState::getClassType returns the pfType* for the class
pfLPointState. The pfType* returned by pfLPointState::getClassType is
the same as the pfType* returned by invoking the virtual function getType
on any instance of class pfLPointState. 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.
pfLightPoint::setShape specifies the light distribution characteristics
of directional light points. Light point directions are specified by
pfGeoSet normals after they have been transformed by the current modeling
matrix. Note that a PFGS_NORMAL3 binding of PFGS_OVERALL is permitted as
well as a binding of PFGS_PER_VERTEX. Directional light points require
that PFLPS_DIR_MODE be PFLPS_DIR_MODE_ON, PFLPS_DIR_MODE_ALPHA, or
PFLPS_DIR_MODE_TEX.
horiz and vert are total-angles angles (not half-angles) in degrees which
specify the horizontal and vertical envelopes about the direction vector.
As such, the maximum value for these angles is 180 degrees, for a 180
degree lobe shape. 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. The envelopes are twisted about the +Y
axis by roll degrees, then rotated by the rotation which takes the +Y
axis onto the light point direction vector. Default values are:
horiz = 90 degrees
vert = 90 degrees
roll = 0 degrees
falloff = 1
ambient = 0
When the vector from the eyepoint to the light position is outside its
envelope, the light point's intensity is ambient. 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 ambient 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 1. As intensity decreases, the light
point's transparency increases.
pfLightPoint::getShape copies the pfLPointState's shape parameters into
horiz, vert, roll, falloff, and ambient.
pfLPointState::setBackColor specifies the back color of the
pfLPointState. If the pfLPointState's shape mode is not
Page 12
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFLPS_SHAPE_MODE_BI_COLOR, then the back color has no effect.
pfLPointState::setBackColor copies the pfLPointState's back color
components into r, g, b, a.
pfLPointState::apply makes the pfLPointState the current pfLPointState
which affects all subsequently drawn pfGeoSets of type PFGS_POINTS.
pfLPointState::apply is a display-listable command which may be captured
by an open pfDispList. A pfLPointState may also be attached to a
pfGeoState. pfGetCurLPState returns the current pfLPointState or NULL if
there is none.
LIGHT POINTS PREPROCESSING
Light point processing can be heavy. One way is to reduce the load by
using textures, but reducing the quality and precision of the light
points. This may be acceptable in many case, but is not tolerable for
high quality light points.
An other way is to have a separate task to do the processing in parallel
with the drawing of the scene, and then to draw the light points that
have already been preprocessed. (see pfDispList::preprocess)
In that case, do not use textures simplification. This prevent
preprocessing and also annul the following pfLPointState callbacks. If
you do not have a process dedicated to preprocess light points, and do
not use texture simplification in a pfLPointState, you may use the
following callbacks being conscious of the time taken out of the draw by
the callback.
pfLPointState::setRasterFunc sets the rasterCallback function and the
user data (data) to the pfLPointState.
pfLPointState::getRasterFunc gives back the current function and data.
pfLPointState::setCalligFunc and pfLPointState::getCalligFunc do the same
for the Calligraphic Light Points callback as explained in the
pfCalligraphic man pages.
The object of those callbacks is to give access directly to the
computation of each light in the pfGoeSet. The callback will be call when
processing the pfLPointState only if the PFLPS_CALLBACK_MODE is not set
to PFLPS_CALLBACK_MODE_OFF.
Two modes are available:
PFLPS_CALLBACK_MODE_PRE makes the callback to be invoked before IRIX
Performer standard light points behaviour. Use this to implement your own
attenuation algorithm.
PFLPS_CALLBACK_MODE_POST makes the callback to be invoked after IRIX
Performer do the standard computation. Use this to implement some nice
animations, or final touch attenuation computation.
Page 13
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
When the callback returns, no further computation is done before the
light points are drawn.
The callback function receive many arguments (as defined in pr.h):
typedef struct {
pfLPointState *lpstate; /* Read Only LPState */
pfGeoSet *geoset; /* Read Only GeoSet */
void *userData; /* Provided when setting the callback */
float *sizes; /* Write Only - resulting sizes */
float *alphas; /* Write Only - resulting alphas */
} pfRasterData;
lpstate is the pointer to the pfLPointState beeing processed.
geoset is the pointer to the pfGeoSet beeing processed.
userData is the pointer provided when declaring the callback.
sizes, alphas are the result of the light points computation. They are
allready allocated, even if it is a PRE callback.
The sizes contains the size of each point in pixel unit, and alpha the
transparency. The size is always a positive value, but an alpha value can
be negative. A negative value tells to draw this point with the
backColor, with an alpha value of -alpha.
Here is an skeleton of a post callback:
void myCallback(pfRasterData *rasterData)
{
pfVec3* vertices;
unsigned short *vindex;
pfVec3* norms;
unsigned short *nindex;
int nbind;
pfVec4* colors;
unsigned short *cindex;
int cbind;
unsigned short *cindex;
pfFog *fog;
int fogEnabled = 0;
int i,n;
int sizeMode;
pfMatrix ViewMat, InvModelView;
/* get pointers to the geoset */
pfGetGSetAttrLists(rasterData->gset,PFGS_COORD3, &vertices, &vindex);
pfGetGSetAttrLists(rasterData->gset,PFGS_NORMAL3, &norms, &nindex);
Page 14
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
nbind = pfGetGSetAttrBind(rasterData->gset,PFGS_NORMAL3);
/* colors are usualy not used here */
cbind = pfGetGSetAttrBind(rasterData->gset,PFGS_COLOR4);
pfGetGSetAttrLists(rasterData->gset,PFGS_COLOR4, &colors, &cindex);
/* use color table if enabled */
if (pfGetEnable(PFEN_COLORTABLE))
colors = pfGetCurCtab();
/* get the number of lights */
n = pfGetGSetNumPrims(rasterData->gset);
/* get matrices */
pfGetViewMat(ViewMat);
pfGetInvModelMat(InvModelMat);
/* see if there's fog */
fog = pfGetCurFog();
if (pfGetEnable(PFEN_FOG) && fog)
fogEnabled = 1;
/* get information on the lpstate */
sizeMode = pfGetLPStateMode(rasterData->lpstate,PFLPS_SIZE_MODE);
........
........
/* do the computation */
for (i=0; i<n; i++)
{
/* get the normal */
if (vindex)
{
if (nbind & PFGS_OVERALL)
nj=nindex[0];
else if (nbind)
nj=nindex[i];
else
nj=-1; /* this geoset has no normals */
nv=vindex[i];
} else
{
if (nbind & PFGS_OVERALL)
nj=0;
else if (nbind)
nj=i;
else
nj=-1; /* this geoset has no normals */
nv=i;
}
/* now we have vertices[nv] and normals[nv] to do the computation */
........
........
Page 15
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
rasterData->alphas[i] = ....
rasterData->sizes[i] = ....
}
}
Calligraphic Light Points are supported using the preprocessing
capability, and the pfCalligraphic object. The calligraphic extensions to
pfLPointState are described in the pfCalligraphic man pages.
NOTES
Falloff distribution is cosine(incidence angle) ^ falloff.
The angle calculation for textured lightpoints may be inaccurate in
extreme wide-angle visibility configurations, and work only for symmetric
aperture.
SEE ALSO
pfCalligraphic, pfDelete, pfDispList, pfFog, pfGeoSet, pfGeoState,
pfState, pfTexture, pfTexGen, pfuMakeLPStateRangeTex,
pfuMakeLPStateShapeTex
Page 16
