|
# DECLARE AN INPUT BUTTON input A { float { 0.0 -100.0 100.0 0 "%f" } } # DECLARE OUTPUT BUTTON AS A TIEBACK TO INPUT # Boxes downstream connected to this button will be # directly referencing the input button 'A'. # output tieback=IN OUT { float out }
There is the subtle implication that a variable is NOT automatically generated for the output button, as is usually the case. Rather, the value of the input button (or variable name, if it's connected to an upstream box) is passed directly to any downstream boxes connected to this output.
In this example, boxes all generate automatic variables, and pass the values from inputs to outputs by copying the value through each automatic variable:
float A_OUT; .. A_OUT = 12.0; |
float B_OUT; .. printf("%f\n", A_OUT); B_OUT = A_OUT; |
float C_OUT; .. C_OUT = sqrt(B_OUT); |
If we modify box B's output to use a tieback to box B's input, then the code generated could be simplified to:
float A_OUT; .. A_OUT = 12.0; |
printf("%f", A_OUT); | float C_OUT; .. C_OUT = sqrt(A_OUT); |
In this case, Box C sees straight through Box B to the variable being output by Box A. Box B does not generate a variable, it's output simply evaluates to the value coming in on Box B's input.
If Box A's output was also configured as a tieback to its input (which the user set to be 12.0), then the output code could be simplified even more to:
(no code needed) | printf("%f", 12.0); | float C_OUT; .. C_OUT = sqrt(12.0); |
In this case, the initial constant at Box A's input appears directly on Box A's output. This value chains straight through Box B, and appears on Box C's input, without any intermediate variables.
Obviously, this makes for more efficient output code, and gets rid of the need for extraneous variables.
# DECLARE A FIXED VALUE OUTPUT BUTTON 'OUT' # Boxes downstream connected to this button will be # directly referencing the input button 'A'. # output fixedvalue=foo OUT { float out }
There is the subtle implication that a variable is NOT automatically generated for this output button, as is usually the case. Rather, the string 'foo' is passed to any downstream box connected to this output button.
Consider the following example, showing the code generated by each box:
A_OUT = 12.0; | B_OUT = A_OUT; | C_OUT = B_OUT; |
If we modify box B's output to be configured as 'fixedvalue=foo' then the code generated could be:
A_OUT = 12.0; | float foo = A_OUT; | C_OUT = foo; |
In the above, Box B does not automatically generate a variable as is usually the case. Here, the box generates its own variable called 'foo', and tells the output button to refer to that name, so all downstream boxes will see 'foo' instead of an automatically generated variable name.
NOTE: The string set by fixedvalue=<string> will be expanded by the macro expander, so it may contain any stree variables such as ${STREE_BoxTitleWid}, so the box can use these variables to declare unique, global scope variable names.
Variable Name |
Example |
Description |
${STREE_BoxTitleWid} | MyBox_12 | Evaluates to the box's title and window id#, which is exactly the same as the box's window title. |
${STREE_BoxWid} | 12 | Just the window id#. |
${STREE_BoxTitle} | MyBox | Just the title of the box, w/out the id#. |
${STREE_DeclareHead_buttname} | float | Evaluates to a word that would declare the datatype for the
named button buttname.
For example, if the user cast this button as a float, then this variable expands to the string 'float '. If the user cast it as a RenderMan color, then this variable expands to the string 'color '. This variable is useful for declaring variables within the macro code that are of the same datatype as a particular input button. See an example of how this variable can be used. |
${STREE_DeclareTail_buttname} | ; | Similar to the above, this evaluates to a string that completes
the declaration of a variable of the datatype for the named button.
See an example of how this variable can be used. |
${STREE_IsConnect_buttname} | 1 | This variable evaluates to a 0 or 1 value, depending on whether the named button buttname is connected to some other box, or not. |
${STREE_NVarInputs_buttname} | 3 | Evaluates to the number of variable inputs
the box currently has for the named button buttname.
This value can be used to determine array sizes, or loop counts to loop through the number of vinput buttons currently instanced. For example, if 'MyBox' has a vinput button defined as 'V', and the user has setup three instances (V1,V2,V3), then ${STREE_NVarInputs_V} will evaluate to '3'. |
If a box has an input button called 'IN', and the code is supposed to declare a variable of the same datatype as IN is currently cast to, one can use in the box's macro code:
${STREE_DeclareHead_IN} foo${STREE_DeclareTail_IN}
This safely declares the variable 'foo', regardless of what input 'IN' is cast as by the user. If it is cast as a 'float', then the code generator will generate:
float foo;
..whereas if the user cast the button as a Mental Ray integer (miInteger), then the code generator might generate:
miInteger foo;
Using 'foo' is ok if you're declaring local variables, but if you want to declare global scope variables, you will want to make the variable name unique, so that several instances of the box generate different global variables. To do this, you can use ${STREE_BoxTitleWid} as a way to ensure a unique variable name, ie:
${STREE_DeclareHead_IN} ${STREE_BoxTitleWid}_array${STREE_DeclareTail_IN}
..might expand to the following, if the box's window title is 'MyBox_12':
float MyBox_12_array;
You can then use ${STREE_BoxTitleWid}_array to refer to this unique variable throughout your code.
So if the user creates three instances of MyBox on the desk, it will generate three different variables, one for each box:
float MyBox_12_array; float MyBox_13_array; float MyBox_14_array;