controllerBuilder.h

Go to the documentation of this file.

//
// Copyright 2026 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_EXEC_EXEC_IR_CONTROLLER_BUILDER_H
#define PXR_EXEC_EXEC_IR_CONTROLLER_BUILDER_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/execIr/computations.h"
#include "pxr/exec/execIr/types.h"
 
#include "pxr/base/tf/staticData.h"
#include "pxr/base/tf/token.h"
#include "pxr/exec/exec/builtinComputations.h"
#include "pxr/exec/exec/computationBuilders.h"
#include "pxr/exec/vdf/executionTypeRegistry.h"
#include "pxr/exec/vdf/readIteratorRange.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
// Builder base class used to share common code.
//
class ExecIr_ControllerBuilderBase {
protected:
    EXECIR_API
    ExecIr_ControllerBuilderBase(
        ExecComputationBuilder &self);
 
    // The destructor is protected so that it's not possible to delete through
    // a base class pointer.
    //
    virtual ~ExecIr_ControllerBuilderBase();
 
    // Registers the 'explicitDesiredValue' and 'computedDesiredValue'
    // computations that are required to compute desired values, including
    // desired values that are expressed as overrides.
    //
    // TODO: These plugin computations won't be necessary when OpenExec provides
    // core inversion support.
    //
    template <typename ValueType>
    void
    _DesiredValueComputations(
        const TfToken &attributeName);
 
    // Sets the computation output to the value from the 'explicitDesiredValue'
    // input if it provides one; otherwise sets the output to the the
    // 'computeDesiredValue' input, if it has one; otherwise sets an empty
    // output value.
    //
    // If, among all considered inputs, more than one input value is provided,
    // an error is emitted.
    //
    // TODO: The compuations that use this callback won't be necessary when
    // OpenExec provides core inversion support.
    //
    template <typename ValueType>
    static void
    _GetExactlyOneDesiredValue(
        const VdfContext &ctx);
 
protected:
    ExecComputationBuilder &_self;
};
 
class ExecIrControllerBuilder : ExecIr_ControllerBuilderBase {
public:
 
    using Callback = ExecIrResult(*)(const VdfContext &);
 
    EXECIR_API
    ExecIrControllerBuilder(
        ExecComputationBuilder &self,
        Callback forwardCallback,
        Callback inverseCallback);
 
    EXECIR_API
    ~ExecIrControllerBuilder() override;
 
    template <typename ValueType>
    void
    InvertibleInputAttribute(
        const TfToken &attributeName);
 
    template <typename ValueType>
    void
    NonInvertibleInputAttribute(
        const TfToken &attributeName);
 
    template <typename ValueType>
    void
    InvertibleInputAttributes(
        const TfTokenVector &attributeNames) {
        for (const TfToken &attributeName : attributeNames) {
            InvertibleInputAttribute<ValueType>(attributeName);
        }
    }
 
    template <typename ValueType>
    void
    InvertibleOutputAttribute(
        const TfToken &attributeName);
 
    template <typename ValueType>
    void
    InvertibleOutputAttributes(
        const TfTokenVector &attributeNames) {
        for (const TfToken &attributeName : attributeNames) {
            InvertibleOutputAttribute<ValueType>(attributeName);
        }
    }
 
    template <typename ValueType>
    void
    SwitchAttribute(
        const TfToken &attributeName);
 
    template <typename ValueType>
    void
    PassthroughAttributes(
        const TfToken &inAttributeName,
        const TfToken &outAttributeName);
 
private:
    
    // These computations are registered by the controller builder, but they
    // are not meant to be consumed by code outside the controller builder.
    struct _PrivateComputationsType {
        EXECIR_API
        _PrivateComputationsType();
 
        const TfToken computeInvertedForwardValue;
        const TfToken forwardCompute;
        const TfToken inverseCompute;
    };
 
    EXECIR_API
    static TfStaticData<_PrivateComputationsType> _privateComputations;
 
    ExecPrimComputationBuilder _forwardComputeReg;
    ExecPrimComputationBuilder _inverseComputeReg;
    TfTokenVector _invertibleOutputAttributeNames;
    Callback _inverseCallback;
};
 
