MaterialX 1.39.3
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 ElementVec = vector<ElementPtr>;
70
72using ElementMap = std::unordered_map<string, ElementPtr>;
73
75using ElementPredicate = std::function<bool(ConstElementPtr)>;
76
78
84class MX_CORE_API Element : public std::enable_shared_from_this<Element>
85{
86 protected:
87 Element(ElementPtr parent, const string& category, const string& name) :
88 _category(category),
89 _name(name),
90 _parent(parent),
91 _root(parent ? parent->getRoot() : nullptr)
92 {
93 }
94
95 public:
96 virtual ~Element() { }
97 Element(const Element&) = delete;
98 Element& operator=(const Element&) = delete;
99
100 protected:
101 using DocumentPtr = shared_ptr<Document>;
102 using ConstDocumentPtr = shared_ptr<const Document>;
103
104 template <class T> friend class ElementRegistry;
105
106 public:
109 bool operator==(const Element& rhs) const;
110
113 bool operator!=(const Element& rhs) const;
114
117
119 void setCategory(const string& category)
120 {
121 _category = category;
122 }
123
127 const string& getCategory() const
128 {
129 return _category;
130 }
131
135
140 void setName(const string& name);
141
143 const string& getName() const
144 {
145 return _name;
146 }
147
153 string getNamePath(ConstElementPtr relativeTo = nullptr) const;
154
160 ElementPtr getDescendant(const string& namePath) const;
161
165
167 void setFilePrefix(const string& prefix)
168 {
169 setAttribute(FILE_PREFIX_ATTRIBUTE, prefix);
170 }
171
173 bool hasFilePrefix() const
174 {
175 return hasAttribute(FILE_PREFIX_ATTRIBUTE);
176 }
177
179 const string& getFilePrefix() const
180 {
181 return getAttribute(FILE_PREFIX_ATTRIBUTE);
182 }
183
186 const string& getActiveFilePrefix() const
187 {
188 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
189 {
190 if (elem->hasFilePrefix())
191 {
192 return elem->getFilePrefix();
193 }
194 }
195 return EMPTY_STRING;
196 }
197
201
203 void setGeomPrefix(const string& prefix)
204 {
205 setAttribute(GEOM_PREFIX_ATTRIBUTE, prefix);
206 }
207
209 bool hasGeomPrefix() const
210 {
211 return hasAttribute(GEOM_PREFIX_ATTRIBUTE);
212 }
213
215 const string& getGeomPrefix() const
216 {
217 return getAttribute(GEOM_PREFIX_ATTRIBUTE);
218 }
219
222 const string& getActiveGeomPrefix() const
223 {
224 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
225 {
226 if (elem->hasGeomPrefix())
227 {
228 return elem->getGeomPrefix();
229 }
230 }
231 return EMPTY_STRING;
232 }
233
237
239 void setColorSpace(const string& colorSpace)
240 {
241 setAttribute(COLOR_SPACE_ATTRIBUTE, colorSpace);
242 }
243
245 bool hasColorSpace() const
246 {
247 return hasAttribute(COLOR_SPACE_ATTRIBUTE);
248 }
249
251 const string& getColorSpace() const
252 {
253 return getAttribute(COLOR_SPACE_ATTRIBUTE);
254 }
255
258 const string& getActiveColorSpace() const
259 {
260 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
261 {
262 if (elem->hasColorSpace())
263 {
264 return elem->getColorSpace();
265 }
266 }
267 return EMPTY_STRING;
268 }
269
273
275 void setInheritString(const string& inherit)
276 {
277 setAttribute(INHERIT_ATTRIBUTE, inherit);
278 }
279
281 bool hasInheritString() const
282 {
283 return hasAttribute(INHERIT_ATTRIBUTE);
284 }
285
287 const string& getInheritString() const
288 {
289 return getAttribute(INHERIT_ATTRIBUTE);
290 }
291
294 {
295 if (super)
296 {
297 setInheritString(super->getName());
298 }
299 else
300 {
301 removeAttribute(INHERIT_ATTRIBUTE);
302 }
303 }
304
307 {
308 return hasInheritString() ? resolveNameReference<Element>(getInheritString()) : nullptr;
309 }
310
314
317
321
323 void setNamespace(const string& space)
324 {
325 setAttribute(NAMESPACE_ATTRIBUTE, space);
326 }
327
329 bool hasNamespace() const
330 {
331 return hasAttribute(NAMESPACE_ATTRIBUTE);
332 }
333
335 const string& getNamespace() const
336 {
337 return getAttribute(NAMESPACE_ATTRIBUTE);
338 }
339
342 string getQualifiedName(const string& name) const
343 {
344 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
345 {
346 const string& namespaceStr = elem->getNamespace();
347 if (!namespaceStr.empty())
348 {
349 // Check if the name is qualified already.
350 const size_t i = name.find_first_of(NAME_PREFIX_SEPARATOR);
351 if (i != string::npos && name.substr(0, i) == namespaceStr)
352 {
353 // The name is already qualified with this namespace,
354 // so just return it as is.
355 return name;
356 }
357 return namespaceStr + NAME_PREFIX_SEPARATOR + name;
358 }
359 }
360 return name;
361 }
362
366
368 void setDocString(const string& doc)
369 {
370 setAttribute(DOC_ATTRIBUTE, doc);
371 }
372
374 string getDocString() const
375 {
376 return getAttribute(DOC_ATTRIBUTE);
377 }
378
382
386 template <class T> bool isA(const string& category = EMPTY_STRING) const
387 {
388 if (!asA<T>())
389 return false;
390 if (!category.empty() && getCategory() != category)
391 return false;
392 return true;
393 }
394
396 template <class T> shared_ptr<T> asA();
397
399 template <class T> shared_ptr<const T> asA() const;
400
404
412 template <class T> shared_ptr<T> addChild(const string& name = EMPTY_STRING);
413
424 ElementPtr addChildOfCategory(const string& category, string name = EMPTY_STRING);
425
431 ElementPtr changeChildCategory(ElementPtr child, const string& category);
432
434 ElementPtr getChild(const string& name) const
435 {
436 ElementMap::const_iterator it = _childMap.find(name);
437 return (it != _childMap.end()) ? it->second : ElementPtr();
438 }
439
443 template <class T> shared_ptr<T> getChildOfType(const string& name) const;
444
447 const ElementVec& getChildren() const
448 {
449 return _childOrder;
450 }
451
455 template <class T> vector<shared_ptr<T>> getChildrenOfType(const string& category = EMPTY_STRING) const;
456
459 void setChildIndex(const string& name, int index);
460
463 int getChildIndex(const string& name) const;
464
466 void removeChild(const string& name);
467
471 template <class T> void removeChildOfType(const string& name)
472 {
473 if (getChildOfType<T>(name))
474 removeChild(name);
475 }
476
480
482 void setAttribute(const string& attrib, const string& value);
483
485 bool hasAttribute(const string& attrib) const
486 {
487 return _attributeMap.count(attrib) != 0;
488 }
489
492 const string& getAttribute(const string& attrib) const
493 {
494 StringMap::const_iterator it = _attributeMap.find(attrib);
495 return (it != _attributeMap.end()) ? it->second : EMPTY_STRING;
496 }
497
500 {
501 return _attributeOrder;
502 }
503
507 template <class T> void setTypedAttribute(const string& attrib, const T& data)
508 {
509 setAttribute(attrib, toValueString(data));
510 }
511
515 template <class T> T getTypedAttribute(const string& attrib) const
516 {
517 if (hasAttribute(attrib))
518 {
519 try
520 {
521 return fromValueString<T>(getAttribute(attrib));
522 }
523 catch (ExceptionTypeError&)
524 {
525 }
526 }
527 return {};
528 }
529
531 void removeAttribute(const string& attrib);
532
536
539 {
540 return shared_from_this();
541 }
542
545 {
546 return shared_from_this();
547 }
548
551 {
552 return _parent.lock();
553 }
554
557 {
558 return _parent.lock();
559 }
560
563
566
568 DocumentPtr getDocument();
569
571 ConstDocumentPtr getDocument() const;
572
575 template <class T> shared_ptr<T> getAncestorOfType()
576 {
577 for (ElementPtr elem = getSelf(); elem; elem = elem->getParent())
578 {
579 shared_ptr<T> typedElem = elem->asA<T>();
580 if (typedElem)
581 {
582 return typedElem;
583 }
584 }
585 return nullptr;
586 }
587
590 template <class T> shared_ptr<const T> getAncestorOfType() const
591 {
592 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
593 {
594 shared_ptr<const T> typedElem = elem->asA<T>();
595 if (typedElem)
596 {
597 return typedElem;
598 }
599 }
600 return nullptr;
601 }
602
606
615 string* message = nullptr) const;
616
624 virtual bool isAttributeEquivalent(ConstElementPtr rhs, const string& attributeName,
625 const ElementEquivalenceOptions& options,
626 string* message = nullptr) const;
627
631
651
676
682 virtual Edge getUpstreamEdge(size_t index = 0) const;
683
685 virtual size_t getUpstreamEdgeCount() const
686 {
687 return 0;
688 }
689
695 ElementPtr getUpstreamElement(size_t index = 0) const;
696
712
716
722 void setSourceUri(const string& sourceUri)
723 {
724 _sourceUri = sourceUri;
725 }
726
728 bool hasSourceUri() const
729 {
730 return !_sourceUri.empty();
731 }
732
734 const string& getSourceUri() const
735 {
736 return _sourceUri;
737 }
738
741 const string& getActiveSourceUri() const
742 {
743 for (ConstElementPtr elem = getSelf(); elem; elem = elem->getParent())
744 {
745 if (elem->hasSourceUri())
746 {
747 return elem->getSourceUri();
748 }
749 }
750 return EMPTY_STRING;
751 }
752
756
759 virtual bool validate(string* message = nullptr) const;
760
764
767 void copyContentFrom(const ConstElementPtr& source);
768
770 virtual void clearContent();
771
774 string createValidChildName(string name) const
775 {
776 name = name.empty() ? "_" : createValidName(name);
777 while (_childMap.count(name))
778 {
779 name = incrementName(name);
780 }
781 return name;
782 }
783
792 StringResolverPtr createStringResolver(const string& geom = EMPTY_STRING) const;
793
796 string asString() const;
797
799
800 protected:
801 // Resolve a reference to a named element at the scope of the given parent,
802 // taking the namespace at the scope of this element into account. If no parent
803 // is provided, then the root scope of the document is used.
804 template <class T> shared_ptr<T> resolveNameReference(const string& name, ConstElementPtr parent = nullptr) const
805 {
806 ConstElementPtr scope = parent ? parent : getRoot();
807 shared_ptr<T> child = scope->getChildOfType<T>(getQualifiedName(name));
808 return child ? child : scope->getChildOfType<T>(name);
809 }
810
811 // Enforce a requirement within a validate method, updating the validation
812 // state and optional output text if the requirement is not met.
813 void validateRequire(bool expression, bool& res, string* message, const string& errorDesc) const;
814
815 public:
816 static const string NAME_ATTRIBUTE;
817 static const string FILE_PREFIX_ATTRIBUTE;
818 static const string GEOM_PREFIX_ATTRIBUTE;
819 static const string COLOR_SPACE_ATTRIBUTE;
820 static const string INHERIT_ATTRIBUTE;
821 static const string NAMESPACE_ATTRIBUTE;
822 static const string DOC_ATTRIBUTE;
823 static const string XPOS_ATTRIBUTE;
824 static const string YPOS_ATTRIBUTE;
825
826 protected:
827 virtual void registerChildElement(ElementPtr child);
828 virtual void unregisterChildElement(ElementPtr child);
829
830 // Return a non-const copy of our self pointer, for use in constructing
831 // graph traversal objects that require non-const storage.
832 ElementPtr getSelfNonConst() const
833 {
834 return std::const_pointer_cast<Element>(shared_from_this());
835 }
836
837 protected:
838 string _category;
839 string _name;
840 string _sourceUri;
841
842 ElementMap _childMap;
843 ElementVec _childOrder;
844
845 StringMap _attributeMap;
846 StringVec _attributeOrder;
847
848 weak_ptr<Element> _parent;
849 weak_ptr<Element> _root;
850
851 private:
852 template <class T> static ElementPtr createElement(ElementPtr parent, const string& name)
853 {
854 return std::make_shared<T>(parent, name);
855 }
856
857 private:
858 using CreatorFunction = ElementPtr (*)(ElementPtr, const string&);
859 using CreatorMap = std::unordered_map<string, CreatorFunction>;
860
861 static CreatorMap _creatorMap;
862};
863
866class MX_CORE_API TypedElement : public Element
867{
868 protected:
869 TypedElement(ElementPtr parent, const string& category, const string& name) :
870 Element(parent, category, name)
871 {
872 }
873
874 public:
875 virtual ~TypedElement() { }
876
877 protected:
878 using TypeDefPtr = shared_ptr<class TypeDef>;
879
880 public:
883
885 void setType(const string& type)
886 {
887 setAttribute(TYPE_ATTRIBUTE, type);
888 }
889
891 bool hasType() const
892 {
893 return hasAttribute(TYPE_ATTRIBUTE);
894 }
895
897 virtual const string& getType() const
898 {
899 return getAttribute(TYPE_ATTRIBUTE);
900 }
901
903 bool isColorType() const
904 {
905 return getType() == "color3" || getType() == "color4";
906 }
907
909 bool isMultiOutputType() const
910 {
911 return getType() == MULTI_OUTPUT_TYPE_STRING;
912 }
913
917
920 TypeDefPtr getTypeDef() const;
921
923
924 public:
925 static const string TYPE_ATTRIBUTE;
926};
927
930class MX_CORE_API ValueElement : public TypedElement
931{
932 protected:
933 ValueElement(ElementPtr parent, const string& category, const string& name) :
934 TypedElement(parent, category, name)
935 {
936 }
937
938 public:
939 virtual ~ValueElement() { }
940
943
945 void setValueString(const string& value)
946 {
947 setAttribute(VALUE_ATTRIBUTE, value);
948 }
949
951 bool hasValueString() const
952 {
953 return hasAttribute(VALUE_ATTRIBUTE);
954 }
955
957 const string& getValueString() const
958 {
959 return getAttribute(VALUE_ATTRIBUTE);
960 }
961
967 string getResolvedValueString(StringResolverPtr resolver = nullptr) const;
968
972
974 void setInterfaceName(const string& name)
975 {
976 setAttribute(INTERFACE_NAME_ATTRIBUTE, name);
977 }
978
980 bool hasInterfaceName() const
981 {
982 return hasAttribute(INTERFACE_NAME_ATTRIBUTE);
983 }
984
986 const string& getInterfaceName() const
987 {
988 return getAttribute(INTERFACE_NAME_ATTRIBUTE);
989 }
990
994
996 void setImplementationName(const string& name)
997 {
998 setAttribute(IMPLEMENTATION_NAME_ATTRIBUTE, name);
999 }
1000
1003 {
1004 return hasAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
1005 }
1006
1008 const string& getImplementationName() const
1009 {
1010 return getAttribute(IMPLEMENTATION_NAME_ATTRIBUTE);
1011 }
1012
1016
1018 template <class T> void setValue(const T& value, const string& type = EMPTY_STRING)
1019 {
1020 setType(!type.empty() ? type : getTypeString<T>());
1022 }
1023
1025 void setValue(const char* value, const string& type = EMPTY_STRING)
1026 {
1027 setValue(value ? string(value) : EMPTY_STRING, type);
1028 }
1029
1031 bool hasValue() const
1032 {
1033 return hasAttribute(VALUE_ATTRIBUTE);
1034 }
1035
1042
1052
1059
1063
1065 void setUnit(const string& unit)
1066 {
1067 setAttribute(UNIT_ATTRIBUTE, unit);
1068 }
1069
1071 bool hasUnit() const
1072 {
1073 return hasAttribute(UNIT_ATTRIBUTE);
1074 }
1075
1077 const string& getUnit() const
1078 {
1079 return getAttribute(UNIT_ATTRIBUTE);
1080 }
1081
1084 const string& getActiveUnit() const;
1085
1087 void setUnitType(const string& unit)
1088 {
1089 setAttribute(UNITTYPE_ATTRIBUTE, unit);
1090 }
1091
1093 bool hasUnitType() const
1094 {
1095 return hasAttribute(UNITTYPE_ATTRIBUTE);
1096 }
1097
1099 const string& getUnitType() const
1100 {
1101 return getAttribute(UNITTYPE_ATTRIBUTE);
1102 }
1103
1107
1109 void setIsUniform(bool value)
1110 {
1111 setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
1112 }
1113
1115 bool getIsUniform() const
1116 {
1117 return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
1118 }
1119
1123
1131 bool isAttributeEquivalent(ConstElementPtr rhs, const string& attributeName,
1132 const ElementEquivalenceOptions& options,
1133 string* message = nullptr) const override;
1134
1138
1141 bool validate(string* message = nullptr) const override;
1142
1144
1145 public:
1146 static const string VALUE_ATTRIBUTE;
1147 static const string INTERFACE_NAME_ATTRIBUTE;
1148 static const string IMPLEMENTATION_NAME_ATTRIBUTE;
1149 static const string IMPLEMENTATION_TYPE_ATTRIBUTE;
1150 static const string ENUM_ATTRIBUTE;
1151 static const string ENUM_VALUES_ATTRIBUTE;
1152 static const string UI_NAME_ATTRIBUTE;
1153 static const string UI_FOLDER_ATTRIBUTE;
1154 static const string UI_MIN_ATTRIBUTE;
1155 static const string UI_MAX_ATTRIBUTE;
1156 static const string UI_SOFT_MIN_ATTRIBUTE;
1157 static const string UI_SOFT_MAX_ATTRIBUTE;
1158 static const string UI_STEP_ATTRIBUTE;
1159 static const string UI_ADVANCED_ATTRIBUTE;
1160 static const string UNIT_ATTRIBUTE;
1161 static const string UNITTYPE_ATTRIBUTE;
1162 static const string UNIFORM_ATTRIBUTE;
1163};
1164
1170class MX_CORE_API Token : public ValueElement
1171{
1172 public:
1173 Token(ElementPtr parent, const string& name) :
1174 ValueElement(parent, CATEGORY, name)
1175 {
1176 }
1177 virtual ~Token() { }
1178
1179 public:
1180 static const string CATEGORY;
1181};
1182
1190class MX_CORE_API CommentElement : public Element
1191{
1192 public:
1193 CommentElement(ElementPtr parent, const string& name) :
1194 Element(parent, CATEGORY, name)
1195 {
1196 }
1197 virtual ~CommentElement() { }
1198
1199 public:
1200 static const string CATEGORY;
1201};
1202
1205class MX_CORE_API NewlineElement : public Element
1206{
1207 public:
1208 NewlineElement(ElementPtr parent, const string& name) :
1209 Element(parent, CATEGORY, name)
1210 {
1211 }
1212 virtual ~NewlineElement() { }
1213
1214 public:
1215 static const string CATEGORY;
1216};
1217
1220class MX_CORE_API GenericElement : public Element
1221{
1222 public:
1223 GenericElement(ElementPtr parent, const string& name) :
1224 Element(parent, CATEGORY, name)
1225 {
1226 }
1227 virtual ~GenericElement() { }
1228
1229 public:
1230 static const string CATEGORY;
1231};
1232
1246class MX_CORE_API StringResolver
1247{
1248 public:
1251 {
1252 return StringResolverPtr(new StringResolver());
1253 }
1254
1255 virtual ~StringResolver() { }
1256
1259
1261 void setFilePrefix(const string& filePrefix)
1262 {
1263 _filePrefix = filePrefix;
1264 }
1265
1267 const string& getFilePrefix() const
1268 {
1269 return _filePrefix;
1270 }
1271
1275
1277 void setGeomPrefix(const string& geomPrefix)
1278 {
1279 _geomPrefix = geomPrefix;
1280 }
1281
1283 const string& getGeomPrefix() const
1284 {
1285 return _geomPrefix;
1286 }
1287
1291
1294 void setUdimString(const string& udim);
1295
1298 void setUvTileString(const string& uvTile);
1299
1301 void setFilenameSubstitution(const string& key, const string& value)
1302 {
1303 _filenameMap[key] = value;
1304 }
1305
1308
1311 {
1312 return _filenameMap;
1313 }
1314
1318
1320 void setGeomNameSubstitution(const string& key, const string& value)
1321 {
1322 _geomNameMap[key] = value;
1323 }
1324
1327 {
1328 return _geomNameMap;
1329 }
1330
1334
1337 virtual string resolve(const string& str, const string& type) const;
1338
1340 static bool isResolvedType(const string& type)
1341 {
1342 return type == FILENAME_TYPE_STRING || type == GEOMNAME_TYPE_STRING;
1343 }
1344
1346
1347 protected:
1348 StringResolver() { }
1349
1350 protected:
1351 string _filePrefix;
1352 string _geomPrefix;
1353 StringMap _filenameMap;
1354 StringMap _geomNameMap;
1355};
1356
1359class MX_CORE_API ElementEquivalenceOptions
1360{
1361 public:
1362 ElementEquivalenceOptions()
1363 {
1368 };
1369 ~ElementEquivalenceOptions() { }
1370
1374
1377
1380
1391};
1392
1396class MX_CORE_API ExceptionOrphanedElement : public Exception
1397{
1398 public:
1399 using Exception::Exception;
1400};
1401
1402template <class T> shared_ptr<T> Element::addChild(const string& name)
1403{
1404 string childName = name;
1405 if (childName.empty())
1406 {
1407 childName = createValidChildName(T::CATEGORY + "1");
1408 }
1409
1410 if (_childMap.count(childName))
1411 throw Exception("Child name is not unique: " + childName);
1412
1413 shared_ptr<T> child = std::make_shared<T>(getSelf(), childName);
1414 registerChildElement(child);
1415
1416 return child;
1417}
1418
1422MX_CORE_API bool targetStringsMatch(const string& target1, const string& target2);
1423
1426MX_CORE_API string prettyPrint(ConstElementPtr elem);
1427
1428MATERIALX_NAMESPACE_END
1429
1430#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:72
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:75
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...
vector< ElementPtr > ElementVec
A vector of elements.
Definition Element.h:69
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.
std::set< string > StringSet
A set of strings.
Definition Library.h:64
vector< string > StringVec
A vector of strings.
Definition Library.h:60
std::unordered_map< string, string > StringMap
An unordered map with strings as both keys and values.
Definition Library.h:62
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.
MX_CORE_API T fromValueString(const string &value)
Convert the given value string to a data value of the given type.
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition Value.h:30
MX_CORE_API string toValueString(const T &data)
Convert the given data value to a value string.
MX_CORE_API const string & getTypeString()
Return the type string associated with the given data type.
An element representing a block of descriptive text within a document, which will be stored a comment...
Definition Element.h:1191
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
A set of options for comparing the functional equivalence of elements.
Definition Element.h:1360
StringSet attributeExclusionList
Specifies the set of attributes that should be excluded when performing a comparison.
Definition Element.h:1390
bool performValueComparisons
Perform value comparisons as opposed to literal string comparisons.
Definition Element.h:1373
int floatPrecision
Floating point precision to use for floating point value comparisons.
Definition Element.h:1379
Value::FloatFormat floatFormat
Floating point format to use for floating point value comparisons.
Definition Element.h:1376
The base class for MaterialX elements.
Definition Element.h:85
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:741
bool hasNamespace() const
Return true if this element has a namespace string.
Definition Element.h:329
const string & getAttribute(const string &attrib) const
Return the value string of the given attribute.
Definition Element.h:492
ConstElementPtr getSelf() const
Return our self pointer.
Definition Element.h:544
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:222
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:386
void setDocString(const string &doc)
Set the documentation string of this element.
Definition Element.h:368
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:575
bool hasGeomPrefix() const
Return true if the given element has a geom prefix string.
Definition Element.h:209
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:590
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:287
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:728
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:251
shared_ptr< T > addChild(const string &name=EMPTY_STRING)
Add a child element of the given subclass and name.
Definition Element.h:1402
const string & getName() const
Return the element's name string.
Definition Element.h:143
void setColorSpace(const string &colorSpace)
Set the element's color space string.
Definition Element.h:239
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:342
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:774
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:215
void setFilePrefix(const string &prefix)
Set the element's file prefix string.
Definition Element.h:167
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:499
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:434
const string & getSourceUri() const
Return the element's source URI.
Definition Element.h:734
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:245
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:179
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:507
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 queryable upstream edges for this element.
Definition Element.h:685
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:281
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:258
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:306
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:515
void setCategory(const string &category)
Set the element's category string.
Definition Element.h:119
void removeAttribute(const string &attrib)
Remove the given attribute, if present.
bool isEquivalent(ConstElementPtr rhs, const ElementEquivalenceOptions &options, string *message=nullptr) const
Return true if the given element tree, including all descendents, is considered to be equivalent to t...
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.
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:203
void setNamespace(const string &space)
Set the namespace string of this element.
Definition Element.h:323
ElementPtr getSelf()
Return our self pointer.
Definition Element.h:538
ConstElementPtr getParent() const
Return our parent element.
Definition Element.h:556
const ElementVec & getChildren() const
Return a constant vector of all child elements.
Definition Element.h:447
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:186
void setInheritString(const string &inherit)
Set the inherit string of this element.
Definition Element.h:275
const string & getNamespace() const
Return the namespace string of this element.
Definition Element.h:335
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:485
void removeChildOfType(const string &name)
Remove the child element, if any, with the given name and subclass.
Definition Element.h:471
void setSourceUri(const string &sourceUri)
Set the element's source URI.
Definition Element.h:722
virtual bool isAttributeEquivalent(ConstElementPtr rhs, const string &attributeName, const ElementEquivalenceOptions &options, string *message=nullptr) const
Return true if the attribute on a given element is equivalent based on the equivalence criteria provi...
string getDocString() const
Return the documentation string of this element.
Definition Element.h:374
void setInheritsFrom(ConstElementPtr super)
Set the element that this one directly inherits from.
Definition Element.h:293
ElementPtr getParent()
Return our parent element.
Definition Element.h:550
bool hasFilePrefix() const
Return true if the given element has a file prefix string.
Definition Element.h:173
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:127
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...
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:1397
An exception that is thrown when a type mismatch is encountered.
Definition Exception.h:56
A generic element subclass, for instantiating elements with unrecognized categories.
Definition Element.h:1221
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:336
An element representing a newline within a document.
Definition Element.h:1206
A helper object for applying string modifiers to data values in the context of a specific element and...
Definition Element.h:1247
void setFilenameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for filename data values.
Definition Element.h:1301
static bool isResolvedType(const string &type)
Return true if the given type may be resolved by this class.
Definition Element.h:1340
const string & getGeomPrefix() const
Return the geom prefix for this context.
Definition Element.h:1283
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:1267
const StringMap & getGeomNameSubstitutions() const
Return the map of geometry name substring substitutions.
Definition Element.h:1326
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:1261
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:1277
const StringMap & getFilenameSubstitutions() const
Return the map of filename substring substitutions.
Definition Element.h:1310
void setGeomNameSubstitution(const string &key, const string &value)
Set an arbitrary substring substitution for geometry name data values.
Definition Element.h:1320
static StringResolverPtr create()
Create a new string resolver.
Definition Element.h:1250
A token element representing a string value.
Definition Element.h:1171
An iterator object representing the state of a tree traversal.
Definition Traversal.h:89
The base class for typed elements.
Definition Element.h:867
virtual const string & getType() const
Return the element's type string.
Definition Element.h:897
bool isColorType() const
Return true if the element is of color type.
Definition Element.h:903
void setType(const string &type)
Set the element's type string.
Definition Element.h:885
bool isMultiOutputType() const
Return true if the element is of multi-output type.
Definition Element.h:909
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:891
The base class for elements that support typed values.
Definition Element.h:931
ValuePtr getValue() const
Return the typed value of an element as a generic value object, which may be queried to access its da...
bool isAttributeEquivalent(ConstElementPtr rhs, const string &attributeName, const ElementEquivalenceOptions &options, string *message=nullptr) const override
Return true if the attribute on a given element is equivalent based on the equivalence criteria provi...
void setUnit(const string &unit)
Set the unit string of an element.
Definition Element.h:1065
const string & getValueString() const
Get the value string of a element.
Definition Element.h:957
void setInterfaceName(const string &name)
Set the interface name of an element.
Definition Element.h:974
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...
const string & getImplementationName() const
Return the implementation name of an element.
Definition Element.h:1008
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:1025
bool hasUnitType() const
Return true if the given element has a unit type.
Definition Element.h:1093
void setIsUniform(bool value)
Set the uniform attribute flag on this element.
Definition Element.h:1109
const string & getUnit() const
Return the unit string of an element.
Definition Element.h:1077
bool getIsUniform() const
The the uniform attribute flag for this element.
Definition Element.h:1115
void setValueString(const string &value)
Set the value string of an element.
Definition Element.h:945
void setValue(const T &value, const string &type=EMPTY_STRING)
Set the typed value of an element.
Definition Element.h:1018
bool hasUnit() const
Return true if the given element has a unit string.
Definition Element.h:1071
bool hasInterfaceName() const
Return true if the given element has an interface name.
Definition Element.h:980
void setUnitType(const string &unit)
Set the unit type of an element.
Definition Element.h:1087
bool hasImplementationName() const
Return true if the given element has an implementation name.
Definition Element.h:1002
void setImplementationName(const string &name)
Set the implementation name of an element.
Definition Element.h:996
const string & getActiveUnit() const
Return the unit defined by the associated NodeDef if this element is a child of a Node.
const string & getInterfaceName() const
Return the interface name of an element.
Definition Element.h:986
bool hasValueString() const
Return true if the given element has a value string.
Definition Element.h:951
const string & getUnitType() const
Return the unit type of an element.
Definition Element.h:1099
bool hasValue() const
Return true if the element possesses a typed value.
Definition Element.h:1031
static FloatFormat getFloatFormat()
Return the current float format.
Definition Value.h:114
FloatFormat
Float formats to use when converting values to strings.
Definition Value.h:50
static int getFloatPrecision()
Return the current float precision.
Definition Value.h:120