Vortex Studio Setup User Guide

The Application Setup File

An Application Setup file (.vxc extension) allows you to set up or configure a Vortex® application without doing it all manually in code. It can be passed to an application which will parse it (like the SimApp) and automatically configure itself based on the file's content.

Through the Application Setup file, you can set some global parameters for the application (such as the default log level, the simulation frame rate, the starting application mode) but most importantly you can specify which modules and extensions will need to be created along with the application and on which node. Specifying multiple nodes in an Application Setup file allows a single document to contain the configuration of multiple types of nodes required for a simulator.

Note
In the Vortex Studio Editor, what the SDK calls an "ApplicationConfig" is referred to as an "Application Setup".

Content of the Setup

An Application Setup file can contain the following elements:

Nodes

A node in a simulator represents, at the OS level, a process which will perform some tasks as part of your simulation. A simulator can be composed of a single node (what we call standalone or desktop) or multiple nodes. In the case of multiple nodes, they may not even be on the same physical machine. Whether they are or not, all nodes will use the Vortex network layer to communicate and exchange data between themselves.

Every Vortex simulator needs a master process. In standalone mode, since there is only one non-networked process, it is fairly straightforward. In a network setup, it is a bit more complicated since it is the master node that coordinates the exchange of data with the other nodes (called slaves) and instructs them on what to do. In most cases, the master will contain the dynamics module, while a slave node never will. If one of your nodes contains the dynamics module, it will be designated as the master by the application. A node can also be explicitly set as a master or a slave by settings its parameter "CommunicationModel" to master or slave.

Note
The master node's configuration (or the configuration of the application in standalone mode) almost always contains the DynamicsEngine module. In a multi-node simulator, you must add the NetworkOpenDDS extension to your ApplicationConfig to allow nodes to communicate between each other. Users of past versions of the SDK might remember having to add the VxSim::VxSlaveModule to their slave nodes' configuration. As of Vortex Studio 2017, this is no longer necessary as all that functionality has been integrated directly into the VxApplication.

To define setup nodes, it is important to understand the interactions between the different modules and extensions of the Application Setup file, as well as the hardware configuration of the target computer. The specific association between a node and a target computer is done when defining a simulator in the Vortex Studio Player (Director) application. See Director User Guide for more information.

Modules

As explained in Integrating the Application, modules are a core part of a Vortex application. Modules are not part of the content like the other extensions and objects are. Modules are directly added to the application, either manually through VxSim::VxApplication::insertModule() or by adding them to an ApplicationConfig which is then applied to the VxApplication.

Extensions

A common workflow is to add extensions to an application by embedding them in a content object and loading the object in the application. Though useful in many cases, if you find yourself re-adding extensions to your content which are not directly related to it (for example, an extension handling a user interface or network communication), it is a clear sign that the extension probably belongs inside an ApplicationConfig instead. Extensions that are fundamental to your simulator application regardless of loaded content are good candidates for this.

Parameters

A Vortex application exposes some high level parameters that can be customized from the ApplicationConfig (e.g., frame rate, default log level). Some of these parameters are global while others can be overridden by each node.

Seats

A seat is a configuration of a group of modules and nodes that are meant to be assigned a specific role during the simulation. See Defining Seats in a Setup for more details.

Application Setup Using an Application Setup File

When an Application Setup file is applied to an application, the setup will first add its global modules, then extensions of the global section (first level), as well as its parameters to the application. Then the node-specific modules, extension and parameters are applied. When a parameter is present at both the node and the global level, the node will prevail.

Editing the Application Setup File in the Vortex Studio Editor

An example of an Application Setup file for a simulator is the Vortex Studio Player's own setup file. It is located in the Vortex Studio installation directory: resources\config\player.vxc. When opening this document in the Editor, you can see that the root object is the global setup object. Through the Explorer panel, we can navigate the structure of the Application Setup file. For instance, the setup global parameters can be changed by highlighting the setup object at the root and then changing any parameter in the Properties panel. Nodes will have similar parameters as the setup object, however they are specific to this node.

Under Setup, any extensions, modules and parameters properties can be modified this way; they will globally apply to any setup node. There is also the possibility to define different seats at this level. Seats will refer to modules from nodes that are part of this seat.

On the second level, each node has its own extension, modules and parameters. A node is a specific configuration for a SimApp in the simulation.

Setup Preset Templates

To simplify the creation of a simulator setup, the Editor includes preset templates of nodes, located in the Toolbox under Presets. To use a specific preset in your Application Setup file, drag the preset into the Explorer panel over the Setup.

The standalone application preset template is meant to be used in standalone (single node) setup, however other nodes can be combined by adding one node engine (master) and one or more slave nodes.

