HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Element Class Reference

#include <Element.h>

+ Inheritance diagram for Element:

Public Member Functions

virtual ~Element ()
 
 Element (const Element &)=delete
 
Elementoperator= (const Element &)=delete
 
bool operator== (const Element &rhs) const
 
bool operator!= (const Element &rhs) const
 
Category
void setCategory (const string &category)
 Set the element's category string. More...
 
const stringgetCategory () const
 
Name
void setName (const string &name)
 
const stringgetName () const
 Return the element's name string. More...
 
string getNamePath (ConstElementPtr relativeTo=nullptr) const
 
ElementPtr getDescendant (const string &namePath) const
 
File Prefix
void setFilePrefix (const string &prefix)
 Set the element's file prefix string. More...
 
bool hasFilePrefix () const
 Return true if the given element has a file prefix string. More...
 
const stringgetFilePrefix () const
 Return the element's file prefix string. More...
 
const stringgetActiveFilePrefix () const
 
Geom Prefix
void setGeomPrefix (const string &prefix)
 Set the element's geom prefix string. More...
 
bool hasGeomPrefix () const
 Return true if the given element has a geom prefix string. More...
 
const stringgetGeomPrefix () const
 Return the element's geom prefix string. More...
 
const stringgetActiveGeomPrefix () const
 
Color Space
void setColorSpace (const string &colorSpace)
 Set the element's color space string. More...
 
bool hasColorSpace () const
 Return true if the given element has a color space string. More...
 
const stringgetColorSpace () const
 Return the element's color space string. More...
 
const stringgetActiveColorSpace () const
 
Inheritance
void setInheritString (const string &inherit)
 Set the inherit string of this element. More...
 
bool hasInheritString () const
 Return true if this element has an inherit string. More...
 
const stringgetInheritString () const
 Return the inherit string of this element. More...
 
void setInheritsFrom (ConstElementPtr super)
 Set the element that this one directly inherits from. More...
 
ElementPtr getInheritsFrom () const
 Return the element, if any, that this one directly inherits from. More...
 
bool hasInheritedBase (ConstElementPtr base) const
 
bool hasInheritanceCycle () const
 Return true if the inheritance chain for this element contains a cycle. More...
 
Namespace
void setNamespace (const string &space)
 Set the namespace string of this element. More...
 
bool hasNamespace () const
 Return true if this element has a namespace string. More...
 
const stringgetNamespace () const
 Return the namespace string of this element. More...
 
string getQualifiedName (const string &name) const
 
Documentation String
void setDocString (const string &doc)
 Set the documentation string of this element. More...
 
string getDocString () const
 Return the documentation string of this element. More...
 
Subclass
template<class T >
bool isA (const string &category=EMPTY_STRING) const
 
template<class T >
shared_ptr< TasA ()
 Dynamic cast to an instance of the given subclass. More...
 
template<class T >
shared_ptr< const TasA () const
 Dynamic cast to a const instance of the given subclass. More...
 
Child Elements
template<class T >
shared_ptr< TaddChild (const string &name=EMPTY_STRING)
 
ElementPtr addChildOfCategory (const string &category, string name=EMPTY_STRING)
 
ElementPtr changeChildCategory (ElementPtr child, const string &category)
 
ElementPtr getChild (const string &name) const
 Return the child element, if any, with the given name. More...
 
template<class T >
shared_ptr< TgetChildOfType (const string &name) const
 
const vector< ElementPtr > & getChildren () const
 
template<class T >
vector< shared_ptr< T > > getChildrenOfType (const string &category=EMPTY_STRING) const
 
void setChildIndex (const string &name, int index)
 
int getChildIndex (const string &name) const
 
void removeChild (const string &name)
 Remove the child element, if any, with the given name. More...
 
template<class T >
void removeChildOfType (const string &name)
 
Attributes
void setAttribute (const string &attrib, const string &value)
 Set the value string of the given attribute. More...
 
bool hasAttribute (const string &attrib) const
 Return true if the given attribute is present. More...
 
const stringgetAttribute (const string &attrib) const
 
const StringVecgetAttributeNames () const
 Return a vector of stored attribute names, in the order they were set. More...
 
template<class T >
void setTypedAttribute (const string &attrib, const T &data)
 
