Vortex Studio SDK Advanced - Events
Introduction
Events Usage
In Vortex, data is passed via connections from one content extension to the other.
Communication between modules across a distributed simulation cannot be accomplished with connections, but by using events.
Events are packets of data tagged with a unique id, that is sent from a sender to all of its listeners, across the simulator's nodes.
Events could be used, for example, to launch actions to be executed on a remote node, e.g. save a file locally.
Events Properties
- Events should be punctual, they are not meant to be sent every frames.
- Events are asynchronous; there is no way to accurately predict how much frames will pass between sending the events and receiving the data.
- Events are not synchronized to be sent at the same frame on each node of the simulator
- Event data is sent across the network, avoid sending too much data.
Using Events in your Vortex C++ Application
Creating an EventId
In order to setup events, you need to create an EventId
for your event.
Each EventId
can only be created once via static function EventManager::createdEventId()
They should be kept in a static variable available to both the sender and the listener.
EventId
s are generated from their given names, which must be unique, Duplicated names will result in failure.
Packaging the event's data
Event's data are package using a small helper container called EventData
.
The class stores it's data in a vector of bytes.
The user can use the provided insertion and extraction operators to put data into it.
These operators supports basics numerical values (signed/unsigned integers on 8, 12, 32 and 64 bits, float and double), boolean and strings.
Alternatively, the user can provide the bytes as a vector.
Using the Event Manager
The EventManager
is an object created by the application and available via the ApplicationContext.
The manager is used to create listener and send events.
Creating a listener
The receiver of the data needs to setup a listener.
A listener is a callback function registered to the EventManager
.
To create a listener, the user uses function registerListener()
on the EventManager
by passing the EventId
and the callback, the EventManager
will return an EventListener
.
The EventListener
is a reference counted object; as long as the EventListener
is referenced, the callback will be called when the EventId
is sent.
The listener will be called during the simulation thread with an object EventData
.
To stop receiving the event's data, either call unregister()
on the EventListener
or delete it.
Sending an Event
To send an event, the user first package its data into an EventData
.
Thereafter, the user calls sendEvent()
on the EventManager
, with the EventId
and EventData
.
The event will be send to all of its listeners, across the simulator's nodes.
static const VxSim::EventId kMyEventId = VxSim::EventManager::createEventId("My Event"); ... class MyObjectUsingAListener { EventListener myListener; ... void eventCallback(const VxSim::EventData& data) { int valueA = 0; std::string valueS; data >> valueA >> valueS; processData(valueA, valueS); } ... void setupListener() { myListener = mApp->getContext()->getEventManager()->registerListener(kMyEventId , [this](const VxSim::EventData& data) { this->eventCallback(data); }); } } ... class MyObjectSendingData { int A; std::string S; ... void notify() { EventData data; data << A << S; mApp->getContext()->getEventManager()->sendEvent(kMyEventId , data); } }
Debugging Events
In the Network Data Page of Vortex Studio Player, monitoring and advanced monitoring of the event can be enabled.
The user can track its own events. User defined events name are seen as "User Event:<event name>".