The stencil buffer is used to count how many times something has been drawn at a particular location on the screen, and then based on those counts, it can be used to cut out pieces of objects. The OpenGL functions which control the stencil buffer are glStencilOp(), glStencilFunc() and glStencilMask(). The corresponding pfFBState member functions are as follows:

void pfFBStateStencilOp(pfFBState* fbstate, GLenum stencilfail,
       GLenum zfail, GLenum zpass);
voi d pfFBStateStencilFunc(pfFBState* fbstate, GLenum func,
      GLint ref, GLuint mask);
void pfFBStateStencilMask(pfFBState* fbstate, GLuint mask);
void pfGetFBStateStencilOp(pfFBState* fbstate, GLenum *stencilfail,
       GLenum *zfail, GLenum *zpass);
void pfGetFBStateStencilFunc(pfFBState* fbstate, GLenum *func,
       GLint *ref, GLuint *mask);
void pfGetFBStateStencilMask(pfFBState* fbstate, GLuint *mask);

OpenGL is capable of blending objects that are being drawn with those that are already present in the framebuffer. Many blending modes are supported, all of which are specified with the OpenGL function glBlendFunc(). The corresponding pfFBState members functions are as follows:

void pfFBStateBlendFunc(pfFBState*	fbstate, GLenum	sfactor,
       GLenum dfactor);
void pfGetFBStateBlendFunc(pfFBState* fbstate, GLenum *sfactor,
       GLenum *dfactor);

The behavior of the blending function can be fine-tuned with additional information which is specified with the OpenGL glBlendEquation() and glBlendColor() functions. In pfFBState, you make the following calls:

void pfFBStateBlendEquation(pfFBState* fbstate, GLenum mode);
void pfFBStateBlendColor(pfFBState* fbstate, GLfloat r,
       GLfloat g, GLfloat b, GLfloat a);

void pfGetFBStateBlendEquation(pfFBState* fbstate,	GLenum *mode);
void pfGetFBStateBlendColor(pfFBState* fbstate, GLfloat *r,
       GLfloat *g,	GLfloat	*b, GLfloat *a);

The depth buffer is used to determine which objects occlude other objects so that interpenetrating objects are drawn correctly. The behavior of the depth buffer is controlled in OpenGL with the glDepthFunc(), glDepthRange() and glDepthMask() functions. The corresponding pfFBState functions are as follows:

void pfFBStateDepthFunc(pfFBState*	fbstate, GLenum	func);
void pfFBStateDepthRange(pfFBState* fbstate, GLclampd near,
       GLclampd far);
void pfFBStateDepthMask(pfFBState*	fbstate, GLboolean flag);

void pfGetFBStateDepthFunc(pfFBState* fbstate, GLenum *func);
void pfGetFBStateDepthRange(pfFBState* fbstate, GLclampd *near,
       GLclampd *far);
void pfGetFBStateDepthMask(pfFBState* fbstate, GLboolean *flag);

The color mask can be used to enable or disable writing to the red, green, blue and alpha channels in the framebuffer. The color mask is specified in OpenGL using the glColorMask() function. The pfFBState analog is the following:

void pfFBStateColorMask(pfFBState* fbstate, GLboolean r,
       GLboolean g, GLboolean b, GLboolean a);
void pfGetFBStateColorMask(pfFBState* fbstate, GLboolean *r,
       GLboolean *g, GLboolean *b, GLboolean *a);

The color matrix is used to transform colors during pixel transfer operations. Each color that is about to be written to the framebuffer during a pixel transfer operation is processed through this matrix and the resultant color is what is actually drawn. Pixel transfer operations include writing pixels directly to the screen using glDrawPixels(), downloading data to texture memory via the mechanisms in pfTexture, or doing framebuffer to framebuffer copies with glCopyPixels(). The color matrix is specified in OpenGL with the glMatrixMode() and glLoadMatrix() functions. The following pfFBState functions are used to specify and query this 4x4 row-major matrix in OpenGL Performer:

void pfFBStateColorMatrix(pfFBState* fbstate, GLfloat *matrix);
void pfGetFBStateColorMatrix(pfFBState* fbstate,
       GLfloat *matrix);

