Element.h

Go to the documentation of this file.

//
// Copyright Contributors to the MaterialX Project
// SPDX-License-Identifier: Apache-2.0
//
 
#ifndef MATERIALX_ELEMENT_H
#define MATERIALX_ELEMENT_H

 
#include <MaterialXCore/Export.h>
 
#include <MaterialXCore/Traversal.h>
#include <MaterialXCore/Util.h>
#include <MaterialXCore/Value.h>
 
MATERIALX_NAMESPACE_BEGIN
 
class Element;
class TypedElement;
class ValueElement;
class Token;
class CommentElement;
class NewlineElement;
class GenericElement;
class StringResolver;
class Document;

using ElementPtr = shared_ptr<Element>;
using ConstElementPtr = shared_ptr<const Element>;

using TypedElementPtr = shared_ptr<TypedElement>;
using ConstTypedElementPtr = shared_ptr<const TypedElement>;

using ValueElementPtr = shared_ptr<ValueElement>;
using ConstValueElementPtr = shared_ptr<const ValueElement>;

using TokenPtr = shared_ptr<Token>;
using ConstTokenPtr = shared_ptr<const Token>;

using CommentElementPtr = shared_ptr<CommentElement>;
using ConstCommentElementPtr = shared_ptr<const CommentElement>;

using NewlineElementPtr = shared_ptr<NewlineElement>;
using ConstNewlineElementPtr = shared_ptr<const NewlineElement>;

using GenericElementPtr = shared_ptr<GenericElement>;
using ConstGenericElementPtr = shared_ptr<const GenericElement>;

using StringResolverPtr = shared_ptr<StringResolver>;

using ElementVec = vector<ElementPtr>;

using ElementMap = std::unordered_map<string, ElementPtr>;

using ElementPredicate = std::function<bool(ConstElementPtr)>;
 
class ElementEquivalenceOptions;

class MX_CORE_API Element : public std::enable_shared_from_this<Element>
{
  protected:
    Element(ElementPtr parent, const string& category, const string& name) :
        _category(category),
        _name(name),
        _parent(parent),
        _root(parent ? parent->getRoot() : nullptr)
    {
    }
 
  public:
    virtual ~Element() { }
    Element(const Element&) = delete;
    Element& operator=(const Element&) = delete;
 
  protected:
    using DocumentPtr = shared_ptr<Document>;
    using ConstDocumentPtr = shared_ptr<const Document>;
 
    template <class T> friend class ElementRegistry;
 
  public:
    bool operator==(const Element& rhs) const;

    bool operator!=(const Element& rhs) const;


    void setCategory(const string& category)
    {
        _category = category;
    }

    const string& getCategory() const
    {
        return _category;
    }


    void setName(const string& name);

    const string& getName() const
    {
        return _name;
    }

    string getNamePath(ConstElementPtr relativeTo = nullptr) const;

    ElementPtr getDescendant(const string& namePath) const;


    void setFilePrefix(const string& prefix)
    {
        setAttribute(FILE_PREFIX_ATTRIBUTE, prefix);
    }

    bool hasFilePrefix() const
    {
        return hasAttribute(FILE_PREFIX_ATTRIBUTE);
    }

    const string& getFilePrefix() const
    {
        return getAttribute(FILE_PREFIX_ATTRIBUTE);
    }

