Description

A temporary reference expression. Temporary reference expressions are used to make the structure of DAGs (directed acyclic graphs) more explicit. Consider a diamond-shaped graph with four nodes A, B, C, and D. Node A references nodes B and C, and both nodes B and C reference node D.

When traversing this graph starting at node A, it could be important to realize when the node D is visited a second time (to avoid double work for node D, or to avoid misinterpreting the graph as a tree).

Note that in this example we use letters to identify the nodes. But expressions themselves do not have names. And the neuray API does not guarantee identical pointer addresses for repeated accesses to the (logically) same object. For example, repeated calls of mi::neuraylib::IExpression_direct_call::get_arguments() followed by mi::neuraylib::IExpression_list::get_expression() result in different pointers, although logically the result is always the same (for the same input). Therefore, a different mechanism is needed to recognize nodes that can be visited several times in a traversal.

This is where temporary references come into play. In an expression graph for the example above, the nodes B and C do not point directly to node D, but to two temporary reference expressions, both with the same index. The node D can then be retrieved by passing that index to mi::neuraylib::IFunction_definition::get_temporary() or mi::neuraylib::ICompiled_material::get_temporary().

A common idiom is to traverse temporaries first, storing the result for each temporary, and to use them when encountering the corresponding temporary reference. Alternatively, one can traverse temporaries when encountered on-demand, store the result for each temporary, and reuse the result of the first encounter of a particular temporary on later encounters of that temporary.

Note that, despite the name mi::neuraylib::IExpression_temporary, expressions of this type are not the temporaries themselves, but references to temporaries. Temporaries can be nested, i.e., a temporary with index i might contain temporary references for other temporaries with indices up to i-1.

Temporary reference expressions appear in fields (and temporaries) of compiled materials, and in the bodies (and temporaries) of function and material definitions.