Util.h File Reference

Shader generation utility methods. More...

#include <MaterialXGenShader/Export.h>
#include <MaterialXCore/Document.h>
#include <unordered_set>

Go to the source code of this file.

Functions
MX_GENSHADER_API bool	isTransparentSurface (ElementPtr element, const string &target=EMPTY_STRING)
	Returns true if the given element is a surface shader with the potential of being transparent. More...
MX_GENSHADER_API void	mapValueToColor (ConstValuePtr value, Color4 &color)
	Maps a value to a four channel color if it is of the appropriate type. More...
MX_GENSHADER_API bool	requiresImplementation (ConstNodeDefPtr nodeDef)
	Return whether a nodedef requires an implementation.
MX_GENSHADER_API bool	elementRequiresShading (ConstTypedElementPtr element)
	Determine if a given element requires shading / lighting for rendering.
MX_GENSHADER_API vector< TypedElementPtr >	findRenderableMaterialNodes (ConstDocumentPtr doc)
	Find all renderable material nodes in the given document. More...
MX_GENSHADER_API vector< TypedElementPtr >	findRenderableElements (ConstDocumentPtr doc)
	Find all renderable elements in the given document, including material nodes if present, or graph outputs of renderable types if no material nodes are found. More...
MX_GENSHADER_API InputPtr	getNodeDefInput (InputPtr nodeInput, const string &target)
	Given a node input, return the corresponding input within its matching nodedef. More...
MX_GENSHADER_API void	tokenSubstitution (const StringMap &substitutions, string &source)
	Perform token substitutions on the given source string, using the given substituation map. More...
MX_GENSHADER_API vector< Vector2 >	getUdimCoordinates (const StringVec &udimIdentifiers)
	Compute the UDIM coordinates for a set of UDIM identifiers. More...
MX_GENSHADER_API void	getUdimScaleAndOffset (const vector< Vector2 > &udimCoordinates, Vector2 &scaleUV, Vector2 &offsetUV)
	Get the UV scale and offset to transform uv coordinates from UDIM uv space to 0..1 space.
MX_GENSHADER_API NodePtr	connectsToWorldSpaceNode (OutputPtr output)
	Determine whether the given output is directly connected to a node that generates world-space coordinates (e.g. More...
MX_GENSHADER_API bool	hasElementAttributes (OutputPtr output, const StringVec &attributes)
	Returns true if there is are any value elements with a given set of attributes either on the starting node or any graph upsstream of that node. More...
MX_GENSHADER_API void	findRenderableMaterialNodes (ConstDocumentPtr doc, vector< TypedElementPtr > &elements, bool, std::unordered_set< ElementPtr > &)
MX_GENSHADER_API void	findRenderableElements (ConstDocumentPtr doc, vector< TypedElementPtr > &elements, bool includeReferencedGraphs=false)

Detailed Description

Shader generation utility methods.

Function Documentation

connectsToWorldSpaceNode()

MX_GENSHADER_API NodePtr connectsToWorldSpaceNode

(

OutputPtr

output

)

Determine whether the given output is directly connected to a node that generates world-space coordinates (e.g.

the "normalmap" node).

Parameters

output

Output to check

Returns

Return the node if found.

findRenderableElements()

MX_GENSHADER_API vector< TypedElementPtr > findRenderableElements

(

ConstDocumentPtr

doc

)

Find all renderable elements in the given document, including material nodes if present, or graph outputs of renderable types if no material nodes are found.

Parameters

doc	Document to examine

Returns

A vector of renderable elements

findRenderableMaterialNodes()

MX_GENSHADER_API vector< TypedElementPtr > findRenderableMaterialNodes

(

ConstDocumentPtr

doc

)

Find all renderable material nodes in the given document.

Parameters

doc	Document to examine

Returns

A vector of renderable material nodes.

getNodeDefInput()

MX_GENSHADER_API InputPtr getNodeDefInput	(	InputPtr	nodeInput,
		const string &	target
	)

Given a node input, return the corresponding input within its matching nodedef.

The optional target string can be used to guide the selection of nodedef declarations.

getUdimCoordinates()

MX_GENSHADER_API vector< Vector2 > getUdimCoordinates

(

const StringVec &

udimIdentifiers

)

Compute the UDIM coordinates for a set of UDIM identifiers.

Returns

List of UDIM coordinates

hasElementAttributes()

MX_GENSHADER_API bool hasElementAttributes	(	OutputPtr	output,
		const StringVec &	attributes
	)

Returns true if there is are any value elements with a given set of attributes either on the starting node or any graph upsstream of that node.

Parameters

output	Starting node
attributes	Attributes to test for

isTransparentSurface()

MX_GENSHADER_API bool isTransparentSurface	(	ElementPtr	element,
		const string &	target = EMPTY_STRING
	)

Returns true if the given element is a surface shader with the potential of being transparent.

This can be used by HW shader generators to determine if a shader will require transparency handling.

Note: This function will check some common cases for how a surface shader can be transparent. It is not covering all possible cases for how transparency can be done and target applications might need to do additional checks to track transparency correctly. For example, custom surface shader nodes implemented in source code will not be tracked by this function and transprency for such nodes must be tracked separately by the target application.

mapValueToColor()

MX_GENSHADER_API void mapValueToColor	(	ConstValuePtr	value,
		Color4 &	color
	)

Maps a value to a four channel color if it is of the appropriate type.

Supported types include float, Vector2, Vector3, Vector4, and Color4. If not mapping is possible the color value is set to opaque black.

tokenSubstitution()

MX_GENSHADER_API void tokenSubstitution	(	const StringMap &	substitutions,
		string &	source
	)

Perform token substitutions on the given source string, using the given substituation map.

Tokens are required to start with '$' and can only consist of alphanumeric characters. The full token name, including '$' and all following alphanumeric character, will be replaced by the corresponding string in the substitution map, if the token exists in the map.