template<class T >
T getTypedAttribute (const string &attrib) const
 
void removeAttribute (const string &attrib)
 Remove the given attribute, if present. More...
 
Self And Ancestor Elements
ElementPtr getSelf ()
 Return our self pointer. More...
 
ConstElementPtr getSelf () const
 Return our self pointer. More...
 
ElementPtr getParent ()
 Return our parent element. More...
 
ConstElementPtr getParent () const
 Return our parent element. More...
 
ElementPtr getRoot ()
 Return the root element of our tree. More...
 
ConstElementPtr getRoot () const
 Return the root element of our tree. More...
 
DocumentPtr getDocument ()
 Return the root document of our tree. More...
 
ConstDocumentPtr getDocument () const
 Return the root document of our tree. More...
 
template<class T >
shared_ptr< const TgetAncestorOfType () const
 
Traversal
TreeIterator traverseTree () const
 
GraphIterator traverseGraph () const
 
virtual Edge getUpstreamEdge (size_t index=0) const
 
virtual size_t getUpstreamEdgeCount () const
 Return the number of queriable upstream edges for this element. More...
 
ElementPtr getUpstreamElement (size_t index=0) const
 
InheritanceIterator traverseInheritance () const
 
Source URI
void setSourceUri (const string &sourceUri)
 
bool hasSourceUri () const
 Return true if this element has a source URI. More...
 
const stringgetSourceUri () const
 Return the element's source URI. More...
 
const stringgetActiveSourceUri () const
 
Validation
virtual bool validate (string *message=nullptr) const
 
Utility
void copyContentFrom (const ConstElementPtr &source)
 
void clearContent ()
 Clear all attributes and descendants from this element. More...
 
string createValidChildName (string name) const
 
StringResolverPtr createStringResolver (const string &geom=EMPTY_STRING) const
 
string asString () const
 
template<class T >
shared_ptr< TresolveRootNameReference (const string &name) const
 

Static Public Attributes

static const string NAME_ATTRIBUTE
 
static const string FILE_PREFIX_ATTRIBUTE
 
static const string GEOM_PREFIX_ATTRIBUTE
 
static const string COLOR_SPACE_ATTRIBUTE
 
static const string INHERIT_ATTRIBUTE
 
static const string NAMESPACE_ATTRIBUTE
 
static const string DOC_ATTRIBUTE
 

Protected Types

using DocumentPtr = shared_ptr< Document >
 
using ConstDocumentPtr = shared_ptr< const Document >
 

Protected Member Functions

 Element (ElementPtr parent, const string &category, const string &name)
 
void validateRequire (bool expression, bool &res, string *message, string errorDesc) const
 
virtual void registerChildElement (ElementPtr child)
 
virtual void unregisterChildElement (ElementPtr child)
 
ElementPtr getSelfNonConst () const
 

Protected Attributes

string _category
 
string _name
 
string _sourceUri
 
ElementMap _childMap
 
vector< ElementPtr_childOrder
 
StringMap _attributeMap
 
StringVec _attributeOrder
 
weak_ptr< Element_parent
 
weak_ptr< Element_root
 

Friends

template<class T >
class ElementRegistry
 

Detailed Description

The base class for MaterialX elements.

An Element is a named object within a Document, which may possess any number of child elements and attributes.

Definition at line 73 of file Element.h.

Member Typedef Documentation

using Element::ConstDocumentPtr = shared_ptr<const Document>
protected

Definition at line 91 of file Element.h.

using Element::DocumentPtr = shared_ptr<Document>
protected

Definition at line 90 of file Element.h.

Constructor & Destructor Documentation

Element::Element ( ElementPtr  parent,
const string category,
const string name 
)
inlineprotected

Definition at line 76 of file Element.h.

virtual Element::~Element ( )
inlinevirtual

Definition at line 85 of file Element.h.

Element::Element ( const Element )
delete

Member Function Documentation

template<class T >
shared_ptr< T > Element::addChild ( const string name = EMPTY_STRING)

Add a child element of the given subclass and name.

Parameters
nameThe name of the new child element. If no name is specified, then a unique name will automatically be generated.
Exceptions
Exceptionif a child of this element already possesses the given name.
Returns
A shared pointer to the new child element.

Definition at line 1303 of file Element.h.

