NAME
SoType -
The SoType class is the basis for the run-time type system in Coin.
Many of the classes in the Coin library must have their type
information registered before any instances are created (including, but
not limited to: engines, nodes, fields, actions, nodekits and
manipulators). The use of SoType to store this information provides
lots of various functionality for working with class hierarchies,
comparing class types, instantiating objects from classnames, etc etc.
SYNOPSIS
#include <Inventor/SoType.h>
Public Types
typedef void *(* instantiationMethod )(void)
Public Member Functions
SbName getName (void) const
const SoType getParent (void) const
SbBool isDerivedFrom (const SoType type) const
SbBool canCreateInstance (void) const
void * createInstance (void) const
uint16_t getData (void) const
int16_t getKey (void) const
SbBool operator== (const SoType type) const
SbBool operator!= (const SoType type) const
SbBool operator< (const SoType type) const
SbBool operator<= (const SoType type) const
SbBool operator>= (const SoType type) const
SbBool operator> (const SoType type) const
SbBool isBad (void) const
void makeInternal (void)
SbBool isInternal (void) const
instantiationMethod getInstantiationMethod (void) const
Static Public Member Functions
static SoType fromName (const SbName name)
static int getAllDerivedFrom (const SoType type, SoTypeList &list)
static const SoType createType (const SoType parent, const SbName name,
const instantiationMethod method=NULL, const uint16_t data=0)
static const SoType overrideType (const SoType originalType, const
instantiationMethod method=NULL)
static SbBool removeType (const SbName &name)
static void init (void)
static SoType fromKey (uint16_t key)
static SoType badType (void)
static int getNumTypes (void)
Detailed Description
The SoType class is the basis for the run-time type system in Coin.
Many of the classes in the Coin library must have their type
information registered before any instances are created (including, but
not limited to: engines, nodes, fields, actions, nodekits and
manipulators). The use of SoType to store this information provides
lots of various functionality for working with class hierarchies,
comparing class types, instantiating objects from classnames, etc etc.
It is for instance possible to do things like this:
void cleanLens(SoNode * anode)
{
assert(anode->getTypeId().isDerivedFrom(SoCamera::getClassTypeId()));
if (anode->getTypeId() == SoPerspectiveCamera::getClassTypeId()) {
// do something..
}
else if (anode->getTypeId() == SoOrthographicCamera::getClassTypeId()) {
// do something..
}
else {
SoDebugError::postWarning(’cleanLens’, ’Unknown camera type %s!0,
anode->getTypeId().getName());
}
}
A notable feature of the SoType class is that it is only 16 bits long
and therefore should be passed around by value for efficiency reasons.
One important note about the use of SoType to register class
information: super classes must be registered before any of their
derived classes are.
See also Dynamic Loading of Extension Nodes for some additional SoType-
related information.
Member Typedef Documentation
SoType::instantiationMethod This is a convenience typedef for the function
signature of a typed class’ instantiation method. It is an extension on
the original Inventor API. Mostly only useful for internal purposes.
An instantation method will take no arguments and returns a void-
pointer to a newly allocated and initialized object of the class type.
Member Function Documentation
SoType SoType::fromName (const SbName name) [static] This static function
returns the SoType object associated with name name.
Type objects for builtin types can be retreived by name both with and
without the ’So’ prefix. For dynamically loadable extension nodes, the
name given to this function must match exactly.
If no node type with the given name has been initialized, a dynamically
loadable extension node with the given name is searched for. If one is
found, it is loaded and initialized, and the SoType object for the
newly initialized class type returned. If no module is found, or the
initialization of the module fails, SoType::badType() is returned.
Support for dynamically loadable extension nodes varies from platform
to platform, and from compiler suite to compiler suite.
So far code built with the following compilers are supported: GNU GCC
v2, GNU GCC v3, Microsoft Visual C++ v6 (and probably v7, not tested),
SGI MIPSPro v7.
Extensions built with compilers that are known to be binary compatible
with the above compilers are also supported, such as e.g. the Intel x86
compiler compatible with MSVC++.
To support dynamic loading for other compilers, we need to know how the
compiler mangles the ’static void classname::initClass(void)’ symbol.
If your compiler is not supported, tell us at coin-support@coin3d.org
which it is and send us the output of a symbol-dump on the shared
object. Typically you can do
$ nm <Node>.so | grep initClass
to find the relevant mangled symbol.
SbName SoType::getName (void) const This method returns the name of the
SoBase-derived class type the SoType object is configured for.
const SoType SoType::getParent (void) const This method returns the SoType
type for the parent class of the SoBase-derived class the SoType object
is configured for.
SbBool SoType::isDerivedFrom (const SoType parent) const This method
returns TRUE if the given type is derived from (or is) the parent type,
and FALSE otherwise.
int SoType::getAllDerivedFrom (const SoType type, SoTypeList & list)
[static] This method appends all the class types derived from type to
list, and returns the number of types added to the list. Internal types
are not included in the list, nor are they counted.
type itself is also added to the list, as a type is seen as a
derivation of its own type.
NB: do not write code which depends in any way on the order of the
elements returned in list.
Here is a small, stand-alone example which shows how this method can be
used for introspection, listing all subclasses of the SoBase
superclass:
#include <stdio.h>
#include <Inventor/SoDB.h>
#include <Inventor/lists/SoTypeList.h>
static void
list_subtypes(SoType t, unsigned int indent = 0)
{
SoTypeList tl;
SoType::getAllDerivedFrom(t, tl);
for (unsigned int i=0; i < indent; i++) { printf(’ ’); }
printf(’%s0, t.getName().getString());
indent++;
for (int j=0; j < tl.getLength(); j++) {
if (tl[j].getParent() == t) { // only interested in direct descendents
list_subtypes(tl[j], indent);
}
}
}
int
main(void)
{
SoDB::init();
list_subtypes(SoType::fromName(’SoBase’));
return 0;
}
SbBool SoType::canCreateInstance (void) const This method returns FALSE for
abstract base classes, and TRUE for class types that can be
instantiated.
void * SoType::createInstance (void) const This method instantiates an
object of the current type.
For types that can not be instantiated, NULL is returned.
Note that if the Coin library has been built as a DLL under Microsoft
Windows and you use this method from application code, you must make
sure that both the Coin DLL and the application executable is using the
same instance of a C Run-Time (CRT) library. Otherwise, you will get
memory heap corruption upon deallocating the returned instances,
eventually leading to mysterious crashes.
This is not harmful if you only call SoType::createInstance() on types
for reference counted class-types, though. These include all nodes,
engines, paths, nodekits, draggers and manipulators.
uint16_t SoType::getData (void) const This method returns a type specific
data variable.
int16_t SoType::getKey (void) const [inline] This method returns the type’s
index in the internal typelist.
SbBool SoType::operator== (const SoType type) const [inline] Check type
equality.
SbBool SoType::operator!= (const SoType type) const [inline] Check type
inequality.
SbBool SoType::operator< (const SoType type) const [inline] Comparison
operator for sorting type data according to some internal criterion.
SbBool SoType::operator<= (const SoType type) const [inline] Comparison
operator for sorting type data according to some internal criterion.
SbBool SoType::operator>= (const SoType type) const [inline] Comparison
operator for sorting type data according to some internal criterion.
SbBool SoType::operator> (const SoType type) const [inline] Comparison
operator for sorting type data according to some internal criterion.
const SoType SoType::createType (const SoType parent, const SbName name,
const instantiationMethod method = NULL, const uint16_t data = 0)
[static] This method creates and registers a new class type.
Classes that do not inherit any other class should use
SoType::badType() for the first argument. Abstract classes should use
NULL for the method argument.
The value passed in for the data parameter can be retrieved with
SoType::getData().
const SoType SoType::overrideType (const SoType originalType, const
instantiationMethod method = NULL) [static] This method makes a new
class’s instantiation method override the instantiation method of an
existing class.
The new type should be a C++ subclass of the original class type, but
this won’t be checked though.
If NULL is passed as the second argument, the type will be considered
uninstantiable -- it does not revert the configuration to the default
setting as one might think.
Here’s a complete code examples which shows how to fully override a
built-in Coin node class, so that a) your application-specific
extension class gets instantiated instead of the built-in class upon
scenegraph import, and b) it gets written out properly upon export:
#include <Inventor/SoDB.h>
#include <Inventor/actions/SoWriteAction.h>
#include <Inventor/errors/SoDebugError.h>
#include <Inventor/nodes/SoSeparator.h>
#include <Inventor/nodes/SoWWWInline.h>
class MyWWWInline : public SoWWWInline {
SO_NODE_HEADER(MyWWWInline);
public:
static void initClass(void);
MyWWWInline(void);
protected:
virtual ~MyWWWInline();
virtual SbBool readInstance(SoInput * in, unsigned short flags);
virtual const char * getFileFormatName(void) const;
};
SO_NODE_SOURCE(MyWWWInline);
MyWWWInline::MyWWWInline(void)
{
SO_NODE_CONSTRUCTOR(MyWWWInline);
// Fool the library to believe this is an internal class, so it gets
// written out in the same manner as the built-in classes, instead
// of as en extension class. There are slight differences, which you
// want to avoid when overriding a class like we do with MyWWWInline
// vs SoWWWInline here.
this->isBuiltIn = TRUE;
}
MyWWWInline::~MyWWWInline()
{
}
void
MyWWWInline::initClass(void)
{
SO_NODE_INIT_CLASS(MyWWWInline, SoWWWInline, ’SoWWWInline’);
// Override instantiation method, so we get MyWWWInline instead of
// SoWWWInline instances upon scenegraph import.
(void)SoType::overrideType(SoWWWInline::getClassTypeId(),
MyWWWInline::createInstance);
}
// Override SoBase::getFileFormatName() to make node get written as
// ’WWWInline’ instead of ’MyWWWInline’.
const char *
MyWWWInline::getFileFormatName(void) const
{
return ’WWWInline’;
}
SbBool
MyWWWInline::readInstance(SoInput * in, unsigned short flags)
{
SoDebugError::postInfo(’MyWWWInline::readInstance’, ’hepp’);
return SoWWWInline::readInstance(in, flags);
}
int
main(int argc, char ** argv)
{
SoDB::init();
MyWWWInline::initClass();
const char * ivscene =
’#Inventor V2.1 ascii0
’Separator {’
’ WWWInline { }’
’}’;
SoInput in;
in.setBuffer((void *)ivscene, strlen(ivscene));
SoSeparator * root = SoDB::readAll(&in);
root->ref();
SoOutput out;
SoWriteAction wa(&out);
wa.apply(root);
root->unref();
return 0;
}
SbBool SoType::removeType (const SbName & name) [static] This method
removes class type from the class system. Returns FALSE if a type with
the given name doesn’t exist.
Since:
Coin 3.0
void SoType::init (void) [static] This static method initializes the type
system.
SoType SoType::fromKey (uint16_t key) [static] Find and return a type from
the given key ID.
SoType SoType::badType (void) [static] This method returns an illegal type,
useful for returning errors.
See also:
SbBool SoType::isBad() const
SbBool SoType::isBad (void) const [inline] This method returns TRUE if the
SoType object represents an illegal class type.
void SoType::makeInternal (void) This method turns the specific type into
an internal type.
SbBool SoType::isInternal (void) const This function returns TRUE if the
type is an internal type.
int SoType::getNumTypes (void) [static] This function returns the number of
types registered in the run-time type system.
SoType::instantiationMethod SoType::getInstantiationMethod (void) const
Returns a pointer to the method used to instantiate objects of the
given type.
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
Author
Generated automatically by Doxygen for Coin from the source code.