pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)NAME
pfState, pfInitState, pfGetCurState, pfPushState, pfPopState, pfGetState,
pfFlushState, pfBasicState, pfPixScale, pfGetPixScale - Create, modify
and query graphics state
FUNCTION SPECIFICATION
#include <ulocks.h>
#include <Performer/pr/pfState.h>
pfState::pfState();
static pfType * pfState::getClassType(void);
void pfState::select(void);
void pfState::load(void);
void pfState::attach(pfState *state1);
void pfInitState(usptr_t* arena);
pfState * pfGetCurState(void);
void pfPushState(void);
void pfPopState(void);
void pfGetState(pfGeoState *gstate);
void pfFlushState(void);
void pfBasicState(void);
void pfPixScale(float scale);
float pfGetPixScale(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfState is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfState. 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 1
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
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 pfState 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
OpenGL Performer manages a subset of the graphics library state for
convenience and improved performance. Further, this state is conceptually
partitioned into two divisions: modes and attributes. A mode is a simple
"setting" usually represented by a single value while an attribute is a
larger collection of related modes that is encapsulated in an OpenGL
Performer structure, such as pfFog.
Modes usually have two routines to set and get them while attributes have
many routines for accessing their parameters and a pf<*>::apply routine
which "applies" the attribute's characteristics to the graphics system
via graphics library state commands. Modes are represented by basic data
types like 'int' and 'float' while attributes are pointers to opaque
OpenGL Performer structures whose contents are accessible only through
function calls.
An example of a mode is the shading model set by pfShadeModel and an
attribute is exemplified by a pfMaterial which is applied with
pfMaterial::apply. Each mode and attribute is identified by a PFSTATE_
token. These tokens are used in pfGeoState::setMode and
pfGeoState::setAttr when initializing a pfGeoState and in pfOverride to
override mode and attribute settings.
Page 2
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
The following table lists the state components that are modes.
Mode PFSTATE_ Token Routine(s) Default
______________________________________________________________________________
Transparency TRANSPARENCY pfTransparency PFTR_OFF
Antialiasing ANTIALIAS pfAntialias PFAA_OFF
Decal DECAL pfDecal PFDECAL_OFF
Face culling CULLFACE pfCullFace PFCF_OFF
Alpha function ALPHAFUNC pfAlphaFunc PFAF_ALWAYS
Alpha reference ALPHAREF pfAlphaFunc 0
Lighting enable ENLIGHTING pfEnable/pfDisable PF_OFF
Texturing enable ENTEXTURE pfEnable/pfDisable PF_OFF
Fogging enable ENFOG pfEnable/pfDisable PF_OFF
Wireframe enable ENWIREFRAME pfEnable/pfDisable PF_OFF
Colortable enable ENCOLORTABLE pfEnable/pfDisable PF_OFF
Highlighting enable ENHIGHLIGHTING pfEnable/pfDisable PF_OFF
Light Point enable ENLPOINTSTATE pfEnable/pfDisable PF_OFF
TexGen enable ENTEXGEN pfEnable/pfDisable PF_OFF
TexMat enable ENTEXMAT pfEnable/pfDisable PF_OFF
TexLOD enable ENTEXLOD pfEnable/pfDisable PF_OFF
Fragment Program enable ENFRAGPROG pfEnable/pfDisable PF_OFF
Vertex Program enable ENVTXPROG pfEnable/pfDisable PF_OFF
GLSL Shader Program enable ENSHADPROG pfEnable/pfDisable PF_OFF
|
|
|
The following table lists the state components that are attributes.
Attribute PFSTATE_ Token Routine Default
________________________________________________________________________
pfLightModel LIGHTMODEL pfLightModel::apply NULL
pfLights LIGHTS pfLight::on all NULL
front pfMaterial FRONTMTL pfMaterial::apply NULL
back pfMaterial BACKMTL pfMaterial::apply NULL
pfTexEnv TEXENV pfTexEnv::apply NULL
pfTexture TEXTURE pfTexture::apply NULL
pfTexGen TEXGEN pfTexGen::apply NULL
pfTexLOD TEXLOD pfTexLOD::apply NULL
texture matrix TEXMAT pfApplyTMat NULL
pfFog FOG pfFog::apply NULL
pfColortable COLORTABLE pfColortable::apply NULL
pfHighlight HIGHLIGHT pfHighlight::apply NULL
pfLPointState LPOINTSTATE pfLPointState::apply NULL
pfPlane DECAL_PLANE pfApplyDecalPlane NULL
pfFragmentProgram FRAGPROG pfFragmentProgram::apply NULL
pfVertexProgram VTXPROG pfVertexProgram::apply NULL
pfGProgramParms GPROGPARMS pfGProgramParams::apply NULL
pfShaderProgram SHADPROG pfShaderProgram::apply NULL
|
|
|
State values may be established within libpr in one of three ways:
1. Immediate mode
Page 3
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
2. Display list mode
3. pfGeoState mode
Like the graphics library itself, OpenGL Performer has two command
execution modes: immediate mode and display list mode. In immediate
mode, the setting of a mode or the application of an attribute is carried
out immediately. Any geometry rendered afterwards will be drawn with
that mode or attribute characteristics. In display list mode, the
command will be "captured" by the open display list (pfDispList) and will
not have effect until the display list is closed and later drawn with
pfDispList::draw.
All the routines listed in Table 1 are display-listable, which is to say
that they will be captured by an open pfDispList. In immediate mode,
most of the above routines send command tokens to the graphics pipeline.
Thus, the process invoking these commands must have a graphics context
open to accept the command tokens, otherwise a segmentation violation or
similar severe exception will result. In addition to an open graphics
context, a global pfState must have been selected by pfState::select.
Note that neither a graphics context nor pfState is required when drawing
in display list mode because the commands will be captured by the display
list.
Example 1:
/* Enable wireframe in immediate mode */
pfEnable(PFEN_WIREFRAME);
/* Draw 'gset' in wireframe */
gset->draw();
Example 2:
/* Enter display list mode by opening 'dlist' for appending */
dlist->open();
pfEnable(PFEN_WIREFRAME);
gset->draw();
pfDispList::close();
/* Draw 'gset' in wireframe */
dlist->draw();
It is important to realize that OpenGL Performer display lists
(pfDispLists) are different from graphics library display lists. A
pfDispList captures only libpr commands and does not contain low-level
geometric information like vertex coordinates and colors.
Page 4
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
The pfGeoState encapsulates all of libpr state, i.e. it has all mode
settings and a pointer to a definition for each attribute type. Through
pfGeoState::setMode and pfGeoState::setAttr it is possible to set every
state element of a pfGeoState. When the pfGeoState is applied through
pfGeoState::apply all the state settings encapsulated by the pfGeoState
become active. pfGeoStates also have useful inheritance properties that
are discussed in the pfGeoState man page. Typical use of a pfGeoState is
to "build" it at database initialization time and attach it to a pfGeoSet
(pfGeoSet::setGState). In this way the pfGeoState defines the graphics
state of the geometry encapsulated by the pfGeoSet (pfDrawGSet will call
pfGeoState::apply if the pfGeoSet has an attached pfGeoState).
Example 3:
/* Set up wireframe pfGeoState */
gstate = new pfGeoState;
gstate->setMode(PFSTATE_ENWIREFRAME, PF_ON);
/* Draw wireframe pfGeoSet in "pfGeoState" mode */
gstate->apply(); /* Apply 'gstate' */
gset->draw(); /* Draw 'gset' in wireframe */
/* Preferred method for drawing wireframe pfGeoSet */
gset->setGState(gstate); /* Attach 'gstate' to 'gset' */
gset->draw(); /* Draw 'gset' in wireframe */
pfInitState initializes internal OpenGL Performer state. arena specifies
a shared semaphore arena created by usinit for multiprocess operation of
OpenGL Performer or NULL for single process operation. For proper
multiprocess operation, pfInitState should be called by a single process
before calls to sproc or fork that will generate other processes using
OpenGL Performer state, with an arena which is shared by all application
processes. In either single or multi-process operation, pfInitState must
be called before any state attributes such as pfTextures are created and
should only be called once.
new(arena) allocates a pfState from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfState from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfStates cannot be created statically, automatically on the stack or in
arrays. pfStates should be deleted with pfDelete rather than the delete
operator. Specifically, a pfState has a stack of state structures that
shadow OpenGL Performer and graphics library state. This stack may be
manipulated by routines described below.
pfState::getClassType returns the pfType* for the class pfState. The
pfType* returned by pfState::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfState. Because OpenGL Performer allows subclassing of built-in
types, when decisions are made based on the type of an object, it is
Page 5
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
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.
A pfState should be created for each graphics context that the process
draws to with libpr routines. When a process switches graphics contexts
it should also switch to the corresponding pfState with pfState::select.
pfState::select makes the pfState the current state. pfState is a global
value so it is shared by all share group processes(See sproc).
pfState::select should be used when switching between different graphics
contexts. It does not configure the graphics context with its state
settings. pfGetCurState returns a pointer to the current pfState or NULL
if there is no active pfState.
Each pfState structure maintains a 64-deep stack of pfGeoStates. A
pfGeoState shadows all libpr modes and attributes. Changes to the
current state made through any of the 3 methods listed above are recorded
in the top of the pfGeoState stack. pfGetState copies the top of the
pfGeoState stack into gstate.
pfPushState pushes the pfGeoState stack of the current pfState. When
pushed, the configuration of the current state is recorded so that when
popped, that state will be restored, overwriting any state changes made
between push and pop. The bit vector which represents state elements
that are overridden by pfOverride is also pushed.
pfPopState compares the current pfGeoState with that of the previously
pushed pfGeoState and calls graphics library routines to restore the
previously pushed state. The override bit vector is popped before
popping any state elements. State changes made to a graphics context
must be made using the OpenGL Performer for pfPushState and pfPopState to
work correctly. Calls made by the application directly to the graphics
library will circumvent OpenGL Performer state management which may or
may not be desired.
pfFlushState is only useful for applications which use pfGeoStates.
pfGeoStates do not inherit state from each other so state is pushed and
popped when drawing them. For performance, state is not actually popped
unless a subsequent pfGeoState requires it. This means that in-between
pfGeoStates, the state may not be what the application expects.
pfFlushState will return the state to the global default.(See pfGeoState
for more on state flushing). pfPushState calls pfFlushState.
pfPixScale sets scale as the value to be used in scaling point and line
width specifications. Global control of this scale factor is important
when Dynamic Video Resolution is in use, since points and lines must be
reduced in width as much as they are enlarged by the video output system
in order that the displayed geometry have the designated width in
display-pixel units. pfGetPixScale returns the current pixel scale value.
pfBasicState is a convenience routine for disabling all modes and is
Page 6
pfState(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfState(3pf)
useful for drawing things like text which usually should not be lit or
fogged. Specifically, pfBasicState is equivalent to the following:
/* return graphics pipeline to basic state */
pfDisable(PFEN_FOG);
pfDisable(PFEN_LIGHTING);
pfDisable(PFEN_TEXTURE);
pfDisable(PFEN_WIREFRAME);
pfDisable(PFEN_COLORTABLE);
pfDisable(PFEN_HIGHLIGHTING);
pfDisable(PFEN_LPOINTSTATE);
pfDisable(PFEN_TEXGEN);
pfDisable(PFEN_TEXMAT);
pfDisable(PFEN_FRAGPROG);
pfDisable(PFEN_VTXPROG);
pfDisable(PFEN_SHADPROG);
pfShadeModel(PFSM_GOURAUD);
pfAlphaFunc(0, PFAF_OFF);
pfCullFace(PFCF_OFF);
pfTransparency(PFTR_OFF);
if (multisampling-type antialiasing is not enabled)
pfAntialias(PFAA_OFF);
pfDecal(PFDECAL_OFF);
Use pfGeoState::makeBasic to configure every state element (value, mode,
and attribute) of the pfGeoState to be identical to the state set with
pfBasicState. The following code fragment is equivalent to pfBasicState:
pfGeoState *gstate = new(NULL)pfGeoState();
gstate->makeBasic();
gstate->load();
Each of pfState::select, pfPushState, pfPopState, pfFlushState, and
pfBasicState are display-listable commands.
SEE ALSO
pfAlphaFunc, pfAntialias, pfColortable, pfCullFace, pfDecal, pfDelete,
pfEnable, pfFog, pfFragmentProgram, pfGeoSet, pfGeoState, pfHighlight,
pfLight, pfLightModel, pfLPointState, pfMaterial, pfOverride,
pfShadeModel, pfShaderProgram, pfTexEnv, pfTexGen, pfTexture,
pfTransparency, pfVertexProgram
Page 7
