pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewSProg, pfGetSProgClassType, pfSProgAddShader, pfGetSProgNumShaders,
pfGetSProgShader, pfSProgRemoveShader, pfSProgReplaceShader,
pfSProgReplaceShaderIndex, pfApplySProg, pfValidateSProg, pfHandleSProg,
pfFindUniformSProg, pfSProgAddUniform, pfUniformSProg,
pfUniformDataSizeSProg, pfGetSProgNumUniforms, pfGetSProgUniformData,
pfGetSProgUniformName, pfGetSProgUniformVals, pfGetSProgUniformType,
pfGetSProgUniformClampMode, pfSProgUniformClampMode,
pfGetSProgUniformMin, pfGetSProgUniformMax, pfSProgUniformMin,
pfSProgUniformMax, pfGetSProgUniformNormalizedFlag,
pfSProgUniformNormalizedFlag, pfGetSProgUniTypeSize - Class for
specifying GLSL shader programs
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfShaderProgram* pfNewSProg(void *arena);
pfType* pfGetSProgClassType(void);
void pfSProgAddShader(pfShaderProgram* _sprog,
pfShaderObject *shader);
int pfGetSProgNumShaders(pfShaderProgram* _sprog);
pfShaderObject* pfGetSProgShader(pfShaderProgram* _sprog, int i);
void pfSProgRemoveShader(pfShaderProgram* _sprog,
pfShaderObject *shader);
void pfSProgReplaceShader(pfShaderProgram* _sprog,
pfShaderObject *_old, pfShaderObject *_new);
void pfSProgReplaceShaderIndex(pfShaderProgram* _sprog,
int i, pfShaderObject *replacement);
void pfApplySProg(pfShaderProgram* _sprog);
GLboolean pfValidateSProg(pfShaderProgram* _sprog);
GLhandleARB pfHandleSProg(const pfShaderProgram* _sprog);
GLint pfFindUniformSProg(pfShaderProgram* _sprog,
const GLcharARB *name);
GLint pfSProgAddUniform(pfShaderProgram* _sprog,
const GLcharARB *name, unsigned int uniType,
int size, void *data);
void pfUniformSProg(pfShaderProgram* _sprog,
GLint whichOne, void *data);
Page 1
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
GLint pfUniformDataSizeSProg(const pfShaderProgram* _sprog,
GLint whichOne);
int pfGetSProgNumUniforms(pfShaderProgram* _sprog);
void* pfGetSProgUniformData(pfShaderProgram* _sprog,
int whichOne);
char* pfGetSProgUniformName(pfShaderProgram* _sprog,
int whichOne);
int pfGetSProgUniformVals(pfShaderProgram* _sprog,
int whichOne);
int pfGetSProgUniformType(pfShaderProgram* _sprog,
int whichOne);
char -
pfGetSProgUniformClampMode(const pfShaderProgram* _sprog,
int whichOne);
void pfSProgUniformClampMode(pfShaderProgram* _sprog,
int whichOne, char clampMode);
void* pfGetSProgUniformMin(const pfShaderProgram* _sprog,
int whichOne);
void* pfGetSProgUniformMax(const pfShaderProgram* _sprog,
int whichOne);
void pfSProgUniformMin(pfShaderProgram* _sprog,
int whichOne, void *data);
void pfSProgUniformMax(pfShaderProgram* _sprog,
int whichOne, void *data);
char -
pfGetSProgUniformNormalizedFlag(const pfShaderProgram* _sprog,
int whichOne);
void pfSProgUniformNormalizedFlag(pfShaderProgram* _sprog,
int whichOne, char onOrOff);
int pfGetSProgUniTypeSize(int uniType);
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. Casting an
object of class pfShaderProgram 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.
Page 2
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
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 pfShaderProgram 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
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.
pfNewShaderObject creates and returns a handle to a pfShaderProgram.
arena specifies a malloc arena out of which the pfShaderProgram is
allocated or NULL for allocation off the process heap. pfShaderPrograms
can be deleted with pfDelete.
pfGetShaderObjectClassType returns the pfType* for the class
pfShaderProgram. The pfType* returned by pfGetShaderObjectClassType is
the same as the pfType* returned by invoking pfGetType 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 pfIsOfType to test if an object is of a type
Page 3
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 = pfNewGState(arena);
pfShaderProgram *sProg = pfNewSProg(arena);
pfGStateMode(gState, PFSTATE_ENSHADPROG, PF_ON);
pfGStateAttr(gState, PFSTATE_SHADPROG, sProg);
The first step in creating a valid pfShaderProgram involves adding a set
of pfShaderObjects to the shader program. This can be done via
pfSProgAddShader. In addition to adding shaders to a given shader program
it's also possible to replace an existing shader object via B
pfSProgReplaceShader. It's also possible to delete shaders objects from a
given shader program via pfSProgRemoveShader.
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 pfGetSProgNumShaders and one can retreive a pointer to the i'th
shader object via pfGetSProgShader.
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.
Page 4
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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.
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
pfSprogAddUniform. 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"
Page 5
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 = pfNewSprog(arena);
uniformIndex = pfSProgAddUniform(sProg, "scaleFactor", PFUNI_FLOAT1, 1, &scale);
A
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.
A uniform variable can be clamped by using pfSProgClampMode 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 pfSProgUniformMin or pfSProgUniformMax. For example:
GLfloat minValue = 0.0f; GLfloat maxValue = 1.0f;
pfSProgUniformMin(sProg, uniformIndex, &minValue);
pfSProgUniformMax(sProg, uniformIndex, &maxValue);
A
In order to query the min and max values one can use
pfGetSProgUniformMin and
pfGetSProgUniformMax. In order to determine
if the value is being clamped used one can use
pfGetSProgClampMode 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
pfSProgNormalizeFlag and this flag
may also be queried for a given uniform variable via
pfGetSProgNormalizeFlag. 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
pfShaderProgramApply, 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 pfSProgLink. This
Page 6
pfShaderProgram(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 pfSProgForceRelink.
One can verify if a given pfShaderProgram is in a state where it
is ready to be applied by calling
pfSProgValidate 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 pfGetSProgHandle.
SEE ALSO
pfShaderObject, pfGeoState, pfObject.
Page 7
