Viz Engine Administrator Guide
Version 5.0 | Published December 20, 2022 ©
External Data Input
Data fed into the Shared Memory (SHM) should be done through the dedicated UDP or TCP IP ports for the SHM. Vizrt provides a set of components, SendToSMM, to makes this task easier.
Note: Go to <Viz Install Directory> > Tools > SendToSMM, for more information about SendToSMM.
Data can also be sent to SHM through a Command Interface. Data sent through the Command Interface may be seen as a good option because the data would need to be sent to one Viz Engine only, and this Viz Engine engine would then distribute the data to the other Viz Engines. But data sent to SHM through the Command Interface has problems:
-
Data sent through the Command Interface blocks the render queue of the receiving engine causing potential frame drops. Since the data needs to be sent through a command significant more bytes are transferred over the network.
-
This Viz Engine is also a single point of failure.
-
The data arrives at this one Viz Engine sooner than on all other Viz Engines.
-
The notification method of the Graphic Hub Manager is used to distribute the data and can cause additional load for the Graphic Hub Manager.
The preferred method to send data is to use the SendToSMM library (or an equivalent) to send the data to the individual Viz Engines.
The communication protocol for the import of Shared Memory data depends on the type and final output of the data. There are set protocols to use with large amounts of data, in which all of the data must reach its destination graphic, and also where large amounts of data must be received quickly, but some loss of data is acceptable.
Note: It is also possible to import data through Multicast. This method is not recommended as it can pollute the network.
This page contains information on the following:
SHM over TCP
The SHM TCP communication protocol guarantees a reliable delivery of packages. It is a much more efficient than the Command Interface, but not as fast as SHM over UDP.
Use cases for a TCP connection could be finance stocks and currencies, or election result information, where the requirement is to deal with large amounts of information, and all of this data must reach its destination graphic. A single piece of lost data can have economic consequences, falsify charts, show mathematically wrong results, etc.
A TCP connection to a Viz Engine can be held open for a long time (this is recommended), and should not be closed and reopened between sending variables.
Note: The default number of connections is 1 and the maximum number of TCP Shared Memory connections is limited to 255. Within this number of connections, a user-defined limit of maximum connections can be set in the configuration file with smm_thread_count.
IMPORTANT! The external program which provides the data, must connect and send the data to each Viz Engine individually. Vizrt provides a C# library, SendToSMM (part of the Viz install), for this purpose.
To Use TCP for SHM
-
Go to the Configuring Viz.
-
Click on Communication.
-
Click on the Shared Memory Properties tab.
-
In the Shared Memory Panel, set TCP Port. There is no specific recommended port. Always make sure that the selected port is not in use by any other program on the same subnet.
-
Click Save.
The syntax for the key-value pairs is:
-
key|value\0
Multiple key-value pairs can be sent, at once, as well. To do this make sure that each pair is terminated with 0.
-
key1|value1\0key2|value2\0key...
SHM over UDP
The SHM UDP communication protocol should be used for the delivery of volatile data. It is quicker than the SHM over TCP protocol, but less reliable, and is much more efficient than the Command Interface.
A use case for UDP would be Motor Sports, where data like speed, velocity, etc., is required. This is where there is a requirement to deal with large amounts of data, but not all of this data must reach its destination. A single piece of lost data does not affect the constant data update.
To Use UDP for SHM
-
Go to the Configuring Viz.
-
Click on Communication.
-
Click on the Shared Memory Properties tab.
-
In the Shared Memory Panel, set UDP Port. There is no specific recommended port. Always make sure that the selected port is not in use by any other program on the same subnet.
-
Click Save.
The syntax for sending key-value pairs is the same as for External Data Input.
Plug-in API
An option to manipulate data in SHM is by a plug-in interface. A use case would be where a TCP or UDP connection can not be used, or is not to be used. It is possible to write a plug-in to import data (for example, from an XML file, another database, etc.) and push it to SHM.
Another use case would be an interactive Scene (see Internal Data (Interactive Scene)).
Note: The Plug-in API documentation is included with the Viz installation (go to Start > All Programs > Viz Artist x.x > Plugin SDK Documentation > Classes > Class List > SHARED_MEMORY).
Command Interface
For small and single value changes the Command Interface of Viz Engine can be used. For example, to update a headline in a Scene.
IMPORTANT! A command operation can block the renderer. If there are too many commands, within a small time, or commands containing a large amount of data, are sent, this can result in not rendering real-time anymore.
Note: Vizrt do not recommend this as a method for data import.
Any external program should consider the performance of the single or all connected Viz Engines. If there is a burst of thousands of SHM variables this can have implications on the Viz Engine rendering performance (Current (CUR) and Maximum (MAX)). A full list of commands is located at <viz install folder>\Documentation\CommandInterface\index.html
Note: From the list of commands, the commands, CLEAR, DELETE_ELEMENT and PURGE_ELEMENT only works when sent through the command interface of Viz Engine.
IMPORTANT! The command CLEAR must be run on each Engine where the MAP is to be reset (VIZ_COMMUNICATION*MAP CLEAR).
Whenever a new entry is made in the map (a new key-value pair) or values are changed, then the change is propagated to the other Viz Engines through a database messaging service to update the local copy of each Viz Engine’s map (this only works when sent over the general communication port of Viz Engine. The default port is 6100).
Command Examples
VIZ_COMMUNICATION*MAP can be used to access the map.
SET_DOUBLE_ELEMENT and GET_DOUBLE_ELEMENTExample: VIZ_COMMUNICATION*MAP SET_DOUBLE_ELEMENT "my_double" 1.2
Example: VIZ_COMMUNICATION*MAP GET_DOUBLE_ELEMENT "my_double"