Viz 3.x introduced quite a number of improvements – starting with internal scripting, through new interface features and scene construction possibilities. One of my favourites is Shared Memory feature, so I’m going to talk for a while about that.

Overview

Most of you are probably familiar with the concept of Shared Memory in viz 3 but for those of you who never used it before I’ll make a quick overview. Shared Memory is like a storage. It’s similar to Dictionary object in vbscript. It can contain number of variant objects indexed with a string key. What’s interesting it can be used to share those object between different scenes or event different machines. The only thing we have to provide to accomplish the second scenario is to be sure all machines are connected to the same VizGraphicsHub (previously VizDB).

We have three types of Shared Memory maps: Scene.Map, System.Map and VizCommunication.Map. To be able to share our data between different machines we should use the last one.

Using Shared Memory – simple example

Lets take a look at the simple usage of Shared Memory. Imagine we have a scene with a text group somewhere in the scene tree. We want to display text depending on a shared memory value. To do that we just have to put Script Plugin on that node a type just a few lines of code.

Sub OnInit()
	VizCommunication.Map.RegisterChangedCallback("text_param")
End Sub

Sub OnSharedMemoryVariableChanged(map As SharedMemory, mapKey As String)
	If (mapKey = "text_param") Then
		this.Geometry.Text = map[mapKey]
	End If
End Sub

As you can see we’ve implemented two events: OnInit() and OnSharedMemoryVariableChanged(). First event is fired just once – when script plugin is initialized. In a typical scenario this means – when scene is loaded. In its body we have a call to RegisterChangedCallback method of VizCommunication.Map. What it does is it constructs a listener on a particular Shared Memory entry. Whenever this entry changes it’s value – OnSharedMemoryVariableChanged() event is fired. We passed a parameter to this method to inform listener we want to monitor any changes made to “text_param” entry. If we wanted to listen to any changes made to Shared Memory we should pass an empty string as parameter. Once we registerd shared memory listener we proceed to OnSharedMemoryVariableChanged() event. As you can see it has two parameters. First one – “map” is a Shared Memory map in which some change occurred. The second parameter is an entry key under which some change has been made. All we have to do now is to assign new value to our text geometry. Voila!

Of course we can always get values stored in Shared Memory and put it in some local variable for example. All we have to do is to refer to specific entry of shared memory map like this:

Dim textVal As String = VizCommunication.Map[“text_param”]

Placing values in Shared Memory from viz3 script

Now that we know how to use values stored lets take a quick look on how can we assign values to shared memory map. Lets assume we have some fancy method/function which calculates something and then it should put the result in a shared memory under specific entry. This is how we could do this:

Function PutValue(param As String) As Boolean

Dim result As Boolean = False
Dim newVal As String = param & “%”
If (newVal <> VizCommunication.Map[“text_param”]) Then
	result = True
End If

VizCommunication.Map[“text_param”] = newVal
PutValue = result

End Function

This function and a percent symbol at the end of a string parameter and then check if resulting string is different then the one stored in shared memory map. If so the result of the function would be true, otherwise – false. Finally it assigns new string value to shared memory. Pretty simple, don’t you think. But wait it gets better :-).

Placing values in Shared Memory from outside of viz engine

What if we wanted to assign Shared Memory entry from external application or Content Pilot template? Of course we can do this. To access Shared Memory from outside we can use viz commands:

• VIZ_COMMUNICATION*MAP CREATE_ELEMENT name –
  creates new Shared Memory entry specified by name
• VIZ_COMMUNICATION*MAP DELETE_ELEMENT name –
  deletes Shared Memory entry specified by name
• VIZ_COMMUNICATION*MAP HAS_ELEMENT name –
  checks if Shared Memory entry exists. If so – returns 1, otherwise returns 0
• VIZ_COMMUNICATION*MAP GET_ELEMENT name –
  gets value of Shared Memory entry specified by name
• VIZ_COMMUNICATION*MAP SET_ELEMENT name value –
  sets value string in Shared Memory entry specified be name

There are more viz commands avaible, so if you’re interested type send VIZ_COMMUNICATION*MAP COMMAND_INFO in engine console window or send this command via VizSend to get full list.

So our function in Content Pilot template could look like this:

Function PutValue(param)

Dim oldVal, newVal, result
	result = False
	oldVal = SendSingleCmd(MainMachine, “VIZ_COMMUNICATION*MAP GET_ELEMENT text_param”, True)
	newVal = param & “%”
	If (oldVal <> newVal) Then
		result = true
	End If
	buffer_clear
	buffer_put “-1 VIZ_COMMUNICATION*MAP SET_ELEMENT text_param “ & newVal
	buffer_send MainMachine

	PutValue = result
End Function

Same thing as previous example, right? Wrong! This function is fine but it doesn’t work as expected with strings that contains spaces. The reason is viz engine splits functions and parameters by spaces so when we pass a string containing those, for example – Hello World! – only Hello word will be assigned. Is there a way to do it a proper way? Of course there is. What we should do is to ensure every string value we pass is encapsulated within quote characters (“). That’s all – now everything should be working fine.

Summary

In this short article we took a look at Shared Memory feature of viz 3.x engine. I showed you basic idea of accessing Shared Memory Map entries. In examples I used only string values, but you can also use different types as well. You can even place your own structures in Shared Memory map. This post should give you brief idea on how to work with this feature, so you can get started utilizing it. Soon I’ll tell you how to create reusable communication model with Shared Memory as a lead actor. Till then – stay tuned.