Data Structures | Functions
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...
 

Functions

AI_API AtMetadataStoreAiMetadataStore ()
 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...
 

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:

{
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
nentrythis is the AtNodeEntry (note that nentry is an argument to node_parameters)
paramthe 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)
namethe name of the metadata you want to attach
valuethe value of the metadata
AI_API void AiMetaDataSetBool (AtNodeEntry *nentry, const AtString param, const AtString name, bool value)
 
void AiMetaDataSetBool (AtNodeEntry *nentry, const char *param, const char *name, bool value)
 
AI_API void AiMetaDataSetInt (AtNodeEntry *nentry, const AtString param, const AtString name, int value)
 
void AiMetaDataSetInt (AtNodeEntry *nentry, const char *param, const char *name, int value)
 
AI_API void AiMetaDataSetFlt (AtNodeEntry *nentry, const AtString param, const AtString name, float value)
 
void AiMetaDataSetFlt (AtNodeEntry *nentry, const char *param, const char *name, float value)
 
AI_API void AiMetaDataSetRGB (AtNodeEntry *nentry, const AtString param, const AtString name, AtRGB value)
 
void AiMetaDataSetRGB (AtNodeEntry *nentry, const char *param, const char *name, AtRGB value)
 
AI_API void AiMetaDataSetRGBA (AtNodeEntry *nentry, const AtString param, const AtString name, AtRGBA value)
 
void AiMetaDataSetRGBA (AtNodeEntry *nentry, const char *param, const char *name, AtRGBA value)
 
AI_API void AiMetaDataSetVec (AtNodeEntry *nentry, const AtString param, const AtString name, AtVector value)
 
void AiMetaDataSetVec (AtNodeEntry *nentry, const char *param, const char *name, AtVector value)
 
AI_API void AiMetaDataSetVec2 (AtNodeEntry *nentry, const AtString param, const AtString name, AtVector2 value)
 
void AiMetaDataSetVec2 (AtNodeEntry *nentry, const char *param, const char *name, AtVector2 value)
 
AI_API void AiMetaDataSetStr (AtNodeEntry *nentry, const AtString param, const AtString name, AtString 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
entrythe AtNodeEntry of the node you want to get metadata from
paramthe 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)
namethe name of the metadata you want to get
[out]valueif the read succeeds, the variable pointed to by value will be overwritten with the metadata
Returns
true when the lookup is succesful
AI_API bool AiMetaDataGetBool (const AtNodeEntry *nentry, const AtString param, const AtString name, bool *value)
 
bool AiMetaDataGetBool (const AtNodeEntry *nentry, const char *param, const char *name, bool *value)
 
AI_API bool AiMetaDataGetInt (const AtNodeEntry *nentry, const AtString param, const AtString name, int *value)
 
bool AiMetaDataGetInt (const AtNodeEntry *nentry, const char *param, const char *name, int *value)
 
AI_API bool AiMetaDataGetFlt (const AtNodeEntry *nentry, const AtString param, const AtString name, float *value)
 
bool AiMetaDataGetFlt (const AtNodeEntry *nentry, const char *param, const char *name, float *value)
 
AI_API bool AiMetaDataGetRGB (const AtNodeEntry *nentry, const AtString param, const AtString name, AtRGB *value)
 
bool AiMetaDataGetRGB (const AtNodeEntry *nentry, const char *param, const char *name, AtRGB *value)
 
AI_API bool AiMetaDataGetRGBA (const AtNodeEntry *nentry, const AtString param, const AtString name, AtRGBA *value)
 
bool AiMetaDataGetRGBA (const AtNodeEntry *nentry, const char *param, const char *name, AtRGBA *value)
 
AI_API bool AiMetaDataGetVec (const AtNodeEntry *nentry, const AtString param, const AtString name, AtVector *value)
 
bool AiMetaDataGetVec (const AtNodeEntry *nentry, const char *param, const char *name, AtVector *value)
 
AI_API bool AiMetaDataGetVec2 (const AtNodeEntry *nentry, const AtString param, const AtString name, AtVector2 *value)
 
bool AiMetaDataGetVec2 (const AtNodeEntry *nentry, const char *param, const char *name, AtVector2 *value)
 
AI_API bool AiMetaDataGetStr (const AtNodeEntry *nentry, const AtString param, const AtString name, AtString *value)
 
bool AiMetaDataGetStr (const AtNodeEntry *nentry, const char *param, const char *name, AtString *value)
 

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
mdsthe metadata store to operate with
namethe name of the metadata you want to attach
valuethe value of the metadata
AI_API void AiMetadataStoreSetBool (AtMetadataStore *mds, const AtString name, bool value)
 
AI_API void AiMetadataStoreParamSetBool (AtMetadataStore *mds, const AtString param, const AtString name, bool value)
 
AI_API void AiMetadataStoreSetInt (AtMetadataStore *mds, const AtString name, int value)
 
AI_API void AiMetadataStoreParamSetInt (AtMetadataStore *mds, const AtString param, const AtString name, int value)
 
AI_API void AiMetadataStoreSetFlt (AtMetadataStore *mds, const AtString name, float value)
 
AI_API void AiMetadataStoreParamSetFlt (AtMetadataStore *mds, const AtString param, const AtString name, float value)
 
AI_API void AiMetadataStoreSetRGB (AtMetadataStore *mds, const AtString name, AtRGB value)
 
AI_API void AiMetadataStoreParamSetRGB (AtMetadataStore *mds, const AtString param, const AtString name, AtRGB value)
 
AI_API void AiMetadataStoreSetVec (AtMetadataStore *mds, const AtString name, AtVector value)
 
