pfState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfState(3pf)NAME
pfNewState, pfGetStateClassType, pfSelectState, pfLoadState,
pfAttachState, pfInitState, pfGetCurState, pfPushState, pfPopState,
pfGetState, pfFlushState, pfBasicState, pfPixScale, pfGetPixScale -
Create, modify and query graphics state
FUNCTION SPECIFICATION
#include <ulocks.h>
#include <Performer/pr.h>
pfState * pfNewState(void *arena);
pfType * pfGetStateClassType(void);
void pfSelectState(pfState *state);
void pfLoadState(pfState *state);
void pfAttachState(pfState *state, 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. Casting an object of
class pfState 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);
Page 1
pfState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfState(3pf)
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 pfState 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);
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 pfApply<*> 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
pfApplyMtl. Each mode and attribute is identified by a PFSTATE_ token.
These tokens are used in pfGStateMode and pfGStateAttr 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 pfApplyLModel NULL
pfLights LIGHTS pfLightOn all NULL
front pfMaterial FRONTMTL pfApplyMtl NULL
back pfMaterial BACKMTL pfApplyMtl NULL
pfTexEnv TEXENV pfApplyTEnv NULL
pfTexture TEXTURE pfApplyTex NULL
pfTexGen TEXGEN pfApplyTGen NULL
pfTexLOD TEXLOD pfApplyTLOD NULL
texture matrix TEXMAT pfApplyTMat NULL
pfFog FOG pfApplyFog NULL
pfColortable COLORTABLE pfApplyCtab NULL
pfHighlight HIGHLIGHT pfApplyHlight NULL
pfLPointState LPOINTSTATE pfApplyLPState NULL
pfPlane DECAL_PLANE pfApplyDecalPlane NULL
pfFragmentProgram FRAGPROG pfGProgramApply NULL
pfVertexProgram VTXPROG pfGProgramApply NULL
pfGProgramParms GPROGPARMS pfGPParamsApply NULL
pfShaderProgram SHADPROG pfSProgApply 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
pfDrawDList.
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 pfSelectState. 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 */
pfDrawGSet(gset);
Example 2:
/* Enter display list mode by opening 'dlist' for appending */
pfOpenDList(dlist);
pfEnable(PFEN_WIREFRAME);
pfDrawGSet(gset);
pfCloseDList();
/* Draw 'gset' in wireframe */
pfDrawDList(dlist);
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
pfGStateMode and pfGStateAttr it is possible to set every state element
of a pfGeoState. When the pfGeoState is applied through pfApplyGState
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 (pfGSetGState).
In this way the pfGeoState defines the graphics state of the geometry
encapsulated by the pfGeoSet (pfDrawGSet will call pfApplyGState if the
pfGeoSet has an attached pfGeoState).
Example 3:
/* Set up wireframe pfGeoState */
gstate = pfNewGState(NULL);
pfGStateMode(gstate, PFSTATE_ENWIREFRAME, PF_ON);
/* Draw wireframe pfGeoSet in "pfGeoState" mode */
pfApplyGState(gstate); /* Apply 'gstate' */
pfDrawGSet(gset); /* Draw 'gset' in wireframe */
/* Preferred method for drawing wireframe pfGeoSet */
pfGSetGState(gset, gstate); /* Attach 'gstate' to 'gset' */
pfDrawGSet(gset); /* 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.
pfNewState creates and returns a handle to a pfState. arena specifies a
malloc arena out of which the pfState is allocated or NULL for allocation
off the process heap. pfStates can be deleted with pfDelete.
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.
pfGetStateClassType returns the pfType* for the class pfState. The
pfType* returned by pfGetStateClassType is the same as the pfType*
returned by invoking pfGetType 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 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.
Page 5
pfState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfState(3pf)
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 pfSelectState.
pfSelectState makes state the current state. pfState is a global value
so it is shared by all share group processes(See sproc). pfSelectState
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
useful for drawing things like text which usually should not be lit or
fogged. Specifically, pfBasicState is equivalent to the following:
Page 6
pfState(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfState(3pf)
/* 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 pfMakeBasicGState to configure every state element (value, mode, and
attribute) of gstate to be identical to the state set with pfBasicState.
The following code fragment is equivalent to pfBasicState:
pfGeoState *gstate = pfNewGState(NULL);
pfMakeBasicGState(gstate);
pfLoadGState(gstate);
Each of pfSelectState, 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
