pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewLPState, pfGetLPStateClassType, pfLPStateMode, pfGetLPStateMode,
pfLPStateVal, pfGetLPStateVal, pfLPStateShape, pfGetLPStateShape,
pfLPStateBackColor, pfGetLPStateBackColor, pfApplyLPState,
pfMakeLPStateRangeTex, pfMakeLPStateShapeTex, pfRasterFunc,
pfGetRasterFunc, pfCalligFunc, pfGetCalligFunc, pfGetCurLPState - Set and
get pfLPointState size, transparency, directionality, shape, and fog
attributes.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfLPointState * pfNewLPState(void *arena);
pfType * pfGetLPStateClassType(void);
void pfLPStateMode(pfLPointState *lpstate, int mode,
int val);
int pfGetLPStateMode(const pfLPointState *lpstate,
int mode);
void pfLPStateVal(pfLPointState *lpstate, int attr,
float val);
float pfGetLPStateVal(const pfLPointState *lpstate,
int attr);
void pfLPStateShape(pfLPointState *lpstate, float horiz,
float vert, float roll, float falloff,
float ambient);
void pfGetLPStateShape(const pfLPointState *lpstate,
float *horiz, float *vert, float *roll,
float *falloff, float *ambient);
void pfLPStateBackColor(pfLPointState *lpstate, float r,
float g, float b, float a);
void pfGetLPStateBackColor(pfLPointState *lpstate, float *r,
float *g, float *b, float *a);
void pfApplyLPState(pfLPointState *lpstate);
void pfMakeLPStateRangeTex(pfLPointState *lpstate,
pfTexture *tex, int size, pfFog* fog);
void pfMakeLPStateShapeTex(pfLPointState *lpstate,
pfTexture *tex, int size);
Page 1
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfRasterFunc(pfLPointState *lpstate,
pfRasterFuncType rasterCallback, void *rasterData);
void pfGetRasterFunc(pfLPointState *lpstate,
pfRasterFuncType *rasterCallback, void **data);
void pfCalligFunc(pfLPointState *lpstate,
pfCalligFuncType calligCallback, void *calligData);
void pfGetCalligFunc(pfLPointState *lpstate,
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. Casting an object
of class pfLPointState 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 pfLPointState 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);
Page 2
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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
lpstate identifies a pfLPointState.
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
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 pfApplyLPState or through its parent
pfGeoState (See pfDrawGSet and pfApplyGState), 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.
Page 3
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
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 = pfNewGState(arena);
pfLPointState *lps = pfNewLPState(arena);
pfGStateMode(gst, PFSTATE_ENLPOINTSTATE, 1);
pfGStateAttr(gst, 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.
*/
pfLPStateMode(lps, PFLPS_SIZE_MODE, PFLPS_SIZE_MODE_ON);
pfLPStateVal(lps, PFLPS_SIZE_MIN_PIXEL, 0.25f);
pfLPStateVal(lps, PFLPS_SIZE_ACTUAL, 0.07f);
pfLPStateVal(lps, 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.
*/
pfLPStateVal(lps, PFLPS_TRANSP_PIXEL_SIZE, 2.0f);
pfLPStateVal(lps, PFLPS_TRANSP_EXPONENT, 1.0f);
pfLPStateVal(lps, PFLPS_TRANSP_SCALE, 0.6f);
pfLPStateVal(lps, PFLPS_TRANSP_CLAMP, 0.1f);
/*
Page 4
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
* Light points will be fogged as if they were 4 times
* nearer to the eye than actual to achieve punch-through.
*/
pfLPStateVal(lps, PFLPS_FOG_SCALE, 0.25f);
/* Range to light points computed on CPU is true range */
pfLPStateMode(lps, PFLPS_RANGE_MODE, PFLPS_RANGE_MODE_TRUE);
/*
* Light points are bidirectional but have different (magenta)
* back color. Front color is provided by pfGeoSet colors.
*/
pfLPStateMode(lps, PFLPS_SHAPE_MODE, PFLPS_SHAPE_MODE_BI_COLOR);
pfLPStateBackColor(lps, 1.0f, 0.0f, 1.0f, 1.0f);
/*
* 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.
*/
pfLPStateShape(lps, 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.
*/
pfLPStateMode(lps, PFLPS_DIR_MODE, PFLPS_DIR_MODE_TEX);
pfLPStateMode(lps, PFLPS_TRANSP_MODE, PFLPS_TRANSP_MODE_ALPHA);
pfLPStateMode(lps, 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 = pfNewTex(arena);
pfMakeLPStateShapeTex(lps, tex, 64);
pfGStateAttr(gst, PFSTATE_TEXTURE, tex);
pfGStateMode(gst, PFSTATE_ENTEXTURE, 1);
/*
* Make SPHERE_MAP pfTexGen and attach to light point pfGeoState.
* pfGeoSet normals define the per-light light point direction.
*/
tgen = pfNewTGen(arena);
pfTGenMode(tgen, PF_S, PFTG_SPHERE_MAP);
pfTGenMode(tgen, PF_T, PFTG_SPHERE_MAP);
pfGStateAttr(gst, PFSTATE_TEXGEN, tgen);
pfGStateMode(gst, PFSTATE_ENTEXGEN, 1);
Page 5
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
/*
* 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.
*/
pfGStateMode(gst, PFSTATE_TRANSPARENCY, PFTR_BLEND_ALPHA);
pfGStateVal(gst, PFSTATE_ALPHAREF, 1.0/255.0);
pfGStateMode(gst, PFSTATE_ALPHAFUNC, PFAF_GREATER);
/*
* Disable pfFog effects since light points are fogged by
* the pfLPointState.
*/
pfGStateMode(gst, PFSTATE_ENFOG, 0);
/*
* Disable lighting effects since light points are completely
* emissive.
*/
pfGStateMode(gst, PFSTATE_ENLIGHTING, 0);
/*
* Attach the pfGeoState to a pfGeoSet of type PFGS_POINTS and
* you've got light points!
*/
pfGSetPrimType(gset, PFGS_POINTS);
pfGSetGState(gset, 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. pfLPStateMode/pfLPStateVal provide control
over feature implementation. Modes and their corresponding values
accepted by pfLPStateMode 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
Page 6
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
PFLPS_FOG_MODE_TEX - Enable fog punch-through. Use texture
mapping to simulate fog.
(Normal fogging should be disabled (pfDisable(PFEN_FOG) or
pfGStateMode(g, 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 pfLPStateShape, 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 pfLPStateShape, centered about the
positive and negative light direction vectors.
PFLPS_SHAPE_MODE_BI_COLOR - Directional light points are
bidirectional with back color specified by pfLPStateBackColor.
Light distribution is two elliptical cones, specified by
pfLPStateShape, centered about the positive and negative light
Page 7
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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
pfLPStateVal sets the attribute of lpstate identified by which to val.
pfGetLPStateVal returns the attribute of lpstate 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;
}
Page 8
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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
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:
Page 9
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
/* 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
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, pfMakeLPStateRangeTex and pfMakeLPStateShapeTex
are provided to compute a texture image which accurately mimics certain
characteristics of lpstate.
pfMakeLPStateRangeTex 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
Page 10
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
as distance from the Z = 0 plane in eye coordinates. For example:
tgen = pfNewTGen(arena);
pfTGenPlane(tgen, PF_S, 0.0f, 0.0f, 1.0f, 0.0f);
pfTGenPlane(tgen, PF_T, 0.0f, 0.0f, 1.0f, 0.0f);
pfTGenMode(tgen, PF_S, PFTG_EYE_PLANE);
pfTGenMode(tgen, PF_T, PFTG_EYE_PLANE);
pfMakeLPStateRangeTex takes into account only the following values of
lpstate when building the texture image and should be called again
whenever they change:
PFLPS_TRANSP_PIXEL_SIZE
PFLPS_TRANSP_EXPONENT
PFLPS_TRANSP_SCALE
PFLPS_TRANSP_CLAMP
pfMakeLPStateShapeTex computes an environment map which approximates the
directional characteristics of lpstate. 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 = pfNewTGen(arena);
pfTGenMode(tgen, PF_S, PFTG_SPHERE_MAP);
pfTGenMode(tgen, PF_T, PFTG_SPHERE_MAP);
pfMakeLPStateShapeTex takes into account only the PFLPS_SHAPE_MODE modes
and those values specified by pfLPStateShape. Consequently,
pfMakeLPStateShapeTex 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
Page 11
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
pfNewLPState creates and returns a handle to a pfLPointState. arena
specifies a malloc arena out of which the pfLPointState is allocated or
NULL for allocation off the process heap. pfLPointStates can be deleted
with pfDelete.
pfGetLPStateClassType returns the pfType* for the class pfLPointState.
The pfType* returned by pfGetLPStateClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfLPointState.
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.
pfLPointShape 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.
Page 12
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
pfGetLPointShape copies lpstate's shape parameters into horiz, vert,
roll, falloff, and ambient.
pfLPStateBackColor specifies the back color of lpstate. If lpstate's
shape mode is not PFLPS_SHAPE_MODE_BI_COLOR, then the back color has no
effect. pfLPStateBackColor copies lpstate's back color components into r,
g, b, a.
pfApplyLPState makes lpstate the current pfLPointState which affects all
subsequently drawn pfGeoSets of type PFGS_POINTS. pfApplyLPState 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 pfPreprocessDList)
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.
pfRasterFunc sets the rasterCallback function and the user data (data) to
the lpstate.
pfGetRasterFunc gives back the current function and data.
pfCalligFunc and pfGetCalligFunc 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:
Page 13
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
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;
Page 14
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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);
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;
Page 15
pfLPointState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
else
nj=-1; /* this geoset has no normals */
nv=i;
}
/* now we have vertices[nv] and normals[nv] to do the computation */
........
........
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
