pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfGeoState, pfGetCurGState, pfGetCurGStateTable, pfGetCurIndexedGState -
Create, modify and query geometry state objects
FUNCTION SPECIFICATION
#include <Performer/pr/pfGeoState.h>
pfGeoState::pfGeoState()
static pfType * pfGeoState::getClassType(void);
void pfGeoState::apply(void);
void pfGeoState::load(void);
void pfGeoState::setMode(uint64_t mode, int val);
int pfGeoState::getMode(uint64_t mode);
int pfGeoState::getCurMode(uint64_t mode);
int pfGeoState::getCombinedMode(uint64_t mode,
const pfGeoState *combGState);
void pfGeoState::setMultiMode(uint64_t mode, int index,
int val);
int pfGeoState::getMultiMode(uint64_t mode, int index);
int pfGeoState::getCurMultiMode(uint64_t mode, int index);
int pfGeoState::getCombinedMultiMode(uint64_t mode,
int index, const pfGeoState *combGState);
void pfGeoState::setVal(uint64_t gsval, float val);
float pfGeoState::getVal(uint64_t gsval);
float pfGeoState::getCurVal(uint64_t gsval);
float pfGeoState::getCombinedVal(uint64_t gsval,
const pfGeoState *combGState);
void pfGeoState::setInherit(uint64_t mask);
uint64_t pfGeoState::getInherit(void);
void pfGeoState::setAttr(uint64_t attr, void *data);
void * pfGeoState::getAttr(uint64_t attr);
Page 1
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void* pfGeoState::getCurAttr(uint64_t attr);
void* pfGeoState::getCombinedAttr(uint64_t attr,
const pfGeoState *combGState);
void pfGeoState::setMultiAttr(uint64_t attr, int index,
void *data);
void * pfGeoState::getMultiAttr(uint64_t attr, int index);
void* pfGeoState::getCurMultiAttr(uint64_t attr, int index);
void* pfGeoState::getCombinedMultiAttr(uint64_t attr,
int index, const pfGeoState *combGState);
void pfGeoState::setFuncs(pfGStateFuncType preFunc,
pfGStateFuncType postFunc, void *data);
void pfGeoState::getFuncs(pfGStateFuncType *preFunc,
pfGStateFuncType *postFunc, void **data);
static void pfGeoState::applyTable(pfList *gstab);
void pfGeoState::makeBasic(void);
int pfGeoState::getNumTextures();
pfGeoState * pfGetCurGState(void);
pfList* pfGetCurGStateTable(void);
pfGeoState* pfGetCurIndexedGState(int index);
typedef int (*pfGStateFuncType)(pfGeoState *gstate, void *userData);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfGeoState is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfGeoState. 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);
Page 2
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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 pfGeoState 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 pfGeoState is an encapsulation of libpr graphics modes and attributes
(see pfState). For example, a pfGeoState can describe a glass surface by
referencing a shiny pfMaterial and enabling transparency. When a
pfGeoState is applied by pfGeoState::apply it sets up the graphics state
through normal libpr routines such as pfMaterial::apply and
pfTransparency.
Most pieces of state that may be manipulated through libpr immediate mode
routines may be specified on a per-pfGeoState basis. For customized
state management, pfGeoStates provide function callbacks. In addition,
pfGeoStates can be indexed through a global table so a single database
can have multiple appearances while avoiding database duplication.
The primary use of a pfGeoState is to attach it to a pfGeoSet (-
pfGeoSet::setGState) in order to define the appearance of the geometry
encapsulated by the pfGeoSet. As discussed below, pfGeoStates have the
useful property of order-independence so that paired pfGeoSets and
pfGeoStates will be rendered consistently regardless of order.
pfGeoState state may either be locally set or globally inherited. By
default, if a state element is not specified on a pfGeoState, then that
pfGeoState will inherit that state element from the global state. Global
Page 3
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
state is set through libpr immediate mode functions, e.g.,
pfMaterial::apply, pfTransparency, pfDecal, pfFog::apply or through
pfGeoState::load as described below. Local state is set on a pfGeoState
through pfGeoState::setMode, pfGeoState::setAttr, or pfGeoState::setVal.
If all state elements are locally set, then a pfGeoState becomes a full
graphics context since all state is defined at the pfGeoState level.
While this is useful, it usually makes sense to inherit most state from
global default values and explicitly set only those state elements which
are expected to change often. Examples of useful global defaults are
lighting model (pfLightModel), lights (pfLight), fog (pfFog), and
transparency (pfTransparency, usually OFF). Highly variable state is
likely to be limited to a small set like textures and materials. By
default all pfGeoState state is inherited.
State is pushed before, and popped after pfGeoStates are applied so that
pfGeoStates do not inherit state from each other. As a result
pfGeoStates are order-independent and you need not consider the problem
of one pfGeoState corrupting another by state inheritance through the
underlying graphics library. The actual pfGeoState pop is a lazy one and
does not happen unless a subsequent pfGeoState needs the default state
restored. This means that the actual state between pfGeoStates is not
necessarily the global state. If a return to global state is required,
call pfFlushState which will restore the global state.
It is a performance advantage to locally set as little local pfGeoState
state as possible. This may be accomplished by setting global defaults
which satisfy the majority of pfGeoStates being drawn. For example, if
most of your database is textured, you should enable texturing at
initialization time (pfEnable(PFEN_TEXTURE)) and configure your
pfGeoStates to inherit the texture enable mode.
new(arena) allocates a pfGeoState from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfGeoState from
the default memory arena (see pfGetSharedArena). Like other pfObjects,
pfGeoStates cannot be created statically, automatically on the stack or
in arrays. pfGeoStates should be deleted with pfDelete rather than the
delete operator. All modes and attributes are inherited by default.
pfGeoState::getClassType returns the pfType* for the class pfGeoState.
The pfType* returned by pfGeoState::getClassType is the same as the
pfType* returned by invoking the virtual function getType on any instance
of class pfGeoState. 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 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.
pfGeoState::setMode sets mode to val. mode is a symbolic constant
specifying the mode to set. Once set, a mode is no longer inherited but
is set to val. mode is a symbolic token and is one of:
Page 4
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFSTATE_TRANSPARENCY
PFSTATE_ANTIALIAS
PFSTATE_DECAL
PFSTATE_ALPHAFUNC
PFSTATE_SHADEMODEL
PFSTATE_ENLIGHTING
PFSTATE_ENTEXTURE
PFSTATE_ENFOG
PFSTATE_CULLFACE
PFSTATE_ENWIREFRAME
PFSTATE_ENCOLORTABLE
PFSTATE_ENHIGHLIGHTING
PFSTATE_ENLPOINTSTATE
PFSTATE_ENTEXGEN
PFSTATE_ENTEXLOD
PFSTATE_ENTEXMAT
PFSTATE_ENFRAGPROG
PFSTATE_ENVTXPROG
PFSTATE_ENSHADPROG
val specifies the value of mode and is a symbolic token appropriate to
the type of mode. For example when mode = PFSTATE_TRANSPARENCY then val
might be PFTR_ON. Only modes which differ from the global state should
be set. Mode values are not inherited between pfGeoStates. By default
all modes are inherited. See the pfState manual page for information on
global default settings.
pfGeoState::setVal sets the gsval value to val. gsval is a symbolic
constant specifying the state value to set. Once set, a value is no
longer inherited but is set to val. gsval is a symbolic token and can be
chosen from any of the following list (only one choice at present):
PFSTATE_ALPHAREF
pfGeoState::setAttr sets attr state element to a. attr is a symbolic
constant starting with PFSTATE_ specifying an attribute and is combined
with data, a handle to an attribute structure of the appropriate libpr
object relevant to attr.
PFSTATE_FRONTMTL pfMaterial*
PFSTATE_BACKMTL pfMaterial*
PFSTATE_TEXTURE pfTexture*
PFSTATE_TEXENV pfTexEnv*
PFSTATE_FOG pfFog*
PFSTATE_LIGHTMODEL pfLightModel*
Page 5
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFSTATE_LIGHTS pfLight**
PFSTATE_COLORTABLE pfColortable*
PFSTATE_HIGHLIGHT pfHighlight*
PFSTATE_LPOINTSTATE pfLPointState*
PFSTATE_TEXGEN pfTexGen*
PFSTATE_TEXLOD pfTexLOD*
PFSTATE_TEXMAT pfMatrix*
PFSTATE_DECALPLANE pfPlane*
PFSTATE_COMBINER pfCombiner*
PFSTATE_FRAGPROG pfFragmentProgram*
PFSTATE_VTXPROG pfVertexProgram*
PFSTATE_GPROGPARMS pfGProgramParms*
PFSTATE_SHADPROG pfShaderProgram*
If attr is PFSTATE_LIGHTS, a should be an array of pfLight* of length
PF_MAX_LIGHTS which specifies which pfLights should be used by the
pfGeoState. Empty entries in the light array should be NULL.
A pfGeoState ignores the PFMTL_FRONT and PFMTL_BACK setting of a
pfMaterial (see pfMaterial::setSide). Instead it uses the attribute
value, PFSTATE_FRONTMTL or PFSTATE_BACKMTL to decide how to apply the
material. Consequently, it is legal to use the same material for both
front and back sides. However, pfGeoStates do not modify the
pfMaterial's side value which is normally set through
pfMaterial::setSide.
Once set, an attribute is no longer inherited but set to a. Only
attributes which differ from the global state should be set. Attributes
are not inherited between pfGeoStates. By default, all attributes are
inherited from the global state.
pfGeoState::setAttr increments the reference count of the supplied
attribute and decrements the reference count of the replaced attribute,
if there is one. pfGeoState::setAttr will not delete any pfObject whose
reference count reaches 0.
pfGeoState supports a few multi-valued elements. At present, all these
multi-valued elements are related to the multi-texture OpenGL extension.
The multi-texture extension enables the application of multiple texture
maps on a single polygon in a single drawing pass. This extension uses
Page 6
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
multiple texture environments to determine the blending among the texture
units. All pfGeoState methods that set/get attributes and modes have
multi-valued versions. The multi-valued versions take one additional
parameter: index. In the case of the multi-texture extension, this
variable picks the hardware texture unit that an attribute or a value
refer to.
pfGeoState::setMultiAttr is a version of pfGeoState::setAttr used for
setting multi-valued attributes. A multi-values attribute collapses a set
of attributes into a single pfGeoState attribute. index picks the texture
unit that attr will be applied to. The following attribute tokens have
multiple values:
PFSTATE_TEXTURE
PFSTATE_TEXENV
PFSTATE_TEXGEN
PFSTATE_TEXLOD
PFSTATE_TEXMAT
PFSTATE_GPPROGPARMS
Similarly, pfGeoState::getMultiAttr, pfGeoState::getCurMultiAttr and
pfGeoState::getCombinedMultiAttr are multi-valued versions of
pfGeoState::getAttr, pfGeoState::getCurAttr and
pfGeoState::getCombinedAttr. All accept the above multi-value attribute
tokens.
pfGeoState::setMultiMode is a multi-value version of pfGeoState::setMode.
It sets the index-th element of mode to val. It accepts the following
multi-value mode tokens:
PFSTATE_ENTEXTURE
PFSTATE_ENTEXGEN
PFSTATE_ENTEXLOD
PFSTATE_ENTEXMAT
Similarly, pfGeoState::getMultiMode, pfGeoState::getCurMultiMode and
pfGeoState::getCombinedMultiMode are multi-value versions of
pfGeoState::getMode, pfGeoState::getCurMode and
pfGeoState::getCombinedMode. All accept the above multi-value mode
tokens.
When (mode == PFSTATE_ENTEXTURE) pfGeoState expects a contiguous sequence
of enable values. The first disabled index in this mode determines how
many values pfGeoState recognizes. For example, when calling
gstate->setMultiMode(PFSTATE_ENTEXTURE, index, 1) for index=[0, 1, 3],
pfGeoState will process two texture units and will ignore the (index ==
3) case. In addition, if the current hardware doesn't support enough
multi-texture units, pfGeoState will issue a warning and ignore settings
for unavailable hardware texture units. pfGeoState::getNumTextures
returns the number of texture units that pfGeoState will process.
Calling a multi-value method with (index == 0) is equivalent to calling
Page 7
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
the single-value version of the method.
As discussed above, modes, values and attributes may either be locally
set on a pfGeoState or inherited from the global state. To help resolve
the inheritance characteristics of pfGeoStates, 3 different versions of
"get" routines are provided for modes, values and attributes:
1. pfGeoState::getMode, pfGeoState::getVal, pfGeoState::getAttr -
The exact mode, value, or attribute of the pfGeoState is
returned.
2. pfGeoState::getCurMode, pfGeoState::getCurVal,
pfGeoState::getCurAttr - The exact mode, value, or attribute of
the pfGeoState is returned if not inherited. Otherwise the
mode, value, or attribute of the currently active global
pfGeoState is returned. Note that this requires that a pfState
be current (see pfState::select).
3. pfGeoState::getCombinedMode, pfGeoState::getCombinedVal,
pfGeoState::getCombinedAttr - The exact mode, value, or
attribute of the pfGeoState is returned if not inherited.
Otherwise the mode, value, or attribute of the combGState is
returned.
pfGeoState::getMode returns the mode value corresponding to mode.
pfGeoState::getVal returns the pfGeoState value corresponding to gsval.
pfGeoState::getAttr returns the attribute handle corresponding to attr.
If attr is PFSTATE_LIGHTS, the returned value is the pfLight* array.
pfGeoState::setInherit specifies which state elements should be inherited
from the global state. mask is a bitwise OR of tokens listed for
pfGeoState::setMode, pfGeoState::setAttr, and pfGeoState::setVal. All of
the state elements specified in mask will become inherited. All modes
and attributes are inherited unless explicitly specified by setting a
mode or attribute with pfGeoState::setAttr, pfGeoState::setMode, or
pfGeoState::setVal. pfGeoState::getInherit returns the bitwise OR of the
tokens for state which is currently inherited from the global state.
pfGeoState::apply makes the pfGeoState the current graphics state. All
modes and attributes of the pfGeoState that are not inherited are applied
using libpr immediate mode commands, for example, the PFSTATE_TEXTURE
attribute is applied with pfTexture::apply. Inherited modes and
attributes that were modified by previous pfGeoStates are reset to their
global values. State elements that are overridden (See pfOverride) are
not changed by pfGeoState::apply.
Another way to apply a pfGeoState is with pfGeoSet::draw. If a pfGeoSet
has an attached pfGeoState (see pfGeoSet::setGState), then pfGeoSet::draw
will call pfGeoState::apply with the attached pfGeoState so that graphics
state is properly established before the pfGeoSet geometry is rendered.
Page 8
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
The following is an example of pfGeoState behavior.
Example 1:
/* Configure global default that pfGeoStates can inherit */
pfLightModel *lmodel = new pfLightModel;
pfLight *light = new pfLight;
pfEnable(PFEN_LIGHTING);
lmodel->apply();
light->on();
pfTransparency(PFTR_OFF);
/* New pfGeoState inherits everything */
gstate = new pfGeoState;
/* Attach 'gstate' to 'gset' */
gset->setGState(gstate);
/* Configure 'gstate' with a transparent material */
gstate->setAttr(PFSTATE_FRONTMTL, mtl);
gstate->setMode(PFSTATE_TRANSPARENCY, PFTR_ON);
Method A:
/* Draw transparent 'gset' */
gset->draw();
Method B:
/* Remove 'gstate' from 'gset' */
gset->setGState(NULL);
/* Apply 'gstate' */
gstate->apply();
/* Draw transparent 'gset' */
gset->draw();
Method C:
/* Remove 'gstate' from 'gset' */
gset->setGState(NULL);
mtl->apply();
pfTransparency(PFTR_ON);
Page 9
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
/* Draw transparent 'gset' */
gset->draw();
In the above example, methods A, B, and C are all produce the same visual
result. Method A is recommended, however, since the pfGeoState and
pfGeoSet pair may be configured at database initialization time and the
use of a pfGeoState provides order-independence when rendering.
The following is an example of pfGeoState inheritance:
pfLightModel *lmodel = new pfLightModel;
pfLight *light = new pfLight;
/* Configure global default that pfGeoStates can inherit */
pfEnable(PFEN_LIGHTING);
lmodel->apply();
light->on();
/* Assume 'redMtl' is PFMTL_FRONT */
redMtl->apply();
/* New pfGeoStates inherit everything */
gstateA = new pfGeoState;
gstateB = new pfGeoState;
/* Attach pfGeoStates to pfGeoSets */
gsetA->setGState(gstateA);
gsetB->setGState(gstateB);
/* Configure 'gstateA' with a green material */
gstateA->setAttr(PFSTATE_FRONTMTL, greenMtl);
/* Draw green 'gset' */
gsetA->draw();
/*
* The FRONTMTL property of gstateB is not set so it inherits
* the global default of 'redMtl' which will be restored
* as the current pfMaterial when gstateB is applied.
*/
/* Draw red 'gset' */
gsetB->draw();
/*
* Note that gsetA and gsetB could be drawn in the opposite
* order with the same results. This is a very important
* pfGeoState property.
*/
Page 10
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfGetCurGState returns the current pfGeoState that was previously applied
directly by pfGeoState::apply or indirectly by pfGeoSet::draw.
pfGeoState::setFuncs sets the callbacks and callback data pointer of the
pfGeoState. The reference count of data is incremented and the reference
count of the previous data is decremented but no deletion takes place if
the reference count reaches 0. Callbacks are invoked by pfGeoState::apply
(or indirectly by pfGeoSet::draw as described above) in the following
order:
postFunc() of previously-applied pfGeoState
setup state according to current pfGeoStatepreFunc() of current pfGeoState
Notice that the post-callback invocation is delayed until a subsequent
pfGeoState is applied. However, pfPushState, pfPopState, and pfFlushState
will invoke any "leftover" post-callback. It is legal to call
pfPushState and pfPopState in the pre and post callbacks respectively but
is not usually necessary because any libpr state set inside pfGeoState
callbacks is considered to have been set by the pfGeoState. Consequently,
the global state is not modified and the normal pfGeoState inheritance
rules apply to state set inside the callbacks.
Callbacks are passed a pointer to the parent pfGeoState and the data
pointer that was previously supplied by pfGeoState::setFuncs. The return
value from pfGeoState callbacks is currently ignored.
pfGeoState::getFuncs gets back the pre and post pfGeoState callbacks and
callback data for the pfGeoState in preFunc, postFunc, and data,
respectively.
A pfGeoSet may either directly reference or indirectly index a pfGeoState
with pfGeoSet::setGState and pfGeoSet::setGStateIndex respectively.
Indexed pfGeoStates use a global table of pfGeoState pointers that is set
by pfGeoState::applyTable. If the global table is NULL or the pfGeoState
index is out of the range of the global table, no pfGeoState is applied,
otherwise the indexed pfGeoState is applied when pfGeoSet::draw is
called. Non-indexed pfGeoState references ignore the current pfGeoState
table. pfGetCurGStateTable returns the current pfGeoState table and
pfGetCurIndexedGState returns the indexth pfGeoState* in the current
pfGeoState table or NULL if the index cannot be properly resolved.
pfGeoState::load is similar to pfGeoState::apply except the modes and
attributes of the pfGeoState can be inherited by subsequent pfGeoStates.
In other words, the pfGeoState loads the global state. Overridden state
elements are not modified by pfGeoState::load. If set, the pre-callback
of the pfGeoState is invoked after the graphics state is loaded. As
described above, the post-callback is not invoked until a subsequent
pfGeoState is applied or pfPushState, pfPopState, or pfFlushState is
called.
Page 11
pfGeoState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfGeoState::apply, pfGeoState::applyTable, and pfGeoState::load are
display-listable commands. If a pfDispList has been opened by
pfDispList::open, these commands will not have immediate effect but will
be captured by the pfDispList and will only have effect when that
pfDispList is later executed with pfDispList::draw. Indexed pfGeoStates
are resolved at display list creation time, not at display list execution
time. In addition, pfGeoStates are "unwound" into their constituent parts
at display list creation time, e.g., a pfGeoState may decompose into
pfMaterial::apply and pfTransparency calls. As a result, changes to a
pfGeoState which have been captured by a pfDispList will *not* be evident
when that pfDispList is executed (pfDispList::draw). pfGeoState indexing
and unwinding at display list creation time is done strictly to improve
pfDispList rendering performance.
pfGeoState::makeBasic configures every state element (value, mode, and
attribute) of the pfGeoState to be identical to the state set with
pfBasicState. The "basic" state is the initial state of a graphics
library window - everything is "off". For example, the PFSTATE_ENLIGHTING
mode will be set to PF_OFF, and the PFSTATE_CULLFACE mode will be set to
PFCF_OFF. The following code fragment is equivalent to pfBasicState:
pfGeoState *gstate = new(NULL)pfGeoState();
gstate->makeBasic();
gstate->load();
NOTES
In some situations it may appear that pfGeoStates do inherit from each
other. This is because OpenGL Performer currently does not provide any
defaults for the state attributes listed above such as PFSTATE_TEXTURE
and PFSTATE_FRONTMTL. Consequently, if the application does not
explicitly set these attributes, it is possible for pfGeoStates which
inherit these attributes to inherit them from previous pfGeoStates.
SEE ALSO
pfAlphaFunc, pfAntialias, pfBasicState, pfCullFace, pfDecal, pfDelete,
pfDispList, pfDrawGSet, pfEnable, pfFog, pfGeoSet, pfLight, pfList,
pfLPointState, pfOverride, pfShadeModel, pfState, pfTexture, pfTexGen,
pfTransparency
Page 12
