Vortex Studio SDK Introduction

Owned by Marc Lievin
Sept 10, 2024
4 min read

Vortex® Studio SDK is designed to simulate content created inside the Vortex Studio Editor. It can either run stand-alone or integrate within your existing framework.

Summary

The Vortex SDK exposes the following features.

C++ SDK

  • File-based configurable application.

  • Four primary content objects: scene, mechanisms, assemblies, and extensions.

  • Setup file creation and manipulation

  • Extensibility through application modules and content extension.

  • Data connection to build content logic and easily combine functionalities.

  • Versioning and serialization of all objects.

  • Several APIs available to the user to build modules and extensions.

  • Create different roles in a simulation (e.g. Tank Driver and Gunner, Crane operator and Signaler…) by assigning extensions (e.g. Camera, Audio Listener, Devices…) to each. Dynamically associate Roles to Seat (hardware setup) during simulation.

  • Set Metrics to be recorded during a simulation.

  • Create key-frame for taking snapshot of the simulation at any given time that can be persisted on disk and restored on the same content at any time.

  • Record and Playback: Record, play back, recorded kinematic information generated by Vortex Studio (dynamics, extensions, etc.) to file.

  • Convert external terrain into collision geometry meshes using the Vortex C++ Terrain API. Dynamically load terrain tiles or streamed terrain for best performance.

Python Scripting

  • Vortex Studio both extends and embeds Python.

  • A part of the Vortex Studio API is exposed as a set of Python objects and functions.

  • Python extension makes it possible to create a custom Vortex Studio simulation using nothing but Python as a programming language.

  • Embedded Dynamics Python is a Vortex Studio plugin that allows any Vortex application to execute dynamics operations as scripts.

Vortex Architecture

Vortex Toolkit is based on the separation between content and application patterns. The application is fixed for a particular simulator, but it can load different content. As a rule of thumb, the application is created by developers and integrators, while content is created by mechanical engineers and level designers.

Content Representation

Content can be created and accessed through the Vortex SDK. All objects and extensions derive from IExtension and other specific interfaces, e.g., IDynamics for dynamics objects, IGraphic for graphics objects.

The scene is the root of the content; it is a container for mechanisms and assemblies. The scene can have one or more extensions, and can consist of, for example, a digging area with vehicles.

 

Vortex Content Model

A mechanism is defined by Mechanism and is the main dynamics object with Vortex. It is the representation of such real-life objects as shovel bodies and shovel buckets. It is made up of assemblies, which are an amalgamation of parts, and constraints. Each mechanism can have one or more extensions.

Extensions are additional functionalities attached to a mechanism or scene. They extend the functionalities of their parents.

 

Relation Between Content and Application

Now that you understand the components that make up the content model and the application model, you can see how they interact with each other and their relationships.

The content model is comprised of the scene and one or more mechanisms, along with the scene's and the mechanism's extensions. VxApplication and the modules are designed for consuming each of the extension types.

 

Content and Application Models

Vortex Runtime Model

Application Object

The application (class VxApplication) is the central object that makes the simulation run. That is, it is the interface for the different executables connecting with Vortex.

The application contains simulator modules (class ISimulatorModule). At each application update, all modules are updated. Each module powers one aspect of the simulation, e.g., dynamics, graphics, sound, device.

A simulator usually has a fairly fixed set of modules, and they are generally closely related to the hardware.

The application also has extensions that are specific for a particular application, e.g., network, user interface, special graphic display.

An application without content is running empty; content is what populates the simulated world. The main objects in the content are the scene (class VxContent::Scene) and the mechanism (class VxDynamics::Mechanism). Both objects are containers for other objects, and their purpose is defined by the extensions they contain.

There can only be one instance of the VxApplication class per operating system process. Additionally, in a given process's lifetime, a VxApplication instance should not be destroyed and replaced by a new instance. Proper cleanup of all its internal components and public add-ons is not guaranteed.

Modules and Extensions

The extension/module pattern is a consequence of the separation between application and content. An extension's job is related to a specific aspect of the simulation, e.g., dynamics, graphics, user interface, specific hardware, 3rd party SDK.

Each aspect is managed by a module, and implemented with an instance of ISimulatorModule. When content extensions are put in the application, each ISimulatorModule receives each IExtension and checks whether it should manage it.

For example, the graphics module interfaces with the graphics engine. It takes the information it receives from the IGraphic extensions in the content and sends it to the graphics driver for rendering at runtime.

Note An extension requires a module to be active in the simulation; it is called 'managed'. If you are creating a new basic interface for a new feature, you need to create an ISimulatorModule that manages the extensions that will manage those interfaces.

Modern C++

Vortex follows several principles and features of modern C++ and is using C++ 11 as much as possible on the supported platforms.

  • First class objects support smart pointers.

  • nullptr usage is encouraged.

  • Vortex containers follow standard library iterators.

  • Standard library is used as much as possible.

Thread Safety

Please refer to the following page for more information about multiple threads usage in Vortex and thread safety.

Vortex Studio SDK Advanced - Threading And Synchronisation

SDK Tutorials

See C++ Tutorials and Python Tutorials.