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...

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

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.

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

Returns

The OSL shader code as an AtString