pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)NAME
pfNewShader, pfGetShaderClassType, pfShaderName, pfGetShaderName,
pfShaderOpenPass, pfShaderClosePass, pfGetShaderCurPassType,
pfGetShaderNumPasses, pfGetShaderCurPass, pfGetShaderPass,
pfGetShaderPassList, pfShaderPassMode, pfGetShaderPassMode,
pfShaderPassMultiMode, pfGetShaderPassMultiMode, pfShaderPassAttr,
pfGetShaderPassAttr, pfShaderPassMultiAttr, pfGetShaderPassMultiAttr,
pfShaderPassVal, pfGetShaderPassVal, pfShaderPassMultiVal,
pfGetShaderPassMultiVal, pfShaderPassFluxedAttr,
pfGetShaderPassFluxedAttr, pfShaderPassFluxedMode,
pfGetShaderPassFluxedMode, pfShaderPassFluxedMultiAttr,
pfGetShaderPassFluxedMultiAttr, pfShaderPassFluxedVal,
pfGetShaderPassFluxedVal, pfShaderPassFluxedMultiMode,
pfGetShaderPassFluxedMultiMode, pfShaderPassFluxedMultiVal,
pfGetShaderPassFluxedMultiVal, pfShaderPassNamedMode,
pfShaderPassNamedAttr, pfShaderPassNamedMultiAttr, pfShaderPassNamedVal,
pfShaderPassNamedMultiMode, pfShaderPassNamedMultiVal,
pfShaderDefaultGeoState, pfShaderDefaultFBState,
pfGetShaderDefaultGeoState, pfGetShaderDefaultFBState,
pfShaderPassGeoState, pfShaderPassFBState, pfGetShaderPassGeoState,
pfGetShaderPassFBState, pfShaderAllocateTempTexture,
pfShaderPassTempTexture, pfShaderTempTexture,
pfShaderResolveTempTextures, pfGetShaderNumTempTextures,
pfGetBumpMapShader, pfGetPhongSpecularShader, pfGetFullPhongShader,
pfGetMultiPhongSpecularShader, pfGetMultiFullPhongShader,
pfGetSpecularHighlightShader - Create, modify and query multi-pass
shading primitives.
FUNCTION SPECIFICATION
#include <Performer/pf.h>
pfShader* pfNewShader(void);
pfType* pfGetShaderClassType(void);
void pfShaderName(pfShader* shader, const char *name);
const char* pfGetShaderName(const pfShader* shader);
void pfShaderOpenPass(pfShader *shader, int passType);
void pfShaderClosePass(pfShader *shader);
int pfGetShaderCurPassType(pfShader *shader);
int pfGetShaderNumPasses(pfShader *shader);
pfShaderPass * pfGetShaderCurPass(pfShader *shader);
pfShaderPass * pfGetShaderPass(pfShader *shader, int index);
Page 1
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
pfPassList * pfGetShaderPassList(pfShader *shader);
void pfShaderPassMode(pfShader *shader, int which, int mode);
int pfGetShaderPassMode(pfShader *shader, int which);
void pfShaderPassMultiMode(pfShader *shader, int which,
int index, int mode);
int pfGetShaderPassMultiMode(pfShader *shader, int which,
int index);
void pfShaderPassAttr(pfShader *shader, int which,
void* attr);
void * pfGetShaderPassAttr(pfShader *shader, int which);
void pfShaderPassMultiAttr(pfShader *shader, int which,
int index, void *attr);
void * pfGetShaderPassMultiAttr(pfShader *shader, int which,
int index);
void pfShaderPassVal(pfShader *shader, int which,
float value);
float pfGetShaderPassVal(pfShader *shader, int which);
void pfShaderPassMultiVal(pfShader *shader, int which,
int index, float values);
float pfGetShaderPassMultiVal(pfShader *shader, int which,
int index);
void pfShaderPassFluxedAttr(pfShader* _shader, int which,
void* attr);
void* pfGetShaderPassFluxedAttr(pfShader* _shader, int which);
void pfShaderPassFluxedMode(pfShader* _shader, int mode,
void* value);
void* pfGetShaderPassFluxedMode(pfShader* _shader, int mode);
void pfShaderPassFluxedMultiAttr(pfShader* _shader,
int which, int index, void *attr);
void* pfGetShaderPassFluxedMultiAttr(pfShader* _shader,
int which, int index);
Page 2
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
void pfShaderPassFluxedVal(pfShader* _shader, int which,
void *value);
void* pfGetShaderPassFluxedVal(pfShader* _shader, int which);
void pfShaderPassFluxedMultiMode(pfShader* _shader, int mode,
int index, void * value);
void* pfGetShaderPassFluxedMultiMode(pfShader* _shader,
int mode, int index);
void pfShaderPassFluxedMultiVal(pfShader* _shader, int which,
int index, void* value);
void* pfGetShaderPassFluxedMultiVal(pfShader* _shader,
int which, int index);
void pfShaderPassNamedMode(pfShader* _shader, int mode,
char *name);
void pfShaderPassNamedAttr(pfShader* _shader, int which,
char *name);
void pfShaderPassNamedMultiAttr(pfShader* _shader, int which,
int index, char *name);
void pfShaderPassNamedVal(pfShader* _shader, int which,
char *name);
void pfShaderPassNamedMultiMode(pfShader* _shader, int mode,
int index, char *name);
void pfShaderPassNamedMultiVal(pfShader* _shader, int which,
int index, char *name);
void pfShaderDefaultGeoState(pfShader *shader,
pfGeoState *gstate);
void pfShaderDefaultFBState(pfShader *shader,
pfFBState *fbs);
pfGeoState * pfGetShaderDefaultGeoState(pfShader *shader);
pfFBState * pfGetShaderDefaultFBState(pfShader *shader);
void pfShaderPassGeoState(pfShader *shader,
pfGeoState *gstate);
void pfShaderPassFBState(pfShader *shader, pfFBState *fbs);
Page 3
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
pfGeoState * pfGetShaderPassGeoState(pfShader *shader);
pfFBState * pfGetShaderPassFBState(pfShader *shader);
int pfShaderAllocateTempTexture(pfShader *shader);
int pfShaderPassTempTexture(pfShader *shader, int texID);
int pfShaderTempTexture(pfShader *shader, int texID,
pfTexture *texture);
int pfShaderResolveTempTextures(pfShader *shader);
int pfGetShaderNumTempTextures(pfShader *shader);
pfShader* pfGetBumpMapShader(pfTexture *bumpTex,
pfFlux *lightPos);
pfShader* pfGetPhongSpecularShader(pfTexture *specularMap,
pfVec3 specularColor, pfFlux *lightPos,
int mapSize);
pfShader* pfGetFullPhongShader(pfTexture *specularMap,
pfVec3 specularColor, pfTexture *diffuseMap,
pfFlux *lightPos, int mapSize);
pfShader* pfGetMultiPhongSpecularShader(int n,
pfTexture **specularMap, pfVec3 *specularColor,
pfFlux **lightPos, int *mapSize);
pfShader* pfGetMultiFullPhongShader(int n,
pfTexture **specularMap, pfVec3 *specularColor,
pfTexture **diffuseMap, pfFlux **lightPos,
int *mapSize);
pfShader* pfGetSpecularHighlightShader(pfTexture *specularMap,
pfVec3 specularColor, pfFlux *lightPos,
int mapSize);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfShader is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfShader. Casting an object of
class pfShader 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 4
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfShader 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
shader identifies a pfShader.
DESCRIPTION
A pfShader is a container for multi-pass rendering algorithm
descriptions. A multi-pass rendering algorithm consists of a collection
of passes. A pass contains information for drawing some arbitrary
geometry with a specific state on the graphic pipeline. A pass may
contain pointers to a pfGeoState and a pfFBState. These two determine the
graphic state to be set before rendering the pass.
A pfShader is not a part of the scene graph. An application should use
pfShaderManager in order to associate a pfShader to a node on the scene
graph. Once a node on the scene graph has a pfShader associated with it,
the entire geometry contents under this node is rendered using that
pfShader.
pfShader supports a number of pass types:
PF_SHADERPASS_GEOMETRY
PF_SHADERPASS_QUAD
PF_SHADERPASS_COPYPIXELS
PF_SHADERPASS_ACCUM
Page 5
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
PF_SHADERPASS_GEOMETRY_DYNAMIC
PF_SHADERPASS_QUAD_DYNAMIC
PF_SHADERPASS_COPYPIXELS_DYNAMIC
PF_SHADERPASS_ACCUM_DYNAMIC
PF_SHADERPASS_SHIFT_TEXTURE
A pass of type PF_SHADERPASS_GEOMETRY draws its associated geometry using
the pass pfGeoState and pfFBState.
A pass of type PF_SHADERPASS_QUAD draws a quad covering the screen
bounding box of the associated geometry. It applies the specified
pfGeoState and pfFBState before drawing the quad.
A pass of type PF_SHADERPASS_COPYPIXELS operates on bitmaps the size of
the screen bounding box of the associated geometry. It can move bitmaps
in three directions:
1. From frame buffer to texture memory.
2. From frame buffer onto itself.
3. From texture memory to frame buffer.
A pass of type PF_SHADERPASS_ACCUM operates on bitmaps the size of the
screen bounding box of the associated geometry. It can copy bitmaps to
and from the accumulation buffer.
Passes of types PF_SHADERPASS_GEOMETRY_DYNAMIC,
PF_SHADERPASS_QUAD_DYNAMIC, PF_SHADERPASS_COPYPIXELS_DYNAMIC and
PF_SHADERPASS_ACCUM_DYNAMIC behave just like their counterparts without
the _DYNAMIC suffix with the difference that they can refer to fluxed
attributes for any of their attribute types. If both a fluxed and non-
fluxed attribute is set on a dynamic pass, the fluxed attribute takes
precedence.
A pass of type PF_SHADERPASS_SHIFT_TEXTURE is a refinement of
PF_SHADERPASS_GEOMETRY_DYNAMIC which computes new texture coordinates for
the pfGeoSets that it shades which are offset toward a light. This pass
is used for multi-pass bump mapping. This pass can only operate on
pfGeoSets that contain individual triangles. No strips of any sort are
yet supported.
pfNewShader creates and returns a handle to a pfShader. Like other
pfUpdatables, pfShader are always allocated from shared memory and can be
deleted using pfDelete.
pfGetShaderClassType returns the pfType* for the class pfShader. The
pfType* returned by pfGetShaderClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfShader.
Because OpenGL Performer allows subclassing of built-in types, when
decisions are made based on the type of an object, it is usually better
Page 6
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
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.
pfShaderSetName sets the name for the shader. Note that this is only
used for identifying purposes and by the pfb loader. pfShaderGetName
returns the name of the shader, if any.
pfShaderOpenPass starts a definition of a new pass on a pfShader.
pfShaderClosePass ends the definition of the currently open pass. Upon
opening a new pass, the application must provide a pass type from the
types mentioned above. While a pass is open, an application may invoke
functions to define the parameters of the pass.
pfGetShaderCurPassType returns the type of the currently open pass. If no
pass is currently open, it returns NULL.
pfGetShaderNumPasses returns the number of passes on a pfShader. This
number does not include the currently open pass.
pfGetShaderPassList returns a pointer to a pfPassList. A pfPassList
contains the full description of all the passes that were opened and
closed on this pfShader. The pfPassList pointer can be added to a
pfGeoSet using the function pfGSetPassList in order to change its drawing
behavior and make it use the pfShader passes instead of its standard
drawing function. Changing the pfPassList pointer on a pfGeoSet is
normally handled by the pfShaderManager.
pfShaderPassMode and pfGetShaderPassMode set and get modes on the
currently open pass. On passes of type PF_SHADERPASS_COPYPIXELS, one can
set the pixel copy direction by setting which to
PF_SHADERPASS_COPYPIXELS_DIRECTION and setting mode to one of the
following:
PF_COPYPIXELSPASS_TO_TEXTURE
- From frame buffer to Texture memory.
PF_COPYPIXELSPASS_FROM_TEXTURE
- From texture memory to frame buffer.
PF_COPYPIXELSPASS_IN_PLACE
- From frame buffer onto itself.
On passes of type PF_SHADERPASS_ACCUM, one can set the accumulation
buffer operation by setting which to PF_SHADERPASS_ACCUM_OP and setting
mode to one of the valid OpenGL GLenum's as the first parameter of the
OpenGL function glAccum. The PF_SHADERPASS_ACCUM passes mode directly to
the glAccum call.
On passes of type PF_SHADERPASS_GEOMETRY and
PF_SHADERPASS_GEOMETRY_DYNAMIC, it is possible to tell the shader to use
each pfGeoSet's pfGeoState to render that pass. To turn on this mode, set
Page 7
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
which to PF_SHADERPASS_USE_LOCAL_GSTATE and set mode to 1. If
PF_SHADERPASS_USE_LOCAL_GSTATE is enabled and the pass also has its own
pfGeoState, the pass pfGeoState takes precedence.
pfShaderPassMultiMode and pfGetShaderPassMultiMode set and get multi-
valued modes on the currently open pass. At the moment, there are no
available modes to set. This API is reserved for future extensions.
pfShaderPassAttr and pfGetShaderPassAttr set and get attributes on the
currently open pass.
On all pass types, setting which to PF_SHADERPASS_FBSTATE and attr to a
pfFBState pointer sets the pfFBState that the currently open pass uses.
On passes of type PF_SHADERPASS_GEOMETRY, PF_SHADERPASS_QUAD,
PF_SHADERPASS_GEOMETRY_DYNAMIC, PF_SHADERPASS_QUAD_DYNAMIC and
PF_SHADERPASS_SHIFT_TEXTURE, setting which to PF_SHADERPASS_GSTATE and
attr to a pfGeoState pointer sets the pfGeoState that the currently open
pass uses.
On passes of type PF_SHADERPASS_GEOMETRY, PF_SHADERPASS_GEOMETRY_DYNAMIC
and PF_SHADERPASS_SHIFT_TEXTURE, setting which to
PF_SHADERPASS_OVERRIDE_COLOR and setting attr to a pfVec4 pointer sets
the override color of the currently open pass to the input pfVec4.
On passes of type PF_SHADERPASS_QUAD and PF_SHADERPASS_QUAD_DYNAMIC,
setting which to PF_SHADERPASS_COLOR and setting attr to a pfVec4 pointer
sets the quad color of the currently open pass.
On passes of type PF_SHADERPASS_COPYPIXELS and
PF_SHADERPASS_COPYPIXELS_DIRECTION, setting which to
PF_SHADERPASS_TEXTURE and setting attr to a pfTexture pointer sets the
texture used by the currently open pass.
pfShaderPassMultiAttr and pfGetShaderPassMultiAttr set and get multi-
value attributes on the currently open pass. At the moment, there are no
available attributes to set. This API is reserved for future extensions.
pfShaderPassVal and pfGetShaderPassVal set and get values on the
currently open pass.
On passes of type PF_SHADERPASS_COPYPIXELS and
PF_SHADERPASS_COPYPIXELS_DYNAMIC, setting which to
PF_SHADERPASS_TEMP_TEXTURE_ID and setting value to a temporary texture ID
determines what temporary texture this pass uses. This value is not used
internally by the pass. It serves as temporary storage for the chosen
texture ID. A later call to pfShaderPassAttr should supply the actual
pfTexture pointer for this pass.
On passes of type PF_SHADERPASS_ACCUM and PF_SHADERPASS_ACCUM_DYNAMIC,
setting which to PF_SHADERPASS_ACCUM_VAL determines the second parameter
of the call to glAccum. The PF_SHADERPASS_ACCUM pass uses value as the
Page 8
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
second parameter of the OpenGL glAccum call.
The following table contains a summary of the available attributes, modes
and values for each shader type:
Token GEOMETRY QUAD COPYPIXELS ACCUM
_________________________________________________________________________
PF_SHADERPASS_FBSTATE + + + +
(Attribute)
PF_SHADERPASS_GSTATE + + - -
(Attribute)
PF_SHADERPASS_OVERRIDE_COLOR + - - -
(Attribute)
PF_SHADERPASS_COLOR - + - -
(Attribute)
PF_SHADERPASS_TEXTURE - - + -
(Attribute)
PF_SHADERPASS_COPYPIXELS_DIRECTION - - + -
(Mode)
PF_SHADERPASS_ACCUM_OP - - - +
(Mode)
PF_SHADERPASS_TEMP_TEXTURE_ID - - + -
(Value)
PF_SHADERPASS_ACCUM_VAL - - - +
(Value)
|
pfShaderPassFluxedAttr and pfGetShaderPassFluxedAttr set and get the
fluxed attributes on the currently open pass.
On all dynamic pass types, setting which to PF_SHADERPASS_FBSTATE and
attr to a pfFluxedFBState sets the pfFluxedFBState that the currently
open pass uses.
On dynamic passes of type PF_SHADERPASS_GEOMETRY_DYNAMIC,
PF_SHADERPASS_SHIFT_TEXTURE and PF_SHADERPASS_QUAD_DYNAMIC, setting
which to PF_SHADERPASS_GSTATE and attr to a pfFluxedGeoState pointer sets
the pfFluxedGeoState on the currently open dynamic pass.
On passes of type PF_SHADERPASS_GEOMETRY_DYNAMIC and
PF_SHADERPASS_SHIFT_TEXTURE, setting which to
PF_SHADERPASS_OVERRIDE_COLOR and attr to a pfFlux which contains a pfVec4
sets the fluxed override color for the currently open dynamic pass.
On passes of type PF_SHADERPASS_QUAD_DYNAMIC, setting which to
PF_SHADERPASS_COLOR and attr to a pfFlux containing a pfVec4 sets the
fluxed color of the quad that the currently open dynamic pass will draw.
On passes of type PF_SHADERPASS_COPYPIXELS_DYNAMIC, setting which to
PF_SHADERPASS_TEXTURE and attr to a pfFlux containing a pfTexture pointer
Page 9
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
will set the fluxed texture pointer that the currently open pass uses.
pfShaderPassFluxedMode and pfGetShaderPassFluxedMode get and set the
fluxed mode of the currently open pass.
On passes of type PF_SHADERPASS_COPYPIXELS_DYNAMIC, setting which to
PF_SHADERPASS_COPYPIXELS_DIRECTION and mode to a pfFlux containing an int
will set the fluxed copy pixels direction. The valid modes for this
fluxed integer are PF_COPYPIXELSPASS_TO_TEXTURE,
PF_COPYPIXELSPASS_FROM_TEXTURE, and PF_COPYPIXELSPASS_IN_PLACE.
On passes of type PF_SHADERPASS_ACCUM_DYNAMIC, setting which to
PF_SHADERPASS_ACCUM_OP and mode to a pfFlux containing a GLenum will set
the fluxed accumulation buffer operation. Valid values for this GLenum
are the same as for the first parameter of glAccum.
pfShaderPassFluxedMultiAttr and pfGetShaderPassFluxedMultiAttr get and
set fluxed multi-value attributes on the currently open pass. There are
currently no such attributes, these functions are here for future
expansion.
pfShaderPassFluxedVal and pfGetShaderPassFluxedVal set and get the
specified fluxed value on the currently open pass.
Currently the only supported fluxed value is on a
PF_SHADERPASS_ACCUM_DYNAMIC pass type. which must be
PF_SHADERPASS_ACCUM_VAL and value should point to a pfFlux containing a
GLfloat. The legal values for this GLfloat are the same as values for the
second parameter of glAccum.
pfShaderPassFluxedMultiMode and pfGetShaderPassFluxedMultiMode get and
set fluxed multi-element modes. There are currently no such supported
modes.
pfShaderPassFluxedMultiVal and pfGetShaderPassFluxedMultiVal get and set
fluxed multi-element values. There are currently no such supported
values.
pfShaderPassMultiVal and pfGetShaderPassMultiVal set and get multi-
element values on the currently open pass. At the moment, there are no
available multi-element values to set. This API is reserved for future
extensions.
pfShaderPassNamedMode, pfShaderPassNamedAttr, pfShaderPassNamedMultiAttr,
pfShaderPassNamedVal, pfShaderPassNamedMultiMode and
pfShaderPassNamedMultiVal are used to set named properties of passes. A
named property is essentially a variable; it can be used to parametrize a
shader. For example, let's say we used a pfNameSpace to attach a
pfGeoState under the name "pass1 GState" somewhere in the scenegraph.
Page 10
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
When constructing a shader, we could set the PF_SHADERPASS_GSTATE
attribute of any pass by name rather than by reference. For instance, we
could call pfShaderPassNamedAttr setting which to PF_SHADERPASS_GSTATE
and name to "pass1 GState". When the pfShaderManager is used to resolve
the shaders in the tree, it will map names to attributes and forward them
to the individual passes. With this kind of setup, it is possible to have
the same name refer to different things in different parts of the tree.
pfShaderPassNamedMode supports the same set of modes as pfShaderPassMode.
pfShaderPassNamedAttr supports the same set of attributes as
pfShaderPassAttr
pfShaderPassNamedVal supports the same set of values as pfShaderPassVal.
There is no distinction between fluxed and non-fluxed named properties
since performer can deduce this at run-time. If a non-dynamic pass type
refers to a name that resolves to a fluxed propery, pfShaderManager will
issue a warning.
pfShaderPassNamedMultiAttr, pfShaderPassNamedMultiMode, and
pfShaderPassNamedMultiVal do not support any properties yet.
pfShaderDefaultGeoState and pfGetShaderDefaultGeoState set and get the
shader default pfGeoState. All graphic state that isn't defined on a pass
pfGeoState is inherited from the pfShader pfGeoState. Any graphic state
that isn't specified on both the default pfGeoState and the pfShader
pfGeoState is inherited from a hard-coded system default.
pfShaderDefaultFBState and pfGetShaderDefaultFBState set and get the
shader default pfFBState. All frame-buffer state that isn't defined on a
pass pfFBState is inherited from the pfShader pfFBState. Any frame-buffer
state that isn't specified on both the default pfFBState and the pfShader
pfFBState is inherited from a hard-coded system default.
pfShaderAllocateTempTexture returns the integer ID of the next available
temporary texture for the pfShader and increments the temporary texture
count for the pfShader.
When constructing a new pfShader object, pfShaderAllocateTempTexture must
be called once for each unique temporary texture which will be used by
the pfShader. The returned integer ID should be used for subsequent
calls to pfShaderPassTempTexture and pfShaderTempTexture for specifying
texture IDs for passes and mapping pfTexture objects to texture IDs.
When constructing a pass of a pfShader which requires a temporary
texture, pfShaderPassTempTexture should be called to assign one of the
texture IDs returned by pfShaderAllocateTempTexture to the current pass.
This will create an association between the pfShader's pass and one of
the temporary texture IDs allocated with pfShaderAllocateTempTexture.
pfShaderPassTempTexture returns negative one if texID is less than zero
Page 11
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
or greater than or equal to the temporary texture count for the pfShader.
Negative one will also be returned if the current pass is not a
pfCopyPixelsPass. Zero is returned on successful assignment.
pfShaderTempTexture maps the integer texID returned by
pfShaderAllocateTempTexture to the pfTexture* texture. In order to
reduce texture memory usage it is desirable for texture to point to a
pfTexture object which will be shared between multiple pfShaders. This
can be done because the data stored in pfShader temporary textures is
just that, temporary. Once all the passes of one pfShader have been
applied, another pfShader can make use of the temporary texture for
storing its own temporary results. Of course, it isn't required that
pfTextures be shared between pfShaders, it's just a good idea to do so
and avoid wasting resources. pfShaderPassTempTexture returns negative
one if texID is less than zero or greater than or equal to the temporary
texture count for the pfShader. Zero is returned on success.
pfShaderResolveTempTextures resolves the mapping from the per pass
integer texture IDs assigned with pfShaderPassTempTexture to the
pfTexture pointers assigned with pfShaderTempTexture. If
pfShaderResolveTempTextures is not called, the passes of the pfShaders
will not be assigned pointers to pfTexture objects.
pfShaderResolveTempTextures returns negative one if the current pass for
the pfShader is still open. Zero is returned on success.
When loading pfShaders with pfdLoadShader and mapping them to pfNodes
with the pfShaderManager, temporary texture management will be taken care
of automatically. pfdLoadShader will make the appropriate calls to
pfShaderAllocateTempTexture and pfShaderPassTempTexture while the
pfShaderManager will create a shared pool of pfTexture objects and assign
them to pfShaders with pfShaderTempTexture. Finally, once all texture
IDs of all pfShaders have been mapped to pointers to pfTextures in the
shared pfTexture pool, the pfShaderManager will call
pfShaderResolveTempTextures to map the texture IDs stored in each
pfShader's passes to pfTexture pointers.
pfGetShaderNumTempTextures returns the count of allocated temporary
textures for the pfShader.
pfGetBumpMapShader generates a shader which bump maps the geometry that
it applies to. The pfGeoSets that this shader draws must have a primitive
type of PFGS_TRIS for now. bumpTex is pfTexture whose image data contains
a greyscale displacement map. Dark colors map to little displacement,
light colors map to a larger displacement. lightPos is a pfFlux which
contains a pfVec3 that encodes a light position in eye space.
pfGetPhongSpecularShader generates a shader which simulates a phong
specular term on the geometry that it applies to. specularMap is an
environment map which encodes the shininess of the light. The specular
map is generated by rendering a highly tesselated sphere in an
Page 12
pfShader(3pf) OpenGL Performer 3.2.2 libpf C Reference Pages pfShader(3pf)
orthographic projection with the light and eye in the same location.
We've provided the utility generatePhongMap.C in
/usr/share/Performer/src/tools to generate these specular maps.
specularColor is a pfVec4 that specifies the color of the specular
highlight; normally the color of the light. lightPos is a pfFlux which
contains a pfVec3 that controls the light position in eye space. mapSize
is a parameter that specifies the size of the environment map to generate
for applying the specular. A size of 64 (width=height) is more than
enough for most applications.
pfGetFullPhongShader This shader is an extension of the phong specular
shader which also simulates the phong lighting model on the diffuse term
of the lighting equation. The additional parameter diffuseMap specifies a
texture that encodes the diffuse term of the phong lighting equation. For
isotropic lighting models, use "/usr/share/Performer/data/NdotL.rgb"
pfGetMultiPhongSpecularShader This function generates the same sort of
shader as pfGetPhongSpecularShader except that it can handle multiple
lights. The first parameter, n specifies the number of lights. The
remaining parameters are arrays of size n which contain the same types of
data as passed to pfGetPhongSpecularShader.
pfGetMultiFullPhongShader This function generates a multi-light full
phong shader. The first parameter, n, specifies the number of lights. The
remaining parameters are arrays of size n which contain the same type of
data as passed to pfGetFullPhongShader
pfGetSpecularHighlightShader generates a shader which draws ONLY the
specular term of the phong lighting model and adds it to the framebuffer.
This shader is useful for combining with other shaders so that it draws
the specular highlight on top of their results. The parameters are the
same as to pfGetPhongSpecularShader
NOTES
Shaded pfGeoSets can not be compiled into OpenGL display lists. Applying
a shader to a pfNode will disable that functionality on all the pfGeoSets
in the subtree rooted at that node. The function pfGSetDrawMode with the
PFGS_COMPILE_GL or PFGS_DRAW_GLOBJ mode tokens will have no effect on
shaded pfGeoSets.
SEE ALSO
pfShaderManager, pfGeoSet, glAccum, pfGeoState, pfFBState, pfNameSpace,
pfFluxedGeoState, pfFluxedFBState
Page 13