    const string& getActiveFilePrefix() const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            if (elem->hasFilePrefix())
            {
                return elem->getFilePrefix();
            }
        }
        return EMPTY_STRING;
    }


    void setGeomPrefix(const string& prefix)
    {
        setAttribute(GEOM_PREFIX_ATTRIBUTE, prefix);
    }

    bool hasGeomPrefix() const
    {
        return hasAttribute(GEOM_PREFIX_ATTRIBUTE);
    }

    const string& getGeomPrefix() const
    {
        return getAttribute(GEOM_PREFIX_ATTRIBUTE);
    }

    const string& getActiveGeomPrefix() const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            if (elem->hasGeomPrefix())
            {
                return elem->getGeomPrefix();
            }
        }
        return EMPTY_STRING;
    }


    void setColorSpace(const string& colorSpace)
    {
        setAttribute(COLOR_SPACE_ATTRIBUTE, colorSpace);
    }

    bool hasColorSpace() const
    {
        return hasAttribute(COLOR_SPACE_ATTRIBUTE);
    }

    const string& getColorSpace() const
    {
        return getAttribute(COLOR_SPACE_ATTRIBUTE);
    }

    const string& getActiveColorSpace() const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            if (elem->hasColorSpace())
            {
                return elem->getColorSpace();
            }
        }
        return EMPTY_STRING;
    }


    void setInheritString(const string& inherit)
    {
        setAttribute(INHERIT_ATTRIBUTE, inherit);
    }

    bool hasInheritString() const
    {
        return hasAttribute(INHERIT_ATTRIBUTE);
    }

    const string& getInheritString() const
    {
        return getAttribute(INHERIT_ATTRIBUTE);
    }

    void setInheritsFrom(ConstElementPtr super)
    {
        if (super)
        {
            setInheritString(super->getName());
        }
        else
        {
            removeAttribute(INHERIT_ATTRIBUTE);
        }
    }

    ElementPtr getInheritsFrom() const
    {
        return hasInheritString() ? resolveNameReference<Element>(getInheritString()) : nullptr;
    }

    bool hasInheritedBase(ConstElementPtr base) const;

    bool hasInheritanceCycle() const;


    void setNamespace(const string& space)
    {
        setAttribute(NAMESPACE_ATTRIBUTE, space);
    }

    bool hasNamespace() const
    {
        return hasAttribute(NAMESPACE_ATTRIBUTE);
    }

    const string& getNamespace() const
    {
        return getAttribute(NAMESPACE_ATTRIBUTE);
    }

    string getQualifiedName(const string& name) const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            const string& namespaceStr = elem->getNamespace();
            if (!namespaceStr.empty())
            {
                // Check if the name is qualified already.
                const size_t i = name.find_first_of(NAME_PREFIX_SEPARATOR);
                if (i != string::npos && name.substr(0, i) == namespaceStr)
                {
                    // The name is already qualified with this namespace,
                    // so just return it as is.
                    return name;
                }
                return namespaceStr + NAME_PREFIX_SEPARATOR + name;
            }
        }
        return name;
    }


    void setDocString(const string& doc)
    {
        setAttribute(DOC_ATTRIBUTE, doc);
    }

    string getDocString() const
    {
        return getAttribute(DOC_ATTRIBUTE);
    }


    template <class T> bool isA(const string& category = EMPTY_STRING) const
    {
        if (!asA<T>())
            return false;
        if (!category.empty() && getCategory() != category)
            return false;
        return true;
    }

    template <class T> shared_ptr<T> asA();

    template <class T> shared_ptr<const T> asA() const;


    template <class T> shared_ptr<T> addChild(const string& name = EMPTY_STRING);

    ElementPtr addChildOfCategory(const string& category, string name = EMPTY_STRING);

    ElementPtr changeChildCategory(ElementPtr child, const string& category);

    ElementPtr getChild(const string& name) const;

    template <class T> shared_ptr<T> getChildOfType(const string& name) const;

    const ElementVec& getChildren() const
    {
        return _childOrder;
    }

    template <class T> vector<shared_ptr<T>> getChildrenOfType(const string& category = EMPTY_STRING) const;

    void setChildIndex(const string& name, int index);

    int getChildIndex(const string& name) const;

    void removeChild(const string& name);

    template <class T> void removeChildOfType(const string& name)
    {
        if (getChildOfType<T>(name))
            removeChild(name);
    }


    void setAttribute(const string& attrib, const string& value);

    bool hasAttribute(const string& attrib) const
    {
        return _attributeMap.count(attrib) != 0;
    }

    const string& getAttribute(const string& attrib) const
    {
        StringMap::const_iterator it = _attributeMap.find(attrib);
        return (it != _attributeMap.end()) ? it->second : EMPTY_STRING;
    }

    const StringVec& getAttributeNames() const
    {
        return _attributeOrder;
    }

    template <class T> void setTypedAttribute(const string& attrib, const T& data)
    {
        setAttribute(attrib, toValueString(data));
    }

    template <class T> T getTypedAttribute(const string& attrib) const
    {
        if (hasAttribute(attrib))
        {
            try
            {
                return fromValueString<T>(getAttribute(attrib));
            }
            catch (ExceptionTypeError&)
            {
            }
        }
        return {};
    }

    void removeAttribute(const string& attrib);


    ElementPtr getSelf()
    {
        return shared_from_this();
    }

    ConstElementPtr getSelf() const
    {
        return shared_from_this();
    }

    ElementPtr getParent()
    {
        return _parent.lock();
    }

    ConstElementPtr getParent() const
    {
        return _parent.lock();
    }

    ElementPtr getRoot();

    ConstElementPtr getRoot() const;

    DocumentPtr getDocument();

    ConstDocumentPtr getDocument() const;

    template <class T> shared_ptr<T> getAncestorOfType()
    {
        for (ElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            shared_ptr<T> typedElem = elem->asA<T>();
            if (typedElem)
            {
                return typedElem;
            }
        }
        return nullptr;
    }

    template <class T> shared_ptr<const T> getAncestorOfType() const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            shared_ptr<const T> typedElem = elem->asA<T>();
            if (typedElem)
            {
                return typedElem;
            }
        }
        return nullptr;
    }


    bool isEquivalent(ConstElementPtr rhs, const ElementEquivalenceOptions& options,
                      string* message = nullptr) const;

    virtual bool isAttributeEquivalent(ConstElementPtr rhs, const string& attributeName,
                                       const ElementEquivalenceOptions& options, 
                                       string* message = nullptr) const;


    TreeIterator traverseTree() const;

    GraphIterator traverseGraph() const;

    virtual Edge getUpstreamEdge(size_t index = 0) const;

    virtual size_t getUpstreamEdgeCount() const
    {
        return 0;
    }

    ElementPtr getUpstreamElement(size_t index = 0) const;

    InheritanceIterator traverseInheritance() const;


    void setSourceUri(const string& sourceUri)
    {
        _sourceUri = sourceUri;
    }

    bool hasSourceUri() const
    {
        return !_sourceUri.empty();
    }

    const string& getSourceUri() const
    {
        return _sourceUri;
    }

    const string& getActiveSourceUri() const
    {
        for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
        {
            if (elem->hasSourceUri())
            {
                return elem->getSourceUri();
            }
        }
        return EMPTY_STRING;
    }


    virtual bool validate(string* message = nullptr) const;


    void copyContentFrom(const ConstElementPtr& source);

    virtual void clearContent();

    string createValidChildName(string name) const
    {
        name = name.empty() ? "_" : createValidName(name);
        while (getChild(name))
        {
            name = incrementName(name);
        }
        return name;
    }

    StringResolverPtr createStringResolver(const string& geom = EMPTY_STRING) const;

    string asString() const;

 
  protected:
    // Resolve a reference to a named element at the scope of the given parent,
    // taking the namespace at the scope of this element into account.  If no parent
    // is provided, then the root scope of the document is used.
    template <class T> shared_ptr<T> resolveNameReference(const string& name, ConstElementPtr parent = nullptr) const
    {
        ConstElementPtr scope = parent ? parent : getRoot();
        shared_ptr<T> child = scope->getChildOfType<T>(getQualifiedName(name));
        return child ? child : scope->getChildOfType<T>(name);
    }
 
    // Enforce a requirement within a validate method, updating the validation
    // state and optional output text if the requirement is not met.
    void validateRequire(bool expression, bool& res, string* message, const string& errorDesc) const;
 
  public:
    static const string NAME_ATTRIBUTE;
    static const string FILE_PREFIX_ATTRIBUTE;
    static const string GEOM_PREFIX_ATTRIBUTE;
    static const string COLOR_SPACE_ATTRIBUTE;
    static const string INHERIT_ATTRIBUTE;
    static const string NAMESPACE_ATTRIBUTE;
    static const string DOC_ATTRIBUTE;
    static const string XPOS_ATTRIBUTE;
    static const string YPOS_ATTRIBUTE;
 
  protected:
    virtual void registerChildElement(ElementPtr child);
    virtual void unregisterChildElement(ElementPtr child);
 
    // Return a non-const copy of our self pointer, for use in constructing
    // graph traversal objects that require non-const storage.
    ElementPtr getSelfNonConst() const
    {
        return std::const_pointer_cast<Element>(shared_from_this());
    }
 
  protected:
    string _category;
    string _name;
    string _sourceUri;
 
    ElementMap _childMap;
    ElementVec _childOrder;
 
    StringMap _attributeMap;
    StringVec _attributeOrder;
 
    weak_ptr<Element> _parent;
    weak_ptr<Element> _root;
 
  private:
    template <class T> static ElementPtr createElement(ElementPtr parent, const string& name)
    {
        return std::make_shared<T>(parent, name);
    }
 
  private:
    using CreatorFunction = ElementPtr (*)(ElementPtr, const string&);
    using CreatorMap = std::unordered_map<string, CreatorFunction>;
 
    static CreatorMap _creatorMap;
};

class MX_CORE_API TypedElement : public Element
{
  protected:
    TypedElement(ElementPtr parent, const string& category, const string& name) :
        Element(parent, category, name)
    {
    }
 
  public:
    virtual ~TypedElement() { }
 
  protected:
    using TypeDefPtr = shared_ptr<class TypeDef>;
 
  public:

    void setType(const string& type)
    {
        setAttribute(TYPE_ATTRIBUTE, type);
    }

    bool hasType() const
    {
        return hasAttribute(TYPE_ATTRIBUTE);
    }

    virtual const string& getType() const
    {
        return getAttribute(TYPE_ATTRIBUTE);
    }

    bool isColorType() const
    {
        return getType() == "color3" || getType() == "color4";
    }

    bool isMultiOutputType() const
    {
        return getType() == MULTI_OUTPUT_TYPE_STRING;
    }


    TypeDefPtr getTypeDef() const;

 
  public:
    static const string TYPE_ATTRIBUTE;
};

class MX_CORE_API ValueElement : public TypedElement
{
  protected:
    ValueElement(ElementPtr parent, const string& category, const string& name) :
        TypedElement(parent, category, name)
    {
    }
 
  public:
    virtual ~ValueElement() { }


    void setValueString(const string& value)
    {
        setAttribute(VALUE_ATTRIBUTE, value);
    }

