MaterialX 1.39.1
Loading...
Searching...
No Matches
Document.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_DOCUMENT
7#define MATERIALX_DOCUMENT
8
11
13
14#include <MaterialXCore/Look.h>
15#include <MaterialXCore/Node.h>
16
17MATERIALX_NAMESPACE_BEGIN
18
19class Document;
20
22using DocumentPtr = shared_ptr<Document>;
24using ConstDocumentPtr = shared_ptr<const Document>;
25
31class MX_CORE_API Document : public GraphElement
32{
33 public:
34 Document(ElementPtr parent, const string& name);
35 virtual ~Document();
36
38 template <class T> static shared_ptr<T> createDocument()
39 {
40 shared_ptr<T> doc = std::make_shared<T>(ElementPtr(), EMPTY_STRING);
41 doc->initialize();
42 return doc;
43 }
44
46 virtual void initialize();
47
49 virtual DocumentPtr copy() const
50 {
51 DocumentPtr doc = createDocument<Document>();
52 doc->copyContentFrom(getSelf());
53 return doc;
54 }
55
60 void importLibrary(const ConstDocumentPtr& library);
61
64
67
73 NodeGraphPtr addNodeGraph(const string& name = EMPTY_STRING)
74 {
75 return addChild<NodeGraph>(name);
76 }
77
79 NodeGraphPtr getNodeGraph(const string& name) const
80 {
81 return getChildOfType<NodeGraph>(name);
82 }
83
85 vector<NodeGraphPtr> getNodeGraphs() const
86 {
87 return getChildrenOfType<NodeGraph>();
88 }
89
91 void removeNodeGraph(const string& name)
92 {
93 removeChildOfType<NodeGraph>(name);
94 }
95
99 vector<PortElementPtr> getMatchingPorts(const string& nodeName) const;
100
104
111 GeomInfoPtr addGeomInfo(const string& name = EMPTY_STRING, const string& geom = UNIVERSAL_GEOM_NAME)
112 {
113 GeomInfoPtr geomInfo = addChild<GeomInfo>(name);
114 geomInfo->setGeom(geom);
115 return geomInfo;
116 }
117
119 GeomInfoPtr getGeomInfo(const string& name) const
120 {
121 return getChildOfType<GeomInfo>(name);
122 }
123
125 vector<GeomInfoPtr> getGeomInfos() const
126 {
127 return getChildrenOfType<GeomInfo>();
128 }
129
131 void removeGeomInfo(const string& name)
132 {
133 removeChildOfType<GeomInfo>(name);
134 }
135
137 ValuePtr getGeomPropValue(const string& geomPropName, const string& geom = UNIVERSAL_GEOM_NAME) const;
138
142
147 GeomPropDefPtr addGeomPropDef(const string& name, const string& geomprop)
148 {
149 GeomPropDefPtr geomPropDef = addChild<GeomPropDef>(name);
150 geomPropDef->setGeomProp(geomprop);
151 return geomPropDef;
152 }
153
155 GeomPropDefPtr getGeomPropDef(const string& name) const
156 {
157 return getChildOfType<GeomPropDef>(name);
158 }
159
161 vector<GeomPropDefPtr> getGeomPropDefs() const
162 {
163 return getChildrenOfType<GeomPropDef>();
164 }
165
167 void removeGeomPropDef(const string& name)
168 {
169 removeChildOfType<GeomPropDef>(name);
170 }
171
175
177 vector<OutputPtr> getMaterialOutputs() const;
178
182
188 LookPtr addLook(const string& name = EMPTY_STRING)
189 {
190 return addChild<Look>(name);
191 }
192
194 LookPtr getLook(const string& name) const
195 {
196 return getChildOfType<Look>(name);
197 }
198
200 vector<LookPtr> getLooks() const
201 {
202 return getChildrenOfType<Look>();
203 }
204
206 void removeLook(const string& name)
207 {
208 removeChildOfType<Look>(name);
209 }
210
214
220 LookGroupPtr addLookGroup(const string& name = EMPTY_STRING)
221 {
222 return addChild<LookGroup>(name);
223 }
224
226 LookGroupPtr getLookGroup(const string& name) const
227 {
228 return getChildOfType<LookGroup>(name);
229 }
230
232 vector<LookGroupPtr> getLookGroups() const
233 {
234 return getChildrenOfType<LookGroup>();
235 }
236
238 void removeLookGroup(const string& name)
239 {
240 removeChildOfType<LookGroup>(name);
241 }
242
246
252 CollectionPtr addCollection(const string& name = EMPTY_STRING)
253 {
254 return addChild<Collection>(name);
255 }
256
258 CollectionPtr getCollection(const string& name) const
259 {
260 return getChildOfType<Collection>(name);
261 }
262
264 vector<CollectionPtr> getCollections() const
265 {
266 return getChildrenOfType<Collection>();
267 }
268
270 void removeCollection(const string& name)
271 {
272 removeChildOfType<Collection>(name);
273 }
274
278
284 TypeDefPtr addTypeDef(const string& name)
285 {
286 return addChild<TypeDef>(name);
287 }
288
290 TypeDefPtr getTypeDef(const string& name) const
291 {
292 return getChildOfType<TypeDef>(name);
293 }
294
296 vector<TypeDefPtr> getTypeDefs() const
297 {
298 return getChildrenOfType<TypeDef>();
299 }
300
302 void removeTypeDef(const string& name)
303 {
304 removeChildOfType<TypeDef>(name);
305 }
306
310
320 NodeDefPtr addNodeDef(const string& name = EMPTY_STRING,
321 const string& type = DEFAULT_TYPE_STRING,
322 const string& node = EMPTY_STRING)
323 {
324 NodeDefPtr child = addChild<NodeDef>(name);
325 if (!type.empty() && type != MULTI_OUTPUT_TYPE_STRING)
326 {
327 child->addOutput("out", type);
328 }
329 if (!node.empty())
330 {
331 child->setNodeString(node);
332 }
333 return child;
334 }
335
342 NodeDefPtr addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string& nodeDefName,
343 const string& category, const string& newGraphName);
344
346 NodeDefPtr getNodeDef(const string& name) const
347 {
348 return getChildOfType<NodeDef>(name);
349 }
350
352 vector<NodeDefPtr> getNodeDefs() const
353 {
354 return getChildrenOfType<NodeDef>();
355 }
356
358 void removeNodeDef(const string& name)
359 {
360 removeChildOfType<NodeDef>(name);
361 }
362
364 vector<NodeDefPtr> getMatchingNodeDefs(const string& nodeName) const;
365
369
375 AttributeDefPtr addAttributeDef(const string& name = EMPTY_STRING)
376 {
377 return addChild<AttributeDef>(name);
378 }
379
381 AttributeDefPtr getAttributeDef(const string& name) const
382 {
383 return getChildOfType<AttributeDef>(name);
384 }
385
387 vector<AttributeDefPtr> getAttributeDefs() const
388 {
389 return getChildrenOfType<AttributeDef>();
390 }
391
393 void removeAttributeDef(const string& name)
394 {
395 removeChildOfType<AttributeDef>(name);
396 }
397
401
407 TargetDefPtr addTargetDef(const string& name = EMPTY_STRING)
408 {
409 return addChild<TargetDef>(name);
410 }
411
413 TargetDefPtr getTargetDef(const string& name) const
414 {
415 return getChildOfType<TargetDef>(name);
416 }
417
419 vector<TargetDefPtr> getTargetDefs() const
420 {
421 return getChildrenOfType<TargetDef>();
422 }
423
425 void removeTargetDef(const string& name)
426 {
427 removeChildOfType<TargetDef>(name);
428 }
429
433
439 PropertySetPtr addPropertySet(const string& name = EMPTY_STRING)
440 {
441 return addChild<PropertySet>(name);
442 }
443
445 PropertySetPtr getPropertySet(const string& name) const
446 {
447 return getChildOfType<PropertySet>(name);
448 }
449
451 vector<PropertySetPtr> getPropertySets() const
452 {
453 return getChildrenOfType<PropertySet>();
454 }
455
457 void removePropertySet(const string& name)
458 {
459 removeChildOfType<PropertySet>(name);
460 }
461
465
471 VariantSetPtr addVariantSet(const string& name = EMPTY_STRING)
472 {
473 return addChild<VariantSet>(name);
474 }
475
477 VariantSetPtr getVariantSet(const string& name) const
478 {
479 return getChildOfType<VariantSet>(name);
480 }
481
483 vector<VariantSetPtr> getVariantSets() const
484 {
485 return getChildrenOfType<VariantSet>();
486 }
487
489 void removeVariantSet(const string& name)
490 {
491 removeChildOfType<VariantSet>(name);
492 }
493
497
503 ImplementationPtr addImplementation(const string& name = EMPTY_STRING)
504 {
505 return addChild<Implementation>(name);
506 }
507
509 ImplementationPtr getImplementation(const string& name) const
510 {
511 return getChildOfType<Implementation>(name);
512 }
513
515 vector<ImplementationPtr> getImplementations() const
516 {
517 return getChildrenOfType<Implementation>();
518 }
519
521 void removeImplementation(const string& name)
522 {
523 removeChildOfType<Implementation>(name);
524 }
525
529 vector<InterfaceElementPtr> getMatchingImplementations(const string& nodeDef) const;
530
534
535 UnitDefPtr addUnitDef(const string& name)
536 {
537 if (name.empty())
538 {
539 throw Exception("A unit definition name cannot be empty");
540 }
541 return addChild<UnitDef>(name);
542 }
543
545 UnitDefPtr getUnitDef(const string& name) const
546 {
547 return getChildOfType<UnitDef>(name);
548 }
549
551 vector<UnitDefPtr> getUnitDefs() const
552 {
553 return getChildrenOfType<UnitDef>();
554 }
555
557 void removeUnitDef(const string& name)
558 {
559 removeChildOfType<UnitDef>(name);
560 }
561
565
566 UnitTypeDefPtr addUnitTypeDef(const string& name)
567 {
568 if (name.empty())
569 {
570 throw Exception("A unit type definition name cannot be empty");
571 }
572 return addChild<UnitTypeDef>(name);
573 }
574
576 UnitTypeDefPtr getUnitTypeDef(const string& name) const
577 {
578 return getChildOfType<UnitTypeDef>(name);
579 }
580
582 vector<UnitTypeDefPtr> getUnitTypeDefs() const
583 {
584 return getChildrenOfType<UnitTypeDef>();
585 }
586
588 void removeUnitTypeDef(const string& name)
589 {
590 removeChildOfType<UnitTypeDef>(name);
591 }
592
596
598 std::pair<int, int> getVersionIntegers() const override;
599
603
607
609 void setColorManagementSystem(const string& cms)
610 {
611 setAttribute(CMS_ATTRIBUTE, cms);
612 }
613
616 {
617 return hasAttribute(CMS_ATTRIBUTE);
618 }
619
621 const string& getColorManagementSystem() const
622 {
623 return getAttribute(CMS_ATTRIBUTE);
624 }
625
629
631 void setColorManagementConfig(const string& cmsConfig)
632 {
633 setAttribute(CMS_CONFIG_ATTRIBUTE, cmsConfig);
634 }
635
638 {
639 return hasAttribute(CMS_CONFIG_ATTRIBUTE);
640 }
641
643 const string& getColorManagementConfig() const
644 {
645 return getAttribute(CMS_CONFIG_ATTRIBUTE);
646 }
647
651
657 bool validate(string* message = nullptr) const override;
658
662
665
667
668 //
669 // These are deprecated wrappers for older versions of the function interfaces in this module.
670 // Clients using these interfaces should update them to the latest API.
671 //
672 [[deprecated]] NodeDefPtr addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string& nodeDefName, const string& node, const string& version,
673 bool isDefaultVersion, const string& nodeGroup, const string& newGraphName);
674
675 public:
676 static const string CATEGORY;
677 static const string CMS_ATTRIBUTE;
678 static const string CMS_CONFIG_ATTRIBUTE;
679
680 private:
681 class Cache;
682 std::unique_ptr<Cache> _cache;
683};
684
687MX_CORE_API DocumentPtr createDocument();
688
689MATERIALX_NAMESPACE_END
690
691#endif
shared_ptr< TargetDef > TargetDefPtr
A shared pointer to a TargetDef.
Definition: Definition.h:47
shared_ptr< UnitDef > UnitDefPtr
A shared pointer to a UnitDef.
Definition: Definition.h:62
shared_ptr< Implementation > ImplementationPtr
A shared pointer to an Implementation.
Definition: Definition.h:37
shared_ptr< AttributeDef > AttributeDefPtr
A shared pointer to an AttributeDef.
Definition: Definition.h:72
shared_ptr< UnitTypeDef > UnitTypeDefPtr
A shared pointer to a UnitTypeDef.
Definition: Definition.h:67
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:24
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:22
shared_ptr< 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:38
shared_ptr< Collection > CollectionPtr
A shared pointer to a Collection.
Definition: Geom.h:53
shared_ptr< GeomPropDef > GeomPropDefPtr
A shared pointer to a GeomPropDef.
Definition: Geom.h:48
Look element subclasses.
shared_ptr< LookGroup > LookGroupPtr
A shared pointer to a LookGroup.
Definition: Look.h:32
shared_ptr< Look > LookPtr
A shared pointer to a Look.
Definition: Look.h:27
Import and export declarations for the Core library.
std::set< string > StringSet
A set of strings.
Definition: Library.h:59
Node element subclasses.
shared_ptr< NodeGraph > NodeGraphPtr
A shared pointer to a NodeGraph.
Definition: Node.h:34
shared_ptr< PropertySet > PropertySetPtr
A shared pointer to a PropertySet.
Definition: Property.h:34
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:29
shared_ptr< VariantSet > VariantSetPtr
A shared pointer to a VariantSet.
Definition: Variant.h:28
A MaterialX document, which represents the top-level element in the MaterialX ownership hierarchy.
Definition: Document.h:32
vector< PropertySetPtr > getPropertySets() const
Return a vector of all PropertySet elements in the document.
Definition: Document.h:451
TargetDefPtr addTargetDef(const string &name=EMPTY_STRING)
Add an TargetDef to the document.
Definition: Document.h:407
void removeLookGroup(const string &name)
Remove the LookGroup, if any, with the given name.
Definition: Document.h:238
void removeNodeDef(const string &name)
Remove the NodeDef, if any, with the given name.
Definition: Document.h:358
vector< LookPtr > getLooks() const
Return a vector of all Look elements in the document.
Definition: Document.h:200
void removeUnitTypeDef(const string &name)
Remove the UnitTypeDef, if any, with the given name.
Definition: Document.h:588
void removeVariantSet(const string &name)
Remove the VariantSet, if any, with the given name.
Definition: Document.h:489
vector< UnitTypeDefPtr > getUnitTypeDefs() const
Return a vector of all UnitTypeDef elements in the document.
Definition: Document.h:582
AttributeDefPtr addAttributeDef(const string &name=EMPTY_STRING)
Add an AttributeDef to the document.
Definition: Document.h:375
GeomInfoPtr getGeomInfo(const string &name) const
Return the GeomInfo, if any, with the given name.
Definition: Document.h:119
vector< InterfaceElementPtr > getMatchingImplementations(const string &nodeDef) const
Return a vector of all node implementations that match the given NodeDef string.
GeomPropDefPtr getGeomPropDef(const string &name) const
Return the GeomPropDef, if any, with the given name.
Definition: Document.h:155
TargetDefPtr getTargetDef(const string &name) const
Return the AttributeDef, if any, with the given name.
Definition: Document.h:413
ImplementationPtr getImplementation(const string &name) const
Return the Implementation, if any, with the given name.
Definition: Document.h:509
UnitTypeDefPtr getUnitTypeDef(const string &name) const
Return the UnitTypeDef, if any, with the given name.
Definition: Document.h:576
void setColorManagementSystem(const string &cms)
Set the color management system string.
Definition: Document.h:609
vector< PortElementPtr > getMatchingPorts(const string &nodeName) const
Return a vector of all port elements that match the given node name.
void removeImplementation(const string &name)
Remove the Implementation, if any, with the given name.
Definition: Document.h:521
void removeNodeGraph(const string &name)
Remove the NodeGraph, if any, with the given name.
Definition: Document.h:91
bool hasColorManagementSystem() const
Return true if a color management system string has been set.
Definition: Document.h:615
TypeDefPtr getTypeDef(const string &name) const
Return the TypeDef, if any, with the given name.
Definition: Document.h:290
vector< NodeDefPtr > getMatchingNodeDefs(const string &nodeName) const
Return a vector of all NodeDef elements that match the given node name.
CollectionPtr addCollection(const string &name=EMPTY_STRING)
Add a Collection to the document.
Definition: Document.h:252
vector< ImplementationPtr > getImplementations() const
Return a vector of all Implementation elements in the document.
Definition: Document.h:515
vector< TypeDefPtr > getTypeDefs() const
Return a vector of all TypeDef elements in the document.
Definition: Document.h:296
const string & getColorManagementConfig() const
Return the color management config string.
Definition: Document.h:643
bool validate(string *message=nullptr) const override
Validate that the given document is consistent with the MaterialX specification.
void removeGeomInfo(const string &name)
Remove the GeomInfo, if any, with the given name.
Definition: Document.h:131
vector< NodeGraphPtr > getNodeGraphs() const
Return a vector of all NodeGraph elements in the document.
Definition: Document.h:85
NodeDefPtr addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string &nodeDefName, const string &category, const string &newGraphName)
Create a NodeDef and Functional Graph based on a Compound NodeGraph.
vector< UnitDefPtr > getUnitDefs() const
Return a vector of all Member elements in the TypeDef.
Definition: Document.h:551
CollectionPtr getCollection(const string &name) const
Return the Collection, if any, with the given name.
Definition: Document.h:258
void removeTypeDef(const string &name)
Remove the TypeDef, if any, with the given name.
Definition: Document.h:302
static shared_ptr< T > createDocument()
Create a new document of the given subclass.
Definition: Document.h:38
bool hasColorManagementConfig() const
Return true if a color management config string has been set.
Definition: Document.h:637
vector< TargetDefPtr > getTargetDefs() const
Return a vector of all TargetDef elements in the document.
Definition: Document.h:419
GeomPropDefPtr addGeomPropDef(const string &name, const string &geomprop)
Add a GeomPropDef to the document.
Definition: Document.h:147
StringSet getReferencedSourceUris() const
Get a list of source URI's referenced by the document.
LookGroupPtr addLookGroup(const string &name=EMPTY_STRING)
Add a LookGroup to the document.
Definition: Document.h:220
virtual void initialize()
Initialize the document, removing any existing content.
void setColorManagementConfig(const string &cmsConfig)
Set the color management config string.
Definition: Document.h:631
void removeTargetDef(const string &name)
Remove the TargetDef, if any, with the given name.
Definition: Document.h:425
GeomInfoPtr addGeomInfo(const string &name=EMPTY_STRING, const string &geom=UNIVERSAL_GEOM_NAME)
Add a GeomInfo to the document.
Definition: Document.h:111
NodeGraphPtr getNodeGraph(const string &name) const
Return the NodeGraph, if any, with the given name.
Definition: Document.h:79
LookPtr addLook(const string &name=EMPTY_STRING)
Add a Look to the document.
Definition: Document.h:188
vector< AttributeDefPtr > getAttributeDefs() const
Return a vector of all AttributeDef elements in the document.
Definition: Document.h:387
UnitDefPtr getUnitDef(const string &name) const
Return the UnitDef, if any, with the given name.
Definition: Document.h:545
void removeLook(const string &name)
Remove the Look, if any, with the given name.
Definition: Document.h:206
vector< GeomInfoPtr > getGeomInfos() const
Return a vector of all GeomInfo elements in the document.
Definition: Document.h:125
NodeGraphPtr addNodeGraph(const string &name=EMPTY_STRING)
Add a NodeGraph to the document.
Definition: Document.h:73
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:320
vector< VariantSetPtr > getVariantSets() const
Return a vector of all VariantSet elements in the document.
Definition: Document.h:483
VariantSetPtr addVariantSet(const string &name=EMPTY_STRING)
Add a VariantSet to the document.
Definition: Document.h:471
NodeDefPtr getNodeDef(const string &name) const
Return the NodeDef, if any, with the given name.
Definition: Document.h:346
void upgradeVersion()
Upgrade the content of this document from earlier supported versions to the library version.
AttributeDefPtr getAttributeDef(const string &name) const
Return the AttributeDef, if any, with the given name.
Definition: Document.h:381
std::pair< int, int > getVersionIntegers() const override
Return the major and minor versions as an integer pair.
vector< OutputPtr > getMaterialOutputs() const
Return material-type outputs for all nodegraphs in the document.
ImplementationPtr addImplementation(const string &name=EMPTY_STRING)
Add an Implementation to the document.
Definition: Document.h:503
void removeAttributeDef(const string &name)
Remove the AttributeDef, if any, with the given name.
Definition: Document.h:393
vector< CollectionPtr > getCollections() const
Return a vector of all Collection elements in the document.
Definition: Document.h:264
virtual DocumentPtr copy() const
Create a deep copy of the document.
Definition: Document.h:49
vector< LookGroupPtr > getLookGroups() const
Return a vector of all LookGroup elements in the document.
Definition: Document.h:232
LookGroupPtr getLookGroup(const string &name) const
Return the LookGroup, if any, with the given name.
Definition: Document.h:226
PropertySetPtr getPropertySet(const string &name) const
Return the PropertySet, if any, with the given name.
Definition: Document.h:445
const string & getColorManagementSystem() const
Return the color management system string.
Definition: Document.h:621
LookPtr getLook(const string &name) const
Return the Look, if any, with the given name.
Definition: Document.h:194
void importLibrary(const ConstDocumentPtr &library)
Import the given document as a library within this document.
VariantSetPtr getVariantSet(const string &name) const
Return the VariantSet, if any, with the given name.
Definition: Document.h:477
void invalidateCache()
Invalidate cached data for optimized lookups within the given document.
vector< GeomPropDefPtr > getGeomPropDefs() const
Return a vector of all GeomPropDef elements in the document.
Definition: Document.h:161
void removeCollection(const string &name)
Remove the Collection, if any, with the given name.
Definition: Document.h:270
void removeGeomPropDef(const string &name)
Remove the GeomPropDef, if any, with the given name.
Definition: Document.h:167
void removeUnitDef(const string &name)
Remove the UnitDef, if any, with the given name.
Definition: Document.h:557
vector< NodeDefPtr > getNodeDefs() const
Return a vector of all NodeDef elements in the document.
Definition: Document.h:352
TypeDefPtr addTypeDef(const string &name)
Add a TypeDef to the document.
Definition: Document.h:284
PropertySetPtr addPropertySet(const string &name=EMPTY_STRING)
Add a PropertySet to the document.
Definition: Document.h:439
void removePropertySet(const string &name)
Remove the PropertySet, if any, with the given name.
Definition: Document.h:457
ValuePtr getGeomPropValue(const string &geomPropName, const string &geom=UNIVERSAL_GEOM_NAME) const
Return the value of a geometric property for the given geometry string.
const string & getAttribute(const string &attrib) const
Return the value string of the given attribute.
Definition: Element.h:504
void setAttribute(const string &attrib, const string &value)
Set the value string of the given attribute.
ElementPtr getSelf()
Return our self pointer.
Definition: Element.h:550
bool hasAttribute(const string &attrib) const
Return true if the given attribute is present.
Definition: Element.h:497
The base class for exceptions that are propagated from the MaterialX library to the client applicatio...
Definition: Exception.h:22
The base class for graph elements such as NodeGraph and Document.
Definition: Node.h:174