cGenericObject Class Reference
[Scenegraph]

This class is the root of basically every render-able object in CHAI. It defines a reference frame (position and rotation) and virtual methods for rendering, which are overloaded by useful subclasses.
. More...

#include <CGenericObject.h>

Inheritance diagram for cGenericObject:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 cGenericObject ()
 Constructor of cGenericObject.
virtual ~cGenericObject ()
 Destructor of cGenericObject.
void setPos (const cVector3d &a_pos)
 Set the local position of this object.
void setPos (const double a_x, const double a_y, const double a_z)
 Set the local position of this object.
cVector3d getPos () const
 Get the local position of this object.
cVector3d getGlobalPos () const
 Get the global position of this object.
void setRot (const cMatrix3d &a_rot)
 Set the local rotation matrix for this object.
cMatrix3d getRot () const
 Get the local rotation matrix of this object.
cMatrix3d getGlobalRot () const
 Get the global rotation matrix of this object.
void translate (const cVector3d &a_translation)
 Translate this object by a specified offset.
void translate (const double a_x, const double a_y, const double a_z)
 Translate this object by a specified offset.
void rotate (const cMatrix3d &a_rotation)
 Rotate this object by multiplying with a specified rotation matrix.
void rotate (const cVector3d &a_axis, const double a_angle)
 Rotate this object around axis a_axis by angle a_angle (radians).
void computeGlobalPositions (const bool a_frameOnly=true, const cVector3d &a_globalPos=cVector3d(0.0, 0.0, 0.0), const cMatrix3d &a_globalRot=cIdentity3d())
 Compute the global position and rotation of this object and its children.
void computeGlobalCurrentObjectOnly (const bool a_frameOnly=true)
 Compute the global position and rotation of current object only.
void computeGlobalPositionsAndMotion (const bool a_frameOnly=true, const cVector3d &a_globalPos=cVector3d(0.0, 0.0, 0.0), const cMatrix3d &a_globalRot=cIdentity3d())
 Compute the global position and rotation with relative motion of this object and its children.
cVector3d computeInteractions (const cVector3d &a_toolPos, const cVector3d &a_toolVel, const unsigned int a_IDN, cInteractionRecorder &a_interactions, cInteractionSettings &a_interactionSettings)
void addEffect (cGenericEffect *a_newEffect)
 add an effect.
void setStiffness (double a_stiffness, const bool a_affectChildren=0)
 Set the haptic stiffness, possibly recursively affecting children.
void setFriction (double a_staticFriction, double a_dynamicFriction, const bool a_affectChildren=0)
 Set the static and dynamic friction for this mesh, possibly recursively affecting children.
void setShowEnabled (const bool a_show, const bool a_affectChildren=false)
 Show or hide this object, optionally propagating the change to children.
