OpenExec: Implement dispatched prim computations

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* are 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 prims. The second
parameter to the DispatchedPrimComputation registration function can be used to
specify zero or more schema types (as TfType%s). 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.

(Internal change: 2371457)

Author: adamrwoodbury

pxr/exec/exec/computationBuilders.cpp

@@ -16,6 +16,7 @@ PXR_NAMESPACE_OPEN_SCOPE
 // Exec_ComputationBuilderValueSpecifierBase
 //
 
+// This struct exists just to keep Exec_InputKey private.
 struct Exec_ComputationBuilderValueSpecifierBase::_Data
 {
     Exec_InputKey inputKey;
@@ -26,13 +27,15 @@ Exec_ComputationBuilderValueSpecifierBase(
     const TfToken &computationName,
     TfType resultType,
     ExecProviderResolution &&providerResolution,
-    const TfToken &inputName)
+    const TfToken &inputName,
+    bool fallsBackToDispatched)
     : _data(
         new _Data{
             inputName,
             computationName,
             resultType,
             std::move(providerResolution),
+            fallsBackToDispatched,
             /* optional */ true})
 {}
 
@@ -43,8 +46,7 @@ Exec_ComputationBuilderValueSpecifierBase(
 {}
 
 Exec_ComputationBuilderValueSpecifierBase::
-~Exec_ComputationBuilderValueSpecifierBase()
-{}
+~Exec_ComputationBuilderValueSpecifierBase() = default;
 
 void
 Exec_ComputationBuilderValueSpecifierBase::_SetInputName(
@@ -60,6 +62,13 @@ Exec_ComputationBuilderValueSpecifierBase::_SetOptional(
     _data->inputKey.optional = optional;
 }
 
+void
+Exec_ComputationBuilderValueSpecifierBase::_SetFallsBackToDispatched(
+    const bool fallsBackToDispatched)
+{
+    _data->inputKey.fallsBackToDispatched = true;
+}
+
 void
 Exec_ComputationBuilderValueSpecifierBase::_GetInputKey(
     Exec_InputKey *const inputKey) const
@@ -75,35 +84,57 @@ struct Exec_PrimComputationBuilder::_Data
 {
     _Data(
         const TfType schemaType_,
-        const TfToken &computationName_)
+        const TfToken &computationName_,
+        const bool dispatched_,
+        ExecDispatchesOntoSchemas &&dispatchesOntoSchemas_)
     : schemaType(schemaType_)
     , computationName(computationName_)
+    , dispatched(dispatched_)
+    , dispatchesOntoSchemas(std::move(dispatchesOntoSchemas_))
     , inputKeys(Exec_InputKeyVector::MakeShared())
     {
     }
 
     const TfType schemaType;
     const TfToken computationName;
+    const bool dispatched;
+    ExecDispatchesOntoSchemas dispatchesOntoSchemas;
     TfType resultType;
     ExecCallbackFn callback;
     Exec_InputKeyVectorRefPtr inputKeys;
 };
 
 Exec_PrimComputationBuilder::Exec_PrimComputationBuilder(
     const TfType schemaType,
-    const TfToken &computationName)
-    : _data(std::make_unique<_Data>(schemaType, computationName))
+    const TfToken &computationName,
+    const bool dispatched,
+    ExecDispatchesOntoSchemas &&dispatchesOntoSchemas)
+    : _data(std::make_unique<_Data>(
+                schemaType, computationName,
+                dispatched, std::move(dispatchesOntoSchemas)))
 {
 }
 
 Exec_PrimComputationBuilder::~Exec_PrimComputationBuilder()
 {
+    // A null pointer indicates the computation is not dispatched; otherwise,
+    // the pointed-to vector contains the list of the schemas onto which the
+    // dispatched computation dispatches, which can be empty, to indicate that
+    // the computation dispatches onto all prims.
+    std::unique_ptr<ExecDispatchesOntoSchemas> dispatchesOntoSchemas;
+    if (_data->dispatched) {
+        dispatchesOntoSchemas.reset(
+            new ExecDispatchesOntoSchemas(
+                std::move(_data->dispatchesOntoSchemas)));
+    }
+
     Exec_DefinitionRegistry::ComputationBuilderAccess::_RegisterPrimComputation(
         _data->schemaType,
         _data->computationName,
         _data->resultType,
         std::move(_data->callback),
-        std::move(_data->inputKeys));
+        std::move(_data->inputKeys),
+        std::move(dispatchesOntoSchemas));
 }
 
 void
@@ -145,4 +176,28 @@ Exec_ComputationBuilder::PrimComputation(
     return Exec_PrimComputationBuilder(_schemaType, computationName);
 }
 
