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 AtNode * | AiNode (const char *name) |
Create a fresh instantiation of a node. More... | |
AI_API AtNode * | AiNodeLookUpByName (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 AtNode * | AiNodeClone (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 AtNode * | AiNodeGetLink (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 AtNodeEntry * | AiNodeGetNodeEntry (const AtNode *node) |
Return the node entry for this node. More... | |
AI_API AtParamValue * | AiNodeGetParams (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 AtArray * | AiNodeGetArray (const AtNode *node, const char *param) |
AI_API void | AiNodeGetMatrix (const AtNode *node, const char *param, AtMatrix matrix) |
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:
#define AI_INSTANCE_COMMON_METHODS |
Exporter for common methods.
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.
name | name of the type of node to be created ("polymesh", etc) |
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.
name | name to look up |
AI_API void AiNodeReset | ( | AtNode * | node | ) |
Reset all node parameters to their default values and remove any input links.
node | pointer to a node to be reset (if the pointer is NULL, the function will simply return) |
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.
node | the source node to be cloned |
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.
node | pointer to an existing node, generally coming from AiNode() |
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:
node | pointer to a node whose type is to be compared |
string | the name of an existing node type |
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:
constant
, uniform
, varying
}BYTE
, INT
, BOOL
, FLOAT
, RGB
, POINT
, STRING
, etc. }The scope of the different classes is:
constant
values exist on a per-object basisuniform
values exist on a per-face basisvarying
values exist on a per-vertex basisIn 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":
node | input node |
name | name of the new parameter |
declaration | declaration string for the class and type of the new parameter |
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:
is equivalent to:
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 |
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:
Attempts to use AiNodeLink() / AiNodeLinkOutput() on a parameter that has been flagged as non-linkable will produce a warning but otherwise have no effect.
src | a non-NULL pointer to the source node, to be connected to the target node |
output | selects one of the components (e.g "r", "g", ...), or the whole output of the source node (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"). |
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.
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"). |
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.
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 the node connected to a given node input parameter.
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 |
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:
node | input node |
AI_API const AtNodeEntry* AiNodeGetNodeEntry | ( | const AtNode * | node | ) |
Return the node entry for this node.
node | input node |
AI_API AtParamValue* AiNodeGetParams | ( | const AtNode * | node | ) |
Returns an array with all parameter values.
node | input node |
AI_API void* AiNodeGetLocalData | ( | const AtNode * | node | ) |
Returns a pointer to the local data in the node.
node | input node |
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.
node | input node |
data | pointer 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.
node | input node |
param | the parameter we are looking for |
AI_API AtUserParamIterator* AiNodeGetUserParamIterator | ( | const AtNode * | node | ) |
Creates and returns a new AtUserParamIterator for this node.
node | node whose user parameters will be iterated over |
AI_API void AiUserParamIteratorDestroy | ( | AtUserParamIterator * | iter | ) |
Destroys a user param iterator when it is no longer needed.
iter | user 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:
iter | a user param iterator |
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.
iter | a user param iterator |
AI_API void AiNodeSetInt | ( | AtNode * | node, |
const char * | param_name, | ||
int | value | ||
) |
Set the value of an integer parameter.
node | pointer to the node |
param_name | name of the parameter to set |
value | new parameter value |
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.
node | pointer to the node |
param_name | name of the parameter to set |
array | new 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:
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.
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 |
AI_API int AiNodeGetInt | ( | const AtNode * | node, |
const char * | param_name | ||
) |
Return the value of an integer parameter.
node | pointer to the node |
param_name | name of the parameter to be queried |