 |
Coin
4.0.3
Coin3D core library
|
|
Coin
4.0.3
Coin3D core library
|
The SoBaseKit class is the top level superclass for nodekits. More...
#include <Inventor/nodekits/SoBaseKit.h>
Static Protected Member Functions | |
| static const SoNodekitCatalog ** | getClassNodekitCatalogPtr (void) |
| static const SoFieldData ** | getFieldDataPtr (void) |
 Static Protected Member Functions inherited from SoNode | |
| static const SoFieldData ** | getFieldDataPtr (void) |
| static int | getNextActionMethodIndex (void) |
| static void | incNextActionMethodIndex (void) |
| static void | setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask) |
| static void | setNextActionMethodIndex (int index) |
| Static Protected Member Functions inherited from SoBase | |
| static uint32_t | getCurrentWriteCounter (void) |
| static void | staticDataLock (void) |
| static void | staticDataUnlock (void) |
Protected Attributes | |
| SoSFNode | callbackList |
| SoChildList * | children |
| SbBool | connectionsSetUp |
| Protected Attributes inherited from SoNode | |
| SbUniqueId | uniqueId |
| Protected Attributes inherited from SoFieldContainer | |
| SbBool | isBuiltIn |
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 Attributes inherited from SoNode | |
| static int | nextActionMethodIndex = 0 |
| static SbUniqueId | nextUniqueId = 1 |
The SoBaseKit class is the top level superclass for nodekits.
Node kits are collections of nodes and other node kits (from here on node kits which are part of some other node kit, will only be referred to as nodes or parts, see catalogs and parts), organized in a way that is convenient for its use. A node kit inherits SoNode and can thus be inserted into a scene graph as any other node.
The organizing of the nodes and node kits of some node kit, is done through catalogs. A node kit's catalog describes the nodes that can be members of the node kit. These members are called parts. Thus a node kit has a catalog describing the parts that it offers to the user.
Each part in the catalog has some values saying something about the part itself and about the role the part plays in the scene graph. Those values are:
TRUE if the part should be instantiated when the node kit is instantiated, otherwise the part is kept empty until it is set by some of the means applicable. TRUE if the part is a list, otherwise it is FALSE. See SoNodeKitListPart for more info on node kit lists. TRUE if the part should be publicly available, otherwise it holds FALSE. Node kits use lazy instantiation when it creates its parts. This means that the nodes making up the parts of the nodekit only are created when they are needed. If the "Created by default?" holds TRUE, then the part is created when the node kit itself is instantiated. If not, parts are created when they are requested through SoBaseKit::getPart() or the SO_GET_PART() macro, or created with SoBaseKit::set(). Also, if a part is set with SoBaseKit::setPart() or the SO_SET_PART() macro, any previously uncreated parts above the set part in the hierarchy, are created automatically.
The advantages of using node kits to represent a scene graph are many.
The usage of a node kit is straightforward. Below follows a code example showing some simple SoShapeKit usage.
The above code snippet will produce a viewer with a side view to the scene shown below:
Notice that the code needed for creating this simple shape using a shape kit, amounts to this:
..while doing it without shape kits amounts to this:
..so even for this minuscule mock-up example, you save on code verbosity and complexity.
For extending the Coin library with your own classes, we strongly recommend that you make yourself acquainted with the excellent «The Inventor Toolmaker» book (ISBN 0-201-62493-1), which describes the tasks involved in detail. This book was written by the original SGI Inventor designers and explains many of the underlying design ideas, as well as having lots of hands-on examples on how to extend the Coin toolkit in ways that are true to the fundamental design ideas. («The Inventor Toolmaker» is also available at SGI's online library, at no cost. See Download The Inventor Toolmaker.) Reading the source code of the built-in classes in Coin should also prove very helpful.
Following is a complete example of a node kit extension. The node kit is a kit which automatically scales a shape so it will be the same size in screen pixels, no matter which distance it is from the camera. This is useful for marker graphics. The shape defaults to a cube, but can be set by the programmer to any shape or scene subgraph.
The header file:
The source code for the example:
And a complete example showing how one can use this node kit:
| SoBaseKit::SoBaseKit | ( | void | ) |
Constructor.
This is the top-level superclass of all node kit and dragger classes. The catalog structure of SoBaseKit is as follows:
CLASS SoBaseKit -->"this" --> "callbackList"
(See SoBaseKit::printDiagram() for information about the output formatting.)
Detailed information on catalog parts:
CLASS SoBaseKit
PVT "this", SoBaseKit ---
"callbackList", SoNodeKitListPart [ SoCallback, SoEventCallback ]
(See SoBaseKit::printTable() for information about the output formatting.)
As can be seen from the catalog, all node kits can have a callback node in front of all other nodes in the kit. This is handy for catching events that should go to application processing.
|
protectedvirtual |
Destructor.
Add a copy of this node and (recursively) all children to the copy dictionary of SoFieldContainer if this has not already been done.
Used internally during copy operations.
Reimplemented from SoNode.
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 from SoFieldContainer.
|
virtual |
Action method for SoCallbackAction.
Simply updates the state according to how the node behaves for the render action, so the application programmer can use the SoCallbackAction for extracting information about the scene graph.
Reimplemented from SoNode.
Reimplemented in SoDragger.
|
protectedvirtual |
Makes a deep copy of all data of from into this instance, except external scene graph references if copyconnections is FALSE.
This is the method that should be overridden by extension node / engine / dragger / whatever subclasses which need to account for internal data that are not handled automatically.
For copying nodes from application code, you should not invoke this function directly, but rather call the SoNode::copy() function:
The same also goes for engines.
Make sure that when you override the copyContents() method in your extension class that you also make it call upwards to its parent superclass in the inheritance hierarchy, as copyContents() in for instance SoNode and SoFieldContainer does important work. It should go something like this:
Reimplemented from SoNode.
Reimplemented in SoRotateCylindricalDragger, SoRotateSphericalDragger, and SoInteractionKit.
Reference count the write connections to nodes in the catalog.
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
Replaces the createNodekitPartsList() method.
Sets up the list of SoSFNode fields with node pointers to the instances in our catalog.
Not part of the Coin API.
It is supposed to create the SoNodekitParts class instance. Since this class can only be used by SoBaseKit (all members are private, with SoBaseKit as friend), we decided to not support this class, and solve the problem of recording which parts are created in an alternative way.
|
protectedvirtual |
Return path with nested SoNodeKit instances down in the catalog hierarchy given by partname.
If the trailing part has not been made and makeifneeded is TRUE, make an instance of the part type and insert into the catalog, as done in setAnyPart().
If leafcheck is TRUE, ignore non-leaf catalog node entries. If publiccheck is TRUE, ignore private catalog entries.
pathtoextend is a path through the nodekit instance catalog hierarchy, where we should pick up and continue to create the path from where pathtoextend terminates. If pathtoextend is NULL, we simply start at the "this" top level node.
Returns NULL on failure, for any of the possible reasons described above (part ends in non-leaf or private catalog entry, part is not syntactically valid or refers to non-existing catalog entries).
|
virtual |
Calls SoBaseKit::createPathToAnyPart() with leafcheck TRUE, and publiccheck TRUE (and other arguments as given to this function).
See SoBaseKit::createPathToAnyPart() for documentation.
This function performs the typical operation of a node for any action.
Reimplemented from SoNode.
| SbBool SoBaseKit::forceChildDrivenWriteRefs | ( | SoOutput * | out | ) |
Returns TRUE if kit should write. This happens if shouldWrite() returns TRUE, or if any of the children (recursively) should write.
|
protectedvirtual |
Returns catalog part of the given partname.
If the partname part is not in the nodekit's catalog, return NULL.
If the part is specified in the catalog, but has not yet been made, the function will either construct the part (if makeifneeded is TRUE) or just return NULL (if makeifneeded is FALSE).
If leafcheck is TRUE, a pointer to the part will only be returned if it is a leaf in the catalog (otherwise NULL is returned).
If publiccheck is TRUE, a pointer to the part will only be returned if it is a public catalog part (otherwise NULL is returned).
The partname input argument should be given as a "path" of catalog part names down to the wanted leaf part. The syntax for specifying partname "paths" is as follows (given in Backus-Naur Form (BNF)):
BNF:
partname = singlename | compoundname
compoundname = singlename | compoundname.singlename
singlename = singlepartname | singlelistelementname
singlelistelementname = singlelistname[idx]
singlepartname is name of a part ("ordinary", nodekit or list)
singlelistname is name of a part which is a list
idx is an integer value
|
virtual |
Action method for the SoGetBoundingBoxAction.
Calculates bounding box and center coordinates for node and modifies the values of the action to encompass the bounding box for this node and to shift the center point for the scene more towards the one for this node.
Nodes influencing how geometry nodes calculate their bounding box also override this method to change the relevant state variables.
Reimplemented from SoNode.
Reimplemented in SoCenterballDragger, and SoDragger.
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
|
virtual |
Returns list of children for this node.
Reimplemented from SoNode.
|
static |
Returns the nodekit catalog which defines the layout of this class' kit.
|
staticprotected |
Returns the pointer to the pointer of the nodekit catalog for this class.
This static method returns the SoType object associated with objects of this class.
|
protected |
Returns a pointer to the group node above an SoNodeKitListPart in the catalog given by listname.
If the list part (and its container) was not yet constructed, they will be so if makeifneeded is TRUE (otherwise, NULL will be returned).
|
protectedvirtual |
Returns a pointer to the class-wide field data storage object for this instance. If no fields are present, returns NULL.
Reimplemented from SoFieldContainer.
Reimplemented in SoForeignFileKit, SoSTLFileKit, SoNodeVisualize, SoProfilerOverlayKit, SoProfilerTopKit, SoProfilerVisualizeKit, SoScrollingGraphKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger, SoAppearanceKit, SoCameraKit, SoInteractionKit, SoLightKit, SoSceneKit, SoSeparatorKit, SoShapeKit, and SoWrapperKit.
|
staticprotected |
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
Returns the SoFieldData class which holds information about fields in this node.
|
virtual |
Action method for SoGetMatrixAction.
Updates action by accumulating with the transformation matrix of this node (if any).
Reimplemented from SoNode.
Reimplemented in SoCenterballDragger, and SoDragger.
|
virtual |
Returns the nodekit catalog which defines the layout of this class' kit.
Reimplemented in SoForeignFileKit, SoSTLFileKit, SoNodeVisualize, SoProfilerOverlayKit, SoProfilerTopKit, SoProfilerVisualizeKit, SoScrollingGraphKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger, SoAppearanceKit, SoCameraKit, SoInteractionKit, SoLightKit, SoSceneKit, SoSeparatorKit, SoShapeKit, and SoWrapperKit.
|
protected |
In Open Inventor, this method returns a pointer to a private class. It will always return NULL in Coin.
Returns a pointer to the node part with partname.
This method calls SoBaseKit::getAnyPart() with leafcheck and publiccheck both set to TRUE.
See the documentation of SoBaseKit::getAnyPart() for information on how to use partname and makeifneeded, and what you can expect to get returned from this method.
Returns the full path name to a catalog part, given the part's current item pointer.
|
virtual |
Action method for the SoGetPrimitiveCountAction.
Calculates the number of triangle, line segment and point primitives for the node and adds these to the counters of the action.
Nodes influencing how geometry nodes calculate their primitive count also override this method to change the relevant state variables.
Reimplemented from SoNode.
Reimplemented in SoDragger.
Returns the type identification of an object derived from a class inheriting SoBase. This is used for runtime type checking and "downward" casting.
Implements SoBase.
Reimplemented in SoForeignFileKit, SoSTLFileKit, SoNodeVisualize, SoProfilerOverlayKit, SoProfilerTopKit, SoProfilerVisualizeKit, SoScrollingGraphKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger, SoAppearanceKit, SoCameraKit, SoInteractionKit, SoLightKit, SoSceneKit, SoSeparatorKit, SoShapeKit, and SoWrapperKit.
|
virtual |
Action method for the SoGLRenderAction.
This is called during rendering traversals. Nodes influencing the rendering state in any way or want to throw geometry primitives at OpenGL override this method.
Reimplemented from SoNode.
Reimplemented in SoDragger, and SoTabPlaneDragger.
|
virtual |
Action method for SoHandleEventAction.
Inspects the event data from action, and processes it if it is something which this node should react to.
Nodes influencing relevant state variables for how event handling is done also override this method.
Reimplemented from SoNode.
Reimplemented in SoNodeVisualize, and SoDragger.
|
static |
Returns the value of the flag indicating whether or not the kit parts are searched during SoSearchAction traversal.
Print out the full nodekit catalog structure. Just invokes SoBaseKit::printSubDiagram() on the catalog root. Useful for debugging.
Example output:
CLASS SoWrapperKit
-->"this"
"callbackList"
"topSeparator"
"pickStyle"
"appearance"
"units"
"transform"
"texture2Transform"
"childList"
--> "localTransform"
--> "contents"
The arrows denote new entries in the catalog for the particular class versus its superclass. (Apart from the root entry, of course.)
For a more detailed catalog dump, see SoBaseKit::printTable().
Print out the nodekit catalog structure from rootname and downwards in the catalog tree, with indentation starting at level.
Write the complete nodekit catalog in table form.
Example output:
CLASS SoWrapperKit
PVT "this", SoWrapperKit ---
"callbackList", SoNodeKitListPart [ SoCallback, SoEventCallback ]
PVT "topSeparator", SoSeparator ---
"pickStyle", SoPickStyle ---
"appearance", SoAppearanceKit ---
"units", SoUnits ---
"transform", SoTransform ---
"texture2Transform", SoTexture2Transform ---
"childList", SoNodeKitListPart [ SoShapeKit, SoSeparatorKit ]
"localTransform", SoTransform ---
"contents", SoSeparator ---
PVT denotes that it is a private entry in the catalog, then follows the part name and the part type. If the part is a list, the allowed node types for the list is given in square brackets, and if not there's a triple hyphen. If the part type is abstract, the default part type will be listed last (not shown in the example output above).
|
virtual |
Action method for SoRayPickAction.
Checks the ray specification of the action and tests for intersection with the data of the node.
Nodes influencing relevant state variables for how picking is done also override this method.
Reimplemented from SoNode.
Reimplemented in SoDragger.
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.
Reimplemented in SoInteractionKit.
|
virtual |
Action method for SoSearchAction.
Compares the search criteria from the action to see if this node is a match. Searching is done by matching up all criteria set up in the SoSearchAction – if any of the requested criteria is a miss, the search is not deemed successful for the node.
Reimplemented from SoNode.
Reimplemented in SoDragger.
| SbBool SoBaseKit::set | ( | const char * | namevaluepairliststring | ) |
Sets nodekit part field values. The input argument string is of the format:
(Whitespace layout is ignored, as always for Inventor format input strings.)
Here's an example, changing several values of the camera part of an SoCameraKit instance:
This just overloads the other SoBaseKit::set() method, and provides a way to set a part value by using a separate input argument for the name of the part and the name of the field (i.e. parameter) settings.
|
protectedvirtual |
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
(Be aware that this method is unlikely to be of interest to the application programmer who does not want to extend the library with new custom nodekits or draggers. If you indeed are writing extensions, see the information in the SoBaseKit class documentation.)
This is a virtual method, and the code in it should call SoField::setDefault() with argument TRUE on part fields that should not be written upon scene graph export operations.
This is typically done when:
field value is NULL and part is NULL by default
it is a leaf SoGroup or SoSeparator node with no children
it is a leaf listpart with no children and an SoGroup or SoSeparator container
it is a non-leaf part and it is of SoGroup type and all fields are at their default values
Subclasses should usually override this to do additional settings for new member fields. From the subclass, do remember to call "upwards" to your superclass' setDefaultOnNonWritingFields() method.
Reimplemented in SoInteractionKit, SoCenterballDragger, SoDirectionalLightDragger, SoDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoSeparatorKit, and SoShapeKit.
Sets parts, updates nodekit scene graph, and makes sure graph is valid with respect to right siblings and parent. This method is virtual to enable subclasses to detect when a part changes value.
This method is not part of the original SGI Open Inventor API, but is an extension specific to Coin.
Reimplemented in SoInteractionKit.
Sets the catalog part given by partname to the from node pointer.
Reimplemented in SoInteractionKit.
Set whether or not the kit parts should be searched during SoSearchAction traversal. The default value is FALSE.
|
protectedvirtual |
Sets up all internal connections for instances of this class.
(This method will usually not be of interest to the application programmer, unless you want to extend the library with new custom nodekits or dragger classes. If so, see the SoBaseKit class documentation.)
Reimplemented in SoCenterballDragger, SoDirectionalLightDragger, SoDragPointDragger, SoHandleBoxDragger, SoJackDragger, SoPointLightDragger, SoRotateCylindricalDragger, SoRotateDiscDragger, SoRotateSphericalDragger, SoScale1Dragger, SoScale2Dragger, SoScale2UniformDragger, SoScaleUniformDragger, SoSpotLightDragger, SoTabBoxDragger, SoTabPlaneDragger, SoTrackballDragger, SoTransformBoxDragger, SoTransformerDragger, SoTranslate1Dragger, SoTranslate2Dragger, SoInteractionKit, and SoSeparatorKit.
|
virtual |
Action method for SoWriteAction.
Writes out a node object, and any connected nodes, engines etc, if necessary.
Reimplemented from SoNode.
Reimplemented in SoDragger.
|
protected |
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
|
protected |
This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
1.10.0