Like the color matrix, pixel scale and bias operate on pixel transfer operations. Pixel scale multiplies color values by a constant and pixel bias adds a constant according to the following equation:

Final Color = (Original Color x Scale) + Bias

All the terms in this equation are (R, G, B, A) values, so there can be a different scale and bias value for each color component. The pixel scale and bias are specified with the OpenGL glPixelTransfer() function. The corresponding functions in pfFBState are the following:

void pfFBStatePixelBias(pfFBState* fbstate, GLfloat r, GLfloat g,
       GLfloat b, GLfloat a);
void pfFBStatePixelScale(pfFBState* fbstate, GLfloat r,
       GLfloat g, GLfloat b, GLfloat a);

void pfGetFBStatePixelBias(pfFBState* fbstate, GLfloat *r,
       GLfloat *g, GLfloat *b, GLfloat *a);
void pfGetFBStatePixelScale(pfFBState* fbstate, GLfloat *r,
       GLfloat *g, GLfloat *b, GLfloat *a);

Pixel maps are lookup tables which operate on the pixel transfer pipeline. When pixel maps are active, the color which would ordinarily be written into the framebuffer is instead used as an index into a lookup table. The color which is actually written to the framebuffer is the value stored at that index in the lookup table. OpenGL supports a large number of color lookup modes, all of which are controlled with the glPixelMapfv() function. The analogous pfFBState functions take the same parameters. They are as follows:

void pfFBStatePixelMap(pfFBState* fbstate, GLenum which,
       GLsizei size, GLfloat *pixmapValues);
void pfGetFBStatePixelMap(pfFBState* fbstate, GLenum which,
       GLsizei *size, GLfloat *pixmapValues);

The glShadeModel() function is used to toggle between smooth shading and flat shading in OpenGL. pfFBState wraps this function into the following:

void pfFBStateShadeModel(pfFBState* fbstate, GLenum mode);
void pfGetFBStateShadeModel(pfFBState* fbstate, GLenum* mode);

All the functions cited earlier control the behavior of a particular OpenGL feature, but many of these features must be enabled when they are to be used and disabled otherwise. To this end, pfFBState provides the following functions:

void pfFBStateEnable(pfFBState* fbstate, GLenum mode, int flag);
void pfGetFBStateEnable(pfFBState* fbstate, GLenum mode, int *flag);

These functions take a feature to enable or disable as the first parameter and a flag that specifies the enable state. Passing in 0 for the flag will disable the feature and passing in any nonnegative value will enable it. The following are features whose state this function can toggle:

Though pfFBState appears to track state like a pfGeoState, it can not be directly applied to a pfGeoSet.There are two ways to apply the pfFBState: through a shader or within a draw callback. The shader method will be covered later in this chapter.

A pfFBState can be applied in any process which has an OpenGL context. The only process in OpenGL Performer that is guaranteed to have one is the draw process; so draw callbacks are the only place pfFBStates can be applied safely.

Like pfGeoState, pfFBState has an apply function which, when invoked, will change OpenGL state in such a way that it matches the state encoded inside the pfFBState. The following functions are available:

void pfApplyFBState(pfFBState* fbstate);
void pfFBStateMakeBasicState(pfFBState* fbstate);
void pfFBStateApplyBasicState(void);

When pfApplyFBState() is called, all the state settings which have been explicitly specified on the pfFBState will be applied, and all those which have not been specified will be inherited from the global pfFBState. The global pfFBState is configured as follows:

Since pfFBStates all inherit state they do not explicitly change from a set of global settings. This means that if two pfFBStates are applied consecutively, the state settings the first one makes will not be inherited by the second. A different way to think of it is that when a pfFBState is applied, the behavior is like that of the global default pfFBState being applied first, followed by the current state.

A shader is a class which encapsulates a multipass rendering algorithm which can be applied to the OpenGL Performer scene graph. Shaders operate only on pfGeoSets, but OpenGL Performer supplies helper classes that make it seem as if the shader can be applied anywhere in the scene.

The shader is implemented in Performer through the pfShader class. This class contains functions which are used to specify the multipass operations to perform on objects. pfShaders can be constructed in two ways: programatically and through the helper function pfdLoadShader().

