Value Specifiers

Collaboration diagram for Value Specifiers:

Functions
template<typename ResultType >
ValueSpecifier	Computation (const TfToken &computationName)
	See Computation().
template<typename ResultType >
ValueSpecifier	IncomingConnections (const TfToken &computationName)
	See IncomingConnections().
template<typename ResultType >
ValueSpecifier	Metadata (const TfToken &metadataKey)
	See Metadata().
template<typename ResultType >
ValueSpecifier	Connections (const TfToken &computationName)
	See Connections().
template<typename ResultType >
ValueSpecifier	TargetedObjects (const TfToken &computationName)
	After a Relationship() accessor, requests input values from the computation computationName of type ResultType on the objects targeted by the relationship.
	Computation (const TfToken &computationName)
	Requests an input value from the computation computationName of type ResultType.
	Metadata (const TfToken &metadataKey)
	Requests an input value from the metadata field indicated by metadataKey, of type ResultType.
	Constant (ValueType &&constantValue)
	Requests a constant input value of type ValueType.
	Constant (const ValueType &constantValue)
	NamespaceAncestor (const TfToken &computationName)
	On a prim computation, requests an input value from the computation computationName of type ResultType on the nearest namespace ancestor prim.
template<typename ResultType >
auto	Connections (const TfToken &computationName)
	As a direct input to an attribute computation or after an Attribute() accessor, requests input values from the computation computationName of type ResultType on the objects targeted by the attribute's connections.
template<typename ResultType >
auto	IncomingConnections (const TfToken &computationName)
	On any provider, requests input values from the computation computationName of type ResultType on the attributes that own any attribute connections that target the provider object.

Detailed Description

A value specifier is an element of an input registration that identifies the value that is requested from a given computation provider.

Each computation input registration must contain exactly one value specifier. A value specifier comes after a sequence of zero or more object accessors, which determine the provider. A value specifier may be followed by one or more input options.

Function Documentation

Computation() [1/2]

template<Exec_ComputationBuilderProviderTypes allowed>

template<typename ResultType >

ValueSpecifier Computation ( const TfToken & computationName )

inline

See Computation().

Definition at line 500 of file computationBuilders.h.

Computation() [2/2]

template<typename ResultType >

Computation ( const TfToken & computationName )

inline

Requests an input value from the computation computationName of type ResultType.

The default input name is computationName; use InputName to specify a different input name.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that returns the value of another
    // prim computation.
    self.PrimComputation(_tokens->myComputation)
        .Callback(+[](const VdfContext &ctx) -> double {
            const double *const valuePtr =
                ctx.GetInputValuePtr<double>(_tokens->sourceComputation);
            return valuePtr ? *valuePtr : 0.0;
        })
        .Inputs(
            Computation<double>(_tokens->sourceComputation)
}

Definition at line 877 of file computationBuilders.h.

Connections() [1/2]

template<Exec_ComputationBuilderProviderTypes allowed>

template<typename ResultType >

ValueSpecifier Connections ( const TfToken & computationName )

inline

See Connections().

Definition at line 572 of file computationBuilders.h.

Connections() [2/2]

template<typename ResultType >

auto Connections

(

const TfToken &

computationName

)

As a direct input to an attribute computation or after an Attribute() accessor, requests input values from the computation computationName of type ResultType on the objects targeted by the attribute's connections.

Note

Conceptually, this input registration provides access to the owning attribute's connections, but as outlined in the paragraph above, in practice it requests the named computation from the objects that are targeted by those connections. The reason we choose "Connections" as the name, rather than "ConnectionTargetedObjects," is to allow for future expansion of USD to allow for value-transforming behaviors on attribute connections themselves.

The default input name is computationName; use InputName to specify a different input name.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register an attribute computation on the attribute 'myAttr' that
    // sums the results of the integer values flowing over myAttr's
    // connections from the objects targeted by those connections.
    self.AttributeComputation(_tokens->myAttr, _tokens->computeSum)
        .Callback(+[](const VdfContext &ctx) -> int {
            VdfReadIteratorRange<int> range(
                ctx, ExecBuiltinComputations->computeValue);
            return std::accumulate(range.begin(), range.end(), 0);
        })
        .Inputs(
            Connections<int>(ExecBuiltinComputations->computeValue));
}

Definition at line 1235 of file computationBuilders.h.

Constant() [1/2]

template<typename ValueType >

Constant ( const ValueType & constantValue )

inline

Definition at line 1059 of file computationBuilders.h.

Constant() [2/2]

template<typename ValueType >

Constant ( ValueType && constantValue )

inline

Requests a constant input value of type ValueType.

Note

No default input name is assigned. Constant(value) must be followed by .InputName(name).

This kind of input isn't necessarily useful when used with a self-contained computation definition. But it becomes useful for more complicated registrations, where one piece of code registers a callback that configures its evaluation-time behavior based on an input value and a separate piece of code registers a constant input that selects the desired behavior.

This can happen:

• When computation definitions are assembled programatically by parameterized registration code that is called to register various versions of a computation, possibly for multiple schemas
• When computation definitions are composed from registrations made for different schemas on the same prim (support for composed computation definitions is still TBD in OpenExec)
• When computation registration is configured (also TBD), allowing registrations for a single schema to be dynamic, depending on metadata values that drive the configuration process

Value Types

All computation input value types, including value types used to provide constant inputs, 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.

Note

Types that are used for constant inputs must be hashable (see VtIsHashable()).

Simple Example

This simple example shows the mechanics of using a constant input, without being suggestive of how it might be useful.

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that returns the value of its
    // constant input.
    self.PrimComputation(_tokens->myComputation)
        .Callback(+[](const VdfContext &ctx) -> double {
            return ctx.GetInputValue<double>(_tokens->myConstant);
        })
        .Inputs(
            Constant(42.0).InputName(_tokens->myConstant));
}

