| Virtual Choreographer Reference Guide (version 1.4) | ||
|---|---|---|
| Prev | Chapter 4. VC Macro-Commands, parameters, and variables | Next |
This section describes how to refer to parameter and variable values in strings. Parameter referencing is done at compile-time once and for all through string substitution. On the contrary variable referencing is done at run-time and depends on dynamic modification of variables through the set_node_scalar_value, set_node_table_value, and set_node_matrix_value. script commands.
Inside the scope of a macro-command that defines and controls a parameter, a parameter can be referenced in a string by the use of {#parameter-name}. Contrary to variables, the use of parentheses in strings is not necessary for parameter evaluation. Contrary to variables, parameter values can be used to define static values such as node IDs. If the parameter n is equal to 4, the following example define a node named "ground_quad_4":
<node id="ground_quad_{#n}">
Parameters can also be used inside arithmetic expressions enclosed in parentheses. If the parameter nbWalls is equal to 2, the following example assigns the value 8.0 to the attribute z of the element transformation:
<transformation z="(6.0 * {#nbWalls})" />
Evaluation of scalar variables in strings is triggered by the use of parentheses. There are three types of variables: integer, float, or string variables. In an arithmetic context, string variables are converted into float values (or null value if the string is not a valid float or integer representation).
Inside the scope of a parenthesized arithmetic expression, a scalar can be referenced in a string by the use of {$node-path:variable-name}. If the node in the current scene graph with the ID motion has three scalar variables arrivee_X, arrivee_Y, and arrivee_Z, the values of these variables at the time of the evaluation, are assigned to the attributes x, y, and z of the element transformation:
<transformation x="({$motion:arrivee_X})"
y="({$motion:arrivee_Y})"
z="({$motion:arrivee_Z})" />
Non scalar variables such as tables and matrices can also be referenced inside arithmetic expressions, but the index of the value must be provided between square brackets. Inside the scope of a parenthesized arithmetic expression, the scalar value of a matrix or a table can be referenced by {$node-path:variable-name[index-value]}. In the following example, we assume that the node root has a scalar variable n and that the value of this variable is 2 at the time of expression evaluation. This element assign the second value of the table or matrix variable named perchLocX of the root node to the attribute x of the element bezier:
<transformation x="({$root:perchLocX[({$root:n})]})" />
Non-scalar variables can also be processed in the context of non-scalar operators. They are referenced through an be referenced in a string by the use of {@node-path:variable-name}. The following expression computes the inverse of the attribute matrix of the transformation carried by the node birdPath (operator inv) and multiplies the resulting matrix by the table variable relativePhysLoc (operator :). The result of this product is a list of scalar values that is assigned to the table absolutePhysLoc through the script command set_node_table_value:
<set_node_table_value id="absolutePhysLoc"
value="(inv({@birdPath:matrix}) : {@birdPath:relativePhysLoc})"
operator="="/>
More details on arithmetic operators on scalar, matrix, and table variables or constant values are given in Chapter 8.
Reference to node, media-object, and transformation attributes is very similar to variable referencing. Inside the scope of a parenthesized arithmetic expression, an attribute can be referenced in a string by the use of {$node-path:attribute-name} in case of a scalar attribute or by {@node-path:attribute-name} in case of a table or matrix attribute.
The attributes referenced by this syntax are either node attributes or attributes of media-objects or transformations carried by nodes unless they are shadowed by a variable with the same ID. It is therefore recommended to avoid to chose attribute names for variable IDs.
For the following example, we assume that the value of the parameter n is equal to 5. If the node in the current scene graph with the ID birdPath 5 is a path transformation, x1 and x4 refer to the first coordinates of the first and fourth control point of the Bezier curve. If we assume that their values are 3.0 and 5.0 at the time of the evaluation, the following example assigns the value 3.4 to the attribute x2 of the element bezier:
<bezier x2="(0.8 * {$birdPath {#n}:x1} + 0.2 * {$birdPath {#n}:x4})" />