pfISL(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfISL(3pf)NAME
pfShaderTexCoordFunc, pfShaderTexApplyFunc, pfShaderTexComputeFunc,
pfAppearanceChanged, pfShaderChanged - OpenGL|Shader Integration
FUNCTION SPECIFICATION
#include <Performer/pr.h>
void pfShaderTexCoordFunc(islAppearance *appearance,
pfTexCoordCallbackType func, void *udata);
void pfShaderTexApplyFunc(islAppearance *appearance,
pfTexApplyCallbackType func, void *udata);
void pfShaderTexComputeFunc(islAppearance *appearance,
pfTexComputeCallbackType func, void *udata);
void pfAppearanceChanged(islAppearance *appearance);
void pfShaderChanged(islAppearance *appearance, islShader *shader);
typedef int (*pfTexApplyCallbackType)(const islAppearance *app,
const char *texName,
void *userData);
typedef void (*pfTexComputeCallbackType)(pfISLTexCoordData *d,
const char *texName,
void *userData);
typedef pfVec2* (*pfTexCoordCallbackType)(pfISLTexCoordData *d,
const float texCoordID,
void *userData);
void void pfDefaultTextureComputeCallback(pfISLTexCoordData *d,
const char *texName,
void *userData);
int pfDefaultTextureApplyCallback(const islAppearance *app,
const char *texName,
void *userData);
DESCRIPTION
These functions provide a mechanism for using OpenGL Shader objects
within Performer. As of Performer 3.0, OpenGL Shader objects can be used
natively in Performer applications with very little API duplication on
the Performer side. To this end, the shader support introduced in
Performer 2.4 has been removed from this and future releases.
OpenGL Shader encapsulates the description of the appearance of an object
in the islAppearance class. Performer can now use islAppearances directly
Page 1
pfISL(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfISL(3pf)
to render pfGeoSets, making islAppearance a peer class to pfGeoState. To
render pfGeoSets with OpenGL Shader, create an islAppearance and its
constituent islShaders and pass the islAppearance to a pfGeoSet.
islAppearances should be compiled with an islCompileAction before passing
them into pfGeoSets to eliminate performance glitches associated with
uncompiled islAppearances coming into view.
OpenGL Shader integration is not completely transparent, however, since
Performer must use its own callbacks as hooks into the OpenGL Shader
library. Since any user specified callbacks are lost and users have no
access to Performer's islShape and islDrawAction classes, Performer
provides a set of its own callbacks that can be used in place of OpenGL
Shader's.
pfShaderTexCoordFunc is used to register a texture coordinate generation
callback. When rendering objects with an islDrawAction, OpenGL Shader
asks for geometry to be drawn with a specified texture coordinate
identification code. These codes are user defined, so Performer must pass
the task of generating the corresponding texture coordinates to the user.
The appearance parameter specifies which islAppearance the callbacks
applies to. The func parameter is a pointer to the user callback and the
udata parameter is a user data pass through pointer. The user callback
must be of type pfTexCoordCallbackType. If appearance is NULL, all
currently registered islAppearances will be updated to use the specified
callback and user data.
In the texture coordinate callback function, the pfISLTexCoordData
pointer refers to a class which contains useful information for computing
the requested texture coordinates, such as the pfGeoSet being rendered,
its islAppearance and the pfGeoSet's modelview matrix. The texCoordID
parameter is the pass-through texture coordinate identification from an
islShader and the userData parameter points to the user data specified
when registering the callback.
The user callback must return a set of Performer texture coordinates for
rendering the specified pfGeoSet.
pfShaderTexApplyFunc is used to register a texture application callback.
This callback is invoked whenever OpenGL Shader asks for a specific named
texture to be applied. The callback function is passed the islAppearance
that requested the texture bind, the texture name, and any user data
specified when the callback is registered. The return value from the user
callback is the number of dimensions in the texture; 1, 2 or 3. If
appearance is NULL, all currently registered islAppearances will be
updated to use the specified callback and user data.
By default, Performer registers the pfDefaultTextureApplyCallback
function with each islAppearance that is installed on a pfGeoSet. This
default callback is a useful utility that assumes that the texture name
is the name of a file and it tries to load that file from disk and
applies it.
Page 2
pfISL(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfISL(3pf)
pfShaderTexComputeFunc is used to register a texture computation
callback. Often, it is necessary to use procedural textures for shading
and and it is most efficient to compute them inside the CULL process.
When rendering islAppearances, Performer queries them as to which
textures they will be using in the next frame and supports calling a user
callback for each texture. The parameters passed into the user callback
specify some useful data for the computation, such as the islAppearance
that triggers the request, the pfGeoSet being renderered and the current
modelview matrix. If appearance is NULL, all currently registered
islAppearances will be updated to use the specified callback and user
data.
By default, Performer registers the pfDefaultTextureComputeCallback with
each islAppearance that is added to a pfGeoSet. This default callback
loads the specified texture and stores it in a global lookup table. When
the pfDefaultTextureApplyCallback is invoked as described above, it
applies a texture from this lookup table.
pfShaderChanged should be called whenever any shader parameters of any
islShader have been modified. The appearance parameter specifies which
islAppearance contains the shader that has changed and the shader
parameter specifies specifically which shader has been changed.
pfAppearanceChanged should be called whenever an islAppearance that
Performer references has been changed by adding or removing a shader.
SEE ALSO
pfISLTexCoordData, islAppearance, islShader, pfGeoSet
Page 3