---

sglStatelet Class Reference

#include <sglStatelet.hpp>

Inheritance diagram for sglStatelet::

List of all members.

Public Types
enum	StateEnum {   eALPHA_TEST,   eANTI_ALIAS_LINE,   eANTI_ALIAS_POINT,   eANTI_ALIAS_POLYGON,   eBLENDING,   eCOLOR_MASK,   eCULL_MODE,   eDEPTH_MASK,   eDEPTH_RANGE,   eDEPTH_TEST,   eDITHERING,   eFOG,   eFRONT_FACE,   eHIGHLIGHT,   eLIGHTING,   eLINE_STIPPLE,   eLINE_WIDTH,   eLOGIC_OP,   eMATERIAL,   eOCCLUSION_CULL,   ePOINT_SIZE,   ePOINT_PARAMETERS,   ePOLY_BACK_STYLE,   ePOLY_FRONT_STYLE,   ePOLYGON_OFFSET,   ePOLYGON_STIPPLE,   eSHADE_MODEL,   eTRANSFORM_MATRIX,   eTRANSPARENCY,   eTEX_ENV,   eTEX_GEN,   eTEXTURE,   eTEXTURE_MATRIX,   eNUM_BASIC_STATES }
Public Methods
virtual	~sglStatelet ()
virtual unsigned int	getType () const
virtual void	apply (sglCurrState *curr_state) const=0
virtual bool	getSorted () const
const void*	getSortKey () const
unsigned int	getIndex () const
bool	operator== (const sglStatelet &rhs) const
virtual void	printInfo (ostream &ostrm, const char *indent_string) const
Protected Methods
	sglStatelet (StateEnum type)
Protected Attributes
unsigned int	m_index

---

Detailed Description

This is the base class for all "elements" of OpenGL state that SGL manages/sorts. Examples of subclasses include sglTexture2D, sglMaterial, sglFog, sglLineAntiAlias, etc. An entire set of sglStatelet subclasses determine the "state" of any given sglDrawable. This "state" is determined from a number of different sources in a specific priority order as follows:

1. The sglScene::createDefaultStatelets() creates a complete set of "baseline" statelets using the default constructor of each. These are generated at the beginning of the cull traversal and are the lowest priority.

2. Stateletes contained in any sglDefaultStateNode's encountered in the scene graph traversal overwrite these values in the order they are encountered; therefore, sglDefaultStateNode's lower in the tree (farther from the root) take precedence over those higher in the tree.

3. Statelets encountered in the sglDrawable (using the sglDrawable::setState() function) overwrite the full state last and thus take precedence over all the default states and the sglDefaultStateNode's.

4. Statelets in sglOverrideStateNode's have priority over all the default and drawable statelets. Statelets in sglOverrideStateNode's higher in the scene graph (closer to the root) have priority over those in nodes lower in the scene graph (opposite that of sglDefaultStateNode).

5. Statelets in the override_statelets parameter passed into the sglScene::cull() functions when starting the cull traversal have the highest priority.

Each element of OpenGL state has been implemented in a separate class to also aid in state sorting. State sorting occurs as the cull traversal encounters sglDrawables that have passed the cull test and before they are rendered. By performing state sorting, sglDrawables with statelets that are the same can be grouped together to avoid issuing duplicate OpenGL state commands. For example, two sglDrawables that use the same texture can be grouped together, and a single set of OpenGL texture commands will be issued to the rendering pipeline before both drawables are rendered. This reduction in OpenGL state commands can improve the performance of an application. The statelets can be sorted by SGL in any user defined order by passing a vector of sglStatelet::StateEnum's into sglCull::setSortOrder(). For instance, if you want sort the nodes to be rendered by texture first and then within that group by material the following code might be used:

   sglCullf trav_state;
     :
   vector<sglStatelet::StateEnum> sort_order;
   sort_order.push_back(sglStatelet::eTEXTURE);
   sort_order.push_back(sglStatelet::eMATERIAL);

   trav_state.setSortOrder(sort_order);

