Data Structures | Macros
AtNode API

Arnold has a pluggable node-management system for the standard primitives such as lights, cameras, geometry, shaders, filters, drivers, etc. More...

Data Structures

struct  AtNode
 This represents a node in Arnold. More...
 

Macros

#define AI_INSTANCE_COMMON_METHODS
 Exporter for common methods. More...
 

Node Method Declarations

#define node_parameters   static void Parameters(AtList* params, AtMetaDataStore* mds)
 Parameter declaration method.
 
#define node_initialize   static void Initialize(AtNode* node, AtParamValue* params)
 Node initialization method.
 
#define node_update   static void Update(AtNode* node, AtParamValue* params)
 Node update method.
 
#define node_finish   static void Finish(AtNode* node)
 Node de-initialization method.
 
#define node_loader   AI_EXPORT_LIB bool NodeLoader(int i, AtNodeLib* node)
 Node loading method (for plugin nodes in dynamic libraries)
 

AtNode Methods

AI_API AtNodeAiNode (const char *name)
 Create a fresh instantiation of a node. More...
 
AI_API AtNodeAiNodeLookUpByName (const char *name)
 Search all nodes in the scene by name. More...
 
AI_API void AiNodeReset (AtNode *node)
 Reset all node parameters to their default values and remove any input links. More...
 
AI_API AtNodeAiNodeClone (const AtNode *node)
 Return an exact clone of a source node. More...
 
AI_API bool AiNodeDestroy (AtNode *node)
 Destroy an existing node. More...
 
AI_API bool AiNodeIs (const AtNode *node, const char *str)
 Compare the node type against a string. More...
 
AI_API bool AiNodeDeclare (AtNode *node, const char *param, const char *declaration)
 Declare a user-defined parameter for this node. More...
 
AI_API bool AiNodeLink (AtNode *src, const char *input, AtNode *target)
 Creates a connection between two shader nodes. More...
 
AI_API bool AiNodeLinkOutput (AtNode *src, const char *output, AtNode *target, const char *input)
 Creates a connection between two shader nodes. More...
 
AI_API bool AiNodeUnlink (AtNode *node, const char *input)
 Removes a connection from a node input parameter. More...
 
AI_API bool AiNodeIsLinked (const AtNode *node, const char *input)
 Returns true if the input parameter is linked. More...
 
AI_API AtNodeAiNodeGetLink (const AtNode *node, const char *input, int *comp=NULL)
 Returns the node connected to a given node input parameter. More...
 
AI_API const char * AiNodeGetName (const AtNode *node)
 Return the node's name. More...
 
AI_API const AtNodeEntryAiNodeGetNodeEntry (const AtNode *node)
 Return the node entry for this node. More...
 
AI_API AtParamValueAiNodeGetParams (const AtNode *node)
 Returns an array with all parameter values. More...
 
AI_API void * AiNodeGetLocalData (const AtNode *node)
 Returns a pointer to the local data in the node. More...
 
AI_API void AiNodeSetLocalData (AtNode *node, void *data)
 Sets local data pointer in the node. More...
 
AI_API const AtUserParamEntry * AiNodeLookUpUserParameter (const AtNode *node, const char *param)
 Return the user-defined parameter entry that matches a given name. More...
 
AI_API AtUserParamIterator * AiNodeGetUserParamIterator (const AtNode *node)
 Creates and returns a new AtUserParamIterator for this node. More...
 

AtUserParamIterator Methods

AI_API void AiUserParamIteratorDestroy (AtUserParamIterator *iter)
 Destroys a user param iterator when it is no longer needed. More...
 
AI_API const AtUserParamEntry * AiUserParamIteratorGetNext (AtUserParamIterator *iter)
 Returns current user param entry and points user param iterator to the next one. More...
 
AI_API bool AiUserParamIteratorFinished (const AtUserParamIterator *iter)
 Returns true if there are no more user parameters to iterate over. More...
 

Parameter Writers

AI_API void AiNodeSetByte (AtNode *node, const char *param, AtByte val)
 
AI_API void AiNodeSetInt (AtNode *node, const char *param, int val)
 Set the value of an integer parameter. More...
 