Unlike other OpenGL Performer classes that represent the appearance of objects, pfShaders are not stored within the scene graph. Shaders are mapped to objects in the scene using the helper class pfShaderManager.

A pfShader class contains a list of rendering passes to be applied to geometry. Each of these passes contains state information on how to draw the geometry and how to blend it with what has already been drawn into the framebuffer. Passes are created in the pfShader using a modal interface in which a pass is opened, its attributes are specified and then the pass is closed. This is somewhat similar to the OpenGL glBegin() and glEnd() functions.

The function used to open (create) a pass is  pfShaderOpenPass(pfShader *shader, passType). Once a pass has been opened, all subsequent calls to pass modification functions will apply to that pass until it is closed with the  pfShaderClosePass() function. pfShaders can have any number of passes.

The following are the four pass types:

In any multipass algorithm, the results of each pass must be blended with the results of other passes. To this end, each one of the four pass types contains a pfFBState, which is applied before that pass performs any rendering. The per-pass pfFBState is specified by calling pfShaderPassAttr(pfShader *shader, which, void* attr). The second parameter of this function specifies the attribute to set, which in this case is PF_SHADERPASS_FBSTATE. The third parameter is a pointer to a pfFBState instance.

The pfShaderManager class encapsulates operations which add, remove and apply shaders to the scene graph. Unlike other OpenGL Performer objects such as pfGeoStates and pfNodes, pfShaders do not exist within the scene graph, so the shader manager is used as an alternate mechanism to associate shaders with scene graph nodes. Shaders are applied to nodes with the following function:

    
pfShaderManagerApplyShader(pfShaderManager* smgr,
       pfNode *node,pfShader *shader)

Shaders may be applied to any subclass of a pfNode. The entire subtree rooted at that node will then be shaded by the specified pfShader. Conversely, shaders may be removed from nodes with the following function:

    
pfShaderManagerRemoveShader(pfShaderManager* smgr, pfNode *node,
       int shaderNum)

The shader removal function takes a shader number, since multiple shaders may apply to a single node. This function will remove the specified shader from the specified node. The pfShaderManager also supports querying shaders which apply to a node using the following function:

    
pfGetShaderManagerShader(pfShaderManager* smgr, pfNode *node,
       int shaderNum)

Calling this function will return the shader at the specified index of the specified node. The number of shaders on a pfNode may be queried with the following function:

    
pfGetShaderManagerNumShaders(pfShaderManager* smgr, pfNode *node)

After mapping all shaders to applicable nodes in the scene graph using the pfShaderManager, the shaders must be pushed down to the pfGeoSet level since all rendering happens on that level. This is accomplished by calling the following function:

    
pfShaderManagerResolveShaders(pfShaderManager* smgr, pfNode *node)

This function compiles all the shaders which are mapped at or below the specified node into a OpenGL Performer internal format, which will then be passed to the pfGeoSets for rendering. During shader resolution, all temporary texture identifiers are mapped to pfTexture objects. The number of pfTextures created will be equal to the number of temporary texture identifiers allocated in the shader with the highest number of temporary textures. Shader resolution is an expensive operation; so, it should be only performed when shaders are either removed from nodes or added to nodes.

Since shaders may be applied anywhere in the scene graph, it often happens that one shader is applied closer to the root of the scene than another. In this case, both shaders will apply to the pfGeoSets that are present under the scene graph nodes that are common to both of them. When multiple shaders are applied to the tree above a given pfGeoSet, all the passes of the shader closest to that pfGeoSet will be rendered first, followed by all the passes of the next closest shader in the path to the root node, and so forth. Figure 10-2 shows a set of shaders mapped to a scene graph using a pfShaderManager and how the shaders end up applying to the pfGeoSets.

Figure 10-2. Shaders Mapped to a Scene Graph

The following basic data types are recognized in a shader description file:

The shader description file format provides limited support for the declaration and use of variables. As in programming languages such as C, variables must be declared before they may be used. Variable declaration takes place in the shader header while variable use takes place in the definition of the shader passes. Currently, only textures may be represented with variables and once declared in the header, a texture variable may not be changed or assigned to another.

