8.4 - DI-Guy Author Programming Reference

Table of Contents

• 8.4.1 DI-Guy Author Interface Class
• 8.4.2 3D Visual Classes
  • 8.4.2.1 Visual Materials
  • 8.4.2.2 Multiline Visuals
  • 8.4.2.3 Waypoint Visuals
  • 8.4.2.4 Object Handle Visuals
  • 8.4.2.5 Region Mesh Visuals
  • 8.4.2.6 Region Paintbrush Visuals

In addition to the information here, there is a substantial amount of documentation in the DI-Guy source code.

Most functions in the C++ header files have documentation comments with them. While doing the integration you will likely be referring to the source code documentation often.

In addition, there is an OpenSceneGraph (OSG) based example IG implementation, with source code, to provide concrete examples of how the various functions should be called and classes written. You will probably copy the provided example classes and replace the OSG code with code specific to your 3D environment.

The classes provided by DI-Guy can be broken into two groups: classes for interchanging information between your IG and Author, and classes for rendering 3D editing visuals.

8.4.1 DI-Guy Author Interface Class

The class diguyAuthorInterface is the primary way you send and receive information to and from DI-Guy. Its functions can be categorized into the following groups:

• Mouse functions. These functions are called by you from the IG when Author editing is enabled. They provide DI-Guy with the 3D window input such as mouse moves and mouse button clicks it needs for editing the scenario.
• Keyboard function. Similar to mouse functions, but for keystrokes.
• Selected object functions. These functions are called by you from the IG when Author editing is enabled. They tell DI-Guy which object was selected in the 3D window.
• Terrain and intersection virtual functions. These functions are called by DI-Guy when it needs information from the IG about the environment. This includes altitude at a point, converting screen to world coordinates and back, requests to update selected objects, and functions DI-Guy needs for generating its navigation mesh.
• Author UI functions. These functions can be called by you from the IG. They provide control for when the Author UI is launched and request that specific Author UI windows are shown and hidden.
• Author UI status update virtual functions. These functions are called by DI-Guy when the status of various parts of the Author UI application change. This gives the IG a chance to update its state on what is happening with the Author UI, such as enabling or disabling various native user interface controls when a window is opened or closed.

8.4.2 3D Visual Classes

The API has classes that provide the IG with the information and infrastructure needed to render 3D editing visuals. These must be subclassed by you so you can do things appropriate to your IG. As with the DI-Guy Graphics API, you must register functions for creating instances of your subclasses when DI-Guy needs an object pointer to the base class.

    \note These are suggested visual representations of editing visuals. If, for example, you would prefer different colors for editing visuals, you are free to ignore the colors specified by the visual’s material. If you would prefer different geometry altogether for waypoints, for example, a textured disc on the ground – you are free to ignore the polygons suggested in the reference implementation.

Most of the geometry visual classes follow the same template, one similar the DI-Guy Graphics API classes. Each of them has most of the following functions:

• constructor. Called when a new instance of the visual is needed. For example, if a new path is added to the scenario, a new multiline visual will be created. Geometry should not be generated until build() is called.
• build(). Called when the geometry for the visual should be generated. It is common for build() and update() to use a shared utility function for creating polygons, and so on. In the reference implementation this function is called update_geometry().
• unbuild(). Called when geometry created by build() should be freed. This is usually, but not always, when the visual is being destroyed.

• update(). Called when the geometry for the visual needs to be updated in some way. This can be because the overall lines or polygons need to be created or recreated, the position of the visual has changed, or the material has changed. It is common for build() and update() to use a shared utility function for creating polygons, and so on.

• draw(). Called when the visual should be drawn in the scene. This is usually not necessary for scene-graph style renderers, as they handle drawing themselves.
• show(). Called when the visual should be shown, typically by attaching it to a scene graph or updating a scene graph switch node.
• hide(). Opposite of show().

8.4.2.1 Visual Materials

Author visual materials are used to specify basic color and other associated information suggested for rendering Author editing visuals. They specify pen color (used for drawing lines), brush color (used for filling polygons), line width, and so on.

Author visuals in general require less information than full DI-Guy Graphics API materials as stored in diguyGraphicsMaterial objects. Because of this a "light-weight" class is used that contains only basic information. All Author visuals provide a pointer to an Author visual material.

The class diguyAuthorMaterial is used for accessing material information.

8.4.2.2 Multiline Visuals

Author multiline visuals are used to render path splines. They are a collection of line segments connected end to end. They should be rendered using the visual material’s pen color. As paths become selected and unselected the color of the pen changes.

The class diguyAuthorVisualMultiline is used for accessing multiline visual information.

8.4.2.3 Waypoint Visuals

Author waypoint visuals are used to render path waypoints. Each waypoint is a collection of polygonal solids that show the waypoint’s position and orientation. They should be rendered using the visual material’s brush color. As waypoints become selected and unselected the color of the brush changes.

The class diguyAuthorVisualWaypoint is used for accessing waypoint visual information.

8.4.2.4 Object Handle Visuals

Author object handle visuals are used to render various simple objects that need only a position and orientation. These include path beads, character selection discs, and terrain point pickers. The object handles specify the basic shape the handle should have (disc, sphere, cone, and so on) and the radii, height and other measurements for these shapes. The colors of the object handles are usually dependent on their role.

The class diguyAuthorVisualObjectHandle is used for accessing object handle visual information.

8.4.2.5 Region Mesh Visuals

Author region mesh visuals render the meshes needed for showing the bounds and contents of crowd regions and general regions. They contain the line segments that outline the region boundaries, and the polygons that make up the region interior. In general, the materials for regions are translucent so that stacked regions can be represented.

The class diguyAuthorVisualRegionMesh is used for accessing region mesh visual information.

8.4.2.6 Region Paintbrush Visuals

The Author paintbrush represents the spherical volume that shows where region painting will occur in certain Author input modes. The material for the paintbrush is translucent so that the terrain inside the brush can be seen.

The class diguyAuthorVisualRegionPaintbrush is used for accessing paintbrush visual information

[<< IG Integration] [Home] [Top of Page]