ElementPtr Element::addChildOfCategory ( const string category,
string  name = EMPTY_STRING 
)

Add a child element of the given category and name.

Parameters
categoryThe category string of the new child element. If the category string is recognized, then the correponding Element subclass is generated; otherwise, a GenericElement is generated.
nameThe name of the new child element. If no name is specified, then a unique name will automatically be generated.
Exceptions
Exceptionif a child of this element already possesses the given name.
Returns
A shared pointer to the new child element.
template<class T >
shared_ptr<T> Element::asA ( )

Dynamic cast to an instance of the given subclass.

template<class T >
shared_ptr<const T> Element::asA ( ) const

Dynamic cast to a const instance of the given subclass.

string Element::asString ( ) const

Return a single-line description of this element, including its category, name, and attributes.

ElementPtr Element::changeChildCategory ( ElementPtr  child,
const string category 
)

Change the category of the given child element.

Parameters
childThe child element that will be modified.
categoryThe new category string for the child element.
Returns
A shared pointer to a new child element, containing the contents of the original child but with a new category and subclass.
void Element::clearContent ( )

Clear all attributes and descendants from this element.

void Element::copyContentFrom ( const ConstElementPtr source)

Copy all attributes and descendants from the given element to this one.

Parameters
sourceThe element from which content is copied.
StringResolverPtr Element::createStringResolver ( const string geom = EMPTY_STRING) const

Construct a StringResolver at the scope of this element. The returned object may be used to apply substring modifiers to data values in the context of a specific element, geometry, and material.

Parameters
geomAn optional geometry name, which will be used to select the applicable set of geometry token substitutions. By default, no geometry token substitutions are applied. If the universal geometry name "/" is given, then all geometry token substitutions are applied,
Returns
A shared pointer to a StringResolver.
string Element::createValidChildName ( string  name) const
inline

Using the input name as a starting point, modify it to create a valid, unique name for a child element.

Definition at line 740 of file Element.h.

const string& Element::getActiveColorSpace ( ) const
inline

Return the color space string that is active at the scope of this element, taking all ancestor elements into account.

Definition at line 247 of file Element.h.

const string& Element::getActiveFilePrefix ( ) const
inline

Return the file prefix string that is active at the scope of this element, taking all ancestor elements into account.

Definition at line 175 of file Element.h.

const string& Element::getActiveGeomPrefix ( ) const
inline

Return the geom prefix string that is active at the scope of this element, taking all ancestor elements into account.

Definition at line 211 of file Element.h.

const string& Element::getActiveSourceUri ( ) const
inline

Return the source URI that is active at the scope of this element, taking all ancestor elements into account.

Definition at line 707 of file Element.h.

template<class T >
shared_ptr<const T> Element::getAncestorOfType ( ) const
inline

Return the first ancestor of the given subclass, or an empty shared pointer if no ancestor of this subclass is found.

Definition at line 581 of file Element.h.

const string& Element::getAttribute ( const string attrib) const
inline

Return the value string of the given attribute. If the given attribute is not present, then an empty string is returned.

Definition at line 498 of file Element.h.

const StringVec& Element::getAttributeNames ( ) const
inline

Return a vector of stored attribute names, in the order they were set.

Definition at line 505 of file Element.h.

const string& Element::getCategory ( ) const
inline

Return the element's category string. The category of a MaterialX element represents its role within the document, with common examples being "material", "nodegraph", and "image".

Definition at line 116 of file Element.h.

ElementPtr Element::getChild ( const string name) const
inline

Return the child element, if any, with the given name.

Definition at line 423 of file Element.h.

int Element::getChildIndex ( const string name) const

Return the index of the child, if any, with the given name. If no child with the given name is found, then -1 is returned.

template<class T >
shared_ptr<T> Element::getChildOfType ( const string name) const
inline

Return the child element, if any, with the given name and subclass. If a child with the given name exists, but belongs to a different subclass, then an empty shared pointer is returned.

Definition at line 432 of file Element.h.

const vector<ElementPtr>& Element::getChildren ( ) const
inline

Return a constant vector of all child elements. The returned vector maintains the order in which children were added.

Definition at line 440 of file Element.h.

template<class T >
vector<shared_ptr<T> > Element::getChildrenOfType ( const string category = EMPTY_STRING) const
inline