Texture declarations take may take on three different forms depending on the source of the texture. Textures may come from image files, they may be defined as a 1D texture within the shader description file, or they may be used as temporary storage for the pfShader. In the case of temporary storage textures, the data within them comes from, and is restored to, the framebuffer.

Textures loaded from files are declared in the following manner:

	texture_def {
 	 texture_id	<identifier_type>
	  texture_src	<enumerated_constant_type>
	  texture_file	<string_type> 
	}

The enumerated constant data following the texture_src token must be equal to FILE.

When one of these texture declarations is found in a shader description file, a pfTexture object is created and the image file named by the string data is loaded. If the image file is successfully read from disk, an entry is added to the symbol table which maps the texture identifier to the corresponding pfTexture.

Textures specified as 1D textures within the shader description file are declared as follows:

	texture_def {
	  texture_id	<identifier_type>
	  texture_src	<enumerated_constant_type>
	  texture_table {
	    texture_table_size <integer_type>
	    texture_table_data <vector_type>
			.
			.
			.
	    texture_table_data <vector_type>
	  }
	}

The enumerated constant data following the texture_src token must be equal to TABLE.

When one of these texture declarations is found in a shader description file, the entries of the table are loaded into an array and a new pfTexture object is created. The array of table entries is specified as the pfTexture image and the dimensions of the pfTexture are set to indicate a 1D texture. An entry is then added to the symbol table which maps the texture identifier to the corresponding pfTexture.

Textures used as temporary storage during execution of the shader passes are declared as follows:

	texture_def {
	  texture_id	<identifier_type>
	  texture_src	<enumerated_constant_type>
	}

The enumerated constant data following the texture_src token must be equal to TMP.

When one of these texture declarations is found in a shader description file, pfShaderAllocateTempTexture() is called and the returned integer value is entered in the symbol table with the texture identifier for the texture. To provide for some optimization of texture memory usage, temporary storage textures are shared between pfShaders. For this reason, pfTexture objects are not created at load time for temporary textures. Instead, integer IDs are used to indicate which temporary texture is used by a pass. Later, when pfShaders are applied to scene graph nodes, the pfShaderManager can determine the maximum number of pfTexture objects to allocate. Once the pfShaderManager has created the pfTextures, it can resolve the mapping between IDs and actual pfTexture objects in the passes of all pfShaders it finds.

---

Note: It is an error to declare the same texture identifier more than once.

---

The shader file must contain all tokens and data within a block like the following:

        # comments can live outside the shader{} block

	shader {
	  # interesting shader description stuff 
	  # should be inserted here
	}

        # comments can live outside the shader{} block

Note that comments are anything on a line following the `#' character. The `#' character need not be the first character on the line.

Beneath this highest level description, the shader file contains a shader header and a definition of the shader passes.

The shader header describes everything about the shader that will not vary from one pass to another. This includes the name of the shader, the shader file revision, variables local to the shader, and the default state of the shader. Ignoring the placement of whitespace and newlines, the shader header must always be formed in a block like the following:

	shader_header {
	  shader_name		<string_type>
	  shader_major_rev	<integer_number_type>
	  shader_minor_rev	<integer_number_type>
	  shader_locals { 
	    .
	    .
	    .
	  }

	  shader_default_state {
	    .
	    .
	    .
	  }
	}

Any textures which will be used by the shader must be declared within the shader_locals block. See section “Variables” for a description of texture declarations.

---

Note: The shader_locals block may be empty.

---

The shader_default_state block contains all the state attributes which will not change on a per pass basis. See section “State Attributes”for a description of different state attributes.

---

Note: The shader_default_state block may be empty.

---

The shader passes definition describes the type of each pass, the order in which the passes are executed, and which state should be enabled for each pass. While there can be a variable number of passes, the shader passes must always be enclosed in a block like the following:

	shader_passes {
	  # pass definitions must be inserted here
	}

As described earlier in the section “Shading Concepts”, there are four basic pass types:

However, since there are three flavors of the copy-pixels pass, we effectively have six different types, which are described as follows:

Shader passes are always specified in the following form:

	geom_pass {
	  .
	  .
	  .
	}

	quad_geom_pass {
	  .
	  .
	  .
	}

	copy_pass {
	  .
	  .
	  .
	}

	copy_to_tex_pass {
	  .
	  .
	  .
	}

	copy_from_tex_pass {
	  .
	  .
	  .
	}

	accum_pass {
	  .
	  .
	  .
	}

