Variable Expressions

Variable expressions are specially formatted strings that contain expressions that USD will evaluate at runtime. The expressions can contain variable data and logic used to dynamically create values. Variable expressions make use of named expression variables that can be easily defined and changed in layer metadata. Expression variables are defined in a "expressionVariables" dictionary metadata field in a layer.

Variable expressions can currently be used in:

• Asset paths (including sublayer, reference, and payload asset paths as well as asset-valued attributes and metadata)
• Variant selections

The following simple example demonstrates using variable expressions to specify a reference path and a variant selection. An ASSET_PATH expression variable is set to a directory, and then used in a reference variable expression. Similarly, a VARIANT_CHOICE expression variable is defined and then used in a variable expression for selecting a variant.

#usda 1.0
(
    expressionVariables = {
        # Define path to reference that can be changed as needed
        string ASSET_PATH = "/finalAssets/SetA"
        # Define the expression variable that can be changed as needed
        string VARIANT_CHOICE = "variantA"
    }
)
over "asset0" (
    # Use a variable expression to complete the reference asset path
    references = @`"${ASSET_PATH}/extraAssets.usda"`@</asset0>
)
{
}
 
def Xform "asset1" (
    variants = {
        # Use a variable expression for specifying the variant
        string displayVariantSet = "`${VARIANT_CHOICE}`"
    }
    prepend variantSets = "displayVariantSet"
)
{
    ...displayVariantSet definition omitted...
}

See Variable Expressions for user documentation on using variable expressions in your USD scene data, and reference information on the variable expressions supported syntax.

Understanding Variable Expression Composition and Evaluation

Expression variables do not compose across sublayers, but do compose in references and payloads, as described in Expression Variables and Composition.

For asset paths using variable expressions, USD will always evaluate the expression before passing the result to Ar for path resolution. If Ar returns a resolved path that looks like an expression, USD doesn't evaluate that expression.

Expressions in asset paths used in composition arcs are evaluated during the composition process. For asset path-valued attributes, USD will do the evaluation and resolution when UsdAttribute::Get (or similar methods) are called.

Working with Expression Variables

To work with a layer's expression variables dictionary, use SdfLayer's GetExpressionVariables(), SetExpressionVariables(), HasExpressionVariables(), and ClearExpressionVariables() methods.

SdfLayerHandle rootLayer = stage->GetRootLayer();
if (rootLayer->HasExpressionVariables()) {
    // Inspect expression variables using GetExpressionVariables() 
    VtDictionary expressionVars = rootLayer->GetExpressionVariables();
    // ... 
    // Clear expression variables using ClearExpressionVariables()
    rootLayer->ClearExpressionVariables();
}

Working with Expressions

Variable expressions are treated as strings in USD data, so there's no special API for creating expressions. You can use expression strings in existing asset path and variant APIs.

// Asset Paths:
SdfAssetPath assetPathWithExpr("`extraAsset_${referenceQualifier}.usda`");
 
// Variant Selections:
workVariantSet.SetVariantSelection("`${variantSel}`");

For evaluating a variable expression, use Sdf's VariableExpression class.

SdfVariableExpression workVarExp("`${myVariable}`");
VtDictionary expressionVars = rootLayer->GetExpressionVariables();
SdfVariableExpression::Result workResult = workVarExp.Evaluate(expressionVars);
// Inspect evaluation errors
std::cout << "Evaluation errors:\n";
for (std::string &error : workResult.errors) {
    std::cout << error << "\n";
}
// ...inspect and use workResult.value as needed...

Change Notifications

Changes to expression variables that are used in expressions in references and other composition arcs will trigger recomposition as needed.

Changes that affect expressions in asset path-valued attributes and metadata will trigger a UsdNotice::ObjectsChange notice containing resolved asset path resyncs to be sent. This informs clients that asset paths in the specified subtrees of the scenegraph may now resolve to different locations. This broad notification is needed because UsdStage currently does not cache or pre-compute expression values to know precisely which objects (if any) were affected by such a change.