AI_API void AiNodeSetUInt (AtNode *node, const char *param, unsigned int val)
 
AI_API void AiNodeSetBool (AtNode *node, const char *param, bool val)
 
AI_API void AiNodeSetFlt (AtNode *node, const char *param, float val)
 
AI_API void AiNodeSetRGB (AtNode *node, const char *param, float r, float g, float b)
 
AI_API void AiNodeSetRGBA (AtNode *node, const char *param, float r, float g, float b, float a)
 
AI_API void AiNodeSetVec (AtNode *node, const char *param, float x, float y, float z)
 
AI_API void AiNodeSetPnt (AtNode *node, const char *param, float x, float y, float z)
 
AI_API void AiNodeSetPnt2 (AtNode *node, const char *param, float x, float y)
 
AI_API void AiNodeSetStr (AtNode *node, const char *param, const char *str)
 
AI_API void AiNodeSetPtr (AtNode *node, const char *param, void *ptr)
 
AI_API void AiNodeSetArray (AtNode *node, const char *param, AtArray *array)
 Set the value of an array parameter. More...
 
AI_API void AiNodeSetMatrix (AtNode *node, const char *param, AtMatrix matrix)
 
AI_API void AiNodeSetAttributes (AtNode *node, const char *attributes)
 Set the parameters of a node through an attributes string. More...
 

Parameter Readers

AI_API AtByte AiNodeGetByte (const AtNode *node, const char *param)
 
AI_API int AiNodeGetInt (const AtNode *node, const char *param)
 Return the value of an integer parameter. More...
 
AI_API unsigned int AiNodeGetUInt (const AtNode *node, const char *param)
 
AI_API bool AiNodeGetBool (const AtNode *node, const char *param)
 
AI_API float AiNodeGetFlt (const AtNode *node, const char *param)
 
AI_API AtRGB AiNodeGetRGB (const AtNode *node, const char *param)
 
AI_API AtRGBA AiNodeGetRGBA (const AtNode *node, const char *param)
 
AI_API AtVector AiNodeGetVec (const AtNode *node, const char *param)
 
AI_API AtPoint AiNodeGetPnt (const AtNode *node, const char *param)
 
AI_API AtPoint2 AiNodeGetPnt2 (const AtNode *node, const char *param)
 
AI_API const char * AiNodeGetStr (const AtNode *node, const char *param)
 
AI_API void * AiNodeGetPtr (const AtNode *node, const char *param)
 
AI_API AtArrayAiNodeGetArray (const AtNode *node, const char *param)
 
AI_API void AiNodeGetMatrix (const AtNode *node, const char *param, AtMatrix matrix)
 

Detailed Description

Arnold has a pluggable node-management system for the standard primitives such as lights, cameras, geometry, shaders, filters, drivers, etc.

Each node type has a set of associated methods (member functions) and parameters. Like C++'s objects, Arnold's node system allows new nodes to inherit both parameters and methods from the "parent" node. For example, all nodes have a "name" parameter and a "node_initialize{}" method (among others) because they are declared in the base node from which all nodes inherit.

In addition to these standard methods and parameters, derived nodes may have their own type-specific parameters and methods. For example, all shaders have a "shader_evaluate{}" method and all driver nodes have a "driver_write_bucket{}" method (among others). User-derived nodes may have their own new parameters but are not permitted to add new methods.

Two of the important data-structures in this object-oriented-like system are:

Macro Definition Documentation

#define AI_INSTANCE_COMMON_METHODS
Value:
node_initialize; \
node_update; \
node_finish; \
static AtCommonMethods ai_common_mtds = { \
Parameters, \
Initialize, \
Update, \
Finish \
};

Exporter for common methods.

Function Documentation

AI_API AtNode* AiNode ( const char *  name)

Create a fresh instantiation of a node.

Arnold-based apps would call this function to populate the scene with nodes. Node instantiations can be created out of built-in nodes (such as "sphere" or "lambert"), manually-installed nodes (using AiNodeEntryInstall()), or plug-in nodes contained in a .so/.dll dynamic library (using AiLoadPlugins()).

