MaterialX 1.38.2
Document.h
Go to the documentation of this file.
1//
2// TM & (c) 2017 Lucasfilm Entertainment Company Ltd. and Lucasfilm Ltd.
3// All rights reserved. See LICENSE.txt for license.
4//
5
6#ifndef MATERIALX_DOCUMENT
7#define MATERIALX_DOCUMENT
8
11
13
14#include <MaterialXCore/Look.h>
15#include <MaterialXCore/Node.h>
16
17namespace MaterialX
18{
19
20class Document;
21
23using DocumentPtr = shared_ptr<Document>;
25using ConstDocumentPtr = shared_ptr<const Document>;
26
32class MX_CORE_API Document : public GraphElement
33{
34 public:
35 Document(ElementPtr parent, const string& name);
36 virtual ~Document();
37
39 template <class T> static shared_ptr<T> createDocument()
40 {
41 shared_ptr<T> doc = std::make_shared<T>(ElementPtr(), EMPTY_STRING);
42 doc->initialize();
43 return doc;
44 }
45
47 virtual void initialize();
48
50 virtual DocumentPtr copy() const
51 {
52 DocumentPtr doc = createDocument<Document>();
53 doc->copyContentFrom(getSelf());
54 return doc;
55 }
56
61 void importLibrary(const ConstDocumentPtr& library);
62
64 StringSet getReferencedSourceUris() const;
65
68
74 NodeGraphPtr addNodeGraph(const string& name = EMPTY_STRING)
75 {
76 return addChild<NodeGraph>(name);
77 }
78
80 NodeGraphPtr getNodeGraph(const string& name) const
81 {
82 return getChildOfType<NodeGraph>(name);
83 }
84
86 vector<NodeGraphPtr> getNodeGraphs() const
87 {
88 return getChildrenOfType<NodeGraph>();
89 }
90
92 void removeNodeGraph(const string& name)
93 {
94 removeChildOfType<NodeGraph>(name);
95 }
96
100 vector<PortElementPtr> getMatchingPorts(const string& nodeName) const;
101
105
112 GeomInfoPtr addGeomInfo(const string& name = EMPTY_STRING, const string& geom = UNIVERSAL_GEOM_NAME)
113 {
114 GeomInfoPtr geomInfo = addChild<GeomInfo>(name);
115 geomInfo->setGeom(geom);
116 return geomInfo;
117 }
118
120 GeomInfoPtr getGeomInfo(const string& name) const
121 {
122 return getChildOfType<GeomInfo>(name);
123 }
124
126 vector<GeomInfoPtr> getGeomInfos() const
127 {
128 return getChildrenOfType<GeomInfo>();
129 }
130
132 void removeGeomInfo(const string& name)
133 {
134 removeChildOfType<GeomInfo>(name);
135 }
136
138 ValuePtr getGeomPropValue(const string& geomPropName, const string& geom = UNIVERSAL_GEOM_NAME) const;
139
143
148 GeomPropDefPtr addGeomPropDef(const string& name, const string& geomprop)
149 {
150 GeomPropDefPtr geomPropDef = addChild<GeomPropDef>(name);
151 geomPropDef->setGeomProp(geomprop);
152 return geomPropDef;
153 }
154
156 GeomPropDefPtr getGeomPropDef(const string& name) const
157 {
158 return getChildOfType<GeomPropDef>(name);
159 }
160
162 vector<GeomPropDefPtr> getGeomPropDefs() const
163 {
164 return getChildrenOfType<GeomPropDef>();
165 }
166
168 void removeGeomPropDef(const string& name)
169 {
170 removeChildOfType<GeomPropDef>(name);
171 }
172
176
182 LookPtr addLook(const string& name = EMPTY_STRING)
183 {
184 return addChild<Look>(name);
185 }
186
188 LookPtr getLook(const string& name) const
189 {
190 return getChildOfType<Look>(name);
191 }
192
194 vector<LookPtr> getLooks() const
195 {
196 return getChildrenOfType<Look>();
197 }
198
200 void removeLook(const string& name)
201 {
202 removeChildOfType<Look>(name);
203 }
204
208
214 LookGroupPtr addLookGroup(const string& name = EMPTY_STRING)
215 {
216 return addChild<LookGroup>(name);
217 }
218
220 LookGroupPtr getLookGroup(const string& name) const
221 {
222 return getChildOfType<LookGroup>(name);
223 }
224
226 vector<LookGroupPtr> getLookGroups() const
227 {
228 return getChildrenOfType<LookGroup>();
229 }
230
232 void removeLookGroup(const string& name)
233 {
234 removeChildOfType<LookGroup>(name);
235 }
236
240
246 CollectionPtr addCollection(const string& name = EMPTY_STRING)
247 {
248 return addChild<Collection>(name);
249 }
250
252 CollectionPtr getCollection(const string& name) const
253 {
254 return getChildOfType<Collection>(name);
255 }
256
258 vector<CollectionPtr> getCollections() const
259 {
260 return getChildrenOfType<Collection>();
261 }
262
264 void removeCollection(const string& name)
265 {
266 removeChildOfType<Collection>(name);
267 }
268
272
278 TypeDefPtr addTypeDef(const string& name)
279 {
280 return addChild<TypeDef>(name);
281 }
282
284 TypeDefPtr getTypeDef(const string& name) const
285 {
286 return getChildOfType<TypeDef>(name);
287 }
288
290 vector<TypeDefPtr> getTypeDefs() const
291 {
292 return getChildrenOfType<TypeDef>();
293 }
294
296 void removeTypeDef(const string& name)
297 {
298 removeChildOfType<TypeDef>(name);
299 }
300
304
314 NodeDefPtr addNodeDef(const string& name = EMPTY_STRING,
315 const string& type = DEFAULT_TYPE_STRING,
316 const string& node = EMPTY_STRING)
317 {
318 NodeDefPtr child = addChild<NodeDef>(name);
319 if (!type.empty() && type != MULTI_OUTPUT_TYPE_STRING)
320 {
321 child->addOutput("out", type);
322 }
323 if (!node.empty())
324 {
325 child->setNodeString(node);
326 }
327 return child;
328 }
329
340 NodeDefPtr addNodeDefFromGraph(const NodeGraphPtr nodeGraph, const string& nodeDefName, const string& node, const string& version,
341 bool isDefaultVersion, const string& nodeGroup, string& newGraphName);
342
344 NodeDefPtr getNodeDef(const string& name) const
345 {
346 return getChildOfType<NodeDef>(name);
347 }
348
350 vector<NodeDefPtr> getNodeDefs() const
351 {
352 return getChildrenOfType<NodeDef>();
353 }
354
356 void removeNodeDef(const string& name)
357 {
358 removeChildOfType<NodeDef>(name);
359 }
360
362 vector<NodeDefPtr> getMatchingNodeDefs(const string& nodeName) const;
363
367
373 AttributeDefPtr addAttributeDef(const string& name = EMPTY_STRING)
374 {
375 return addChild<AttributeDef>(name);
376 }
377
379 AttributeDefPtr getAttributeDef(const string& name) const
380 {
381 return getChildOfType<AttributeDef>(name);
382 }
383
385 vector<AttributeDefPtr> getAttributeDefs() const
386 {
387 return getChildrenOfType<AttributeDef>();
388 }
389
391 void removeAttributeDef(const string& name)
392 {
393 removeChildOfType<AttributeDef>(name);
394 }
395
399
405 TargetDefPtr addTargetDef(const string& name = EMPTY_STRING)
406 {
407 return addChild<TargetDef>(name);
408 }
409
411 TargetDefPtr getTargetDef(const string& name) const
412 {
413 return getChildOfType<TargetDef>(name);
414 }
415
417 vector<TargetDefPtr> getTargetDefs() const
418 {
419 return getChildrenOfType<TargetDef>();
420 }
421
423 void removeTargetDef(const string& name)
424 {
425 removeChildOfType<TargetDef>(name);
426 }
427
431
437 PropertySetPtr addPropertySet(const string& name = EMPTY_STRING)
438 {
439 return addChild<PropertySet>(name);
440 }
441
443 PropertySetPtr getPropertySet(const string& name) const
444 {
445 return getChildOfType<PropertySet>(name);
446 }
447
449 vector<PropertySetPtr> getPropertySets() const
450 {
451 return getChildrenOfType<PropertySet>();
452 }
453
455 void removePropertySet(const string& name)
456 {
457 removeChildOfType<PropertySet>(name);
458 }
459
463
469 VariantSetPtr addVariantSet(const string& name = EMPTY_STRING)
470 {
471 return addChild<VariantSet>(name);
472 }
473
475 VariantSetPtr getVariantSet(const string& name) const
476 {
477 return getChildOfType<VariantSet>(name);
478 }
479
481 vector<VariantSetPtr> getVariantSets() const
482 {
483 return getChildrenOfType<VariantSet>();
484 }
485
487 void removeVariantSet(const string& name)
488 {
489 removeChildOfType<VariantSet>(name);
490 }
491
495
501 ImplementationPtr addImplementation(const string& name = EMPTY_STRING)
502 {
503 return addChild<Implementation>(name);
504 }
505
507 ImplementationPtr getImplementation(const string& name) const
508 {
509 return getChildOfType<Implementation>(name);
510 }
511
513 vector<ImplementationPtr> getImplementations() const
514 {
515 return getChildrenOfType<Implementation>();
516 }
517
519 void removeImplementation(const string& name)
520 {
521 removeChildOfType<Implementation>(name);
522 }
523
527 vector<InterfaceElementPtr> getMatchingImplementations(const string& nodeDef) const;
528
532
533 UnitDefPtr addUnitDef(const string& name)
534 {
535 if (name.empty())
536 {
537 throw Exception("A unit definition name cannot be empty");
538 }
539 return addChild<UnitDef>(name);
540 }
541
543 UnitDefPtr getUnitDef(const string& name) const
544 {
545 return getChildOfType<UnitDef>(name);
546 }
547
549 vector<UnitDefPtr> getUnitDefs() const
550 {
551 return getChildrenOfType<UnitDef>();
552 }
553
555 void removeUnitDef(const string& name)
556 {
557 removeChildOfType<UnitDef>(name);
558 }
559
563
564 UnitTypeDefPtr addUnitTypeDef(const string& name)
565 {
566 if (name.empty())
567 {
568 throw Exception("A unit type definition name cannot be empty");
569 }
570 return addChild<UnitTypeDef>(name);
571 }
572
574 UnitTypeDefPtr getUnitTypeDef(const string& name) const
575 {
576 return getChildOfType<UnitTypeDef>(name);
577 }
578
580 vector<UnitTypeDefPtr> getUnitTypeDefs() const
581 {
582 return getChildrenOfType<UnitTypeDef>();
583 }
584
586 void removeUnitTypeDef(const string& name)
587 {
588 removeChildOfType<UnitTypeDef>(name);
589 }
590
594
596 std::pair<int, int> getVersionIntegers() const override;
597
600 void upgradeVersion();
601
605
607 void setColorManagementSystem(const string& cms)
608 {
609 setAttribute(CMS_ATTRIBUTE, cms);
610 }
611
614 {
615 return hasAttribute(CMS_ATTRIBUTE);
616 }
617
619 const string& getColorManagementSystem() const
620 {
621 return getAttribute(CMS_ATTRIBUTE);
622 }
623
627
629 void setColorManagementConfig(const string& cmsConfig)
630 {
631 setAttribute(CMS_CONFIG_ATTRIBUTE, cmsConfig);
632 }
633
636 {
637 return hasAttribute(CMS_CONFIG_ATTRIBUTE);
638 }
639
641 const string& getColorManagementConfig() const
642 {
643 return getAttribute(CMS_CONFIG_ATTRIBUTE);
644 }
645
649
655 bool validate(string* message = nullptr) const override;
656
660
662 void invalidateCache();
663
665
666 public:
667 static const string CATEGORY;
668 static const string CMS_ATTRIBUTE;
669 static const string CMS_CONFIG_ATTRIBUTE;
670
671 private:
672 class Cache;
673 std::unique_ptr<Cache> _cache;
674};
675
678MX_CORE_API DocumentPtr createDocument();
679
680} // namespace MaterialX
681
682#endif
shared_ptr< TargetDef > TargetDefPtr
A shared pointer to a TargetDef.
Definition: Definition.h:48
shared_ptr< UnitDef > UnitDefPtr
A shared pointer to a UnitDef.
Definition: Definition.h:63
shared_ptr< Implementation > ImplementationPtr
A shared pointer to an Implementation.
Definition: Definition.h:38
shared_ptr< AttributeDef > AttributeDefPtr
A shared pointer to an AttributeDef.
Definition: Definition.h:73
shared_ptr< NodeDef > NodeDefPtr
A shared pointer to a NodeDef.
Definition: Definition.h:33
shared_ptr< UnitTypeDef > UnitTypeDefPtr
A shared pointer to a UnitTypeDef.
Definition: Definition.h:68
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:25
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:23
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
shared_ptr< GeomInfo > GeomInfoPtr
A shared pointer to a GeomInfo.
Definition: Geom.h:39
shared_ptr< Collection > CollectionPtr
A shared pointer to a Collection.
Definition: Geom.h:54
shared_ptr< GeomPropDef > GeomPropDefPtr
A shared pointer to a GeomPropDef.
Definition: Geom.h:49
Look element subclasses.
shared_ptr< LookGroup > LookGroupPtr
A shared pointer to a LookGroup.
Definition: Look.h:33
shared_ptr< Look > LookPtr
A shared pointer to a Look.
Definition: Look.h:28
Import and export declarations for the Core library.
std::set< string > StringSet
A set of strings.
Definition: Library.h:60
Node element subclasses.
shared_ptr< NodeGraph > NodeGraphPtr
A shared pointer to a NodeGraph.
Definition: Node.h:35
shared_ptr< PropertySet > PropertySetPtr
A shared pointer to a PropertySet.
Definition: Property.h:35
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:30
shared_ptr< VariantSet > VariantSetPtr
A shared pointer to a VariantSet.
Definition: Variant.h:29
A MaterialX document, which represents the top-level element in the MaterialX ownership hierarchy.
Definition: Document.h:33
vector< PropertySetPtr > getPropertySets() const
Return a vector of all PropertySet elements in the document.
Definition: Document.h:449
TargetDefPtr addTargetDef(const string &name=EMPTY_STRING)
Add an TargetDef to the document.
Definition: Document.h:405
void removeLookGroup(const string &name)
Remove the LookGroup, if any, with the given name.
Definition: Document.h:232
void removeNodeDef(const string &name)
Remove the NodeDef, if any, with the given name.
Definition: Document.h:356
vector< LookPtr > getLooks() const
Return a vector of all Look elements in the document.
Definition: Document.h:194
void removeUnitTypeDef(const string &name)
Remove the UnitTypeDef, if any, with the given name.
Definition: Document.h:586
void removeVariantSet(const string &name)
Remove the VariantSet, if any, with the given name.
Definition: Document.h:487
vector< UnitTypeDefPtr > getUnitTypeDefs() const
Return a vector of all UnitTypeDef elements in the document.
Definition: Document.h:580
AttributeDefPtr addAttributeDef(const string &name=EMPTY_STRING)
Add an AttributeDef to the document.
Definition: Document.h:373
GeomInfoPtr getGeomInfo(const string &name) const
Return the GeomInfo, if any, with the given name.
Definition: Document.h:120
GeomPropDefPtr getGeomPropDef(const string &name) const
Return the GeomPropDef, if any, with the given name.
Definition: Document.h:156
TargetDefPtr getTargetDef(const string &name) const
Return the AttributeDef, if any, with the given name.
Definition: Document.h:411
ImplementationPtr getImplementation(const string &name) const
Return the Implementation, if any, with the given name.
Definition: Document.h:507
UnitTypeDefPtr getUnitTypeDef(const string &name) const
Return the UnitTypeDef, if any, with the given name.
Definition: Document.h:574
void setColorManagementSystem(const string &cms)
Set the color management system string.
Definition: Document.h:607
void removeImplementation(const string &name)
Remove the Implementation, if any, with the given name.
Definition: Document.h:519
void removeNodeGraph(const string &name)
Remove the NodeGraph, if any, with the given name.
Definition: Document.h:92
bool hasColorManagementSystem() const
Return true if a color management system string has been set.
Definition: Document.h:613
TypeDefPtr getTypeDef(const string &name) const
Return the TypeDef, if any, with the given name.
Definition: Document.h:284
CollectionPtr addCollection(const string &name=EMPTY_STRING)
Add a Collection to the document.
Definition: Document.h:246
vector< ImplementationPtr > getImplementations() const
Return a vector of all Implementation elements in the document.
Definition: Document.h:513
vector< TypeDefPtr > getTypeDefs() const
Return a vector of all TypeDef elements in the document.
Definition: Document.h:290
const string & getColorManagementConfig() const
Return the color management config string.
Definition: Document.h:641
void removeGeomInfo(const string &name)
Remove the GeomInfo, if any, with the given name.
Definition: Document.h:132
vector< NodeGraphPtr > getNodeGraphs() const
Return a vector of all NodeGraph elements in the document.
Definition: Document.h:86
vector< UnitDefPtr > getUnitDefs() const
Return a vector of all Member elements in the TypeDef.
Definition: Document.h:549
CollectionPtr getCollection(const string &name) const
Return the Collection, if any, with the given name.
Definition: Document.h:252
void removeTypeDef(const string &name)
Remove the TypeDef, if any, with the given name.
Definition: Document.h:296
bool hasColorManagementConfig() const
Return true if a color management config string has been set.
Definition: Document.h:635
vector< TargetDefPtr > getTargetDefs() const
Return a vector of all TargetDef elements in the document.
Definition: Document.h:417
GeomPropDefPtr addGeomPropDef(const string &name, const string &geomprop)
Add a GeomPropDef to the document.
Definition: Document.h:148
LookGroupPtr addLookGroup(const string &name=EMPTY_STRING)
Add a LookGroup to the document.
Definition: Document.h:214
void setColorManagementConfig(const string &cmsConfig)
Set the color management config string.
Definition: Document.h:629
void removeTargetDef(const string &name)
Remove the TargetDef, if any, with the given name.
Definition: Document.h:423
GeomInfoPtr addGeomInfo(const string &name=EMPTY_STRING, const string &geom=UNIVERSAL_GEOM_NAME)
Add a GeomInfo to the document.
Definition: Document.h:112
NodeGraphPtr getNodeGraph(const string &name) const
Return the NodeGraph, if any, with the given name.
Definition: Document.h:80
LookPtr addLook(const string &name=EMPTY_STRING)
Add a Look to the document.
Definition: Document.h:182
vector< AttributeDefPtr > getAttributeDefs() const
Return a vector of all AttributeDef elements in the document.
Definition: Document.h:385
UnitDefPtr getUnitDef(const string &name) const
Return the UnitDef, if any, with the given name.
Definition: Document.h:543
void removeLook(const string &name)
Remove the Look, if any, with the given name.
Definition: Document.h:200
vector< GeomInfoPtr > getGeomInfos() const
Return a vector of all GeomInfo elements in the document.
Definition: Document.h:126
NodeGraphPtr addNodeGraph(const string &name=EMPTY_STRING)
Add a NodeGraph to the document.
Definition: Document.h:74
NodeDefPtr addNodeDef(const string &name=EMPTY_STRING, const string &type=DEFAULT_TYPE_STRING, const string &node=EMPTY_STRING)
Add a NodeDef to the document.
Definition: Document.h:314
vector< VariantSetPtr > getVariantSets() const
Return a vector of all VariantSet elements in the document.
Definition: Document.h:481
VariantSetPtr addVariantSet(const string &name=EMPTY_STRING)
Add a VariantSet to the document.
Definition: Document.h:469
NodeDefPtr getNodeDef(const string &name) const
Return the NodeDef, if any, with the given name.
Definition: Document.h:344
AttributeDefPtr getAttributeDef(const string &name) const
Return the AttributeDef, if any, with the given name.
Definition: Document.h:379
ImplementationPtr addImplementation(const string &name=EMPTY_STRING)
Add an Implementation to the document.
Definition: Document.h:501
void removeAttributeDef(const string &name)
Remove the AttributeDef, if any, with the given name.
Definition: Document.h:391
vector< CollectionPtr > getCollections() const
Return a vector of all Collection elements in the document.
Definition: Document.h:258
virtual DocumentPtr copy() const
Create a deep copy of the document.
Definition: Document.h:50
vector< LookGroupPtr > getLookGroups() const
Return a vector of all LookGroup elements in the document.
Definition: Document.h:226
LookGroupPtr getLookGroup(const string &name) const
Return the LookGroup, if any, with the given name.
Definition: Document.h:220
PropertySetPtr getPropertySet(const string &name) const
Return the PropertySet, if any, with the given name.
Definition: Document.h:443
const string & getColorManagementSystem() const
Return the color management system string.
Definition: Document.h:619
LookPtr getLook(const string &name) const
Return the Look, if any, with the given name.
Definition: Document.h:188
static shared_ptr< T > createDocument()
Create a new document of the given subclass.
Definition: Document.h:39
VariantSetPtr getVariantSet(const string &name) const
Return the VariantSet, if any, with the given name.
Definition: Document.h:475
vector< GeomPropDefPtr > getGeomPropDefs() const
Return a vector of all GeomPropDef elements in the document.
Definition: Document.h:162
void removeCollection(const string &name)
Remove the Collection, if any, with the given name.
Definition: Document.h:264
void removeGeomPropDef(const string &name)
Remove the GeomPropDef, if any, with the given name.
Definition: Document.h:168
void removeUnitDef(const string &name)
Remove the UnitDef, if any, with the given name.
Definition: Document.h:555
vector< NodeDefPtr > getNodeDefs() const
Return a vector of all NodeDef elements in the document.
Definition: Document.h:350
TypeDefPtr addTypeDef(const string &name)
Add a TypeDef to the document.
Definition: Document.h:278
PropertySetPtr addPropertySet(const string &name=EMPTY_STRING)
Add a PropertySet to the document.
Definition: Document.h:437
void removePropertySet(const string &name)
Remove the PropertySet, if any, with the given name.
Definition: Document.h:455
The base class for exceptions that are propagated from the MaterialX library to the client applicatio...
Definition: Exception.h:23
The base class for graph elements such as NodeGraph and Document.
Definition: Node.h:177