Computation Registrations

Computation registrations initiate the process of defining computations. More...

Collaboration diagram for Computation Registrations:

Functions
EXEC_API ExecPrimComputationBuilder	PrimComputation (const TfToken &computationName)
	Registers a prim computation named computationName.
EXEC_API ExecAttributeComputationBuilder	AttributeComputation (const TfToken &attributeName, const TfToken &computationName)
	Registers an attribute computation named computationName on attributes named attributeName.
EXEC_API ExecAttributeExpressionBuilder	AttributeExpression (const TfToken &attributeName)
	Registers an attribute expression for attributes named attributeName.
template<class... DispatchedOntoSchemaTypes>
ExecPrimComputationBuilder	DispatchedPrimComputation (const TfToken &computationName, DispatchedOntoSchemaTypes &&...schemaTypes)
	Registers a dispatched prim computation named computationName.
EXEC_API ExecPrimComputationBuilder	DispatchedPrimComputation (const TfToken &computationName, ExecDispatchesOntoSchemas &&ontoSchemas)
template<class... DispatchedOntoSchemaTypes>
ExecAttributeComputationBuilder	DispatchedAttributeComputation (const TfToken &computationName, DispatchedOntoSchemaTypes &&...schemaTypes)
	Registers a dispatched attribute computation named computationName.
EXEC_API ExecAttributeComputationBuilder	DispatchedAttributeComputation (const TfToken &computationName, ExecDispatchesOntoSchemas &&ontoSchemas)
template<typename ResultType = _UnspecifiedType, typename ReturnType = _UnspecifiedType>
Derived &	Callback (ReturnType(*callback)(const VdfContext &))
	Registers a callback function that implements the evaluation logic for a computation.
template<typename... Args>
ExecPrimComputationBuilder &	Inputs (Args &&... args)
	Takes one or more input registrations that specify how to source input values for a prim computation.
template<typename... Args>
ExecAttributeComputationBuilder &	Inputs (Args &&... args)
	Takes one or more input registrations that specify how to source input values for an attribute computation.
template<typename... Args>
ExecAttributeExpressionBuilder &	Inputs (Args &&... args)
	Takes one or more input registrations that specify how to source input values for an attribute expression.

Detailed Description

Computation registrations initiate the process of defining computations.

The object returned by a computation registration has methods that are used to specify the callback that implements the computation and the inputs that are provided to the callback at evaluation time.

Function Documentation

AttributeComputation()

EXEC_API ExecAttributeComputationBuilder AttributeComputation	(	const TfToken &	attributeName,
		const TfToken &	computationName
	)

Registers an attribute computation named computationName on attributes named attributeName.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a trivial attribute computation.
    self.AttributeComputation(
        _tokens->attr,   // attributeName
        _tokens->eleven) // computationName
        .Callback<double>(+[](const VdfContext &) { return 11.0; })
}

AttributeExpression()

EXEC_API ExecAttributeExpressionBuilder AttributeExpression

(

const TfToken &

attributeName

)

Registers an attribute expression for attributes named attributeName.

All attributes have a computed value that can be consumed by computation inputs, either by explicitly requesting the built-in computation computeValue or by using AttributeValue. The attribute expression allows plugin-writers to customize this computed value. If no attribute expression is defined, then computeValue simply provides the resolved value of the attribute.

When defining an attribute expression, it is often desired that it consume the attribute's resolved value. The expression can obtain the resolved value by registering an input from the computation computeResolvedValue on the provider attribute.

Note

The attribute expression may produce a different type from the attribute on which it has been registered. Though allowed, this can lead to confusion, and this may become restricted in the future.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register an attribute expression for the string-valued attribute
    // 'myString', such that its computed value is its resolved value
    // in upper-case.
    self.AttributeExpression(_tokens->myString)
        .Inputs(
            Computation<std::string>(
                ExecBuiltinComputations->computeResolvedValue))
        .Callback(+[](const VdfContext &ctx) -> std::string {
            return TfStringToUpper(ctx.GetInputValue<std::string>(
                ExecBuiltinComputations->computeResolvedValue));
        });
}

Callback()

Derived & Callback

(

ReturnType(*)(const VdfContext &)

callback

)

Registers a callback function that implements the evaluation logic for a computation.

This registration must follow a computation registration.

Callback functions must be function pointers where the signature is ReturnType (*)(const VdfContext &) and ReturnType can be any of the following:

• The result type of the computation, in which case ResultType can be deduced from the callback type.
• A type that is convertible to the result type of the computaion, in which case ResultType must be explicitly specified as a template parameter.
• void in which case ResultType must be explicitly specified as a template parameter and the callback must call VdfContext::SetOutput to provide the output value.

Result Types

Note that the types used as computation result types (and as computation input value types) must be known to the execution system. All types that can be used to author attribute and metadata values in USD are known to exec by default. User-defined types must be registered by calling ExecTypeRegistry::RegisterType.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation with a callback where the result type
    // is deduced to be `float`.
    self.PrimComputation(_tokens->doubleValuedComputation)
        .Callback(
            +[](const VdfContext &) { return 11.0f; });
 
    // Register a prim computation with a callback where the explicit
    // result type is `std::string`.
    self.PrimComputation(_tokens->stringValuedComputation)
        .Callback<std::string>(
            +[](const VdfContext &) { return "a string value"; });
 
    // Register a prim computation with a callback that explicitly calls
    // SetValue.
    self.PrimComputation(_tokens->stringValuedComputation)
        .Callback<int>(
            +[](const VdfContext &) { ctx.SetValue(42); });
}

Definition at line 1841 of file computationBuilders.h.

DispatchedAttributeComputation()

ExecAttributeComputationBuilder DispatchedAttributeComputation	(	const TfToken &	computationName,
		DispatchedOntoSchemaTypes &&...	schemaTypes
	)

Registers a dispatched attribute computation named computationName.

See also

DispatchedPrimComputation

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a dispatched attribute computation that can be found on
    // attributes on scopes.
    const TfType scopeType = TfType::FindByName("UsdGeomScope");
    self.DispatchedAttributeComputation(_tokens->eleven, scopeType)
        .Callback<double>(+[](const VdfContext &) { return 11.0; })
 
    // Register a prim computation that requests the above dispatched
    // computation on an attribute on the owning prim named 'attr'.
    self.PrimComputation(_tokens->myComputation)
        .Callback<double>(+[](const VdfContext &ctx) {
            const double *const valuePtr =
                ctx.GetInputValuePtr<double>(_tokens->eleven);
            return valuePtr ? *valuePtr : -1.0;
        })
        .Inputs(
 
            // This input opts-in to finding dispatched computations.
            Attribute(_tokens->attr)
                .Computation<double>(_tokens->eleven)
                .FallsBackToDispatched())
}

Definition at line 1964 of file computationBuilders.h.

DispatchedPrimComputation()

ExecPrimComputationBuilder DispatchedPrimComputation	(	const TfToken &	computationName,
		DispatchedOntoSchemaTypes &&...	schemaTypes
	)

Registers a dispatched prim computation named computationName.

A dispatched prim computation is only visible to computations on the prim that does the dispatching. I.e., the computation registrations for a schema can include dispatched computations and inputs to computations registered on the same schema can request the dispatched computations, using the input option FallsBackToDispatched(), from other provider prims and find them there. Other schema computation registrations will not be able to find the dispatched computations, however.

Dispatched computations can be restricted as to which prims they can dispatch onto, based on the typed and applied schemas of a given target prim. The second parameter to the DispatchedPrimComputation registration function can be used to specify zero or more schema types (as TfTypes). If any types are given, the dispatched computation will only be found on a target prim if that prim's typed schema type (or one of its base type) is among the given schema types or if the fully expanded list of API schemas applied to the prim includes a schema that is among the given schema types.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a dispatched prim computation that can be found on
    // scopes.
    const TfType scopeType = TfType::FindByName("UsdGeomScope");
    self.DispatchedPrimComputation(_tokens->eleven, scopeType)
        .Callback<double>(+[](const VdfContext &) { return 11.0; })
 
    // Register a prim computation that requests the above dispatched
    // computation via uses relationship targets. Any targeted prim
    // whose type is UsdGeomScope will find the requested computation.
    self.PrimComputation(_tokens->myComputation)
        .Callback<double>(+[](const VdfContext &ctx) {
            const double *const valuePtr =
                ctx.GetInputValuePtr<double>(_tokens->eleven);
            return valuePtr ? *valuePtr : -1.0;
        })
        .Inputs(
 
            // This input opts-in to finding dispatched computations.
            Relationship(_tokens->myRelationship)
                .TargetedObjects<double>(_tokens->eleven)
                .FallsBackToDispatched())
}

Definition at line 1949 of file computationBuilders.h.

Inputs() [1/3]

ExecPrimComputationBuilder & Inputs

(

Args &&...

args

)

Takes one or more input registrations that specify how to source input values for a prim computation.

This registration must follow a computation registration.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that reads from two inputs.
    self.PrimComputation(_tokens->myPrimComputation)
        .Callback<int>(&_MyCallbackFn)
        .Inputs(
            AttributeValue<int>(_tokens->myAttribute),
            NamespaceAncestor<double>(_tokens->anotherPrimComputation));
}

Definition at line 1892 of file computationBuilders.h.

Inputs() [2/3]

ExecAttributeComputationBuilder & Inputs

(

Args &&...

args

)

Takes one or more input registrations that specify how to source input values for an attribute computation.

This registration must follow a computation registration.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register an attribute computation that reads from another
    // computation on the same attribute, and from a sibling attribute's
    // computed value.
    self.AttributeComputation(
        _tokens->attr,
        _tokens->myAttrComputation)
        .Callback<int>(&_MyCallbackFn)
        .Inputs(
            Computation<double>(_tokens->anotherAttrComputation),
            Prim().AttributeValue<double>(_tokens->anotherAttr));
}

Definition at line 1911 of file computationBuilders.h.

Inputs() [3/3]

ExecAttributeExpressionBuilder & Inputs

(

Args &&...

args

)

Takes one or more input registrations that specify how to source input values for an attribute expression.

This registration must follow a computation registration.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register an attribute expression that uses the attribute's
    // resolved value, and the computed value of all connected
    // attributes.
    self.AttributeExpression(_tokens->attr)
        .Callback<int>(&_MyCallbackFn)
        .Inputs(
            Computation<double>(
                ExecBuiltinComputations->computeResolvedValue),
            Connections<double>(ExecBuiltinComputations->computeValue));
}

Definition at line 1930 of file computationBuilders.h.

PrimComputation()

EXEC_API ExecPrimComputationBuilder PrimComputation

(

const TfToken &

computationName

)

Registers a prim computation named computationName.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a trivial prim computation.
    self.PrimComputation(_tokens->eleven)
        .Callback<double>(+[](const VdfContext &) { return 11.0; })
}