Data Structures | Macros
AtNode API

Creation, manipulation and operation with Arnold nodes. More...

Data Structures

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

Macros

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

Node Method Declarations

#define node_parameters   static void Parameters(AtList* params, AtNodeEntry* nentry)
 Parameter declaration method.
 
#define node_plugin_initialize
 Node plugin initialize method (optional) More...
 
#define node_plugin_cleanup
 Node plugin cleanup method (optional) More...
 
#define node_initialize   static void Initialize(AtNode* node)
 Node initialization method.
 
#define node_update   static void Update(AtNode* node)
 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 (AtUniverse *universe, const AtString nentry_name, const AtString name=AtString(), const AtNode *parent=NULL)
 Create a fresh instantiation of a node in a specific Arnold universe. More...
 
AI_API AI_PURE AtNodeAiNodeLookUpByName (const AtUniverse *universe, const AtString name, const AtNode *parent=NULL)
 Search for a specific node in the given universe using the specified name string (which can be a simple name, a relative path or an absolute path). More...
 
AI_API bool AiNodeDeclare (AtNode *node, const AtString param, const char *declaration)
 Declare a user-defined parameter for this node. More...
 
AI_API AI_PURE const AtUserParamEntry * AiNodeLookUpUserParameter (const AtNode *node, const AtString param)
 Return the user-defined parameter entry that matches a given name. More...
 
AI_API AI_PURE bool AiNodeIs (const AtNode *node, AtString str)
 Compare the node type against a string. More...
 
AI_API void AiNodeReset (AtNode *node)
 Reset all node parameters to their default values and remove any input links. More...
 
AI_API void AiNodeResetParameter (AtNode *node, const char *param)
 Reset a node parameter to its default value and remove any links to that parameter. More...
 
AI_API AtNodeAiNodeClone (const AtNode *node, const AtString new_name=AtString(), const AtNode *parent=NULL)
 Return an exact clone of a source node. More...
 
AI_API bool AiNodeDestroy (AtNode *node)
 Destroy an existing node. More...
 
AI_API void AiNodeReplace (AtNode *old_node, AtNode *new_node, bool remove)
 Replace an existing node with another, updating all references to that 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 AI_PURE 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 AI_PURE const char * AiNodeGetName (const AtNode *node)
 Return the node's name. More...
 
AI_API AI_PURE const AtNodeEntryAiNodeGetNodeEntry (const AtNode *node)
 Return the node entry for this node. More...
 
AI_API AI_PURE 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 AI_PURE void * AiNodeGetPluginData (const AtNode *node)
 Returns a pointer to the per plugin data for the node type, as created in the node_plugin_initialize method. More...
 
AI_API void AiNodeSetDisabled (AtNode *node, bool disabled)
 Disable or enable any node in the scene. More...
 
AI_API AI_PURE bool AiNodeIsDisabled (const AtNode *node)
 Check if a node has been disabled or not. More...
 
AI_API AI_PURE AtNodeAiNodeGetParent (const AtNode *node)
 Returns the procedural parent of a node. More...
 
AI_API AI_PURE AtUniverseAiNodeGetUniverse (const AtNode *node)
 Returns the universe a node belongs to. More...
 
AI_API AtUserParamIterator * AiNodeGetUserParamIterator (const AtNode *node)
 Creates and returns a new AtUserParamIterator for this node. More...
 
AI_DEPRECATED AtNodeAiNode (const AtString nentry_name, const AtString name=AtString(), const AtNode *parent=NULL)
 Create a fresh instantiation of a node in the default universe. More...
 
AI_DEPRECATED AtNodeAiNodeLookUpByName (const AtString name, const AtNode *parent=NULL)
 Search for a specific node in the default universe using the specified name string (which can be a simple name, a relative path or an absolute path). More...
 
AI_DEPRECATED AtNodeAiNode (AtUniverse *universe, const char *nentry_name, const char *name="", const AtNode *parent=NULL)
 
AI_DEPRECATED AtNodeAiNode (const char *nentry_name, const char *name="", const AtNode *parent=NULL)
 
AI_DEPRECATED AtNodeAiNodeLookUpByName (const AtUniverse *universe, const char *name, const AtNode *parent=NULL)
 
AI_DEPRECATED AtNodeAiNodeLookUpByName (const char *name, const AtNode *parent=NULL)
 
AI_DEPRECATED bool AiNodeDeclare (AtNode *node, const char *param, const char *declaration)
 
AI_DEPRECATED const AtUserParamEntry * AiNodeLookUpUserParameter (const AtNode *node, const char *param)
 

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 AtString param, uint8_t val)
 
AI_API void AiNodeSetInt (AtNode *node, const AtString param, int val)
 Set the value of an integer parameter. More...
 
AI_API void AiNodeSetUInt (AtNode *node, const AtString param, unsigned int val)
 
AI_API void AiNodeSetBool (AtNode *node, const AtString param, bool val)
 
AI_API void AiNodeSetFlt (AtNode *node, const AtString param, float val)
 
AI_API void AiNodeSetPtr (AtNode *node, const AtString param, void *val)
 
AI_API void AiNodeSetArray (AtNode *node, const AtString param, AtArray *val)
 Set the value of an array parameter. More...
 
AI_API void AiNodeSetMatrix (AtNode *node, const AtString param, AtMatrix val)
 
AI_API void AiNodeSetStr (AtNode *node, const AtString param, const AtString str)
 
AI_API void AiNodeSetRGB (AtNode *node, const AtString param, float r, float g, float b)
 
AI_API void AiNodeSetRGBA (AtNode *node, const AtString param, float r, float g, float b, float a)
 
AI_API void AiNodeSetVec (AtNode *node, const AtString param, float x, float y, float z)
 
AI_API void AiNodeSetVec2 (AtNode *node, const AtString param, float x, float y)
 
AI_DEPRECATED void AiNodeSetByte (AtNode *node, const char *param, uint8_t val)
 
AI_DEPRECATED void AiNodeSetInt (AtNode *node, const char *param, int val)
 
AI_DEPRECATED void AiNodeSetUInt (AtNode *node, const char *param, unsigned int val)
 
AI_DEPRECATED void AiNodeSetBool (AtNode *node, const char *param, bool val)
 
AI_DEPRECATED void AiNodeSetFlt (AtNode *node, const char *param, float val)
 
AI_DEPRECATED void AiNodeSetPtr (AtNode *node, const char *param, void *val)
 
AI_DEPRECATED void AiNodeSetArray (AtNode *node, const char *param, AtArray *val)
 
AI_DEPRECATED void AiNodeSetMatrix (AtNode *node, const char *param, AtMatrix val)
 
AI_DEPRECATED void AiNodeSetStr (AtNode *node, const char *param, const char *str)
 
AI_DEPRECATED void AiNodeSetRGB (AtNode *node, const char *param, float r, float g, float b)
 
AI_DEPRECATED void AiNodeSetRGBA (AtNode *node, const char *param, float r, float g, float b, float a)
 
AI_DEPRECATED void AiNodeSetVec (AtNode *node, const char *param, float x, float y, float z)
 
AI_DEPRECATED void AiNodeSetVec2 (AtNode *node, const char *param, float x, float y)
 
AI_API void AiNodeSetAttributes (AtNode *node, const char *attributes)
 Set the parameters of a node through an attributes string. More...
 

Parameter Readers

AI_API uint8_t AiNodeGetByte (const AtNode *node, const AtString param)
 
AI_API int AiNodeGetInt (const AtNode *node, const AtString param)
 Return the value of an integer parameter. More...
 
AI_API unsigned int AiNodeGetUInt (const AtNode *node, const AtString param)
 
AI_API bool AiNodeGetBool (const AtNode *node, const AtString param)
 
AI_API float AiNodeGetFlt (const AtNode *node, const AtString param)
 
AI_API AtRGB AiNodeGetRGB (const AtNode *node, const AtString param)
 
AI_API AtRGBA AiNodeGetRGBA (const AtNode *node, const AtString param)
 
AI_API AtVector AiNodeGetVec (const AtNode *node, const AtString param)
 
AI_API AtVector2 AiNodeGetVec2 (const AtNode *node, const AtString param)
 
AI_API AtString AiNodeGetStr (const AtNode *node, const AtString param)
 
