vector.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_VECTOR_H
#define PXR_EXEC_VDF_VECTOR_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/exec/vdf/api.h"
#include "pxr/exec/vdf/boxedContainerTraits.h"
#include "pxr/exec/vdf/mask.h"
#include "pxr/exec/vdf/vectorAccessor.h"
#include "pxr/exec/vdf/vectorImpl_Boxed.h"
#include "pxr/exec/vdf/vectorImpl_Compressed.h"
#include "pxr/exec/vdf/vectorImpl_Contiguous.h"
#include "pxr/exec/vdf/vectorImpl_Empty.h"
#include "pxr/exec/vdf/vectorImpl_Shared.h"
#include "pxr/exec/vdf/vectorImpl_Single.h"
 
#include "pxr/base/arch/hints.h"
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/safeTypeCompare.h"
#include "pxr/base/vt/value.h"
 
#include <iosfwd>
#include <new>
#include <type_traits>
#include <typeinfo>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
template <typename T>
class Vdf_VectorSubrangeAccessor;
 
class VdfVector
{
public:
 
    VdfVector(const VdfVector &rhs)
    {
        // We need to new an empty impl because Clone() always expects
        // a valid _data to clone into.
        rhs._data.Get()->NewEmpty(0, &_data);
        rhs._data.Get()->Clone(&_data);
    }
 
    VdfVector(
        const VdfVector &rhs,
        const VdfMask &mask)
    {
        // CloneSubset expects valid _data to copy into, so first create
        // an empty vector.
        rhs._data.Get()->NewEmpty(0, &_data);
 
        // If the mask is all ones, take advange of the potentially faster 
        // Clone() method.
        if (mask.IsAllOnes()) {
            rhs._data.Get()->Clone(&_data);
        } else if (mask.IsAnySet()) {
            rhs._data.Get()->CloneSubset(mask, &_data);
        }
    }
 
    enum ConstructBoxedCopyTag {
        ConstructBoxedCopy
    };
 
    VdfVector(
        const VdfVector &rhs,
        const VdfMask &mask,
        ConstructBoxedCopyTag)
    {
        if (rhs.GetSize() != mask.GetSize()) {
            TF_CODING_ERROR(
                "size mismatch: rhs.GetSize() (%zu) != mask.GetSize() (%zu)",
                rhs.GetSize(), mask.GetSize());
        }
 
        // Box expects valid _data to copy into, so first create an
        // empty vector.
        rhs._data.Get()->NewEmpty(0, &_data);
        if (mask.IsAnySet()) {
            rhs._data.Get()->Box(mask.GetBits(), &_data);
        }
    }
 
    VdfVector(
        const VdfVector &rhs,
        size_t size)
    {
        if (size == 0) {
            rhs._data.Get()->NewEmpty(0, &_data);
        } else if (size == 1){
            rhs._data.Get()->NewSingle(&_data);
        } else{
            rhs._data.Get()->NewDense(size, &_data);
        }
    }
 
    VdfVector(VdfVector &&rhs)
    {
        rhs._data.Get()->NewEmpty(0, &_data);
        rhs._data.Get()->MoveInto(&_data);
    }
 
    ~VdfVector()
    {
        _data.Destroy();
    }
 
    size_t GetSize() const { return _data.Get()->GetSize(); }
 
    bool IsEmpty() const { return GetSize() == 0; }
 
    size_t GetNumStoredElements() const
    {
        return _data.Get()->GetNumStoredElements();
    }
 
    template<typename TYPE>
    void Set(TYPE &&data)
    {
        // We need to decay because TYPE is deduced as T& when l-values are
        // passed and T may also be cv-qualified.  This decayed type is what
        // is held by the underlying vector impl that provides storage.
        using T = typename std::decay<TYPE>::type;
 
        _CheckType<T>();
        _data.Destroy();
        _data.New<Vdf_VectorImplSingle<T>>(std::forward<TYPE>(data));
    }
 
    template <typename TYPE>
    void Set(const Vdf_BoxedContainer<TYPE> &data)
    {
        _CheckType<TYPE>();
        _data.Destroy();
        _data.New<Vdf_VectorImplBoxed<TYPE>>(data);
    }
    // Unfortunately, we have to provide overloads for all combinations of
    // const-qualification & reference category due to the unconstrained Set
    // overload.  Everything other than non-const rvalue reference gets
    // copied.
    //
    template <typename TYPE>
    void Set(Vdf_BoxedContainer<TYPE> &data)
    {
        const Vdf_BoxedContainer<TYPE> &cdata = data;
        this->Set(cdata);
    }
    template <typename TYPE>
    void Set(const Vdf_BoxedContainer<TYPE> &&data)
    {
        const Vdf_BoxedContainer<TYPE> &cdata = data;
        this->Set(cdata);
    }
 
    template <typename TYPE>
    void Set(Vdf_BoxedContainer<TYPE> &&data)
    {
        _CheckType<TYPE>();
        _data.Destroy();
        _data.New<Vdf_VectorImplBoxed<TYPE>>(std::move(data));
    }
 
    template<typename TYPE>
    void Resize(size_t size)
    {
        _CheckType<TYPE>();
 
        _data.Destroy();
 
        // Note that we never construct a compressed vector impl, here. The
        // purpose of this function is to resize the vector to be able to
        // accommodate all the data denoted in \p mask, but we do not support
        // merging data into a compressed vector without first uncompressing.
 
        if (size == 0)
            _data.New< Vdf_VectorImplEmpty<TYPE> >(0);
        else if (size == 1)
            _data.New< Vdf_VectorImplSingle<TYPE> >();
        else
            _data.New< Vdf_VectorImplContiguous<TYPE> >(size);
    }
 
    template<typename TYPE>
    void Resize(const VdfMask::Bits &bits)
    {
        _CheckType<TYPE>();
 
        _data.Destroy();
 
        // Note that we never construct a compressed vector impl, here. The
        // purpose of this function is to resize the vector to be able to
        // accommodate all the data denoted in \p bits, but we do not support
        // merging data into a compressed vector without first uncompressing.
 
        const size_t size = bits.GetSize();
 
        if (size == 0)
            _data.New< Vdf_VectorImplEmpty<TYPE> >(0);
        else if (size == 1)
            _data.New< Vdf_VectorImplSingle<TYPE> >();
        else if (bits.AreAllUnset())
            _data.New< Vdf_VectorImplEmpty<TYPE> >(size);
        else
            _data.New< Vdf_VectorImplContiguous<TYPE> >(bits);
    }
 
    VDF_API
    void Clear();
 
    void Copy(const VdfVector &rhs, const VdfMask &mask)
    {
        _CheckType(rhs);
 
        // Need to detach local data before copying into it if we are shared.
        if (ARCH_UNLIKELY(_data.Get()->GetInfo().ownership ==
            Vdf_VectorData::Info::Ownership::Shared)) {
            Vdf_VectorImplShared::Detach(&_data);
        }
 
        // If the mask is all ones, take advange of the potentially faster 
        // Clone() method.
        if (mask.IsAllOnes()) {
            rhs._data.Get()->Clone(&_data);
        }
 
        else if (mask.IsAnySet()) {
            rhs._data.Get()->CloneSubset(mask, &_data);
        } 
        
        // If the mask is all zeros, create an empty vector instead of
        // duplicating the rhs vector's implementation with an empty data
        // section. For compressed vectors, for example, this would cause
        // problems, because the index mapping would remain uninitialized,
        // essentially leaving the implementation in a broken state.
        else {
            _data.Destroy();
            rhs._data.Get()->NewEmpty(mask.GetSize(), &_data);
        }
    }
 
    VDF_API
    void Merge(const VdfVector &rhs, const VdfMask::Bits &bits);
 
    void Merge(const VdfVector &rhs, const VdfMask &mask) {
        Merge(rhs, mask.GetBits());
    }
 
    bool Share() const  
    {
        // Bail out if not sharable
        if (!_data.Get()->IsSharable()) {
            return false;
        }
 
        // Create the new shared impl in a temp DataHolder, _data is moved
        // into and held by a SharedSource.
        Vdf_VectorData::DataHolder tmp;
        tmp.New<Vdf_VectorImplShared>(&_data);
 
        // Move the new shared data into this vector's DataHolder.
        tmp.Get()->MoveInto(&_data);
        tmp.Destroy();
 
        return true;
    }
 
