context.h

Go to the documentation of this file.

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_EXEC_VDF_CONTEXT_H
#define PXR_EXEC_VDF_CONTEXT_H


#include "pxr/pxr.h"

#include "pxr/exec/vdf/api.h"
#include "pxr/exec/vdf/connection.h"
#include "pxr/exec/vdf/error.h"
#include "pxr/exec/vdf/evaluationState.h"
#include "pxr/exec/vdf/executionTypeRegistry.h"
#include "pxr/exec/vdf/executorInterface.h"
#include "pxr/exec/vdf/node.h"
#include "pxr/exec/vdf/scheduleTasks.h"
#include "pxr/exec/vdf/traits.h"
#include "pxr/exec/vdf/types.h"
#include "pxr/exec/vdf/vector.h"

#include "pxr/base/arch/attributes.h"
#include "pxr/base/arch/functionLite.h"
#include "pxr/base/tf/mallocTag.h"

PXR_NAMESPACE_OPEN_SCOPE

class TfToken;

class VdfContext
{
public:

    // VdfContext should not be copied or assigned to.
    VdfContext(const VdfContext &rhs) = delete;
    VdfContext &operator=(const VdfContext &rhs) = delete;

    VdfContext(
        const VdfEvaluationState &state,
        const VdfNode &node) :
        VdfContext(state, node, VdfScheduleTaskInvalid)
    {}

    VdfContext(
        const VdfEvaluationState &state,
        const VdfNode &node,
        const VdfScheduleTaskIndex invocation) :
        _state(state),
        _node(node),
        _invocation(invocation)
    {}

    template<typename T>
    inline VdfByValueOrConstRef<T>
    GetInputValue(const TfToken &name) const;

    template<typename T>
    inline const T *
    GetInputValuePtr(const TfToken &name) const;

    template<typename T>
    inline const T *
    GetInputValuePtr(const TfToken &name, const T *defPtr) const;

    VDF_API
    bool HasInputValue(const TfToken &name) const;

    VDF_API
    bool IsOutputRequested(const TfToken &outputName) const;

    template<typename T>
    inline void SetOutput(const TfToken &outputName,
                          const T &value) const;

    template<typename T>
    inline void SetOutput(const T &value) const;

    template<typename T>
    inline void SetOutput(T &&value) const;

    template<typename T>
    inline void SetOutput(const TfToken &outputName,
                          T &&value) const;

    VDF_API
    void SetEmptyOutput() const;

    VDF_API
    void SetEmptyOutput(const TfToken &outputName) const;

    VDF_API
    void SetOutputToReferenceInput(const TfToken &inputName) const;



    VDF_API
    void Warn(const char *fmt, ...) const ARCH_PRINTF_FUNCTION(2, 3);
          




    VDF_API
    std::string GetNodeDebugName() const;

    VDF_API
    void CodingError(const char *fmt, ...) const ARCH_PRINTF_FUNCTION(2, 3);



private:

    // This API is for VdfIterators to access internal context data.
    friend class VdfIterator;

    // Speculation nodes need to call _GetExecutor.
    friend class VdfSpeculationNode;

    // Returns the first input value on the given input, or a null pointer, if
    // no such value exists.
    //
    template<typename T>
    inline const T *_GetFirstInputValue(const TfToken &name) const;

    // Retrieves the request and affects mask of the requested output, if
    // available. Returns \c true if the output is scheduled, and \c false
    // otherwise.
    // 
    // Note, output must be an output on the current node!
    //
    VDF_API
    bool _GetOutputMasks(
        const VdfOutput &output,
        const VdfMask **requestMask,
        const VdfMask **affectsMask) const;

    // Returns true when the output is scheduled and required, and
    // false otherwise.  Used by special iterators to avoid computing outputs
    // that aren't necessary.
    //
    VDF_API
    bool _IsRequiredOutput(const VdfOutput &output) const;

    // Returns the request mask of \p output, if the output has been scheduled
    // and \c NULL otherwise.
    // 
    const VdfMask *_GetRequestMask(const VdfOutput &output) const;

    // Returns the current node
    //
    const VdfNode &_GetNode() const { return _node; }

    // Returns the executor for this context.
    //
    const VdfExecutorInterface &_GetExecutor() const { return _state.GetExecutor(); }

    // Returns the schedule for this context.
    //
    const VdfSchedule &_GetSchedule() const { return _state.GetSchedule(); }

    // Returns the error logger for this context.
    //
    VdfExecutorErrorLogger *_GetErrorLogger() const {
        return _state.GetErrorLogger();
    }

private:

    // The evaluation state
    const VdfEvaluationState &_state;

    // The node this context has been built for.
    const VdfNode &_node;

    // The current node invocation index. If this context is not for a node
    // with multiple invocations, this will be set to VdfScheduleTaskInvalid.
    const VdfScheduleTaskIndex _invocation;
};


template<typename T>
VdfByValueOrConstRef<T>
VdfContext::GetInputValue(const TfToken &name) const
{
    // Calling this API means that the client expects there to be one and
    // only one value, so we always return the first one here if there are 
    // any.
    if (const T *value = _GetFirstInputValue<T>(name)) {
        return *value;
    }

    TF_CODING_ERROR(
        "No input value for token '%s' on node '%s'",
        name.GetText(), GetNodeDebugName().c_str());

    // Ask the type registry for the fallback value to use.
    return VdfExecutionTypeRegistry::GetInstance().GetFallback<T>();
}

template<typename T>
inline const T *
VdfContext::GetInputValuePtr(const TfToken &name) const
{
    return _GetFirstInputValue<T>(name);
}

template<typename T>
inline const T *
VdfContext::GetInputValuePtr(const TfToken &name, const T *defPtr) const
{
    const T *value = _GetFirstInputValue<T>(name);
    return value ? value : defPtr;
}

template<typename T>
const T *
VdfContext::_GetFirstInputValue(const TfToken &name) const
{
    // We need to implement code fairly similar to what the VdfReadIterator has
    // to do.  The up side is that we can implement a more specific semantic
    // (namely that we return nullptr when the input is connected but not
    // executed, whereas the read iterator will error out).  Also we have the
    // opportunity to squeeze some performance out.  The downside is that we
    // have to make sure that whenever we return true, that the read iterator
    // can reasonably provide a value.  So the code must be kept at least
    // somewhat in sync.
    const VdfInput *input = _GetNode().GetInput(name);
    if (!input) {
        return nullptr;
    }

    for (const VdfConnection *connection : input->GetConnections()) {
        const VdfMask &mask = connection->GetMask();
        const size_t firstIndex = mask.GetFirstSet();
        if (firstIndex < mask.GetSize()) {
            // The connection has a mask on it, make sure there's a value
            // present.

            // Get the output to read the value from.
            const VdfVector *value = _GetExecutor()._GetInputValue(
                *connection, mask);

            if (value) {
                VdfVector::ReadAccessor<T> accessor = 
                    value->GetReadAccessor<T>();
                if (firstIndex < accessor.GetNumValues()) {
                    return &accessor[firstIndex];
                }
            }
        }
    }

    // No values on any of the connections.
    return nullptr;
}

template<typename T>
void
VdfContext::SetOutput(const TfToken &outputName,
                      const T &value) const
{
    TfAutoMallocTag2 tag("Vdf", "VdfContext::SetOutput");
    TfAutoMallocTag2 tag2("Vdf", __ARCH_PRETTY_FUNCTION__);

    // GetOutput emits an error if it returns NULL.
    const VdfOutput *output = _node.GetOutput(outputName);
    if (output && _IsRequiredOutput(*output))
        if (VdfVector *v = _GetExecutor()._GetOutputValueForWriting(*output))
            v->Set(value);
}

template<typename T>
void
VdfContext::SetOutput(const T &value) const
{
    TfAutoMallocTag2 tag("Vdf", "VdfContext::SetOutput");
    TfAutoMallocTag2 tag2("Vdf", __ARCH_PRETTY_FUNCTION__);

    // GetOutput emits an error if it returns NULL. Note that there is no need
    // to check _IsRequiredOutput: By virtue of the owning node being scheduled,
    // we can conclude that its only output is therefore scheduled.
    if (const VdfOutput *output = _node.GetOutput())
        if (VdfVector *v = _GetExecutor()._GetOutputValueForWriting(*output))
            v->Set(value);
}

template<typename T>
void
VdfContext::SetOutput(T &&value) const
{
    TfAutoMallocTag2 tag("Vdf", "VdfContext::SetOutput (move)");
    TfAutoMallocTag2 tag2("Vdf", __ARCH_PRETTY_FUNCTION__);

    // GetOutput emits an error if it returns NULL. Note that there is no need
    // to check _IsRequiredOutput: By virtue of the owning node being scheduled,
    // we can conclude that its only output is therefore scheduled.
    if (const VdfOutput *output = _node.GetOutput())
        if (VdfVector *v = 
                _GetExecutor()._GetOutputValueForWriting(*output))
            v->Set(std::forward<T>(value));
}

template<typename T>
void 
VdfContext::SetOutput(const TfToken &outputName,
                      T &&value) const
{
    TfAutoMallocTag2 tag("Vdf", "VdfContext::SetOutput (move)");
    TfAutoMallocTag2 tag2("Vdf", __ARCH_PRETTY_FUNCTION__);

    // GetOutput emits an error if it returns NULL.
    const VdfOutput *output = _node.GetOutput(outputName);
    if (output && _IsRequiredOutput(*output))
        if (VdfVector *v = _GetExecutor()._GetOutputValueForWriting(*output))
            v->Set(std::forward<T>(value));
}

PXR_NAMESPACE_CLOSE_SCOPE

#endif