template <typename ValueType>
void
ExecIrControllerBuilder::InvertibleInputAttribute(
    const TfToken &attributeName)
{
    using namespace exec_registration;
 
    // Invertible input attributes define 'computeDesiredValue' computations
    // that extract their values from the inverse computation.
    //
    // TODO: When we have core inversion support, this plugin computation will
    // be registered using a builtin computation token that the core will
    // provide, as a plugin point for plugins that provide inversion behavior.
    _self.AttributeComputation(
        attributeName, ExecIrComputations->computeDesiredValue)
        .Callback<ValueType>([attributeName](const VdfContext &ctx) {
            const ExecIrResult &resultMap = ctx.GetInputValue<ExecIrResult>(
                    _privateComputations->inverseCompute);
 
            // If the inverse computation computed a value for this attribute,
            // return it; otherwise, set an empty result.
            if (const auto it = resultMap.find(attributeName);
                it != resultMap.end()) {
                ctx.SetOutput(it->second.Get<ValueType>());
            }
            else {
                ctx.SetEmptyOutput();
            }
        })
        .Inputs(
            Prim().Computation<ExecIrResult>(
                _privateComputations->inverseCompute));
 
    // Invertible input attributes define 'computeInvertedForwardValue'
    // computations that get their values from the inverse computation, but only
    // if they are evaluated in a context where the inverse is being computed
    // (i.e., when the inverse directly or transitively receives desired value
    // overrides). Otherwise, this computation falls back to the computed value
    // of the input attribute.
    // 
    // This allows for correct computation of inverses for "non-spanning"
    // controllers. I.e., this is important in cases where controller inverses
    // can't always satisfy all desired output values, and when one controller
    // is dependent on another. In such situations, computing "inverted forward
    // values" allows for controller networks to produce "best try" solutions.
    _self.AttributeComputation(
        attributeName, _privateComputations->computeInvertedForwardValue)
        .Callback(+[](const VdfContext &ctx) -> ValueType {
            // If we have a computed desired value, that takes precedence.
            if (const ValueType *const desiredValue =
                ctx.GetInputValuePtr<ValueType>(
                    ExecIrComputations->computeDesiredValue)) {
                return *desiredValue;
            }
 
            // Otherwise, return the attribute's computed value.
            return ctx.GetInputValue<ValueType>(
                ExecBuiltinComputations->computeValue);
        })
        .Inputs(
            Computation<ValueType>(ExecIrComputations->computeDesiredValue),
            Computation<ValueType>(ExecBuiltinComputations->computeValue));
 
    // Invertible input attributes provide inputs to the forward computation via
    // the 'computeInvertedForwardValue' computation.
    _forwardComputeReg.Inputs(
        Attribute(attributeName)
            .Computation<ValueType>(
                _privateComputations->computeInvertedForwardValue)
            .InputName(attributeName));
}
 
template <typename ValueType>
void
ExecIrControllerBuilder::NonInvertibleInputAttribute(
    const TfToken &attributeName)
{
    using namespace exec_registration;
 
    // All input attributes (invertible or not) are inputs to the forward
    // computation.
    _forwardComputeReg.Inputs(AttributeValue<ValueType>(attributeName));
 
    // Non-invertible input attributes are inputs to the inverse computation.
    _inverseComputeReg.Inputs(AttributeValue<ValueType>(attributeName));
}
 
template <typename ValueType>
void
ExecIrControllerBuilder::InvertibleOutputAttribute(
    const TfToken &attributeName)
{
    using namespace exec_registration;
 
    _invertibleOutputAttributeNames.push_back(attributeName);
 
    // Invertible outputs support computing desired values, for inversion.
    _DesiredValueComputations<ValueType>(attributeName);
 
    // Invertible outputs provide inputs to the inverse computation, getting
    // their values from the attribute's 'computeDesiredValue' computation.
    _inverseComputeReg.Inputs(
        Attribute(attributeName)
            .Computation<ValueType>(
                ExecIrComputations->computeDesiredValue)
            .InputName(attributeName));
 
    // Register an expression on the invertible output that pulls its value
    // from the forward computation result map.
    _self.AttributeExpression(attributeName)
        .Callback<ValueType>([attributeName](const VdfContext &ctx) {
            const ExecIrResult &resultMap =
                ctx.GetInputValue<ExecIrResult>(
                    _privateComputations->forwardCompute);
            const auto it = resultMap.find(attributeName);
            if (it != resultMap.end()) {
                ctx.SetOutput(it->second.Get<ValueType>());
            }
            else {
                TF_CODING_ERROR(
                    "Failed to find a result value for output attribute '%s' "
                    "when computing %s",
                    attributeName.GetText(),
                    ctx.GetNodeDebugName().c_str());
 
                ctx.SetOutput(
                    VdfExecutionTypeRegistry::GetInstance()
                        .GetFallback<ValueType>());
            }
        })
        .Inputs(
            Prim().Computation<ExecIrResult>(
                _privateComputations->forwardCompute));
}
 
