MaterialX  1.36.1
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 
12 #include <MaterialXCore/Library.h>
13 
14 #include <MaterialXCore/Look.h>
15 #include <MaterialXCore/Material.h>
16 #include <MaterialXCore/Node.h>
17 #include <MaterialXCore/Variant.h>
18 
19 namespace MaterialX
20 {
21 
22 class Document;
23 
25 using DocumentPtr = shared_ptr<Document>;
27 using ConstDocumentPtr = shared_ptr<const Document>;
28 
34 class Document : public GraphElement
35 {
36  public:
37  Document(ElementPtr parent, const string& name);
38  virtual ~Document();
39 
41  template <class T> static shared_ptr<T> createDocument()
42  {
43  shared_ptr<T> doc = std::make_shared<T>(ElementPtr(), EMPTY_STRING);
44  doc->initialize();
45  return doc;
46  }
47 
49  virtual void initialize();
50 
52  virtual DocumentPtr copy()
53  {
54  DocumentPtr doc = createDocument<Document>();
55  doc->copyContentFrom(getSelf());
56  return doc;
57  }
58 
66  void importLibrary(ConstDocumentPtr library, const CopyOptions* copyOptions = nullptr);
67 
71 
77  NodeGraphPtr addNodeGraph(const string& name = EMPTY_STRING)
78  {
79  return addChild<NodeGraph>(name);
80  }
81 
83  NodeGraphPtr getNodeGraph(const string& name) const
84  {
85  return getChildOfType<NodeGraph>(name);
86  }
87 
89  vector<NodeGraphPtr> getNodeGraphs() const
90  {
91  return getChildrenOfType<NodeGraph>();
92  }
93 
95  void removeNodeGraph(const string& name)
96  {
97  removeChildOfType<NodeGraph>(name);
98  }
99 
103  vector<PortElementPtr> getMatchingPorts(const string& nodeName) const;
104 
108 
114  MaterialPtr addMaterial(const string& name = EMPTY_STRING)
115  {
116  return addChild<Material>(name);
117  }
118 
120  MaterialPtr getMaterial(const string& name) const
121  {
122  return getChildOfType<Material>(name);
123  }
124 
126  vector<MaterialPtr> getMaterials() const
127  {
128  return getChildrenOfType<Material>();
129  }
130 
132  void removeMaterial(const string& name)
133  {
134  removeChildOfType<Material>(name);
135  }
136 
140 
147  GeomInfoPtr addGeomInfo(const string& name = EMPTY_STRING, const string& geom = UNIVERSAL_GEOM_NAME)
148  {
149  GeomInfoPtr geomInfo = addChild<GeomInfo>(name);
150  geomInfo->setGeom(geom);
151  return geomInfo;
152  }
153 
155  GeomInfoPtr getGeomInfo(const string& name) const
156  {
157  return getChildOfType<GeomInfo>(name);
158  }
159 
161  vector<GeomInfoPtr> getGeomInfos() const
162  {
163  return getChildrenOfType<GeomInfo>();
164  }
165 
167  void removeGeomInfo(const string& name)
168  {
169  removeChildOfType<GeomInfo>(name);
170  }
171 
175 
181  LookPtr addLook(const string& name = EMPTY_STRING)
182  {
183  return addChild<Look>(name);
184  }
185 
187  LookPtr getLook(const string& name) const
188  {
189  return getChildOfType<Look>(name);
190  }
191 
193  vector<LookPtr> getLooks() const
194  {
195  return getChildrenOfType<Look>();
196  }
197 
199  void removeLook(const string& name)
200  {
201  removeChildOfType<Look>(name);
202  }
203 
207 
213  CollectionPtr addCollection(const string& name = EMPTY_STRING)
214  {
215  return addChild<Collection>(name);
216  }
217 
219  CollectionPtr getCollection(const string& name) const
220  {
221  return getChildOfType<Collection>(name);
222  }
223 
225  vector<CollectionPtr> getCollections() const
226  {
227  return getChildrenOfType<Collection>();
228  }
229 
231  void removeCollection(const string& name)
232  {
233  removeChildOfType<Collection>(name);
234  }
235 
239 
245  TypeDefPtr addTypeDef(const string& name)
246  {
247  return addChild<TypeDef>(name);
248  }
249 
251  TypeDefPtr getTypeDef(const string& name) const
252  {
253  return getChildOfType<TypeDef>(name);
254  }
255 
257  vector<TypeDefPtr> getTypeDefs() const
258  {
259  return getChildrenOfType<TypeDef>();
260  }
261 
263  void removeTypeDef(const string& name)
264  {
265  removeChildOfType<TypeDef>(name);
266  }
267 
271 
279  NodeDefPtr addNodeDef(const string& name = EMPTY_STRING,
280  const string& type = DEFAULT_TYPE_STRING,
281  const string& node = EMPTY_STRING)
282  {
283  NodeDefPtr child = addChild<NodeDef>(name);
284  child->setType(type);
285  if (!node.empty())
286  {
287  child->setNodeString(node);
288  }
289  return child;
290  }
291 
293  NodeDefPtr getNodeDef(const string& name) const
294  {
295  return getChildOfType<NodeDef>(name);
296  }
297 
299  vector<NodeDefPtr> getNodeDefs() const
300  {
301  return getChildrenOfType<NodeDef>();
302  }
303 
305  void removeNodeDef(const string& name)
306  {
307  removeChildOfType<NodeDef>(name);
308  }
309 
311  vector<NodeDefPtr> getMatchingNodeDefs(const string& nodeName) const;
312 
316 
322  PropertySetPtr addPropertySet(const string& name = EMPTY_STRING)
323  {
324  return addChild<PropertySet>(name);
325  }
326 
328  PropertySetPtr getPropertySet(const string& name) const
329  {
330  return getChildOfType<PropertySet>(name);
331  }
332 
334  vector<PropertySetPtr> getPropertySets() const
335  {
336  return getChildrenOfType<PropertySet>();
337  }
338 
340  void removePropertySet(const string& name)
341  {
342  removeChildOfType<PropertySet>(name);
343  }
344 
348 
354  VariantSetPtr addVariantSet(const string& name = EMPTY_STRING)
355  {
356  return addChild<VariantSet>(name);
357  }
358 
360  VariantSetPtr getVariantSet(const string& name) const
361  {
362  return getChildOfType<VariantSet>(name);
363  }
364 
366  vector<VariantSetPtr> getVariantSets() const
367  {
368  return getChildrenOfType<VariantSet>();
369  }
370 
372  void removeVariantSet(const string& name)
373  {
374  removeChildOfType<VariantSet>(name);
375  }
376 
380 
386  ImplementationPtr addImplementation(const string& name = EMPTY_STRING)
387  {
388  return addChild<Implementation>(name);
389  }
390 
392  ImplementationPtr getImplementation(const string& name) const
393  {
394  return getChildOfType<Implementation>(name);
395  }
396 
398  vector<ImplementationPtr> getImplementations() const
399  {
400  return getChildrenOfType<Implementation>();
401  }
402 
404  void removeImplementation(const string& name)
405  {
406  removeChildOfType<Implementation>(name);
407  }
408 
412  vector<InterfaceElementPtr> getMatchingImplementations(const string& nodeDef) const;
413 
417 
419  std::pair<int, int> getVersionIntegers() const override;
420 
423  void upgradeVersion();
424 
428 
430  void setColorManagementSystem(const string& cms)
431  {
432  setAttribute(CMS_ATTRIBUTE, cms);
433  }
434 
437  {
438  return hasAttribute(CMS_ATTRIBUTE);
439  }
440 
442  const string& getColorManagementSystem() const
443  {
444  return getAttribute(CMS_ATTRIBUTE);
445  }
446 
450 
452  void setColorManagementConfig(const string& cmsConfig)
453  {
454  setAttribute(CMS_CONFIG_ATTRIBUTE, cmsConfig);
455  }
456 
459  {
460  return hasAttribute(CMS_CONFIG_ATTRIBUTE);
461  }
462 
464  const string& getColorManagementConfig() const
465  {
466  return getAttribute(CMS_CONFIG_ATTRIBUTE);
467  }
468 
472 
478  bool validate(string* message = nullptr) const override;
479 
483 
485  virtual void enableCallbacks() { }
486 
488  virtual void disableCallbacks() { }
489 
491  virtual void onAddElement(ElementPtr parent, ElementPtr elem);
492 
494  virtual void onRemoveElement(ElementPtr parent, ElementPtr elem);
495 
497  virtual void onSetAttribute(ElementPtr elem, const string& attrib, const string& value);
498 
500  virtual void onRemoveAttribute(ElementPtr elem, const string& attrib);
501 
503  virtual void onInitialize() { }
504 
506  virtual void onRead() { }
507 
509  virtual void onWrite() { }
510 
512  virtual void onBeginUpdate() { }
513 
515  virtual void onEndUpdate() { }
516 
518 
519  public:
520  static const string CATEGORY;
521  static const string CMS_ATTRIBUTE;
522  static const string CMS_CONFIG_ATTRIBUTE;
523 
524  private:
525  class Cache;
526  std::unique_ptr<Cache> _cache;
527 };
528 
535 {
536  public:
537  explicit ScopedUpdate(DocumentPtr doc) :
538  _doc(doc)
539  {
540  _doc->onBeginUpdate();
541  }
542  ~ScopedUpdate()
543  {
544  _doc->onEndUpdate();
545  }
546 
547  private:
548  DocumentPtr _doc;
549 };
550 
557 {
558  public:
559  explicit ScopedDisableCallbacks(DocumentPtr doc) :
560  _doc(doc)
561  {
562  _doc->disableCallbacks();
563  }
565  {
566  _doc->enableCallbacks();
567  }
568 
569  private:
570  DocumentPtr _doc;
571 };
572 
575 DocumentPtr createDocument();
576 
577 } // namespace MaterialX
578 
579 #endif
shared_ptr< Look > LookPtr
A shared pointer to a Look.
Definition: Look.h:27
VariantSetPtr addVariantSet(const string &name=EMPTY_STRING)
Add a VariantSet to the document.
Definition: Document.h:354
MaterialPtr getMaterial(const string &name) const
Return the Material, if any, with the given name.
Definition: Document.h:120
virtual void onEndUpdate()
Called after a set of document updates is performed.
Definition: Document.h:515
ImplementationPtr addImplementation(const string &name=EMPTY_STRING)
Add an Implementation to the document.
Definition: Document.h:386
void removeCollection(const string &name)
Remove the Collection, if any, with the given name.
Definition: Document.h:231
virtual void enableCallbacks()
Enable all observer callbacks.
Definition: Document.h:485
Definition: Definition.cpp:10
shared_ptr< Collection > CollectionPtr
A shared pointer to a Collection.
Definition: Geom.h:47
GeomInfoPtr getGeomInfo(const string &name) const
Return the GeomInfo, if any, with the given name.
Definition: Document.h:155
CollectionPtr addCollection(const string &name=EMPTY_STRING)
Add a Collection to the document.
Definition: Document.h:213
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:25
virtual void onRead()
Called when data is read into the current document.
Definition: Document.h:506
shared_ptr< VariantSet > VariantSetPtr
A shared pointer to a VariantSet.
Definition: Variant.h:29
bool hasColorManagementConfig() const
Return true if a color management config string has been set.
Definition: Document.h:458
CollectionPtr getCollection(const string &name) const
Return the Collection, if any, with the given name.
Definition: Document.h:219
void removeNodeGraph(const string &name)
Remove the NodeGraph, if any, with the given name.
Definition: Document.h:95
vector< CollectionPtr > getCollections() const
Return a vector of all Collection elements in the document.
Definition: Document.h:225
shared_ptr< Implementation > ImplementationPtr
A shared pointer to an Implementation.
Definition: Definition.h:40
shared_ptr< NodeGraph > NodeGraphPtr
A shared pointer to a NodeGraph.
Definition: Node.h:34
shared_ptr< GeomInfo > GeomInfoPtr
A shared pointer to a GeomInfo.
Definition: Geom.h:42
vector< NodeDefPtr > getNodeDefs() const
Return a vector of all NodeDef elements in the document.
Definition: Document.h:299
virtual void onWrite()
Called when data is written from the current document.
Definition: Document.h:509
void removeNodeDef(const string &name)
Remove the NodeDef, if any, with the given name.
Definition: Document.h:305
vector< PropertySetPtr > getPropertySets() const
Return a vector of all PropertySet elements in the document.
Definition: Document.h:334
TypeDefPtr getTypeDef(const string &name) const
Return the TypeDef, if any, with the given name.
Definition: Document.h:251
virtual void initialize()
Initialize the document, removing any existing content.
Definition: Document.cpp:136
virtual void disableCallbacks()
Disable all observer callbacks.
Definition: Document.h:488
MaterialPtr addMaterial(const string &name=EMPTY_STRING)
Add a Material to the document.
Definition: Document.h:114
ElementPtr getSelf()
Return our self pointer.
Definition: Element.h:568
virtual void onInitialize()
Called when a document is initialized.
Definition: Document.h:503
vector< NodeGraphPtr > getNodeGraphs() const
Return a vector of all NodeGraph elements in the document.
Definition: Document.h:89
vector< LookPtr > getLooks() const
Return a vector of all Look elements in the document.
Definition: Document.h:193
vector< NodeDefPtr > getMatchingNodeDefs(const string &nodeName) const
Return a vector of all NodeDef elements that match the given node name.
Definition: Document.cpp:213
bool validate(string *message=nullptr) const override
Validate that the given document is consistent with the MaterialX specification.
Definition: Document.cpp:247
PropertySetPtr getPropertySet(const string &name) const
Return the PropertySet, if any, with the given name.
Definition: Document.h:328
void setColorManagementConfig(const string &cmsConfig)
Set the color management config string.
Definition: Document.h:452
const string & getColorManagementConfig() const
Return the color management config string.
Definition: Document.h:464
const string & getAttribute(const string &attrib) const
Return the value string of the given attribute.
Definition: Element.h:522
vector< GeomInfoPtr > getGeomInfos() const
Return a vector of all GeomInfo elements in the document.
Definition: Document.h:161
bool hasColorManagementSystem() const
Return true if a color management system string has been set.
Definition: Document.h:436
vector< ImplementationPtr > getImplementations() const
Return a vector of all Implementation elements in the document.
Definition: Document.h:398
Node element subclasses.
void removePropertySet(const string &name)
Remove the PropertySet, if any, with the given name.
Definition: Document.h:340
A MaterialX document, which represents the top-level element in the MaterialX ownership hierarchy...
Definition: Document.h:34
shared_ptr< Material > MaterialPtr
A shared pointer to a Material.
Definition: Material.h:32
shared_ptr< PropertySet > PropertySetPtr
A shared pointer to a PropertySet.
Definition: Property.h:35
A set of options for controlling the behavior of element copy operations.
Definition: Element.h:1242
void removeLook(const string &name)
Remove the Look, if any, with the given name.
Definition: Document.h:199
virtual void onSetAttribute(ElementPtr elem, const string &attrib, const string &value)
Called when an attribute of an element is set to a new value.
Definition: Document.cpp:549
bool hasAttribute(const string &attrib) const
Return true if the given attribute is present.
Definition: Element.h:515
LookPtr addLook(const string &name=EMPTY_STRING)
Add a Look to the document.
Definition: Document.h:181
virtual void onRemoveAttribute(ElementPtr elem, const string &attrib)
Called when an attribute of an element is removed.
Definition: Document.cpp:554
vector< InterfaceElementPtr > getMatchingImplementations(const string &nodeDef) const
Return a vector of all node implementations that match the given NodeDef string.
Definition: Document.cpp:230
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
NodeDefPtr getNodeDef(const string &name) const
Return the NodeDef, if any, with the given name.
Definition: Document.h:293
vector< TypeDefPtr > getTypeDefs() const
Return a vector of all TypeDef elements in the document.
Definition: Document.h:257
std::pair< int, int > getVersionIntegers() const override
Return the major and minor versions as an integer pair.
Definition: Document.cpp:187
void removeMaterial(const string &name)
Remove the Material, if any, with the given name.
Definition: Document.h:132
Variant element subclasses.
virtual void onRemoveElement(ElementPtr parent, ElementPtr elem)
Called when an element is removed from the element tree.
Definition: Document.cpp:544
vector< PortElementPtr > getMatchingPorts(const string &nodeName) const
Return a vector of all port elements that match the given node name.
Definition: Document.cpp:196
LookPtr getLook(const string &name) const
Return the Look, if any, with the given name.
Definition: Document.h:187
The base class for graph elements such as NodeGraph and Document.
Definition: Node.h:149
vector< VariantSetPtr > getVariantSets() const
Return a vector of all VariantSet elements in the document.
Definition: Document.h:366
Look element subclasses.
Library-wide includes and types.
const string & getColorManagementSystem() const
Return the color management system string.
Definition: Document.h:442
void removeTypeDef(const string &name)
Remove the TypeDef, if any, with the given name.
Definition: Document.h:263
TypeDefPtr addTypeDef(const string &name)
Add a TypeDef to the document.
Definition: Document.h:245
void removeImplementation(const string &name)
Remove the Implementation, if any, with the given name.
Definition: Document.h:404
vector< MaterialPtr > getMaterials() const
Return a vector of all Material elements in the document.
Definition: Document.h:126
ImplementationPtr getImplementation(const string &name) const
Return the Implementation, if any, with the given name.
Definition: Document.h:392
void upgradeVersion()
Upgrade the content of this document from earlier supported versions to the library version...
Definition: Document.cpp:254
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:279
NodeGraphPtr addNodeGraph(const string &name=EMPTY_STRING)
Add a NodeGraph to the document.
Definition: Document.h:77
GeomInfoPtr addGeomInfo(const string &name=EMPTY_STRING, const string &geom=UNIVERSAL_GEOM_NAME)
Add a GeomInfo to the document.
Definition: Document.h:147
void importLibrary(ConstDocumentPtr library, const CopyOptions *copyOptions=nullptr)
Import the given document as a library within this document.
Definition: Document.cpp:151
void setAttribute(const string &attrib, const string &value)
Set the value string of the given attribute.
Definition: Element.cpp:214
NodeGraphPtr getNodeGraph(const string &name) const
Return the NodeGraph, if any, with the given name.
Definition: Document.h:83
An RAII class for disabling Document callbacks.
Definition: Document.h:556
void removeGeomInfo(const string &name)
Remove the GeomInfo, if any, with the given name.
Definition: Document.h:167
static shared_ptr< T > createDocument()
Create a new document of the given subclass.
Definition: Document.h:41
void setColorManagementSystem(const string &cms)
Set the color management system string.
Definition: Document.h:430
void removeVariantSet(const string &name)
Remove the VariantSet, if any, with the given name.
Definition: Document.h:372
virtual DocumentPtr copy()
Create a deep copy of the document.
Definition: Document.h:52
Material element subclasses.
virtual void onAddElement(ElementPtr parent, ElementPtr elem)
Called when an element is added to the element tree.
Definition: Document.cpp:539
An RAII class for Document updates.
Definition: Document.h:534
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:27
virtual void onBeginUpdate()
Called before a set of document updates is performed.
Definition: Document.h:512
PropertySetPtr addPropertySet(const string &name=EMPTY_STRING)
Add a PropertySet to the document.
Definition: Document.h:322
VariantSetPtr getVariantSet(const string &name) const
Return the VariantSet, if any, with the given name.
Definition: Document.h:360