AttributeSet.h

Go to the documentation of this file.

// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: MPL-2.0


#ifndef OPENVDB_POINTS_ATTRIBUTE_SET_HAS_BEEN_INCLUDED
#define OPENVDB_POINTS_ATTRIBUTE_SET_HAS_BEEN_INCLUDED

#include "AttributeArray.h"
#include <openvdb/version.h>
#include <openvdb/MetaMap.h>

#include <limits>
#include <memory>
#include <vector>


class TestAttributeSet;


namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
namespace points {


using GroupType = uint8_t;




class OPENVDB_API AttributeSet
{
public:
    enum { INVALID_POS = std::numeric_limits<size_t>::max() };

    using Ptr                   = std::shared_ptr<AttributeSet>;
    using ConstPtr              = std::shared_ptr<const AttributeSet>;
    using UniquePtr             = std::unique_ptr<AttributeSet>;

    class Descriptor;

    using DescriptorPtr         = std::shared_ptr<Descriptor>;
    using DescriptorConstPtr    = std::shared_ptr<const Descriptor>;


    struct Util
    {
        struct NameAndType {
            NameAndType(const std::string& n, const NamePair& t, const Index s = 1)
                : name(n), type(t), stride(s) {}
            Name name;
            NamePair type;
            Index stride;
        };

        using NameAndTypeVec    = std::vector<NameAndType>;
        using NameToPosMap      = std::map<std::string, size_t>;
        using GroupIndex        = std::pair<size_t, uint8_t>;
    };


    AttributeSet();

    AttributeSet(const AttributeSet& attributeSet, Index arrayLength,
        const AttributeArray::ScopedRegistryLock* lock = nullptr);

    AttributeSet(const DescriptorPtr& descriptor, Index arrayLength = 1,
        const AttributeArray::ScopedRegistryLock* lock = nullptr);

    AttributeSet(const AttributeSet&);

    AttributeSet& operator=(const AttributeSet&) = delete;

    Descriptor& descriptor() { return *mDescr; }
    const Descriptor& descriptor() const { return *mDescr; }

    DescriptorPtr descriptorPtr() const { return mDescr; }

    size_t size() const { return mAttrs.size(); }

    size_t memUsage() const;

    size_t find(const std::string& name) const;

    size_t replace(const std::string& name, const AttributeArray::Ptr&);

    size_t replace(size_t pos, const AttributeArray::Ptr&);

    const AttributeArray* getConst(const std::string& name) const;
    const AttributeArray* get(const std::string& name) const;
    AttributeArray*       get(const std::string& name);

    const AttributeArray* getConst(size_t pos) const;
    const AttributeArray* get(size_t pos) const;
    AttributeArray*       get(size_t pos);

    size_t groupOffset(const Name& groupName) const;
    size_t groupOffset(const Util::GroupIndex& index) const;

    Util::GroupIndex groupIndex(const Name& groupName) const;
    Util::GroupIndex groupIndex(const size_t offset) const;

    std::vector<size_t> groupAttributeIndices() const;

    bool isShared(size_t pos) const;
    void makeUnique(size_t pos);

    AttributeArray::Ptr appendAttribute(const Name& name,
                                        const NamePair& type,
                                        const Index strideOrTotalSize = 1,
                                        const bool constantStride = true,
                                        const Metadata* defaultValue = nullptr);

    OPENVDB_DEPRECATED
    AttributeArray::Ptr appendAttribute(const Name& name,
                                        const NamePair& type,
                                        const Index strideOrTotalSize,
                                        const bool constantStride,
                                        Metadata::Ptr defaultValue);

    AttributeArray::Ptr appendAttribute(const Descriptor& expected, DescriptorPtr& replacement,
                                        const size_t pos, const Index strideOrTotalSize = 1,
                                        const bool constantStride = true,
                                        const Metadata* defaultValue = nullptr,
                                        const AttributeArray::ScopedRegistryLock* lock = nullptr);

    OPENVDB_DEPRECATED
    AttributeArray::Ptr appendAttribute(const Descriptor& expected, DescriptorPtr& replacement,
                                        const size_t pos, const Index strideOrTotalSize,
                                        const bool constantStride,
                                        const AttributeArray::ScopedRegistryLock* lock);

    AttributeArray::Ptr removeAttribute(const Name& name);

    AttributeArray::Ptr removeAttribute(const size_t pos);

    AttributeArray::Ptr removeAttributeUnsafe(const size_t pos);

    void dropAttributes(const std::vector<size_t>& pos);

    void dropAttributes(const std::vector<size_t>& pos,
                        const Descriptor& expected, DescriptorPtr& replacement);

    void renameAttributes(const Descriptor& expected, const DescriptorPtr& replacement);

    void reorderAttributes(const DescriptorPtr& replacement);

    void resetDescriptor(const DescriptorPtr& replacement, const bool allowMismatchingDescriptors = false);

    void read(std::istream&);
    void write(std::ostream&, bool outputTransient = false) const;

    void readDescriptor(std::istream&);
    void writeDescriptor(std::ostream&, bool outputTransient = false) const;

    void readMetadata(std::istream&);
    void writeMetadata(std::ostream&, bool outputTransient = false, bool paged = false) const;

    void readAttributes(std::istream&);
    void writeAttributes(std::ostream&, bool outputTransient = false) const;

    bool operator==(const AttributeSet& other) const;
    bool operator!=(const AttributeSet& other) const { return !this->operator==(other); }

private:
    using AttrArrayVec = std::vector<AttributeArray::Ptr>;

