H3D API Training

1. H3D API Training Part 6: C++

2. H3D API • C++ H3D: • Standard Template Library (STL) • C++ design of API • The H3DNodeDatabase • Writing new nodes • Specializing fields • Scene-graph traversal

3. STL • Library of utility templates • http://www.sgi.com/tech/stl/ • vector, string, map, “containers” • sorting • auto_ptr • pair

4. C++ Design • C++ broken down into major components: • Node Database • Field structure • Nodes • Supporting classes

5. Node Database • H3DNodeDatabase • Static array of Nodes available • Updated at runtime (e.g. load DLL) • Allows searching by X3D name or C++ type id • Provides Field database for each Node • Field Database provides • Access type (inputOnly, outputOnly, initializeOnly, inputOutput) • get field instance by string name

6. Creating a new node • Node - base class for all nodes • Creating a new node: • Define all associated fields, and any field types • Define static H3DNodeDatabase entry with X3D field interface • Constructor to initialize fields and set up dependencies.

7. Reference counting • Node instances are reference counted • Nodes removed automatically when reference count is zero • References held by: • MFNode, SFNode • AutoRef

8. Reference counting Wrong way Sphere *sphere = new Sphere; group->children->push_back( sphere ); … delete sphere; Correct way AutoRef< Sphere > sphere( new Sphere ); // reference Sphere *sphere = new Sphere; group->children->push_back( sphere ); // reference

9. The initialize() function • Called once upon first reference to a Node • Used for initialization where the values of initializeOnly fields are required

10. Scenegraph traversal • Each scenegraph loop contains two traversals of the scenegraph. • General traversal. Updating states, adding haptic objects. • Graphic rendering traversal.

11. General traversal • Accomplished through call to:virtual void traverseSG(TraverseInfo &ti ) • Nodes can override this function to access information and adding objects to render haptically.

12. TraverseInfo • Holds information for the current traversal • accumulated transform matrices • active haptics devices and their values • current Surface • Enable/disable haptics. • Add haptic objects to be rendered at haptics devices.

13. Accumulated matrices • getAccumulatedForward() • The transformation matrix from local space of the Node in the scenegraph to global space. • getAccumulatedInverse() • The transformation matrix from global space to the local space of the Node.

14. Graphics traversal • Display lists used for caching OpenGL calls with the DisplayList field. • render() function performs the OpenGL calls. • Events on fields routed to the DisplayList field causes rebuilt of display list.

15. DisplayList • callList() – builds display list if possible, otherwise just runs render() function • bool hasCausedEvent( Field *f ) – true if the field given has generated an event since the last call to update() • GraphicsCachingOptions node • Control caching

16. Specializing fields – C++ • Allowed field types for routes in can be specified. • A field can be specialized to perform any action when updating its value. • Done by specializing the update() function.

17. Specializing fields class H3DAPI_API SFMatrix4f: public TypedField< H3D::SFMatrix4f, Types< SFVec3f, SFRotation, SFVec3f, SFRotation > >{ protected: /// Update the matrix virtual void update(); };

18. Specializing fields void SFMatrix4f::update() { Vec3f c = static_cast< SFVec3f *> (routes_in[0])->getValue(); Rotation r = static_cast< SFRotation *> (routes_in[1])->getValue(); Vec3f s = static_cast< SFVec3f * > (routes_in[2])->getValue(); value = ComputeTransform( c, r, s ); }

19. Example - Sphere Check out source code for Sphere