    bool IsShared() const
    {
        return _data.Get()->GetInfo().ownership == 
            Vdf_VectorData::Info::Ownership::Shared;
    }
 
    bool IsSharable() const
    {
        return _data.Get()->IsSharable();
    }
 
    template <typename T>
    VtArray<T>
    ExtractAsVtArray(const size_t size, const int offset) const
    {
        Vdf_VectorData* data = _data.Get();
        const Vdf_VectorData::Info& info = data->GetInfo();
 
        if (ARCH_UNLIKELY(info.compressedIndexMapping)) {
            return _DecompressAsVtArray(
                reinterpret_cast<T *>(info.data),
                *info.compressedIndexMapping, size, offset);
        }
 
        // Need to get a typed pointer to the first element. The memory layout
        // depends on if the vector is boxed or not. This is what 
        // Vdf_VectorAccessor does under the hood to provide element access.
        T *access;
        if (info.layout == Vdf_VectorData::Info::Layout::Boxed) {
            using BoxedVectorType = Vdf_BoxedContainer<T>;
            access = reinterpret_cast<BoxedVectorType *>(info.data)->data();
        } else {
            access = reinterpret_cast<T *>(info.data) - info.first;
        }
 
        access += offset;
 
        return info.ownership == Vdf_VectorData::Info::Ownership::Shared
            ? VtArray<T>(data->GetSharedSource(), access, size)
            : VtArray<T>(access, access + size);
    }
 
    template < typename TYPE >
    class ReadWriteAccessor {
    public:
 
        ReadWriteAccessor() = default;
 
        bool IsEmpty() const { return _accessor.IsEmpty(); }
 
        size_t GetNumValues() const { return _accessor.GetNumValues(); }
 
        bool IsBoxed() const { return _accessor.IsBoxed(); }
 
        TYPE &operator[](size_t i) const { return _accessor[i]; }
 
    private:
 
        // Only VdfVector is allowed to create instances of this class.
        friend class VdfVector;
 
        // The constructor used by VdfVector.
        ReadWriteAccessor(
            Vdf_VectorData *data,
            const Vdf_VectorData::Info &info) : 
            _accessor(data, info) 
        {}
 
        // The underlying accessor type.
        Vdf_VectorAccessor<TYPE> _accessor;
        
    };
 
    template<typename TYPE>
    ReadWriteAccessor<TYPE> GetReadWriteAccessor() const
    {
        Vdf_VectorData::Info info = _data.Get()->GetInfo();
 
        if (ARCH_UNLIKELY(info.ownership == 
            Vdf_VectorData::Info::Ownership::Shared)) {
 
            Vdf_VectorImplShared::Detach(&_data);
        
            // Update the info after detaching.
            info = _data.Get()->GetInfo();
        }
 
        return ReadWriteAccessor<TYPE>(_data.Get(), info);
    }
 
    template <typename TYPE>
    class ReadAccessor {
    public:
 
        ReadAccessor() = default;
 
        bool IsEmpty() const { return _accessor.IsEmpty(); }
 
        size_t GetNumValues() const { return _accessor.GetNumValues(); }
 
        bool IsBoxed() const { return _accessor.IsBoxed(); }
 
        const TYPE& operator[](size_t i) const { return _accessor[i]; }
 
    private:
 
        // Only VdfVector is allowed to create instances of this class.
        friend class VdfVector;
 
        // The constructor used by VdfVector. 
        ReadAccessor(
            Vdf_VectorData* data,
            const Vdf_VectorData::Info& info): 
            _accessor(data, info)
        {}
 
        // The underlying accessor type. 
        Vdf_VectorAccessor<TYPE> _accessor;
    };
 
    template <typename TYPE>
    ReadAccessor<TYPE> GetReadAccessor() const
    {
        return ReadAccessor<TYPE>(_data.Get(), _data.Get()->GetInfo());
    }
 
    template <typename TYPE>
    Vdf_VectorSubrangeAccessor<TYPE> GetSubrangeAccessor() const
    {
        return Vdf_VectorSubrangeAccessor<TYPE>(
            _data.Get(), _data.Get()->GetInfo());
    }
 