Complex Example

This example demonstrate how more complicated registration code might make use of constant inputs to configure the behavior of a callback at evaluation time.

template <typename RegistrationType>
void RegisterCallback(RegistrationType &reg)
{
    reg.Callback(+[](const VdfContext &ctx) -> std::string {
        const TfToken &mode = ctx.GetInputValue<TfToken>(_tokens->mode);
        if (mode == _tokens->mode1) {
            return "Mode 1 selected";
        else if (mode == _tokens->mode2) {
            return "Mode 2 selected";
        }
}
 
template <typename RegistrationType>
void RegisterInput(RegistrationType &reg, const int mode)
{
    if (mode == 1) {
        reg.Inputs(Constant(_tokens->mode1).InputName(_tokens->mode));
    } else if (mode == 2) {
        reg.Inputs(Constant(_tokens->mode2).InputName(_tokens->mode));
    }
}
 
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    auto reg = self.PrimComputation(_tokens->myComputation);
 
    // ...
 
    RegisterCallback(reg);
 
    // ...
 
    RegisterInput(reg, mode);
}

Definition at line 1043 of file computationBuilders.h.

IncomingConnections() [1/2]

template<Exec_ComputationBuilderProviderTypes allowed>

template<typename ResultType >

ValueSpecifier IncomingConnections ( const TfToken & computationName )

inline

See IncomingConnections().

Definition at line 515 of file computationBuilders.h.

IncomingConnections() [2/2]

template<typename ResultType >

auto IncomingConnections

(

const TfToken &

computationName

)

On any provider, requests input values from the computation computationName of type ResultType on the attributes that own any attribute connections that target the provider object.

When this input parameter produces multiple input values, there is no deterministic ordering.

Note

Conceptually, this input registration provides access to the connections that target the provider, but as outlined in the paragraph above, in practice it requests the named computation from the attributes that own those connections. The reason we choose "IncomingConnections" as the name, rather than "IncomingConnectionOwningAttributes," is to allow for future expansion of USD to allow for value-transforming behaviors on attribute connections themselves.

The default input name is computationName; use InputName to specify a different input name.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that sums the values of the
    // integer-valued attributes that own connections that target the
    // provider prim.
    self.PrimComputation(_tokens->computeSum)
        .Callback(+[](const VdfContext &ctx) -> int {
            VdfReadIteratorRange<int> range(
                ctx, ExecBuiltinComputations->computeValue);
            return std::accumulate(range.begin(), range.end(), 0);
        })
        .Inputs(
            IncomingConnections<int>(ExecBuiltinComputations->computeValue));
}

Definition at line 1286 of file computationBuilders.h.

Metadata() [1/2]

template<Exec_ComputationBuilderProviderTypes allowed>

template<typename ResultType >

ValueSpecifier Metadata ( const TfToken & metadataKey )

inline

See Metadata().

Definition at line 528 of file computationBuilders.h.

Metadata() [2/2]

template<typename ValueType >

Metadata ( const TfToken & metadataKey )

inline

Requests an input value from the metadata field indicated by metadataKey, of type ResultType.

The default input name is metadataKey; use InputName to specify a different input name.

Example

self.PrimComputation(_tokens->computeDocMetadata)
    .Callback(+[](const VdfContext &ctx) -> std::string {
         return ctx.GetInputValue<std::string>(
             SdfFieldKeys->Documentation);
    })
    .Inputs(
        Metadata<std::string>(SdfFieldKeys->Documentation).Required()
    );

Definition at line 919 of file computationBuilders.h.

NamespaceAncestor()

template<typename ResultType >

NamespaceAncestor ( const TfToken & computationName )

inline

On a prim computation, requests an input value from the computation computationName of type ResultType on the nearest namespace ancestor prim.

The default input name is computationName; use InputName to specify a different input name.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that finds the nearest namespace
    // ancestor that defines a computation 'sourceComputation' with
    // an `int` result type. If found, the result is the value of the
    // ancestor compuation; otherwise, returns 0.
    self.PrimComputation(_tokens->myComputation)
        .Callback(+[](const VdfContext &ctx) -> int {
            const int *const valuePtr =
                ctx.GetInputValuePtr<int>(_tokens->sourceComputation);
            return valuePtr ? *valuePtr : 0;
        })
        .Inputs(
            NamespaceAncestor<int>(_tokens->sourceComputation));
}

Definition at line 1124 of file computationBuilders.h.

TargetedObjects()

template<Exec_ComputationBuilderProviderTypes allowed>

template<typename ResultType >

ValueSpecifier TargetedObjects ( const TfToken & computationName )

inline

After a Relationship() accessor, requests input values from the computation computationName of type ResultType on the objects targeted by the relationship.

Relationship forwarding is applied, so if the relationship targets another relationship, the targets are transitively expanded, resulting in the ultimately targeted, non-relationship objects.

The default input name is computationName; use InputName to specify a different input name.

Example

EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
{
    // Register a prim computation that looks for the computation
    // 'sourceComputation' on all targeted objects of the relationship
    // 'myRel' and returns the number of matching targets.
    self.PrimComputation(_tokens->myComputation)
        .Callback(+[](const VdfContext &ctx) -> int {
            VdfReadIterator<int> it(_tokens->sourceComputation);
            return static_cast<int>(it.ComputeSize());
        })
        .Inputs(
            Relationship(_tokens->myRel)
            .TargetedObjects<int>(_tokens->sourceComputation));
}

Definition at line 636 of file computationBuilders.h.