bool getShowEnabled () const
 Read the display status of object (true means it's visible).
void setHapticEnabled (const bool a_hapticEnabled, const bool a_affectChildren=false)
 Allow this object to be felt (when visible), optionally propagating the change to children.
bool getHapticEnabled () const
 Read the haptic status of object (true means it can be felt when visible).
void setShowTree (const bool a_showTree, const bool a_affectChildren=false)
 Show or hide the child/parent tree, optionally propagating the change to children.
bool getShowTree () const
 Read the display status of the tree (true means it's visible).
void setTreeColor (const cColorf &a_treeColor, const bool a_affectChildren=false)
 Set the tree color, optionally propagating the change to children.
cColorf getTreeColor () const
 Read the tree color.
void setShowFrame (const bool a_showFrame, const bool a_affectChildren=false)
 Show or hide the reference frame arrows for this object, optionally propagating the change to children.
bool getShowFrame (void) const
 Read the display status of the reference frame (true means it's visible).
void setShowBox (const bool iShowBox, const bool iAffectChildren=false)
 Show or hide the boundary box for this object, optionally propagating the change to children.
bool getShowBox () const
 Read the display status of boundary box. (true means it's visible).
void setBoxColor (const cColorf &a_boxColor, const bool a_affectChildren=false)
 Set the color of boundary box for this object, optionally propagating the change to children.
cColorf getBoxColor () const
 Read the color of boundary box.
void setShowCollisionTree (const bool a_showCollisionTree, const bool a_affectChildren=false)
 Show or hide the collision tree for this object, optionally propagating the change to children.
bool getShowCollisionTree ()
 Read the display status of of the collision tree for this object.
virtual void onDisplayReset (const bool a_affectChildren=true)
 This function should get called when it's necessary to re-initialize the OpenGL context.
virtual void finalize (const bool a_affectChildren=true)
 This function tells children that you're not going to change their contents any more.
virtual void unfinalize (const bool a_affectChildren=true)
 This function tells objects that you may modify their contents.
virtual void renderSceneGraph (const int a_renderMode=CHAI_RENDER_MODE_RENDER_ALL)
 Render the entire scene graph, starting from this object.
void setMaterial (cMaterial &a_mat, const bool a_affectChildren=false, const bool a_applyPhysicalParmetersOnly=false)
 Set the material for this mesh, and optionally pass it on to my children.
virtual void setTransparencyLevel (const float a_level, const bool a_applyToTextures=false, const bool a_affectChildren=true)
 Set the alpha value at each vertex and in all of my material colors.
void setTransparencyRenderMode (const bool a_useMultipassTransparency, const bool a_affectChildren=true)
 Specify whether this mesh should use multipass transparency (see cCamera).
bool getMultipassTransparencyEnabled () const
 Is multipass transparency used for this mesh?
void setUseTransparency (const bool a_useTransparency, const bool a_affectChildren=true)
 Enable or disable transparency (also see setTransparencyRenderMode)... turns the depth mask _off_!
bool getUseTransparency () const
 Is transparency enabled for this mesh?
void setWireMode (const bool a_showWireMode, const bool a_affectChildren=true)
 Enable or disable wireframe rendering, optionally propagating the operation to my children.
bool getWireMode () const
 Return whether wireframe rendering is enabled.
void setUseCulling (const bool a_useCulling, const bool a_affectChildren=true)
 Enable or disabling face-culling, optionally propagating the operation to my children.
bool getUseCulling () const
 Is face-culling currently enabled?
void setUseVertexColors (const bool a_useColors, const bool a_affectChildren=true)
 Enable or disable the use of per-vertex colors, optionally propagating the operation to my children.
bool getUseVertexColors () const
 Are per-vertex properties currently enabled?
void setUseMaterial (const bool a_useMaterial, const bool a_affectChildren=true)
 Enable or disable the use of material properties, optionally propagating the operation to my children.
bool getUseMaterial () const
 Are material properties currently enabled?
void setUseTexture (const bool a_useTexture, const bool a_affectChildren=true)
 Enable or disable the use of texture-mapping, optionally propagating the operation to my children.
bool getUseTexture () const
 Is texture-mapping enabled?
void setTexture (cTexture2D *a_texture, const bool a_affectChildren=0)
 Set my texture, possibly recursively affecting children.
cTexture2D * getTexture () const
 Access my texture.
cVector3d getBoundaryMin () const
 Read the minimum point of this object's boundary box.
cVector3d getBoundaryMax () const
 Read the maximum point of this object's boundary box.
cVector3d getBoundaryCenter () const
 Compute the center of this object's boundary box.
void computeBoundaryBox (const bool a_includeChildren=true)
 Re-compute this object's bounding box, optionally forcing it to bound child objects.
bool setFrameSize (const double a_size=1.0, const double a_thickness=1.0, const bool a_affectChildren=false)
 Set the size of the rendered reference frame, optionally propagating the change to children.
double getFrameSize () const
 Read the size of the rendered reference frame.
void setCollisionDetector (cGenericCollision *a_collisionDetector)
 Set a collision detector for current object.
cGenericCollision * getCollisionDetector () const
 Get pointer to this object's current collision detector.
void setCollisionDetectorProperties (unsigned int a_displayDepth, cColorf &a_color, const bool a_affectChildren=false)
 Set collision rendering properties.
void deleteCollisionDetector (const bool a_affectChildren=false)
 Delete any existing collision detector and set the current cd to null (no collisions).
bool computeCollisionDetection (cVector3d &a_segmentPointA, cVector3d &a_segmentPointB, cCollisionRecorder &a_recorder, cCollisionSettings &a_settings)
 Compute collision detection using collision trees.
virtual void adjustCollisionSegment (cVector3d &a_segmentPointA, cVector3d &a_segmentPointAadjusted)
 Adjust collision segment for dynamic objects.
void setParent (cGenericObject *a_parent)
 Set parent of current object.
cGenericObject * getParent () const
 Read parent of current object.
cGenericObject * getChild (const unsigned int a_index) const
 Read an object from my list of children.
void addChild (cGenericObject *a_object)
 Add an object to my list of children.
bool removeChild (cGenericObject *a_object)
 Remove an object from my list of children, without deleting it.
bool containsChild (cGenericObject *a_object, bool a_includeChildren=false)
 Does this object have the specified object as a child?
bool deleteChild (cGenericObject *a_object)
 Remove an object from my list of children and delete it.
void clearAllChildren ()
 Clear all objects from my list of children, without deleting them.
void deleteAllChildren ()
 Clear and delete all objects from my list of children.
unsigned int getNumChildren ()
 Return the number of children on my list of children.
unsigned int getNumDescendants (bool a_includeCurrentObject=false)
 Return my total number of descendants, optionally including this object.
void enumerateChildren (std::list< cGenericObject * > &a_childList, bool a_includeCurrentObject=true)
 Fill this list with all of my descendants.
bool removeFromGraph ()
 Remove me from my parent's CHAI scene graph.
void setAsGhost (bool a_ghostStatus)
 Makes this object a ghost node.
bool getAsGhost ()
 Read the ghost status of this object.
void setExternalParent (cGenericType *a_externalParent, const bool a_affectChildren=false)
 Sets a pointer to an external parent of the current object. Optionally propagating the change to children.
cGenericType * getExternalParent ()
 Get the external parent of current object.
void setSuperParent (cGenericObject *a_superParent, const bool a_affectChildren=false)
 Sets the super parent of the current object. Optionally propagating the change to children.
cGenericObject * getSuperParent ()
 Get the super parent of current object.
void scale (const double &a_scaleFactor, const bool a_includeChildren=true)
 Scale this object by a_scaleFactor (uniform scale).
void scale (const cVector3d &a_scaleFactors, const bool a_includeChildren=true)
 Non-uniform scale.
virtual void setTag (const int a_tag, const bool a_affectChildren=0)
 Set the tag for this object and - optionally - for my children.
virtual void setUserData (void *a_data, const bool a_affectChildren=0)
 Set the m_userData pointer for this object and - optionally - for my children.
virtual void setName (const char *a_name, const bool a_affectChildren=0)
 Set the name for this object and - optionally - for my children.

Public Attributes

cVector3d m_interactionProjectedPoint
 Projection of the latest interaction point with the surface (limits) of the current object.
bool m_interactionInside
 Was the last interaction point located inside the object?
vector< cGenericEffect * > m_effects
 list of haptic effects.
cMaterial m_material
 Material properties.
cTexture2D * m_texture
 Texture property.
int m_tag
 An arbitrary tag, not used by CHAI.
void * m_userData
 An arbitrary data pointer, not used by CHAI.
char m_objectName [CHAI_SIZE_NAME]
 A name for this object, automatically assigned by mesh loaders (for example).

Protected Member Functions

virtual void render (const int a_renderMode=CHAI_RENDER_MODE_RENDER_ALL)
 Render this object in OpenGL.
virtual void updateGlobalPositions (const bool a_frameOnly)
 Update the m_globalPos and m_globalRot properties of any members of this object (e.g. all triangles).
virtual void updateBoundaryBox ()
 Update the bounding box of this object, based on object-specific data (e.g. triangle positions).
virtual void scaleObject (const cVector3d &a_scaleFactors)
 Scale current object with scale factors along x, y and z.
virtual void computeLocalInteraction (const cVector3d &a_toolPos, const cVector3d &a_toolVel, const unsigned int a_IDN)
 Update the geometric relationship between the tool and the current object.
virtual cVector3d computeOtherInteractions (const cVector3d &a_toolPos, const cVector3d &a_toolVel, const unsigned int a_IDN, cInteractionRecorder &a_interactions, cInteractionSettings &a_interactionSettings)
 computes any other interaction with object.
virtual bool computeOtherCollisionDetection (cVector3d &a_segmentPointA, cVector3d &a_segmentPointB, cCollisionRecorder &a_recorder, cCollisionSettings &a_settings)
 Compute any collisions other than the default collision detector.

Protected Attributes

cGenericObject * m_parent
 Parent object.
vector< cGenericObject * > m_children
 My list of children.
bool m_ghostStatus
 Ghost status of current object.
cGenericType * m_externalParent
cGenericObject * m_superParent
cVector3d m_localPos
 The position of this object in my parent's reference frame.
cVector3d m_globalPos
 The position of this object in the world's reference frame.
cMatrix3d m_localRot
 The rotation matrix that rotates my reference frame into my parent's reference frame.
cMatrix3d m_globalRot
 The rotation matrix that rotates my reference frame into the world's reference frame.
cVector3d m_prevLocalPos
 The previous position of this of this object in the parent's reference frame.
cMatrix3d m_prevLocalRot
 The previous position of this of this object in the parent's reference frame.
cVector3d m_prevGlobalPos
 A previous position; exact interpretation up to user.
cMatrix3d m_prevGlobalRot
 A previous rotation; exact interpretation up to user.
cVector3d m_boundaryBoxMin
 Minimum position of boundary box.
cVector3d m_boundaryBoxMax
 Maximum position of boundary box.
double m_frameSize
 Size of graphical representation of frame (X-Y-Z).
double m_frameThicknessScale
 Pen thickness of graphical representation of frame (X-Y-Z).
bool m_show
 If true, this object is rendered.
bool m_hapticEnabled
 IF true, this object can be felt.
bool m_showFrame
 If true, this object's reference frame is rendered as a set of arrows.
bool m_showBox
 If true, this object's boundary box is displayed as a set of lines.
bool m_showTree
 If true, the skeleton of the scene graph is rendered at this node.
bool m_showCollisionTree
 If true, the collision tree is displayed (if available) at this node.
cColorf m_treeColor
 The color of the collision tree.
cColorf m_boundaryBoxColor
 The color of the bounding box.
bool m_useTextureMapping
 Should texture mapping be used?
bool m_useMaterialProperty
 Should material properties be used?
bool m_useVertexColors
 Should per-vertex colors be used?
int m_triangleMode
 The polygon rendering mode (GL_FILL or GL_LINE).
bool m_useTransparency
bool m_useMultipassTransparency
bool m_cullingEnabled
cGenericCollision * m_collisionDetector
 The collision detector used to test for contact with this object.
cMatrixGL m_frameGL
 OpenGL matrix describing my position and orientation transformation.

Detailed Description

This class is the root of basically every render-able object in CHAI. It defines a reference frame (position and rotation) and virtual methods for rendering, which are overloaded by useful subclasses.
.

This class also defines basic methods for maintaining a scene graph, and propagating rendering passes and reference frame changes through a hierarchy of cGenericObjects.

Besides subclassing, a useful way to extend cGenericObject is to store custom data in the m_tag and m_userData member fields, which are not used by CHAI.

The most important methods to look at here are probably the virtual methods, which are listed last in CGenericObject.h. These methods will be called on each cGenericObject as operations propagate through the scene graph.

Constructor & Destructor Documentation

cGenericObject::~cGenericObject (  )  [virtual]

Destructor of cGenericObject.

Destructor of cGenericObject. This function deletes all children starting from this point in the scene graph, so if you have objects that shouldn't be deleted, be sure to remove them from the scene graph before deleting their parents.

Member Function Documentation

void cGenericObject::addChild ( cGenericObject *  a_object  ) 

Add an object to my list of children.

Adds an object to the scene graph below this object.

Parameters:
a_object Object to be added to children list.

void cGenericObject::addEffect ( cGenericEffect *  a_effect  ) 

add an effect.

Adds a haptic effect to the current object

Parameters:
a_effect Effect to be added to effects list.

void cGenericObject::adjustCollisionSegment ( cVector3d &  a_segmentPointA,
cVector3d &  a_segmentPointAadjusted 
) [virtual]

Adjust collision segment for dynamic objects.

Adjust the given segment such that it tests for intersection of the ray with objects at their previous positions at the last haptic loop so that collision detection will work in a dynamic environment.

Parameters:
a_segmentPointA Start point of segment.
a_segmentPointAadjusted Same segment, adjusted to be in local space.

void cGenericObject::computeBoundaryBox ( const bool  a_includeChildren = true  ) 

Re-compute this object's bounding box, optionally forcing it to bound child objects.

Compute the bounding box of this object and (optionally) its children.

If parameter a_includeChildren is set to true then each object's bounding box covers its own volume and the volume of its children.

Note that regardless of this parameter's value, this operation propagates down the scene graph.

Parameters:
a_includeChildren If true, then children are included.

bool cGenericObject::computeCollisionDetection ( cVector3d &  a_segmentPointA,
cVector3d &  a_segmentPointB,
cCollisionRecorder &  a_recorder,
cCollisionSettings &  a_settings 
)

Compute collision detection using collision trees.

Determine whether the given segment intersects a triangle in this object (or any of its descendants). The segment is described by a start point a_segmentPointA and end point a_segmentPointB. Collision detection functions of all children of this object are called, which recursively call the collision detection functions for all of this object's descendants. If there is more than one collision, the one closest to a_segmentPointA is the one returned.

Parameters:
a_segmentPointA Start point of segment. Value may be changed if returned collision is with a moving object.
a_segmentPointB End point of segment.
a_recorder Stores all collision events.
a_settings Contains collision settings information.

Reimplemented in cWorld.

void cGenericObject::computeGlobalCurrentObjectOnly ( const bool  a_frameOnly = true  ) 

Compute the global position and rotation of current object only.

Compute globalPos and globalRot for this object only, by recursively climbing up the scene graph tree until the root is reached.

If a_frameOnly is set to false, additional global positions such as vertex positions are computed.

Parameters:
a_frameOnly If true then only the global frame is computed.

void cGenericObject::computeGlobalPositions ( const bool  a_frameOnly = true,
const cVector3d &  a_globalPos = cVector3d(0.0, 0.0, 0.0),
const cMatrix3d &  a_globalRot = cIdentity3d() 
)

Compute the global position and rotation of this object and its children.

Compute globalPos and globalRot given the localPos and localRot of this object and its parents. Optionally propagates to children.

If a_frameOnly is set to false, additional global positions such as vertex positions are computed (which can be time-consuming).

Call this method any time you've moved an object and will need to access to globalPos and globalRot in this object or its children. For performance reasons, these values are not kept up-to-date by default, since almost all operations use local positions and rotations.?

Parameters:
a_frameOnly If true then only the global frame is computed
a_globalPos Global position of my parent.
a_globalRot Global rotation matrix of my parent.

cVector3d cGenericObject::computeInteractions ( const cVector3d &  a_toolPos,
const cVector3d &  a_toolVel,
const unsigned int  a_IDN,
cInteractionRecorder &  a_interactions,
cInteractionSettings &  a_interactionSettings 
)

Descend through child objects to compute interactions for all cGenericEffect classes defined for each object.

Parameters:
a_toolPos Current position of tool.
a_toolVel Current position of tool.
a_IDN Identification number of the force algorithm.
a_interactions List of recorded interactions.
a_interactionSettings Settings of the interaction recorder.
Returns:
Return resulting interaction forces.

void cGenericObject::computeLocalInteraction ( const cVector3d &  a_toolPos,
const cVector3d &  a_toolVel,
const unsigned int  a_IDN 
) [protected, virtual]

Update the geometric relationship between the tool and the current object.

From the position of the tool, search for the nearest point located at the surface of the current object. Decide if the point is located inside or outside of the object.

Parameters:
a_toolPos Position of the tool.
a_toolVel Velocity of the tool.
a_IDN Identification number of the force algorithm.

Reimplemented in cShapeLine, cShapeSphere, and cShapeTorus.

bool cGenericObject::containsChild ( cGenericObject *  a_object,
bool  a_includeChildren = false 
)

Does this object have the specified object as a child?

Does this object have the specified object as a child?

Parameters:
a_object Object to search for.
a_includeChildren Should we also search this object's descendants?

void cGenericObject::deleteAllChildren (  ) 

Clear and delete all objects from my list of children.

Delete and clear all objects from my list of children.

bool cGenericObject::deleteChild ( cGenericObject *  a_object  ) 

Remove an object from my list of children and delete it.

Removes an object from my list of children, and deletes the child object from memory.

Parameters:
a_object Object to be removed from my list of children and deleted.
Returns:
Returns true if the specified object was found on my list of children.

void cGenericObject::deleteCollisionDetector ( const bool  a_affectChildren = false  ) 

Delete any existing collision detector and set the current cd to null (no collisions).

Delete any existing collision detector and set the current cd to null. It's fine for an object to have a null collision detector (that's the default for a new object, in fact), it just means that no collisions will be found.

Parameters:
a_affectChildren If true, all my children's cd's are also deleted.

void cGenericObject::enumerateChildren ( std::list< cGenericObject * > &  a_childList,
bool  a_includeCurrentObject = true 
)

Fill this list with all of my descendants.

Fill this list with all of my descendants. The current object is optionally included in this list. Does not clear the list before appending to it.

Parameters:
a_childList The list to write our enumerated results to.
a_includeCurrentObject Should I include myself on the list?

void cGenericObject::finalize ( const bool  a_affectChildren = true  )  [virtual]

This function tells children that you're not going to change their contents any more.

This call tells an object that you're not going to modify him any more. For example, a mesh-like object might optimize his vertex arrangement when he gets this call. Always optional; just for performance...

Parameters:
a_affectChildren If true, the operation propagates through the scene graph.

unsigned int cGenericObject::getNumDescendants ( bool  a_includeCurrentObject = false  ) 

Return my total number of descendants, optionally including this object.

Return my total number of descendants, optionally including this object.

Parameters:
a_includeCurrentObject Should I include myself in the count?
Returns:
Returns the number of descendants found.

void cGenericObject::onDisplayReset ( const bool  a_affectChildren = true  )  [virtual]

This function should get called when it's necessary to re-initialize the OpenGL context.

Users should call this function when it's necessary to re-initialize the OpenGL context; e.g. re-initialize textures and display lists. Subclasses should perform whatever re-initialization they need to do.

Note that this is not an event CHAI can easily detect, so it's up to the application-writer to call this function on the root of the scenegraph.

Parameters:
a_affectChildren If true, the operation propagates through the scene graph.

Reimplemented in cCamera, cMesh, and cWorld.

bool cGenericObject::removeChild ( cGenericObject *  a_object  ) 

Remove an object from my list of children, without deleting it.

Removes an object from my list of children, without deleting the child object from memory.

This method assigns the child object's parent point to null, so if you're moving someone around in your scene graph, make sure you call this function _before_ you add the child to another node in the scene graph.

Parameters:
a_object Object to be removed from my list of children.
Returns:
Returns true if the specified object was found on my list of children

void cGenericObject::render ( const int  a_renderMode = CHAI_RENDER_MODE_RENDER_ALL  )  [protected, virtual]

Render this object in OpenGL.

Render this object. Subclasses will generally override this method. This is called from renderSceneGraph, which subclasses generally do not need to override.

The a_renderMode parameter is used to allow multiple rendering passes, and takes one of the following values:

CHAI_RENDER_MODE_NON_TRANSPARENT_ONLY=0,
CHAI_RENDER_MODE_TRANSPARENT_BACK_ONLY,
CHAI_RENDER_MODE_TRANSPARENT_FRONT_ONLY,
CHAI_RENDER_MODE_RENDER_ALL

If you have multipass transparency disabled (see cCamera), your objects will only be rendered once per frame, with a_renderMode set to CHAI_RENDER_MODE_RENDER_ALL. This is the default, and unless you enable multipass transparency, you don't ever need to care about a_renderMode.

A word on OpenGL conventions:

CHAI does not re-initialize the OpenGL state at every rendering pass. The only OpenGL state variables that CHAI sets explicitly in a typical rendering pass are:

lighting is enabled (cWorld)
depth-testing is enabled (cWorld)
glColorMaterial is enabled and set to GL_AMBIENT_AND_DIFFUSE/GL_FRONT_AND_BACK (cWorld)
a perspective projection matrix is set up (cCamera)

This adherence to the defaults is nice because it lets an application change an important piece of state globally and not worry about it getting changed by CHAI objects.

It is expected that objects will "clean up after themselves" if they change any rendering state besides:

color (glColor)
material properties (glMaterial)
normals (glNormal)

For example, if my object changes the rendering color, I don't need to set it back before returning, but if my object turns on vertex buffering, I should turn it off before returning. Consequently if I care about the current color, I should set it up in my own render() function, because I shouldn't count on it being meaningful when my render() function is called.

Necessary exceptions to these conventions include:

cLight will change the lighting state for his assigned GL_LIGHT
cCamera sets up relevant transformation matrices

Parameters:
a_renderMode Rendering mode; see above

Reimplemented in cMesh, cShapeLine, cShapeSphere, cShapeTorus, cWorld, cGeneric3dofPointer, cGenericTool, cLabel, cGELMesh, and cODEGenericBody.

void cGenericObject::renderSceneGraph ( const int  a_renderMode = CHAI_RENDER_MODE_RENDER_ALL  )  [virtual]

Render the entire scene graph, starting from this object.

Render the scene graph starting at this object. This method is called for each object and optionally renders the object itself, its reference frame and the collision and/or scenegraph trees.

The object itself is rendered by calling render(), which should be defined for each subclass that has a graphical representation. renderSceneGraph does not generally need to be over-ridden in subclasses.

The a_renderMode parameter is used to allow multiple rendering passes, and takes one of the following values:

CHAI_RENDER_MODE_NON_TRANSPARENT_ONLY=0,
CHAI_RENDER_MODE_TRANSPARENT_BACK_ONLY,
CHAI_RENDER_MODE_TRANSPARENT_FRONT_ONLY,
CHAI_RENDER_MODE_RENDER_ALL

If you have multipass transparency disabled (see cCamera), your objects will only be rendered once per frame, with a_renderMode set to CHAI_RENDER_MODE_RENDER_ALL. This is the default, and unless you enable multipass transparency, you don't ever need to care about a_renderMode.

Parameters:
a_renderMode Rendering mode.

void cGenericObject::rotate ( const cVector3d &  a_axis,
const double  a_angle 
)

Rotate this object around axis a_axis by angle a_angle (radians).

Rotate this object around axis a_axis by angle a_angle (radians). a_axis is not normalized, so unless you know what you're doing, normalize your axis before supplying it to this function.

Parameters:
a_axis Rotation axis.
a_angle Rotation angle in radians.

void cGenericObject::rotate ( const cMatrix3d &  a_rotation  ) 

Rotate this object by multiplying with a specified rotation matrix.

Rotate this object by multiplying with a specified rotation matrix.

Parameters:
a_rotation Rotation matrix.

void cGenericObject::scale ( const cVector3d &  a_scaleFactors,
const bool  a_includeChildren = true 
)

Non-uniform scale.

Non-uniform scale, optionally include children. Not necessarily implemented in all subclasses. Does nothing at the cGenericObject level; subclasses should scale themselves, then call the superclass method.

Parameters:
a_scaleFactors Possibly non-uniform scale factors.
a_includeChildren If true, this message is passed to children.

void cGenericObject::scale ( const double &  a_scaleFactor,
const bool  a_includeChildren = true 
)

Scale this object by a_scaleFactor (uniform scale).

Uniform scale, optionally include children. Not necessarily implemented in all subclasses. Does nothing at the cGenericObject level. Subclasses should scale themselves, then call the superclass method.

Parameters:
a_scaleFactor Scale factor.
a_includeChildren If true, this message is passed to children.

void cGenericObject::setAsGhost ( bool  a_ghostStatus  ) 

Makes this object a ghost node.

It can be sometimes useful to add an object twice in a scenegraph to create for instance a reflexion of a model over a ground. In these cases there only one model for which all the interactions should be computed. The second one is only there for display purposes. By enabling the ghost status, we disable all collision detection, force interaction further down the scene graph. An example of this feature can be found in the example "ODE-cube".

void cGenericObject::setBoxColor ( const cColorf &  a_boxColor,
const bool  a_affectChildren = false 
)

Set the color of boundary box for this object, optionally propagating the change to children.

Set the color of the graphic representation of the boundary boundary box of this object.

Parameters:
a_boxColor Color of boundary box.
a_affectChildren If true all children are updated.

void cGenericObject::setCollisionDetectorProperties ( unsigned int  a_displayDepth,
cColorf &  a_color,
const bool  a_affectChildren = false 
)

Set collision rendering properties.

Set the rendering properties for the graphic representation of collision detection tree at this node.

If a_affectChildren is set to true then all children are updated with the new values.

Parameters:
a_color Color used to render collision detector.
a_displayDepth Indicated which depth of collision tree needs to be displayed (see cGenericCollision).
a_affectChildren If true, all children are updated.

void cGenericObject::setExternalParent ( cGenericType *  a_externalParent,
const bool  a_affectChildren = false 
)

Sets a pointer to an external parent of the current object. Optionally propagating the change to children.

Sets a pointer to an external parent of the current object. Optionally propagating the change to children. A pointer to an external parent located outside of the scenegraph. This parameter can typically be used if you want to attach an generic object to some other object outside of CHAI3D of to an external representation such as a dynamics engine model. See the ODE examples to understand how a generic object can be attached to an ODE object.

Parameters:
a_externalParent External parent.
a_affectChildren If true, this message is passed to children.

bool cGenericObject::setFrameSize ( const double  a_size = 1.0,
const double  a_thickness = 1.0,
const bool  a_affectChildren = false 
)

Set the size of the rendered reference frame, optionally propagating the change to children.

Set the display size of the arrows representing my reference frame. The size corresponds to the length of each displayed axis (X-Y-Z).

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_size Length of graphical representation of frame.
a_thickness Thickness of graphical representation of frame.
a_affectChildren If true all children are updated.

void cGenericObject::setFriction ( double  a_staticFriction,
double  a_dynamicFriction,
const bool  a_affectChildren = 0 
)

Set the static and dynamic friction for this mesh, possibly recursively affecting children.

Set the static and dynamic friction for this mesh, possibly recursively affecting children.

Parameters:
a_staticFriction The static friction to apply to this object.
a_dynamicFriction The dynamic friction to apply to this object.
a_affectChildren If true, then children are also modified.

void cGenericObject::setHapticEnabled ( const bool  a_hapticEnabled,
const bool  a_affectChildren = false 
)

Allow this object to be felt (when visible), optionally propagating the change to children.

Allow or disallow the object to be felt (when visible).

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_hapticEnabled If true object can be felt when visible.
a_affectChildren If true all children are updated.

void cGenericObject::setMaterial ( cMaterial &  a_mat,
const bool  a_affectChildren = false,
const bool  a_applyPhysicalParmetersOnly = false 
)

Set the material for this mesh, and optionally pass it on to my children.

Set the current material for this mesh, possibly recursively affecting children. If parameter a_applyPhysicalParmetersOnly is set to true then only the physical properties are modified. This is extremely useful if the user loads a 3d object file into a mesh and then applies some haptic properties which are also defined in the cMaterial class.

Note that this does not affect whether material rendering is enabled; it sets the maetrial that will be rendered _if_ material rendering is enabled. Call useMaterial to enable / disable material rendering.

Parameters:
a_mat The material to apply to this object
a_affectChildren If true, then children are also modified.
a_applyPhysicalParmetersOnly If true, then only physical properties are applied

void cGenericObject::setName ( const char *  a_name,
const bool  a_affectChildren = 0 
) [virtual]

Set the name for this object and - optionally - for my children.

Set the name for this object and - optionally - for my children.

Parameters:
a_name The name we'll assign to this object.
a_affectChildren If true, the operation propagates through the scene graph.

void cGenericObject::setShowBox ( const bool  a_showBox,
const bool  a_affectChildren = false 
)

Show or hide the boundary box for this object, optionally propagating the change to children.

Show or hide the graphic representation of the boundary box of this object.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_showBox If true, boundary box is displayed.
a_affectChildren If true all children are updated.

void cGenericObject::setShowCollisionTree ( const bool  a_showCollisionTree,
const bool  a_affectChildren = false 
)

Show or hide the collision tree for this object, optionally propagating the change to children.

Show or hide the graphic representation of the collision tree at this node.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_showCollisionTree If true, small normals are rendered graphicaly.
a_affectChildren If true all children are updated.

void cGenericObject::setShowEnabled ( const bool  a_show,
const bool  a_affectChildren = false 
)

Show or hide this object, optionally propagating the change to children.

Show or hide this object.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_show If true object shape is visible.
a_affectChildren If true all children are updated.

void cGenericObject::setShowFrame ( const bool  a_showFrame,
const bool  a_affectChildren = false 
)

Show or hide the reference frame arrows for this object, optionally propagating the change to children.

Show or hide the set of arrows that represent this object's reference frame.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_showFrame If true then frame is displayed.
a_affectChildren If true all children are updated.

void cGenericObject::setShowTree ( const bool  a_showTree,
const bool  a_affectChildren = false 
)

Show or hide the child/parent tree, optionally propagating the change to children.

Show or hide the graphic representation of the scene graph at this node.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_showTree If true then tree is displayed.
a_affectChildren If true all children are updated.

void cGenericObject::setStiffness ( double  a_stiffness,
const bool  a_affectChildren = 0 
)

Set the haptic stiffness, possibly recursively affecting children.

Set the haptic stiffness for this mesh, possibly recursively affecting children.

Parameters:
a_stiffness The stiffness to apply to this object.
a_affectChildren If true, then children are also modified.

void cGenericObject::setSuperParent ( cGenericObject *  a_superParent,
const bool  a_affectChildren = false 
)

Sets the super parent of the current object. Optionally propagating the change to children.

Sets the super parent of the current object. Optionally propagating the change to children. A super parent points to another object generally located higher up in the scene graph. When a mesh is created, the super parent of its children will generally point towards the root of the mesh. This parameter is automatically set by the 3D object file loader.

Parameters:
a_superParent Super parent.
a_affectChildren If true, this message is passed to children.

void cGenericObject::setTag ( const int  a_tag,
const bool  a_affectChildren = 0 
) [virtual]

Set the tag for this object and - optionally - for my children.

Set the tag for this object and - optionally - for my children.

Parameters:
a_tag The tag we'll assign to this object.
a_affectChildren If true, the operation propagates through the scene graph.

void cGenericObject::setTexture ( cTexture2D *  a_texture,
const bool  a_affectChildren = 0 
)

Set my texture, possibly recursively affecting children.

Set the current texture for this mesh, possibly recursively affecting children.

Note that this does not affect whether texturing is enabled; it sets the texture that will be rendered _if_ texturing is enabled. Call useTexture to enable / disable texturing.

Parameters:
a_texture The texture to apply to this object.
a_affectChildren If true, then children are also modified.

void cGenericObject::setTransparencyLevel ( const float  a_level,
const bool  a_applyToTextures = false,
const bool  a_affectChildren = true 
) [virtual]

Set the alpha value at each vertex and in all of my material colors.

Set the alpha value at each vertex, in all of my material colors, optionally propagating the operation to my children.

Using the 'apply to textures' option causes the actual texture alpha values to be over-written in my texture, if it exists.

[Editor's note: the 'apply to textures' option is not currently enabled, since (a) it's a silly way to control transparency and (b) not all textures have an alpha channel.]

Parameters:
a_level Level of transparency ranging from 0.0 to 1.0.
a_applyToTextures If true, then apply changes to texture.
a_affectChildren If true, then children also modified.

Reimplemented in cMesh.

void cGenericObject::setTransparencyRenderMode ( const bool  a_useMultipassTransparency,
const bool  a_affectChildren = true 
)

Specify whether this mesh should use multipass transparency (see cCamera).

Specify whether transparent rendering should use two passes (looks better) or one pass (runs faster). See cCamera for more information about multipass transparency.

Parameters:
a_useMultipassTransparency If true, this mesh uses multipass rendering.
a_affectChildren If true, then children are also modified.

void cGenericObject::setTreeColor ( const cColorf &  a_treeColor,
const bool  a_affectChildren = false 
)

Set the tree color, optionally propagating the change to children.

Set the color of the graphic representation of the scene graph at this node.

If a_affectChildren is set to true then all children are updated with the new value.

Parameters:
a_treeColor Color of tree.
a_affectChildren If true all children are updated.

void cGenericObject::setUseCulling ( const bool  a_useCulling,
const bool  a_affectChildren = true 
)

Enable or disabling face-culling, optionally propagating the operation to my children.

Enables or disables backface culling (rendering in GL is much faster with culling on).

Parameters:
a_useCulling If true, backfaces are culled.
a_affectChildren If true, this operation is propagated to my children.

void cGenericObject::setUseMaterial ( const bool  a_useMaterial,
const bool  a_affectChildren = true 
)

Enable or disable the use of material properties, optionally propagating the operation to my children.

Enable or disable the use of material properties.

Parameters:
a_useMaterial If true, then material properties are used for rendering.
a_affectChildren If true, then children are also modified.

void cGenericObject::setUserData ( void *  a_data,
const bool  a_affectChildren = 0 
) [virtual]

Set the m_userData pointer for this object and - optionally - for my children.

Set the m_userData pointer for this object and - optionally - for my children.

Parameters:
a_data The pointer to which we will set m_userData
a_affectChildren If true, the operation propagates. through the scene graph.

void cGenericObject::setUseTexture ( const bool  a_useTexture,
const bool  a_affectChildren = true 
)

Enable or disable the use of texture-mapping, optionally propagating the operation to my children.

Enable or disable texture-mapping, possibly recursively affecting children.

Parameters:
a_useTexture If true, then texture mapping is used.
a_affectChildren If true, then children are also modified.

void cGenericObject::setUseTransparency ( const bool  a_useTransparency,
const bool  a_affectChildren = true 
)

Enable or disable transparency (also see setTransparencyRenderMode)... turns the depth mask _off_!

Specify whether transparency should be enabled. Note that this does not affect the transparency _mode_, which controls the use of simple transparency vs. multipass transparency.

Parameters:
a_useTransparency If true, transparency is enabled.
a_affectChildren If true, then children are also modified.

void cGenericObject::setUseVertexColors ( const bool  a_useColors,
const bool  a_affectChildren = true 
)

Enable or disable the use of per-vertex colors, optionally propagating the operation to my children.

Enable or disable the use of per-vertex color information of when rendering the mesh.

Parameters:
a_useColors If true, then vertex color information is applied.
a_affectChildren If true, then children are also modified.

void cGenericObject::setWireMode ( const bool  a_showWireMode,
const bool  a_affectChildren = true 
)

Enable or disable wireframe rendering, optionally propagating the operation to my children.

Enable or disable wireframe rendering, optionally propagating the operation to my children.

Parameters:
a_showWireMode If true, wireframe mode is used.
a_affectChildren If true, then children are also updated.

void cGenericObject::translate ( const double  a_x,
const double  a_y,
const double  a_z 
)

Translate this object by a specified offset.

Translate an object by a specified offset.

Parameters:
a_x Translation component X.
a_y Translation component Y.
a_z Translation component Z.

void cGenericObject::translate ( const cVector3d &  a_translation  ) 

Translate this object by a specified offset.

Translate this object by a specified offset.

Parameters:
a_translation Translation offset.

void cGenericObject::unfinalize ( const bool  a_affectChildren = true  )  [virtual]

This function tells objects that you may modify their contents.

This call tells an object that you may modify his contents. See finalize() for more information.

Parameters:
a_affectChildren If true, the operation propagates through the scene graph.

Member Data Documentation

bool cGenericObject::m_cullingEnabled [protected]

Should culling be used when rendering triangles?

Note that this option only applies when multipass transparency is disabled or during the non-transparent rendering pass when multipass transparency is enabled...

Also note that currently only back-faces are culled during non-transparent rendering; you can't cull front-faces.

cGenericType* cGenericObject::m_externalParent [protected]

A pointer to an external parent located outside of the scenegraph. This parameter can typically be used if you want to attach an generic object to some other object outside of CHAI3D of to an external representation such as a dynamics engine model. See the ODE examples to understand how a generic object can be attached to an ODE object.

cGenericObject* cGenericObject::m_superParent [protected]

A super parent points to another object generally located higher up in the scene graph. When a mesh is created, the super parent of its children will generally point towards the root of the mesh. This parameter is automatically set by the 3D object file loader.

bool cGenericObject::m_useMultipassTransparency [protected]

If true, multipass transparency is permitted for this mesh... this means that if the rendering camera is using multipass transparency, this mesh will render back and front faces separately.

Note that m_useTransparency also has to be true for this variable to be meaningful.

Reimplemented in cCamera.

bool cGenericObject::m_useTransparency [protected]

If true, transparency is enabled... this turns alpha on when the mesh is rendered, and - if multipass transparency is enabled in the rendering camera - uses the camera's multiple rendering passes to approximate back-to-front sorting via culling.

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

CHAI3D 2.0.0 documentation
Please address any questions to support@chai3d.org
(C) 2003-2009 - CHAI 3D
All Rights Reserved.