pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfHighlight, pfGetCurHlight - Control, create, modify and query highlight
state
FUNCTION SPECIFICATION
#include <Performer/pr/pfHighlight.h>
pfHighlight::pfHighlight()
static pfType * pfHighlight::getClassType(void);
void pfHighlight::apply(void);
void pfHighlight::setMode(uint mode);
uint pfHighlight::getMode(void);
void pfHighlight::setColor(uint which, float r, float g,
float b);
void pfHighlight::getColor(uint which, float *r, float *g,
float *b);
void pfHighlight::setAlpha(float a);
float pfHighlight::getAlpha(void);
void pfHighlight::setNormalLength(float length,
float bboxScale);
float pfHighlight::getNormalLength(float *length,
float *bboxScale);
void pfHighlight::setLineWidth(float width);
float pfHighlight::getLineWidth(void);
void pfHighlight::setPntSize(float size);
float pfHighlight::getPntSize(void);
void pfHighlight::setLinePat(int which, ushort pat);
ushort pfHighlight::getLinePat(const int which);
void pfHighlight::setFillPat(int which, uint *fillPat);
void pfHighlight::getFillPat(const int which, uint *pat);
void pfHighlight::setGState(pfHighlight* hl,
pfGeoState *gstate);
Page 1
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfGeoState* pfHighlight::getGState(const pfHighlight* hl);
void pfHighlight::setGStateIndex(pfHighlight* hl, int id);
int pfHighlight::getGStateIndex(const pfHighlight* hl);
void pfHighlight::setTex(pfTexture *tex);
pfTexture* pfHighlight::getTex(void);
void pfHighlight::setTEnv(pfTexEnv *tev);
pfTexEnv* pfHighlight::getTEnv(void);
void pfHighlight::setTGen(pfTexGen *tgen);
pfTexGen* pfHighlight::getTGen(void);
pfHighlight * pfGetCurHlight(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfHighlight is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfHighlight. 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 pfHighlight 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);
Page 2
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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
OpenGL Performer supports a mechanism for highlighting individual objects
in a scene with a variety of special drawing styles that are activated by
applying a pfHighlight state structure. Highlighting makes use of
outlining of lines and polygons and of filling polygons with patterned or
textured overlays. Highlighted drawing uses a highlighting color, or
foreground color, and in some modes, a contrasting, or background, color.
Additionally, there are highlighting modes for displaying the bound
normals and cached bounding boxes of pfGeoState geometry.
A pfHighlight structure can be applied in immediate mode to the current
active pfGeoState with pfHighlight::apply, and added to a specific
pfGeoState with pfGeoState::setMode. Highlighting can be enabled and
disabled in immediate mode with pfEnable(PFEN_HIGHLIGHTING) and
pfDisable(PFEN_HIGHLIGHTING), and the override for highlighting can be
set with pfOverride(PFSTATE_HIGHLIGHT). Unlike other types of state, a
structure may be applied to a specific pfGeoSet with pfGeoSet::setHlight.
This will cause the pfGeoSet to be drawn as highlighted with the
specified highlighting structure, unless highlighting has been overridden
as off with pfOverride.
This special exception was made because it is assumed that highlighting
is to be used dynamically to highlight specific objects for a short
period of time and should not impact the rest of the state structure.
Highlighting does have some performance penalty, in part because some of
the highlighting modes make use of expensive graphics features, and in
part because, to offer this flexibility, highlighted objects go through a
slightly slower path in OpenGL Performer rendering code.
new(arena) allocates a pfHighlight from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfHighlight from
the default memory arena (see pfGetSharedArena). Like other pfObjects,
pfHighlights cannot be created statically, automatically on the stack or
in arrays. pfHighlights should be deleted with pfDelete rather than the
delete operator.
pfHighlight::getClassType returns the pfType* for the class pfHighlight.
The pfType* returned by pfHighlight::getClassType is the same as the
pfType* returned by invoking the virtual function getType on any instance
of class pfHighlight. Because OpenGL Performer allows subclassing of
Page 3
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
pfHighlight::apply makes the pfHighlight the current active pfHighlight
structure.
pfGetCurHlight returns a pointer to the current active pfHighlight
structure.
pfHighlight::setGState sets a highlighting pfGeoState of the pfHighlight
to gstate. This pfGeoState is made the current pfGeoState for the
highlighting phase of the drawing of the highlighted pfGeoSet.
Additional highlighting mode changes are applied on top of this
pfGeoState. This allows a user to make additional custom state changes
to highlighted objects. pfHighlight::getGState returns the previously
set highlighting pfGeoState of the pfHighlight.
pfHighlight::setGStateIndex specifies the index into a pfGeoState table
to use for the highlighting pfGeoState. pfHighlight::getGStateIndex
returns the previously set highlighting pfGeoState index of the
pfHighlight.
pfHighlight::setMode sets the highlighting mode mode for the pfHighlight.
The mode specifies the drawing style: how the filled region and polygon
outlines of an object should be drawn. This mode is a bitmask composed
by bitwise OR-ing together the following tokens. The default is
PFHL_FILL, and a zero mask is ignored.
PFHL_POINTS Selects the display of object vertices as points
using the point size specified by
pfHlightPntSize.
PFHL_NORMALS Selects the display of object normals as lines
of width determined by
pfHighlight::setLineWidth, length determined by
pfHighlight::setNormalLength, and color
determined by pfHighlight::setColor.
PFHL_BBOX_LINES Selects the display of the object's cached
bounding box in lines of width determined by
pfHighlight::setLineWidth and color determined
by pfHighlight::setColor.
PFHL_BBOX_FILL Selects the display of the object's cached
bounding box as a solid filled box of the
foreground color of the pfHighlight.
PFHL_LINES Selects outlining of primitives. The lines are
drawn of width determined by
pfHighlight::setLineWidth and color determined
by pfHighlight::setColor.
Page 4
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFHL_LINES_R Selects outlining of primitives and reverses
foreground and background colors for the lines.
PFHL_LINESPAT Selects outlining of primitives with patterned
lines.
PFHL_LINESPAT2 Selects outlining of primitives with 2-pass
patterned lines, using both foreground and
background highlighting colors.
PFHL_FILL Selects filling of polygons with the foreground
highlighting color. In this mode, the
highlighted polygons are filled once. The
foreground highlighting color is used as the
base color of polygons, and as the material
color for lit polygons.
PFHL_FILL_R Selects outlining of primitives and reverses
foreground and background colors for fill
highlight modes.
PFHL_FILLTEX Selects the application of a highlight texture
on the object geometry. The default texture may
be used, or a texture and associated attributes
may be set with pfHighlight::setTexTGen,
pfHighlight::setTEnvTGen, and
pfHighlight::setTGen.
PFHL_FILLPAT Selects patterned filling of polygons with the
foreground highlighting color. This patterning
will be done in addition to the normal filling
of the polygons and will be an overlay with the
normal base polygons showing through.
PFHL_FILLPAT2 Selects 2-pass patterned filling of polygons
using both the foreground and background
highlighting colors. This patterning will be
done in addition to the normal filling of the
polygons and will be an overlay with the normal
base polygons showing through.
PFHL_SKIP_BASE Causes the normal drawing phase of the
highlighted pfGeoSet to be skipped. This
includes the application of the pfGeoState for
that pfGeoSet.
pfHighlight::getMode returns the highlighting mode of the pfHighlight.
pfHighlight::setColor sets the specified highlighting color color,
PFHL_FGCOLOR or PFHL_BGCOLOR, of the pfHighlight, to r, g, and b.
pfHighlight::getColor copies the specified color, PFHL_FGCOLOR or
PFHL_BGCOLOR, of the pfHighlight, into r, g, and b.
Page 5
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfHighlight::setAlpha sets the alpha of the pfHighlight to a.
pfHighlight::getAlpha returns the alpha of the pfHighlight.
pfHighlight::setLineWidth sets the line width to be used for the
PFHL_LINES, PFHL_NORMALS, and PFHL_BBOX highlighting modes of the
pfHighlight to width. If width is not greater than zero, the line width
will not be set by the highlight structure and will be inherited from the
current environment. pfHighlight::getLineWidth returns the line width of
the pfHighlight.
pfHighlight::setNormalLength sets a length and a scale factor for the
normals drawn in the PFHL_NORMALS highlighting mode. The normals will be
drawn of length normalLength + bboxScale*bboxLength.
pfHighlight::getNormalLength will return the normal length and scale
values of the pfHighlight in length and bboxScale, respectively.
pfHighlight::setPntSize sets the point size to be used for the
PFHL_POINTS highlighting mode of the pfHighlight to size. If size is not
greater than zero, the point size will not be set by the highlight
structure and will be inherited from the current environment.
pfHighlight::getPntSize returns the point size of the pfHighlight.
pfHighlight::setLinePat sets the pattern to be used for lines in the
PFHL_LINES highlighting modes of the pfHighlight to pat.
pfHighlight::getLinePat returns the highlighting line pattern of the
pfHighlight. For both functions, the which argument determines if the
line pattern pertaining to the foreground (PFHL_FGPAT) or background (-
PFHL_BGPAT) style is to be set or inquired.
pfHighlight::setFillPat sets the fill pattern to be used in the
PFHL_FILLPAT highlighting modes of the pfHighlight to pat.
pfHighlight::getFillPat returns the highlighting fill pattern of the
pfHighlight.
pfHighlight::setTex sets the pfTexture for the PFHL_TEX highlighting
modes of the pfHighlight to tex. pfHighlight::getTex returns the
previously set highlighting texture of the pfHighlight. If a texture is
not specified but the PFHL_TEX is selected for the pfHighlight, a default
two-component texture using the highlighting foreground and background
colors will be used.
pfHighlight::setTEnv sets the texture environment (pfTexEnv) for the
PFHL_TEX highlighting modes of the pfHighlight to tev.
pfHighlight::getTEnv returns the previously set highlighting texture
environment of the pfHighlight. If a texture environment is not
specified but the PFHL_TEX is selected for the pfHighlight, a default
texture blend environment will be used.
pfHighlight::setTGen sets the texture coordinate generation attribute
(pfTexGen) for the PFHL_TEX highlighting modes of the pfHighlight to
tgen. pfHighlight::getTGen returns the previously set highlighting
pfTexGen of the pfHighlight. If a texture coordinate generation function
Page 6
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
is not specified and the object to be highlighted has no texture
coordinates of its own and the PFHL_TEX is selected for the pfHighlight,
a default texture coordinate generation function will be used.
EXAMPLES
Example 1: Set up a highlighting structure and apply it in immediate mode
to the current pfGeoState.
pfHighlight *hl;
/* allocate a new highlight color */
hl = new pfHighlight;
/* specify highlight modes */
hl->setMode(PFHL_FILL);
hl->setColor(PFHL_FGCOLOR, 1.0f, 0.0f, 1.0f);
/* apply highlight */
hl->apply();
SEE ALSO
pfDelete, pfDisable, pfDrawHlightedGSet, pfEnable, pfGSetHlight,
pfGeoState, pfGetGSetHlight, pfObject, pfOverride, pfState
Page 7
