MaterialX API

MaterialX document processing. More...

Enumerations
enum	AtMaterialxErrorCode { AI_MATX_SUCCESS , AI_MATX_ERROR_LOAD_DOCUMENT , AI_MATX_ERROR_NO_MATERIALS }
	MaterialX error codes. More...

Functions
AI_API int	AiMaterialxWrite (const AtUniverse *universe, const char *filename, const char *look_name, const char *properties=NULL, bool relative=true)
	Generate and write a MaterialX document to a file from an Arnold scene. More...
AI_API int	AiMaterialxWriteMaterial (const char *filename, const char *material_name, const AtNode *surface=NULL, const AtNode *volume=NULL, const AtNode *displacement=NULL)
AI_API AtArray *	AiMaterialxGetLookNames (const char *filename)
	Get a list of look names in a MaterialX document. More...
AI_API AtArray *	AiMaterialxGetMaterialNames (const char *filename)
	Get a list of material names in a MaterialX document. More...
AI_API int	AiMaterialxReadMaterials (AtUniverse *universe, const char *filename, const AtParamValueMap *params=NULL, AtArray *nodes=NULL)
	Populates an Arnold universe with materials in a MaterialX document. More...
AI_API const AtString	AiMaterialxGetOslShaderCode (const char *node_definition, const char *shader_name, AtParamValueMap *connected_inputs=nullptr)
	Given a MaterialX node definition, generate its corresponding OSL code as a shader. More...
AI_API const AtNodeEntry *	AiMaterialxGetNodeEntryFromDefinition (const char *node_definition, AtParamValueMap *optional_parameters=nullptr)
	Given a MaterialX node definition, returns the corresponding Arnold Node Entry. More...

Detailed Description

MaterialX document processing.

This API acts as a bridge between the Arnold and MaterialX data models. For instance, materials and looks in an Arnold universe can be written to a MaterialX document, and vice versa.

Other utility functions can be used to introspect and query elements in a MaterialX document such as look and material names.

Enumeration Type Documentation

AtMaterialxErrorCode

enum AtMaterialxErrorCode

MaterialX error codes.

Enumerator
AI_MATX_SUCCESS	no error
AI_MATX_ERROR_LOAD_DOCUMENT	error loading the document
AI_MATX_ERROR_NO_MATERIALS	no materials found

Function Documentation

AiMaterialxWrite()

AI_API int AiMaterialxWrite	(	const AtUniverse *	universe,
		const char *	filename,
		const char *	look_name,
		const char *	properties,
		bool	relative
	)

Generate and write a MaterialX document to a file from an Arnold scene.

Parameters

universe	universe whose contents will be written to a .mtlx document (NULL for default universe)
filename	output filename
look_name	output look name that will be created/appended
properties	a list of parameter names to include in the property assignments, where the string is expected to follow the materialx comma-separated convention (spaces are ignored)
relative	if true, the assignments for nodes will be relative to their top-most parent node

Returns

0 if the file was written succesfully, -1 otherwise

AiMaterialxGetLookNames()

AI_API AtArray * AiMaterialxGetLookNames

(

const char *

filename

)

Get a list of look names in a MaterialX document.

Parameters

filename

mtlx document filename

Returns

string array containing the look names, must be freed with AiArrayDestroy

AiMaterialxGetMaterialNames()

AI_API AtArray * AiMaterialxGetMaterialNames

(

const char *

filename

)

Get a list of material names in a MaterialX document.

Parameters

filename

mtlx document filename

Returns

string array containing the material names, must be freed with AiArrayDestroy

AiMaterialxReadMaterials()

AI_API int AiMaterialxReadMaterials	(	AtUniverse *	universe,
		const char *	filename,
		const AtParamValueMap *	params,
		AtArray *	nodes
	)

Populates an Arnold universe with materials in a MaterialX document.

Parameters

universe	universe which will be populated with MaterialX materials
filename	mtlx document filename, or blob of text containing MaterialX document
params	Optional parameters that influance the generated nodes "material" - set the material to return, if not set return all materials in document "shader_prefix" - a string to prefix all generated shaders with
nodes	an array of the nodes generated from reading the document

AiMaterialxGetOslShaderCode()

AI_API const AtString AiMaterialxGetOslShaderCode	(	const char *	node_definition,
		const char *	shader_name,
		AtParamValueMap *	connected_inputs
	)

Given a MaterialX node definition, generate its corresponding OSL code as a shader.

Arnold will search for node definitions in the materialx directory in the Arnold distribution and in any directory listed in the ARNOLD_MATERIALX_NODE_DEFINITIONS environment variable.

Parameters

node_definition	materialx node definition
shader_name	name of the returned OSL shader, note that OSL non-uniform parameters are prefixed with the node name
connected_inputs	Optional parameters to the function, specifying connected node parameter names as keys in the connected_input map will affect the OSL code generation for GeomProp parameters such as UV coordinates and position. The reserved MATERIALX_NODE_DEFINITIONS parameter can be set to load additional MaterialX node definitions.

Returns

The OSL shader code as an AtString

AiMaterialxGetNodeEntryFromDefinition()

AI_API const AtNodeEntry * AiMaterialxGetNodeEntryFromDefinition	(	const char *	node_definition,
		AtParamValueMap *	optional_parameters
	)

Given a MaterialX node definition, returns the corresponding Arnold Node Entry.

Arnold will search for node definitions in the materialx directory in the Arnold distribution and in any directory listed in the ARNOLD_MATERIALX_NODE_DEFINITIONS environment variable.

Parameters

node_definition	materialx node definition
optional_parameters	The reserved MATERIALX_NODE_DEFINITIONS parameter can be set to load additional MaterialX node definitions.

Returns

The Arnold node entry corresponding to the node definition or nullptr if the definition is unknown