MaterialX 1.38.2
Traversal.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_TRAVERSAL_H
7#define MATERIALX_TRAVERSAL_H
8
11
13
14namespace MaterialX
15{
16
17class Element;
18
19using ElementPtr = shared_ptr<Element>;
20using ConstElementPtr = shared_ptr<const Element>;
21
30class MX_CORE_API Edge
31{
32 public:
33 Edge(ElementPtr elemDown, ElementPtr elemConnect, ElementPtr elemUp) :
34 _elemDown(elemDown),
35 _elemConnect(elemConnect),
36 _elemUp(elemUp)
37 {
38 }
39 ~Edge() { }
40
41 bool operator==(const Edge& rhs) const
42 {
43 return _elemDown == rhs._elemDown &&
44 _elemConnect == rhs._elemConnect &&
45 _elemUp == rhs._elemUp;
46 }
47 bool operator!=(const Edge& rhs) const
48 {
49 return !(*this == rhs);
50 }
51 bool operator<(const Edge& rhs) const
52 {
53 return std::tie(_elemDown, _elemConnect, _elemUp) < std::tie(rhs._elemDown, rhs._elemConnect, rhs._elemUp);
54 }
55
56 operator bool() const;
57
60 {
61 return _elemDown;
62 }
63
66 {
67 return _elemConnect;
68 }
69
72 {
73 return _elemUp;
74 }
75
77 string getName() const;
78
79 private:
80 ElementPtr _elemDown;
81 ElementPtr _elemConnect;
82 ElementPtr _elemUp;
83};
84
89class MX_CORE_API TreeIterator
90{
91 public:
92 explicit TreeIterator(ElementPtr elem):
93 _elem(elem),
94 _prune(false),
95 _holdCount(0)
96 {
97 }
98 ~TreeIterator() { }
99
100 private:
101 using StackFrame = std::pair<ElementPtr, size_t>;
102
103 public:
104 bool operator==(const TreeIterator& rhs) const
105 {
106 return _elem == rhs._elem &&
107 _stack == rhs._stack &&
108 _prune == rhs._prune;
109 }
110 bool operator!=(const TreeIterator& rhs) const
111 {
112 return !(*this == rhs);
113 }
114
118 {
119 return _elem;
120 }
121
123 TreeIterator& operator++();
124
127
130 {
131 return _elem;
132 }
133
137
140 size_t getElementDepth() const
141 {
142 return _stack.size();
143 }
144
148
152 void setPruneSubtree(bool prune)
153 {
154 _prune = prune;
155 }
156
159 bool getPruneSubtree() const
160 {
161 return _prune;
162 }
163
167
170 TreeIterator& begin(size_t holdCount = 0)
171 {
172 _holdCount = holdCount;
173 return *this;
174 }
175
177 static const TreeIterator& end();
178
180
181 private:
182 ElementPtr _elem;
183 vector<StackFrame> _stack;
184 bool _prune;
185 size_t _holdCount;
186};
187
192class MX_CORE_API GraphIterator
193{
194 public:
195 explicit GraphIterator(ElementPtr elem):
196 _upstreamElem(elem),
197 _prune(false),
198 _holdCount(0)
199 {
200 _pathElems.insert(elem);
201 }
202 ~GraphIterator() { }
203
204 private:
205 using ElementSet = std::set<ElementPtr>;
206 using StackFrame = std::pair<ElementPtr, size_t>;
207
208 public:
209 bool operator==(const GraphIterator& rhs) const
210 {
211 return _upstreamElem == rhs._upstreamElem &&
212 _stack == rhs._stack &&
213 _prune == rhs._prune;
214 }
215 bool operator!=(const GraphIterator& rhs) const
216 {
217 return !(*this == rhs);
218 }
219
222 {
223 return Edge(getDownstreamElement(),
224 getConnectingElement(),
225 getUpstreamElement());
226 }
227
230 GraphIterator& operator++();
231
234
237 {
238 return !_stack.empty() ? _stack.back().first : ElementPtr();
239 }
240
243 {
244 return _connectingElem;
245 }
246
249 {
250 return _upstreamElem;
251 }
252
255 size_t getUpstreamIndex() const
256 {
257 return !_stack.empty() ? _stack.back().second : 0;
258 }
259
263
266 size_t getElementDepth() const
267 {
268 return _stack.size();
269 }
270
273 size_t getNodeDepth() const;
274
278
282 void setPruneSubgraph(bool prune)
283 {
284 _prune = prune;
285 }
286
289 bool getPruneSubgraph() const
290 {
291 return _prune;
292 }
293
297
300 GraphIterator& begin(size_t holdCount = 0)
301 {
302 // Increment once to generate a valid edge.
303 if (_stack.empty())
304 {
305 operator++();
306 }
307
308 _holdCount = holdCount;
309 return *this;
310 }
311
313 static const GraphIterator& end();
314
316
317 private:
318 void extendPathUpstream(ElementPtr upstreamElem, ElementPtr connectingElem);
319 void returnPathDownstream(ElementPtr upstreamElem);
320
321 private:
322 ElementPtr _upstreamElem;
323 ElementPtr _connectingElem;
324 ElementSet _pathElems;
325 vector<StackFrame> _stack;
326 bool _prune;
327 size_t _holdCount;
328};
329
334class MX_CORE_API InheritanceIterator
335{
336 public:
337 explicit InheritanceIterator(ConstElementPtr elem) :
338 _elem(elem),
339 _holdCount(0)
340 {
341 _pathElems.insert(elem);
342 }
344
345 private:
346 using ConstElementSet = std::set<ConstElementPtr>;
347
348 public:
349 bool operator==(const InheritanceIterator& rhs) const
350 {
351 return _elem == rhs._elem;
352 }
353 bool operator!=(const InheritanceIterator& rhs) const
354 {
355 return !(*this == rhs);
356 }
357
361 {
362 return _elem;
363 }
364
367 InheritanceIterator& operator++();
368
371 InheritanceIterator& begin(size_t holdCount = 0)
372 {
373 _holdCount = holdCount;
374 return *this;
375 }
376
378 static const InheritanceIterator& end();
379
380 private:
381 ConstElementPtr _elem;
382 ConstElementSet _pathElems;
383 size_t _holdCount;
384};
385
388class MX_CORE_API ExceptionFoundCycle : public Exception
389{
390 public:
391 using Exception::Exception;
392};
393
394extern MX_CORE_API const Edge NULL_EDGE;
395
396extern MX_CORE_API const TreeIterator NULL_TREE_ITERATOR;
397extern MX_CORE_API const GraphIterator NULL_GRAPH_ITERATOR;
398extern MX_CORE_API const InheritanceIterator NULL_INHERITANCE_ITERATOR;
399
400} // namespace MaterialX
401
402#endif
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
shared_ptr< const Element > ConstElementPtr
A shared pointer to a const Element.
Definition: Element.h:33
Base exception classes.
An edge between two connected Elements, returned during graph traversal.
Definition: Traversal.h:31
ElementPtr getDownstreamElement() const
Return the downstream element of the edge.
Definition: Traversal.h:59
ElementPtr getConnectingElement() const
Return the connecting element of the edge, if any.
Definition: Traversal.h:65
ElementPtr getUpstreamElement() const
Return the upstream element of the edge.
Definition: Traversal.h:71
An exception that is thrown when a traversal call encounters a cycle.
Definition: Traversal.h:389
The base class for exceptions that are propagated from the MaterialX library to the client applicatio...
Definition: Exception.h:23
An iterator object representing the state of an upstream graph traversal.
Definition: Traversal.h:193
ElementPtr getDownstreamElement() const
Return the downstream element of the current edge.
Definition: Traversal.h:236
size_t getUpstreamIndex() const
Return the index of the current edge within the range of upstream edges available to the downstream e...
Definition: Traversal.h:255
bool getPruneSubgraph() const
Return the prune subgraph flag, which controls whether the current subgraph is pruned from traversal.
Definition: Traversal.h:289
Edge operator*() const
Dereference this iterator, returning the current edge in the traversal.
Definition: Traversal.h:221
ElementPtr getConnectingElement() const
Return the connecting element, if any, of the current edge.
Definition: Traversal.h:242
ElementPtr getUpstreamElement() const
Return the upstream element of the current edge.
Definition: Traversal.h:248
void setPruneSubgraph(bool prune)
Set the prune subgraph flag, which controls whether the current subgraph is pruned from traversal.
Definition: Traversal.h:282
size_t getElementDepth() const
Return the element depth of the current traversal, where a single edge between two elements represent...
Definition: Traversal.h:266
GraphIterator & begin(size_t holdCount=0)
Interpret this object as an iteration range, and return its begin iterator.
Definition: Traversal.h:300
An iterator object representing the current state of an inheritance traversal.
Definition: Traversal.h:335
InheritanceIterator & begin(size_t holdCount=0)
Interpret this object as an iteration range, and return its begin iterator.
Definition: Traversal.h:371
ConstElementPtr operator*() const
Dereference this iterator, returning the current element in the traversal.
Definition: Traversal.h:360
An iterator object representing the state of a tree traversal.
Definition: Traversal.h:90
TreeIterator & begin(size_t holdCount=0)
Interpret this object as an iteration range, and return its begin iterator.
Definition: Traversal.h:170
ElementPtr operator*() const
Dereference this iterator, returning the current element in the traversal.
Definition: Traversal.h:117
void setPruneSubtree(bool prune)
Set the prune subtree flag, which controls whether the current subtree is pruned from traversal.
Definition: Traversal.h:152
ElementPtr getElement() const
Return the current element in the traversal.
Definition: Traversal.h:129
size_t getElementDepth() const
Return the element depth of the current traversal, where the starting element represents a depth of z...
Definition: Traversal.h:140
bool getPruneSubtree() const
Return the prune subtree flag, which controls whether the current subtree is pruned from traversal.
Definition: Traversal.h:159