---

sglObject Class Reference

#include <sglObject.hpp>

Inheritance diagram for sglObject::

List of all members.

Public Types
enum	CloneModeEnum {   eCLONE_ONE_NODE = 0,   eCLONE_NODES_RECURSIVE = 0x01,   eCLONE_USER_DATA = 0x02 }
Public Methods
	sglObject ()
virtual	~sglObject ()=0
void	ref ()
void	deref ()
unsigned int	getRefCount () const
void	setName (const string &name)
const string&	getName () const
void	setUserData (sglUserData *data)
sglUserData*	getUserData () const
virtual void	printInfo (ostream &ostrm, const char *indent_string) const
Protected Methods
void	copyTo (sglObject *dst, unsigned int mode) const
Protected Attributes
unsigned int	m_ref_count
sglUserData*	m_user_data
string	m_name

---

Detailed Description

This is the abstract base class for (nearly?) all objects that appear in the scene graph including the group and leaf nodes, the geometry nodes, and statelets. Through this class the user can assign a name (character string), associate application-specific user data and query/modify the reference count of these objects.

Reference Counting

All objects in the scene graph are (or should be) reference counted. Whenever a node is added as a child to another (see sglGroup), the node's reference count is incremented. Likewise, the reference count is decremented when the node is removed as a child to another node. If the reference count goes to zero it is safe to destruct the object as it is no longer referenced by anything in the scene graph. The scene graph does not automatically destruct a node when its reference count goes to zero (particularly when calling sglGroup::removeChild() or sglGeode::removeGeometry()). The exception to this rule is the destruction of statelets if their reference count goes to zero during a call to sglDrawable::removeState().

Another circumstance in which SGL will automatically destruct an sglObject is when an sglObject references other sglObjects (as in the cases of child sglNodes of an sglGroup, child sglDrawable's of an sglGeode, or sglStatelets of an sglDrawable) and is destructed, the reference counts of those objects it references is decremented. If at anytime those reference counts goes to zero, then those objects are destructed as well. The process continues recursively to all objects in the scene graph below the object destructed by the user.

The user may also explicitly increment and decrement the reference count with ref() and deref() member functions. For example, the ref() function can be called when the object is an integral part (member) of another class or even allocated off the stack to prevent improper destruction of the object. Caution: if deref() is attempted for an sglNode that has a reference count of zero, causes an assertion failure.

NOTE: not all data in the scene graph is currently reference counted and special care must be taken by the user to manage it. This is most important for the attribute data referenced by sglDrawable nodes (vertices, normals, color vertices, and index arrays and their states (texture coordinates).

Application-specific data

An application that uses SGL can associate application specific data with any of the classes derived from sglObject. The only caveat is that the application's user data must be encapsulated in a class derived from sglUserData.

The printInfo function

All subclasses of sglObject should also implement the printInfo function that first calls its base class' version of this function and then outputs an informational data about the node's current state. This function is used in a couple of sglu functions for outputting all or portions of a scene graph (good for debugging).

Example:

   sglGroup *node = new sglGroup; // a subclass of sglObject (via sglNode)
   node->setName("Foo");          // sets name
   char *name = node->getName();  // returns pointer to name
   node->printInfo(cout, "  ");   // output node info to cout w/ 2 space indent

   node->ref();                   // increment the reference count
   unsigned int count = node->getRefCount();  // returns 1
   node->deref();                 // decrement the reference count
   node->deref();                 // ERROR: causes assertion failure

Proposal: subclass from an sglMemory class to manage/track memory allocation?

Definition at line 112 of file sglObject.hpp.

---

Member Enumeration Documentation

enum sglObject::CloneModeEnum

Mode bits for the clone traversal function in sub classes Enumeration values: eCLONE_ONE_NODE   clone just this node. eCLONE_NODES_RECURSIVE   clone all sglNodes (not drawables). eCLONE_USER_DATA   clone the user data (references only). Definition at line 117 of file sglObject.hpp.

---

Constructor & Destructor Documentation

sglObject::sglObject ( )

default constructor.

sglObject::~sglObject ( ) [pure virtual]

destructor: pure virtual to ensure abstractness.

---

Member Function Documentation

void sglObject::ref ( ) [inline]

Increment the reference count. Definition at line 142 of file sglObject.hpp. Referenced by sglTexCoords::sglTexCoords().

void sglObject::deref ( ) [inline]

Decrement the reference count. An assertion failure will occur if this count goes negative. Definition at line 147 of file sglObject.hpp.

unsigned int sglObject::getRefCount ( ) const [inline]

Get the current reference count. Returns: current reference count Definition at line 152 of file sglObject.hpp.

void sglObject::setName ( const string & name ) [inline]

Set the name of this object (the string is copied into this object). Parameters: name   reference to a string containing the name. Definition at line 157 of file sglObject.hpp.

const string & sglObject::getName ( ) const [inline]

Get the name of this object Returns: const reference to the string Definition at line 162 of file sglObject.hpp.

void sglObject::setUserData ( sglUserData * data ) [inline]

Set the user data. This data will NOT be destructed with this sglObject. Parameters: data   pointer to the user data object. Pass NULL to clear the data. Definition at line 169 of file sglObject.hpp.

sglUserData * sglObject::getUserData ( ) const [inline]

Get the user data pointer Returns: pointer to the user data object Definition at line 174 of file sglObject.hpp.

void sglObject::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 in sglAnimation, sglBillboard, sglBitMaskSwitch, sglCallback, sglCamera, sglDefaultStateNode, sglDirectionalLight, sglDiscriminator, sglDistanceSwitch, sglLOD, sglDrawable, sglFog, sglGeode, sglGeoSet, sglGroup, sglIndexedBitMaskSwitch, sglInterleavedGeometry, sglKeyFrameAnimation, sglLayer, sglLight, sglLOD, sglLODState, sglLODStateNode, sglMaterial, sglNode, sglOrderedGroup, sglOrthographicCamera, sglOverrideStateNode, sglPerspectiveCamera, sglPositionalLight, sglScale, sglScene, sglSphericalTransform, sglSpotLight, sglStatelet, sglBooleanStatelet, sglAlphaTest, sglBlending, sglColorMask, sglCullMode, sglDepthRange, sglDepthTest, sglFrontFace, sglLineStipple, sglLineWidth, sglLogicOp, sglOcclusionCull, sglPointSize, sglPointParameters, sglPolyStyle, sglPolygonOffset, sglPolygonStipple, sglShadeModel, sglTextureMatrix, sglSwitch, sglTexCombinerParams, sglTexEnv, sglTexGen, sglTextSet, sglTexture, sglTexture1D, sglTexture2D, sglTexturedTextSet, sglTimedAnimation, sglTransform, sglTranslate, sglUnProject, sglUnScale, sglUnScaleRange, sglViewPlatform, and sglCylinder.

---

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

• sglObject.hpp

---