Note, there is no "best" sort order. The best sort order is dependent on the graphics hardware/driver and the contents of your scene. See the testTraversal program for examples of two scene graphs that work best with completely different sort orders.

Arbitrarily long sort orders can be specified but longer sort orders require more computation and quickly suffer from diminishing returns after the first two or three. Also note that some sorts are more expensive than others. Obviously, the more attributes that you sort on the more time it is going to take. You should also be aware that statelets that can take on an unlimited number of values (e.g. material, texture, etc) have a worst case O(n*logn) sort time. Statelets with a fixed number of values (e.g., any boolean statelets, polygon style, etc.) have a worst case O(n) sort time.

Implementation Notes:

This base class implements a number of the functions that the internal state sorting mechanism uses: getSorted, getSortKey, and getIndex. Each subclass is responsible for setting the m_index member variable in the sglStatelet base class. If the statelet can only take on a few distinct modes (e.g. disable or enable line anti-aliasing) then m_index should be set to a unique small unsigned integer corresponding to each unique mode. This value should start at zero and cover a contiguous set of values. If the statelet can take on a nearly infinite number of modes (e.g. RGB floating point color value), then m_index should be set to UINT_MAX. The state sorting algorithm calls the getIndex() member function to get this index, and if it is set to UINT_MAX it will sort this particular statelet by its pointer rather than the index number.

The default implementation of getSorted() is to return false indicating that the statelet should be sorted by using m_index to index into an array of possible statelets (which take on the state corresponding to that index). If m_index can be set to UINT_MAX, then that subclass must override the getSorted() function to return true. In this case the state sorting mechanism will call the getSortKey() function and sort on its return value.

Note that a given subclass can set m_index to small unsigned integers for a subset of its more common states and UINT_MAX for other states (see sglAlphaTest for an example). In this case the getSorted() function should return true and the getSortKey() will return a pointer to the statelet if m_index is UINT_MAX or a pseudo-pointer equal to m_index otherwise to make it appear that statelets of this type with the same m_index will be treated as the same state for sorting purposes.

Subclassing sglStatelet:

The following is the procedure for creating new subclasses of sglStatelet:

1. Add an enum to the sglStatelet::StateEnum list corresponding to the statelet created. The naming convention for the enum: if the class is sglCullMode the enum label is eCULL_MODE (an 'e' prefix, and underscore separated words). This can be added to the enum list anywhere before the texture related statelets.

2. Implement the default constructor that builds the statelet with the default mode for that portion of OpenGL state. Generally this constructor should initialize the object so that apply() will issue OpenGL calls equal to OpenGL's default for them. This and all other constructors must call the sglStatelet constructor in the initialization list with the correct StateEnum as the parameter.

3. Add code to set sglStatelet::m_index variable appropriately (see discussion above).

4. Implement the virtual apply() method with all of the OpenGL commands needed to set up the state.

5. Implement a printInfo() function that calls the base class printInfo() function and then outputs its own state.

6. If necessary, implement the getSorted() virtual function to return true (only if m_index can be set to UINT_MAX).

7. Modify sglScene::createDefaultStatelets to push a heap allocated copy of the statelet (using the default constructor) onto the the full list of statelets. IMPORTANT: it must be added to the vector in the order they appear in the sglStatelet::StateEnum list below.

Todo:

Add sglScribe statelet (a la Performer) where wire frame is rendered on top of the filled geometry.

Add sglNormalsDisplay statelet (a la Performer) where normals are rendered along with the geometry.

Definition at line 177 of file sglStatelet.hpp.

---

Member Enumeration Documentation

enum sglStatelet::StateEnum

The complete list of state enums in alphabetical order with the exception that all texture/multitexture states must come last. These enum values will be used as indexes into arrays of statelets (sglFullState). Definition at line 185 of file sglStatelet.hpp.

---

Constructor & Destructor Documentation

sglStatelet::~sglStatelet ( ) [inline, virtual]

virtual destructor Definition at line 238 of file sglStatelet.hpp.

---

