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 AtNode * | AiOpGetTarget (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 AtNode * | AiOpCookContextGetCookScope (AtCookContext *cook_context) |
| Get the cook scope which is represented by the node that the operator graph is connected to. More... | |
Variables | |
| AtOpInit | AtOperatorNodeMethods::Init |
| AtOpCleanup | AtOperatorNodeMethods::Cleanup |
| AtOpCook | AtOperatorNodeMethods::Cook |
| AtOpPostCook | AtOperatorNodeMethods::PostCook |
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.
| #define AI_OPERATOR_COMMON_NODE_METHODS |
Exporter for the methods shared with the standard node interface.
| #define AI_OPERATOR_NODE_EXPORT_METHODS | ( | tag | ) |
| #define AI_OPERATOR_NODE_INTERNAL_METHODS | ( | tag | ) |
| 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.
| op | operator node (itself) |
| user_data | general-purpose, user-supplied data pointer that Arnold will pass along to the other operator methods |
| 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.
| op | operator node (itself) |
| user_data | general-purpose, user-supplied data pointer as returned from AtOpInit. |
| 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.
| node | node being cooked |
| op | operator node (itself) |
| child_data | general-purpose data pointer that may be passed here by the operator's creator |
| user_data | general-purpose, user-supplied data pointer as returned from AtOpInit. |
| matching_params | names of parameters that matched the selection expression |
| cook_context | context specific information about the cook (see e.g. AtOpCookContextGetCookReference) |
| 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.
| op | operator node (itself) |
| user_data | general-purpose, user-supplied data pointer as returned from AtOpInit. |
| typedef int(* AtOpFuncPtr) (AtOperatorNodeMethods *methods) |
Operator function pointer entry-point symbol.
| [out] | methods | List of operator methods |
| AI_API bool AiOpSetTarget | ( | AtUniverse * | universe, |
| AtNode * | node | ||
| ) |
Set the target operator in a given Arnold universe.
| universe | universe where the target operator is set (NULL for default universe) |
| node | pointer 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.
| universe | universe to get the target operator from (NULL for default universe) |
| AI_API AtArray * AiOpGetInputs | ( | AtNode * | op | ) |
Get operator nodes connected to the inputs on a given operator node.
| op | operator node |
Connect an operator to a given input index on an operator.
| from | operator node whose output connects to an input on the 'to' operator |
| to | operator node whose input is connected to |
| index | input index if defined, otherwise a new input is appended |
| AI_API bool AiOpUnlinkInputByIndex | ( | AtNode * | op, |
| unsigned int | index | ||
| ) |
Unlink an input connection on an operator for a given index.
| op | operator node |
| index | input index to unlink |
Unlink connected operators.
| from | operator node whose output connects to an input on the 'to' operator |
| to | operator node whose input is connected to |
| 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.
| op | operator node receiving the child data |
| child_data | data that should be passed to the operator |
| AtOpCleanupChildData | function 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.
| node | node that is matched against a selection |
| selection | selection expression used to match |
| relative | if true the selection is assumed to be relative to the node's parent, if any |
| target | optional target operator node |
| 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.