    bool hasValueString() const
    {
        return hasAttribute(VALUE_ATTRIBUTE);
    }

    const string& getValueString() const
    {
        return getAttribute(VALUE_ATTRIBUTE);
    }

    string getResolvedValueString(StringResolverPtr resolver = nullptr) const;


    void setInterfaceName(const string& name)
    {
        setAttribute(INTERFACE_NAME_ATTRIBUTE, name);
    }

    bool hasInterfaceName() const
    {
        return hasAttribute(INTERFACE_NAME_ATTRIBUTE);
    }

    const string& getInterfaceName() const
    {
        return getAttribute(INTERFACE_NAME_ATTRIBUTE);
    }


    void setImplementationName(const string& name)
    {
        setAttribute(IMPLEMENTATION_NAME_ATTRIBUTE, name);
    }

    bool hasImplementationName() const
    {
        return hasAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
    }

    const string& getImplementationName() const
    {
        return getAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
    }


    template <class T> void setValue(const T& value, const string& type = EMPTY_STRING)
    {
        setType(!type.empty() ? type : getTypeString<T>());
        setValueString(toValueString(value));
    }

    void setValue(const char* value, const string& type = EMPTY_STRING)
    {
        setValue(value ? string(value) : EMPTY_STRING, type);
    }

    bool hasValue() const
    {
        return hasAttribute(VALUE_ATTRIBUTE);
    }

    ValuePtr getValue() const;

    ValuePtr getResolvedValue(StringResolverPtr resolver = nullptr) const;

    ValuePtr getDefaultValue() const;


    void setUnit(const string& unit)
    {
        setAttribute(UNIT_ATTRIBUTE, unit);
    }

    bool hasUnit() const
    {
        return hasAttribute(UNIT_ATTRIBUTE);
    }

    const string& getUnit() const
    {
        return getAttribute(UNIT_ATTRIBUTE);
    }

    const string& getActiveUnit() const;

    void setUnitType(const string& unit)
    {
        setAttribute(UNITTYPE_ATTRIBUTE, unit);
    }

    bool hasUnitType() const
    {
        return hasAttribute(UNITTYPE_ATTRIBUTE);
    }

    const string& getUnitType() const
    {
        return getAttribute(UNITTYPE_ATTRIBUTE);
    }


    void setIsUniform(bool value)
    {
        setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
    }

    bool getIsUniform() const
    {
        return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
    }


    bool isAttributeEquivalent(ConstElementPtr rhs, const string& attributeName,
                               const ElementEquivalenceOptions& options, 
                               string* message = nullptr) const override;


