NAME
SoBase -
The SoBase class is the top-level superclass for a number of class-
hierarchies.
SoBase provides the basic interfaces and methods for doing reference
counting, type identification and import/export. All classes in Coin
which uses these mechanisms are descendent from this class.
SYNOPSIS
#include <Inventor/misc/SoBase.h>
Inherited by SoFieldContainer, and SoPath.
Public Member Functions
void ref (void) const
void unref (void) const
void unrefNoDelete (void) const
int32_t getRefCount (void) const
void touch (void)
virtual SoType getTypeId (void) const =0
SbBool isOfType (SoType type) const
virtual SbName getName (void) const
virtual void setName (const SbName &newname)
virtual void startNotify (void)
virtual void notify (SoNotList *l)
void addAuditor (void *const auditor, const SoNotRec::Type type)
void removeAuditor (void *const auditor, const SoNotRec::Type type)
const SoAuditorList & getAuditors (void) const
virtual void addWriteReference (SoOutput *out, SbBool isfromfield=0)
SbBool shouldWrite (void)
void assertAlive (void) const
Static Public Member Functions
static void initClass (void)
static SoType getClassTypeId (void)
static void addName (SoBase *const base, const char *const name)
static void removeName (SoBase *const base, const char *const name)
static void incrementCurrentWriteCounter (void)
static void decrementCurrentWriteCounter (void)
static SoBase * getNamedBase (const SbName &name, SoType type)
static int getNamedBases (const SbName &name, SoBaseList &baselist,
SoType type)
static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype)
static void setInstancePrefix (const SbString &c)
static void setTraceRefs (SbBool trace)
static SbBool getTraceRefs (void)
static SbBool connectRoute (SoInput *input, const SbName &fromnodename,
const SbName &fromfieldname, const SbName &tonodename, const SbName
&tofieldname)
static SbBool readRoute (SoInput *input)
Protected Types
enum BaseFlags { IS_ENGINE = 0x01, IS_GROUP = 0x02 }
Protected Member Functions
SoBase (void)
virtual ~SoBase ()
virtual void destroy (void)
SbBool hasMultipleWriteRefs (void) const
SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine)
const
void writeFooter (SoOutput *out) const
virtual const char * getFileFormatName (void) const
virtual SbBool readInstance (SoInput *input, unsigned short flags)=0
Static Protected Member Functions
static uint32_t getCurrentWriteCounter (void)
static void staticDataLock (void)
static void staticDataUnlock (void)
Detailed Description
The SoBase class is the top-level superclass for a number of class-
hierarchies.
SoBase provides the basic interfaces and methods for doing reference
counting, type identification and import/export. All classes in Coin
which uses these mechanisms are descendent from this class.
One important issue with SoBase-derived classes is that they should not
be statically allocated, neither in static module memory nor on
function’s stack-frames. SoBase-derived classes must always be
allocated dynamically from the memory heap with the new operator.
This is so because SoBase-derived instances are reference counted, and
will self-destruct on the approriate time. For this to work, they must
be explicitly allocated in heap-memory. See the class documentation of
SoNode for more information.
Member Enumeration Documentation
enum SoBase::BaseFlags [protected] This API member is considered internal
to the library, as it is not likely to be of interest to the
application programmer.
Constructor & Destructor Documentation
SoBase::SoBase (void) [protected] Constructor. The initial reference count
will be set to zero.
SoBase::~SoBase () [protected, virtual] Destructor. There should not be any
normal circumstance where you need to explicitly delete an object
derived from the SoBase class, as the reference counting should take
care of deallocating unused objects.
See also:
unref(), unrefNoDelete()
Member Function Documentation
void SoBase::initClass (void) [static] Sets up initialization for data
common to all instances of this class, like submitting necessary
information to the Coin type system.
Reimplemented in SoPath, SoVRMLAnchor, SoVRMLAppearance,
SoVRMLAudioClip, SoVRMLBackground, SoVRMLBillboard, SoVRMLBox,
SoVRMLCollision, SoVRMLColor, SoVRMLColorInterpolator, SoVRMLCone,
SoVRMLCoordinate, SoVRMLCoordinateInterpolator, SoVRMLCylinder,
SoVRMLCylinderSensor, SoVRMLDirectionalLight, SoVRMLDragSensor,
SoVRMLElevationGrid, SoVRMLExtrusion, SoVRMLFog, SoVRMLFontStyle,
SoVRMLGeometry, SoVRMLGroup, SoVRMLImageTexture, SoVRMLIndexedFaceSet,
SoVRMLIndexedLine, SoVRMLIndexedLineSet, SoVRMLIndexedShape,
SoVRMLInline, SoVRMLInterpolator, SoVRMLLOD, SoVRMLLight,
SoVRMLMaterial, SoVRMLMovieTexture, SoVRMLNavigationInfo, SoVRMLNormal,
SoVRMLNormalInterpolator, SoVRMLOrientationInterpolator, SoVRMLParent,
SoVRMLPixelTexture, SoVRMLPlaneSensor, SoVRMLPointLight,
SoVRMLPointSet, SoVRMLPositionInterpolator, SoVRMLProximitySensor,
SoVRMLScalarInterpolator, SoVRMLScript, SoVRMLSensor, SoVRMLShape,
SoVRMLSound, SoVRMLSphere, SoVRMLSphereSensor, SoVRMLSpotLight,
SoVRMLSwitch, SoVRMLText, SoVRMLTexture, SoVRMLTextureCoordinate,
SoVRMLTextureTransform, SoVRMLTimeSensor, SoVRMLTouchSensor,
SoVRMLTransform, SoVRMLVertexLine, SoVRMLVertexPoint,
SoVRMLVertexShape, SoVRMLViewpoint, SoVRMLVisibilitySensor,
SoVRMLWorldInfo, SoShadowCulling, SoShadowGroup, SoShadowSpotLight,
SoShadowStyle, SoForeignFileKit, SoSTLFileKit, SoProfilerStats,
SoCenterballDragger, SoDirectionalLightDragger, SoDragPointDragger,
SoDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger,
SoRotateCylindricalDragger, SoRotateDiscDragger,
SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger,
SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger,
SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger,
SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger,
SoTranslate2Dragger, SoBoolOperation, SoCalculator, SoComposeMatrix,
SoComposeRotation, SoComposeRotationFromTo, SoComposeVec2f,
SoComposeVec3f, SoComposeVec4f, SoComputeBoundingBox, SoConcatenate,
SoCounter, SoDecomposeMatrix, SoDecomposeRotation, SoDecomposeVec2f,
SoDecomposeVec3f, SoDecomposeVec4f, SoElapsedTime, SoEngine,
SoFieldConverter, SoGate, SoHeightMapToNormalMap, SoInterpolate,
SoInterpolateFloat, SoInterpolateRotation, SoInterpolateVec2f,
SoInterpolateVec3f, SoInterpolateVec4f, SoNodeEngine, SoOnOff,
SoOneShot, SoSelectOne, SoTexture2Convert, SoTimeCounter,
SoTransformVec3f, SoTriggerAny, SoFieldContainer, SoCenterballManip,
SoClipPlaneManip, SoDirectionalLightManip, SoHandleBoxManip,
SoJackManip, SoPointLightManip, SoSpotLightManip, SoTabBoxManip,
SoTrackballManip, SoTransformBoxManip, SoTransformManip,
SoTransformerManip, SoProto, SoProtoInstance, SoAppearanceKit,
SoBaseKit, SoCameraKit, SoInteractionKit, SoLightKit,
SoNodeKitListPart, SoSceneKit, SoSeparatorKit, SoShapeKit,
SoWrapperKit, SoAnnotation, SoAntiSquish, SoArray, SoAsciiText,
SoBaseColor, SoBlinker, SoBumpMap, SoBumpMapCoordinate,
SoBumpMapTransform, SoCacheHint, SoCallback, SoCamera, SoClipPlane,
SoColorIndex, SoComplexity, SoCone, SoCoordinate3, SoCoordinate4,
SoCube, SoCylinder, SoDepthBuffer, SoDirectionalLight, SoDrawStyle,
SoEnvironment, SoEventCallback, SoExtSelection, SoFaceSet, SoFile,
SoFont, SoFontStyle, SoFragmentShader, SoFrustumCamera,
SoGeoCoordinate, SoGeoLocation, SoGeoOrigin, SoGeoSeparator,
SoGeometryShader, SoGroup, SoImage, SoIndexedFaceSet, SoIndexedLineSet,
SoIndexedMarkerSet, SoIndexedNurbsCurve, SoIndexedNurbsSurface,
SoIndexedPointSet, SoIndexedShape, SoIndexedTriangleStripSet, SoInfo,
SoLOD, SoLabel, SoLevelOfDetail, SoLight, SoLightModel, SoLineSet,
SoLinearProfile, SoListener, SoLocateHighlight, SoMarkerSet,
SoMaterial, SoMaterialBinding, SoMatrixTransform, SoMultipleCopy,
SoNode, SoNonIndexedShape, SoNormal, SoNormalBinding, SoNurbsCurve,
SoNurbsProfile, SoNurbsSurface, SoOrthographicCamera, SoPackedColor,
SoPathSwitch, SoPendulum, SoPerspectiveCamera, SoPickStyle,
SoPointLight, SoPointSet, SoPolygonOffset, SoProfile,
SoProfileCoordinate2, SoProfileCoordinate3, SoQuadMesh,
SoResetTransform, SoRotation, SoRotationXYZ, SoRotor, SoScale,
SoSceneTexture2, SoSceneTextureCubeMap, SoSelection, SoSeparator,
SoShaderObject, SoShaderParameter, SoShaderProgram, SoShape,
SoShapeHints, SoShuttle, SoSphere, SoSpotLight, SoSurroundScale,
SoSwitch, SoText2, SoText3, SoTexture2, SoTexture2Transform,
SoTexture3, SoTexture3Transform, SoTextureCombine,
SoTextureCoordinate2, SoTextureCoordinate3, SoTextureCoordinateBinding,
SoTextureCoordinateCube, SoTextureCoordinateCylinder,
SoTextureCoordinateDefault, SoTextureCoordinateEnvironment,
SoTextureCoordinateFunction, SoTextureCoordinateNormalMap,
SoTextureCoordinateObject, SoTextureCoordinatePlane,
SoTextureCoordinateReflectionMap, SoTextureCoordinateSphere,
SoTextureCubeMap, SoTextureMatrixTransform, SoTextureScalePolicy,
SoTextureUnit, SoTransform, SoTransformSeparator, SoTransformation,
SoTranslation, SoTransparencyType, SoTriangleStripSet, SoUnits,
SoVertexAttribute, SoVertexAttributeBinding, SoVertexProperty,
SoVertexShader, SoVertexShape, SoWWWAnchor, and SoWWWInline.
void SoBase::ref (void) const Increase the reference count of the object.
This might be necessary to do explicitly from user code for certain
situations (chiefly to avoid premature deletion), but is usually called
from other instances within the Coin library when objects are made
dependent on each other.
See the class documentation of SoNode for more extensive information
about reference counting.
See also:
unref(), unrefNoDelete()
void SoBase::unref (void) const Decrease the reference count of an object.
If the reference count reaches zero, the object will delete itself. Be
careful when explicitly calling this method, beware that you usually
need to match user level calls to ref() with calls to either unref() or
unrefNoDelete() to avoid memory leaks.
See also:
ref(), unrefNoDelete()
void SoBase::unrefNoDelete (void) const Decrease reference count, but do
not delete ourself if the count reaches zero.
See also:
unref()
int32_t SoBase::getRefCount (void) const Returns number of objects
referring to this object.
void SoBase::touch (void) Force an update, in the sense that all objects
connected to this object as an auditor will have to re-check the values
of their inter-dependent data.
This is often used as an effective way of manually triggering a redraw
by application programmers.
SoType SoBase::getTypeId (void) const [pure virtual] Returns the type
identification of an object derived from a class inheriting SoBase.
This is used for run-time type checking and ’downward’ casting.
Usage example:
void foo(SoNode * node)
{
if (node->getTypeId() == SoFile::getClassTypeId()) {
SoFile * filenode = (SoFile *)node; // safe downward cast, knows the type
}
}
For application programmers wanting to extend the library with new
nodes, engines, nodekits, draggers or others: this method needs to be
overridden in all subclasses. This is typically done as part of setting
up the full type system for extension classes, which is usually
accomplished by using the pre-defined macros available through for
instance Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and
SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h
(for engine classes) and so on.
For more information on writing Coin extensions, see the class
documentation of the toplevel superclasses for the various class
groups.
Implemented in SoPath, SoVRMLAnchor, SoVRMLScript, SoProto, and
SoVertexAttribute.
SbBool SoBase::isOfType (SoType type) const Returns TRUE if the type of
this object is either of the same type or inherited from type.
This is used for run-time type checking and ’downward’ casting.
Usage example:
void foo(SoNode * node)
{
if (node->isOfType(SoGroup::getClassTypeId())) {
SoGroup * group = (SoGroup *)node; // safe downward cast, knows the type
}
}
SoType SoBase::getClassTypeId (void) [static] This static method returns
the SoType object associated with objects of this class.
Reimplemented in SoPath, SoVRMLAnchor, SoVRMLScript, SoEngine,
SoNodeEngine, SoFieldContainer, SoProto, SoNode, and SoVertexAttribute.
SbName SoBase::getName (void) const [virtual] Returns name of object. If no
name has been given to this object, the returned SbName will contain
the empty string.
void SoBase::setName (const SbName & newname) [virtual] Set the name of
this object.
Some characters are invalid to use as parts of names for SoBase derived
objects, as object names needs to be consistent with the syntax of
Inventor and VRML files upon file export / import operations (so one
must for instance avoid using special token characters).
Invalid characters will be automatically replaced by underscore
characters. If the name starts with an invalid character, the new name
will be preceded by an underscore character.
For the exact definitions of what constitutes legal and illegal
characters for SoBase names, see the SbName functions listed below.
See also:
getName(), SbName::isBaseNameStartChar(), SbName::isBaseNameChar()
void SoBase::addName (SoBase *const b, const char *const name) [static]
Adds a name<->object mapping to the global dictionary.
void SoBase::removeName (SoBase *const base, const char *const name)
[static] Removes a name<->object mapping from the global dictionary.
void SoBase::startNotify (void) [virtual] This is the method which starts
the notification sequence after changes.
At the end of a notification sequence, all ’immediate’ sensors (i.e.
sensors set up with a zero priority) are triggered.
Reimplemented in SoNode.
void SoBase::notify (SoNotList * l) [virtual] Notifies all auditors for
this instance when changes are made.
Reimplemented in SoVRMLAppearance, SoVRMLBillboard, SoVRMLCollision,
SoVRMLElevationGrid, SoVRMLExtrusion, SoVRMLGeometry, SoVRMLGroup,
SoVRMLIndexedLine, SoVRMLIndexedLineSet, SoVRMLIndexedShape, SoVRMLLOD,
SoVRMLParent, SoVRMLPixelTexture, SoVRMLProximitySensor, SoVRMLScript,
SoVRMLShape, SoVRMLSwitch, SoVRMLText, SoVRMLTimeSensor,
SoVRMLTouchSensor, SoVRMLTransform, SoVRMLVertexLine,
SoVRMLVertexPoint, SoVRMLVertexShape, SoShadowGroup, SoProfilerStats,
SoEngine, SoNodeEngine, SoFieldContainer, SoAsciiText, SoBlinker,
SoBumpMap, SoImage, SoIndexedLineSet, SoIndexedMarkerSet,
SoIndexedPointSet, SoLOD, SoLevelOfDetail, SoMaterial, SoNode,
SoPackedColor, SoSceneTexture2, SoSceneTextureCubeMap, SoSeparator,
SoShape, SoSwitch, SoText3, SoTexture2, SoTexture3, SoTextureCubeMap,
SoVertexAttribute, SoVertexProperty, and SoVertexShape.
void SoBase::addAuditor (void *const auditor, const SoNotRec::Type type)
Add an auditor to notify whenever the object changes in any significant
way.
See also:
removeAuditor()
void SoBase::removeAuditor (void *const auditor, const SoNotRec::Type
type) Remove an auditor from the list. auditor will then no longer be
notified whenever any updates are made to this object.
See also:
addAuditor()
const SoAuditorList & SoBase::getAuditors (void) const Returns list of
objects auditing this object.
See also:
addAuditor(), removeAuditor()
void SoBase::addWriteReference (SoOutput * out, SbBool isfromfield = 0)
[virtual] This method is used during the first write pass of a write
action to count the number of references to this object in the scene
graph.
Reimplemented in SoFieldContainer, and SoBaseKit.
SbBool SoBase::shouldWrite (void) Returns TRUE if this object should be
written out during a write action. Will return FALSE if no references
to this object has been made in the scene graph.
Note that connections from the fields of fieldcontainer objects is not
alone a valid reason for writing out the object -- there must also be
at least one reference directly from another SoBase (like a
parent/child relationship, for instance).
This method will return a valid result only during the second pass of
write actions.
void SoBase::incrementCurrentWriteCounter (void) [static] This API member
is considered internal to the library, as it is not likely to be of
interest to the application programmer.
void SoBase::decrementCurrentWriteCounter (void) [static] This API member
is considered internal to the library, as it is not likely to be of
interest to the application programmer.
SoBase * SoBase::getNamedBase (const SbName & name, SoType type) [static]
Returns the object of type, or derived from type, registered under
name. If several has been registered under the same name with the same
type, returns the last one which was registered.
If no object of a valid type or subtype has been registered with the
given name, returns NULL.
int SoBase::getNamedBases (const SbName & name, SoBaseList & baselist,
SoType type) [static] Returns the number of objects of type type, or
derived from type, registered under name.
All matches will also be appended to baselist.
SbBool SoBase::read (SoInput * in, SoBase *& base, SoType expectedtype)
[static] Read next SoBase derived instance from the in stream, check
that it is derived from expectedtype and place a pointer to the newly
allocated instance in base.
FALSE is returned on read errors, mismatch with the expectedtype, or if
there are attempts at referencing (through the USE keyword) unknown
instances.
If we return TRUE with base equal to NULL, three things might have
happened:
1. End-of-file. Use SoInput::eof() after calling this method to detect
end-of-file conditions.
2. in didn’t have a valid identifier name at the stream for us to read.
This happens either in the case of errors, or when all child nodes of a
group has been read. Check if the next character in the stream is a ’}’
to detect the latter case.
3. A child was given as the NULL keyword. This can happen when reading
the contents of SoSFNode fields (note that NULL is not allowed for
SoMFNode)
If TRUE is returned and base is not NULL upon return, the instance was
allocated and initialized according to what was read from the in
stream.
void SoBase::setInstancePrefix (const SbString & c) [static] Referenced
instances of SoBase are written as ’DEF NamePrefixNumber’ when
exported. ’Name’ is the name of the base instance from setName(),
’Prefix’ is common for all objects and can be set by this method
(default is ’+’), and ’Number’ is a unique id which is necessary if
multiple objects have the same name.
If you want the prefix to be something else than ’+’, use this method.
void SoBase::setTraceRefs (SbBool trace) [static] Set to TRUE to activate
debugging of reference counting, which could aid in finding hard to
track down problems with accesses to freed memory or memory leaks.
Note: this will produce lots of debug information in any ’normal’
running system, so use sensibly.
The reference tracing functionality will be disabled in ’release
versions’ of the Coin library.
SbBool SoBase::getTraceRefs (void) [static] Return the status of the
reference tracing flag.
See also:
setTraceRefs()
SbBool SoBase::connectRoute (SoInput * in, const SbName & fromnodename,
const SbName & fromfieldname, const SbName & tonodename, const SbName &
tofieldname) [static] Connect a route from the node named
fromnodenames field fromfieldname to the node named tonodenames field
tofieldname. This method will consider the fields types (event in,
event out, etc) when connecting.
This function is an extension for Coin, and it is not available in the
original SGI Open Inventor v2.1 API.
Since:
Coin 2.0
void SoBase::assertAlive (void) const This API member is considered
internal to the library, as it is not likely to be of interest to the
application programmer.
There are 4 bits allocated for each SoBase-object for a bitpattern that
indicates the object is still ’alive’. The pattern is changed when the
object is destructed. If this method is then called after destruction,
an assert will hit.
This is used internally in Coin (in for instance SoBase::ref()) to try
to detect when the instance has been prematurely destructed. This is a
very common mistake to make by application programmers (letting the
refcount dip to zero before it should, that is), so the extra piece of
assistance through the accompanying assert() in this method to detect
dangling references to the object, with subsequent memory corruption
and mysterious crashes, should be a Good Thing.
This function is an extension for Coin, and it is not available in the
original SGI Open Inventor v2.1 API.
Since:
Coin 2.0
SbBool SoBase::readRoute (SoInput * in) [static] This API member is
considered internal to the library, as it is not likely to be of
interest to the application programmer.
Reads a (VRML97) ROUTE. We decided to also add support for routes in
Coin, as a generic feature, since we think it is nicer than setting up
field connections inside the nodes.
void SoBase::destroy (void) [protected, virtual] Cleans up all hanging
references to and from this instance, and then commits suicide.
Called automatically when the reference count goes to zero.
Reimplemented in SoProto.
SbBool SoBase::hasMultipleWriteRefs (void) const [protected] Returns TRUE
if this object will be written more than once upon export. Note that
the result from this method is only valid during the second pass of a
write action (and partly during the COUNT_REFS pass).
SbBool SoBase::writeHeader (SoOutput * out, SbBool isgroup, SbBool
isengine) const [protected] Write out the header of any SoBase derived
object. The header consists of the DEF keyword and the object name (if
the object has a name, otherwise these will be skipped), the class name
and a left bracket.
Alternatively, the object representation may be made up of just the USE
keyword plus the object name, if this is the second or subsequent
reference written to the file.
If the object has been completed just by writing the header (which will
be the case if we’re writing multiple references of an object), we
return TRUE, otherwise FALSE.
If we return FALSE (i.e. there’s more to write), we will increment the
indentation level.
See also:
writeFooter(), SoOutput::indent()
void SoBase::writeFooter (SoOutput * out) const [protected] This method
will terminate the block representing an SoBase derived object.
const char * SoBase::getFileFormatName (void) const [protected, virtual]
Returns the class name this object should be written under. Default
string returned is the name of the class from the type system.
User extensions nodes and engines override this method to return the
name of the extension (instead of ’UnknownNode’ or ’UnknownEngine’).
Reimplemented in SoProtoInstance.
SbBool SoBase::readInstance (SoInput * in, unsigned short flags)
[protected, pure virtual] This method is mainly intended for internal
use during file import operations.
It reads a definition of an instance from the input stream in. The
input stream state points to the start of a serialized / persistant
representation of an instance of this class type.
TRUE or FALSE is returned, depending on if the instantiation and
configuration of the new object of this class type went ok or not. The
import process should be robust and handle corrupted input streams by
returning FALSE.
flags is used internally during binary import when reading user
extension nodes, group nodes or engines.
Implemented in SoVRMLImageTexture, SoVRMLLOD, SoVRMLParent,
SoVRMLPixelTexture, SoVRMLSwitch, SoEngine, SoNodeEngine,
SoFieldContainer, SoProto, SoProtoInstance, SoBaseKit,
SoInteractionKit, SoNodeKitListPart, SoBumpMap, SoFile, SoGroup,
SoImage, SoNode, SoNormalBinding, SoSeparator, SoShaderObject,
SoTexture2, SoTexture3, SoTextureCoordinateBinding, SoTextureCubeMap,
SoVertexAttribute, and SoWWWInline.
uint32_t SoBase::getCurrentWriteCounter (void) [static, protected] This API
member is considered internal to the library, as it is not likely to be
of interest to the application programmer.
void SoBase::staticDataLock (void) [static, protected] .PP
For internal use only.
Since:
Coin 2.3
void SoBase::staticDataUnlock (void) [static, protected] .PP
For internal use only.
Since:
Coin 2.3
Author
Generated automatically by Doxygen for Coin from the source code.