AI_API void AiMetadataStoreParamSetVec (AtMetadataStore *mds, const AtString param, const AtString name, AtVector value)
 
AI_API void AiMetadataStoreSetVec2 (AtMetadataStore *mds, const AtString name, AtVector2 value)
 
AI_API void AiMetadataStoreParamSetVec2 (AtMetadataStore *mds, const AtString param, const AtString name, AtVector2 value)
 
AI_API void AiMetadataStoreSetStr (AtMetadataStore *mds, const AtString name, AtString value)
 
AI_API void AiMetadataStoreParamSetStr (AtMetadataStore *mds, const AtString param, const AtString name, AtString value)
 
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
mdsthe metadata store to read from
namethe name of the metadata you want to get
[out]valueif the read succeeds, the variable pointed to by value will be overwritten with the metadata
Returns
true when the lookup is succesful
AI_API bool AiMetadataStoreGetBool (const AtMetadataStore *mds, const AtString name, bool *value)
 
AI_API bool AiMetadataStoreParamGetBool (const AtMetadataStore *mds, const AtString param, const AtString name, bool *value)
 
AI_API bool AiMetadataStoreGetInt (const AtMetadataStore *mds, const AtString name, int *value)
 
AI_API bool AiMetadataStoreParamGetInt (const AtMetadataStore *mds, const AtString param, const AtString name, int *value)
 
AI_API bool AiMetadataStoreGetFlt (const AtMetadataStore *mds, const AtString name, float *value)
 
AI_API bool AiMetadataStoreParamGetFlt (const AtMetadataStore *mds, const AtString param, const AtString name, float *value)
 
AI_API bool AiMetadataStoreGetRGB (const AtMetadataStore *mds, const AtString name, AtRGB *value)
 
AI_API bool AiMetadataStoreParamGetRGB (const AtMetadataStore *mds, const AtString param, const AtString name, AtRGB *value)
 
AI_API bool AiMetadataStoreGetVec (const AtMetadataStore *mds, const AtString name, AtVector *value)
 
AI_API bool AiMetadataStoreParamGetVec (const AtMetadataStore *mds, const AtString param, const AtString name, AtVector *value)
 
AI_API bool AiMetadataStoreGetVec2 (const AtMetadataStore *mds, const AtString name, AtVector2 *value)
 
AI_API bool AiMetadataStoreParamGetVec2 (const AtMetadataStore *mds, const AtString param, const AtString name, AtVector2 *value)
 
AI_API bool AiMetadataStoreGetStr (const AtMetadataStore *mds, const AtString name, AtString *value)
 
AI_API bool AiMetadataStoreParamGetStr (const AtMetadataStore *mds, const AtString param, const AtString name, AtString *value)
 

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.

NameTypeApplies toDescription
deprecatedBOOLEANNode entryIf a node entry has this metadata set to true, creating a node of that type will emit a warning about it being deprecated
gpu_supportBOOLEANNode entry / ParametersUsed to flag node types or parameters that are not yet supported by GPU rendering
is_perspectiveBOOLEANNode entryShould be set in a custom camera if it is a perspective camera
linkableBOOLEANParametersCan be use to flag if parameters can be linked (true if metadata is not set)
opacity_termINTEGERNode entry / ParametersSet 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_initBOOLEANNode EntrySet in custom procedurals to allow parallel initialization
pathSTRINGString ParametersSet to a string parameter to select specific semantics for the value (valid values: file, folder, folderlist)
_synonymSTRINGNode entry / ParametersProvides alternative name to node entries or parameters
transparency_termINTEGERNode entry / ParametersSet 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_reinitializeBOOLEANParametersSet on node parameters that will trigger a node deinit & reinitialization when modified
_triggers_reloadBOOLEANParameters(Deprecated) Synonym for _triggers_reinitialize
parallel_driver_needs_bucketBOOLEANNode entrySet on a driver to enable the driver_needs_bucket API to be executed in parallel
parallel_driver_prepare_bucketBOOLEANNode entrySet on a driver to enable the driver_prepare_bucket API to be executed in parallel
parallel_driver_write_bucketBOOLEANNode entrySet on a driver to enable the driver_write_bucket API to be executed in parallel
force_updateBOOLEANIf a node must always have its node_init or node_update run every pass even if arnold thinks the node has not changed

Function Documentation

AI_API AtMetadataStore* AiMetadataStore ( )

Creates a new metadata store.

Returns
new metadata store object
AI_API void AiMetadataStoreDestroy ( AtMetadataStore mds)

Destroys a metadata store object.

Parameters
mdsmetadata store object to be destroyed
AI_API bool AiMetadataStoreLoadFromASS ( AtMetadataStore mds,
const char *  file 
)

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

Parameters
mdsmetadata store object where embedded metadata will be loaded
filefilename of the .ass file with the embedded metadata to load
AI_API AtMetaDataIterator* AiMetadataStoreGetIterator ( const AtMetadataStore mds)

Creates a new metadata iterator that traverses all global metadata.

Parameters
mdsmetadata store object to get an iterator for
Returns
an iterator over all global metadata in a metadata store
AI_API AtMetaDataIterator* AiMetadataStoreGetIteratorRecursive ( const AtMetadataStore mds,
const char *  param,
bool  recursive 
)

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

Parameters
mdsmetadata store object to get an iterator for
paramrequest metadata for a specific param (or global metadata if param is NULL)
recursiveif 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
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:

1 const char* metadata_file = "my_metadata_file.mtd";
2 bool success = AiMetaDataLoadFile(metadata_file)
3 if (!success)
4  printf("\nError loading metadata file %s", metadata_file);
Parameters
filenamethe full path of the metadata file to load
Returns
true when the file could be read succesfully

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com