Data Structures | Macros | Typedefs | Enumerations | Functions
Procedural API

Implementation of custom Arnold procedural nodes. More...

Data Structures

struct  AtProceduralNodeMethods
 

Macros

#define AI_PROCEDURAL_NODE_EXPORT_METHODS(tag)
 Procedural node methods exporter. More...
 
#define procedural_init   static int ProceduralInit(AtNode* node, void** user_ptr)
 
#define procedural_cleanup   static int ProceduralCleanup(const AtNode* node, void* user_ptr)
 
#define procedural_num_nodes   static int ProceduralNumNodes(const AtNode* node, void* user_ptr)
 
#define procedural_get_node   static AtNode* ProceduralGetNode(const AtNode* node, void* user_ptr, int i)
 
#define procedural_update
 
#define procedural_finish
 
#define procedural_viewport
 

Typedefs

typedef int(* AtProcInit) (AtNode *node, void **user_ptr)
 Procedural init method. More...
 
typedef int(* AtProcCleanup) (const AtNode *node, void *user_ptr)
 Procedural cleanup method. More...
 
typedef int(* AtProcNumNodes) (const AtNode *node, void *user_ptr)
 Procedural node count method. More...
 
typedef AtNode *(* AtProcGetNode) (const AtNode *node, void *user_ptr, int i)
 Procedural node fetching method. More...
 
typedef int(* AtProcViewport) (const AtNode *node, AtUniverse *universe, AtProcViewportMode mode, const AtParamValueMap *params)
 Procedural viewport representation method. More...
 
typedef int(* AtProcFuncPtr) (AtProceduralNodeMethods *methods)
 Procedural function pointer entry-point symbol. More...
 

Enumerations

enum  AtProcViewportMode { AI_PROC_BOXES = 0, AI_PROC_POINTS, AI_PROC_POLYGONS }
 Enum with the different modes available for a procedural viewport representation.
 

Functions

AI_API int AiProceduralViewport (const AtNode *node, AtUniverse *universe, AtProcViewportMode mode=AI_PROC_BOXES, const AtParamValueMap *params=NULL)
 Procedural viewport representation method. More...
 

Detailed Description

Implementation of custom Arnold procedural nodes.

This API is used to create geometry procedurally at render time, rather than upfront. This is accomplished by providing the renderer some callback functions which are called during scene initialization, before rendering. Procedural nodes should only contain geometry, shaders and lights.

Note that procedurals can recursively create other procedural nodes.

Procedurals are loaded during the pre-render initialization process. This process runs single-threaded by default, but setting "options.parallel_node_init" will make it multi-threaded.

So, in order to benefit from this parallel initialization, it is necessary that the code in a procedural node is properly designed to be re-entrant.

Macro Definition Documentation

#define AI_PROCEDURAL_NODE_EXPORT_METHODS (   tag)
Value:
AI_INSTANCE_COMMON_SHAPE_METHODS \
procedural_init; \
procedural_cleanup; \
procedural_num_nodes; \
procedural_get_node; \
static AtProceduralNodeMethods ai_proc_mtds = { \
ProceduralInit, \
ProceduralCleanup, \
ProceduralNumNodes, \
ProceduralGetNode, \
NULL, \
}; \
static AtNodeMethods ai_node_mtds = { \
&ai_common_mtds, \
&ai_proc_mtds \
}; \
const AtNodeMethods* tag = &ai_node_mtds;
Node methods.
Definition: ai_node_entry.h:83
Definition: ai_procedural.h:156

Procedural node methods exporter.

#define procedural_update
Value:
static void Update(AtNode* node); \
AI_OPTIONAL_METHOD_INSTALL(ai_common_mtds, Update) \
static void Update(AtNode* node)
This represents a node in Arnold.
#define procedural_finish
Value:
static void Finish(AtNode* node); \
AI_OPTIONAL_METHOD_INSTALL(ai_common_mtds, Finish) \
static void Finish(AtNode* node)
This represents a node in Arnold.
#define procedural_viewport
Value:
static int ProceduralViewport(const AtNode* node, AtUniverse* universe, AtProcViewportMode mode, const AtParamValueMap* params); \
AI_OPTIONAL_METHOD_INSTALL(ai_proc_mtds, ProceduralViewport) \
static int ProceduralViewport(const AtNode* node, AtUniverse* universe, AtProcViewportMode mode, const AtParamValueMap* params)
This represents a universe in Arnold.
AtProcViewportMode
Enum with the different modes available for a procedural viewport representation. ...
Definition: ai_procedural.h:121
This represents a node in Arnold.

Typedef Documentation

typedef int(* AtProcInit) (AtNode *node, void **user_ptr)

Procedural init method.

This method will be called first and should perform any initialization required by your procedural. You probably want to create new nodes inside this method but you should return them through AtProcGetNode and correctly return the number of created nodes from AtProcNumNodes, otherwise the behavior is undefined. Alternatively, if you know ahead of time exactly how many nodes you are going to create, you can create them in AtProcGetNode too.