The system automatically destroys all nodes at AiEnd() time prior to shutdown.

Parameters
namename of the type of node to be created ("polymesh", etc)
Returns
pointer to a new AtNode of the requested type, or NULL if the node could not be created (the node wasn't previously installed, or it was in the ignore list)
AI_API AtNode* AiNodeLookUpByName ( const char *  name)

Search all nodes in the scene by name.

Given a name string, loop over all node instances in the scene checking for a matching "name" parameter. If found return the node.

Parameters
namename to look up
Returns
pointer to a node whose "name" parameter matches the given name string, or NULL if there are no nodes with that name
AI_API void AiNodeReset ( AtNode node)

Reset all node parameters to their default values and remove any input links.

Parameters
nodepointer to a node to be reset (if the pointer is NULL, the function will simply return)
AI_API AtNode* AiNodeClone ( const AtNode node)

Return an exact clone of a source node.

Note that this performs a "deep" copy of all of the node's parameters, including strings and arrays.

Parameters
nodethe source node to be cloned
Returns
a clone of the source node, or NULL if the source was NULL or was non-clonable (like the options node)
AI_API bool AiNodeDestroy ( AtNode node)

Destroy an existing node.

This function releases all resources associated with an existing node, including all of its memory, parameters, arrays, etc. Attempts to access a destroyed node will cause undefined behaviour.

For now, this function will do nothing if called during rendering.

Parameters
nodepointer to an existing node, generally coming from AiNode()
Returns
true if the node was destroyed, false otherwise
AI_API bool AiNodeIs ( const AtNode node,
const char *  string 
)

Compare the node type against a string.

This is a useful helper function that allows one to write code like:

if (AiNodeIs(mynode,"lambert"))
{
// do something exciting that only applies to lambert nodes
}
Parameters
nodepointer to a node whose type is to be compared
stringthe name of an existing node type
Returns
true if the node type's name matches the given string
AI_API bool AiNodeDeclare ( AtNode node,
const char *  name,
const char *  declaration 
)

Declare a user-defined parameter for this node.

Adds new parameter of type 'declaration' to the specified node instantiation. declaration is a string of the form "class type", where:

  • class := { constant, uniform, varying }
  • type := { BYTE, INT, BOOL, FLOAT, RGB, POINT, STRING, etc. }

The scope of the different classes is:

  • constant values exist on a per-object basis
  • uniform values exist on a per-face basis
  • varying values exist on a per-vertex basis

In the case where the type is ARRAY, then the user should also supply the array type as well.

In the following example, we are declaring two user-defined parameters, "bar" and "heatmap", for one specific polymesh node whose name is "mymesh":

AtNode *mymesh = AiNode("polymesh");
AiNodeDeclare(mymesh, "bar", "constant BOOL");
AiNodeDeclare(mymesh, "heatmap", "constant ARRAY RGB");
Parameters
nodeinput node
namename of the new parameter
declarationdeclaration string for the class and type of the new parameter
Returns
true if the parameter could be succesfully added: it didn't already exist and the declaration string wasn't malformed
See Also
User-Data API
AI_API bool AiNodeLink ( AtNode src,
const char *  input,
AtNode target 
)

Creates a connection between two shader nodes.

This is just a convenience function for linking shaders when the whole output of the source shader is used. It maintains the previous API for linking. Eveything else is the same as in AiNodeLinkOutput.

So, this:

AiNodeLink(source, "parameter", target);

is equivalent to:

AiNodeLinkOutput(source, "", target, "parameter");
See Also
AiNodeLinkOutput
Parameters
srca non-NULL pointer to the source node, to be connected to the target node
inputthe input parameter specification in the target node, which can optionally include a component specification (e.g. "Kd.r", "dir.x"), an array element index (e.g. "colors[1]") or both (e.g. "colors[1].r").
targeta non-NULL pointer to the target node whose input parameter will be connected to the output of the source node
Returns
true if the connection was performed successfully, false otherwise
AI_API bool AiNodeLinkOutput ( AtNode src,
const char *  output,
AtNode target,
const char *  input 
)

Creates a connection between two shader nodes.

This function is used to build shader networks. It links the output of the source node to one of the input parameters in the target node.

A specific component can be selected for certain types, both in the source output and the target input, so that the connection would only affect that component (the other components can be linked independently).

For input parameters of array type, a specific element can be selected, so that the link affects only that element. Same as with components, the other array elements can be linked independently. Additionally, a specific component can be selected for the array element.

A check is made for "link-compatibility" between the source and the target of the connection, so it cannot be performed if they are not compatible. This includes resolution of array types (when using array linking) and takes into account separate component linking.

Node parameters can be explicitly flagged as non-linkable by setting the following boolean metadata:

{
...
AiMetaDataSetBool(mds, "parameter_name", "linkable", false);
}

Attempts to use AiNodeLink() / AiNodeLinkOutput() on a parameter that has been flagged as non-linkable will produce a warning but otherwise have no effect.

See Also
AiNodeLink
Parameters
srca non-NULL pointer to the source node, to be connected to the target node
outputselects one of the components (e.g "r", "g", ...), or the whole output of the source node (using "")
targeta non-NULL pointer to the target node whose input parameter will be connected to the output of the source node
inputthe input parameter specification in the target node, which can optionally include a component specification (e.g. "Kd.r", "dir.x"), an array element index (e.g. "colors[1]") or both (e.g. "colors[1].r").
Returns
true if the connection was performed successfully, false otherwise
AI_API bool AiNodeUnlink ( AtNode node,
const char *  input 
)

Removes a connection from a node input parameter.

Using this function you can disconnect, or unlink, a shader input that has been previously linked. If the specified parameter wasn't already linked, this function won't do anything.

Parameters
nodea non-NULL pointer to a node
inputthe input parameter specification in the target node, which can optionally include a component specification (e.g. "Kd.r", "dir.x"), an array element index (e.g. "colors[1]") or both (e.g. "colors[1].r").
Returns
true if the disconnection was performed successfully, false otherwise
AI_API bool AiNodeIsLinked ( const AtNode node,
const char *  input 
)

Returns true if the input parameter is linked.

It will also check for the parameter to be an array, and check if there is any array element connection, and also check for any separate component linking.

Parameters
nodenode to be queried
inputthe input parameter specification in the given node, which can optionally include a component specification (e.g. "Kd_color.r", "dir.x"), an array element index (e.g. "colors[1]") or both (e.g. "colors[1].r").
Returns
true if the input specification (or any of its components) is explicitly linked, e.g. querying for "Kd_color" will return true if either "Kd_color" or any of its R, G, or B components are linked, but querying for "Kd_color.r" will return true only if the R component has been explicitly linked)
AI_API AtNode* AiNodeGetLink ( const AtNode node,
const char *  input,
int *  comp 
)