Per-pass attributes are specified within the body of a pass block. Depending upon the pass type, certain state attributes may or may not be valid. The mapping between pass types and state attributes is described in Table 10-8.

The following section describes the individual attributes.

State attributes enable and set parameters for various rendering states that apply during execution of shader passes. The section “Shader Passes”describes which attributes are valid for the various pass types, but note that all state attributes are optional; that is, just because a state attribute is valid for a given pass type, it does not mean that it must be specified for that pass. Note also that it is an error to specify an attribute more than once per pass even if it is a valid attribute for that pass.

Each state attribute is described in detail in the following subsections.

	alpha_test {
	  alpha_test_func	<enumeranted_constant_type>
	  alpha_test_ref	<real_number_type>
	}

	LESS	
	LEQUAL
	GREATER
	GEQUAL
	EQUAL
	NOTEQUAL
	ALWAYS

	alpha_test {
	  disable
	}

	blend {
	  blend_eqn	<enumerated_constant_type>
	  blend_src	<enumerated_constant_type>
	  blend_dst	<enumerated_constant_type>
	}

	blend {
	  blend_eqn	<enumerated_constant_type>
	  blend_src	<enumerated_constant_type>
	  blend_dst	<enumerated_constant_type>
	  blend_color	<vector_type>
	}

	ADD
	SUBTRACT
	REVERSE_SUBTRACT
	MIN
	MAX
	LOGIC_OP

	ZERO
	ONE
	DST_COLOR
	ONE_MINUS_DST_COLOR
	SRC_ALPHA
	ONE_MINUS_SRC_ALPHA
	DST_ALPHA
	ONE_MINUS_DST_ALPHA
	SRC_ALPHA_SATURATE
	CONSTANT_COLOR
	ONE_MINUS_CONSTANT_COLOR
	CONSTANT_ALPHA
	ONE_MINUS_CONSTANT_ALPHA

	ZERO
	ONE
	SRC_COLOR
	ONE_MINUS_SRC_COLOR
	SRC_ALPHA
	ONE_MINUS_SRC_ALPHA
	DST_ALPHA
	ONE_MINUS_DST_ALPHA
	SRC_ALPHA_SATURATE
	CONSTANT_COLOR
	ONE_MINUS_CONSTANT_COLOR
	CONSTANT_ALPHA
	ONE_MINUS_CONSTANT_ALPHA