    DescriptorPtr mDescr;
    AttrArrayVec  mAttrs;
}; // class AttributeSet



namespace future {
    class Container
    {
        class Element { };
        std::vector<std::shared_ptr<Element>> mElements;
    };
}




class OPENVDB_API AttributeSet::Descriptor
{
public:
    using Ptr               = std::shared_ptr<Descriptor>;

    using NameAndType       = Util::NameAndType;
    using NameAndTypeVec    = Util::NameAndTypeVec;
    using GroupIndex        = Util::GroupIndex;
    using NameToPosMap      = Util::NameToPosMap;
    using ConstIterator     = NameToPosMap::const_iterator;

    struct Inserter {
        NameAndTypeVec vec;
        Inserter& add(const NameAndType& nameAndType) {
            vec.push_back(nameAndType); return *this;
        }
        Inserter& add(const Name& name, const NamePair& type) {
            vec.emplace_back(name, type); return *this;
        }
        Inserter& add(const NameAndTypeVec& other) {
            for (NameAndTypeVec::const_iterator it = other.begin(), itEnd = other.end(); it != itEnd; ++it) {
                vec.emplace_back(it->name, it->type);
            }
            return *this;
        }
    };


    Descriptor();

    Descriptor(const Descriptor&);

    static Ptr create(const NamePair&);

    Ptr duplicateAppend(const Name& name, const NamePair& type) const;

    Ptr duplicateDrop(const std::vector<size_t>& pos) const;

    size_t size() const { return mTypes.size(); }

    size_t count(const NamePair& type) const;

    size_t memUsage() const;

    size_t find(const std::string& name) const;

    size_t rename(const std::string& fromName, const std::string& toName);

    const Name& valueType(size_t pos) const;
    const NamePair& type(size_t pos) const;

    MetaMap& getMetadata();
    const MetaMap& getMetadata() const;

    bool hasDefaultValue(const Name& name) const;
    template<typename ValueType>
    ValueType getDefaultValue(const Name& name) const
    {
        const size_t pos = find(name);
        if (pos == INVALID_POS) {
            OPENVDB_THROW(LookupError, "Cannot find attribute name to set default value.")
        }

        std::stringstream ss;
        ss << "default:" << name;

        auto metadata = mMetadata.getMetadata<TypedMetadata<ValueType>>(ss.str());

        if (metadata)   return metadata->value();

        return zeroVal<ValueType>();
    }
    void setDefaultValue(const Name& name, const Metadata& defaultValue);
    // Remove the default value if it exists
    void removeDefaultValue(const Name& name);
    // Prune any default values for which the key is no longer present
    void pruneUnusedDefaultValues();

    bool operator==(const Descriptor&) const;
    bool operator!=(const Descriptor& rhs) const { return !this->operator==(rhs); }
    bool hasSameAttributes(const Descriptor& rhs) const;

    const NameToPosMap& map() const { return mNameMap; }
    const NameToPosMap& groupMap() const { return mGroupMap; }

    bool hasGroup(const Name& group) const;
    void setGroup(const Name& group, const size_t offset,
        const bool checkValidOffset = false);
    void dropGroup(const Name& group);
    void clearGroups();
    size_t renameGroup(const std::string& fromName, const std::string& toName);
    const Name uniqueGroupName(const Name& name) const;

    size_t groupOffset(const Name& groupName) const;
    size_t groupOffset(const GroupIndex& index) const;

    GroupIndex groupIndex(const Name& groupName) const;
    GroupIndex groupIndex(const size_t offset) const;

    static size_t groupBits() { return sizeof(GroupType) * CHAR_BIT; }

    size_t availableGroups() const;

    size_t unusedGroups() const;

    bool canCompactGroups() const;

    size_t unusedGroupOffset(size_t hint = std::numeric_limits<size_t>::max()) const;

    OPENVDB_DEPRECATED
    size_t nextUnusedGroupOffset() const;

    bool requiresGroupMove(Name& sourceName, size_t& sourceOffset, size_t& targetOffset) const;

    bool groupIndexCollision(const Descriptor& rhs) const;

    const Name uniqueName(const Name& name) const;

    static bool validName(const Name& name);

    static void parseNames( std::vector<std::string>& includeNames,
                            std::vector<std::string>& excludeNames,
                            bool& includeAll,
                            const std::string& nameStr);

    static void parseNames( std::vector<std::string>& includeNames,
                            std::vector<std::string>& excludeNames,
                            const std::string& nameStr);

    void write(std::ostream&) const;
    void read(std::istream&);

protected:
    void appendTo(NameAndTypeVec& attrs) const;

    static Ptr create(const NameAndTypeVec&, const NameToPosMap&, const MetaMap&);

    size_t insert(const std::string& name, const NamePair& typeName);

private:
    friend class ::TestAttributeSet;

    NameToPosMap                mNameMap;
    std::vector<NamePair>       mTypes;
    NameToPosMap                mGroupMap;
    MetaMap                     mMetadata;
    // as this change is part of an ABI change, there's no good reason to reduce the reserved
    // space aside from keeping the memory size of an AttributeSet the same for convenience
    // (note that this assumes a typical three-pointer implementation for std::vector)
    future::Container           mFutureContainer;   // occupies 3 reserved slots
    int64_t                     mReserved[5];       // for future use
}; // class Descriptor

} // namespace points
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb

#endif // OPENVDB_POINTS_ATTRIBUTE_ARRAY_HAS_BEEN_INCLUDED