Member Function Documentation

unsigned int sglStatelet::getType ( ) const [inline, virtual]

Get an identifier for the type of this statelet. Returns: The StateEnum corresponding to the type of statelet. For texturing statelets beyond the first texture unit integers beyond the last StateEnum value are returned. Reimplemented in sglMultiTextureStatelet. Definition at line 245 of file sglStatelet.hpp.

void sglStatelet::apply ( sglCurrState * curr_state ) const [pure virtual]

Apply this state change to the current rendering state. Parameters: curr_state   Required for statelets that affect one another. For example the sglTransparency sets up depth mask and blending modes which interact with the sglBlending and sglDepthMask statelets, and the curr_state object is used to resolve these internal issues. Reimplemented in sglFog, sglMaterial, sglAlphaTest, sglAntiAliasLine, sglAntiAliasPoint, sglAntiAliasPolygon, sglBlending, sglColorMask, sglCullMode, sglDepthMask, sglDepthRange, sglDepthTest, sglDithering, sglFrontFace, sglHighlight, sglLighting, sglLineStipple, sglLineWidth, sglLogicOp, sglOcclusionCull, sglPointSize, sglPointParameters, sglPolyBackStyle, sglPolyFrontStyle, sglPolygonOffset, sglPolygonStipple, sglShadeModel, sglTexturingStatelet, sglMultiTextureStatelet, and sglTransparency.

bool sglStatelet::getSorted ( ) const [inline, virtual]

Query the sorting mode for this statelet. Returns: true if this type of statelet should be sorted by pointer rather than using m_index to index into an array. The defualt implementation is the latter, but if a statelet can take on an inordinate number of states (e.g. a floating point parameter) then true should be returned. Reimplemented in sglFog, sglMaterial, sglAlphaTest, sglBlending, sglDepthRange, sglLineStipple, sglLineWidth, sglPointSize, sglPointParameters, sglPolygonOffset, sglPolygonStipple, sglMultiTextureStatelet, sglTextureMatrix, sglTexEnv, sglTexGen, and sglTexture. Definition at line 262 of file sglStatelet.hpp. Referenced by sglMultiTextureStatelet::getSorted().

const void * sglStatelet::getSortKey ( ) const [inline]

If getSorted() returns true, then this function is used to retrieve the key (pointer) to sort with. This function is non-virtual so that access to it can be inlined in the cull traversal for speed. Returns: Pointer to the statelet or a pseudo pointer equal to m_index. Definition at line 269 of file sglStatelet.hpp.

unsigned int sglStatelet::getIndex ( ) const [inline]

If getSorted() returns false, then this function is used to retrieve an index that can be used as a lookup key in a table for state sorting. This function is non-virtual so that access to it can be inlined in the cull traversal for speed. Returns: Index corresponding to the state of the statelet. Definition at line 283 of file sglStatelet.hpp.

bool sglStatelet::operator== ( const sglStatelet & rhs ) const [inline]

The equality operator Parameters: rhs   The object to which to compare this statelet. Returns: true if the rhs is the same as this. Definition at line 289 of file sglStatelet.hpp.

virtual void sglStatelet::printInfo ( ostream & ostrm, const char * indent_string ) const [virtual]

Output the state of this node to the specified ostream. Parameters: ostrm   the ostream to which the output is sent indent_string   the string (usually spaces) that is output at the beginning of every line of output Reimplemented from sglObject. Reimplemented in sglFog, sglMaterial, sglBooleanStatelet, sglAlphaTest, sglBlending, sglColorMask, sglCullMode, sglDepthRange, sglDepthTest, sglFrontFace, sglLineStipple, sglLineWidth, sglLogicOp, sglOcclusionCull, sglPointSize, sglPointParameters, sglPolyStyle, sglPolygonOffset, sglPolygonStipple, sglShadeModel, sglTextureMatrix, sglTexEnv, sglTexGen, sglTexture, sglTexture1D, and sglTexture2D.

---

The documentation for this class was generated from the following file:

• sglStatelet.hpp

---