CONSTANT_COLOR
ONE_MINUS_CONSTANT_COLOR
CONSTANT_ALPHA
ONE_MINUS_CONSTANT_ALPHA

	blend {
	  disable
	}

	color {
	  color_data <vector_type>
	}

	color_mask {
	  color_mask_data <integer_number_type>
	}

	color_matrix {
	  matrix_data <matrix_type>
	}

	depth_test {
	  depth_test_func <enumerated_constant_type>
	}

	LESS	
	LEQUAL
	GREATER
	GEQUAL
	EQUAL
	NOTEQUAL
	ALWAYS

	depth_test {
	  disable
	}

	
	lights {
	  light {
	    .
	    .
	    .
	  }
  	  .
	  .
	  .
	  light {
	    .
	    .
	    .
	  }
	}

	light {
	  light_position <vector_type>

	  spot_light_cone {
	    spot_light_cone_exponent	<real_number_type>
	    spot_light_cone_cutoff	<real_number_type>
          }

	  light_ambient  <vector_type>

	  light_diffuse  <vector_type>

	  light_specular <vector_type>

	  light_attenuation {
	    light_constant_attenuation	<real_number_type>
	    light_linear_attenuation	<real_number_type>
	    light_quadratic_attenuation	<real_number_type>
          }
	}

	light {
	  light_position (1 0 0 1)
	  light_position (0 10 0 1)
	}

	lights {
	  disable
	}

	material {
	  material_emission  <vector_type>
	  material_ambient   <vector_type>
	  material_diffuse   <vector_type>
	  material_specular  <vector_type>
	  material_shininess <real_number_type>
	}

	material {
	  material_emission	(0.25 0 0 1)
	  material_diffuse	(1 0 0 1)
	  material_emission	(0.75 0 0.25 1)
	}

	pixel_bias {
	  pixel_bias_data <vector_type>
	}

	pixel_scale {
	  pixel_scale_data <vector_type>
	}

	pixmaps {
	  pixmap {}
	    .
	    .
	    .
	  pixmap {}
	}

	pixmap {
	  pixmap_component	<enumerated_constant_type>
	  pixmap_size		<integer_number_rule>
	  pixmap_data		<real_number_rule>
	    .
	    .
	    .
	  pixmap_data		<real_number_rule>
	}

	RED
	GREEN
	BLUE
	ALPHA

	pixmaps {
	  disable
	}

	shade_model {
	  shade_model_mode <enumerated_constant_type>
	}

	stencil_test {
	  stencil_test_func	<enumerated_constant_type>
	  stencil_test_ref	<integer_number_type>
	  stencil_test_mask	<integer_number_type>
	  stencil_test_sfail	<enumerated_constant_type>
	  stencil_test_zfail	<enumerated_constant_type>
	  stencil_test_zpass	<enumerated_constant_type>
	  stencil_test_wmask	<integer_number_type>
	}

	LESS	
	LEQUAL
	GREATER
	GEQUAL
	EQUAL
	NOTEQUAL
	ALWAYS

	KEEP
	ZERO
	REPLACE
	INCR
	DECR
	INVERT

	stencil_test {
	  disable
	}

	texenv {
	  texenv_mode	<enumerated_constant_type>
	}

	texenv {
	  texenv_mode	<enumerated_constant_type>
	  texenv_color	<vector_type>
	}

	MODULATE
	BLEND
	DECAL
	REPLACE
	ADD
	ALPHA

	texgens {
	  texgen {}
	    .
	    .
	    .
	  texgen {}
	}

	texgen {
	  texgen_coord	<enumerated_constant_type>
	  texgen_mode	<enumerated_constant_type>
	}

	texgen {
	  texgen_coord	<enumerated_constant_type>
	  texgen_mode	<enumerated_constant_type>
	  texgen_plane	<vector_type>
	}	

S
T
R
Q

	EYE_LINEAR
	OBJECT_LINEAR
	SPHERE_MAP

	texgens {
  	  texgen {
	    texgen_coord	 S
	    texgen_mode		EYE_LINEAR
	  }
  	  texgen {
	    texgen_coord	 S
	    texgen_mode		OBJECT_LINEAR
	  }
	}

	texgens {
	  disable
	}

	texture {
	  texture_id <identifier_type>
	}

	texture {
	  disable
	}

	texture_matrix {
	  matrix_data	<matrix_type>
	}

Here is a very simple two-pass shader, which combines one pass of constant color with another pass using a table texture.

shader {

  # one time shader setup is done here
  shader_header {
    shader_name            “example shader”
    shader_major_rev       1
    shader_minor_rev       0

    shader_locals {
      texture_def {
        texture_id $table
        texture_src TABLE
        texture_table {
          texture_table_size 8
          texture_table_data (0.00 0.00 0.00 1)
          texture_table_data (0.14 0.14 0.14 1)
          texture_table_data (0.29 0.29 0.29 1)
          texture_table_data (0.43 0.43 0.43 1)
          texture_table_data (0.57 0.57 0.57 1)
          texture_table_data (0.71 0.71 0.71 1)
          texture_table_data (0.86 0.86 0.86 1)
          texture_table_data (1.00 1.00 1.00 1)
        }
      }
    }
        
    shader_default_state { 
        depth_test {
          depth_test_func LEQUAL
        }
    }
  }

  # begin specification of shader passes
  shader_passes {
    geom_pass {
        color {
          color_data (1 1 0 1)
        }
    }
    geom_pass {
        blend {
          blend_eqn ADD
          blend_src DST_COLOR
          blend_dst ZERO
        }       
        texture {
          texture_id $table
        }
        texture_matrix {
          matrix_data (8 0 0 0)
                      (0 1 0 0)
                      (0 0 1 0)
                      (0 0 0 1)
        }       
    }
  }
}