readWriteIterator.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_WRITE_ITERATOR_H
#define PXR_EXEC_VDF_READ_WRITE_ITERATOR_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/vdf/allocateBoxedValue.h"
#include "pxr/exec/vdf/boxedContainer.h"
#include "pxr/exec/vdf/input.h"
#include "pxr/exec/vdf/iterator.h"
#include "pxr/exec/vdf/mask.h"
#include "pxr/exec/vdf/node.h"
#include "pxr/exec/vdf/vector.h"
 
#include <memory>
 
PXR_NAMESPACE_OPEN_SCOPE
 
template<typename T>
class VdfReadWriteIterator final : public VdfIterator
{
public:
 
    using value_type = T;
 
    using difference_type = int;
 
    using reference = value_type &;
 
    using pointer = value_type *;
 
    using iterator_category = std::forward_iterator_tag;
 
    VdfReadWriteIterator(const VdfContext &context, const TfToken &name);
 
    explicit VdfReadWriteIterator(const VdfContext &context) :
        VdfReadWriteIterator(context, TfToken())
    {}
 
    static VdfReadWriteIterator Allocate(
        const VdfContext &context,
        const TfToken &name,
        size_t count);
 
    static VdfReadWriteIterator Allocate(
        const VdfContext &context,
        size_t count);
 
    bool operator==(const VdfReadWriteIterator &rhs) const;
 
    bool operator!=(const VdfReadWriteIterator &rhs) const {
        return !operator==(rhs);
    }
 
    VdfReadWriteIterator &operator++();
 
    reference operator*() const {
        TF_DEV_AXIOM( !IsAtEnd() );
        TF_DEV_AXIOM( *_iterator < _accessor.GetNumValues() );
        return _accessor[*_iterator];
    }
 
    pointer operator->() const {
        TF_DEV_AXIOM( !IsAtEnd() );
        TF_DEV_AXIOM( *_iterator < _accessor.GetNumValues() );
        return &_accessor[*_iterator];
    }
    
    bool IsAtEnd() const {
        return _iterator.IsAtEnd();
    }
 
    void AdvanceToEnd() {
        _iterator = VdfMask::Bits::AllSetView::const_iterator();
    }
 
private:
 
    // Default constructs a read/write iterator that is at end.
    VdfReadWriteIterator() : _output(nullptr) {}
 
    // Returns the current index into the data source.
    friend int Vdf_GetIteratorIndex(const VdfReadWriteIterator &it) {
        return *it._iterator;
    }
 
    // Initialize the iterator.
    void _Initialize(const VdfContext &context);
 
    // The output data accessor.
    VdfVector::ReadWriteAccessor<T> _accessor;
    
    // The mask iterator. Will iterate over the affects mask or the optional
    // bitset.
    VdfMask::Bits::AllSetView::const_iterator _iterator;
 
    // The optional bitset used for iteration over values with an empty
    // affects mask. A bitset is used instead of a mask, in order to avoid
    // contention on the mask registry lock.
    std::shared_ptr<VdfMask::Bits> _bits;
 
    // The source output.
    const VdfOutput *_output;
    
};
 
 
template<typename T>
VdfReadWriteIterator<T>::VdfReadWriteIterator(
    const VdfContext &context,
    const TfToken &name)
{
    // Get the required output, if available. This will issue a coding error if
    // the output is not available.
    _output = _GetRequiredOutputForWriting(context, name);
 
    // Initialize with the required output.
    if (_output) {
        _Initialize(context);
    }
}
 
template<typename T>
VdfReadWriteIterator<T>
VdfReadWriteIterator<T>::Allocate(
    const VdfContext &context,
    const TfToken &name,
    size_t count)
{
    return Vdf_AllocateBoxedValue<T>(context, name, count)
        ? VdfReadWriteIterator(context, name)
        : VdfReadWriteIterator();
}
 
template<typename T>
VdfReadWriteIterator<T>
VdfReadWriteIterator<T>::Allocate(
    const VdfContext &context,
    size_t count)
{
    return Vdf_AllocateBoxedValue<T>(context, TfToken(), count)
        ? VdfReadWriteIterator(context)
        : VdfReadWriteIterator();
}
 
template<typename T>
bool
VdfReadWriteIterator<T>::operator==(const VdfReadWriteIterator &rhs) const
{
    // The source outputs must match.
    if (_output != rhs._output) {
        return false;
    }
 
    // If either one iterate is at-end, the other one must be at-end too.
    const bool atEnd = IsAtEnd();
    const bool rhsAtEnd = rhs.IsAtEnd();
    if (atEnd || rhsAtEnd) {
        return atEnd == rhsAtEnd;
    }
 
    // If neither iterator is at-end, we can dereference the mask iterators and
    // compare the resulting indices.
    return *_iterator == *rhs._iterator;
}
 
template<typename T>
VdfReadWriteIterator<T> &
VdfReadWriteIterator<T>::operator++()
{
    ++_iterator;
    return *this;
}
 
template<typename T>
void
VdfReadWriteIterator<T>::_Initialize(const VdfContext &context)
{
    // Retrieve the affects and request masks.
    const VdfMask *requestMask = nullptr;
    const VdfMask *affectsMask = nullptr;
    if (!_GetOutputMasks(context, *_output, &requestMask, &affectsMask)) {
        return;
    }
 
    // Get the output value for writing. We always expect there to be one. It
    // should have been prepared by the executor engine.
    VdfVector *v = _GetOutputValueForWriting(context, *_output);
    if (!TF_VERIFY(
            v, "Output '%s' is missing buffer.",
            _output->GetName().GetText())) {
        return;
    }
 
    // Get the accessor to the data, and bail out if there is no data to
    // iterate over.
    _accessor = v->GetReadWriteAccessor<T>();
    if (_accessor.IsEmpty()) {
        return;
    }
 
    // If the affects mask size mismatches the number of data elements, iterate
    // over all of the available data. This includes the case where the affects
    // mask is empty (output does not have an affects mask) and where the value
    // is boxed.
    if (ARCH_UNLIKELY(affectsMask->GetSize() != _accessor.GetNumValues())) {
        TF_DEV_AXIOM(
            (affectsMask->IsEmpty()) ||
            (affectsMask->GetSize() == 1 && _accessor.IsBoxed()));
 
        _bits = std::make_shared<VdfMask::Bits>(_accessor.GetNumValues());
        _bits->Complement();
        _iterator = _bits->GetAllSetView().begin();
    }
 
    // If there is a valid affects mask, let's use it for iteration.
    else {
        _iterator = affectsMask->GetBits().GetAllSetView().begin();
    }
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif