MaterialX 1.39.0
Loading...
Searching...
No Matches
Element.h
Go to the documentation of this file.
1//
2// Copyright Contributors to the MaterialX Project
3// SPDX-License-Identifier: Apache-2.0
4//
5
6#ifndef MATERIALX_ELEMENT_H
7#define MATERIALX_ELEMENT_H
8
11
13
15#include <MaterialXCore/Util.h>
16#include <MaterialXCore/Value.h>
17
18MATERIALX_NAMESPACE_BEGIN
19
20class Element;
21class TypedElement;
22class ValueElement;
23class Token;
24class CommentElement;
25class NewlineElement;
26class GenericElement;
27class StringResolver;
28class Document;
29
31using ElementPtr = shared_ptr<Element>;
33using ConstElementPtr = shared_ptr<const Element>;
34
36using TypedElementPtr = shared_ptr<TypedElement>;
38using ConstTypedElementPtr = shared_ptr<const TypedElement>;
39
41using ValueElementPtr = shared_ptr<ValueElement>;
43using ConstValueElementPtr = shared_ptr<const ValueElement>;
44
46using TokenPtr = shared_ptr<Token>;
48using ConstTokenPtr = shared_ptr<const Token>;
49
51using CommentElementPtr = shared_ptr<CommentElement>;
53using ConstCommentElementPtr = shared_ptr<const CommentElement>;
54
56using NewlineElementPtr = shared_ptr<NewlineElement>;
58using ConstNewlineElementPtr = shared_ptr<const NewlineElement>;
59
61using GenericElementPtr = shared_ptr<GenericElement>;
63using ConstGenericElementPtr = shared_ptr<const GenericElement>;
64
66using StringResolverPtr = shared_ptr<StringResolver>;
67
69using ElementMap = std::unordered_map<string, ElementPtr>;
70
72using ElementPredicate = std::function<bool(ConstElementPtr)>;
73
79class MX_CORE_API Element : public std::enable_shared_from_this<Element>
80{
81 protected:
82 Element(ElementPtr parent, const string& category, const string& name) :
83 _category(category),
84 _name(name),
85 _parent(parent),
86 _root(parent ? parent->getRoot() : nullptr)
87 {
88 }
89
90 public:
91 virtual ~Element() { }
92 Element(const Element&) = delete;
93 Element& operator=(const Element&) = delete;
94
95 protected:
96 using DocumentPtr = shared_ptr<Document>;
97 using ConstDocumentPtr = shared_ptr<const Document>;
98
99 template <class T> friend class ElementRegistry;
100
101 public:
104 bool operator==(const Element& rhs) const;
105
108 bool operator!=(const Element& rhs) const;
109
112
114 void setCategory(const string& category)
115 {
116 _category = category;
117 }
118
122 const string& getCategory() const
123 {
124 return _category;
125 }
126
130
135 void setName(const string& name);
136
138 const string& getName() const
139 {
140 return _name;
141 }
142
148 string getNamePath(ConstElementPtr relativeTo = nullptr) const;
149
155 ElementPtr getDescendant(const string& namePath) const;
156
160
162 void setFilePrefix(const string& prefix)
163 {
164 setAttribute(FILE_PREFIX_ATTRIBUTE, prefix);
165 }
166
168 bool hasFilePrefix() const
169 {
170 return hasAttribute(FILE_PREFIX_ATTRIBUTE);
171 }
172
174 const string& getFilePrefix() const
175 {
176 return getAttribute(FILE_PREFIX_ATTRIBUTE);
177 }
178
181 const string& getActiveFilePrefix() const
182 {
183 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
184 {
185 if (elem->hasFilePrefix())
186 {
187 return elem->getFilePrefix();
188 }
189 }
190 return EMPTY_STRING;
191 }
192
196
198 void setGeomPrefix(const string& prefix)
199 {
200 setAttribute(GEOM_PREFIX_ATTRIBUTE, prefix);
201 }
202
204 bool hasGeomPrefix() const
205 {
206 return hasAttribute(GEOM_PREFIX_ATTRIBUTE);
207 }
208
210 const string& getGeomPrefix() const
211 {
212 return getAttribute(GEOM_PREFIX_ATTRIBUTE);
213 }
214
217 const string& getActiveGeomPrefix() const
218 {
219 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
220 {
221 if (elem->hasGeomPrefix())
222 {
223 return elem->getGeomPrefix();
224 }
225 }
226 return EMPTY_STRING;
227 }
228
232
234 void setColorSpace(const string& colorSpace)
235 {
236 setAttribute(COLOR_SPACE_ATTRIBUTE, colorSpace);
237 }
238
240 bool hasColorSpace() const
241 {
242 return hasAttribute(COLOR_SPACE_ATTRIBUTE);
243 }
244
246 const string& getColorSpace() const
247 {
248 return getAttribute(COLOR_SPACE_ATTRIBUTE);
249 }
250
253 const string& getActiveColorSpace() const
254 {
255 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
256 {
257 if (elem->hasColorSpace())
258 {
259 return elem->getColorSpace();
260 }
261 }
262 return EMPTY_STRING;
263 }
264
268
270 void setInheritString(const string& inherit)
271 {
272 setAttribute(INHERIT_ATTRIBUTE, inherit);
273 }
274
276 bool hasInheritString() const
277 {
278 return hasAttribute(INHERIT_ATTRIBUTE);
279 }
280
282 const string& getInheritString() const
283 {
284 return getAttribute(INHERIT_ATTRIBUTE);
285 }
286
289 {
290 if (super)
291 {
292 setInheritString(super->getName());
293 }
294 else
295 {
296 removeAttribute(INHERIT_ATTRIBUTE);
297 }
298 }
299
302 {
303 return hasInheritString() ? resolveNameReference<Element>(getInheritString()) : nullptr;
304 }
305
309
312
316
318 void setNamespace(const string& space)
319 {
320 setAttribute(NAMESPACE_ATTRIBUTE, space);
321 }
322
324 bool hasNamespace() const
325 {
326 return hasAttribute(NAMESPACE_ATTRIBUTE);
327 }
328
330 const string& getNamespace() const
331 {
332 return getAttribute(NAMESPACE_ATTRIBUTE);
333 }
334
337 string getQualifiedName(const string& name) const
338 {
339 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
340 {
341 const string& namespaceStr = elem->getNamespace();
342 if (!namespaceStr.empty())
343 {
344 // Check if the name is qualified already.
345 const size_t i = name.find_first_of(NAME_PREFIX_SEPARATOR);
346 if (i != string::npos && name.substr(0, i) == namespaceStr)
347 {
348 // The name is already qualified with this namespace,
349 // so just return it as is.
350 return name;
351 }
352 return namespaceStr + NAME_PREFIX_SEPARATOR + name;
353 }
354 }
355 return name;
356 }
357
361
363 void setDocString(const string& doc)
364 {
365 setAttribute(DOC_ATTRIBUTE, doc);
366 }
367
369 string getDocString() const
370 {
371 return getAttribute(DOC_ATTRIBUTE);
372 }
373
377
381 template <class T> bool isA(const string& category = EMPTY_STRING) const
382 {
383 if (!asA<T>())
384 return false;
385 if (!category.empty() && getCategory() != category)
386 return false;
387 return true;
388 }
389
391 template <class T> shared_ptr<T> asA();
392
394 template <class T> shared_ptr<const T> asA() const;
395
399
407 template <class T> shared_ptr<T> addChild(const string& name = EMPTY_STRING);
408
419 ElementPtr addChildOfCategory(const string& category, string name = EMPTY_STRING);
420
426 ElementPtr changeChildCategory(ElementPtr child, const string& category);
427
429 ElementPtr getChild(const string& name) const
430 {
431 ElementMap::const_iterator it = _childMap.find(name);
432 return (it != _childMap.end()) ? it->second : ElementPtr();
433 }
434
438 template <class T> shared_ptr<T> getChildOfType(const string& name) const
439 {
440 ElementPtr child = getChild(name);
441 return child ? child->asA<T>() : shared_ptr<T>();
442 }
443
446 const vector<ElementPtr>& getChildren() const
447 {
448 return _childOrder;
449 }
450
454 template <class T> vector<shared_ptr<T>> getChildrenOfType(const string& category = EMPTY_STRING) const
455 {
456 vector<shared_ptr<T>> children;
457 for (ElementPtr child : _childOrder)
458 {
459 shared_ptr<T> instance = child->asA<T>();
460 if (!instance)
461 continue;
462 if (!category.empty() && child->getCategory() != category)
463 continue;
464 children.push_back(instance);
465 }
466 return children;
467 }
468
471 void setChildIndex(const string& name, int index);
472
475 int getChildIndex(const string& name) const;
476
478 void removeChild(const string& name);
479
483 template <class T> void removeChildOfType(const string& name)
484 {
485 if (getChildOfType<T>(name))
486 removeChild(name);
487 }
488
492
494 void setAttribute(const string& attrib, const string& value);
495
497 bool hasAttribute(const string& attrib) const
498 {
499 return _attributeMap.count(attrib) != 0;
500 }
501
504 const string& getAttribute(const string& attrib) const
505 {
506 StringMap::const_iterator it = _attributeMap.find(attrib);
507 return (it != _attributeMap.end()) ? it->second : EMPTY_STRING;
508 }
509
512 {
513 return _attributeOrder;
514 }
515
519 template <class T> void setTypedAttribute(const string& attrib, const T& data)
520 {
521 setAttribute(attrib, toValueString(data));
522 }
523
527 template <class T> T getTypedAttribute(const string& attrib) const
528 {
529 if (hasAttribute(attrib))
530 {
531 try
532 {
533 return fromValueString<T>(getAttribute(attrib));
534 }
535 catch (ExceptionTypeError&)
536 {
537 }
538 }
539 return {};
540 }
541
543 void removeAttribute(const string& attrib);
544
548
551 {
552 return shared_from_this();
553 }
554
557 {
558 return shared_from_this();
559 }
560
563 {
564 return _parent.lock();
565 }
566
569 {
570 return _parent.lock();
571 }
572
575
578
580 DocumentPtr getDocument();
581
583 ConstDocumentPtr getDocument() const;
584
587 template <class T> shared_ptr<T> getAncestorOfType()
588 {
589 for (ElementPtr elem = getSelf(); elem; elem = elem->getParent())
590 {
591 shared_ptr<T> typedElem = elem->asA<T>();
592 if (typedElem)
593 {
594 return typedElem;
595 }
596 }
597 return nullptr;
598 }
599
602 template <class T> shared_ptr<const T> getAncestorOfType() const
603 {
604 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
605 {
606 shared_ptr<const T> typedElem = elem->asA<T>();
607 if (typedElem)
608 {
609 return typedElem;
610 }
611 }
612 return nullptr;
613 }
614
618
638
663
669 virtual Edge getUpstreamEdge(size_t index = 0) const;
670
672 virtual size_t getUpstreamEdgeCount() const
673 {
674 return 0;
675 }
676
682 ElementPtr getUpstreamElement(size_t index = 0) const;
683
699
703
709 void setSourceUri(const string& sourceUri)
710 {
711 _sourceUri = sourceUri;
712 }
713
715 bool hasSourceUri() const
716 {
717 return !_sourceUri.empty();
718 }
719
721 const string& getSourceUri() const
722 {
723 return _sourceUri;
724 }
725
728 const string& getActiveSourceUri() const
729 {
730 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
731 {
732 if (elem->hasSourceUri())
733 {
734 return elem->getSourceUri();
735 }
736 }
737 return EMPTY_STRING;
738 }
739
743
746 virtual bool validate(string* message = nullptr) const;
747
751
754 void copyContentFrom(const ConstElementPtr& source);
755
757 virtual void clearContent();
758
761 string createValidChildName(string name) const
762 {
763 name = name.empty() ? "_" : createValidName(name);
764 while (_childMap.count(name))
765 {
766 name = incrementName(name);
767 }
768 return name;
769 }
770
779 StringResolverPtr createStringResolver(const string& geom = EMPTY_STRING) const;
780
783 string asString() const;
784
786
787 protected:
788 // Resolve a reference to a named element at the scope of the given parent,
789 // taking the namespace at the scope of this element into account. If no parent
790 // is provided, then the root scope of the document is used.
791 template <class T> shared_ptr<T> resolveNameReference(const string& name, ConstElementPtr parent = nullptr) const
792 {
793 ConstElementPtr scope = parent ? parent : getRoot();
794 shared_ptr<T> child = scope->getChildOfType<T>(getQualifiedName(name));
795 return child ? child : scope->getChildOfType<T>(name);
796 }
797
798 // Enforce a requirement within a validate method, updating the validation
799 // state and optional output text if the requirement is not met.
800 void validateRequire(bool expression, bool& res, string* message, const string& errorDesc) const;
801
802 public:
803 static const string NAME_ATTRIBUTE;
804 static const string FILE_PREFIX_ATTRIBUTE;
805 static const string GEOM_PREFIX_ATTRIBUTE;
806 static const string COLOR_SPACE_ATTRIBUTE;
807 static const string INHERIT_ATTRIBUTE;
808 static const string NAMESPACE_ATTRIBUTE;
809 static const string DOC_ATTRIBUTE;
810 static const string XPOS_ATTRIBUTE;
811 static const string YPOS_ATTRIBUTE;
812
813 protected:
814 virtual void registerChildElement(ElementPtr child);
815 virtual void unregisterChildElement(ElementPtr child);
816
817 // Return a non-const copy of our self pointer, for use in constructing
818 // graph traversal objects that require non-const storage.
819 ElementPtr getSelfNonConst() const
820 {
821 return std::const_pointer_cast<Element>(shared_from_this());
822 }
823
824 protected:
825 string _category;
826 string _name;
827 string _sourceUri;
828
829 ElementMap _childMap;
830 vector<ElementPtr> _childOrder;
831
832 StringMap _attributeMap;
833 StringVec _attributeOrder;
834
835 weak_ptr<Element> _parent;
836 weak_ptr<Element> _root;
837
838 private:
839 template <class T> static ElementPtr createElement(ElementPtr parent, const string& name)
840 {
841 return std::make_shared<T>(parent, name);
842 }
843
844 private:
845 using CreatorFunction = ElementPtr (*)(ElementPtr, const string&);
846 using CreatorMap = std::unordered_map<string, CreatorFunction>;
847
848 static CreatorMap _creatorMap;
849};
850
853class MX_CORE_API TypedElement : public Element
854{
855 protected:
856 TypedElement(ElementPtr parent, const string& category, const string& name) :
857 Element(parent, category, name)
858 {
859 }
860
861 public:
862 virtual ~TypedElement() { }
863
864 protected:
865 using TypeDefPtr = shared_ptr<class TypeDef>;
866
867 public:
870
872 void setType(const string& type)
873 {
874 setAttribute(TYPE_ATTRIBUTE, type);
875 }
876
878 bool hasType() const
879 {
880 return hasAttribute(TYPE_ATTRIBUTE);
881 }
882
884 virtual const string& getType() const
885 {
886 return getAttribute(TYPE_ATTRIBUTE);
887 }
888
890 bool isColorType() const
891 {
892 return getType() == "color3" || getType() == "color4";
893 }
894
896 bool isMultiOutputType() const
897 {
898 return getType() == MULTI_OUTPUT_TYPE_STRING;
899 }
900
904
907 TypeDefPtr getTypeDef() const;
908
910
911 public:
912 static const string TYPE_ATTRIBUTE;
913};
914
917class MX_CORE_API ValueElement : public TypedElement
918{
919 protected:
920 ValueElement(ElementPtr parent, const string& category, const string& name) :
921 TypedElement(parent, category, name)
922 {
923 }
924
925 public:
926 virtual ~ValueElement() { }
927
930
932 void setValueString(const string& value)
933 {
934 setAttribute(VALUE_ATTRIBUTE, value);
935 }
936
938 bool hasValueString() const
939 {
940 return hasAttribute(VALUE_ATTRIBUTE);
941 }
942
944 const string& getValueString() const
945 {
946 return getAttribute(VALUE_ATTRIBUTE);
947 }
948
954 string getResolvedValueString(StringResolverPtr resolver = nullptr) const;
955
959
961 void setInterfaceName(const string& name)
962 {
963 setAttribute(INTERFACE_NAME_ATTRIBUTE, name);
964 }
965
967 bool hasInterfaceName() const
968 {
969 return hasAttribute(INTERFACE_NAME_ATTRIBUTE);
970 }
971
973 const string& getInterfaceName() const
974 {
975 return getAttribute(INTERFACE_NAME_ATTRIBUTE);
976 }
977
981
983 void setImplementationName(const string& name)
984 {
985 setAttribute(IMPLEMENTATION_NAME_ATTRIBUTE, name);
986 }
987
990 {
991 return hasAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
992 }
993
995 const string& getImplementationName() const
996 {
997 return getAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
998 }
999
1003
1005 template <class T> void setValue(const T& value, const string& type = EMPTY_STRING)
1006 {
1007 setType(!type.empty() ? type : getTypeString<T>());
1008 setValueString(toValueString(value));
1009 }
1010
1012 void setValue(const char* value, const string& type = EMPTY_STRING)
1013 {
1014 setValue(value ? string(value) : EMPTY_STRING, type);
1015 }
1016
1018 bool hasValue() const
1019 {
1020 return hasAttribute(VALUE_ATTRIBUTE);
1021 }
1022
1029 {
1030 if (!hasValue())
1031 return ValuePtr();
1032 return Value::createValueFromStrings(getValueString(), getType());
1033 }
1034
1044 {
1045 if (!hasValue())
1046 return ValuePtr();
1047 return Value::createValueFromStrings(getResolvedValueString(resolver), getType());
1048 }
1049
1056
1060
1062 void setUnit(const string& unit)
1063 {
1064 setAttribute(UNIT_ATTRIBUTE, unit);
1065 }
1066
1068 bool hasUnit() const
1069 {
1070 return hasAttribute(UNIT_ATTRIBUTE);
1071 }
1072
1074 const string& getUnit() const
1075 {
1076 return getAttribute(UNIT_ATTRIBUTE);
1077 }
1078
1081 const string& getActiveUnit() const;
1082
1084 void setUnitType(const string& unit)
1085 {
1086 setAttribute(UNITTYPE_ATTRIBUTE, unit);
1087 }
1088
1090 bool hasUnitType() const
1091 {
1092 return hasAttribute(UNITTYPE_ATTRIBUTE);
1093 }
1094
1096 const string& getUnitType() const
1097 {
1098 return getAttribute(UNITTYPE_ATTRIBUTE);
1099 }
1100
1104
1106 void setIsUniform(bool value)
1107 {
1108 setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
1109 }
1110
1112 bool getIsUniform() const
1113 {
1114 return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
1115 }
1116
1120
1123 bool validate(string* message = nullptr) const override;
1124
1126
1127 public:
1128 static const string VALUE_ATTRIBUTE;
1129 static const string INTERFACE_NAME_ATTRIBUTE;
1130 static const string IMPLEMENTATION_NAME_ATTRIBUTE;
1131 static const string IMPLEMENTATION_TYPE_ATTRIBUTE;
1132 static const string ENUM_ATTRIBUTE;
1133 static const string ENUM_VALUES_ATTRIBUTE;
1134 static const string UI_NAME_ATTRIBUTE;
1135 static const string UI_FOLDER_ATTRIBUTE;
1136 static const string UI_MIN_ATTRIBUTE;
1137 static const string UI_MAX_ATTRIBUTE;
1138 static const string UI_SOFT_MIN_ATTRIBUTE;
1139 static const string UI_SOFT_MAX_ATTRIBUTE;
1140 static const string UI_STEP_ATTRIBUTE;
1141 static const string UI_ADVANCED_ATTRIBUTE;
1142 static const string UNIT_ATTRIBUTE;
1143 static const string UNITTYPE_ATTRIBUTE;
1144 static const string UNIFORM_ATTRIBUTE;
1145};
1146
1152class MX_CORE_API Token : public ValueElement
1153{
1154 public:
1155 Token(ElementPtr parent, const string& name) :
1156 ValueElement(parent, CATEGORY, name)
1157 {
1158 }
1159 virtual ~Token() { }
1160
1161 public:
1162 static const string CATEGORY;
1163};
1164
1172class MX_CORE_API CommentElement : public Element
1173{
1174 public:
1175 CommentElement(ElementPtr parent, const string& name) :
1176 Element(parent, CATEGORY, name)
1177 {
1178 }
1179 virtual ~CommentElement() { }
1180
1181 public:
1182 static const string CATEGORY;
1183};
1184
1187class MX_CORE_API NewlineElement : public Element
1188{
1189 public:
1190 NewlineElement(ElementPtr parent, const string& name) :
1191 Element(parent, CATEGORY, name)
1192 {
1193 }
1194 virtual ~NewlineElement() { }
1195
1196 public:
1197 static const string CATEGORY;
1198};
1199
1202class MX_CORE_API GenericElement : public Element
1203{
1204 public:
1205 GenericElement(ElementPtr parent, const string& name) :
1206 Element(parent, CATEGORY, name)
1207 {
1208 }
1209 virtual ~GenericElement() { }
1210
1211 public:
1212 static const string CATEGORY;
1213};
1214
1228class MX_CORE_API StringResolver
1229{
1230 public:
1233 {
1234 return StringResolverPtr(new StringResolver());
1235 }
1236
1237 virtual ~StringResolver() { }
1238
1241
1243 void setFilePrefix(const string& filePrefix)
1244 {
1245 _filePrefix = filePrefix;
1246 }
1247
1249 const string& getFilePrefix() const
1250 {
1251 return _filePrefix;
1252 }
1253
1257
1259 void setGeomPrefix(const string& geomPrefix)
1260 {
1261 _geomPrefix = geomPrefix;
1262 }
1263
1265 const string& getGeomPrefix() const
1266 {
1267 return _geomPrefix;
1268 }
1269
1273
1276 void setUdimString(const string& udim);
1277
1280 void setUvTileString(const string& uvTile);
1281
1283 void setFilenameSubstitution(const string& key, const string& value)
1284 {
1285 _filenameMap[key] = value;
1286 }
1287
1290
1293 {
1294 return _filenameMap;
1295 }
1296
1300
1302 void setGeomNameSubstitution(const string& key, const string& value)
1303 {
1304 _geomNameMap[key] = value;
1305 }
1306
1309 {
1310 return _geomNameMap;
1311 }
1312
1316
1319 virtual string resolve(const string& str, const string& type) const;
1320
1322 static bool isResolvedType(const string& type)
1323 {
1324 return type == FILENAME_TYPE_STRING || type == GEOMNAME_TYPE_STRING;
1325 }
1326
1328
1329 protected:
1330 StringResolver() { }
1331
1332 protected:
1333 string _filePrefix;
1334 string _geomPrefix;
1335 StringMap _filenameMap;
1336 StringMap _geomNameMap;
1337};
1338
1342class MX_CORE_API ExceptionOrphanedElement : public Exception
1343{
1344 public:
1345 using Exception::Exception;
1346};
1347
1348template <class T> shared_ptr<T> Element::addChild(const string& name)
1349{
1350 string childName = name;
1351 if (childName.empty())
1352 {
1353 childName = createValidChildName(T::CATEGORY + "1");
1354 }
1355
1356 if (_childMap.count(childName))
1357 throw Exception("Child name is not unique: " + childName);
1358
1359 shared_ptr<T> child = std::make_shared<T>(getSelf(), childName);
1360 registerChildElement(child);
1361
1362 return child;
1363}
1364
1368MX_CORE_API bool targetStringsMatch(const string& target1, const string& target2);
1369
1372MX_CORE_API string prettyPrint(ConstElementPtr elem);
1373
1374MATERIALX_NAMESPACE_END
1375
1376#endif
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...
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...
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
Utility methods.
MX_CORE_API string incrementName(const string &name)
Increment the numeric suffix of a name.
MX_CORE_API string createValidName(string name, char replaceChar='_')
Create a valid MaterialX name from the given string.
Graph traversal classes.
Generic value classes.
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:29
MX_CORE_API string toValueString(const T &data)
Convert the given data value to a value string.
An element representing a block of descriptive text within a document, which will be stored a comment...
Definition: Element.h:1173
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:728
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
string asString() const
Return a single-line description of this element, including its category, name, and attributes.
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
shared_ptr< T > getAncestorOfType()
Return the first ancestor of the given subclass, or an empty shared pointer if no ancestor of this su...
Definition: Element.h:587
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:602
void setChildIndex(const string &name, int index)
Set the index of the child, if any, with the given name.
const string & getInheritString() const
Return the inherit string of this element.
Definition: Element.h:282
TreeIterator traverseTree() const
Traverse the tree from the given element to each of its descendants in depth-first order,...
GraphIterator traverseGraph() const
Traverse the dataflow graph from the given element to each of its upstream sources in depth-first ord...
bool hasSourceUri() const
Return true if this element has a source URI.
Definition: Element.h:715
void removeChild(const string &name)
Remove the child element, if any, with the given name.
ElementPtr changeChildCategory(ElementPtr child, const string &category)
Change the category of the given child element.
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:1348
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:761
shared_ptr< const T > asA() const
Dynamic cast to a const instance of the given subclass.
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
bool hasInheritedBase(ConstElementPtr base) const
Return true if this element has the given element as an inherited base, taking the full inheritance c...
bool hasInheritanceCycle() const
Return true if the inheritance chain for this element contains a cycle.
void setAttribute(const string &attrib, const string &value)
Set the value string of the given attribute.
const StringVec & getAttributeNames() const
Return a vector of stored attribute names, in the order they were set.
Definition: Element.h:511
void setName(const string &name)
Set the element's name string.
virtual void clearContent()
Clear all attributes and descendants from this element.
int getChildIndex(const string &name) const
Return the index of the child, if any, with the given name.
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:721
virtual bool validate(string *message=nullptr) const
Validate that the given element tree, including all descendants, is consistent with the MaterialX spe...
bool hasColorSpace() const
Return true if the given element has a color space string.
Definition: Element.h:240
InheritanceIterator traverseInheritance() const
Traverse the inheritance chain from the given element to each element from which it inherits.
ElementPtr getRoot()
Return the root element of our tree.
const string & getFilePrefix() const
Return the element's file prefix string.
Definition: Element.h:174
void copyContentFrom(const ConstElementPtr &source)
Copy all attributes and descendants from the given element to this one.
void setTypedAttribute(const string &attrib, const T &data)
Set the value of an implicitly typed attribute.
Definition: Element.h:519
bool operator!=(const Element &rhs) const
Return true if the given element tree, including all descendants, differs from this one.
DocumentPtr getDocument()
Return the root document of our tree.
virtual size_t getUpstreamEdgeCount() const
Return the number of queriable upstream edges for this element.
Definition: Element.h:672
StringResolverPtr createStringResolver(const string &geom=EMPTY_STRING) const
Construct a StringResolver at the scope of this element.
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
shared_ptr< T > asA()
Dynamic cast to an instance of the given subclass.
ElementPtr getInheritsFrom() const
Return the element, if any, that this one directly inherits from.
Definition: Element.h:301
ElementPtr getUpstreamElement(size_t index=0) const
Return the Element with the given index that lies directly upstream from this one in the dataflow gra...
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
void removeAttribute(const string &attrib)
Remove the given attribute, if present.
bool operator==(const Element &rhs) const
Return true if the given element tree, including all descendants, is identical to this one.
shared_ptr< T > getChildOfType(const string &name) const
Return the child element, if any, with the given name and subclass.
Definition: Element.h:438
ElementPtr getDescendant(const string &namePath) const
Return the element specified by the given hierarchical name path, relative to the current element.
string getNamePath(ConstElementPtr relativeTo=nullptr) const
Return the element's hierarchical name path, relative to the root document.
ConstElementPtr getRoot() const
Return the root element of our tree.
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
ConstDocumentPtr getDocument() const
Return the root document of our tree.
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:709
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
ElementPtr addChildOfCategory(const string &category, string name=EMPTY_STRING)
Add a child element of the given category and name.
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
virtual Edge getUpstreamEdge(size_t index=0) const
Return the Edge with the given index that lies directly upstream from this element in the dataflow gr...
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:1343
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:1203
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:1188
A helper object for applying string modifiers to data values in the context of a specific element and...
Definition: Element.h:1229
void setFilenameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for filename data values.
Definition: Element.h:1283
static bool isResolvedType(const string &type)
Return true if the given type may be resolved by this class.
Definition: Element.h:1322
const string & getGeomPrefix() const
Return the geom prefix for this context.
Definition: Element.h:1265
void setUvTileString(const string &uvTile)
Set the UV-tile substring substitution for filename data values.
const string & getFilePrefix() const
Return the file prefix for this context.
Definition: Element.h:1249
const StringMap & getGeomNameSubstitutions() const
Return the map of geometry name substring substitutions.
Definition: Element.h:1308
void addTokenSubstitutions(ConstElementPtr element)
Add filename token substitutions for a given element.
void setFilePrefix(const string &filePrefix)
Set the file prefix for this context.
Definition: Element.h:1243
virtual string resolve(const string &str, const string &type) const
Given an input string and type, apply all appropriate modifiers and return the resulting string.
void setUdimString(const string &udim)
Set the UDIM substring substitution for filename data values.
void setGeomPrefix(const string &geomPrefix)
Set the geom prefix for this context.
Definition: Element.h:1259
const StringMap & getFilenameSubstitutions() const
Return the map of filename substring substitutions.
Definition: Element.h:1292
void setGeomNameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for geometry name data values.
Definition: Element.h:1302
static StringResolverPtr create()
Create a new string resolver.
Definition: Element.h:1232
A token element representing a string value.
Definition: Element.h:1153
An iterator object representing the state of a tree traversal.
Definition: Traversal.h:89
The base class for typed elements.
Definition: Element.h:854
virtual const string & getType() const
Return the element's type string.
Definition: Element.h:884
bool isColorType() const
Return true if the element is of color type.
Definition: Element.h:890
void setType(const string &type)
Set the element's type string.
Definition: Element.h:872
bool isMultiOutputType() const
Return true if the element is of multi-output type.
Definition: Element.h:896
TypeDefPtr getTypeDef() const
Return the TypeDef declaring the type string of this element.
bool hasType() const
Return true if the given element has a type string.
Definition: Element.h:878
The base class for elements that support typed values.
Definition: Element.h:918
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:1028
void setUnit(const string &unit)
Set the unit string of an element.
Definition: Element.h:1062
const string & getValueString() const
Get the value string of a element.
Definition: Element.h:944
void setInterfaceName(const string &name)
Set the interface name of an element.
Definition: Element.h:961
ValuePtr getDefaultValue() const
Return the default value for this element as a generic value object, which may be queried to access i...
string getResolvedValueString(StringResolverPtr resolver=nullptr) const
Return the resolved value string of an element, applying any string substitutions that are defined at...
bool validate(string *message=nullptr) const override
Validate that the given element tree, including all descendants, is consistent with the MaterialX spe...
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:1043
const string & getImplementationName() const
Return the implementation name of an element.
Definition: Element.h:995
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:1012
bool hasUnitType() const
Return true if the given element has a unit type.
Definition: Element.h:1090
void setIsUniform(bool value)
Set the uniform attribute flag on this element.
Definition: Element.h:1106
const string & getUnit() const
Return the unit string of an element.
Definition: Element.h:1074
bool getIsUniform() const
The the uniform attribute flag for this element.
Definition: Element.h:1112
void setValueString(const string &value)
Set the value string of an element.
Definition: Element.h:932
void setValue(const T &value, const string &type=EMPTY_STRING)
Set the typed value of an element.
Definition: Element.h:1005
bool hasUnit() const
Return true if the given element has a unit string.
Definition: Element.h:1068
bool hasInterfaceName() const
Return true if the given element has an interface name.
Definition: Element.h:967
void setUnitType(const string &unit)
Set the unit type of an element.
Definition: Element.h:1084
bool hasImplementationName() const
Return true if the given element has an implementation name.
Definition: Element.h:989
void setImplementationName(const string &name)
Set the implementation name of an element.
Definition: Element.h:983
const string & getActiveUnit() const
Return the unit defined by the assocaited NodeDef if this element is a child of a Node.
const string & getInterfaceName() const
Return the interface name of an element.
Definition: Element.h:973
bool hasValueString() const
Return true if the given element has a value string.
Definition: Element.h:938
const string & getUnitType() const
Return the unit type of an element.
Definition: Element.h:1096
bool hasValue() const
Return true if the element possesses a typed value.
Definition: Element.h:1018
static ValuePtr createValueFromStrings(const string &value, const string &type)
Create a new value instance from value and type strings.