Metadata API

Reading and writing of metadata. More...

Data Structures
struct	AtMetadataStore
	This structure holds a generic list of metadata items, each of which could optionally be associated to a specific parameter (for node metadata). More...

Node metadata writing
These functions allow attaching auxiliary information about specific parameters or the node itself. This information is stored within the AtNodeEntry. These methods may only be called within the node_parameters function where the parameters are declared. Here is an example: node_parameters { AiParameterFlt("Kd", 0.7f); // create a lower-case synonym for parameter Kd AiMetaDataSetStr(nentry, "Kd", "_synonym", "kd"); // describe the parameter AiMetaDataSetStr(nentry, "Kd", "description", "Diffuse coefficient"); // describe the node itself AiMetaDataSetStr(nentry, NULL, "description", "This is a simple lambert shader for illustration purposes"); } Note that you should never pass allocated strings, as they will not be freed. Parameters nentry this is the AtNodeEntry (note that nentry is an argument to node_parameters) param the name of the node parameter to which the metadata will be attached (or a null/empty string if you want to attach information to the node itself) name the name of the metadata you want to attach value the value of the metadata
const AtString	param
const AtString const AtString	name
const AtString const AtString bool	value { return AiMetaDataGetBool (nentry, AtString(param), AtString(name), value)
	__attribute__ ((visibility("default"))) void AiMetaDataSetBool(AtNodeEntry *nentry
void	AiMetaDataSetBool (AtNodeEntry *nentry, const char *param, const char *name, bool value)
void	AiMetaDataSetInt (AtNodeEntry *nentry, const char *param, const char *name, int value)
void	AiMetaDataSetFlt (AtNodeEntry *nentry, const char *param, const char *name, float value)
void	AiMetaDataSetRGB (AtNodeEntry *nentry, const char *param, const char *name, AtRGB value)
void	AiMetaDataSetRGBA (AtNodeEntry *nentry, const char *param, const char *name, AtRGBA value)
void	AiMetaDataSetVec (AtNodeEntry *nentry, const char *param, const char *name, AtVector value)
void	AiMetaDataSetVec2 (AtNodeEntry *nentry, const char *param, const char *name, AtVector2 value)
void	AiMetaDataSetStr (AtNodeEntry *nentry, const char *param, const char *name, AtString value)
void	AiMetaDataSetStr (AtNodeEntry *nentry, const char *param, const char *name, const char *value)

Node Metadata Retrieval
These functions allow client code to examine metadata attached to specific parameters or to a node. Following on the example above: const AtNodeEntry* entry = AiNodeEntryLookUp("my_simple_lambert"); char* desc; bool success = AiMetaDataGetStr(entry, "Kd", "description", &desc) if (success) printf("\nDescription for parameter Kd: %s", desc); Parameters entry the AtNodeEntry of the node you want to get metadata from param the name of the node parameter you want to get metadata from (or null/empty string if you are looking for metadata on the node itself) name the name of the metadata you want to get [out] value if the read succeeds, the variable pointed to by value will be overwritten with the metadata Returns true when the lookup is succesful
	__attribute__ ((deprecated)) bool AiMetaDataGetBool(const AtNodeEntry *nentry

AtMetadataStore Writing
These functions allow attaching auxiliary information to a specific metadata store. Here is an example: AiMetadataStoreSetStr(mds, AtString("author"), "William Shakespeare"); AiMetadataStoreSetStr(mds, AtString("bbox"), "-1 -1 -1 1 1 1"); AiMetadataStoreSetFlt(mds, AtString("temperature"), 21.0f); Note that you should never pass allocated strings, as they will not be freed. Parameters mds the metadata store to operate with name the name of the metadata you want to attach value the value of the metadata
void	AiMetadataStoreSetStr (AtMetadataStore *mds, const AtString name, const char *value)
void	AiMetadataStoreParamSetStr (AtMetadataStore *mds, const AtString param, const AtString name, const char *value)

AtMetadataStore Retrieval
These functions allow client code to get metadata entries within a specific metadata store. Following on the example above: char* author; bool success = AiMetadataStoreGetStr(mds, "author", &author) if (success) printf("\nAuthor: %s", author); Parameters mds the metadata store to read from name the name of the metadata you want to get [out] value if the read succeeds, the variable pointed to by value will be overwritten with the metadata Returns true when the lookup is succesful
AI_API AtMetadataStore *	AiMetadataStore ()
	Creates a new metadata store. More...
AI_API void	AiMetadataStoreDestroy (AtMetadataStore *mds)
	Destroys a metadata store object. More...
AI_API bool	AiMetadataStoreLoadFromASS (AtMetadataStore *mds, const char *file)
	Load embedded metadata from an .ass file into a metadata store. More...
AI_API AtMetaDataIterator *	AiMetadataStoreGetIterator (const AtMetadataStore *mds)
	Creates a new metadata iterator that traverses all global metadata. More...
AI_API AtMetaDataIterator *	AiMetadataStoreGetIteratorRecursive (const AtMetadataStore *mds, const char *param, bool recursive)
	Creates a new metadata iterator pointing at the first matching entry. More...
AI_API bool	AiMetaDataLoadFile (const char *filename)
	Load a metadata file. More...

Detailed Description

Reading and writing of metadata.

Arnold provides a container for generic metadata called AtMetadataStore. An AtMetadataStore object can contain any number of metadata items, each consisting on a name, type and value.

Every Arnold AtNodeEntry object contains its own AtMetadataStore, with metadata specific to that node entry and its parameters. All this metadata is shared among all nodes of that type. This metadata can be helpful to maintain extra annotations about parameters for GUI tools for example.

Finally, metadata can also be loaded from a metadata file, or embedded in .ass files.

The following metadata items are recognized by Arnold, and could be used to modify the way nodes and parameters are processed.

Name	Type	Applies to	Description
animatable	BOOLEAN	Array parameters	Indicate if keyframe data in array parameter is used in animation (ie motion blur)
aov_shader	BOOLEAN	Node entry	Indicate if a shader may usefully be assigned as a global AOV shader in the "aov_shaders" render option
aov.type<td> INTEGER	STRING parameters	For string parameters describing custom AOV outputs of a shader, describes the AOV's type (AI_TYPE_INT, AI_TYPE_FLOAT, AI_TYPE_RGB, etc)
category	STRING	Node entry	Category under which to display a shader node in UIs (built-in categories are: "AOV","Atmosphere","Color","Convert","Light Filter","Math","Matrix","Noise","Shading","State","Texture","User Data","Utility","Vector","Volume")
default	*<Parameter's type>*	Parameters	Default value to present in user interfaces
deprecated	BOOLEAN	Node entry	If a node entry has this metadata set to true, creating a node of that type will emit a warning about it being deprecated
extensions	STRING	Parameters	Used to tag a file path parameter with supported extensions
force_update	BOOLEAN	If a node must always have its node_init or node_update run every pass even if arnold thinks the node has not changed
gpu_support	BOOLEAN	Node entry / Parameters	Used to flag node types or parameters that are not yet supported by GPU rendering
help	STRING	Node entry / Parameters	Descriptive text used to help indicate the design and purpose of a node or one of its parameters
is_perspective	BOOLEAN	Node entry	Should be set in a custom camera if it is a perspective camera
linkable	BOOLEAN	Parameters	Can be use to flag if parameters can be linked (true if metadata is not set)
max	*<Parameter type>*	Numeric parameters	Maximum value above which a parameter loses functionality
min	*<Parameter type>*	Numeric parameters	Minimum value below which a parameter loses functionality
opacity_term	INTEGER	Node entry / Parameters	Set to a shader node entry if it is always opaque, or set to a parameter that is opaque when equal to 1 (1, 1, 1)
parallel_driver_needs_bucket	BOOLEAN	Node entry	Set on a driver to enable the driver_needs_bucket API to be executed in parallel
parallel_driver_prepare_bucket	BOOLEAN	Node entry	Set on a driver to enable the driver_prepare_bucket API to be executed in parallel
parallel_driver_write_bucket	BOOLEAN	Node entry	Set on a driver to enable the driver_write_bucket API to be executed in parallel
parallel_init	BOOLEAN	Node Entry	Set in custom procedurals to allow parallel initialization
path	STRING	String Parameters	Set to a string parameter to select specific semantics for the value (valid values: file, folder, folderlist)
softmax	*<Parameter type>*	Numeric parameters	Recommended maximum value to present in user interfaces
softmin	*<Parameter type>*	Numeric parameters	Recommended minimum value to present in user interfaces
_synonym	STRING	Node entry / Parameters	Provides alternative name to node entries or parameters
transparency_term	INTEGER	Node entry / Parameters	Set to a shader node entry if it is always transparent, or set to a parameter that is opaque when equal to 0 (0, 0, 0)
_triggers_reinitialize	BOOLEAN	Parameters	Set on shape node parameters that will trigger a node deinit & reinitialization when modified
_triggers_reload	BOOLEAN	Parameters	(Deprecated) Synonym for _triggers_reinitialize
ui.groups<td> STRING	Node entry	String describing the recommended paramter grouping for UIs. Formatting is: "Group1:param1 param2,Group2:param3 param4"

Function Documentation

AiMetadataStore()

AI_API AtMetadataStore * AiMetadataStore

(

)

Creates a new metadata store.

Returns

new metadata store object

AiMetadataStoreDestroy()

AI_API void AiMetadataStoreDestroy

(

AtMetadataStore *

mds

)

Destroys a metadata store object.

Parameters

mds	metadata store object to be destroyed

AiMetadataStoreLoadFromASS()

AI_API bool AiMetadataStoreLoadFromASS	(	AtMetadataStore *	mds,
		const char *	file
	)

Load embedded metadata from an .ass file into a metadata store.

Parameters

mds	metadata store object where embedded metadata will be loaded
file	filename of the .ass file with the embedded metadata to load

AiMetadataStoreGetIterator()

AI_API AtMetaDataIterator * AiMetadataStoreGetIterator

(

const AtMetadataStore *

mds

)

Creates a new metadata iterator that traverses all global metadata.

Parameters

mds	metadata store object to get an iterator for

Returns

an iterator over all global metadata in a metadata store

AiMetadataStoreGetIteratorRecursive()

AI_API AtMetaDataIterator * AiMetadataStoreGetIteratorRecursive	(	const AtMetadataStore *	mds,
		const char *	param,
		bool	recursive
	)

Creates a new metadata iterator pointing at the first matching entry.

Parameters

mds	metadata store object to get an iterator for
param	request metadata for a specific param (or global metadata if param is NULL)
recursive	if true and param is NULL, it will traverse both global metadata and param metadata for all params

Returns

an iterator over all metadata in a metadata store

AiMetaDataLoadFile()

AI_API bool AiMetaDataLoadFile

(

const char *

filename

)

Load a metadata file.

Metadata items loaded from this file will be attached to existing node entries and their parameters, as especified by the .mtd file format

Usage:

const char* metadata_file = "my_metadata_file.mtd";
bool success = AiMetaDataLoadFile(metadata_file)
if (!success)
   printf("\nError loading metadata file %s", metadata_file);

Parameters

filename

the full path of the metadata file to load

Returns

true when the file could be read succesfully