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:

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.

To Use TCP for Shared Memory

1. Open Viz Configuration.

2. Click on Communication.

3. Click on the Shared Memory Properties tab.

4. 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.

5. 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

• 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.

• 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

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

1. Open Viz Configuration.

2. Click on Communication.

3. Click on the Shared Memory Properties tab.

4. 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.

5. 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.

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.

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.

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