pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewHlight, pfGetHlightClassType, pfApplyHlight, pfHlightMode,
pfGetHlightMode, pfHlightColor, pfGetHlightColor, pfHlightAlpha,
pfGetHlightAlpha, pfHlightNormalLength, pfGetHlightNormalLength,
pfHlightLineWidth, pfGetHlightLineWidth, pfHlightPntSize,
pfGetHlightPntSize, pfHlightLinePat, pfGetHlightLinePat, pfHlightFillPat,
pfGetHlightFillPat, pfHlightGState, pfGetHlightGState,
pfHlightGStateIndex, pfGetHlightGStateIndex, pfHlightTex, pfGetHlightTex,
pfHlightTEnv, pfGetHlightTEnv, pfHlightTGen, pfGetHlightTGen,
pfGetCurHlight - Control, create, modify and query highlight state
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfHighlight* pfNewHlight(void *arena);
pfType * pfGetHlightClassType(void);
void pfApplyHlight(pfHighlight * hl);
void pfHlightMode(pfHighlight *hl, uint mode);
uint pfGetHlightMode(const pfHighlight *hl);
void pfHlightColor(pfHighlight *hl, uint which, float r,
float g, float b);
void pfGetHlightColor(const pfHighlight *hl, uint which,
float *r, float *g, float *b);
void pfHlightAlpha(pfHighlight *hl, float a);
float pfGetHlightAlpha(const pfHighlight *hl);
void pfHlightNormalLength(pfHighlight* hl, float length,
float bboxScale);
void pfGetHlightNormalLength(const pfHighlight* hl,
float *length, float *bboxScale);
void pfHlightLineWidth(pfHighlight* hl, float width );
float pfGetHlightLineWidth(const pfHighlight* hl);
void pfHlightPntSize(pfHighlight* hl, float size );
float pfGetHlightPntSize(const pfHighlight* hl);
void pfHlightLinePat(pfHighlight* hl, int which, ushort pat);
Page 1
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
ushort pfGetHlightLinePat(const pfHighlight* hl, int which);
void pfHlightFillPat(pfHighlight* hl, int which,
uint *fillPat );
void pfGetHlightFillPat(const pfHighlight* hl, int which,
uint *pat);
void pfHlightGState(pfHighlight* hl, pfGeoState *gstate);
pfGeoState * pfGetHlightGState(const pfHighlight* hl);
void pfHlightGStateIndex(pfHighlight* hl, int id);
int pfGetHlightGStateIndex(const pfHighlight* hl);
void pfHlightTex(pfHighlight* hl, pfTexture *tex);
pfTexture* pfGetHlightTex(const pfHighlight* hl);
void pfHlightTEnv(pfHighlight* hl, pfTexEnv *tev);
pfTexEnv* pfGetHlightTEnv(const pfHighlight* hl);
void pfHlightTGen(pfHighlight* hl, pfTexGen *tgen);
pfTexGen* pfGetHlightTGen(const pfHighlight* hl);
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. Casting an object of
class pfHighlight 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);
Page 2
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
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
hl identifies a pfHighlight.
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 pfApplyHlight, and added to a specific pfGeoState
with pfGStateMode. 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 pfGSetHlight. 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
Page 3
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
slightly slower path in OpenGL Performer rendering code.
pfNewHlight creates and returns a handle to a pfHighlight. arena
specifies a malloc arena out of which the pfHighlight is allocated or
NULL for allocation off the process heap. pfHighlights can be deleted
with pfDelete.
pfGetHlightClassType returns the pfType* for the class pfHighlight. The
pfType* returned by pfGetHlightClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfHighlight.
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.
pfApplyHlight makes hl the current active pfHighlight structure.
pfGetCurHlight returns a pointer to the current active pfHighlight
structure.
pfHlightGState sets a highlighting pfGeoState of hl 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.
pfGetHlightGState returns the previously set highlighting pfGeoState of
hl. pfHlightGStateIndex specifies the index into a pfGeoState table to
use for the highlighting pfGeoState. pfGetHlightGStateIndex returns the
previously set highlighting pfGeoState index of hl.
pfHlightMode sets the highlighting mode mode for hl. 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 pfHlightLineWidth, length
determined by pfHlightNormalLength, and color
determined by pfHlightColor.
PFHL_BBOX_LINES Selects the display of the object's cached
bounding box in lines of width determined by
pfHlightLineWidth and color determined by
pfHlightColor.
Page 4
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PFHL_BBOX_FILL Selects the display of the object's cached
bounding box as a solid filled box of the
foreground color of hl.
PFHL_LINES Selects outlining of primitives. The lines are
drawn of width determined by pfHlightLineWidth
and color determined by pfHlightColor.
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 pfHlightTex, pfHlightTEnv, and
pfHlightTGen.
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.
Page 5
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfGetHlightMode returns the highlighting mode of hl.
pfHlightColor sets the specified highlighting color color, PFHL_FGCOLOR
or PFHL_BGCOLOR, of hl, to r, g, and b. pfGetHlightColor copies the
specified color, PFHL_FGCOLOR or PFHL_BGCOLOR, of hl, into r, g, and b.
pfHlightAlpha sets the alpha of hl to a. pfGetHlightAlpha returns the
alpha of hl.
pfHlightLineWidth sets the line width to be used for the PFHL_LINES,
PFHL_NORMALS, and PFHL_BBOX highlighting modes of hl 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.
pfGetHlightLineWidth returns the line width of hl.
pfHlightNormalLength 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. pfGetHlightNormalLength will
return the normal length and scale values of hl in length and bboxScale,
respectively.
pfHlightPntSize sets the point size to be used for the PFHL_POINTS
highlighting mode of hl 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. pfGetHlightPntSize returns the
point size of hl.
pfHlightLinePat sets the pattern to be used for lines in the PFHL_LINES
highlighting modes of hl to pat. pfGetHlightLinePat returns the
highlighting line pattern of hl. 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.
pfHlightFillPat sets the fill pattern to be used in the PFHL_FILLPAT
highlighting modes of hl to pat. pfGetHlightFillPat returns the
highlighting fill pattern of hl.
pfHlightTex sets the pfTexture for the PFHL_TEX highlighting modes of hl
to tex. pfGetHlightTex returns the previously set highlighting texture
of hl. If a texture is not specified but the PFHL_TEX is selected for
hl, a default two-component texture using the highlighting foreground and
background colors will be used.
pfHlightTEnv sets the texture environment (pfTexEnv) for the PFHL_TEX
highlighting modes of hl to tev. pfGetHlightTEnv returns the previously
set highlighting texture environment of hl. If a texture environment is
not specified but the PFHL_TEX is selected for hl, a default texture
blend environment will be used.
pfHlightTGen sets the texture coordinate generation attribute (pfTexGen)
for the PFHL_TEX highlighting modes of hl to tgen. pfGetHlightTGen
returns the previously set highlighting pfTexGen of hl. If a texture
Page 6
pfHighlight(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
coordinate generation function is not specified and the object to be
highlighted has no texture coordinates of its own and the PFHL_TEX is
selected for hl, 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 = pfNewHlight(NULL);
/* specify highlight modes */
pfHlightMode(hl, PFHL_FILL);
pfHlightColor(hl, PFHL_FGCOLOR, 1.0f, 0.0f, 1.0f);
/* apply highlight */
pfApplyHlight(hl);
SEE ALSO
pfDelete, pfDisable, pfDrawHlightedGSet, pfEnable, pfGSetHlight,
pfGeoState, pfGetGSetHlight, pfObject, pfOverride, pfState
Page 7