template <typename ValueType>
void
ExecIrControllerBuilder::SwitchAttribute(
    const TfToken &attributeName)
{
    // TODO: We will have work to do here that is specific to switch attributes
    // when we implement more invertible rigging features. E.g., switch
    // attributes play a key role in determining which controllers contribute to
    // the current pose, and determining contributing controllers is critical
    // for supporing advanced authoring behaviors for invertible rigs.
 
    // Switch attributes have all the exec registrations that non-invertible
    // attributes have.
    NonInvertibleInputAttribute<ValueType>(attributeName);
}
 
template <typename ValueType>
void
ExecIrControllerBuilder::PassthroughAttributes(
    const TfToken &inAttributeName,
    const TfToken &outAttributeName)
{
    using namespace exec_registration;
 
    // Passthrough attributes are inputs to the forward and inverse
    // computations.
    _forwardComputeReg.Inputs(AttributeValue<ValueType>(inAttributeName));
    _inverseComputeReg.Inputs(AttributeValue<ValueType>(inAttributeName));
 
    // Passthrough attributes pass the value from the input attribute to the
    // output attribute.
    _self.AttributeExpression(outAttributeName)
        .Inputs(Prim().AttributeValue<ValueType>(inAttributeName))
        .template Callback<ValueType>([inAttributeName](const VdfContext &ctx) {
            ctx.SetOutputToReferenceInput(inAttributeName);
        });
}
 
template <typename ValueType>
void
ExecIr_ControllerBuilderBase::_DesiredValueComputations(
    const TfToken &attributeName)
{
    using namespace exec_registration;
 
    // The 'explicitDesiredValue' computation only exists to provide an output
    // where desired values can be specified as overrides passed to
    // ComputeWithOverrides.
    _self.AttributeComputation(
        attributeName, ExecIrComputations->explicitDesiredValue)
        .Callback<ValueType>(+[](const VdfContext &ctx) {
            ctx.SetEmptyOutput();
        });
 
    // The 'computeDesiredValue' computation gets its value from the
    // 'explicitDesiredValue' computation if it provides one, or from the
    // 'computeDesiredValue' computation via incoming connections--but only if
    // there is exactly one desired value present on these inputs. Otherwise, no
    // value is returned. An error is emitted if more than one desired value is
    // present.
    _self.AttributeComputation(
        attributeName, ExecIrComputations->computeDesiredValue)
        .Callback<ValueType>(&_GetExactlyOneDesiredValue<ValueType>)
        .Inputs(
            Computation<ValueType>(
                ExecIrComputations->explicitDesiredValue),
            IncomingConnections<ValueType>(
                ExecIrComputations->computeDesiredValue));
}
 
template <typename ValueType>
void
ExecIr_ControllerBuilderBase::_GetExactlyOneDesiredValue(
    const VdfContext &ctx)
{
    const ValueType *const inputValue = [&]() -> const ValueType*
    {
        const ValueType *foundInputValue =
            ctx.GetInputValuePtr<ValueType>(
                ExecIrComputations->explicitDesiredValue);
 
        for (const ValueType &value :
                 VdfReadIteratorRange<ValueType>(
                     ctx, ExecIrComputations->computeDesiredValue)) {
            if (!foundInputValue) {
                foundInputValue = &value;
            } else {
                // TODO: We will introduce an ExecValidationErrorType enum to
                // specifically identifiy this error condition.
                TF_RUNTIME_ERROR(
                    "Found more than one desired value for node %s",
                    ctx.GetNodeDebugName().c_str());
                return nullptr;
            }
        }
 
        return foundInputValue;
    }();
 
    if (inputValue) {
        ctx.SetOutput(*inputValue);
    } else {
        ctx.SetEmptyOutput();
    }
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif