Data Structures | Macros | Typedefs | Functions
Operator API

Operator node creation and operation. More...

Data Structures

struct  AtOperatorNodeMethods
 Cleanup method for child data which is passed to other operators. More...
 

Macros

#define AI_OPERATOR_COMMON_NODE_METHODS
 Exporter for the methods shared with the standard node interface. More...
 
#define AI_OPERATOR_NODE_EXPORT_METHODS(tag)
 
#define AI_OPERATOR_NODE_INTERNAL_METHODS(tag)
 
#define operator_init   static bool OperatorInit(AtNode* op, void** user_data)
 
#define operator_cleanup   static bool OperatorCleanup(AtNode* op, void* user_data)
 
#define operator_cook   static bool OperatorCook(AtNode* node, AtNode* op, void* child_data, void* user_data, const AtArray* matching_params, AtCookContext* cook_context)
 
#define operator_post_cook   static bool OperatorPostCook(AtNode* op, void* user_data)
 

Typedefs

typedef bool(* AtOpCleanupChildData) (void *child_data)
 
typedef bool(* AtOpInit) (AtNode *op, void **user_data)
 Operator init method. More...
 
typedef bool(* AtOpCleanup) (AtNode *op, void *user_data)
 Operator cleanup method. More...
 
typedef bool(* AtOpCook) (AtNode *node, AtNode *op, void *child_data, void *user_data, const AtArray *matching_params, AtCookContext *cook_context)
 Operator cook method which operates on the cooked node. More...
 
typedef bool(* AtOpPostCook) (AtNode *op, void *user_data)
 Operator post cook method which is called once per operator instance after all the cook calls for all operators are finished. More...
 
typedef int(* AtOpFuncPtr) (AtOperatorNodeMethods *methods)
 Operator function pointer entry-point symbol. More...
 

Functions

AI_API bool AiOpSetTarget (AtUniverse *universe, AtNode *node)
 Set the target operator in a given Arnold universe. More...
 
AI_API AtNodeAiOpGetTarget (const AtUniverse *universe)
 Get the target operator node in a given universe, if any. More...
 
AI_API AtArray * AiOpGetInputs (AtNode *op)
 Get operator nodes connected to the inputs on a given operator node. More...
 
AI_API bool AiOpLink (AtNode *from, AtNode *to, int index=-1)
 Connect an operator to a given input index on an operator. More...
 
AI_API bool AiOpUnlinkInputByIndex (AtNode *to, unsigned int index)
 Unlink an input connection on an operator for a given index. More...
 
AI_API bool AiOpUnlink (AtNode *from, AtNode *to)
 Unlink connected operators. More...
 
AI_API void AiOpSetChildData (AtNode *op, void *child_data=NULL, AtOpCleanupChildData cleanup=NULL)
 Set child data on an operator. More...
 
AI_API bool AiOpMatchNodeSelection (AtNode *node, AtString selection, bool relative=true, AtNode *target=NULL)
 Check if a node, including its name and parameters, match a given selection expression. More...
 
AI_API AtNodeAiOpCookContextGetCookScope (AtCookContext *cook_context)
 Get the cook scope which is represented by the node that the operator graph is connected to. More...
 

Detailed Description

Operator node creation and operation.

This API is used to create graphs of operator nodes which can procedurally perform scene inspection, creation, and late binding modifications at render time.

The operator graph defines a non-destructive set of operations, where the graph is evaluated from a given node in the graph, denoted as target operator. The target operator is defined in the options and can be set using AiOpSetTarget. Any graphs not connected to the target operator will be ignored.

An operator that is connected to the target will be initialized and cooked if it needs to do any work. That is determined based on the presence of a selection parameter and if the operator is enabled. An enabled operator without a selection will always be initialized and cooked at least once, otherwise it's only initialized and cooked if the selection expression matches one or more nodes in the scene.

