by Ryan Webber
This tutorial will demonstrate how to use the Set Global Values, and Get Global Values actors in Isadora.
Isadora version 2.1 introduced a new method of passing values between actors, and more importantly between scenes. The Set Global Values and Get Global Values actors offer a simple and powerful way to pass data within an Isadora show file. Values are available instantly to any and all active scenes. Values can contain text or numeric values, and allow the sharing of these values without the use of patch cords.
The Set Global Values and Get Global Values actors use a 'name' input to associate the two actors. You can think of 'name' as a container for the values – once the container name is defined by a Set Global Values actor, any Get Global Values actor can access the contents of the container by using this name. Using a unique name for each collection of values means that multiple pairs of these actors can be used within your show file without interfering with each other. It is best practice to use a name that helps make the purpose of the values clear. (Note that the name is case-sensitive: "my_name" is not the same as "My_Name".)
A variable number of values can be associated with each 'name.' You set the number of values using the 'values' input of the Set Global Values actor, and the 'outputs' input of the Get Global Values actor. As these inputs are changed, you will see a corresponding number of additional inputs or outputs, labeled 'value 1', 'value 2', etc., will be added to the actors. You may have up to 64 values associated with each name.
The Get Global Values actor will are output its values under these circumstances:
- Upon entering scene the Get Global Values actor will output the current values associated with 'name'.
- When one of the value inputs ('value 1', 'value 2', etc.) of a Set Global Values actor with the same 'name' changes.
It is common to set the 'values' and 'outputs' input values to the same number but, is not required. It is possible to set 12 values in a Set Global Values actor, and output only the first three in an associated Get Global Values actor. Remember that the values are ordered; therefore, to output the last value of the collection, the 'outputs' input of a Get Global Values actor must match the 'values' input of the associated Set Global Values actor.
TIP: Organizing your list of values so that the most commonly needed values are listed first may help with the overall organization of your patch.
Using Multiple Pairs of Global Values Actors
Although you can add 64 values to a Set Global Values/Get Global Values actors pair, if your patch is using these values in very different areas of your patch, it may become hard to manage the long patch cords making the patch logic hard to follow. Using a number of unique name values to create multiple pairs of setters and getters is a good way to logically structure your data and organize your patch.
Using Mutability
Both the Set Global Values, and Get Global Values actors offer mutable inputs and outputs for the value. Mutable input or output ports – which are drawn with a green dot instead of a blue one – dynamically change their data type when connected to another actor. For example, if you connect the 'value 1' input of a Set Global Values actor to the text output of a Trigger Text actor, the 'value 1' input will change to receive text instead of numeric input.
Important Note about Mutating Inputs and Outputs
When the input of a Set Global Values actor mutates to a new type, the output of an associated Get Global Values actor does not automatically mutate to match.
For example, when you connect the text output of a Trigger Text actor to the 'value 2' input of a Set Global Values actor, that input will mutate to accept text. But, the 'value 2' output of a Get Global Values that references the same 'name' does not automatically mutate to a text output. Instead it is up to you to ensure that the 'value 2' output of the matching Get Global Values actor is connected to an input that receives text.
The image above provides a good example, specifically the setup of the "HUD-text" Global Values actors. Notice the four outputs. Only two have been mutated to type text, and the other two show the default numeric value (zero).
Remember that media types (like video) are not supported for global values, unlike Broadcaster / Listener actor pairs.
Advanced Usage with User Actors
Using uniquely named Set Global Values / Get Global Values actor pairs within a User Actor is preferred over the use of Broadcaster / Listener actor pairs. The use of Broadcaster / Listener pairs within User Actors increases the chances of data conflicts due to the integer based channel setting. These same numeric channels are easily referenced from the parent patch, where the data may be corrupted if their usage in the User Actor is unknown or misunderstood.
By prefixing a globals collection with the name of your User Actor (example: 'actorname-XYvals') it is possible to insulate these data collections from outside influence. This is similar to providing variable scope or a namespace in traditional programming languages.
Since an important purpose of User Actors is to facilitate sharing of reusable modules, it is strongly recommended that Set Global Values / Get Global Values actor pairs are used inside User Actors instead of Broadcaster / Listener actor pairs.