Return a vector of all child elements that are instances of the given subclass, optionally filtered by the given category string. The returned vector maintains the order in which children were added.

Definition at line 448 of file Element.h.

const string& Element::getColorSpace ( ) const
inline

Return the element's color space string.

Definition at line 240 of file Element.h.

ElementPtr Element::getDescendant ( const string namePath) const

Return the element specified by the given hierarchical name path, relative to the current element. If the name path is empty then the current element is returned. If no element is found at the given path, then an empty shared pointer is returned.

Parameters
namePathThe relative name path of the specified element.
string Element::getDocString ( ) const
inline

Return the documentation string of this element.

Definition at line 363 of file Element.h.

DocumentPtr Element::getDocument ( )

Return the root document of our tree.

ConstDocumentPtr Element::getDocument ( ) const

Return the root document of our tree.

const string& Element::getFilePrefix ( ) const
inline

Return the element's file prefix string.

Definition at line 168 of file Element.h.

const string& Element::getGeomPrefix ( ) const
inline

Return the element's geom prefix string.

Definition at line 204 of file Element.h.

ElementPtr Element::getInheritsFrom ( ) const
inline

Return the element, if any, that this one directly inherits from.

Definition at line 295 of file Element.h.

const string& Element::getInheritString ( ) const
inline

Return the inherit string of this element.

Definition at line 276 of file Element.h.

const string& Element::getName ( ) const
inline

Return the element's name string.

Definition at line 132 of file Element.h.

string Element::getNamePath ( ConstElementPtr  relativeTo = nullptr) const

Return the element's hierarchical name path, relative to the root document. The name of each ancestor will be prepended in turn, separated by forward slashes.

Parameters
relativeToIf a valid ancestor element is specified, then the returned path will be relative to this ancestor.
const string& Element::getNamespace ( ) const
inline

Return the namespace string of this element.

Definition at line 324 of file Element.h.

ElementPtr Element::getParent ( )
inline

Return our parent element.

Definition at line 556 of file Element.h.

ConstElementPtr Element::getParent ( ) const
inline

Return our parent element.

Definition at line 562 of file Element.h.

string Element::getQualifiedName ( const string name) const
inline

Return a qualified version of the given name, taking the namespace at the scope of this element into account.

Definition at line 331 of file Element.h.

ElementPtr Element::getRoot ( )

Return the root element of our tree.

ConstElementPtr Element::getRoot ( ) const

Return the root element of our tree.

ElementPtr Element::getSelf ( )
inline

Return our self pointer.

Definition at line 544 of file Element.h.

ConstElementPtr Element::getSelf ( ) const
inline

Return our self pointer.

Definition at line 550 of file Element.h.

ElementPtr Element::getSelfNonConst ( ) const
inlineprotected

Definition at line 795 of file Element.h.

const string& Element::getSourceUri ( ) const
inline

Return the element's source URI.

Definition at line 700 of file Element.h.

template<class T >
T Element::getTypedAttribute ( const string attrib) const
inline

Return the value of an implicitly typed attribute. If the given attribute is not present, or cannot be converted to the given data type, then the zero value for the data type is returned.

Definition at line 521 of file Element.h.

virtual Edge Element::getUpstreamEdge ( size_t  index = 0) const
virtual

Return the Edge with the given index that lies directly upstream from this element in the dataflow graph.

Parameters
indexAn optional index of the edge to be returned, where the valid index range may be determined with getUpstreamEdgeCount.
Returns
The upstream Edge, if valid, or an empty Edge object.

Reimplemented in Output, and Node.

virtual size_t Element::getUpstreamEdgeCount ( ) const
inlinevirtual

Return the number of queriable upstream edges for this element.

Reimplemented in Output, and Node.

Definition at line 651 of file Element.h.

ElementPtr Element::getUpstreamElement ( size_t  index = 0) const

Return the Element with the given index that lies directly upstream from this one in the dataflow graph.

Parameters
indexAn optional index of the element to be returned, where the valid index range may be determined with getUpstreamEdgeCount.
Returns
The upstream Element, if valid, or an empty ElementPtr.
bool Element::hasAttribute ( const string attrib) const
inline

Return true if the given attribute is present.

Definition at line 491 of file Element.h.

bool Element::hasColorSpace ( ) const
inline

Return true if the given element has a color space string.

Definition at line 234 of file Element.h.

bool Element::hasFilePrefix ( ) const
inline

Return true if the given element has a file prefix string.

Definition at line 162 of file Element.h.

bool Element::hasGeomPrefix ( ) const
inline

Return true if the given element has a geom prefix string.

Definition at line 198 of file Element.h.

bool Element::hasInheritanceCycle ( ) const

Return true if the inheritance chain for this element contains a cycle.

bool Element::hasInheritedBase ( ConstElementPtr  base) const

Return true if this element has the given element as an inherited base, taking the full inheritance chain into account.

bool Element::hasInheritString ( ) const
inline

Return true if this element has an inherit string.

Definition at line 270 of file Element.h.

bool Element::hasNamespace ( ) const
inline

Return true if this element has a namespace string.

Definition at line 318 of file Element.h.

bool Element::hasSourceUri ( ) const
inline

Return true if this element has a source URI.

Definition at line 694 of file Element.h.

template<class T >
bool Element::isA ( const string category = EMPTY_STRING) const
inline

Return true if this element belongs to the given subclass. If a category string is specified, then both subclass and category matches are required.

Definition at line 375 of file Element.h.

bool Element::operator!= ( const Element rhs) const

Return true if the given element tree, including all descendants, differs from this one.

Element& Element::operator= ( const Element )
delete
bool Element::operator== ( const Element rhs) const

Return true if the given element tree, including all descendants, is identical to this one.

virtual void Element::registerChildElement ( ElementPtr  child)
protectedvirtual

Reimplemented in InterfaceElement.

void Element::removeAttribute ( const string attrib)

Remove the given attribute, if present.

void Element::removeChild ( const string name)

Remove the child element, if any, with the given name.

template<class T >
void Element::removeChildOfType ( const string name)
inline

Remove the child element, if any, with the given name and subclass. If a child with the given name exists, but belongs to a different subclass, then this method has no effect.

Definition at line 477 of file Element.h.

template<class T >
shared_ptr<T> Element::resolveRootNameReference ( const string name) const
inline

Resolve a reference to a named element at the root scope of this document, taking the namespace at the scope of this element into account.

Definition at line 766 of file Element.h.

void Element::setAttribute ( const string attrib,
const string value 
)

Set the value string of the given attribute.

void Element::setCategory ( const string category)
inline

Set the element's category string.

Definition at line 108 of file Element.h.

void Element::setChildIndex ( const string name,
int  index 
)

Set the index of the child, if any, with the given name. If the given index is out of bounds, then an exception is thrown.

void Element::setColorSpace ( const string colorSpace)
inline

Set the element's color space string.

Definition at line 228 of file Element.h.

void Element::setDocString ( const string doc)
inline

Set the documentation string of this element.

Definition at line 357 of file Element.h.

void Element::setFilePrefix ( const string prefix)
inline

Set the element's file prefix string.

Definition at line 156 of file Element.h.

void Element::setGeomPrefix ( const string prefix)
inline

Set the element's geom prefix string.

Definition at line 192 of file Element.h.

void Element::setInheritsFrom ( ConstElementPtr  super)
inline

Set the element that this one directly inherits from.

Definition at line 282 of file Element.h.

void Element::setInheritString ( const string inherit)
inline

Set the inherit string of this element.

Definition at line 264 of file Element.h.

void Element::setName ( const string name)

Set the element's name string. The name of a MaterialX element must be unique among all elements at the same scope.

Exceptions
Exceptionif an element at the same scope already possesses the given name.
void Element::setNamespace ( const string space)
inline

Set the namespace string of this element.

Definition at line 312 of file Element.h.

void Element::setSourceUri ( const string sourceUri)
inline

Set the element's source URI.

Parameters
sourceUriA URI string representing the resource from which this element originates. This string may be used by serialization and deserialization routines to maintain hierarchies of include references.

Definition at line 688 of file Element.h.

template<class T >
void Element::setTypedAttribute ( const string attrib,
const T data 
)
inline

Set the value of an implicitly typed attribute. Since an attribute stores no explicit type, the same type argument must be used in corresponding calls to getTypedAttribute.

Definition at line 513 of file Element.h.

GraphIterator Element::traverseGraph ( ) const

Traverse the dataflow graph from the given element to each of its upstream sources in depth-first order, using pre-order visitation.

Exceptions
ExceptionFoundCycleif a cycle is encountered.
Returns
A GraphIterator object.

Example usage with an implicit iterator:

for (Edge edge : inputElem->traverseGraph())
{
ElementPtr upElem = edge.getUpstreamElement();
ElementPtr downElem = edge.getDownstreamElement();
cout << upElem->asString() << " lies upstream from " << downElem->asString() << endl;
}

Example usage with an explicit iterator:

for (mx::GraphIterator it = inputElem->traverseGraph().begin(); it != mx::GraphIterator::end(); ++it)
{
mx::ElementPtr elem = it.getUpstreamElement();
cout << elem->asString() << " at depth " << it.getElementDepth() << endl;
}
See Also
getUpstreamEdge
getUpstreamElement
InheritanceIterator Element::traverseInheritance ( ) const

Traverse the inheritance chain from the given element to each element from which it inherits.

Exceptions
ExceptionFoundCycleif a cycle is encountered.
Returns
An InheritanceIterator object.

Example usage:

ConstElementPtr derivedElem;
for (ConstElementPtr elem : inputElem->traverseInheritance())
{
if (derivedElem)
cout << derivedElem->asString() << " inherits from " << elem->asString() << endl;
derivedElem = elem;
}
TreeIterator Element::traverseTree ( ) const

Traverse the tree from the given element to each of its descendants in depth-first order, using pre-order visitation.

Returns
A TreeIterator object.

Example usage with an implicit iterator:

for (ElementPtr elem : inputElem->traverseTree())
{
cout << elem->asString() << endl;
}

Example usage with an explicit iterator:

for (mx::TreeIterator it = inputElem->traverseTree().begin(); it != mx::TreeIterator::end(); ++it)
{
mx::ElementPtr elem = it.getElement();
cout << elem->asString() << " at depth " << it.getElementDepth() << endl;
}
virtual void Element::unregisterChildElement ( ElementPtr  child)
protectedvirtual

Reimplemented in InterfaceElement.

virtual bool Element::validate ( string message = nullptr) const
virtual

Validate that the given element tree, including all descendants, is consistent with the MaterialX specification.

Reimplemented in ValueElement, Document, Collection, Backdrop, NodeGraph, Output, Implementation, Input, GeomElement, PortElement, Node, and NodeDef.

void Element::validateRequire ( bool  expression,
bool &  res,
string message,
string  errorDesc 
) const
protected

Friends And Related Function Documentation

template<class T >
friend class ElementRegistry
friend

Definition at line 93 of file Element.h.

Member Data Documentation

StringMap Element::_attributeMap
protected

Definition at line 808 of file Element.h.

StringVec Element::_attributeOrder
protected

Definition at line 809 of file Element.h.

string Element::_category
protected

Definition at line 801 of file Element.h.

ElementMap Element::_childMap
protected

Definition at line 805 of file Element.h.

vector<ElementPtr> Element::_childOrder
protected

Definition at line 806 of file Element.h.

string Element::_name
protected

Definition at line 802 of file Element.h.

weak_ptr<Element> Element::_parent
protected

Definition at line 811 of file Element.h.

weak_ptr<Element> Element::_root
protected

Definition at line 812 of file Element.h.

string Element::_sourceUri
protected

Definition at line 803 of file Element.h.

const string Element::COLOR_SPACE_ATTRIBUTE
static

Definition at line 784 of file Element.h.

const string Element::DOC_ATTRIBUTE
static

Definition at line 787 of file Element.h.

const string Element::FILE_PREFIX_ATTRIBUTE
static

Definition at line 782 of file Element.h.

const string Element::GEOM_PREFIX_ATTRIBUTE
static

Definition at line 783 of file Element.h.

const string Element::INHERIT_ATTRIBUTE
static

Definition at line 785 of file Element.h.

const string Element::NAME_ATTRIBUTE
static

Definition at line 781 of file Element.h.

const string Element::NAMESPACE_ATTRIBUTE
static

Definition at line 786 of file Element.h.


The documentation for this class was generated from the following file: