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 ResultType , typename FuncType >
Derived &	Callback (FuncType &&callback)
	Registers a callback function that implements the evaluation logic for a computation; this overload accepts a function object that isn't a function pointer (e.g., a capturing lambda).
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(+[](const VdfContext &) -> double { 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() [1/2]

Derived & Callback

(

FuncType &&

callback

)

Registers a callback function that implements the evaluation logic for a computation; this overload accepts a function object that isn't a function pointer (e.g., a capturing lambda).

This registration must follow a computation registration or a function that returns a computation registration. This function returns a computation registration.

Accepts a function object that takes a single argument of type const VdfContext & and returns void. The ResultType must be explicitly specified as a template parameter. The callback must provide the output value by calling VdfContext::SetOutput, VdfContext::SetEmptyOutput, or using a write iterator.

Thread and Cache Safety

Computation callbacks must be pure functions. They must be thread safe in the sense that multiple instances of a given computation callback may be invoked simultaneously in multiple threads. They must be "cache safe," meaning that all input values must be known to the exec system so that it can invalidate cached computation results when input values change.

When passing a function object as a callback, it is therefore important to be careful not to run afoul of these requirements for callbacks. E.g., be careful with lambda capture, or shared state that is reachable from function object data members.

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)
{
    const TfToken inputName("anInputName");
    
    // Register a prim computation with a capturing lambda as the
    // callback.
    self.PrimComputation(_tokens->stringValuedComputation)
        .Callback<int>([inputName](const VdfContext &) {
            int i = ctx.GetInputValue(inputName);
            ctx.SetValue(i+1);
        });
}

Definition at line 1963 of file computationBuilders.h.

Callback() [2/2]

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 or a function that returns a computation registration. This function returns a computation registration.

Accepts a callback function that is a function pointer with a signature of ReturnType (*)(const VdfContext &). 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.

Thread and Cache Safety

Computation callbacks must be pure functions. They must be thread safe in the sense that multiple instances of a given computation callback may be invoked simultaneously in multiple threads. They must be "cache safe," meaning that all input values must be known to the exec system so that it can invalidate cached computation results when input values change.

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 1915 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(+[](const VdfContext &) -> double { 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(+[](const VdfContext &ctx) -> double {
            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 2074 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(+[](const VdfContext &) -> double { 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(+[](const VdfContext &ctx) -> double {
            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 2059 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 or a function that returns a computation registration. This function returns a computation registration.

Example

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

Definition at line 2002 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 or a function that returns a computation registration. This function returns 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(&_MyCallbackFn)
        .Inputs(
            Computation<double>(_tokens->anotherAttrComputation),
            Prim().AttributeValue<double>(_tokens->anotherAttr));
}

Definition at line 2021 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 or a function that returns a computation registration. This function returns 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(&_MyCallbackFn)
        .Inputs(
            Computation<double>(
                ExecBuiltinComputations->computeResolvedValue),
            Connections<double>(ExecBuiltinComputations->computeValue));
}

Definition at line 2040 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(+[](const VdfContext &) -> double { return 11.0; })
}