    bool validate(string* message = nullptr) const override;

 
  public:
    static const string VALUE_ATTRIBUTE;
    static const string INTERFACE_NAME_ATTRIBUTE;
    static const string IMPLEMENTATION_NAME_ATTRIBUTE;
    static const string IMPLEMENTATION_TYPE_ATTRIBUTE;
    static const string ENUM_ATTRIBUTE;
    static const string ENUM_VALUES_ATTRIBUTE;
    static const string UI_NAME_ATTRIBUTE;
    static const string UI_FOLDER_ATTRIBUTE;
    static const string UI_MIN_ATTRIBUTE;
    static const string UI_MAX_ATTRIBUTE;
    static const string UI_SOFT_MIN_ATTRIBUTE;
    static const string UI_SOFT_MAX_ATTRIBUTE;
    static const string UI_STEP_ATTRIBUTE;
    static const string UI_ADVANCED_ATTRIBUTE;
    static const string UNIT_ATTRIBUTE;
    static const string UNITTYPE_ATTRIBUTE;
    static const string UNIFORM_ATTRIBUTE;
};

class MX_CORE_API Token : public ValueElement
{
  public:
    Token(ElementPtr parent, const string& name) :
        ValueElement(parent, CATEGORY, name)
    {
    }
    virtual ~Token() { }
 
  public:
    static const string CATEGORY;
};

class MX_CORE_API CommentElement : public Element
{
  public:
    CommentElement(ElementPtr parent, const string& name) :
        Element(parent, CATEGORY, name)
    {
    }
    virtual ~CommentElement() { }
 
  public:
    static const string CATEGORY;
};

class MX_CORE_API NewlineElement : public Element
{
  public:
    NewlineElement(ElementPtr parent, const string& name) :
        Element(parent, CATEGORY, name)
    {
    }
    virtual ~NewlineElement() { }
 
  public:
    static const string CATEGORY;
};

class MX_CORE_API GenericElement : public Element
{
  public:
    GenericElement(ElementPtr parent, const string& name) :
        Element(parent, CATEGORY, name)
    {
    }
    virtual ~GenericElement() { }
 
  public:
    static const string CATEGORY;
};

class MX_CORE_API StringResolver
{
  public:
    static StringResolverPtr create()
    {
        return StringResolverPtr(new StringResolver());
    }
 
    virtual ~StringResolver() { }


    void setFilePrefix(const string& filePrefix)
    {
        _filePrefix = filePrefix;
    }

    const string& getFilePrefix() const
    {
        return _filePrefix;
    }


    void setGeomPrefix(const string& geomPrefix)
    {
        _geomPrefix = geomPrefix;
    }

    const string& getGeomPrefix() const
    {
        return _geomPrefix;
    }


    void setUdimString(const string& udim);

    void setUvTileString(const string& uvTile);

    void setFilenameSubstitution(const string& key, const string& value)
    {
        _filenameMap[key] = value;
    }

    void addTokenSubstitutions(ConstElementPtr element);

    const StringMap& getFilenameSubstitutions() const
    {
        return _filenameMap;
    }


    void setGeomNameSubstitution(const string& key, const string& value)
    {
        _geomNameMap[key] = value;
    }

    const StringMap& getGeomNameSubstitutions() const
    {
        return _geomNameMap;
    }


    virtual string resolve(const string& str, const string& type) const;

    static bool isResolvedType(const string& type)
    {
        return type == FILENAME_TYPE_STRING || type == GEOMNAME_TYPE_STRING;
    }

 
  protected:
    StringResolver() { }
 
  protected:
    string _filePrefix;
    string _geomPrefix;
    StringMap _filenameMap;
    StringMap _geomNameMap;
};

class MX_CORE_API ElementEquivalenceOptions
{
  public:
    ElementEquivalenceOptions()
    {
        performValueComparisons = true;
        floatFormat = Value::getFloatFormat();
        floatPrecision = Value::getFloatPrecision();
        attributeExclusionList = {};
    };
    ~ElementEquivalenceOptions() = default;

    bool performValueComparisons;

    Value::FloatFormat floatFormat;

    int floatPrecision;

    StringSet attributeExclusionList;
};

class MX_CORE_API ExceptionOrphanedElement : public Exception
{
  public:
    using Exception::Exception;
};
 
template <class T> shared_ptr<T> Element::addChild(const string& name)
{
    string childName = name;
    if (childName.empty())
    {
        childName = createValidChildName(T::CATEGORY + "1");
    }
 
    if (_childMap.count(childName))
        throw Exception("Child name is not unique: " + childName);
 
    shared_ptr<T> child = std::make_shared<T>(getSelf(), childName);
    registerChildElement(child);
 
    return child;
}

MX_CORE_API bool targetStringsMatch(const string& target1, const string& target2);

MX_CORE_API string prettyPrint(ConstElementPtr elem);
 
MATERIALX_NAMESPACE_END
 
#endif