Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

NVSG Objects

The term 'NVSG objects' covers all class objects that inherit from nvsg::Object. Through this relationship all NVSG objects behave the same way regarding general object management.
This page gives a brief introduction on how to use NVSG objects in general. It also gives a short description of the major concepts used for NVSG objects. It contains the following sections:

See also:
How to Derive an NVSG Object

Optimized Memory Management for NVSG Objects

All NVSG objects make use of a special allocator through the nvutil::IAllocator interface. This allocator is highly optimized for the needs of NVSG objects. NVSG objects can live on heap only. Any attempts to create an arbitrary NVSG object on stack will be rejected by the compiler. See Creating NVSG Objects for more details on creating NVSG objects. The reference counting and data sharing concepts require this limitation. See Object Level Reference Counting and Sharing Data Between Kindred NVSG Objects for more details on these topics.

Object Level Reference Counting

All NVSG objects - for example nvsg::Drawable, nvsg::Node, nvsg::StateAttribute, etc. - inherit from nvsg::Object. As nvsg::Object inherits from nvutil::RCObject, all NVSG objects are reference counted. This is particularly necessary if an object is referenced multiple times within a certain scene. For example, a car tire might be referenced four times for a car model.

The nvutil::RCObject class provides the necessary interface for proper reference counting on object level. See Using NVSG Objects for more details on how to use the nvutil::RCObject interface.

Creating NVSG Objects

NVSG objects can only be created by class-specific static creation functions. Any attempts to create a NVSG object on stack will be rejected by the compiler. Therefore, the only way to instantiate an NVSG object is to create it on heap:

  using namespace nvsg;
  // Instantiate a GeoNode
  const GeoNode * pGeoNode = GeoNode::create();

Note:
The reference count for NVSG objects is initially zero!

Using NVSG Objects

After creating and before using an NVSG object, the object's reference count should be incremented. This ensures the pointer to the object is valid until the object's reference count is decremented again:

  using namespace nvsg;
  // Instantiating a GeoNode
  const GeoNode * pGeoNode = GeoNode::create();
  pGeoNode->addRef(); 
  // ... use the GeoNode instance
  
  // ... and after usage
  pGeoNode->removeRef();

Modifying NVSG Objects

NVSG Objects are created as pointers to constants and can't be modified directly. Any modification to NVSG Objects must be encased by calls to beginEdit() and endEdit() to ensure save access in multithreaded environments:

const GeoNode * pGeoNode;               // a GeoNode after creation
GeoNode * pNC = beginEdit( pGeoNode );  // get a pointer to modify the GeoNode
//  ... modify the GeoNode instance

//  ... and after modifying
endEdit( pNC );

Note:
Before modifying an NVSG Object be sure that you have called addRef() on it somewhere.

Sharing Data Between Kindred NVSG Objects

Beneath the reference counting at the object level, NVSG objects are capable of sharing their data between kindred objects. Unlike reference counting at the object level, this capability is handled automatically.

An arbitrary NVSG object shares its data with a kindred object if

  // Sharing data between GeoNodes
  using namespace nvsg
  // Instantiate a GeoNode
  const GeoNode * pGeoNode = GeoNode::create();
  // Instantiating a copy of the GeoNode, pGeoNode is pointing to
  const GeoNode * pAnotherGeoNode = GeoNode::create(*pGeoNode);
  // The objects pointed to by pGeoNode and pAnotherGeoNode, share the same data now
  // ...
  // Instantiate a third Geo node
  const GeoNode * pAThirdGeoNode = GeoNode::create();
  // re-assign it
  GeoNode * pNC = beginEdit( pAThirdGeoNode );
  *pNC = *pGeoNode;
  endEdit( pNC );
  // Now the object pointed to by pAThirdGeoNode shares its data with the objects pointed to
  // by pGeoNode and pAnotherGeoNode

Note:
If an object shares its data with other objects, it will automatically split off its own copy of that data once the object initiates a modifying access on that data.

Deleting NVSG Objects

It is prohibited by the compiler to explicitly call delete on a pointer to an arbitrary NVSG object. After a call to removeRef an NVSG object will be deleted automatically after its reference count reaches zero.
Remarks:
After creating an NVSG object, its initial reference count is zero. The reason for this is that, in most cases, client code instantiates and initializes an NVSG object but no longer directly uses the object's interface. Instead, it hands over the object to subsequent layers. In doing so, the client code does not need to care about the object's lifetime but the subsequent layer needs the following:
  using namespace nvsg;
  // instantiate a default Transform
  const Transform * pTrafo = Transform::create();
  // instantiating a GeoNode
  const GeoNode * pGeoNode = GeoNode::create();
  // ... initialize the GeoNode here
  // ...
  // hand over the GeoNode to the Transform as child
  Transform * pNC = beginEdit( pTrafo );
  pNC->addChild(pGeoNode);
  endEdit( pNC );
  // ... don't care about the GeoNode's lifetime, the Transform does  
Note:
Because the reference count of a NVSG object initially is zero, it is an error to call removeRef on a pointer to a NVSG object without having called addRef on that pointer beforehand!
Back to:

Generated on Tue Mar 1 13:20:21 2005 for NVSGSDK by NVIDIA