6#ifndef MATERIALX_ELEMENT_H
7#define MATERIALX_ELEMENT_H
64using ElementMap = std::unordered_map<string, ElementPtr>;
74class MX_CORE_API
Element :
public std::enable_shared_from_this<Element>
81 _root(parent ? parent->getRoot() :
nullptr)
90 using DocumentPtr = shared_ptr<Document>;
91 using ConstDocumentPtr = shared_ptr<const Document>;
93 template <
class T>
friend class ElementRegistry;
98 bool operator==(
const Element& rhs)
const;
102 bool operator!=(
const Element& rhs)
const;
110 _category = category;
129 void setName(
const string& name);
149 ElementPtr getDescendant(
const string& namePath)
const;
158 setAttribute(FILE_PREFIX_ATTRIBUTE, prefix);
164 return hasAttribute(FILE_PREFIX_ATTRIBUTE);
170 return getAttribute(FILE_PREFIX_ATTRIBUTE);
179 if (elem->hasFilePrefix())
181 return elem->getFilePrefix();
194 setAttribute(GEOM_PREFIX_ATTRIBUTE, prefix);
200 return hasAttribute(GEOM_PREFIX_ATTRIBUTE);
206 return getAttribute(GEOM_PREFIX_ATTRIBUTE);
215 if (elem->hasGeomPrefix())
217 return elem->getGeomPrefix();
230 setAttribute(COLOR_SPACE_ATTRIBUTE, colorSpace);
236 return hasAttribute(COLOR_SPACE_ATTRIBUTE);
242 return getAttribute(COLOR_SPACE_ATTRIBUTE);
251 if (elem->hasColorSpace())
253 return elem->getColorSpace();
266 setAttribute(INHERIT_ATTRIBUTE, inherit);
272 return hasAttribute(INHERIT_ATTRIBUTE);
278 return getAttribute(INHERIT_ATTRIBUTE);
286 setInheritString(super->getName());
290 removeAttribute(INHERIT_ATTRIBUTE);
297 return resolveRootNameReference<Element>(getInheritString());
305 bool hasInheritanceCycle()
const;
314 setAttribute(NAMESPACE_ATTRIBUTE, space);
320 return hasAttribute(NAMESPACE_ATTRIBUTE);
326 return getAttribute(NAMESPACE_ATTRIBUTE);
335 const string& namespaceStr = elem->getNamespace();
336 if (!namespaceStr.empty())
339 const size_t i = name.find_first_of(NAME_PREFIX_SEPARATOR);
340 if (i != string::npos && name.substr(0, i) == namespaceStr)
346 return namespaceStr + NAME_PREFIX_SEPARATOR + name;
359 setAttribute(DOC_ATTRIBUTE, doc);
365 return getAttribute(DOC_ATTRIBUTE);
375 template<
class T>
bool isA(
const string& category = EMPTY_STRING)
const
379 if (!category.empty() && getCategory() != category)
385 template<
class T> shared_ptr<T> asA();
388 template<
class T> shared_ptr<const T> asA()
const;
401 template<
class T> shared_ptr<T> addChild(
const string& name = EMPTY_STRING);
413 ElementPtr addChildOfCategory(
const string& category,
string name = EMPTY_STRING);
425 ElementMap::const_iterator it = _childMap.find(name);
426 return (it != _childMap.end()) ? it->second :
ElementPtr();
435 return child ? child->asA<T>() : shared_ptr<T>();
448 template<
class T> vector< shared_ptr<T> >
getChildrenOfType(
const string& category = EMPTY_STRING)
const
450 vector< shared_ptr<T> > children;
453 shared_ptr<T> instance = child->asA<T>();
456 if (!category.empty() && child->getCategory() != category)
458 children.push_back(instance);
465 void setChildIndex(
const string& name,
int index);
469 int getChildIndex(
const string& name)
const;
472 void removeChild(
const string& name);
479 if (getChildOfType<T>(name))
488 void setAttribute(
const string& attrib,
const string& value);
493 return _attributeMap.count(attrib) != 0;
500 StringMap::const_iterator it = _attributeMap.find(attrib);
501 return (it != _attributeMap.end()) ? it->second : EMPTY_STRING;
507 return _attributeOrder;
515 setAttribute(attrib, toValueString(data));
523 if (hasAttribute(attrib))
527 return fromValueString<T>(getAttribute(attrib));
537 void removeAttribute(
const string& attrib);
546 return shared_from_this();
552 return shared_from_this();
558 return _parent.lock();
564 return _parent.lock();
585 shared_ptr<const T> typedElem = elem->asA<T>();
648 virtual Edge getUpstreamEdge(
size_t index = 0)
const;
661 ElementPtr getUpstreamElement(
size_t index = 0)
const;
687 return parent->getTreeIndex() * (int) (parent->getChildren().size() + 1) +
688 parent->getChildIndex(getName()) + 1;
702 _sourceUri = sourceUri;
708 return !_sourceUri.empty();
723 if (elem->hasSourceUri())
725 return elem->getSourceUri();
737 virtual bool validate(
string* message =
nullptr)
const;
754 name = createValidName(name);
755 while (_childMap.count(name))
757 name = incrementName(name);
774 string asString()
const;
781 shared_ptr<T> child = root->getChildOfType<T>(getQualifiedName(name));
782 return child ? child : root->getChildOfType<T>(name);
790 void validateRequire(
bool expression,
bool& res,
string* message,
string errorDesc)
const;
793 static const string NAME_ATTRIBUTE;
794 static const string FILE_PREFIX_ATTRIBUTE;
795 static const string GEOM_PREFIX_ATTRIBUTE;
796 static const string COLOR_SPACE_ATTRIBUTE;
797 static const string INHERIT_ATTRIBUTE;
798 static const string NAMESPACE_ATTRIBUTE;
799 static const string DOC_ATTRIBUTE;
802 virtual void registerChildElement(
ElementPtr child);
803 virtual void unregisterChildElement(
ElementPtr child);
809 return std::const_pointer_cast<Element>(shared_from_this());
817 ElementMap _childMap;
818 vector<ElementPtr> _childOrder;
820 StringMap _attributeMap;
821 StringVec _attributeOrder;
823 weak_ptr<Element> _parent;
824 weak_ptr<Element> _root;
827 template <
class T>
static ElementPtr createElement(ElementPtr parent,
const string& name)
829 return std::make_shared<T>(parent, name);
834 using CreatorMap = std::unordered_map<string, CreatorFunction>;
836 static CreatorMap _creatorMap;
845 Element(parent, category, name)
852 using TypeDefPtr = shared_ptr<class TypeDef>;
861 setAttribute(TYPE_ATTRIBUTE, type);
867 return hasAttribute(TYPE_ATTRIBUTE);
873 return getAttribute(TYPE_ATTRIBUTE);
879 return getType() == MULTI_OUTPUT_TYPE_STRING;
893 static const string TYPE_ATTRIBUTE;
914 setAttribute(VALUE_ATTRIBUTE, value);
920 return hasAttribute(VALUE_ATTRIBUTE);
926 return getAttribute(VALUE_ATTRIBUTE);
943 setAttribute(INTERFACE_NAME_ATTRIBUTE, name);
949 return hasAttribute(INTERFACE_NAME_ATTRIBUTE);
955 return getAttribute(INTERFACE_NAME_ATTRIBUTE);
965 setAttribute(IMPLEMENTATION_NAME_ATTRIBUTE, name);
971 return hasAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
977 return getAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
985 template<
class T>
void setValue(
const T& value,
const string& type = EMPTY_STRING)
987 setType(!type.empty() ? type : getTypeString<T>());
988 setValueString(toValueString(value));
992 void setValue(
const char* value,
const string& type = EMPTY_STRING)
994 setValue(value ?
string(value) : EMPTY_STRING, type);
1000 return hasAttribute(VALUE_ATTRIBUTE);
1044 setAttribute(UNIT_ATTRIBUTE, unit);
1050 return hasAttribute(UNIT_ATTRIBUTE);
1056 return getAttribute(UNIT_ATTRIBUTE);
1061 const string& getActiveUnit()
const;
1066 setAttribute(UNITTYPE_ATTRIBUTE, unit);
1072 return hasAttribute(UNITTYPE_ATTRIBUTE);
1078 return getAttribute(UNITTYPE_ATTRIBUTE);
1088 setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
1094 return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
1103 bool validate(
string* message =
nullptr)
const override;
1108 static const string VALUE_ATTRIBUTE;
1109 static const string INTERFACE_NAME_ATTRIBUTE;
1110 static const string IMPLEMENTATION_NAME_ATTRIBUTE;
1111 static const string IMPLEMENTATION_TYPE_ATTRIBUTE;
1112 static const string ENUM_ATTRIBUTE;
1113 static const string ENUM_VALUES_ATTRIBUTE;
1114 static const string UI_NAME_ATTRIBUTE;
1115 static const string UI_FOLDER_ATTRIBUTE;
1116 static const string UI_MIN_ATTRIBUTE;
1117 static const string UI_MAX_ATTRIBUTE;
1118 static const string UI_SOFT_MIN_ATTRIBUTE;
1119 static const string UI_SOFT_MAX_ATTRIBUTE;
1120 static const string UI_STEP_ATTRIBUTE;
1121 static const string UI_ADVANCED_ATTRIBUTE;
1122 static const string UNIT_ATTRIBUTE;
1123 static const string UNITTYPE_ATTRIBUTE;
1124 static const string UNIFORM_ATTRIBUTE;
1142 static const string CATEGORY;
1156 Element(parent, CATEGORY, name)
1162 static const string CATEGORY;
1171 Element(parent, CATEGORY, name)
1177 static const string CATEGORY;
1210 _filePrefix = filePrefix;
1226 _geomPrefix = geomPrefix;
1241 void setUdimString(
const string& udim);
1245 void setUvTileString(
const string& uvTile);
1250 _filenameMap[key] = value;
1256 return _filenameMap;
1266 _geomNameMap[key] = value;
1272 return _geomNameMap;
1281 virtual string resolve(
const string& str,
const string& type)
const;
1286 return type == FILENAME_TYPE_STRING || type == GEOMNAME_TYPE_STRING;
1297 StringMap _filenameMap;
1298 StringMap _geomNameMap;
1307 using Exception::Exception;
1312 string childName = name;
1313 if (childName.empty())
1318 if (_childMap.count(childName))
1319 throw Exception(
"Child name is not unique: " + childName);
1321 shared_ptr<T> child = std::make_shared<T>(
getSelf(), childName);
1322 registerChildElement(child);
1330MX_CORE_API
bool targetStringsMatch(
const string& target1,
const string& target2);
shared_ptr< TypeDef > TypeDefPtr
A shared pointer to a TypeDef.
Definition: Definition.h:43
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:25
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:23
shared_ptr< Token > TokenPtr
A shared pointer to a Token.
Definition: Element.h:46
shared_ptr< const GenericElement > ConstGenericElementPtr
A shared pointer to a const GenericElement.
Definition: Element.h:58
shared_ptr< TypedElement > TypedElementPtr
A shared pointer to a TypedElement.
Definition: Element.h:36
shared_ptr< StringResolver > StringResolverPtr
A shared pointer to a StringResolver.
Definition: Element.h:61
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
shared_ptr< const CommentElement > ConstCommentElementPtr
A shared pointer to a const CommentElement.
Definition: Element.h:53
std::unordered_map< string, ElementPtr > ElementMap
A hash map from strings to elements.
Definition: Element.h:64
shared_ptr< const Token > ConstTokenPtr
A shared pointer to a const Token.
Definition: Element.h:48
shared_ptr< GenericElement > GenericElementPtr
A shared pointer to a GenericElement.
Definition: Element.h:56
shared_ptr< ValueElement > ValueElementPtr
A shared pointer to a ValueElement.
Definition: Element.h:41
shared_ptr< const ValueElement > ConstValueElementPtr
A shared pointer to a const ValueElement.
Definition: Element.h:43
shared_ptr< CommentElement > CommentElementPtr
A shared pointer to a CommentElement.
Definition: Element.h:51
shared_ptr< const TypedElement > ConstTypedElementPtr
A shared pointer to a const TypedElement.
Definition: Element.h:38
std::function< bool(ConstElementPtr)> ElementPredicate
A standard function taking an ElementPtr and returning a boolean.
Definition: Element.h:67
shared_ptr< const Element > ConstElementPtr
A shared pointer to a const Element.
Definition: Element.h:33
Import and export declarations for the Core library.
vector< string > StringVec
A vector of strings.
Definition: Library.h:56
std::unordered_map< string, string > StringMap
An unordered map with strings as both keys and values.
Definition: Library.h:58
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:30
An edge between two connected Elements, returned during graph traversal.
Definition: Traversal.h:31
The base class for MaterialX elements.
Definition: Element.h:75
const string & getActiveSourceUri() const
Return the source URI that is active at the scope of this element, taking all ancestor elements into ...
Definition: Element.h:719
bool hasNamespace() const
Return true if this element has a namespace string.
Definition: Element.h:318
const string & getAttribute(const string &attrib) const
Return the value string of the given attribute.
Definition: Element.h:498
ConstElementPtr getSelf() const
Return our self pointer.
Definition: Element.h:550
const string & getActiveGeomPrefix() const
Return the geom prefix string that is active at the scope of this element, taking all ancestor elemen...
Definition: Element.h:211
bool isA(const string &category=EMPTY_STRING) const
Return true if this element belongs to the given subclass.
Definition: Element.h:375
void setDocString(const string &doc)
Set the documentation string of this element.
Definition: Element.h:357
bool hasGeomPrefix() const
Return true if the given element has a geom prefix string.
Definition: Element.h:198
shared_ptr< const T > getAncestorOfType() const
Return the first ancestor of the given subclass, or an empty shared pointer if no ancestor of this su...
Definition: Element.h:581
const string & getInheritString() const
Return the inherit string of this element.
Definition: Element.h:276
bool hasSourceUri() const
Return true if this element has a source URI.
Definition: Element.h:706
const string & getColorSpace() const
Return the element's color space string.
Definition: Element.h:240
shared_ptr< T > addChild(const string &name=EMPTY_STRING)
Add a child element of the given subclass and name.
Definition: Element.h:1310
const string & getName() const
Return the element's name string.
Definition: Element.h:132
void setColorSpace(const string &colorSpace)
Set the element's color space string.
Definition: Element.h:228
string getQualifiedName(const string &name) const
Return a qualified version of the given name, taking the namespace at the scope of this element into ...
Definition: Element.h:331
string createValidChildName(string name) const
Using the input name as a starting point, modify it to create a valid, unique name for a child elemen...
Definition: Element.h:752
const string & getGeomPrefix() const
Return the element's geom prefix string.
Definition: Element.h:204
void setFilePrefix(const string &prefix)
Set the element's file prefix string.
Definition: Element.h:156
shared_ptr< T > resolveRootNameReference(const string &name) const
Resolve a reference to a named element at the root scope of this document, taking the namespace at th...
Definition: Element.h:778
const StringVec & getAttributeNames() const
Return a vector of stored attribute names, in the order they were set.
Definition: Element.h:505
ElementPtr getChild(const string &name) const
Return the child element, if any, with the given name.
Definition: Element.h:423
const string & getSourceUri() const
Return the element's source URI.
Definition: Element.h:712
bool hasColorSpace() const
Return true if the given element has a color space string.
Definition: Element.h:234
const string & getFilePrefix() const
Return the element's file prefix string.
Definition: Element.h:168
void setTypedAttribute(const string &attrib, const T &data)
Set the value of an implicitly typed attribute.
Definition: Element.h:513
virtual size_t getUpstreamEdgeCount() const
Return the number of queriable upstream edges for this element.
Definition: Element.h:651
bool hasInheritString() const
Return true if this element has an inherit string.
Definition: Element.h:270
const string & getActiveColorSpace() const
Return the color space string that is active at the scope of this element, taking all ancestor elemen...
Definition: Element.h:247
int getTreeIndex() const
Return the breadth-first index of this element within the document tree.
Definition: Element.h:680
ElementPtr getInheritsFrom() const
Return the element, if any, that this one directly inherits from.
Definition: Element.h:295
T getTypedAttribute(const string &attrib) const
Return the value of an implicitly typed attribute.
Definition: Element.h:521
void setCategory(const string &category)
Set the element's category string.
Definition: Element.h:108
shared_ptr< T > getChildOfType(const string &name) const
Return the child element, if any, with the given name and subclass.
Definition: Element.h:432
void setGeomPrefix(const string &prefix)
Set the element's geom prefix string.
Definition: Element.h:192
void setNamespace(const string &space)
Set the namespace string of this element.
Definition: Element.h:312
ElementPtr getSelf()
Return our self pointer.
Definition: Element.h:544
const vector< ElementPtr > & getChildren() const
Return a constant vector of all child elements.
Definition: Element.h:440
ConstElementPtr getParent() const
Return our parent element.
Definition: Element.h:562
const string & getActiveFilePrefix() const
Return the file prefix string that is active at the scope of this element, taking all ancestor elemen...
Definition: Element.h:175
void setInheritString(const string &inherit)
Set the inherit string of this element.
Definition: Element.h:264
const string & getNamespace() const
Return the namespace string of this element.
Definition: Element.h:324
bool hasAttribute(const string &attrib) const
Return true if the given attribute is present.
Definition: Element.h:491
void removeChildOfType(const string &name)
Remove the child element, if any, with the given name and subclass.
Definition: Element.h:477
void setSourceUri(const string &sourceUri)
Set the element's source URI.
Definition: Element.h:700
string getDocString() const
Return the documentation string of this element.
Definition: Element.h:363
void setInheritsFrom(ConstElementPtr super)
Set the element that this one directly inherits from.
Definition: Element.h:282
ElementPtr getParent()
Return our parent element.
Definition: Element.h:556
bool hasFilePrefix() const
Return true if the given element has a file prefix string.
Definition: Element.h:162
const string & getCategory() const
Return the element's category string.
Definition: Element.h:116
vector< shared_ptr< T > > getChildrenOfType(const string &category=EMPTY_STRING) const
Return a vector of all child elements that are instances of the given subclass, optionally filtered b...
Definition: Element.h:448
The base class for exceptions that are propagated from the MaterialX library to the client applicatio...
Definition: Exception.h:23
An exception that is thrown when an ElementPtr is used after its owning Document has gone out of scop...
Definition: Element.h:1305
An exception that is thrown when a type mismatch is encountered.
Definition: Value.h:39
A generic element subclass, for instantiating elements with unrecognized categories.
Definition: Element.h:1168
An iterator object representing the state of an upstream graph traversal.
Definition: Traversal.h:193
An iterator object representing the current state of an inheritance traversal.
Definition: Traversal.h:335
A helper object for applying string modifiers to data values in the context of a specific element and...
Definition: Element.h:1194
void setFilenameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for filename data values.
Definition: Element.h:1248
static bool isResolvedType(const string &type)
Return true if the given type may be resolved by this class.
Definition: Element.h:1284
const string & getGeomPrefix() const
Return the geom prefix for this context.
Definition: Element.h:1230
const string & getFilePrefix() const
Return the file prefix for this context.
Definition: Element.h:1214
const StringMap & getGeomNameSubstitutions() const
Return the map of geometry name substring substitutions.
Definition: Element.h:1270
void setFilePrefix(const string &filePrefix)
Set the file prefix for this context.
Definition: Element.h:1208
void setGeomPrefix(const string &geomPrefix)
Set the geom prefix for this context.
Definition: Element.h:1224
const StringMap & getFilenameSubstitutions() const
Return the map of filename substring substitutions.
Definition: Element.h:1254
void setGeomNameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for geometry name data values.
Definition: Element.h:1264
static StringResolverPtr create()
Create a new string resolver.
Definition: Element.h:1197
A token element representing a string value.
Definition: Element.h:1133
An iterator object representing the state of a tree traversal.
Definition: Traversal.h:90
The base class for typed elements.
Definition: Element.h:842
virtual const string & getType() const
Return the element's type string.
Definition: Element.h:871
void setType(const string &type)
Set the element's type string.
Definition: Element.h:859
bool isMultiOutputType() const
Return true if the element is of multi-output type.
Definition: Element.h:877
bool hasType() const
Return true if the given element has a type string.
Definition: Element.h:865
The base class for elements that support typed values.
Definition: Element.h:899
ValuePtr getValue() const
Return the typed value of an element as a generic value object, which may be queried to access its da...
Definition: Element.h:1008
void setUnit(const string &unit)
Set the unit string of an element.
Definition: Element.h:1042
const string & getValueString() const
Get the value string of a element.
Definition: Element.h:924
void setInterfaceName(const string &name)
Set the interface name of an element.
Definition: Element.h:941
ValuePtr getResolvedValue(StringResolverPtr resolver=nullptr) const
Return the resolved value of an element as a generic value object, which may be queried to access its...
Definition: Element.h:1023
const string & getImplementationName() const
Return the implementation name of an element.
Definition: Element.h:975
void setValue(const char *value, const string &type=EMPTY_STRING)
Set the typed value of an element from a C-style string.
Definition: Element.h:992
bool hasUnitType() const
Return true if the given element has a unit type.
Definition: Element.h:1070
void setIsUniform(bool value)
Set the uniform attribute flag on this element.
Definition: Element.h:1086
const string & getUnit() const
Return the unit string of an element.
Definition: Element.h:1054
bool getIsUniform() const
The the uniform attribute flag for this element.
Definition: Element.h:1092
void setValueString(const string &value)
Set the value string of an element.
Definition: Element.h:912
void setValue(const T &value, const string &type=EMPTY_STRING)
Set the typed value of an element.
Definition: Element.h:985
bool hasUnit() const
Return true if the given element has a unit string.
Definition: Element.h:1048
bool hasInterfaceName() const
Return true if the given element has an interface name.
Definition: Element.h:947
void setUnitType(const string &unit)
Set the unit type of an element.
Definition: Element.h:1064
bool hasImplementationName() const
Return true if the given element has an implementation name.
Definition: Element.h:969
void setImplementationName(const string &name)
Set the implementation name of an element.
Definition: Element.h:963
const string & getInterfaceName() const
Return the interface name of an element.
Definition: Element.h:953
bool hasValueString() const
Return true if the given element has a value string.
Definition: Element.h:918
const string & getUnitType() const
Return the unit type of an element.
Definition: Element.h:1076
bool hasValue() const
Return true if the element possesses a typed value.
Definition: Element.h:998
static ValuePtr createValueFromStrings(const string &value, const string &type)
Create a new value instance from value and type strings.
Definition: Value.cpp:211