This method may be called concurrently with other uses of the same procedural plugin, unless "options.enable_threaded_procedurals" is off.

Parameters
nodeThis is the procedural node itself
[out]user_ptrThis is a general-purpose, user-supplied data pointer that Arnold will pass along to the other procedural methods.
Returns
true upon success
typedef int(* AtProcCleanup) (const AtNode *node, void *user_ptr)

Procedural cleanup method.

This method will be called last and should perform any cleanup required by your procedural. Make sure you release any memory you allocated that is no longer needed by Arnold.

This method may be called concurrently with other uses of the same procedural plugin.

Parameters
nodeThis is the procedural node itself
user_ptrUser data pointer, as returned from AtProcInit
Returns
true upon success
typedef int(* AtProcNumNodes) (const AtNode *node, void *user_ptr)

Procedural node count method.

This method will be called after initialization and should report the exact number of nodes to be created. Alternatively, when the total number of nodes is not known beforehand, it might return -1, and then Arnold will call the AtProcGetNode method until it returns NULL to indicate no more nodes are available.

This method may be called concurrently with other uses of the same procedural plugin.

Parameters
nodeThis is the procedural node itself
user_ptrUser data pointer, as returned from AtProcInit
Returns
The number of nodes in the procedural
typedef AtNode*(* AtProcGetNode) (const AtNode *node, void *user_ptr, int i)

Procedural node fetching method.

This method will be called once for each node to be created (as determined by AtProcNumNodes). Note that if you created any node in AtProcInit, they also should be returned here, otherwise the behaviour would be undefined.

If -1 was returned by AtProcNumNodes, this method should return NULL when all nodes have been returned and there are no more available.

This method may be called concurrently with other uses of the same procedural plugin.

Parameters
nodeThis is the procedural node itself
user_ptrUser data pointer, as returned from AtProcInit
iNode index, in the range 0 to AtProcNumNodes - 1
Returns
The i'th node in the procedural
typedef int(* AtProcViewport) (const AtNode *node, AtUniverse *universe, AtProcViewportMode mode, const AtParamValueMap *params)

Procedural viewport representation method.

This method can be called to obtain a simplified representation of a procedural, made up of nodes that will be created in the given universe.

This is an example implementation for a simple custom procedural:

1 procedural_viewport
2 {
3  if (mode == AI_PROC_BOXES)
4  {
5  AtNode* bbox_node = AiNode(universe, "box", "bbox0");
6  AiNodeSetVec(bbox_node, "min", -5, -5, -5);
7  AiNodeSetVec(bbox_node, "max", 5, 5, 5);
8  }
9  return AI_SUCCESS;
10 }
Parameters
nodeThis is the procedural node itself
universeThe universe where the new nodes will be created
modeThe type of primitives used for the viewport representation
paramsList of optional parameters to be interpreted by the procedurals
Returns
AI_SUCCESS if no error, an error value otherwise
typedef int(* AtProcFuncPtr) (AtProceduralNodeMethods *methods)

Procedural function pointer entry-point symbol.

A function pointer of this type can be set in the procedural funcptr parameter.

Parameters
[out]methodsList of procedural methods (some of which are optional) to be supplied by the user
Returns
true upon success

Function Documentation

AI_API int AiProceduralViewport ( const AtNode node,
AtUniverse universe,
AtProcViewportMode  mode = AI_PROC_BOXES,
const AtParamValueMap *  params = NULL 
)

Procedural viewport representation method.

Call this method to get a simplified representation of a procedural for a DCC viewport. The nodes are created in the given universe, and mode determines the type of representation (for example, bounding boxes, points, or polygons). The optional params allows you to pass in a variable number of paramater values to the method.

This is an example of some code to get this representation from a procedural "proc":

1 // Create new universe to store the procedural representation
2 AtUniverse* view_universe = AiUniverse();
3 
4 // Obtain bounding-box representation (one box for each object in the procedural)
5 AtParamValueMap* params = AiParamValueMap();
6 AiParamValueMapSetInt(params, AtString("param"), 0); // Example parameter
7 AiProceduralViewport(proc, view_universe, AI_PROC_BOXES, params);
8 AiParamValueMapDestroy(params);
9 
10 // After that, we can iterate over those nodes and get any kind of information
11 AtNodeIterator* it = AiUniverseGetNodeIterator(view_universe, AI_NODE_SHAPE);
12 while (!AiNodeIteratorFinished(it))
13 {
14  AtNode* node = AiNodeIteratorGetNext(it);
15  printf("Node name: %s\n", AiNodeGetName(node));
16 }
17 AiNodeIteratorDestroy(it);

Optional parameters allow further configuration of the representation:

Supported optional parameters
None yet
Parameters
nodeThis is the procedural node itself
universeThe universe where the new nodes will be created
modeThe type of primitives used for the viewport representation
paramsList of optional parameters to be interpreted by the procedurals
Returns
AI_SUCCESS if no error, an error value otherwise

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