AtNode API

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

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

AtNode Methods
AI_API AtNode *	AiNode (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 AtNode *	AiNodeLookUpByName (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 AtNode *	AiNodeClone (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 AtNode *	AiNodeGetLink (const AtNode *node, const char *input, int *comp=NULL)
	Returns the node connected to a given node input parameter. More...
AI_API AtNode *	AiNodeGetLinkOutput (const AtNode *node, const char *input, int &output_param, int &output_comp)
	Returns the node, node output, and output component 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 AtNodeEntry *	AiNodeGetNodeEntry (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 AtNode *	AiNodeGetParent (const AtNode *node)
	Returns the procedural parent of a node. More...
AI_API AI_PURE AtUniverse *	AiNodeGetUniverse (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 AtNode *	AiNode (AtUniverse *universe, const char *nentry_name, const char *name="", const AtNode *parent=NULL)
AI_DEPRECATED AtNode *	AiNodeLookUpByName (const AtUniverse *universe, 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)
#define	AiNodeDeclareGPULocalData(type)   namespace {}

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(AtRenderSession* render_session, AtNode* node)
	Node initialization method. More...
#define	node_update   static void Update(AtRenderSession* render_session, AtNode* node)
	Node update method. More...
#define	node_finish   static void Finish(AtNode* node)
	Node de-initialization method. More...
#define	node_loader   AI_EXPORT_LIB bool NodeLoader(int i, AtNodeLib* node)
	Node loading method (for plugin nodes in dynamic libraries)
#define	AI_INSTANCE_COMMON_METHODS
	Exporter for common methods. More...
#define	AI_INSTANCE_COMMON_SHAPE_METHODS
	Exporter for common shape methods. More...

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:

• AtNodeEntry – this contains the "description" of a particular node type ("polymesh", "persp_camera", etc.)
• AtNode – this contains the "instantiation" of a particular node type

Macro Definition Documentation

node_plugin_initialize

#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)

node_plugin_cleanup

#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)

node_initialize

#define node_initialize   static void Initialize(AtRenderSession* render_session, AtNode* node)

Node initialization method.

This function can be used to allocate and/or initialize any data required by the node during rendering. Those allocations should be released in node_finish.

This function is called once when the scene is initialized, and will only be called again if the node is interactively reloaded.

An example could be allocating space for matrices, lookup tables or any kind of cached values that only needs to happen once.

Parameters

render_session	render session where this node will be used for rendering
node	pointer to the node

node_update

#define node_update   static void Update(AtRenderSession* render_session, AtNode* node)

Node update method.

Unlike the node_initialize function, which usually is called just once, this will be called every time a render pass is executed. This is where data derived from modifiable node parameters should be precomputed for later use during rendering. Computation that only needs to happen once should be moved to node_initialization so that there is less overhead during IPR.

Parameters

render_session	render session where this node will be used for rendering
node	pointer to the node

node_finish

#define node_finish   static void Finish(AtNode* node)

Node de-initialization method.

This function is used to revert the actions performed in node_initialize, such as releasing memory allocated by node_init and bringing the node back to its initial state.

This is called when a node is destroyed, and when it is reverted to its initial value, which could happen when interactively modifying a value for a parameter that has the _triggers_reinitialize metadata set.

Parameters

node	pointer to the node

AI_INSTANCE_COMMON_METHODS

#define AI_INSTANCE_COMMON_METHODS

Value:

node_parameters;                           \
node_initialize;                           \
node_update;                               \
node_finish;                               \
static AtCommonMethods ai_common_mtds = {  \
   NULL,                                   \
   NULL,                                   \
   Parameters,                             \
   Initialize,                             \
   Update,                                 \
   Finish                                  \
};

Exporter for common methods.

AI_INSTANCE_COMMON_SHAPE_METHODS

#define AI_INSTANCE_COMMON_SHAPE_METHODS

Value:

node_parameters;                           \
static AtCommonMethods ai_common_mtds = {  \
   NULL,                                   \
   NULL,                                   \
   Parameters,                             \
   NULL,                                   \
   NULL,                                   \
   NULL                                    \
};

Exporter for common shape methods.

Function Documentation

AiNode()

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

universe	universe where the node is to be created (NULL for default universe)
nentry_name	name of the type of node to be created ("polymesh", etc)
name	name of the new node to be created
parent	parent 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)

AiNodeLookUpByName()

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:

AiNodeLookUpByName("myshader", myprocedural);
AiNodeLookUpByName("materials^wood^cherry");
AiNodeLookUpByName("^myproc^mymesh");

Parameters

universe	universe to search for this node (NULL for default universe)
name	node path to look up
parent	if 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

AiNodeDeclare()

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

AtNode *mymesh = AiNode("polymesh");
AiNodeDeclare(mymesh, AtString("bar"), "constant BOOL");
AiNodeDeclare(mymesh, AtString("heatmap"), "constant ARRAY RGB");

Parameters

node	input node
name	name of the new parameter
declaration	declaration 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

AiNodeLookUpUserParameter()

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

node	input node
param	the 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

AiNodeIs()

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:

if (AiNodeIs(mynode,AtString("lambert")))
{
   // do something exciting that only applies to lambert nodes
}

Parameters

node	pointer to a node whose type is to be compared
string	the name of an existing node type

Returns

true if the node type's name matches the given string

AiNodeReset()

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

node	pointer to a node to be reset (if the pointer is NULL, the function will simply return)

AiNodeResetParameter()

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.

\node 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

node	pointer to a node (if the pointer is NULL, the function will simply return)
param	name of the parameter to be reset to its default value

AiNodeClone()

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

node	the source node to be cloned
new_name	the name given to the cloned node
parent	parent 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)

AiNodeDestroy()

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

node	pointer to an existing node, generally coming from AiNode()

Returns

true if the node was destroyed, false otherwise

AiNodeReplace()

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_node	pointer to an existing node, generally coming from AiNode()
new_node	pointer to an existing node, generally coming from AiNode()
remove	true if the old_node should be destroyed after replacing references

AiNodeLink()

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 default output of the source shader is used. It maintains the previous API for linking. Everything else is the same as in AiNodeLinkOutput.

So, this:

AiNodeLink(source, "parameter", target);

is equivalent to:

AiNodeLinkOutput(source, "", target, "parameter");

See also

AiNodeLinkOutput

Parameters

src	a non-NULL pointer to the source node, to be connected to the target node
input	the 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").
target	a 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

AiNodeLinkOutput()

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

node_parameters
{
   ...
   AiMetaDataSetBool(nentry, "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

src	a non-NULL pointer to the source node, to be connected to the target node
output	a selection of a specific node output (e.g "output_A", "output_B", ...), a specific component of the default output (e.g "r", "g", ...), a specific component of a specific output (e.g "output_A.g", "output_B.z", ...), or the full default node output when left unspecified (using "")
target	a non-NULL pointer to the target node whose input parameter will be connected to the output of the source node
input	the 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

AiNodeUnlink()

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

node	a non-NULL pointer to a node
input	the 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

AiNodeIsLinked()

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

node	node to be queried
input	the 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)

AiNodeGetLink()

AI_API AtNode * AiNodeGetLink	(	const AtNode *	node,
		const char *	input,
		int *	comp
	)

Returns the node connected to a given node input parameter.

Parameters

node	node to be queried
input	the 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").
comp	if 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

AiNodeGetLinkOutput()

AI_API AtNode * AiNodeGetLinkOutput	(	const AtNode *	node,
		const char *	input,
		int &	output_param,
		int &	output_comp
	)

Returns the node, node output, and output component connected to a given node input parameter.

Parameters

node	node to be queried
input	the 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").
output_param	the index of the output parameter to which the input is linked (-1 for the default node output, 0 or greater otherwise) will be returned here, undefined when function returns NULL
output_comp	the index of the output parameter components to which the input is linked (-1 for the whole output, [0..3] for a single component) will be returned here, undefined when function returns NULL

Returns

pointer to the connected node, or NULL if the parameter or component is not linked

AiNodeGetName()

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:

AiNodeGetStr(node, "name");

Parameters

node	input node

Returns

the node name string, or NULL if the input node was NULL

AiNodeGetNodeEntry()

AI_API AI_PURE const AtNodeEntry * AiNodeGetNodeEntry

(

const AtNode *

node

)

Return the node entry for this node.

Parameters

node	input node

Returns

the node entry for this node, or NULL if the input node was NULL

AiNodeGetLocalData()

AI_API AI_PURE void * AiNodeGetLocalData

(

const AtNode *

node

)

Returns a pointer to the local data in the node.

Parameters

node	input node

Returns

pointer to local data

AiNodeSetLocalData()

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

node	input node
data	pointer to new local data

AiNodeGetPluginData()

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

node	input node

Returns

pointer to plugin data

AiNodeSetDisabled()

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

node	pointer to an existing node, generally coming from AiNode()
disabled	true to disable this node, false otherwise

AiNodeIsDisabled()

AI_API AI_PURE bool AiNodeIsDisabled

(

const AtNode *

node

)

Check if a node has been disabled or not.

Parameters

node	pointer to an existing node, generally coming from AiNode()

Returns

true if the node is disabled, false otherwise

AiNodeGetParent()

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

node	pointer to an existing node, generally coming from AiNode()

Returns

procedural parent node, or NULL if the node does not come from one

AiNodeGetUniverse()

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

node	pointer to an existing node, generally coming from AiNode()

Returns

universe the node belongs to

AiNodeGetUserParamIterator()

AI_API AtUserParamIterator * AiNodeGetUserParamIterator

(

const AtNode *

node

)

Creates and returns a new AtUserParamIterator for this node.

Parameters

node	node whose user parameters will be iterated over

Returns

an iterator over all user parameters on this node

AiUserParamIteratorDestroy()

AI_API void AiUserParamIteratorDestroy

(

AtUserParamIterator *

iter

)

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

Parameters

iter	user param iterator that will be deallocated

AiUserParamIteratorGetNext()

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);
while (!AiUserParamIteratorFinished(iter))
{
   AtUserParamEntry *upentry = AiUserParamIteratorGetNext(iter);
   printf("%s\n", AiUserParamGetName(upentry));
}
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

iter	a 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

AiUserParamIteratorFinished()

AI_API bool AiUserParamIteratorFinished

(

const AtUserParamIterator *

iter

)

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

Parameters

iter	a user param iterator

Returns

true if the user param iterator has moved past the last user parameter

AiNodeSetInt()

AI_API void AiNodeSetInt	(	AtNode *	node,
		const AtString	param_name,
		int	value
	)

Set the value of an integer parameter.

Parameters

node	pointer to the node
param_name	name of the parameter to set
value	new parameter value

AiNodeSetArray()

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

node	pointer to the node
param_name	name of the parameter to set
array	new parameter value

AiNodeSetAttributes()

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

node	pointer to the node
attributes	string containing any number of parameter/value pairs separated by whitespace (spaces, tabs, newlines) as found in .ass files

AiNodeGetInt()

AI_API int AiNodeGetInt	(	const AtNode *	node,
		const AtString	param_name
	)

Return the value of an integer parameter.

Parameters

node	pointer to the node
param_name	name of the parameter to be queried

Returns

value of parameter