.TH "SoType" 3 "Sat Oct 12 2013" "Version 4.0.0a" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME SoType \- .PP The \fBSoType\fP class is the basis for the run-time type system in Coin\&. .PP 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 \fBSoType\fP to store this information provides lots of various functionality for working with class hierarchies, comparing class types, instantiating objects from classnames, etc etc\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .SS "Public Types" .in +1c .ti -1c .RI "typedef void *(* \fBinstantiationMethod\fP )(void)" .br .in -1c .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBSbName\fP \fBgetName\fP (void) const " .br .ti -1c .RI "const \fBSoType\fP \fBgetParent\fP (void) const " .br .ti -1c .RI "SbBool \fBisDerivedFrom\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBcanCreateInstance\fP (void) const " .br .ti -1c .RI "void * \fBcreateInstance\fP (void) const " .br .ti -1c .RI "uint16_t \fBgetData\fP (void) const " .br .ti -1c .RI "int16_t \fBgetKey\fP (void) const " .br .ti -1c .RI "SbBool \fBoperator==\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBoperator!=\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBoperator<\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBoperator<=\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBoperator>=\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBoperator>\fP (const \fBSoType\fP type) const " .br .ti -1c .RI "SbBool \fBisBad\fP (void) const " .br .ti -1c .RI "void \fBmakeInternal\fP (void)" .br .ti -1c .RI "SbBool \fBisInternal\fP (void) const " .br .ti -1c .RI "\fBinstantiationMethod\fP \fBgetInstantiationMethod\fP (void) const " .br .in -1c .SS "Static Public Member Functions" .in +1c .ti -1c .RI "static \fBSoType\fP \fBfromName\fP (const \fBSbName\fP name)" .br .ti -1c .RI "static int \fBgetAllDerivedFrom\fP (const \fBSoType\fP type, \fBSoTypeList\fP &list)" .br .ti -1c .RI "static const \fBSoType\fP \fBcreateType\fP (const \fBSoType\fP parent, const \fBSbName\fP name, const \fBinstantiationMethod\fP method=NULL, const uint16_t data=0)" .br .ti -1c .RI "static const \fBSoType\fP \fBoverrideType\fP (const \fBSoType\fP originalType, const \fBinstantiationMethod\fP method=NULL)" .br .ti -1c .RI "static SbBool \fBremoveType\fP (const \fBSbName\fP &name)" .br .ti -1c .RI "static void \fBinit\fP (void)" .br .ti -1c .RI "static \fBSoType\fP \fBfromKey\fP (uint16_t key)" .br .ti -1c .RI "static \fBSoType\fP \fBbadType\fP (void)" .br .ti -1c .RI "static int \fBgetNumTypes\fP (void)" .br .in -1c .SH "Detailed Description" .PP The \fBSoType\fP class is the basis for the run-time type system in Coin\&. .PP 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 \fBSoType\fP 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: .PP .PP .nf 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()); } } .fi .PP .PP A notable feature of the \fBSoType\fP class is that it is only 16 bits long and therefore should be passed around by value for efficiency reasons\&. .PP One important note about the use of \fBSoType\fP to register class information: super classes must be registered before any of their derived classes are\&. .PP See also \fBDynamic Loading of Extension Nodes\fP for some additional SoType-related information\&. .SH "Member Typedef Documentation" .PP .SS "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\&. .PP An instantation method will take no arguments and returns a void-pointer to a newly allocated and initialized object of the class type\&. .SH "Member Function Documentation" .PP .SS "POTENTIAL_ROTTING_DOCUMENTATION \fBSoType\fP SoType::fromName (const \fBSbName\fPname)\fC [static]\fP" This static function returns the \fBSoType\fP object associated with name \fIname\fP\&. .PP 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\&. .PP 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 \fBSoType\fP object for the newly initialized class type returned\&. If no module is found, or the initialization of the module fails, \fBSoType::badType()\fP is returned\&. .PP Support for dynamically loadable extension nodes varies from platform to platform, and from compiler suite to compiler suite\&. .PP 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\&. .PP 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++\&. .PP 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 \fCcoin-support@coin3d.org\fP which it is and send us the output of a symbol-dump on the shared object\&. Typically you can do .PP .PP .nf $ nm \&.so | grep initClass .fi .PP .PP to find the relevant mangled symbol\&. .SS "\fBSbName\fP SoType::getName (void) const" This method returns the name of the SoBase-derived class type the \fBSoType\fP object is configured for\&. .SS "const \fBSoType\fP SoType::getParent (void) const" This method returns the \fBSoType\fP type for the parent class of the SoBase-derived class the \fBSoType\fP object is configured for\&. .SS "SbBool SoType::isDerivedFrom (const \fBSoType\fPparent) const" This method returns \fCTRUE\fP if the given type is derived from (or \fIis\fP) the \fIparent\fP type, and \fCFALSE\fP otherwise\&. .SS "int SoType::getAllDerivedFrom (const \fBSoType\fPtype, \fBSoTypeList\fP &list)\fC [static]\fP" This method appends all the class types derived from \fItype\fP to \fIlist\fP, and returns the number of types added to the list\&. Internal types are not included in the list, nor are they counted\&. .PP \fItype\fP itself is also added to the list, as a type is seen as a derivation of its own type\&. .PP NB: do not write code which depends in any way on the order of the elements returned in \fIlist\fP\&. .PP Here is a small, stand-alone example which shows how this method can be used for introspection, listing all subclasses of the \fBSoBase\fP superclass: .PP .PP .nf #include #include #include 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; } .fi .PP .SS "SbBool SoType::canCreateInstance (void) const" This method returns \fCFALSE\fP for abstract base classes, and \fCTRUE\fP for class types that can be instantiated\&. .SS "void * SoType::createInstance (void) const" This method instantiates an object of the current type\&. .PP For types that can not be instantiated, \fCNULL\fP is returned\&. .PP \fBNote that if the Coin library has been built as a DLL under Microsoft Windows and you use this method from application code, you \fImust\fP 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 \fIwill\fP get memory heap corruption upon deallocating the returned instances, eventually leading to mysterious crashes\&.\fP .PP This is not harmful if you only call \fBSoType::createInstance()\fP on types for reference counted class-types, though\&. These include all nodes, engines, paths, nodekits, draggers and manipulators\&. .SS "uint16_t SoType::getData (void) const" This method returns a type specific data variable\&. .SS "int16_t SoType::getKey (void) const\fC [inline]\fP" This method returns the type's index in the internal typelist\&. .SS "SbBool SoType::operator== (const \fBSoType\fPtype) const\fC [inline]\fP" Check type equality\&. .SS "SbBool SoType::operator!= (const \fBSoType\fPtype) const\fC [inline]\fP" Check type inequality\&. .SS "SbBool SoType::operator< (const \fBSoType\fPtype) const\fC [inline]\fP" Comparison operator for sorting type data according to some internal criterion\&. .SS "SbBool SoType::operator<= (const \fBSoType\fPtype) const\fC [inline]\fP" Comparison operator for sorting type data according to some internal criterion\&. .SS "SbBool SoType::operator>= (const \fBSoType\fPtype) const\fC [inline]\fP" Comparison operator for sorting type data according to some internal criterion\&. .SS "SbBool SoType::operator> (const \fBSoType\fPtype) const\fC [inline]\fP" Comparison operator for sorting type data according to some internal criterion\&. .SS "const \fBSoType\fP SoType::createType (const \fBSoType\fPparent, const \fBSbName\fPname, const \fBinstantiationMethod\fPmethod = \fCNULL\fP, const uint16_tdata = \fC0\fP)\fC [static]\fP" This method creates and registers a new class type\&. .PP Classes that do not inherit any other class should use \fBSoType::badType()\fP for the first argument\&. Abstract classes should use \fCNULL\fP for the \fImethod\fP argument\&. .PP The value passed in for the \fIdata\fP parameter can be retrieved with \fBSoType::getData()\fP\&. .SS "const \fBSoType\fP SoType::overrideType (const \fBSoType\fPoriginalType, const \fBinstantiationMethod\fPmethod = \fCNULL\fP)\fC [static]\fP" This method makes a new class's instantiation method override the instantiation method of an existing class\&. .PP The new type should be a C++ subclass of the original class type, but this won't be checked though\&. .PP If \fCNULL\fP 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\&. .PP Here's a \fIcomplete\fP 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: .PP .PP .nf #include #include #include #include #include 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 ascii\n\n' '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; } .fi .PP .SS "SbBool SoType::removeType (const \fBSbName\fP &name)\fC [static]\fP" This method removes class type from the class system\&. Returns FALSE if a type with the given name doesn't exist\&. .PP \fBSince:\fP .RS 4 Coin 3\&.0 .RE .PP .SS "void SoType::init (void)\fC [static]\fP" This static method initializes the type system\&. .SS "\fBSoType\fP SoType::fromKey (uint16_tkey)\fC [static]\fP" Find and return a type from the given key ID\&. .SS "\fBSoType\fP SoType::badType (void)\fC [static]\fP" This method returns an illegal type, useful for returning errors\&. .PP \fBSee Also:\fP .RS 4 SbBool \fBSoType::isBad() const\fP .RE .PP .SS "SbBool SoType::isBad (void) const\fC [inline]\fP" This method returns TRUE if the \fBSoType\fP object represents an illegal class type\&. .SS "void SoType::makeInternal (void)" This method turns the specific type into an internal type\&. .SS "SbBool SoType::isInternal (void) const" This function returns TRUE if the type is an internal type\&. .SS "int SoType::getNumTypes (void)\fC [static]\fP" This function returns the number of types registered in the run-time type system\&. .SS "\fBSoType::instantiationMethod\fP SoType::getInstantiationMethod (void) const" Returns a pointer to the method used to instantiate objects of the given type\&. .PP This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2\&.1 API\&. .PP \fBSince:\fP .RS 4 Coin 2\&.0 .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.