pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfShaderProgram - Class for specifying GLSL shader programs
FUNCTION SPECIFICATION
#include <Performer/pr/pfShaderProgram.h>
pfShaderProgram::pfShaderProgram();
void pfShaderProgram::addShader(pfShaderObject *shader);
int pfShaderProgram::getNumShaders();
pfShaderObject* pfShaderProgram::getShader(int i);
void pfShaderProgram::removeShader(pfShaderObject *shader);
void pfShaderProgram::replaceShader(pfShaderObject *_old,
pfShaderObject *_new);
void pfShaderProgram::replaceShader(int i,
pfShaderObject *replacement);
void pfShaderProgram::apply();
int pfShaderProgram::link(GLcharARB *log = NULL);
int pfShaderProgram::forceRelink(GLcharARB *log = NULL);
GLboolean pfShaderProgram::validate();
GLhandleARB pfShaderProgram::getHandle() const;
GLint pfShaderProgram::findUniform(const GLcharARB *name);
GLint pfShaderProgram::addUniform(const GLcharARB *name,
unsigned int uniType, int size, void *data);
void pfShaderProgram::setUniform(GLint whichOne,
void *data);
GLint -
pfShaderProgram::getUniformDataSize(GLint whichOne) const;
void * pfShaderProgram::getUniformData(int whichOne);
char * pfShaderProgram::getUniformName(int whichOne);
int pfShaderProgram::getUniformNumVals(int whichOne);
int pfShaderProgram::getUniformType(int whichOne);
Page 1
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
char -
pfShaderProgram::getUniformClampMode(int whichOne) const;
void pfShaderProgram::setUniformClampMode(int whichOne,
char clampMode);
void * pfShaderProgram::getUniformMin(int whichOne) const;
void * pfShaderProgram::getUniformMax(int whichOne) const;
void pfShaderProgram::setUniformMin(int whichOne,
void *data);
void pfShaderProgram::setUniformMax(int whichOne,
void *data);
char -
pfShaderProgram::getUniformNormalizedFlag(int whichOne) const;
void pfShaderProgram::setUniformNormalizedFlag(int whichOne,
char onOrOff);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfShaderProgram is derived from the parent
class pfObject, so each of these member functions of class pfObject are
also directly usable with objects of class pfShaderProgram. 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);
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 pfShaderProgram 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);
Page 2
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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
The pfShaderProgram class encapsulates the functionality associated with
OpenGL's shader programs.
A pfShaderProgram is a comprised of a collection of pfShaderObjects and
an collection of uniform variables which are an opaque type and can only
be accessed via an index from the pfShaderProgram interface.
new(arena) allocates a pfShaderProgram from the specified memory arena,
or from the heap if arena is NULL. new allocates a pfShaderProgram from
the default memory arena (see pfGetSharedArena). Like other pfObjects,
pfShaderPrograms cannot be created statically, automatically on the stack
or in arrays. pfShaderPrograms should be deleted with pfDelete rather
than the delete operator.
pfShaderProgram::getClassType returns the pfType* for the class
pfShaderProgram. The pfType* returned by pfShaderProgram::getClassType
is the same as the pfType* returned by invoking the virtual function
getType on any instance of class pfShaderProgram. 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.
In order to use a pfShaderProgram as a piece of state one must specify A
it as an attribute for a pfGeoState and enable that mode:
pfGeoState *gState = new pfGeoState();
pfShaderProgram *sProg = new pfShaderProgram();
gState->setMode(PFSTATE_ENSHADPROG, PF_ON);
gState->setAttr(PFSTATE_SHADPROG, sProg);
The first step in creating a valid pfShaderProgram involves adding a set
Page 3
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
of pfShaderObjects to the shader program. This can be done via
pfShaderProgram::addShader. In addition to adding shaders to a given
shader program it's also possible to replace an existing shader object
via B pfShaderProgram::replaceShader. It's also possible to delete
shaders objects from a given shader program via
pfShaderProgram::removeShader.
In addition to the methods for adding/deleting/replacing shader objects
from a shader program it's also possible to query an existing
pfShaderProgram to determine how many shader objects are associated with
it via pfShaderProgram::getNumShaders and one can retreive a pointer to
the i'th shader object via pfShaderProgram::getShader.
In addition to specifying a set of pfShaderObjects for a pfShaderProgram
one may also specify a set of uniform variables for the program. These
uniforms can then be referenced by index (which aren't necessarily the
same as those set internally via OpenGL). A uniform variable is comprised
of a name (stored as a GLcharARB*), a type, a value indicating the number
of variables of that type being stored in the uniform, a flag indicating
if the value is to be clamped to a min and/or max value (or not at all),
a flag indicating if the value should be normalized (for those types
which can be normalized), and of course pointers to the current value as
well as the min and max values for this uniform variable is indeed being
clamped.
The type for a uniform variable can be one of the following:
PFUNI_FLOAT1 single GLfloat.
PFUNI_FLOAT2 array of two GLfloats.
PFUNI_FLOAT3 array of three GLfloats.
PFUNI_FLOAT4 array of four GLfloats.
PFUNI_INT1 single GLint.
PFUNI_INT2 array of two GLints.
PFUNI_INT3 array of three GLints.
PFUNI_INT4 array of four GLints.
PFUNI_BOOL1 single GLint specifying boolean value.
PFUNI_BOOL2 array of two GLints specifying boolean values. B
PFUNI_BOOL3 array of three GLints specifying boolean values.
Page 4
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
PFUNI_BOOL4 array of four GLints specifying boolean values.
PFUNI_MAT2 four GLfloats specifying 2x2 matrix.
PFUNI_MAT3 nine GLfloats specifying 3x3 matrix.
PFUNI_MAT4 sixteen GLfloats specifying 4x4 matrix.
PFUNI_SAMP1D single GLint specifying which texture unit to
look into for this sampler.
PFUNI_SAMP2D single GLint specifying which texture unit to
look into for this sampler.
PFUNI_SAMP3D single GLint specifying which texture unit to
look into for this sampler.
PFUNI_SAMPCUBE single GLint specifying which texture unit to
look into for this sampler.
PFUNI_SAMP1DSHADOW single GLint specifying which texture unit to
look into for this sampler.
PFUNI_SAMP2DSHADOW single GLint specifying which texture unit to
look into for this sampler.
In order to add a uniform variable to a pfShaderProgram one should use
pfShaderProgram::addUniform. The first parameter name specifies the name
for the uniform variable. The second parameter uniType is one of the
types specified above. The third variable size indicates how many
variables of this type will be found in the fourth and final parameter
data. Internally OpenGL Performer will make a copy of this data if it is
not a pointer to a pfMemory; if it is then the ref count for this piece
of memory will get incremented and no copy will be performed.
For example, in order to add a uniform variable called "scaleFactor"
which is a 4-byte float (size of a GLfloat) set to 0.5 one could do the
following:
int uniformIndex;
GLfloat scale = 0.5f;
pfShaderProgram *sProg = new pfShaderProgram();
uniformIndex = sProg->addUniform("scaleFactor", PFUNI_FLOAT1, 1, &scale);
In addition to specifying the name, type, number of variables of this
type and a data pointer it's also possible to set a flag to indicate
whether or not the value should be clamped and if it should be
normalized.
Page 5
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
A uniform variable can be clamped by using pfShaderProgram::setClampMode
to any one of PFUNI_CLAMP_NONE, PFUNI_CLAMP_MIN, PFUNI_CLAMP_MAX or
PFUNI_CLAMP_ALL. The default value is PFUNI_CLAMP_NONE. In order to set
the value to clamp to one must call pfShaderProgram::setUniformMin or
pfShaderProgram::setUniformMax. For example:
GLfloat minValue = 0.0f;
GLfloat maxValue = 1.0f;
sProg->setUniformMin(uniformIndex, &minValue);
sProg->setUniformMax(uniformIndex, &maxValue);
A In order to query the min and max values one can use
pfShader::getUniformMin and pfShader::getUniformMax. In order to
determine if the value is being clamped used one can use
pfShader::getClampMode and check the return value.
For uniform variables of type PFUNI_FLOAT2, PFUNI_FLOAT3 or PFUNI_FLOAT4
it's also possible to normalize the values such that they correspond to
vectors of size 1.0. In order to do this you must use
pfShaderProgram::setNormalizeFlag and this flag may also be queried for a
given uniform variable via pfShaderProgram::getNormalizeFlag. By default
uniform variables are not normalized. If this flag is set on a uniform
variable of a type other than one which supports this feature the flag
will be ignored and a warning will be issued at run time.
You can apply the pfShaderProgram using pfShaderProgram::apply, but only
in the draw process. When this operation is performed OpenGL Performer
will verify if for any reason the shader program needs to be recompiled
and perform that operation if required. It is also possible to force
compilation to occur by calling pfShaderProgram::link. This method will
return 0 if successful, -1 if the associated OpenGL handle is NULL or
some other occured and a positive integer indicating how many
pfShaderObjects did not compile if the link process failed. In the case
where one would like to force OpenGL Performer to relink a
pfShaderProgram once call call pfShaderProgram::forceRelink.
One can verify if a given pfShaderProgram is in a state where it is ready
to be applied by calling pfShaderProgram::validate which will return 1 if
the program can be applied given the current state or 0 otherwise.
The OpenGL handle associated with a given pfShaderProgram can be
retreived using pfShaderProgram::getHandle.
Page 6
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
SEE ALSO
pfShaderObject, pfGeoState, pfObject.
Page 7
