Apply Shared Memory

graphics/viz_icons_applysharedmemory.png

The Apply Shared Memory plugin allows values to be transferred into Viz Engine using Data Sharing mechanisms provided by shared memory maps that can be applied to control plugins such as Control Text. Just as Control Object acts as a distribution hub for content provided by control applications, the Apply Shared Memory plugin acts as a distribution hub for content provided by external systems feeding real-time data through the shared memory maps.

The control plugins that the Apply Shared Memory plugin can apply content to resides in the same folder.

Just like the Control Object plugin, the Apply Shared Memory plugin only applies values to control plugins residing in the subtree of the scene tree where the Apply Shared Memory plugin resides. Also like the Control Object plugin, it matches the keys of incoming content with the field identifiers of individual control plugins to determine where to apply which incoming content value.

Note: This plugin is located in: Built-ins -> Container Plugins -> Control

This section contains information on the following topics:

Apply Shared Memory Properties
graphics/plug-ins_applysharedmemory_editor.png
  • Shared Memory Source: Specifies which shared memory map to apply values from. The Scene, Global and Distributed choices select the shared memory maps that are referred to as Scene.Map, System.Map and VizCommunication.Map respectively in the Data Sharing section.

  • Memory Base Key: The key prefix path to combine with the field identifiers of control plugins to determine the key to look up in the chosen shared memory map when applying values to a particular field exposed by a control plugin.

  • Expose Base Key: Expose the Memory Base Key property as a controllable field. Once this option is turned on the properties Field Identifier and Description as described in the Common Control Plugin Properties section can be specified.

The Expose Base Key property is typically used to allow a control application to control the base key which determines where in the shared memory map to pull values from. However, since the exposed property is an exposed control field like any other, a parent Apply Shared Memory plugin can be used to make the shared Memory Base Key property controllable by external systems through a shared memory map.

Choosing whether to allow the exposed field to be controlled by control applications or external systems feeding the shared memory map is done by placing either a Control Object or another Apply Shared Memory plugin on a parent container, respectively.

Visualizing composite data structures

The Memory Base Key property combined with the field identifiers exposed by control plugins can be seen as a way to visualize sets of related key-value pairs stored in shared memory maps. While the Memory Base Key property specifies where in the shared memory map to locate the set of related key-value pairs, the exposed field identifiers specify which of the related key-value pairs from the selected set to visualize in a particular way in the scene subtree.

For example, the Memory Base Key property can specify a shared memory path representing a particular stock symbol, while the field identifiers of control plugins picks out particular values such as stock name, value and change from that location in the shared memory map.

Since the Apply Shared Memory plugin only affects the scene subtree it is placed on, visualizing multiple composite data structure instances sharing the same structure and presentation can easily be achieved by copying subtrees and only change the Memory Base Key property.

For example, design a stock presentation design once, and copy it many times to create a scene showing several distinct stocks using the same visual style. Turning on the Expose Base Key property gives users of control applications control of which stocks to show in each presentation copy, while the data content for each stock is still supplied in real-time through the shared memory map.

How shared memory keys are determined

The shared memory keys used to look up values in a shared memory map is constructed by the combination of an absolute path specified in Memory Base Key property and an either relative or absolute path consisting of the field identifier of an exposed field. Any path starting with a slash (/) is considered an absolute path, while all other paths are considered relative.

If the field identifier is an absolute path, then that absolute path alone is the result of the resulting shared memory key used. For example, the field identifier “/weather/norway/bergen/temperature” will result in the shared memory key “/weather/norway/bergen/temperature” regardless of what the Memory Base Key property is.

If the field identifier is a relative path, the path is interpreted relative to the absolute base path provided in the Memory Base Key property, and the absolute path resulting from that interpretation is used as the shared memory key. For example, a Memory Base Key property of “/weather/sweden/stockholm” and a field identifier of “temperature” results in the shared memory key “/weather/sweden/stockholm/temperature”.

Like file system paths, a path segment consisting of a single dot (.) is considered referring to the current directory, while two dots (..) is considered referring to the parent directory. This notation is resolved to a regular absolute path before using the result as a shared memory key. For example, a Memory Base Key property of “/weather/./norway/trondheim” and a field identifier of “../oslo/windspeed” will resolve to the shared memory key “/weather/norway/oslo/windspeed”.

To visualize stock data from shared memory
graphics/plug-ins_applysharedmemory-stock-visualization-tree.png

This procedure will visualize composite content fed through a shared memory map to the control plugins Control Text, Control Num and Control Sign Container.

  1. Create a new container

  2. Drag and drop a Apply Shared Memory plugin into this container

  3. Set the Memory Base Key property of the Apply Shared Memory plugin to “/stocks/nyse/ibm”

  4. Create two text geometries as children of this container

  5. Drag and drop a Control Text plugin into the first text geometry container

  6. Set the Field Identifier property of the Control Text plugin to “name”

  7. Turn off Use formatted text property of the Control Text plugin

  8. Drag and drop a Control Num plugin into the second text geometry container

  9. Set the Field Identifier property of the of the Control Num plugin to “value”

  10. Create a third container as a child of the Apply Shared Memory plugin container

  11. Drag and drop a Control Sign Container plugin into this container.

  12. Set the Field Identifier property of the of the Control Sign Container plugin to “value”

  13. Create three text geometries as children of the Control Sign Container plugin container

  14. Drag and drop a Control Num plugin into each of these three text geometry containers

  15. For each of these three Control Num plugins set the Field Identifier property to “change”

  16. Arrange the layout of the text geometries, and apply materials for styling

To test stock visualization
graphics/plug-ins_applysharedmemory-console-output.png

To test that stock visualization commands can be sent to populate the global shared memory map, see the descriptions in the Data Sharing section.

graphics/plug-ins_applysharedmemory-scene-editor.png

While these commands are suitable for testing the designs, a real external system that feeds the Viz Engine with data would use a more efficient data transfer protocols to populate the shared memory map. See the External Data Input section for information about sending data efficiently using UDP.

When changing a value in the shared memory map that is visualized by a control plugin the scene updates immediately to reflect the new value. The shared memory map can be populated with stock values for many stock symbols, including stocks that are not visualized at the moment. As soon as the Memory Base Key property of the Apply Shared Memory plugin is changed to visualize the values for a different stock symbol, and the scene updates immediately to reflect the value previously populated into the shared memory map for that stock symbol.