Returns the node connected to a given node input parameter.

Parameters
nodenode to be queried
inputthe input parameter specification in the target node, which can optionally include a component specification (e.g. "Kd_color.r", "dir.x"), an array element index (e.g. "colors[1]") or both (e.g. "colors[1].r").
compif not NULL, the specific component selected on the source node output (-1 for the whole output, [0..3] for a single component) will be returned here
Returns
pointer to the connected node, or NULL if the parameter or component is not linked
AI_API const char* AiNodeGetName ( const AtNode node)

Return the node's name.

This is both faster and easier to use than the equivalent call:

AiNodeGetStr(node, "name");
Parameters
nodeinput node
Returns
the node name string, or NULL if the input node was NULL
AI_API const AtNodeEntry* AiNodeGetNodeEntry ( const AtNode node)

Return the node entry for this node.

Parameters
nodeinput node
Returns
the node entry for this node, or NULL if the input node was NULL
AI_API AtParamValue* AiNodeGetParams ( const AtNode node)

Returns an array with all parameter values.

Parameters
nodeinput node
Returns
the array of all parameter values, or NULL if the input node was NULL
AI_API void* AiNodeGetLocalData ( const AtNode node)

Returns a pointer to the local data in the node.

Parameters
nodeinput node
Returns
pointer to local data
AI_API void AiNodeSetLocalData ( AtNode node,
void *  data 
)

