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();
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 );
addRef()
on it somewhere.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
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. 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
removeRef
on a pointer to a NVSG object without having called addRef
on that pointer beforehand!