 |
DI-Guy SDK Documentation
13.7.1
|
|
DI-Guy SDK Documentation
13.7.1
|
The DI-Guy Graphics API classifies renderers into two types: immediate mode and scene graph. The type of renderer has a large impact on which DI-Guy Graphics API classes are subclassed, and which virtual functions of those subclasses the user overrides.
Immediate mode renderers expect the user's code to perform transformations, bind materials and textures, and draw geometry at the appropriate times during the rendering of each frame. A primary example of an immediate mode renderer is OpenGL.
The most important stages in implementing DI-Guy support for an immediate mode renderer are the Build Stage and the Draw Stage. During the Build Stage renderer-specific objects may be created from the meshes, materials, and textures to facilitate later draws. During each Draw Stage calls are made to bind materials and textures, and transform and draw the objects.
The following classes are usually subclassed for immediate mode renderers:
Scene graph renderers typically build a hierarchy of graphical objects. The scene graph renderer automatically takes care of transformations, binding materials and textures, and drawing geometry. Examples of scene graph renderers are OpenSceneGraph and Vega Prime.
The most important stages in implementing DI-Guy support for a scene graph renderer are Build Stage and Update Stage. During the Build Stage all geometry, materials, and textures and turned into renderer-specific objects and inserted in the scene graph. During the Update Stage the scene graph objects are updated with new information based on DI-Guy motion data.
The following classes are usually subclassed for scene graph renderers:
DI-Guy comes with a built-in geometry file loader that is used for some graphics environments (for example, OpenGL, DirectX, and DI-Guy Graphics API), and makes use of native file loaders in graphics environments that provide them (for example, Vega Prime). The DI-Guy Loader can load and parse various types of files, most notably OpenFlight (.flt) and Collada (.dae) files for object geometry, and a selection of various texture file types. The DI-Guy Loader correctly loads the human character geometry files provided in a DI-Guy Data distribution.
Unlike the main DI-Guy API, which makes extensive use of callback functions to notify the user's application of events, the DI-Guy Graphics API makes use of virtual functions in C++ classes. Each class has a set of virtual functions that can be overridden in a user-defined subclass. At appropriate times during program execution these virtual functions will be called by the DI-Guy Graphics API.
The virtual functions are called at specific stages of program execution. These stages are the Build Stage, the Update Stage, the Draw Stage, and the Unbuild Stage.
Build Stage functions are typically called during program initialization, when geometry files are being read and the information therein being turned into renderer-specific objects. Build functions may also be called during program main loop execution if new characters or appearances that haven't been preloaded are called upon.
The Build Stage is very important for both scene graph and immediate mode renderers.
Update Stage functions are called during program main loop execution, when the state of objects should be modified based on motion data from DI-Guy. Most often this means updating degree-of-freedom (DOF) type objects in a scene graph with new joint angles, but may also include showing or hiding objects.
The Update Stage is very important for scene graph renderers.
Draw Stage functions are also called during program main loop execution, when it is time for objects to be rendered. Though they do not contain any visible geometry themselves, link objects "draw" themselves by applying updated transformation state to the renderer. Similarly, materials and textures have bind functions that are called during the Draw Stage.
The Draw Stage is very important for immediate mode renderers.
Unbuild Stage functions are typically called during program shutdown. They are responsible to freeing any renderer-specific resources that may have been allocated during the Build Stage.
The Unbuild Stage is very important for both scene graph and immediate mode renderers.
During the function calls of the various stages listed above, the user obtains information by calling "accessor" functions.
A diguyGraphicsLink subclass object, for example, can determine which link is its parent (the link it is attached to in the link hierarchy), and which links are its children (the links that are attached to it) by calling the functions get_parent_link() and get_child_link_at_index(), respectively.
A diguyGraphicsTexture subclass object can call the function get_texture_map_data(), which returns a buffer containing the RGB data for the texture which can then be used to define a renderer-specific texture object.
The DI-Guy Graphics API is responsible for creating and destroying all objects; the new and delete operators should not be called on DI-Graphics API classes or subclasses. In fact, the constructors and destructors of the classes are all protected, so compilers should refuse to compile code that breaks this rule.
In order to create subclass objects, object creation functions can be registered with the DI-Guy Graphics API. These create functions will be called whenever the API needs to allocate a new object, allowing the user to allocate and return a subclass of the object specialized for a specific renderer. The create functions should be registered before the initialization function discussed below is called.
Note that renderer-specific objects typically should not be created in the subclass constructor, but should instead be created in the Build Stage. Objects are typically created before their data has been fully read by the loader, with the consequence that the accessor functions cannot yet return valid data.
To make use of the DI-Guy Graphics API for rendering instead of one of DI-Guy's built-in renderers, a different initialization function must be called. Instead of calling diguy_ogl_initialize() to make use of the built-in OpenGL renderer, for example, a program using the DI-Guy Graphics API would call diguy_graphics_initialize(). Similarly, instead of including the header file diguy_graphics_ogl.h, the DI-Guy Graphics API program would include diguy_graphics_api.h.
The base link of a DI-Guy character's graphics hierarchy can be retrieved using the function diguyCharacter::get_base_link(). Once the base link has been retrieved, function calls to the base link can retrieve pointers to child links and shapes attached to links.
A pointer to the character to which a link or shape belongs can be retrieved using the functions diguyGraphicsLink::get_character() and diguyGraphicsShape::get_character(), respectively.
All other DI-Guy Graphics API types are shared among multiple characters, so there is no single character to which they belong and therefore no get_character() function.
[<< Types Overview] [Home] [Top of Page] [Programming Examples >>]
1.8.9.1 