Sets local data pointer in the node.

This can be used to store custom data managed by the user.

Parameters
nodeinput node
datapointer to new local data
AI_API const AtUserParamEntry* AiNodeLookUpUserParameter ( const AtNode node,
const char *  param 
)

Return the user-defined parameter entry that matches a given name.

This function searches the user-defined parameter entries of a given node looking for a parameter that matches the given string. If found, returns a pointer to the parameter entry.

Parameters
nodeinput node
paramthe parameter we are looking for
Returns
handle to the user-defined parameter entry whose name matches the given string, or NULL if not found
See Also
User-Data API
AI_API AtUserParamIterator* AiNodeGetUserParamIterator ( const AtNode node)

Creates and returns a new AtUserParamIterator for this node.

Parameters
nodenode whose user parameters will be iterated over
Returns
an iterator over all user parameters on this node
AI_API void AiUserParamIteratorDestroy ( AtUserParamIterator *  iter)

Destroys a user param iterator when it is no longer needed.

Parameters
iteruser param iterator that will be deallocated
AI_API const AtUserParamEntry* AiUserParamIteratorGetNext ( AtUserParamIterator *  iter)

Returns current user param entry and points user param iterator to the next one.

This function is designed to be used inside a loop, as illustrated by the following example, which prints all the user-defined parameters of a given AtNode:

AtUserParamIterator *iter = AiNodeGetUserParamIterator(node);
{
AtUserParamEntry *upentry = AiUserParamIteratorGetNext(iter);
printf("%s\n", AiUserParamGetName(upentry));
}
Note
If this is an instance, the iterator will NOT include user parameters that were declared in the reference node, even though AiNodeLookUpUserParameter() would find such user parameters in the instance.
Parameters
itera user param iterator
Returns
the current user param entry pointed by the iterator, or NULL if there are no more user parameters to iterate over
AI_API bool AiUserParamIteratorFinished ( const AtUserParamIterator *  iter)

Returns true if there are no more user parameters to iterate over.

Parameters
itera user param iterator
Returns
true if the user param iterator has moved past the last user parameter
AI_API void AiNodeSetInt ( AtNode node,
const char *  param_name,
int  value 
)

Set the value of an integer parameter.

Parameters
nodepointer to the node
param_namename of the parameter to set
valuenew parameter value
AI_API void AiNodeSetArray ( AtNode node,
const char *  param_name,
AtArray array 
)

Set the value of an array parameter.

Note that to avoid a memory leak when setting a node's array successive times, the existing array (if any) is deallocated before it's overwritten with the new value; you don't need to call AiArrayDestroy() on the old array, and in fact doing so will probably cause a crash because of a double deallocation.

Parameters
nodepointer to the node
param_namename of the parameter to set
arraynew parameter value
AI_API void AiNodeSetAttributes ( AtNode node,
const char *  attributes 
)

Set the parameters of a node through an attributes string.

Given a node, this API can be used to set a number of its attributes in one go, as shown in the following examples:

AiNodeSetAttributes(myoptions, "threads 32");
AiNodeSetAttributes(myoptions, "GI_diffuse_samples 3 GI_diffuse_depth 1");
AiNodeSetAttributes(mylambert, "Kd 0.7\nKd_color 0.5 0.5 0.5");

This is helpful if you need to use an attribute of a newer version of the Arnold core from an old version of a host 3D application whose UI does not expose this particular attribute yet; the user could enable new or experimental features in the renderer by typing a carefully crafted string in a text field of the UI, which the host app would simply pass through to the renderer. The string is later parsed with the same exact code that is used for parsing node attributes in an .ass file.

Parameters
nodepointer to the node
attributesstring containing any number of parameter/value pairs separated by whitespace (spaces, tabs, newlines) as found in .ass files
AI_API int AiNodeGetInt ( const AtNode node,
const char *  param_name 
)

Return the value of an integer parameter.

Parameters
nodepointer to the node
param_namename of the parameter to be queried
Returns
value of parameter

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com