Coin: SoType Class Reference

| Coin3D is Free Software, published under the BSD 3-clause license. | https://coin3d.github.io https://www.kongsberg.com/en/kogt/

SoType Class Reference
Miscellaneous Classes

The SoType class is the basis for the runtime type system in Coin. More...

`#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 runtime 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 class names, 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!\n",
anode->getTypeId().getName());
}
}
SoBase::getTypeId
virtual SoType getTypeId(void) const =0
Returns the type identification of an object derived from a class inheriting SoBase....
SoCamera::getClassTypeId
static SoType getClassTypeId(void)
Definition SoCamera.cpp:337
SoDebugError::postWarning
static void postWarning(const char *const source, const char *const format,...)
Definition SoDebugError.cpp:402
SoNode
The SoNode class is the base class for nodes used in scene graphs.
Definition SoNode.h:56
SoOrthographicCamera::getClassTypeId
static SoType getClassTypeId(void)
Definition SoOrthographicCamera.cpp:105
SoPerspectiveCamera::getClassTypeId
static SoType getClassTypeId(void)
Definition SoPerspectiveCamera.cpp:79
SoType::isDerivedFrom
SbBool isDerivedFrom(const SoType type) const
Definition SoType.cpp:737
SoType::getName
SbName getName(void) const
Definition SoType.cpp:675

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

## ◆ instantiationMethod

typedef void *(* SoType::instantiationMethod) (void)

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 instantiation method will take no arguments and returns a void pointer to a newly allocated and initialized object of the class type.

## Member Function Documentation

## ◆ fromName()

SoType SoType::fromName | ( | const SbName | name | ) |
| static

This static function returns the SoType object associated with name name.

Type objects for built-in types can be retrieved 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-4, Microsoft Visual C++ v6, 2003, 2005 and 2008), 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-.nosp@m.supp.nosp@m.ort@c.nosp@m.oin3.nosp@m.d.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.

## ◆ getName()

SbName SoType::getName | ( | void |  | ) | const

This method returns the name of the SoBase-derived class type the SoType object is configured for.

## ◆ getParent()

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.

## ◆ isDerivedFrom()

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.

## ◆ getAllDerivedFrom()

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, standalone example which shows how this method can be used for introspection, listing all subclasses of the SoBase superclass:

#include <cstdio>
#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("%s\n", 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;
}
SbName::getString
const char * getString(void) const
Definition SbName.cpp:144
SbPList::getLength
int getLength(void) const
Definition lists/SbPList.h:103
SoDB::init
static void init(void)
Definition SoDB.cpp:200
SoTypeList
The SoTypeList class is a container class for arrays of SoType objects.
Definition SoTypeList.h:39
SoType
The SoType class is the basis for the runtime type system in Coin.
Definition SoType.h:59
SoType::getParent
const SoType getParent(void) const
Definition SoType.cpp:701
SoType::fromName
static SoType fromName(const SbName name)
Definition SoType.cpp:510
SoType::getAllDerivedFrom
static int getAllDerivedFrom(const SoType type, SoTypeList &list)
Definition SoType.cpp:814

## ◆ canCreateInstance()

SbBool SoType::canCreateInstance | ( | void |  | ) | const

This method returns `FALSE` for abstract base classes, and `TRUE` for class types that can be instantiated.

## ◆ createInstance()

void * SoType::createInstance | ( | void |  | ) | const

This method instantiates an object of the current type.

For types that cannot 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 are 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.

## ◆ getData()

uint16_t SoType::getData | ( | void |  | ) | const

This method returns a type specific data variable.

## ◆ getKey()

int16_t SoType::getKey | ( | void |  | ) | const
| inline

This method returns the type's index in the internal type list.

## ◆ operator==()

SbBool SoType::operator== | ( | const SoType | type | ) | const
| inline

Check type equality.

## ◆ operator!=()

SbBool SoType::operator!= | ( | const SoType | type | ) | const
| inline

Check type inequality.

## ◆ operator<()

SbBool SoType::operator< | ( | const SoType | type | ) | const
| inline

Comparison operator for sorting type data according to some internal criterion.

## ◆ operator<=()

SbBool SoType::operator<= | ( | const SoType | type | ) | const
| inline

Comparison operator for sorting type data according to some internal criterion.

## ◆ operator>=()

SbBool SoType::operator>= | ( | const SoType | type | ) | const
| inline

Comparison operator for sorting type data according to some internal criterion.

## ◆ operator>()

SbBool SoType::operator> | ( | const SoType | type | ) | const
| inline

Comparison operator for sorting type data according to some internal criterion.

## ◆ createType()

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().

## ◆ overrideType()

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 scene graph 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 scene graph 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 ascii\n\n"
"Separator {"
" WWWInline { }"
"}";
SoInput in;
in.setBuffer(ivscene, strlen(ivscene));
SoSeparator * root = SoDB::readAll(&in);
root->ref();
SoOutput out;
SoWriteAction wa(&out);
wa.apply(root);
root->unref();
return 0;
}
SoBase::getFileFormatName
virtual const char * getFileFormatName(void) const
Definition SoBase.cpp:1364
SoBase::unref
void unref(void) const
Definition SoBase.cpp:530
SoBase::ref
void ref(void) const
Definition SoBase.cpp:478
SoDB::readAll
static SoSeparator * readAll(SoInput *input)
Definition SoDB.cpp:682
SoDebugError::postInfo
static void postInfo(const char *const source, const char *const format,...)
Definition SoDebugError.cpp:412
SoInput
The SoInput class is an abstraction of file import functionality.
Definition SoInput.h:61
SoInput::setBuffer
virtual void setBuffer(const void *bufpointer, size_t bufsize)
Definition SoInput.cpp:733
SoType::overrideType
static const SoType overrideType(const SoType originalType, const instantiationMethod method=NULL)
Definition SoType.cpp:450
SoWWWInline
The SoWWWInline class is a node used to include data from an URL.
Definition SoWWWInline.h:57
SoWWWInline::initClass
static void initClass(void)
Sets up initialization for data common to all instances of this class, like submitting necessary info...
Definition SoWWWInline.cpp:255
SoWWWInline::readInstance
virtual SbBool readInstance(SoInput *in, unsigned short flags)
Definition SoWWWInline.cpp:671
SoWWWInline::getClassTypeId
static SoType getClassTypeId(void)
Definition SoWWWInline.cpp:212
SO_NODE_SOURCE
#define SO_NODE_SOURCE(classname)
Definition Coin_macros.dox:98
SO_NODE_HEADER
#define SO_NODE_HEADER(classname)
Definition Coin_macros.dox:50
SO_NODE_INIT_CLASS
#define SO_NODE_INIT_CLASS(classname, parentclass, parentname)
Definition Coin_macros.dox:73
SO_NODE_CONSTRUCTOR
#define SO_NODE_CONSTRUCTOR(classname)
Definition Coin_macros.dox:122

## ◆ removeType()

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

## ◆ init()

void SoType::init | ( | void |  | ) |
| static

This static method initializes the type system.

## ◆ fromKey()

SoType SoType::fromKey | ( | uint16_t | key | ) |
| static

Find and return a type from the given key ID.

## ◆ badType()

SoType SoType::badType | ( | void |  | ) |
| static

This method returns an illegal type, useful for returning errors.

See also
  SbBool SoType::isBad() const

## ◆ isBad()

SbBool SoType::isBad | ( | void |  | ) | const
| inline

This method returns TRUE if the SoType object represents an illegal class type.

## ◆ makeInternal()

void SoType::makeInternal | ( | void |  | ) |

This method turns the specific type into an internal type.

## ◆ isInternal()

SbBool SoType::isInternal | ( | void |  | ) | const

This function returns TRUE if the type is an internal type.

## ◆ getNumTypes()

int SoType::getNumTypes | ( | void |  | ) |
| static

This function returns the number of types registered in the runtime type system.

## ◆ getInstantiationMethod()

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

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

- SoType.h
- SoType.cpp