The available presets are the following:

• Standalone application
A single node (global) setup where the node has both a dynamics engine and a graphics with a single display. Joystick, recorder, metrics and audio are also included as well support for Earthworks and Human. There is also a seat defined with the Joystick, Graphics and Audio.
• Master with dynamics
A node with a dynamics engine to be used in a distributed setup. The NetworkOpenDDS extension is added to the global setup, if it's not already present as well as other support modules used in a distributed setup.
• Slave with 1 window
A node with the graphics module as well as one display setup. For the engine, other distributed network support extensions and modules are added to the global setup if not already present. Joystick, audio and metrics support are included.
• Slave with 2 windows
A node with the graphics module as well as two display setups. For the engine, other distributed network support extensions and modules are added to the global setup if not already present. Joystick, audio and metrics support are included.
• Slave with no graphics
A template for a slave node meant for purposes other than graphics. For instance, it could be the base template for a dedicated slave meant to run a user module if your simulator includes one or a console (UI) application.

Defining Seats in a Setup

The closest analogy to represent a seat is the seat you are sitting on in the simulator. The operator's seat on the motion platform and the instructor's chair in another room are examples of seats which differ from one another mainly through the hardware that is attached to the seat (screens, motion platform, controllers, etc.). When a role is applied to a seat, only the modules of the seat will manage the extensions of the role, otherwise the extensions will be ignored by the application.

A role is the counterpart to the seat. It represents an actor in the simulation and contains extensions that are only added to the simulation when it is applied to a seat.

For example, consider the development of a tank simulator. The simulator includes room for one student in the operator seat and an instructor in the instructor seat. Inside the simulation however there are at least three different roles: one for the instructor (which may be physically inside the simulation as a Vortex Human), one for the tank driver, and another for the tank gunner. The instructor seat has a standard desktop with mouse and keyboard, perfect to navigate the scene and evaluate what the student does. The operator seat has a motion platform, a steering wheel, pedals and two joysticks. The driver and gunner roles can alternately be applied to the operator seat which contains all the modules to handle the hardware. However, the gunner role does not contain the extension for the steering wheel and the pedals, and inversely the driver role does not contain the joystick extensions. Also both roles may not use the same displays to reflect a different field of view. On the other side, the instructor seat does not have all the hardware modules of the operator and the instructor extensions may include an extension for using a mouse.

To summarize, roles are added to your content directly but seats are part of your Application Setup file since they go with the simulator regardless of the content loaded on top of it.

The concepts of seat and role are important (especially in a multi-node setup) as they provide a way to assign a set of devices employed by a user on a seat to a different role without the need to configure each extension separately.

Preferred Roles

A seat module does not receive a role until one is assigned to it. The role-seat assignment is performed either by specifying the preferred roles directly on the seat (see Creating a Seat below), using the Vortex Studio Player Roles and Seats tab, or programming it (see VxSeat).

Creating a Seat

To create a seat:

1. From the Vortex Studio Home page, click Open. Open the setup file player.vxc; the default location is C:/CM Labs/Vortex Studio X.x/resources/config where X.x is the version number.
2. Select Basics in the Toolbox.
3. Double-click Seat to add a seat to the Explorer panel. Give it an appropriate name via its Properties panel.
4. Select Modules from the Toolbox, and double-click modules that you want to add to seats in order to include them in the Explorer panel.
5. Select the seat in the Explorer panel.
1. In its Properties panel, under Modules, click the + button.
2. Drag the desired module from the Explorer panel into the newly added row.
3. Repeat this process to add more modules if necessary.
6. Select a seat in the Explorer panel.
1. In its Properties panel, under Devices, click the + button.
2. Drag the desired device from the Explorer panel into the newly added row.
3. Repeat this process to add more devices if necessary. (See Tandem Simulators.)
7. In the seat parameters, you can select to automatically apply the first role loaded (Apply First Role checkbox) in the seat or set a list of "preferred roles" in order of preference. Those two options are mutually exclusive: if Apply First Role is set, the Preferred Roles list is ignored. If none of this selection logic is applicable, then a seat can be assigned to a role later by code or using the Vortex Studio Player role and seat interface.
8. If you do want to create a list of preferred roles, press the + button in the Preferred Roles section of the Properties panel to create a list of the roles expected to be in the content of the simulator. The name of each role should be <role owner name>.<role name> (e.g., Tank.Gunner, Tank.Driver, Scene.Instructor).
9. Save the file.

Setup Documents Usage in Director

An Application Setup file is associated with a target computer when creating a simulator in the Director. A simulator can only refer to a single Application Setup file, therefore all nodes of a simulator must be in the same document. Further information about the Director and simulator documents is available in the Director User Guide.