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;
 
    template<typename T>
    inline 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;
 
    template<typename T>
    inline void SetEmptyOutput() const;
 
    template<typename T>
    inline 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>
bool
VdfContext::HasInputValue(const TfToken &name) const
{
    // Note that we generally shouldn't have to check the result of
    // _GetFirstInputValue(name) here, as opposed to simply checking whether
    // there are any connections with non-zero masks on input.
    //
    // The one exception, unfortunately, is the EfSelectNode, which selects
    // amongst its inputs.  In the case where it doesn't have any inputs, it
    // doesn't set an output at all even though it is connected.  We technically
    // shouldn't be compiling a select node at all when there is no input, but
    // we do so to make sure that "first-time" constraints is fast.  We should
    // revisit that.
 
    return _GetFirstInputValue<T>(name);
}
 
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));
}
 
template<typename T>
void
VdfContext::SetEmptyOutput() const
{
    // 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.
    const VdfOutput *const output = _node.GetOutput();
    if (!output) {
        return;
    }
 
    VdfVector *const vector = _GetExecutor()._GetOutputValueForWriting(*output);
    if (!vector) {
        VDF_FATAL_ERROR(_GetNode(), "Couldn't get output vector.");
    }
 
    *vector = VdfTypedVector<T>();
}
 
template<typename T>
void
VdfContext::SetEmptyOutput(const TfToken &outputName) const
{
    // GetOutput emits an error if it returns null.
    const VdfOutput *const output = _node.GetOutput(outputName);
    if (!(output && _IsRequiredOutput(*output))) {
        return;
    }
 
    VdfVector *const vector = _GetExecutor()._GetOutputValueForWriting(*output);
    if (!vector) {
        VDF_FATAL_ERROR(_GetNode(), "Couldn't get output vector.");
    }
 
    *vector = VdfTypedVector<T>();
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif