readIterator.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_READ_ITERATOR_H
#define PXR_EXEC_VDF_READ_ITERATOR_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/vdf/connection.h"
#include "pxr/exec/vdf/iterator.h"
#include "pxr/exec/vdf/node.h"
#include "pxr/exec/vdf/poolChainIndex.h"
#include "pxr/exec/vdf/vector.h"
 
#include "pxr/base/tf/diagnostic.h"
 
#include <iterator>
 
PXR_NAMESPACE_OPEN_SCOPE
 
template<typename T>
class VdfReadIterator : public VdfIterator
{
public:
 
    using value_type = const T;
 
    using difference_type = int;
 
    using reference = value_type &;
 
    using pointer = value_type *;
 
    using iterator_category = std::forward_iterator_tag;
 
    VdfReadIterator(const VdfContext &context, const TfToken &inputName);
 
    bool operator==(const VdfReadIterator &rhs) const;
 
    bool operator!=(const VdfReadIterator &rhs) const {
        return !operator==(rhs);
    }
 
    VdfReadIterator &operator++();
 
    reference operator*() const {
        return *operator->();
    }
 
    pointer operator->() const;
 
    bool IsAtEnd() const {
        return _connectionIndex == -1;
    }
 
    size_t ComputeSize() const;
 
    void AdvanceToEnd();
 
private:
 
    // VdfSubrangeView has access to the private constructor.
    template<typename> friend class VdfSubrangeView;
 
    // Construct a read iterator beginning at the specified connection and boxed
    // index. Will seek to the next valid connection if the specified connection
    // does not provide data.
    VdfReadIterator(
        const VdfContext &context,
        const TfToken &inputName,
        int connectionIndex,
        unsigned int boxedIndex);
 
    // Returns the current index into the data source.
    friend int Vdf_GetIteratorIndex(const VdfReadIterator &it) {
        return *it._iterator + it._boxedIndex;
    }
 
    // Returns the name of the current data source.
    friend bool Vdf_IsIteratorSourcePool(const VdfReadIterator &it) {
        return Vdf_IsPoolOutput(
            (*it._input)[it._connectionIndex].GetSourceOutput());
    }
 
    // Sets the current connection from our input connector and returns true if
    // the connection is valid. If the connection is not valid, we need to jump
    // to the next connection. Returns true if the specified connection is
    // a valid data source.
    bool _SetCurrentConnection(int connectionIndex);
 
    // Sets the current boxed index to the specified index, or advances to the
    // next valid connection if the index exceeds the number of input values
    // available on this connection. Returns true if a valid data source is
    // available.
    bool _SetCurrentBoxedIndex(unsigned int boxedIndex);
 
    // Advances to the next input and returns true if one exists,
    // otherwise returns false to indicate at end. Returns true if there is
    // a valid data element to advance to.
    bool _Advance();
 
    // Advances to the next input connection with scheduled output data to
    // source from.
    bool _AdvanceConnection(int connectionIndex);
 
    // The context this iterator is bound to.
    const VdfContext *_context;
 
    // The input connector for this iterator.  This is where all the connections
    // that we are iterating through are connected.
    const VdfInput *_input;
 
    // The index of the current connection.
    int _connectionIndex;
 
    // The index of the current boxed value.
    unsigned int _boxedIndex;
 
    // The iterator for the connection mask.
    VdfMask::iterator _iterator;
 
    // The accessor into the current output value.
    VdfVector::ReadAccessor<T> _accessor;
 
};
 
 
template<typename T>
VdfReadIterator<T>::VdfReadIterator(
    const VdfContext &context, 
    const TfToken &inputName) :
    _context(&context),
    _input(_GetNode(context).GetInput(inputName)),
    _connectionIndex(-1),
    _boxedIndex(0)
{
    // If the input is not valid, or there are no input connections, this
    // iterator remains empty.
    if (!_input || _input->GetNumConnections() == 0) {
        return;
    }
 
    // Advance connections starting at the current connection index -1, to find
    // the first valid connection with data.
    if (!_AdvanceConnection(-1)) {
        AdvanceToEnd();
    }
}
 
template<typename T>
VdfReadIterator<T>::VdfReadIterator(
    const VdfContext &context, 
    const TfToken &inputName,
    int connectionIndex,
    unsigned int boxedIndex) :
    _context(&context),
    _input(_GetNode(context).GetInput(inputName)),
    _connectionIndex(-1),
    _boxedIndex(0)
{
    // If the input is not valid, or the specified connection index is beyond
    // the number of available connections, this iterator is at-end.
    if (!_input ||
        connectionIndex < 0 ||
        static_cast<size_t>(connectionIndex) >= _input->GetNumConnections()) {
        return;
    }
 
    // Advance to the next valid connection starting at the previous connection
    // index. If the previous connection index is -1, find the first valid
    // connection.
    if (!_AdvanceConnection(connectionIndex - 1) ||
        !_SetCurrentBoxedIndex(boxedIndex)) {
        AdvanceToEnd();
    }
}
 
template<typename T>
bool
VdfReadIterator<T>::operator==(const VdfReadIterator &rhs) const
{
    return
        _input == rhs._input &&
        _connectionIndex == rhs._connectionIndex &&
        _boxedIndex == rhs._boxedIndex &&
        _iterator == rhs._iterator;
}
 
template<typename T>
VdfReadIterator<T> &
VdfReadIterator<T>::operator++()
{
    // Are we already at end()?
    if (IsAtEnd()) {
        return *this;
    }
 
    // If not, advance to the next input.
    if (!_Advance()) {
        AdvanceToEnd();
    }
 
    return *this;
}
 
template<typename T>
typename VdfReadIterator<T>::pointer
VdfReadIterator<T>::operator->() const
{
    TF_DEV_AXIOM(!IsAtEnd());
    const size_t idx = *_iterator + _boxedIndex;
 
    TF_DEV_AXIOM(idx < _accessor.GetNumValues());
    return &_accessor[idx];
}
 
template<typename T>
size_t
VdfReadIterator<T>::ComputeSize() const
{
    // Bail out immediately if there is no data to iterate over.
    if (!_input || _input->GetNumConnections() == 0) {
        return 0;
    }
 
    // Fast path for single connection, boxed values.
    if (_input->GetNumConnections() == 1 && _accessor.IsBoxed()) {
        return _accessor.GetNumValues();
    }
 
    // Iterate over all the connections on the input connector.
    size_t size = 0;
    for (const VdfConnection *connection : _input->GetConnections()) {
 
        // For connections with 1x1 masks, we could be dealing with boxed
        // values, so we need to look at the stored value to figure out the
        // actual number of data values provided.
        const VdfMask &mask = connection->GetMask();
        if (mask.GetSize() == 1 && mask.IsAllOnes()) {
 
            // If this is a scheduled input value, account for the total number
            // of data values provided by the boxed container.
            if (_IsRequiredInput(*_context, *connection)) {  
 
                if (const VdfVector *v =
                    _GetInputValue(*_context, *connection, mask)) {
                    VdfVector::ReadAccessor<T> accessor = 
                        v->template GetReadAccessor<T>();
                    size += accessor.GetNumValues();
                }
            }
        }
 
        // For all other masks, the number of entries set in the mask is the
        // number of input values provided.
        else {
            size += mask.GetNumSet();
        }
    }
 
    // Return the number of input values provided.
    return size;
}
 
template<typename T>
void
VdfReadIterator<T>::AdvanceToEnd()
{
    _connectionIndex = -1;
    _boxedIndex = 0;
    _iterator = VdfMask::iterator();
}
 
template<typename T>
bool 
VdfReadIterator<T>::_SetCurrentConnection(int connectionIndex)
{
    const VdfConnection &connection = (*_input)[connectionIndex];
    const VdfMask &mask = connection.GetMask();
 
    // Reset all indices.
    _connectionIndex = connectionIndex;
    _boxedIndex = 0;
    _iterator = mask.begin();
 
    // Reset the accessor
    _accessor = VdfVector::ReadAccessor<T>();
 
    // See if the connection's source output is scheduled. This is not a
    // valid connection, if the source output is not scheduled.
    if (!_IsRequiredInput(*_context, connection)) {
        return false;
    }
 
    // Get the accessor to the data.
    const VdfVector *data = _GetInputValue(*_context, connection, mask);
    if (!data) {
        return false;
    }
    _accessor = data->GetReadAccessor<T>();
 
    // Return false if the connection does not provide any values.
    if (!_accessor.GetNumValues()) {
        return false;
    }
 
    // This is a valid connection if the iterator is valid.
    return !_iterator.IsAtEnd();
}
 
template<typename T>
bool
VdfReadIterator<T>::_SetCurrentBoxedIndex(unsigned int boxedIndex)
{
    // If the boxed index exceeds the number of available input values, move on
    // to the next valid connection, if any.
    if (boxedIndex >= _accessor.GetNumValues()) {
        return _AdvanceConnection(_connectionIndex);
    }
 
    // Apply the boxed index.
    _boxedIndex = boxedIndex;
 
    // Success!
    return true;
}
 
template<typename T>
bool
VdfReadIterator<T>::_Advance()
{
    // When iterating over boxed values, increment the index into the boxed
    // container.
    if (_accessor.IsBoxed()) {
        ++_boxedIndex;
 
        // After the last element in the boxed container, move on to the next
        // connection.
        if (_boxedIndex >= _accessor.GetNumValues()) {
            return _AdvanceConnection(_connectionIndex);
        }
    }
 
    // When iterating over values that are not boxed, increment the mask
    // iterator.
    else {
        ++_iterator;
 
        // After the last entry in the mask, move on to the next connection.
        if (_iterator.IsAtEnd()) {
            return _AdvanceConnection(_connectionIndex);
        }
    }
 
    // Successfully reached the next input value.
    return true;
}
 
template<typename T>
bool
VdfReadIterator<T>::_AdvanceConnection(int connectionIndex)
{
    // Note that we start at '_connectionIndex + 1' because we have already
    // iterated through the mask of the current connection.
    const int numConnections = _input->GetNumConnections();
    for (int i = connectionIndex + 1; i < numConnections; ++i) {
 
        // If the next connection has a scheduled data source, we are done.
        // Skip any data sources that provide no values.
        if (_SetCurrentConnection(i)) {
            return true;
        }
    }
 
    return false;
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif