OpenExec: Add the IncomingConnections computation input parameter, which allows

computations to take input from computations on attributes that have connections
that target the consuming computation's provider object.

(Internal change: 2399176)

Author: adamrwoodbury

pxr/exec/esf/editReason.cpp

@@ -22,6 +22,8 @@ EsfEditReason::_GetBitDescription(EsfEditReason::_BitIndex bitIndex)
         return "ChangedPropertyList";
     case EsfEditReason::_BitIndex::ChangedConnectionPaths:
         return "ChangedConnectionPaths";
+    case EsfEditReason::_BitIndex::ChangedIncomingConnections:
+        return "ChangedIncomingConnections";
     case EsfEditReason::_BitIndex::ChangedTargetPaths:
         return "ChangedTargetPaths";
     case EsfEditReason::_BitIndex::Max:

pxr/exec/esf/editReason.h

@@ -52,6 +52,10 @@ class EsfEditReason
     ///
     static const EsfEditReason ChangedConnectionPaths;
 
+    /// The set of connections that target an object has changed.
+    ///
+    static const EsfEditReason ChangedIncomingConnections;
+
     /// The list of target paths on a relationship has changed.
     ///
     static const EsfEditReason ChangedTargetPaths;
@@ -128,6 +132,7 @@ class EsfEditReason
         ResyncedObject,
         ChangedPropertyList,
         ChangedConnectionPaths,
+        ChangedIncomingConnections,
         ChangedTargetPaths,
         Max
     };
@@ -154,6 +159,9 @@ inline constexpr EsfEditReason EsfEditReason::ChangedPropertyList(
 inline constexpr EsfEditReason EsfEditReason::ChangedConnectionPaths(
     EsfEditReason::_BitIndex::ChangedConnectionPaths);
 
+inline constexpr EsfEditReason EsfEditReason::ChangedIncomingConnections(
+    EsfEditReason::_BitIndex::ChangedIncomingConnections);
+
 inline constexpr EsfEditReason EsfEditReason::ChangedTargetPaths(
     EsfEditReason::_BitIndex::ChangedTargetPaths);
 

pxr/exec/esf/object.cpp

@@ -66,10 +66,8 @@ EsfObjectInterface::GetIncomingConnections(EsfJournal *const journal) const
     if (journal) {
         journal->Add(
             _GetPath(),
-// TODO:
-//             EsfEditReason::ResyncedObject |
-//             EsfEditReason::ChangedIncomingConnections);
-            EsfEditReason::ResyncedObject);
+            EsfEditReason::ResyncedObject |
+            EsfEditReason::ChangedIncomingConnections);
     }
     return _GetIncomingConnections();
 }

pxr/exec/esfUsd/stageData.cpp

@@ -329,7 +329,7 @@ EsfUsdStageData::UpdateForResync(
     // Note that as long as an owning attribute has a given connection, the
     // incoming connection map entry remains populated, regardless of whether
     // the targeted object exists in the scene.
-    if (!resyncedPrim || !UsdPrimDefaultPredicate(resyncedPrim)) {
+    if (!UsdPrimDefaultPredicate(resyncedPrim)) {
         TRACE_FUNCTION_SCOPE("Update for expired resynced prim");
 
         for (auto it = _outgoing.lower_bound(resyncedPath);

pxr/exec/exec/computationBuilders.h

@@ -508,6 +508,19 @@ struct Exec_ComputationBuilderAccessor
              ExecProviderResolution::DynamicTraversal::Local});
     }
 
+    /// See [IncomingConnections()](#exec_registration::IncomingConnections)
+    template <typename ResultType>
+    ValueSpecifier
+    IncomingConnections(const TfToken &computationName)
+    {
+        return ValueSpecifier(
+            computationName,
+            ExecTypeRegistry::GetInstance().CheckForRegistration<ResultType>(),
+            {Exec_ComputationBuilderAccessorBase::_GetLocalTraversal(),
+             ExecProviderResolution::DynamicTraversal::
+                 IncomingConnectionOwningAttributes});
+    }
+
     /// See [Metadata()](#exec_registration::Metadata)
     template <typename ResultType>
     ValueSpecifier
@@ -552,8 +565,7 @@ struct Exec_ComputationBuilderAttributeAccessor
     /// \addtogroup group_Exec_ValueSpecifiers
     /// @{
 
-    /// See
-    /// [Connections()](#exec_registration::Connections)
+    /// See [Connections()](#exec_registration::Connections)
     template <typename ResultType>
     ValueSpecifier
     Connections(const TfToken &computationName)
@@ -569,7 +581,7 @@ struct Exec_ComputationBuilderAttributeAccessor
     /// @}
 
     // XXX:TODO
-    // Accessors for AnimSpline, IncomingConnections
+    // Accessors for AnimSpline, etc.
 };
 
 /// Relationship accessor
@@ -1180,9 +1192,7 @@ AttributeValue(const TfToken &attributeName)
 /// 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. This
-/// concept exists in Presto and is extremely useful for rigging, so there's a
-/// good chance it will be introduced in the future in USD and OpenExec.
+/// allow for value-transforming behaviors on attribute connections themselves.
 ///
 /// The default input name is \p computationName; use `InputName` to specify a
 /// different input name.
@@ -1223,6 +1233,57 @@ Connections(const TfToken &computationName)
                  ConnectionTargetedObjects});
 }
 
+/// On any provider, requests input values from the computation \p
+/// computationName of type \p 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 \p computationName; use `InputName` to specify a
+/// different input name.
+///
+/// # Example
+///
+/// ```{.cpp}
+/// 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<int>(+[](const VdfContext &ctx) {
+///             VdfReadIteratorRange<int> range(
+///                 ctx, ExecBuiltinComputations->computeValue);
+///             return std::accumulate(range.begin(), range.end(), 0);
+///         })
+///         .Inputs(
+///             IncomingConnections<int>(ExecBuiltinComputations->computeValue));
+/// }
+/// ```
+///
+template <typename ResultType>
+auto
+IncomingConnections(const TfToken &computationName)
+{
+    return Exec_ComputationBuilderComputationValueSpecifier<
+        Exec_ComputationBuilderProviderTypes::Any>(
+            computationName,
+            ExecTypeRegistry::GetInstance().CheckForRegistration<ResultType>(),
+            {SdfPath::ReflexiveRelativePath(),
+             ExecProviderResolution::DynamicTraversal::
+                 IncomingConnectionOwningAttributes});
+}
+
 /// @} // Value Specifiers
 
 } // namespace exec_registration

pxr/exec/exec/definitionRegistry.cpp

@@ -510,7 +510,7 @@ Exec_DefinitionRegistry::_ValidateComputationRegistration(
 {
     if (schemaType.IsUnknown()) {
         TF_CODING_ERROR(
-            "Attempt to register computation '%s' using an unknown type.",
+            "Attempt to register computation '%s' using an unknown schema type.",
             computationName.GetText());
         return false;
     }

pxr/exec/exec/inputResolver.cpp

@@ -396,6 +396,49 @@ class _InputResolver
         return outputKeys;
     }
 
+    // Returns the ouput keys for the attributes that own connections that
+    // target the currrent object, for the computation of the given name and
+    // result type.
+    //
+    // The current object must be valid prior to calling this method.
+    //
+    Exec_OutputKeyVector _TraverseToIncomingConnectionOwningAttributes(
+        const TfToken &computationName,
+        const TfType resultType,
+        const TfToken &disambiguatingId)
+    {
+        if (!TF_VERIFY(_currentObject->IsValid(_journal))) {
+            return {};
+        }
+
+        Exec_OutputKeyVector outputKeys;
+
+        for (const SdfPath &path :
+                 _currentObject->GetIncomingConnections(_journal)) {
+            if (!_TraverseToAbsolutePath(path)) {
+                continue;
+            }
+
+            if (const Exec_ComputationDefinition *const computationDefinition =
+                _FindComputationDefinition(
+                    computationName,
+                    resultType,
+                    disambiguatingId)) {
+                outputKeys.emplace_back(
+                    _currentObject->AsObject(),
+                    _GetDispatchingConfigKeyForOutputKey(computationDefinition),
+                    computationDefinition);
+            }
+        }
+
+        // Clear the current object since the traversal has terminated.
+        _currentObjectVariant = std::monostate{};
+        _currentObject = nullptr;
+        _currentAttribute = nullptr;
+
+        return outputKeys;
+    }
+
     // Updates the current object to the nearest namespace ancestor that 
     // a computation named \p computationName with the given \p resultType.
     //
@@ -563,6 +606,13 @@ class _InputResolver
                 inputKey.resultType,
                 inputKey.disambiguatingId);
 
+        case ExecProviderResolution::DynamicTraversal::
+            IncomingConnectionOwningAttributes:
+            return _TraverseToIncomingConnectionOwningAttributes(
+                inputKey.computationName,
+                inputKey.resultType,
+                inputKey.disambiguatingId);
+            
         case ExecProviderResolution::DynamicTraversal::NamespaceAncestor:
             if (!_TraverseToNamespaceAncestor(
                 inputKey.computationName,

pxr/exec/exec/providerResolution.h

@@ -50,6 +50,10 @@ struct ExecProviderResolution {
         /// they target.
         ConnectionTargetedObjects,
 
+        /// Find providers by traversing incoming attribute connections to the
+        /// attributes that own them.
+        IncomingConnectionOwningAttributes,
+
         /// Find the provider by traversing upward in namespace
         NamespaceAncestor,
     };

pxr/exec/exec/systemChangeProcessor.cpp

@@ -53,12 +53,18 @@ ExecSystem::_ChangeProcessor::DidResync(const SdfPath &path)
 {
     // TODO: Resyncs on an object may trigger edit reasons on related objects.
     // (E.g. resync on /Prim.attr would trigger a ChangedPropertyList on /Prim)
-    // That would be handled here. For now, resync is the only supported edit
-    // reason.
+    // That would be handled here.
     _state->uncompiler.UncompileForSceneChange(
         path, EsfEditReason::ResyncedObject);
 }
 
+void
+ExecSystem::_ChangeProcessor::DidChangeIncomingConnections(const SdfPath &path)
+{
+    _state->uncompiler.UncompileForSceneChange(
+        path, EsfEditReason::ChangedIncomingConnections);
+}
+
 void
 ExecSystem::_ChangeProcessor::DidChangeInfoOnly(
     const SdfPath &path,

pxr/exec/exec/systemChangeProcessor.h

@@ -54,6 +54,12 @@ class ExecSystem::_ChangeProcessor
         const SdfPath &path,
         const TfTokenVector &changedFields);
 
+    /// Notifies the ExecSystem that the set of attribute connections that
+    /// target a scene object has changed.
+    ///
+    EXEC_API
+    void DidChangeIncomingConnections(const SdfPath &path);
+
 private:
     // Processes accumulated state from changes before the processor goes out of
     // scope.
@@ -70,4 +76,4 @@ class ExecSystem::_ChangeProcessor
 
 PXR_NAMESPACE_CLOSE_SCOPE
 
-#endif
+#endif