+// Exec_PrimComputationBuilder 
+// Exec_ComputationBuilder::DispatchedPrimComputation(
+//     const TfToken &computationName,
+//     const TfType &ontoSchema)
+// {
+//     return Exec_PrimComputationBuilder(
+//         _schemaType,
+//         computationName,
+//         /* dispatched */ true,
+//         {ontoSchema});
+// }
+
+Exec_PrimComputationBuilder 
+Exec_ComputationBuilder::DispatchedPrimComputation(
+    const TfToken &computationName,
+    ExecDispatchesOntoSchemas &&ontoSchemas)
+{
+    return Exec_PrimComputationBuilder(
+        _schemaType,
+        computationName,
+        /* dispatched */ true,
+        std::move(ontoSchemas));
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/exec/exec/computationBuilders.h

@@ -224,7 +224,8 @@ class Exec_ComputationBuilderValueSpecifierBase
         const TfToken &computationName,
         TfType resultType,
         ExecProviderResolution &&providerResolution,
-        const TfToken &inputName);
+        const TfToken &inputName,
+        bool fallsBackToDispatched);
 
     EXEC_API
     Exec_ComputationBuilderValueSpecifierBase(
@@ -240,6 +241,9 @@ class Exec_ComputationBuilderValueSpecifierBase
     EXEC_API
     void _SetOptional (const bool optional);
 
+    EXEC_API
+    void _SetFallsBackToDispatched(bool fallsBackToDispatched);
+
 private:
     // Only computation builders can get the input key.
     friend class Exec_PrimComputationBuilder;
@@ -265,12 +269,14 @@ struct Exec_ComputationBuilderComputationValueSpecifier
 {
     Exec_ComputationBuilderComputationValueSpecifier(
         const TfToken &computationName,
-        TfType resultType,
-        ExecProviderResolution &&providerResolution)
+        const TfType resultType,
+        ExecProviderResolution &&providerResolution,
+        const bool fallsBackToDispatched = false)
         : Exec_ComputationBuilderValueSpecifierBase(
             computationName, resultType,
             std::move(providerResolution),
-            computationName)
+            computationName /* inputName */,
+            fallsBackToDispatched)
     {
     }
 
@@ -339,6 +345,44 @@ struct Exec_ComputationBuilderComputationValueSpecifier
         return *this;
     }
 
+    /// Declares the input can find dispatched computations *if* the requested
+    /// computation name doesn't match a local computation on the provider.
+    ///
+    /// \see [DispatchedPrimComputation](#Exec_ComputationBuilder::DispatchedPrimComputation)
+    ///
+    /// # Example
+    ///
+    /// ```{.cpp}
+    /// EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(MySchemaType)
+    /// {
+    ///     // Register a dispatched prim computation.
+    ///     self.DispatchedPrimComputation(_tokens->myDispatchedComputation)
+    ///         .Callback<double>(+[](const VdfContext &) { return 11.0; })
+    ///
+    ///     // Register a prim computation that requests the above dispatched
+    ///     // computation via uses relationship targets.
+    ///     self.PrimComputation(_tokens->myComputation)
+    ///         .Callback<double>(+[](const VdfContext &ctx) {
+    ///             const double *const valuePtr =
+    ///                 ctx.GetInputValuePtr<double>(
+    ///                     _tokens->myDispatchedComputation);
+    ///             return valuePtr ? *valuePtr : -1.0;
+    ///         })
+    ///         .Inputs(
+    ///             Relationship(_tokens->myRelationship)
+    ///                 .TargetedObjects<double>(
+    ///                     _tokens->myDispatchedComputation)
+    ///                 .FallsBackToDispatched())
+    /// }
+    /// ```
+    ///
+    This&
+    FallsBackToDispatched()
+    {
+        _SetFallsBackToDispatched(true);
+        return *this;
+    }
+
     /// @}
 };
 
@@ -829,8 +873,71 @@ class Exec_ComputationBuilder
     Exec_PrimComputationBuilder 
     PrimComputation(const TfToken &computationName);
 
+    /// Registers a dispatched prim computation named \p 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
+    /// TfType%s). 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
+    ///
+    /// ```{.cpp}
+    /// 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.
+    ///     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())
+    /// }
+    /// ```
+    ///
+    EXEC_API
+    Exec_PrimComputationBuilder 
+    DispatchedPrimComputation(
+        const TfToken &computationName,
+        ExecDispatchesOntoSchemas &&ontoSchemas);
+
+    // Convenience variadic template overload that takes zero or more schema
+    // types.
+    template <class... DispatchedOntoSchemaTypes>
+    Exec_PrimComputationBuilder
+    DispatchedPrimComputation(
+        const TfToken &computationName,
+        DispatchedOntoSchemaTypes &&...schemaTypes);
+
     // XXX:TODO
-    // AttributeComputation
+    // - AttributeComputation
+    // - DispatchedAttributeComputation
 
     ///  @}
 
@@ -849,7 +956,9 @@ class Exec_PrimComputationBuilder
     EXEC_API
     Exec_PrimComputationBuilder(
         TfType schemaType,
-        const TfToken &computationName);
+        const TfToken &computationName,
+        bool dispatched = false,
+        ExecDispatchesOntoSchemas &&dispatchesOntoSchemas = {});
 
 public:
     EXEC_API
@@ -1002,6 +1111,21 @@ Exec_PrimComputationBuilder::_ValidateInputs() {
         "Input is not allowed on a provider of this type.");
 }
 
+template <class... DispatchedOntoSchemaTypes>
+Exec_PrimComputationBuilder
+Exec_ComputationBuilder::DispatchedPrimComputation(
+    const TfToken &computationName,
+    DispatchedOntoSchemaTypes &&...schemaTypes)
+{
+    static_assert(
+        (std::is_same_v<
+             std::decay_t<DispatchedOntoSchemaTypes>, TfType> && ...));
+
+    return DispatchedPrimComputation(
+        computationName,
+        {std::forward<DispatchedOntoSchemaTypes>(schemaTypes)...});
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE
 
 #endif

pxr/exec/exec/computationDefinition.cpp

@@ -37,4 +37,10 @@ Exec_ComputationDefinition::GetExtractionType(
     return _resultType;
 }
 
+bool
+Exec_ComputationDefinition::IsDispatched() const
+{
+    return false;
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/exec/exec/computationDefinition.h

@@ -54,6 +54,9 @@ class Exec_ComputationDefinition
     virtual TfType GetExtractionType(
         const EsfObjectInterface &providerObject) const;
 
+    /// Returns `true` if this computation is a dispatched computation.
+    virtual bool IsDispatched() const;
+
     /// Returns the keys that indicate how to source the input values required
     /// to evaluate the computation when the provider is \p providerObject.
     ///