4.3 - Generating Code for Agents

Table of Contents

• 4.3.1 The Object Class Definition
• 4.3.2 Distributed Code Generator Limitations
• 4.3.3 Starting the Distributed Code Generator
• 4.3.4 Creating an Object Class Definition
• 4.3.5 Building Agent Classes
  • 4.3.5.1 Building Agent Classes in the Distributed Code Generator GUI
  • 4.3.5.2 Building Agent Classes in Your IDE
• 4.3.6 Distributed Code Generator Command-Line Arguments

Every object needs an agent to manage its creation on the master display engine and external display engines.

Since the generic functioning of agents is the same regardless of the object, it is possible to automate the process of creating them. VR-Forces includes a tool, the Distributed Code Generator, that generates source code for agent classes from object classes so that they can be easily integrated into drivers.

The Distributed Code Generator generates an agent class, an agent implementation class, a definition class, and a creator class. Most of the time, you will only need to know about the agent class. However, the following is a brief description of all of the generated classes:

• The agent class is an abstract class that allows the agent to be completely independent of the dependencies of the object class
• The agent implementation class implements the agent functions and must have access to the object class
• The definition class stores the data regarding the agent functions to ensure that they are properly forwarded
• The creator class is used by the drivers and distributed object manager to create these classes.

The exampleDistributedObject example has generated agent classes. Please see exampleDistributedObject for a description of the object class, generating agent classes, and adding the agent to a driver.

4.3.1 The Object Class Definition

The Distributed Code Generator generates code based on the information in an object class definition (OCD). An OCD contains all the information the Distributed Code Generator needs to generate the agent classes, such as the object class name, namespace, functions, and comments. The functions that the agent will have are called distributed functions, because these function calls will be distributed to objects in display engines.

You create an OCD in the Distributed Code Generator's graphical user interface. You save the OCD in an object class definition file (extension .ocdx).

Once you create the OCD, you can build the classes from the Distributed Code Generator's GUI, from the command-line, or from within Visual Studio.

4.3.2 Distributed Code Generator Limitations

The Distributed Code Generator has the following limitations:

• Only methods that return void are supported. The agents on the master display engine always send commands to the external display engines. The external display engines do not send anything back. Therefore, no methods on agents can ever return anything.
• Agents do not have member values. All they do is forward function calls to the actual object.

4.3.3 Starting the Distributed Code Generator

You can start the Distributed Code Generator from the command line. For details, please see 4.3.6 Distributed Code Generator Command-Line Arguments. On Windows, you can also start it from the Start menu.

4.3.4 Creating an Object Class Definition

To see an example of an object class definition, load ./examples/exampleDistributedObject/DtExampleObject.ocdx.

To create an object class definition:

1. Run ./bin/dcgen.exe. The Distributed Code Generator opens.
2. Choose Files -> New.
3. In the Object Class group box, Name text box, type the name of the object class.
4. Type the namespace that the class is in.
5. Type the name of the header file for the object class.
6. Specify the agent functions. For each function:
   1. In the Functions group box, click New. The cursor jumps to the Name column and an empty signature is added.
   2. Type the function name in the name column.
   3. In the Function Arguments group box, click New. The cursor jumps to the Type column.
   4. Type the type of the argument.
   5. Double click the Name field. It becomes editable.
   6. Type the name of the argument.
   7. Type comments for the function in the Function C++ Comments text box.
7. Optionally, complete other fields in the form.
8. Choose Files -> Save. The Save Class File dialog box opens.

9. Navigate to the location where you want to save the OCD file.

   Note

   We recommend that you create a directory for your OCD files, for example, myProject/Object Class Definitions. Then create a subdirectory called generated to store the files generated by the Distributed Code Generator.

10. Type a name for the file.
11. Click Save.

4.3.5 Building Agent Classes

You can build agent classes from the Distributed Code Generator GUI, from the command-line, or as part of your build process using Microsoft Visual Studio. For command-line arguments, please see 4.3.6 Distributed Code Generator Command-Line Arguments.

4.3.5.1 Building Agent Classes in the Distributed Code Generator GUI

To build agent classes from the Distributed Code Generator GUI:

1. Create an object class definition (as described in 4.3.4 Creating an Object Class Definition) or load a previously created OCD.
2. Choose Build -> Set Output Directory. A directory chooser dialog box opens.
3. Select the directory in which the Distributed Code Generator should put the generated source code.
4. Click OK.
5. Choose Build -> Generate Files.

4.3.5.2 Building Agent Classes in Your IDE

You can integrate creation of agent classes into your build process. This is the recommended way to generate these classes.

Note

This example code in this section procedure is from the exampleDistributedObject example. It assumes that you have created an OCD and saved it to DtExampleObject.ocdx and created a directory called exampleDistributedObject.

To generate the agent files using Microsoft Visual Studio:

1. Right click on the .ocdx file in the Solution Explorer and examine its Custom Build Step in its properties. It will look something like this:

   Outputs:
   $(InputDir)$(InputName)Agent.hpp;$(InputDir)$(InputName)Agent.cpp
   $(InputDir)$(InputName)Classes.hpp;$(InputDir)$(InputName)Classes.cpp
   Additional Dependencies: ..\..\bin\sceneObjectCompilerd.exe
   Command Line: ..\..\bin\sceneObjectCompilerd.exe "$(InputPath)" -a -S "$(InputDir)/" -H "$(InputDir)/" -A "../../include"

2. Compile just the DtExampleObject.ocdx file (right click on it and click compile). This generates the following files in the exampleDistributedObject directory:
   • DtExampleObjectClasses.cpp
   • DtExampleObjectClasses.hpp
   • DtExampleObjectAgent.cpp
   • DtExampleObjectAgent.hpp.
3. Add those files to the generated folder.
4. Right click on the generated folder and click add existing item.
5. Select those files and add them.

4.3.6 Distributed Code Generator Command-Line Arguments

You can run the Distributed Code Generator from the command line if you have an object class definition file to input to it. The syntax is:

dcgend.exe input_file [{-i | -a | -p} -A root_dir -H header_dir -S source_dir -o output_dir -- -v -h]

The following table describes the command line arguments.

Distributed Code Generator Command-line Arguments
Argument	Description
input_file	The Object Class Definition file to process.
(-i | –generateImplementation)	Generate all of the implementation classes.
(-a | –generateAll)	Generate all of the classes.
(-p | –generateAgent)	Generate only the abstract driver class.
(-A | –RelativeIncludeDirectory) root_dir	The root directory that generated include statements are relative to.
(-H | –HeaderOutputDirectory) header_dir	The directory to write header files to.
(-S | –SourceOutputDirectory) source_dir	The directory to write source files to.
(-o | –OutputDirectory) output_dir	The directory to write all files to.
(-v | –version)	Display version information and exit.
(-h | –help)	Display usage information and exit.
(– | –ignore_rest)	Ignore all command-line arguments after this one.

Suppose that you are generating the file testAgent.hpp in the /productRoot/include/test/ directory. However, you want the include statement to look like:

#include <test/testAgent.hpp>

and NOT

#include <testAgent.hpp>

Use the arguments -H /productRoot/include/test -A /productRoot/include to specify the header location and relative include path.

[<< Distributed Rendering] [Home] [Top of Page] [Observers >>]