6#ifndef MATERIALX_ELEMENT_H
7#define MATERIALX_ELEMENT_H
18MATERIALX_NAMESPACE_BEGIN
69using ElementMap = std::unordered_map<string, ElementPtr>;
79class MX_CORE_API
Element :
public std::enable_shared_from_this<Element>
86 _root(parent ? parent->getRoot() :
nullptr)
96 using DocumentPtr = shared_ptr<Document>;
97 using ConstDocumentPtr = shared_ptr<const Document>;
99 template <
class T>
friend class ElementRegistry;
104 bool operator==(
const Element& rhs)
const;
108 bool operator!=(
const Element& rhs)
const;
116 _category = category;
135 void setName(
const string& name);
155 ElementPtr getDescendant(
const string& namePath)
const;
164 setAttribute(FILE_PREFIX_ATTRIBUTE, prefix);
170 return hasAttribute(FILE_PREFIX_ATTRIBUTE);
176 return getAttribute(FILE_PREFIX_ATTRIBUTE);
185 if (elem->hasFilePrefix())
187 return elem->getFilePrefix();
200 setAttribute(GEOM_PREFIX_ATTRIBUTE, prefix);
206 return hasAttribute(GEOM_PREFIX_ATTRIBUTE);
212 return getAttribute(GEOM_PREFIX_ATTRIBUTE);
221 if (elem->hasGeomPrefix())
223 return elem->getGeomPrefix();
236 setAttribute(COLOR_SPACE_ATTRIBUTE, colorSpace);
242 return hasAttribute(COLOR_SPACE_ATTRIBUTE);
248 return getAttribute(COLOR_SPACE_ATTRIBUTE);
257 if (elem->hasColorSpace())
259 return elem->getColorSpace();
272 setAttribute(INHERIT_ATTRIBUTE, inherit);
278 return hasAttribute(INHERIT_ATTRIBUTE);
284 return getAttribute(INHERIT_ATTRIBUTE);
292 setInheritString(super->getName());
296 removeAttribute(INHERIT_ATTRIBUTE);
303 return hasInheritString() ? resolveNameReference<Element>(getInheritString()) :
nullptr;
311 bool hasInheritanceCycle()
const;
320 setAttribute(NAMESPACE_ATTRIBUTE, space);
326 return hasAttribute(NAMESPACE_ATTRIBUTE);
332 return getAttribute(NAMESPACE_ATTRIBUTE);
341 const string& namespaceStr = elem->getNamespace();
342 if (!namespaceStr.empty())
345 const size_t i = name.find_first_of(NAME_PREFIX_SEPARATOR);
346 if (i != string::npos && name.substr(0, i) == namespaceStr)
352 return namespaceStr + NAME_PREFIX_SEPARATOR + name;
365 setAttribute(DOC_ATTRIBUTE, doc);
371 return getAttribute(DOC_ATTRIBUTE);
381 template <
class T>
bool isA(
const string& category = EMPTY_STRING)
const
385 if (!category.empty() && getCategory() != category)
391 template <
class T> shared_ptr<T> asA();
394 template <
class T> shared_ptr<const T> asA()
const;
407 template <
class T> shared_ptr<T> addChild(
const string& name = EMPTY_STRING);
419 ElementPtr addChildOfCategory(
const string& category,
string name = EMPTY_STRING);
431 ElementMap::const_iterator it = _childMap.find(name);
432 return (it != _childMap.end()) ? it->second :
ElementPtr();
441 return child ? child->asA<T>() : shared_ptr<T>();
454 template <
class T> vector<shared_ptr<T>>
getChildrenOfType(
const string& category = EMPTY_STRING)
const
456 vector<shared_ptr<T>> children;
459 shared_ptr<T> instance = child->asA<T>();
462 if (!category.empty() && child->getCategory() != category)
464 children.push_back(instance);
471 void setChildIndex(
const string& name,
int index);
475 int getChildIndex(
const string& name)
const;
478 void removeChild(
const string& name);
485 if (getChildOfType<T>(name))
494 void setAttribute(
const string& attrib,
const string& value);
499 return _attributeMap.count(attrib) != 0;
506 StringMap::const_iterator it = _attributeMap.find(attrib);
507 return (it != _attributeMap.end()) ? it->second : EMPTY_STRING;
513 return _attributeOrder;
521 setAttribute(attrib, toValueString(data));
529 if (hasAttribute(attrib))
533 return fromValueString<T>(getAttribute(attrib));
543 void removeAttribute(
const string& attrib);
552 return shared_from_this();
558 return shared_from_this();
564 return _parent.lock();
570 return _parent.lock();
591 shared_ptr<const T> typedElem = elem->asA<T>();
654 virtual Edge getUpstreamEdge(
size_t index = 0)
const;
667 ElementPtr getUpstreamElement(
size_t index = 0)
const;
696 _sourceUri = sourceUri;
702 return !_sourceUri.empty();
717 if (elem->hasSourceUri())
719 return elem->getSourceUri();
731 virtual bool validate(
string* message =
nullptr)
const;
742 virtual void clearContent();
748 name = name.empty() ?
"_" : createValidName(name);
749 while (_childMap.count(name))
751 name = incrementName(name);
768 string asString()
const;
776 template <
class T> shared_ptr<T> resolveNameReference(
const string& name,
ConstElementPtr parent =
nullptr)
const
779 shared_ptr<T> child = scope->getChildOfType<T>(getQualifiedName(name));
780 return child ? child : scope->getChildOfType<T>(name);
785 void validateRequire(
bool expression,
bool& res,
string* message,
const string& errorDesc)
const;
788 static const string NAME_ATTRIBUTE;
789 static const string FILE_PREFIX_ATTRIBUTE;
790 static const string GEOM_PREFIX_ATTRIBUTE;
791 static const string COLOR_SPACE_ATTRIBUTE;
792 static const string INHERIT_ATTRIBUTE;
793 static const string NAMESPACE_ATTRIBUTE;
794 static const string DOC_ATTRIBUTE;
797 virtual void registerChildElement(
ElementPtr child);
798 virtual void unregisterChildElement(
ElementPtr child);
804 return std::const_pointer_cast<Element>(shared_from_this());
813 vector<ElementPtr> _childOrder;
818 weak_ptr<Element> _parent;
819 weak_ptr<Element> _root;
824 return std::make_shared<T>(parent, name);
829 using CreatorMap = std::unordered_map<string, CreatorFunction>;
831 static CreatorMap _creatorMap;
840 Element(parent, category, name)
848 using TypeDefPtr = shared_ptr<class TypeDef>;
857 setAttribute(TYPE_ATTRIBUTE, type);
863 return hasAttribute(TYPE_ATTRIBUTE);
869 return getAttribute(TYPE_ATTRIBUTE);
875 return getType() == MULTI_OUTPUT_TYPE_STRING;
889 static const string TYPE_ATTRIBUTE;
911 setAttribute(VALUE_ATTRIBUTE, value);
917 return hasAttribute(VALUE_ATTRIBUTE);
923 return getAttribute(VALUE_ATTRIBUTE);
940 setAttribute(INTERFACE_NAME_ATTRIBUTE, name);
946 return hasAttribute(INTERFACE_NAME_ATTRIBUTE);
952 return getAttribute(INTERFACE_NAME_ATTRIBUTE);
962 setAttribute(IMPLEMENTATION_NAME_ATTRIBUTE, name);
968 return hasAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
974 return getAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
982 template <
class T>
void setValue(
const T& value,
const string& type = EMPTY_STRING)
984 setType(!type.empty() ? type : getTypeString<T>());
985 setValueString(toValueString(value));
989 void setValue(
const char* value,
const string& type = EMPTY_STRING)
991 setValue(value ?
string(value) : EMPTY_STRING, type);
997 return hasAttribute(VALUE_ATTRIBUTE);
1041 setAttribute(UNIT_ATTRIBUTE, unit);
1047 return hasAttribute(UNIT_ATTRIBUTE);
1053 return getAttribute(UNIT_ATTRIBUTE);
1058 const string& getActiveUnit()
const;
1063 setAttribute(UNITTYPE_ATTRIBUTE, unit);
1069 return hasAttribute(UNITTYPE_ATTRIBUTE);
1075 return getAttribute(UNITTYPE_ATTRIBUTE);
1085 setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
1091 return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
1100 bool validate(
string* message =
nullptr)
const override;
1105 static const string VALUE_ATTRIBUTE;
1106 static const string INTERFACE_NAME_ATTRIBUTE;
1107 static const string IMPLEMENTATION_NAME_ATTRIBUTE;
1108 static const string IMPLEMENTATION_TYPE_ATTRIBUTE;
1109 static const string ENUM_ATTRIBUTE;
1110 static const string ENUM_VALUES_ATTRIBUTE;
1111 static const string UI_NAME_ATTRIBUTE;
1112 static const string UI_FOLDER_ATTRIBUTE;
1113 static const string UI_MIN_ATTRIBUTE;
1114 static const string UI_MAX_ATTRIBUTE;
1115 static const string UI_SOFT_MIN_ATTRIBUTE;
1116 static const string UI_SOFT_MAX_ATTRIBUTE;
1117 static const string UI_STEP_ATTRIBUTE;
1118 static const string UI_ADVANCED_ATTRIBUTE;
1119 static const string UNIT_ATTRIBUTE;
1120 static const string UNITTYPE_ATTRIBUTE;
1121 static const string UNIFORM_ATTRIBUTE;
1139 static const string CATEGORY;
1153 Element(parent, CATEGORY, name)
1159 static const string CATEGORY;
1168 Element(parent, CATEGORY, name)
1174 static const string CATEGORY;
1183 Element(parent, CATEGORY, name)
1189 static const string CATEGORY;
1222 _filePrefix = filePrefix;
1238 _geomPrefix = geomPrefix;
1253 void setUdimString(
const string& udim);
1257 void setUvTileString(
const string& uvTile);
1262 _filenameMap[key] = value;
1271 return _filenameMap;
1281 _geomNameMap[key] = value;
1287 return _geomNameMap;
1296 virtual string resolve(
const string& str,
const string& type)
const;
1301 return type == FILENAME_TYPE_STRING || type == GEOMNAME_TYPE_STRING;
1322 using Exception::Exception;
1327 string childName = name;
1328 if (childName.empty())
1333 if (_childMap.count(childName))
1334 throw Exception(
"Child name is not unique: " + childName);
1336 shared_ptr<T> child = std::make_shared<T>(
getSelf(), childName);
1337 registerChildElement(child);
1351MATERIALX_NAMESPACE_END
shared_ptr< TypeDef > TypeDefPtr
A shared pointer to a TypeDef.
Definition: Definition.h:42
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:24
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:22
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:63
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:66
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:69
shared_ptr< NewlineElement > NewlineElementPtr
A shared pointer to a NewlineElement.
Definition: Element.h:56
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:61
shared_ptr< const Element > ConstElementPtr
A shared pointer to a const Element.
Definition: Element.h:33
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
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:72
shared_ptr< const NewlineElement > ConstNewlineElementPtr
A shared pointer to a const NewlineElement.
Definition: Element.h:58
MX_CORE_API string prettyPrint(ConstElementPtr elem)
Pretty print the given element tree, calling asString recursively on each element in depth-first orde...
Definition: Element.cpp:673
MX_CORE_API bool targetStringsMatch(const string &target1, const string &target2)
Given two target strings, each containing a string array of target names, return true if they have an...
Definition: Element.cpp:657
Import and export declarations for the Core library.
vector< string > StringVec
A vector of strings.
Definition: Library.h:57
std::unordered_map< string, string > StringMap
An unordered map with strings as both keys and values.
Definition: Library.h:59
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:29
A MaterialX document, which represents the top-level element in the MaterialX ownership hierarchy.
Definition: Document.h:32
An edge between two connected Elements, returned during graph traversal.
Definition: Traversal.h:30
The base class for MaterialX elements.
Definition: Element.h:80
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:713
bool hasNamespace() const
Return true if this element has a namespace string.
Definition: Element.h:324
const string & getAttribute(const string &attrib) const
Return the value string of the given attribute.
Definition: Element.h:504
ConstElementPtr getSelf() const
Return our self pointer.
Definition: Element.h:556
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:217
bool isA(const string &category=EMPTY_STRING) const
Return true if this element belongs to the given subclass.
Definition: Element.h:381
void setDocString(const string &doc)
Set the documentation string of this element.
Definition: Element.h:363
bool hasGeomPrefix() const
Return true if the given element has a geom prefix string.
Definition: Element.h:204
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:587
const string & getInheritString() const
Return the inherit string of this element.
Definition: Element.h:282
bool hasSourceUri() const
Return true if this element has a source URI.
Definition: Element.h:700
const string & getColorSpace() const
Return the element's color space string.
Definition: Element.h:246
shared_ptr< T > addChild(const string &name=EMPTY_STRING)
Add a child element of the given subclass and name.
Definition: Element.h:1325
const string & getName() const
Return the element's name string.
Definition: Element.h:138
void setColorSpace(const string &colorSpace)
Set the element's color space string.
Definition: Element.h:234
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:337
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:746
const string & getGeomPrefix() const
Return the element's geom prefix string.
Definition: Element.h:210
void setFilePrefix(const string &prefix)
Set the element's file prefix string.
Definition: Element.h:162
const StringVec & getAttributeNames() const
Return a vector of stored attribute names, in the order they were set.
Definition: Element.h:511
ElementPtr getChild(const string &name) const
Return the child element, if any, with the given name.
Definition: Element.h:429
const string & getSourceUri() const
Return the element's source URI.
Definition: Element.h:706
bool hasColorSpace() const
Return true if the given element has a color space string.
Definition: Element.h:240
const string & getFilePrefix() const
Return the element's file prefix string.
Definition: Element.h:174
void setTypedAttribute(const string &attrib, const T &data)
Set the value of an implicitly typed attribute.
Definition: Element.h:519
virtual size_t getUpstreamEdgeCount() const
Return the number of queriable upstream edges for this element.
Definition: Element.h:657
bool hasInheritString() const
Return true if this element has an inherit string.
Definition: Element.h:276
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:253
ElementPtr getInheritsFrom() const
Return the element, if any, that this one directly inherits from.
Definition: Element.h:301
T getTypedAttribute(const string &attrib) const
Return the value of an implicitly typed attribute.
Definition: Element.h:527
void setCategory(const string &category)
Set the element's category string.
Definition: Element.h:114
shared_ptr< T > getChildOfType(const string &name) const
Return the child element, if any, with the given name and subclass.
Definition: Element.h:438
void setGeomPrefix(const string &prefix)
Set the element's geom prefix string.
Definition: Element.h:198
void setNamespace(const string &space)
Set the namespace string of this element.
Definition: Element.h:318
ElementPtr getSelf()
Return our self pointer.
Definition: Element.h:550
const vector< ElementPtr > & getChildren() const
Return a constant vector of all child elements.
Definition: Element.h:446
ConstElementPtr getParent() const
Return our parent element.
Definition: Element.h:568
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:181
void setInheritString(const string &inherit)
Set the inherit string of this element.
Definition: Element.h:270
const string & getNamespace() const
Return the namespace string of this element.
Definition: Element.h:330
bool hasAttribute(const string &attrib) const
Return true if the given attribute is present.
Definition: Element.h:497
void removeChildOfType(const string &name)
Remove the child element, if any, with the given name and subclass.
Definition: Element.h:483
void setSourceUri(const string &sourceUri)
Set the element's source URI.
Definition: Element.h:694
string getDocString() const
Return the documentation string of this element.
Definition: Element.h:369
void setInheritsFrom(ConstElementPtr super)
Set the element that this one directly inherits from.
Definition: Element.h:288
ElementPtr getParent()
Return our parent element.
Definition: Element.h:562
bool hasFilePrefix() const
Return true if the given element has a file prefix string.
Definition: Element.h:168
const string & getCategory() const
Return the element's category string.
Definition: Element.h:122
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:454
The base class for exceptions that are propagated from the MaterialX library to the client applicatio...
Definition: Exception.h:22
An exception that is thrown when an ElementPtr is used after its owning Document has gone out of scop...
Definition: Element.h:1320
An exception that is thrown when a type mismatch is encountered.
Definition: Value.h:38
A generic element subclass, for instantiating elements with unrecognized categories.
Definition: Element.h:1180
An iterator object representing the state of an upstream graph traversal.
Definition: Traversal.h:192
An iterator object representing the current state of an inheritance traversal.
Definition: Traversal.h:334
An element representing a newline within a document.
Definition: Element.h:1165
A helper object for applying string modifiers to data values in the context of a specific element and...
Definition: Element.h:1206
void setFilenameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for filename data values.
Definition: Element.h:1260
static bool isResolvedType(const string &type)
Return true if the given type may be resolved by this class.
Definition: Element.h:1299
const string & getGeomPrefix() const
Return the geom prefix for this context.
Definition: Element.h:1242
const string & getFilePrefix() const
Return the file prefix for this context.
Definition: Element.h:1226
const StringMap & getGeomNameSubstitutions() const
Return the map of geometry name substring substitutions.
Definition: Element.h:1285
void setFilePrefix(const string &filePrefix)
Set the file prefix for this context.
Definition: Element.h:1220
void setGeomPrefix(const string &geomPrefix)
Set the geom prefix for this context.
Definition: Element.h:1236
const StringMap & getFilenameSubstitutions() const
Return the map of filename substring substitutions.
Definition: Element.h:1269
void setGeomNameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for geometry name data values.
Definition: Element.h:1279
static StringResolverPtr create()
Create a new string resolver.
Definition: Element.h:1209
A token element representing a string value.
Definition: Element.h:1130
An iterator object representing the state of a tree traversal.
Definition: Traversal.h:89
The base class for typed elements.
Definition: Element.h:837
virtual const string & getType() const
Return the element's type string.
Definition: Element.h:867
void setType(const string &type)
Set the element's type string.
Definition: Element.h:855
bool isMultiOutputType() const
Return true if the element is of multi-output type.
Definition: Element.h:873
bool hasType() const
Return true if the given element has a type string.
Definition: Element.h:861
The base class for elements that support typed values.
Definition: Element.h:895
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:1005
void setUnit(const string &unit)
Set the unit string of an element.
Definition: Element.h:1039
const string & getValueString() const
Get the value string of a element.
Definition: Element.h:921
void setInterfaceName(const string &name)
Set the interface name of an element.
Definition: Element.h:938
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:1020
const string & getImplementationName() const
Return the implementation name of an element.
Definition: Element.h:972
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:989
bool hasUnitType() const
Return true if the given element has a unit type.
Definition: Element.h:1067
void setIsUniform(bool value)
Set the uniform attribute flag on this element.
Definition: Element.h:1083
const string & getUnit() const
Return the unit string of an element.
Definition: Element.h:1051
bool getIsUniform() const
The the uniform attribute flag for this element.
Definition: Element.h:1089
void setValueString(const string &value)
Set the value string of an element.
Definition: Element.h:909
void setValue(const T &value, const string &type=EMPTY_STRING)
Set the typed value of an element.
Definition: Element.h:982
bool hasUnit() const
Return true if the given element has a unit string.
Definition: Element.h:1045
bool hasInterfaceName() const
Return true if the given element has an interface name.
Definition: Element.h:944
void setUnitType(const string &unit)
Set the unit type of an element.
Definition: Element.h:1061
bool hasImplementationName() const
Return true if the given element has an implementation name.
Definition: Element.h:966
void setImplementationName(const string &name)
Set the implementation name of an element.
Definition: Element.h:960
const string & getInterfaceName() const
Return the interface name of an element.
Definition: Element.h:950
bool hasValueString() const
Return true if the given element has a value string.
Definition: Element.h:915
const string & getUnitType() const
Return the unit type of an element.
Definition: Element.h:1073
bool hasValue() const
Return true if the element possesses a typed value.
Definition: Element.h:995
static ValuePtr createValueFromStrings(const string &value, const string &type)
Create a new value instance from value and type strings.
Definition: Value.cpp:216