AI_API void * AiNodeGetPtr (const AtNode *node, const AtString param)
 
AI_API AtArray * AiNodeGetArray (const AtNode *node, const AtString param)
 
AI_API AtMatrix AiNodeGetMatrix (const AtNode *node, const AtString param)
 
AI_DEPRECATED uint8_t AiNodeGetByte (const AtNode *node, const char *param)
 
AI_DEPRECATED int AiNodeGetInt (const AtNode *node, const char *param)
 
AI_DEPRECATED unsigned int AiNodeGetUInt (const AtNode *node, const char *param)
 
AI_DEPRECATED bool AiNodeGetBool (const AtNode *node, const char *param)
 
AI_DEPRECATED float AiNodeGetFlt (const AtNode *node, const char *param)
 
AI_DEPRECATED AtRGB AiNodeGetRGB (const AtNode *node, const char *param)
 
AI_DEPRECATED AtRGBA AiNodeGetRGBA (const AtNode *node, const char *param)
 
AI_DEPRECATED AtVector AiNodeGetVec (const AtNode *node, const char *param)
 
AI_DEPRECATED AtVector2 AiNodeGetVec2 (const AtNode *node, const char *param)
 
AI_DEPRECATED AtString AiNodeGetStr (const AtNode *node, const char *param)
 
AI_DEPRECATED void * AiNodeGetPtr (const AtNode *node, const char *param)
 
AI_DEPRECATED AtArray * AiNodeGetArray (const AtNode *node, const char *param)
 
AI_DEPRECATED AtMatrix AiNodeGetMatrix (const AtNode *node, const char *param)
 

Detailed Description

Creation, manipulation and operation with Arnold nodes.

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.

Optional "node_plugin_initialize{}" and "node_plugin_cleanup{}" methods can be used for initializing a plugin, if there is some initialization or data to be shared between nodes of the same type. These methods are only called if a node of this type is created. AiNodeGetPluginData() can be used to retrieve the plugin data.

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

Macro Definition Documentation

#define node_plugin_initialize
Value:
static bool PluginInitialize(void** plugin_data); \
AI_OPTIONAL_METHOD_INSTALL(ai_common_mtds, PluginInitialize) \
static bool PluginInitialize(void** plugin_data)

Node plugin initialize method (optional)

#define node_plugin_cleanup
Value:
static void PluginCleanup(void* plugin_data); \
AI_OPTIONAL_METHOD_INSTALL(ai_common_mtds, PluginCleanup) \
static void PluginCleanup(void* plugin_data)

Node plugin cleanup method (optional)

#define AI_INSTANCE_COMMON_METHODS
Value:
static AtCommonMethods ai_common_mtds = { \
NULL, \
NULL, \
Parameters, \
Initialize, \
Update, \
Finish \
};
#define node_initialize
Node initialization method.
Definition: ai_nodes.h:87
#define node_parameters
Parameter declaration method.
Definition: ai_nodes.h:71
#define node_finish
Node de-initialization method.
Definition: ai_nodes.h:95
Methods common to all nodes.
Definition: ai_node_entry.h:70
#define node_update
Node update method.
Definition: ai_nodes.h:91

Exporter for common methods.

#define AI_INSTANCE_COMMON_SHAPE_METHODS
Value:
static AtCommonMethods ai_common_mtds = { \
NULL, \
NULL, \
Parameters, \
NULL, \
NULL, \
NULL \
};
#define node_parameters
Parameter declaration method.
Definition: ai_nodes.h:71
Methods common to all nodes.
Definition: ai_node_entry.h:70

Exporter for common shape methods.

Function Documentation

AI_API AtNode* AiNode ( AtUniverse universe,
const AtString  nentry_name,
const AtString  name,
const AtNode parent 
)

Create a fresh instantiation of a node in a specific Arnold universe.

Arnold-based apps would call this function to populate a universe 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, or when a universe is explicitly destroyed.

