--- name: "SoProto" section: "3" platform: "linux" package: "coin" version: "1:4.0.10-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/SoProto" --- # SoProto(3) The SoProto class handles PROTO definitions. ## NAME SoProto - The **SoProto** class handles PROTO definitions. ## SYNOPSIS \#include \ Inherits **SoNode**. ### Public Member Functions **SoProto** (const SbBool externproto=FALSE)\ virtual **SoType** **getTypeId** (void) const\ Returns the type identification of an object derived from a class inheriting **SoBase**. This is used for runtime type checking and *downward"*casting. **SoProtoInstance** \* **createProtoInstance** (void)\ void **addISReference** (**SoNode** \*container, const **SbName** &fieldname, const **SbName** &interfacename)\ **SbName** **findISReference** (const **SoFieldContainer** \*container, const **SbName** &fieldname)\ void **addReference** (const **SbName** &name, **SoBase** \*base)\ void **removeReference** (const **SbName** &name)\ **SoBase** \* **findReference** (const **SbName** &name) const\ void **addRoute** (const **SbName** &fromnode, const **SbName** &fromfield, const **SbName** &tonode, const **SbName** &tofield)\ **SbName** **getProtoName** (void) const\ virtual SbBool **readInstance** (**SoInput** \*input, unsigned short flags)\ virtual void **write** (**SoWriteAction** \*action)\ Public Member Functions inherited from **SoNode** void **setOverride** (const SbBool state)\ SbBool **isOverride** (void) const\ void **setNodeType** (const **NodeType** type)\ **NodeType** **getNodeType** (void) const\ virtual **SoNode** \* **copy** (SbBool copyconnections=FALSE) const\ virtual SbBool **affectsState** (void) const\ virtual void **doAction** (**SoAction** \*action)\ virtual void **GLRender** (**SoGLRenderAction** \*action)\ virtual void **GLRenderBelowPath** (**SoGLRenderAction** \*action)\ virtual void **GLRenderInPath** (**SoGLRenderAction** \*action)\ virtual void **GLRenderOffPath** (**SoGLRenderAction** \*action)\ virtual void **callback** (**SoCallbackAction** \*action)\ virtual void **getBoundingBox** (**SoGetBoundingBoxAction** \*action)\ virtual void **getMatrix** (**SoGetMatrixAction** \*action)\ virtual void **handleEvent** (**SoHandleEventAction** \*action)\ virtual void **pick** (**SoPickAction** \*action)\ virtual void **rayPick** (**SoRayPickAction** \*action)\ virtual void **search** (**SoSearchAction** \*action)\ virtual void **audioRender** (**SoAudioRenderAction** \*action)\ virtual void **getPrimitiveCount** (**SoGetPrimitiveCountAction** \*action)\ virtual void **grabEventsSetup** (void)\ virtual void **grabEventsCleanup** (void)\ virtual void **startNotify** (void)\ virtual void **notify** (**SoNotList** \*l)\ SbUniqueId **getNodeId** (void) const\ virtual **SoChildList** \* **getChildren** (void) const\ virtual void **writeInstance** (**SoOutput** \*out)\ virtual **SoNode** \* **addToCopyDict** (void) const\ virtual void **copyContents** (const **SoFieldContainer** \*from, SbBool copyconnections)\ virtual **SoFieldContainer** \* **copyThroughConnection** (void) const\ Public Member Functions inherited from **SoFieldContainer** void **setToDefaults** (void)\ SbBool **hasDefaultValues** (void) const\ SbBool **fieldsAreEqual** (const **SoFieldContainer** \*container) const\ void **copyFieldValues** (const **SoFieldContainer** \*container, SbBool copyconnections=FALSE)\ SbBool **set** (const char \*const fielddata)\ void **get** (**SbString** &fielddata)\ virtual int **getFields** (**SoFieldList** &l) const\ virtual int **getAllFields** (**SoFieldList** &l) const\ virtual **SoField** \* **getField** (const **SbName** &name) const\ virtual **SoField** \* **getEventIn** (const **SbName** &name) const\ virtual **SoField** \* **getEventOut** (const **SbName** &name) const\ SbBool **getFieldName** (const **SoField** \*const field, **SbName** &name) const\ SbBool **enableNotify** (const SbBool flag)\ SbBool **isNotifyEnabled** (void) const\ SbBool **set** (const char \*fielddata, **SoInput** \*input)\ void **get** (**SbString** &fielddata, **SoOutput** \*out)\ virtual SbBool **validateNewFieldValue** (**SoField** \*field, void \*newval)\ virtual void **addWriteReference** (**SoOutput** \*out, SbBool isfromfield=FALSE)\ SbBool **getIsBuiltIn** (void) const\ virtual const **SoFieldData** \* **getFieldData** (void) const\ virtual void **getFieldsMemorySize** (size\_t &managed, size\_t &unmanaged) const\ void **setUserData** (void \*userdata) const\ void \* **getUserData** (void) const\ Public Member Functions inherited from **SoBase** void **ref** (void) const\ void **unref** (void) const\ void **unrefNoDelete** (void) const\ int32\_t **getRefCount** (void) const\ void **touch** (void)\ SbBool **isOfType** (**SoType** type) const\ Returns TRUE if the type of this object is either of the same type or inherited from *type*. virtual **SbName** **getName** (void) const\ virtual void **setName** (const **SbName** &newname)\ void **addAuditor** (void \*const auditor, const **SoNotRec::Type** type)\ void **removeAuditor** (void \*const auditor, const **SoNotRec::Type** type)\ const **SoAuditorList** & **getAuditors** (void) const\ SbBool **shouldWrite** (void)\ void **assertAlive** (void) const\ ### Static Public Member Functions static void **setFetchExternProtoCallback** (SoFetchExternProtoCB \*cb, void \*closure)\ static **SoType** **getClassTypeId** (void)\ static **SoProto** \* **findProto** (const **SbName** &name)\ static void **initClass** (void)\ Static Public Member Functions inherited from **SoNode** static uint32\_t **getCompatibilityTypes** (const **SoType** &nodetype)\ static **SoType** **getClassTypeId** (void)\ static **SoNode** \* **getByName** (const **SbName** &name)\ static int **getByName** (const **SbName** &name, **SoNodeList** &l)\ static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static void **initClasses** (void)\ static SbUniqueId **getNextNodeId** (void)\ static int **getActionMethodIndex** (const **SoType** type)\ static void **getBoundingBoxS** (**SoAction** \*action, **SoNode** \*node)\ static void **GLRenderS** (**SoAction** \*action, **SoNode** \*node)\ static void **callbackS** (**SoAction** \*action, **SoNode** \*node)\ static void **getMatrixS** (**SoAction** \*action, **SoNode** \*node)\ static void **handleEventS** (**SoAction** \*action, **SoNode** \*node)\ static void **pickS** (**SoAction** \*action, **SoNode** \*node)\ static void **rayPickS** (**SoAction** \*action, **SoNode** \*node)\ static void **searchS** (**SoAction** \*action, **SoNode** \*node)\ static void **writeS** (**SoAction** \*action, **SoNode** \*node)\ static void **audioRenderS** (**SoAction** \*action, **SoNode** \*node)\ static void **getPrimitiveCountS** (**SoAction** \*action, **SoNode** \*node)\ Static Public Member Functions inherited from **SoFieldContainer** static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static **SoType** **getClassTypeId** (void)\ This static method returns the **SoType** object associated with objects of this class. static void **cleanupClass** (void)\ static void **initCopyDict** (void)\ static void **addCopy** (const **SoFieldContainer** \*orig, const **SoFieldContainer** \*copy)\ static **SoFieldContainer** \* **checkCopy** (const **SoFieldContainer** \*orig)\ static **SoFieldContainer** \* **findCopy** (const **SoFieldContainer** \*orig, const SbBool copyconnections)\ static void **copyDone** (void)\ Static Public Member Functions inherited from **SoBase** static void **initClass** (void)\ Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system. static **SoType** **getClassTypeId** (void)\ This static method returns the **SoType** object associated with objects of this class. 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 Member Functions virtual **~SoProto** ()\ virtual void **destroy** (void)\ Protected Member Functions inherited from **SoNode** **SoNode** (void)\ virtual **~SoNode** ()\ Protected Member Functions inherited from **SoFieldContainer** **SoFieldContainer** (void)\ virtual **~SoFieldContainer** ()\ Protected Member Functions inherited from **SoBase** **SoBase** (void)\ virtual **~SoBase** ()\ 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 **SoNotRec** **createNotRec** (void)\ ### Additional Inherited Members Public Types inherited from **SoNode** enum **NodeType** { **INVENTOR** = 0x0000, **VRML1** = 0x0001, **VRML2** = 0x0002, **INVENTOR\_1** = 0x0004, **INVENTOR\_2\_0** = 0x0008, **INVENTOR\_2\_1** = 0x0010, **INVENTOR\_2\_5** = 0x0020, **INVENTOR\_2\_6** = 0x0040, **COIN\_1\_0** = 0x0080, **COIN\_2\_0** = 0x0100, **EXTENSION** = 0x0200, **COIN\_2\_2** = 0x0400, **COIN\_2\_3** = 0x0800, **COIN\_2\_4** = 0x1000, **INVENTOR\_5\_0** = 0x2000, **COIN\_2\_5** = 0x4000, **COIN\_3\_0** = 0x8000, **INVENTOR\_6\_0** = 0x10000, **COIN\_4\_0** = 0x20000 }\ Protected Types inherited from **SoBase** enum **BaseFlags** { **IS\_ENGINE** = 0x01, **IS\_GROUP** = 0x02 }\ Static Protected Member Functions inherited from **SoNode** static const **SoFieldData** \*\* **getFieldDataPtr** (void)\ static void **setNextActionMethodIndex** (int index)\ static int **getNextActionMethodIndex** (void)\ static void **incNextActionMethodIndex** (void)\ static void **setCompatibilityTypes** (const **SoType** &nodetype, const uint32\_t bitmask)\ Static Protected Member Functions inherited from **SoBase** static uint32\_t **getCurrentWriteCounter** (void)\ static void **staticDataLock** (void)\ static void **staticDataUnlock** (void)\ Protected Attributes inherited from **SoNode** SbUniqueId **uniqueId**\ Protected Attributes inherited from **SoFieldContainer** SbBool **isBuiltIn**\ Static Protected Attributes inherited from **SoNode** static SbUniqueId **nextUniqueId** = 1\ static int **nextActionMethodIndex** = 0\ ## Detailed Description The **SoProto** class handles PROTO definitions. **SoProto** and **SoProtoInstance** are mostly internal classes. They're designed to read and handle VRML97 PROTOs. However, it's possible to define your PROTOs in C++. You must define your PROTO in a char array, and read that char array using **SoInput::setBuffer()** and **SoDB::readAllVRML()**. Example: ``` char myproto[] = "#VRML V2.0 utf8\n" "PROTO ColorCube [\n" " field SFColor color 1 1 1\n" " field SFVec3f size 1 1 1\n" "]\n" "{\n" " Shape {\n" " appearance Appearance {\n" " material Material {\n" " diffuseColor IS color\n" " }\n" " }\n" " geometry Box { size IS size }\n" " }\n" "}\n" "ColorCube { color 1 0 0 size 2 1 1 }\n"; SoInput in; in.setBuffer(myproto, strlen(myproto)); SoVRMLGroup * protoroot = SoDB::readAllVRML(&in); ``` Now you can create new instances of the ColorCube PROTO using **SoProto::findProto()** and **SoProto::createProtoInstance()**. If you want to insert PROTO instances into your scene graph, you should insert the node returned from **SoProtoInstance::getRootNode()**. See http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.8 for more information about PROTOs in VRML97. ## Constructor & Destructor Documentation ### SoProto::SoProto (const SbBool externproto = FALSE) Constructor. ### SoProto::~SoProto () \[protected\], \[virtual\] Destructor. ## Member Function Documentation ### SoType SoProto::getTypeId (void ) const \[virtual\] Returns the type identification of an object derived from a class inheriting **SoBase**. This is used for runtime 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 predefined 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 top level superclasses for the various class groups. Implements **SoBase**. ### SoProto \* SoProto::findProto (const SbName & name) \[static\] Returns the PROTO definition named *name* or NULL if not found. ### SoProtoInstance \* SoProto::createProtoInstance (void ) Creates an instance of the PROTO. ### void SoProto::addISReference (SoNode \* container, const SbName & fieldname, const SbName & interfacename) Adds an IS reference for this PROTO definition. ### SbName SoProto::findISReference (const SoFieldContainer \* container, const SbName & fieldname) If *container* is a PROTO definition node with an IS interface field named *fieldname*, return the interface name, otherwise return an empty **SbName**. ### void SoProto::addReference (const SbName & name, SoBase \* base) Adds a reference for this PROTO definition. ### void SoProto::removeReference (const SbName & name) Removes a reference for this PROTO definition. ### SoBase \* SoProto::findReference (const SbName & name) const Finds a reference for this PROTO definition. ### void SoProto::addRoute (const SbName & fromnode, const SbName & fromfield, const SbName & tonode, const SbName & tofield) Adds a ROUTE for this PROTO definition. ### SbName SoProto::getProtoName (void ) const Returns the PROTO name. ### SbBool SoProto::readInstance (SoInput \* in, unsigned short flags) \[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 / persistent 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. Reimplemented from **SoNode**. ### void SoProto::write (SoWriteAction \* action) \[virtual\] Action method for **SoWriteAction**. Writes out a node object, and any connected nodes, engines etc, if necessary. Reimplemented from **SoNode**. ### void SoProto::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 from **SoBase**. ## Author Generated automatically by Doxygen for Coin from the source code.