Operators can recursively create other operator nodes and optionally pass child data to them (see AiOpSetChildData. Operators can also declare their own user data, where it is initialized/used in AtOpInit, used in AtOpCook, and deleted in AtOpCleanup. Note that no information flows through the graph.

Operators are evaluated during the pre-render initialization process which is done in parallel. It is therefore important that the code in an operator node is designed to be re-entrant.

Macro Definition Documentation

#define AI_OPERATOR_COMMON_NODE_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 the methods shared with the standard node interface.

#define AI_OPERATOR_NODE_EXPORT_METHODS (   tag)
Value:
AI_OPERATOR_COMMON_NODE_METHODS \
operator_init; \
operator_cleanup; \
operator_cook; \
operator_post_cook; \
static AtOperatorNodeMethods ai_op_mtds = { \
OperatorInit, \
OperatorCleanup, \
OperatorCook, \
OperatorPostCook \
}; \
static AtNodeMethods ai_node_mtds = { \
&ai_common_mtds, \
&ai_op_mtds \
}; \
const AtNodeMethods* tag = &ai_node_mtds;
Cleanup method for child data which is passed to other operators.
Definition: ai_operator.h:162
Node methods.
Definition: ai_node_entry.h:83
#define AI_OPERATOR_NODE_INTERNAL_METHODS (   tag)
Value:
AI_INSTANCE_COMMON_METHODS \
static AtNodeMethods ai_node_internal_mtds = { \
&ai_common_mtds, \
NULL \
}; \
const AtNodeMethods* tag = &ai_node_internal_mtds;
Node methods.
Definition: ai_node_entry.h:83

Typedef Documentation

typedef bool(* AtOpInit) (AtNode *op, void **user_data)

Operator init method.

This method will be called first if the operator needs to do any work to perform any initialization required by the operator.

The operator is only initialized once in a batch session but in an IPR session this method is called every time the operator is dirtied. This method may be called concurrently with other uses of the same operator plugin.

Parameters
opoperator node (itself)
user_datageneral-purpose, user-supplied data pointer that Arnold will pass along to the other operator methods
Returns
true if successful, false otherwise
typedef bool(* AtOpCleanup) (AtNode *op, void *user_data)

Operator cleanup method.

This method is called if the operator node is deleted or if the render session has finished, where it should perform any cleanup required by the operator. Make sure to release any memory you allocated that is no longer needed by Arnold.

Parameters
opoperator node (itself)
user_datageneral-purpose, user-supplied data pointer as returned from AtOpInit.
Returns
true if successful, false otherwise
typedef bool(* AtOpCook) (AtNode *node, AtNode *op, void *child_data, void *user_data, const AtArray *matching_params, AtCookContext *cook_context)

Operator cook method which operates on the cooked node.

The cooked node is either the operator itself (no selection parameter), or any node in the scene which matches the selection expression.

Therefore, this method is called one or more times if the operator needs to do any work, depending on how many nodes it has to operate on. The operator may cook multiple nodes concurrently.

This method may have access to user data and child data when cooking. The user data is a general-purpose pointer that is used by this operator and is initialized and cleaned up as part of the operator's life cycle. The child data is a general-purpose pointer that can be passed to an operator after creating it, where the cleanup method provided is called when the child data is cleaned up (see AtOpCleanupChildData).

Selection expressions support wildcards when matching parameter names and selections can match multiple parameters. The matched parameter names are accessible to allow customizing the operator's behavior based on the matched parameters.

Parameters
nodenode being cooked
opoperator node (itself)
child_datageneral-purpose data pointer that may be passed here by the operator's creator
user_datageneral-purpose, user-supplied data pointer as returned from AtOpInit.
matching_paramsnames of parameters that matched the selection expression
cook_contextcontext specific information about the cook (see e.g. AtOpCookContextGetCookReference)
Returns
true if successful, false otherwise
typedef bool(* AtOpPostCook) (AtNode *op, void *user_data)

Operator post cook method which is called once per operator instance after all the cook calls for all operators are finished.

The method is only called if an operator was cooked by being part of a graph that was connected to the options or a procedural.

Parameters
opoperator node (itself)
user_datageneral-purpose, user-supplied data pointer as returned from AtOpInit.
Returns
true if successful, false otherwise
typedef int(* AtOpFuncPtr) (AtOperatorNodeMethods *methods)

Operator function pointer entry-point symbol.

Parameters
[out]methodsList of operator methods
Returns
true upon success

Function Documentation

AI_API bool AiOpSetTarget ( AtUniverse universe,
AtNode node 
)

Set the target operator in a given Arnold universe.

Parameters
universeuniverse where the target operator is set (NULL for default universe)
nodepointer to the node used as a target operator
AI_API AtNode* AiOpGetTarget ( const AtUniverse universe)

Get the target operator node in a given universe, if any.

Parameters
universeuniverse to get the target operator from (NULL for default universe)
Returns
pointer to the target operator node if it's defined, NULL otherwise
AI_API AtArray* AiOpGetInputs ( AtNode op)

Get operator nodes connected to the inputs on a given operator node.

Parameters
opoperator node
Returns
array of operator nodes which are connected as inputs on the operator node
AI_API bool AiOpLink ( AtNode from,
AtNode to,
int  index 
)

Connect an operator to a given input index on an operator.

Parameters
fromoperator node whose output connects to an input on the 'to' operator
tooperator node whose input is connected to
indexinput index if defined, otherwise a new input is appended
Returns
true if the operator nodes were successfully linked, false otherwise
AI_API bool AiOpUnlinkInputByIndex ( AtNode op,
unsigned int  index 
)

Unlink an input connection on an operator for a given index.

Parameters
opoperator node
indexinput index to unlink
Returns
true if the connection was successfully unlinked, false otherwise
AI_API bool AiOpUnlink ( AtNode from,
AtNode to 
)

Unlink connected operators.

Parameters
fromoperator node whose output connects to an input on the 'to' operator
tooperator node whose input is connected to
Returns
true if the connection was successfully unlinked, false otherwise
AI_API void AiOpSetChildData ( AtNode op,
void *  child_data,
AtOpCleanupChildData  cleanup 
)

Set child data on an operator.

This is typically done when an operator creates another operator and wants to pass certain information to it. The lifetime of the operator that created the data might differ from the child data so a corresponding cleanup function for the data is required.

Parameters
opoperator node receiving the child data
child_datadata that should be passed to the operator
AtOpCleanupChildDatafunction pointer to clean up the child data
AI_API bool AiOpMatchNodeSelection ( AtNode node,
AtString  selection,
bool  relative,
AtNode target 
)

Check if a node, including its name and parameters, match a given selection expression.

If a target operator node is specified then the operator and any upstream operators are processed when aggregating relevant graph information used for matching such as collections.

Parameters
nodenode that is matched against a selection
selectionselection expression used to match
relativeif true the selection is assumed to be relative to the node's parent, if any
targetoptional target operator node
Returns
true if the node matches the selection expression, false otherwise
AI_API AtNode* AiOpCookContextGetCookScope ( AtCookContext *  cook_context)

Get the cook scope which is represented by the node that the operator graph is connected to.

If the operator is cooked as part of a graph that is connected to the options node then the scope is global and this function returns null. However, if the operator graph is connected to a procedural then the scope is locally relative to it, where the procedural node is returned.

This allows an operator to behave differently depending on what the expected scope is, which is determined by what graph the operator find itself in. The same operator instance can be used by different graphs, where each graph can be connected to different nodes which have an operator input. Therefore, the scope for the an operator instance can vary between cooks.

Returns
the node that the current cook scope is relative to, null if the scope is global

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