Note
When creating a node that will be contained in a procedural node, it is CRITICAL that the proper parent procedural pointer is given through the "parent" parameter. Failure to do so will result in some issues due to incomplete node initialization.
Parameters
universeuniverse where the node is to be created (NULL for default universe)
nentry_namename of the type of node to be created ("polymesh", etc)
namename of the new node to be created
parentparent of the new node, or NULL for none (global scope)
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 AI_PURE AtNode* AiNodeLookUpByName ( const AtUniverse universe,
const AtString  name,
const AtNode parent 
)

Search for a specific node in the given universe using the specified name string (which can be a simple name, a relative path or an absolute path).

Performs a recursive search for the given name string, starting from the contents of the specified parent node, then continuing up towards the root of the scene, until the node is found. If the parent given is null, the search is performed only at the root level.

The name string could be one a simple name, a relative path (with parent names separated by '^' followed by the node name, or an absolute path, with a similar syntax to relative paths, but starting with '^'). These are some examples:

1 AiNodeLookUpByName("myshader", myprocedural);
2 AiNodeLookUpByName("materials^wood^cherry");
3 AiNodeLookUpByName("^myproc^mymesh");
Parameters
universeuniverse to search for this node (NULL for default universe)
namenode path to look up
parentif not null, search will begin within the contents of this node, then it will continue recursively up towards the root of the scene. If null, search will be limited to nodes in the root level.
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 bool AiNodeDeclare ( AtNode node,
const AtString  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":

1 AtNode *mymesh = AiNode("polymesh");
2 AiNodeDeclare(mymesh, AtString("bar"), "constant BOOL");
3 AiNodeDeclare(mymesh, AtString("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 AI_PURE const AtUserParamEntry* AiNodeLookUpUserParameter ( const AtNode node,
const AtString  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 AI_PURE bool AiNodeIs ( const AtNode node,
const AtString  string 
)

Compare the node type against a string.

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

1 if (AiNodeIs(mynode,AtString("lambert")))
2 {
3  // do something exciting that only applies to lambert nodes
4 }
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 void AiNodeReset ( AtNode node)

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

Note
If the node is a procedural, any parameter that had a explicit value was overriding the values on the children. Resetting these parameters will remove those overrides.
Parameters
nodepointer to a node to be reset (if the pointer is NULL, the function will simply return)
AI_API void AiNodeResetParameter ( AtNode node,
const char *  param 
)

Reset a node parameter to its default value and remove any links to that parameter.

Note
If you reset a declared user parameter, it will be removed and will not exist anymore. You will need to re-declare it later if you wish to use that particular user parameter.

If the node is a procedural, this parameter could have been overriding values on the nodes contained in it. This override will disappear once the parameter is reset.

Parameters
nodepointer to a node (if the pointer is NULL, the function will simply return)
paramname of the parameter to be reset to its default value
AI_API AtNode* AiNodeClone ( const AtNode node,
const AtString  new_name,
const AtNode parent 
)

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.

Note
the value of the "parent" parameter is the same as if the node was being created as new with the AiNode function. A node that will be contained in a procedural should be created with the proper parent, regardless of where the original node is coming from (root level, another procedural or even the same procedural).
Parameters
nodethe source node to be cloned
new_namethe name given to the cloned node
parentparent of the cloned node, or NULL for none (global scope)
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.

Note
This function is intended for a single node or very few nodes, created and destroyed during an interactive session. It has an overhead due to memory release and update of data structures, so don't apply this to a large number of nodes, and never to the whole scene. All nodes in the scene are released efficiently during AiEnd().
Parameters
nodepointer to an existing node, generally coming from AiNode()
Returns
true if the node was destroyed, false otherwise
AI_API void AiNodeReplace ( AtNode old_node,
AtNode new_node,
bool  remove 
)

Replace an existing node with another, updating all references to that node.

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

Parameters
old_nodepointer to an existing node, generally coming from AiNode()
new_nodepointer to an existing node, generally coming from AiNode()
removetrue if the old_node should be destroyed after replacing references
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. Everything else is the same as in AiNodeLinkOutput.

So, this:

1 AiNodeLink(source, "parameter", target);

is equivalent to:

1 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:

1 node_parameters
2 {
3  ...
4  AiMetaDataSetBool(nentry, "parameter_name", "linkable", false);
5 }

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 AI_PURE 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 AI_PURE const char* AiNodeGetName ( const AtNode node)

Return the node's name.

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

1 AiNodeGetStr(node, "name");
Parameters
nodeinput node
Returns
the node name string, or NULL if the input node was NULL
AI_API AI_PURE 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 AI_PURE 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 AI_PURE void* AiNodeGetPluginData ( const AtNode node)

Returns a pointer to the per plugin data for the node type, as created in the node_plugin_initialize method.

Parameters
nodeinput node
Returns
pointer to plugin data
AI_API void AiNodeSetDisabled ( AtNode node,
bool  disabled 
)

Disable or enable any node in the scene.

Disabled nodes won't take part in the rendering process and the resulting effect will depend on the type of node:

  • shape : it is simply excluded from the render
  • procedural : all its contained objects are excluded from render
  • shader : a disabled shader is replaced with the default shader
  • light : disabled lights are not used during rendering
Parameters
nodepointer to an existing node, generally coming from AiNode()
disabledtrue to disable this node, false otherwise
AI_API AI_PURE bool AiNodeIsDisabled ( const AtNode node)

Check if a node has been disabled or not.

Parameters
nodepointer to an existing node, generally coming from AiNode()
Returns
true if the node is disabled, false otherwise
AI_API AI_PURE AtNode* AiNodeGetParent ( const AtNode node)

Returns the procedural parent of a node.

This function returns the "procedural" geometry node that originally created the given node. See Procedural API.

Note
Although this will work in the majority of cases, it doesn't support a few corner cases, such as automatic procedural instancing as used by the procedural .ass cache, where the first procedural that was loaded will be returned.
Parameters
nodepointer to an existing node, generally coming from AiNode()
Returns
procedural parent node, or NULL if the node does not come from one
AI_API AI_PURE AtUniverse* AiNodeGetUniverse ( const AtNode node)

Returns the universe a node belongs to.

This function returns the "universe" in which the node was created.

Parameters
nodepointer to an existing node, generally coming from AiNode()
Returns
universe the node belongs to
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 AtNode * AiNode ( const AtString  nentry_name,
const AtString  name = AtString(),
const AtNode parent = NULL 
)
inline

Create a fresh instantiation of a node in the default universe.

Arnold-based apps would call this function to populate a universe 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 in the default universe at AiEnd() time prior to shutdown.

Note
When creating a node that will be contained in a procedural node, it is CRITICAL that the proper parent procedural pointer is given through the "parent" parameter. Failure to do so will result in some issues due to incomplete node initialization.
Parameters
nentry_namename of the type of node to be created ("polymesh", etc)
namename of the new node to be created
parentparent of the new node, or NULL for none (global scope)
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 AtString  name,
const AtNode parent = NULL 
)
inline

Search for a specific node in the default universe using the specified name string (which can be a simple name, a relative path or an absolute path).

Performs a recursive search for the given name string, starting from the contents of the specified parent node, then continuing up towards the root of the scene, until the node is found. If the parent given is null, the search is performed only at the root level.

The name string could be one a simple name, a relative path (with parent names separated by '^' followed by the node name, or an absolute path, with a similar syntax to relative paths, but starting with '^'). These are some examples:

1 AiNodeLookUpByName("myshader", myprocedural);
2 AiNodeLookUpByName("materials^wood^cherry");
3 AiNodeLookUpByName("^myproc^mymesh");
Parameters
namenode path to look up
parentif not null, search will begin within the contents of this node, then it will continue recursively up towards the root of the scene. If null, search will be limited to nodes in the root level.
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 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:

1 AtUserParamIterator *iter = AiNodeGetUserParamIterator(node);
2 while (!AiUserParamIteratorFinished(iter))
3 {
4  AtUserParamEntry *upentry = AiUserParamIteratorGetNext(iter);
5  printf("%s\n", AiUserParamGetName(upentry));
6 }
7 AiUserParamIteratorDestroy(iter);
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 AtString  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 AtString  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.

NOTE: The new array will be unmap'ed automatically before being set.

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:

1 AiNodeSetAttributes(myoptions, "threads 32");
2 AiNodeSetAttributes(myoptions, "GI_diffuse_samples 3 GI_diffuse_depth 1");
3 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 AtString  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

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