Viz Artist User Guide
Version 5.0 | Published December 20, 2022 ©
External Data Input
Data to Shared Memory should be fed through the dedicated UDP or TCP IP ports for SHM. Vizrt provides a set of development components called SendToSMM to make developing tools for this purpose easier. The component files are included with the standard Viz installation and located at <viz install folder>\Tools\SendToSMM.
Data can also be sent to shared memory through the 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 shared memory 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 is used to distribute the data and can cause additional load for the Graphic Hub.
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.
For use-cases, see:
Note: It is also possible to import data through Multicast. This method is not recommended as it can pollute the network.
TCP Protocol
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 the UDP Protocol. 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 opened and closed 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 config file with smm_thread_count (see To Limit the Number of TCP Connections in the Configuring Viz section of the Viz Engine Administrator Guide).
IMPORTANT! The external program which provides the data, must connect and send the data to each Viz Engine individually. Vizrt provides a C# library for this purpose, called SendToSMM, as part of the Viz installation.
To Use TCP for Shared Memory
-
Open Viz Configuration.
-
Click on Communication.
-
Click on the Shared Memory Properties tab.
-
In the Shared Memory panel set the TCP Port parameter. A specific port is not recommended. Always make sure that the selected port is not in use by any other program on the same subnet.
-
Click Save.
When accessing the VizCommunication Memory Map, the syntax for sending the key-value pairs is <key>|<value>, followed by a null-termination character:
-
key|value\0
Note: Key and value are divided by the pipe character, also known as vertical bar: |
Multiple key-value pairs can be sent at once. This requires that each pair is null-terminated:
-
key1|value1\0key2|value2\0
When accessing a Scene or System shared memory map, the syntax requires the inclusion of further information.Example: When sending multiple key-value pairs to system shared memory the syntax should be SMMSystem_SetValue|key1|value1\0SMMSystem_SetValue|key2|value2\0 and in this case if SMMSystem_SetValue is not specified before each key-value pair, only the first one is sent to the system shared memory while the rest of sent pairs are sent to VizCommunication shared memory.
-
Syntax for accessing the VizCommunication shared memory map:
-
SharedMemoryMap_SetValue|<key>|<value>\0
-
SharedMemoryMap_SetValueDistribute|<key>|<value>\0
-
SharedMemoryMap_CreateElement|<key>\0
-
SharedMemoryMap_DeleteElement|<key>\0
-
SharedMemoryMap_SetPartialValue|<key>|<part>|<number-parts>|<value>\0
-
Used to send long values over UDP where one command would exceed the UDP-Package size. With this command, the value can be sent in multiple parts
-
Current part index <part>
-
Total number of parts <number-parts>
-
Example: sending SharedMemoryMap_SetPartialValue|key1|0|2|123\0 and SharedMemoryMap_SetPartialValue|key1|1|2|456\0 would set the key 'key1' = 123456
-
-
-
Syntax for accessing the Scene shared memory map:
-
SMM#<scene object id>_SetValue|<key>|<value>\0
-
SMM#<scene object id>_CreateElement|<key>\0
-
SMM#<scene object id>_DeleteElement|<key>\0
-
-
Syntax for accessing the System shared memory map:
-
SMMSystem_SetValue|<key>|<value>\0
-
SMMSystem_CreateElement|<key>\0
-
SMMSystem_DeleteElement|<key>\0
Note: A C++ library to write to shared memory maps and an example is included with the local viz installation: <viz installation location>\Tools\VizControlLib.
-
UDP Protocol
The SHM UDP communication protocol should be used for the delivery of volatile data. It is quicker than the 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 data lost does not affect the constant data update.
To Use UDP for SHM
-
Open Viz Configuration.
-
Click on Communication.
-
Click on the Shared Memory Properties tab.
-
In the Shared Memory panel set the UDP Port parameter. A specific port is not recommended. 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 TCP and UDP Synchronization.
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 cannot be used, or is not to be used. It is possible to write a plug-in to import data (e.g. 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 is documented in the plug-in API documentation and comes with the Viz installer (go to, Start > All Programs > vizrt > Viz x.x > Documentation > plug-in SDK Documentation > Classes > Class List > Shared_Memory).
Command Interface
For small and single value changes, the Command Interface of Viz Artist can be used, for example, to update the headline in a Scene.
IMPORTANT! A command operation can block the renderer. If there are too many commands within a short time-frame, or if commands containing a large amount of data is being sent, this can result in not rendering real-time anymore.
Note: This is not recommended as a method for synchronization.
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 available 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 Artist.
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 (default port 6100)).
Command Examples
VIZ_COMMUNICATION*MAP can be used to access the map.
SET_DOUBLE_ELEMENT and GET_DOUBLE_ELEMENT
Example: VIZ_COMMUNICATION*MAP SET_DOUBLE_ELEMENT "my_double" 1.2
Example: VIZ_COMMUNICATION*MAP GET_DOUBLE_ELEMENT "my_double"