    template<typename TYPE>
    bool Holds() const
    {
        static_assert(
            !Vdf_IsBoxedContainer<TYPE>,
            "VdfVector::Holds cannot check for boxed-ness");
 
        return TfSafeTypeCompare(_GetTypeInfo(), typeid(TYPE));
    }
 
    VdfVector &operator=(const VdfVector &rhs)
    {
        if (&rhs == this)
            return *this;
 
        _CheckType(rhs);
 
        rhs._data.Get()->Clone(&_data);
 
        return *this;
    }
 
    VdfVector &operator=(VdfVector &&rhs)
    {
        if (&rhs == this)
            return *this;
 
        _CheckType(rhs);
 
        rhs._data.Get()->MoveInto(&_data);
 
        return *this;
    }
 
    size_t EstimateElementMemory() const
    {
        return _data.Get()->EstimateElementMemory();
    }
 
    class DebugPrintable {
    public:
 
        VDF_API
        friend std::ostream &operator<<(std::ostream &, const DebugPrintable &);
 
    private:
 
        // Only VdfVector is allowed to create instances of this class.
        friend class VdfVector;
 
        // Constructor.
        DebugPrintable(const Vdf_VectorData *data, const VdfMask &mask) :
            _data(data), _mask(mask)
        {}
 
        // The vector to be printed.
        const Vdf_VectorData *_data;
 
        // The mask denoting which elements in the vector should be printed.
        const VdfMask _mask;
 
    };
 
    DebugPrintable GetDebugPrintable(const VdfMask &mask) const
    {
        return DebugPrintable(_data.Get(), mask);
    }
 
// -----------------------------------------------------------------------------
 
protected:
 
    // Constructs an empty VdfVector.  Note that publicly we're only allowed
    // to create a VdfTypedVector.  See also
    // VdfExecutionTypeRegistry::CreateEmptyVector(const TfType&).
    //
    VdfVector()
    {
        // We rely on VdfTypedVector to make an empty data of the correct
        // type for the default construction case.
    }
 
private:
 
    // Helper for ExtractAsVtArray.
    //
    // Decompresses the contents of a compressed vector into a VtArray.
    // Compressed vectors are always copied because they're never sharable.
    template <typename T>
    static VtArray<T> _DecompressAsVtArray(
        const T* const access,
        const Vdf_CompressedIndexMapping &indexMapping,
        const size_t size,
        const int offset) {
 
        VtArray<T> array;
 
        // This is not a general purpose compressed vector copy.  VtArray
        // extraction requests a contiguous range of logical indices and we
        // assume that this cannot span multiple blocks of data.
        if (size_t dataIdx; _ComputeCompressedExtractionIndex(
                                indexMapping, size, offset, &dataIdx)) {
            const T* const src = access + dataIdx;
            array.assign(src, src+size);
        }
        return array;
    }
 
    // Computes the data index into a compressed vector impl for the logical
    // offset.
    //
    // Returns true if (offset, size) is contained in a single block of data
    // and a valid index was written to *dataIdx.  Otherwise, returns false.
    VDF_API
    static bool _ComputeCompressedExtractionIndex(
        const Vdf_CompressedIndexMapping &indexMapping,
        size_t size,
        int offset,
        size_t *dataIdx);
 
    // Helper function that delivers an error message when type checking fails.
    VDF_API
    static void _PostTypeError(
        const std::type_info &thisTypeInfo,
        const std::type_info &otherTypeInfo);
 
    void _CheckType(
        const std::type_info &otherTypeInfo) const
    {
        const std::type_info &thisTypeInfo = _GetTypeInfo();
        if (!TfSafeTypeCompare(thisTypeInfo, otherTypeInfo)) {
            _PostTypeError(thisTypeInfo, otherTypeInfo);
        }
    }
 
    void _CheckType(const VdfVector &rhs) const
    {
        _CheckType(rhs._GetTypeInfo());
    }
 
    template <typename TYPE>
    void _CheckType() const
    {
        _CheckType(typeid(TYPE));
    }
 
    const std::type_info &_GetTypeInfo() const
    {
        return _data.Get()->GetTypeInfo();
    }
 
protected:
 
    // Holder of the actual implementation of Vdf_VectorData that holds this 
    // vector's data.  This is protected so that it can be initialized from
    // our only derived class VdfTypedVector.
    mutable Vdf_VectorData::DataHolder _data;
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif