#include <Element.h>

Inheritance diagram for Element:

Public Member Functions
virtual	~Element ()

	Element (const Element &)=delete

Element &	operator= (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 string &	getCategory () const

Name
void	setName (const string &name)

const string &	getName () 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 string &	getFilePrefix () const
	Return the element's file prefix string. More...

const string &	getActiveFilePrefix () 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 string &	getGeomPrefix () const
	Return the element's geom prefix string. More...

const string &	getActiveGeomPrefix () 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 string &	getColorSpace () const
	Return the element's color space string. More...

const string &	getActiveColorSpace () 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 string &	getInheritString () 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 string &	getNamespace () 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< T >	asA ()
	Dynamic cast to an instance of the given subclass. More...

template<class T >
shared_ptr< const T >	asA () const
	Dynamic cast to a const instance of the given subclass. More...

Child Elements
template<class T >
shared_ptr< T >	addChild (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< T >	getChildOfType (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 string &	getAttribute (const string &attrib) const

const StringVec &	getAttributeNames () 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 T >	getAncestorOfType () 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 string &	getSourceUri () const
	Return the element's source URI. More...

const string &	getActiveSourceUri () const

Validation
virtual bool	validate (string *message=nullptr) const

Utility
void	copyContentFrom (const ConstElementPtr &source)

virtual 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

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)

template<class T >
shared_ptr< T >	resolveNameReference (const string &name, ConstElementPtr parent=nullptr) const

void	validateRequire (bool expression, bool &res, string *message, const 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 79 of file Element.h.

Member Typedef Documentation

using Element::ConstDocumentPtr = shared_ptr<const Document>

protected

Definition at line 97 of file Element.h.

using Element::DocumentPtr = shared_ptr<Document>

protected

Definition at line 96 of file Element.h.

Constructor & Destructor Documentation

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

inlineprotected

Definition at line 82 of file Element.h.

virtual Element::~Element ( )

inlinevirtual

Definition at line 91 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

name	The name of the new child element. If no name is specified, then a unique name will automatically be generated.

Exceptions

Exception if a child of this element already possesses the given name.

Returns: A shared pointer to the new child element.

Definition at line 1331 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

category	The 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.
name	The name of the new child element. If no name is specified, then a unique name will automatically be generated.

Exceptions

Exception if 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

child	The child element that will be modified.
category	The 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.

virtual void Element::clearContent ( )

virtual

Clear all attributes and descendants from this element.

Reimplemented in InterfaceElement.

void Element::copyContentFrom ( const ConstElementPtr & source )

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

Parameters

source The 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

geom	An 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 746 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 253 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 181 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 217 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 713 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 587 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 504 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 511 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 122 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 429 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 438 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 446 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 454 of file Element.h.

const string& Element::getColorSpace ( ) const

inline

Return the element's color space string.

Definition at line 246 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

namePath The relative name path of the specified element.

string Element::getDocString ( ) const

inline

Return the documentation string of this element.

Definition at line 369 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 174 of file Element.h.

const string& Element::getGeomPrefix ( ) const

inline

Return the element's geom prefix string.

Definition at line 210 of file Element.h.

ElementPtr Element::getInheritsFrom ( ) const

inline

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

Definition at line 301 of file Element.h.

const string& Element::getInheritString ( ) const

inline

Return the inherit string of this element.

Definition at line 282 of file Element.h.

const string& Element::getName ( ) const

inline

Return the element's name string.

Definition at line 138 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

relativeTo If 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 330 of file Element.h.

ElementPtr Element::getParent ( )

inline

Return our parent element.

Definition at line 562 of file Element.h.

ConstElementPtr Element::getParent ( ) const

inline

Return our parent element.

Definition at line 568 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 337 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 550 of file Element.h.

ConstElementPtr Element::getSelf ( ) const

inline

Return our self pointer.

Definition at line 556 of file Element.h.

ElementPtr Element::getSelfNonConst ( ) const

inlineprotected

Definition at line 802 of file Element.h.

const string& Element::getSourceUri ( ) const

inline

Return the element's source URI.

Definition at line 706 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 527 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

index An 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 657 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

index An 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 497 of file Element.h.

bool Element::hasColorSpace ( ) const

inline

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

Definition at line 240 of file Element.h.

bool Element::hasFilePrefix ( ) const

inline

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

Definition at line 168 of file Element.h.

bool Element::hasGeomPrefix ( ) const

inline

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

Definition at line 204 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 276 of file Element.h.

bool Element::hasNamespace ( ) const

inline

Return true if this element has a namespace string.

Definition at line 324 of file Element.h.

bool Element::hasSourceUri ( ) const

inline

Return true if this element has a source URI.

Definition at line 700 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 381 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 483 of file Element.h.

template<class T >

shared_ptr<T> Element::resolveNameReference	(	const string &	name,
		ConstElementPtr	parent = `nullptr`
	)		const

inlineprotected

Definition at line 776 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 114 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 234 of file Element.h.

void Element::setDocString ( const string & doc )

inline

Set the documentation string of this element.

Definition at line 363 of file Element.h.

void Element::setFilePrefix ( const string & prefix )

inline

Set the element's file prefix string.

Definition at line 162 of file Element.h.

void Element::setGeomPrefix ( const string & prefix )

inline

Set the element's geom prefix string.

Definition at line 198 of file Element.h.

void Element::setInheritsFrom ( ConstElementPtr super )

inline

Set the element that this one directly inherits from.

Definition at line 288 of file Element.h.

void Element::setInheritString ( const string & inherit )

inline

Set the inherit string of this element.

Definition at line 270 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

Exception if 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 318 of file Element.h.

void Element::setSourceUri ( const string & sourceUri )

inline

Set the element's source URI.

Parameters

sourceUri A 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 694 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 519 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

ExceptionFoundCycle if 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

ExceptionFoundCycle if 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,
		const string &	errorDesc
	)		const

protected

Friends And Related Function Documentation

template<class T >

friend class ElementRegistry

friend

Definition at line 99 of file Element.h.

Member Data Documentation

StringMap Element::_attributeMap

protected

Definition at line 815 of file Element.h.

StringVec Element::_attributeOrder

protected

Definition at line 816 of file Element.h.

string Element::_category

protected

Definition at line 808 of file Element.h.

ElementMap Element::_childMap

protected

Definition at line 812 of file Element.h.

vector<ElementPtr> Element::_childOrder

protected

Definition at line 813 of file Element.h.

string Element::_name

protected

Definition at line 809 of file Element.h.

weak_ptr<Element> Element::_parent

protected

Definition at line 818 of file Element.h.

weak_ptr<Element> Element::_root

protected

Definition at line 819 of file Element.h.

string Element::_sourceUri

protected

Definition at line 810 of file Element.h.

const string Element::COLOR_SPACE_ATTRIBUTE

static

Definition at line 791 of file Element.h.

const string Element::DOC_ATTRIBUTE

static

Definition at line 794 of file Element.h.

const string Element::FILE_PREFIX_ATTRIBUTE

static

Definition at line 789 of file Element.h.

const string Element::GEOM_PREFIX_ATTRIBUTE

static

Definition at line 790 of file Element.h.

const string Element::INHERIT_ATTRIBUTE

static

Definition at line 792 of file Element.h.

const string Element::NAME_ATTRIBUTE

static

Definition at line 788 of file Element.h.

const string Element::NAMESPACE_ATTRIBUTE

static

Definition at line 793 of file Element.h.

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

MaterialXCore/Element.h

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation