Houdini Engine 7.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Nodes

Functions

HAPI_DECL HAPI_IsNodeValid (const HAPI_Session *session, HAPI_NodeId node_id, int unique_node_id, HAPI_Bool *answer)
 Determine if your instance of the node actually still exists inside the Houdini scene. This is what can be used to determine when the Houdini scene needs to be re-populated using the host application's instances of the nodes. Note that this function will ALWAYS return HAPI_RESULT_SUCCESS. More...
 
HAPI_DECL HAPI_GetNodeInfo (const HAPI_Session *session, HAPI_NodeId node_id, HAPI_NodeInfo *node_info)
 Fill an HAPI_NodeInfo struct. More...
 
HAPI_DECL HAPI_GetNodePath (const HAPI_Session *session, HAPI_NodeId node_id, HAPI_NodeId relative_to_node_id, HAPI_StringHandle *path)
 Get the node absolute path in the Houdini node network or a relative path any other node. More...
 
HAPI_DECL HAPI_GetManagerNodeId (const HAPI_Session *session, HAPI_NodeType node_type, HAPI_NodeId *node_id)
 Get the root node of a particular network type (ie. OBJ). More...
 
HAPI_DECL HAPI_ComposeChildNodeList (const HAPI_Session *session, HAPI_NodeId parent_node_id, HAPI_NodeTypeBits node_type_filter, HAPI_NodeFlagsBits node_flags_filter, HAPI_Bool recursive, int *count)
 Compose a list of child nodes based on given filters. More...
 
HAPI_DECL HAPI_GetComposedChildNodeList (const HAPI_Session *session, HAPI_NodeId parent_node_id, HAPI_NodeId *child_node_ids_array, int count)
 Get the composed list of child node ids from the previous call to HAPI_ComposeChildNodeList(). More...
 
HAPI_DECL HAPI_CreateNode (const HAPI_Session *session, HAPI_NodeId parent_node_id, const char *operator_name, const char *node_label, HAPI_Bool cook_on_creation, HAPI_NodeId *new_node_id)
 Create a node inside a node network. Nodes created this way will have their HAPI_NodeInfo::createdPostAssetLoad set to true. More...
 
HAPI_DECL HAPI_CreateInputNode (const HAPI_Session *session, HAPI_NodeId parent_node_id, HAPI_NodeId *node_id, const char *name)
 Creates a simple geometry SOP node that can accept geometry input. Inside the specified parent node, this will create a Null SOP you can set the geometry of using the geometry SET APIs. You can then connect this node to any other node as a geometry input. More...
 
HAPI_DECL HAPI_CookNode (const HAPI_Session *session, HAPI_NodeId node_id, const HAPI_CookOptions *cook_options)
 Initiate a cook on this node. Note that this may trigger cooks on other nodes if they are connected. More...
 
HAPI_DECL HAPI_DeleteNode (const HAPI_Session *session, HAPI_NodeId node_id)
 Delete a node from a node network. Only nodes with their HAPI_NodeInfo::createdPostAssetLoad set to true can be deleted this way. More...
 
HAPI_DECL HAPI_RenameNode (const HAPI_Session *session, HAPI_NodeId node_id, const char *new_name)
 Rename a node that you created. Only nodes with their HAPI_NodeInfo::createdPostAssetLoad set to true can be renamed this way. More...
 
HAPI_DECL HAPI_ConnectNodeInput (const HAPI_Session *session, HAPI_NodeId node_id, int input_index, HAPI_NodeId node_id_to_connect, int output_index)
 Connect two nodes together. More...
 
HAPI_DECL HAPI_DisconnectNodeInput (const HAPI_Session *session, HAPI_NodeId node_id, int input_index)
 Disconnect a node input. More...
 
HAPI_DECL HAPI_QueryNodeInput (const HAPI_Session *session, HAPI_NodeId node_to_query, int input_index, HAPI_NodeId *connected_node_id)
 Query which node is connected to another node's input. More...
 
HAPI_DECL HAPI_GetNodeInputName (const HAPI_Session *session, HAPI_NodeId node_id, int input_idx, HAPI_StringHandle *name)
 Get the name of an node's input. This function will return a string handle for the name which will be valid (persist) until the next call to this function. More...
 
HAPI_DECL HAPI_DisconnectNodeOutputsAt (const HAPI_Session *session, HAPI_NodeId node_id, int output_index)
 Disconnect all of the node's output connections at the output index. More...
 
HAPI_DECL HAPI_QueryNodeOutputConnectedCount (const HAPI_Session *session, HAPI_NodeId node_id, int output_idx, HAPI_Bool into_subnets, HAPI_Bool through_dots, int *connected_count)
 Get the number of nodes currently connected to the given node at the output index. More...
 
HAPI_DECL HAPI_QueryNodeOutputConnectedNodes (const HAPI_Session *session, HAPI_NodeId node_id, int output_idx, HAPI_Bool into_subnets, HAPI_Bool through_dots, HAPI_NodeId *connected_node_ids_array, int start, int length)
 Get the ids of nodes currently connected to the given node at the output index. More...
 
HAPI_DECL HAPI_GetNodeOutputName (const HAPI_Session *session, HAPI_NodeId node_id, int output_idx, HAPI_StringHandle *name)
 Get the name of an node's output. This function will return a string handle for the name which will be valid (persist) until the next call to this function. More...
 
HAPI_DECL HAPI_GetNodeFromPath (const HAPI_Session *session, const HAPI_NodeId parent_node_id, const char *path, HAPI_NodeId *node_id)
 Get the id of the node with the specified path. More...
 
HAPI_DECL HAPI_GetOutputNodeId (const HAPI_Session *session, HAPI_NodeId node_id, int output, HAPI_NodeId *output_node_id)
 Gets the node id of an output node in a SOP network. More...
 
HAPI_DECL HAPI_SetNodeDisplay (const HAPI_Session *session, HAPI_NodeId node_id, int onOff)
 Set the specified node's display flag. More...
 
HAPI_DECL HAPI_GetTotalCookCount (const HAPI_Session *session, HAPI_NodeId node_id, HAPI_NodeTypeBits node_type_filter, HAPI_NodeFlagsBits node_flags_filter, HAPI_Bool recursive, int *count)
 Get the specified node's total cook count, including its children, if specified. More...
 

Detailed Description

Functions for working with nodes

Function Documentation

HAPI_DECL HAPI_ComposeChildNodeList ( const HAPI_Session session,
HAPI_NodeId  parent_node_id,
HAPI_NodeTypeBits  node_type_filter,
HAPI_NodeFlagsBits  node_flags_filter,
HAPI_Bool  recursive,
int *  count 
)

Compose a list of child nodes based on given filters.

This function will only compose the list of child nodes. It will not return this list. After your call to this function, call HAPI_GetComposedChildNodeList() to get the list of child node ids.

Note: When looking for all Display SOP nodes using this function, and using recursive mode, the recursion will stop as soon as a display SOP is found within each OBJ geometry network. It is almost never useful to get a list of ALL display SOP nodes recursively as they would all containt the same geometry. Even so, this special case only comes up if the display SOP itself is a subnet.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]parent_node_idThe node id of the parent node.
[in]node_type_filterThe node type by which to filter the children.
[in]node_flags_filterThe node flags by which to filter the children.
[in]recursiveWhether or not to compose the list recursively.
[out]countThe number of child nodes composed. Use this as the argument to HAPI_GetComposedChildNodeList().
HAPI_DECL HAPI_ConnectNodeInput ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  input_index,
HAPI_NodeId  node_id_to_connect,
int  output_index 
)

Connect two nodes together.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node whom's input to connect to.
[in]input_indexThe input index. Should be between 0 and the to_node's HAPI_NodeInfo::inputCount - 1.
[in]node_id_to_connectThe node to connect to node_id's input.
[in]output_indexThe output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
HAPI_DECL HAPI_CookNode ( const HAPI_Session session,
HAPI_NodeId  node_id,
const HAPI_CookOptions cook_options 
)

Initiate a cook on this node. Note that this may trigger cooks on other nodes if they are connected.

Note
In threaded mode, this is an async call!

This API will invoke the cooking thread if threading is enabled. This means it will return immediately. Use the status and cooking count APIs under DIAGNOSTICS to get a sense of the progress. All other API calls will block until the cook operation has finished.

Also note that the cook result won't be of type HAPI_STATUS_CALL_RESULT like all calls (including this one). Whenever the threading cook is done it will fill the cook result which is queried using HAPI_STATUS_COOK_RESULT.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]cook_optionsThe cook options. Pass in NULL to use the global cook options that you specified when calling HAPI_Initialize().
HAPI_DECL HAPI_CreateInputNode ( const HAPI_Session session,
HAPI_NodeId  parent_node_id,
HAPI_NodeId node_id,
const char *  name 
)

Creates a simple geometry SOP node that can accept geometry input. Inside the specified parent node, this will create a Null SOP you can set the geometry of using the geometry SET APIs. You can then connect this node to any other node as a geometry input.

Note that when saving the Houdini scene using HAPI_SaveHIPFile() the nodes created with this method will be green and will start with the name "input".

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]parent_node_idThe node id of the parent OBJ node or SOP subnetwork node in which the input node should be created, or -1 to create a new dummy parent OBJ node for this input node.
[out]node_idNewly created node's id. Use HAPI_GetNodeInfo() to get more information about the node.
[in]nameGive this input node a name for easy debugging. The node's parent OBJ node and the Null SOP node will both get this given name with "input_" prepended. You can also pass NULL in which case the name will be "input#" where # is some number.
HAPI_DECL HAPI_CreateNode ( const HAPI_Session session,
HAPI_NodeId  parent_node_id,
const char *  operator_name,
const char *  node_label,
HAPI_Bool  cook_on_creation,
HAPI_NodeId new_node_id 
)

Create a node inside a node network. Nodes created this way will have their HAPI_NodeInfo::createdPostAssetLoad set to true.

Note
In threaded mode, this is an async call!
This is also when we actually check for valid licenses.

This API will invoke the cooking thread if threading is enabled. This means it will return immediately with a call result of HAPI_RESULT_SUCCESS, even if fed garbage. Use the status and cooking count APIs under DIAGNOSTICS to get a sense of the progress. All other API calls will block until the creation (and, optionally, the first cook) of the node has finished.

Also note that the cook result won't be of type HAPI_STATUS_CALL_RESULT like all calls (including this one). Whenever the threading cook is done it will fill the cook result which is queried using HAPI_STATUS_COOK_RESULT.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]parent_node_idThe parent node network's node id or -1 if the parent network is the manager (top-level) node. In that case, the manager must be identified by the table name in the operator_name.
[in]operator_nameThe name of the node operator type.

If you passed parent_node_id == -1, then the operator_name has to include the table name (ie. Object/ or Sop/). This is the common case for when creating asset nodes from a loaded asset library. In that case, just pass whatever HAPI_GetAvailableAssets() returns.

If you have a parent_node_id then you should include only the namespace, name, and version.

For example, lets say you have an Object type asset, in the "hapi" namespace, of version 2.0, named "foo". If you pass parent_node_id == -1, then set the operator_name as "Object/hapi::foo::2.0". Otherwise, if you have a valid parent_node_id, then just pass operator_name as "hapi::foo::2.0".

Parameters
[in]node_label(Optional) The label of the newly created node.
[in]cook_on_creationSet whether the node should cook once created or not.
[out]new_node_idThe returned node id of the just-created node.
HAPI_DECL HAPI_DeleteNode ( const HAPI_Session session,
HAPI_NodeId  node_id 
)

Delete a node from a node network. Only nodes with their HAPI_NodeInfo::createdPostAssetLoad set to true can be deleted this way.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node to delete.
HAPI_DECL HAPI_DisconnectNodeInput ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  input_index 
)

Disconnect a node input.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node whom's input to disconnect.
[in]input_indexThe input index. Should be between 0 and the to_node's HAPI_NodeInfo::inputCount - 1.
HAPI_DECL HAPI_DisconnectNodeOutputsAt ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  output_index 
)

Disconnect all of the node's output connections at the output index.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node whom's outputs to disconnect.
[in]output_indexThe output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount.
HAPI_DECL HAPI_GetComposedChildNodeList ( const HAPI_Session session,
HAPI_NodeId  parent_node_id,
HAPI_NodeId child_node_ids_array,
int  count 
)

Get the composed list of child node ids from the previous call to HAPI_ComposeChildNodeList().

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]parent_node_idThe node id of the parent node.
[out]child_node_ids_arrayThe array of HAPI_NodeId for the child nodes.
[in]countThe number of children in the composed list. MUST match the count returned by HAPI_ComposeChildNodeList().
HAPI_DECL HAPI_GetManagerNodeId ( const HAPI_Session session,
HAPI_NodeType  node_type,
HAPI_NodeId node_id 
)

Get the root node of a particular network type (ie. OBJ).

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_typeThe node network type.
[out]node_idThe node id of the root node network.
HAPI_DECL HAPI_GetNodeFromPath ( const HAPI_Session session,
const HAPI_NodeId  parent_node_id,
const char *  path,
HAPI_NodeId node_id 
)

Get the id of the node with the specified path.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]parent_node_idIf path does not start with "/", search for the path relative to this node. Provide -1 if path is an absolute path.
[in]pathThe path of the node. If the path does not start with "/", it is treated as a relative path from the node specified in parent_node_id.
[out]node_idThe id of the found node.
HAPI_DECL HAPI_GetNodeInfo ( const HAPI_Session session,
HAPI_NodeId  node_id,
HAPI_NodeInfo node_info 
)

Fill an HAPI_NodeInfo struct.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[out]node_infoReturn value - contains things like asset id.
HAPI_DECL HAPI_GetNodeInputName ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  input_idx,
HAPI_StringHandle name 
)

Get the name of an node's input. This function will return a string handle for the name which will be valid (persist) until the next call to this function.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]input_idxThe input index. Should be between 0 and the node_to_query's HAPI_NodeInfo::inputCount - 1.
[out]nameInput name string handle return value - valid until the next call to this function.
HAPI_DECL HAPI_GetNodeOutputName ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  output_idx,
HAPI_StringHandle name 
)

Get the name of an node's output. This function will return a string handle for the name which will be valid (persist) until the next call to this function.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]output_idxThe output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[out]nameOutput name string handle return value - valid until the next call to this function.
HAPI_DECL HAPI_GetNodePath ( const HAPI_Session session,
HAPI_NodeId  node_id,
HAPI_NodeId  relative_to_node_id,
HAPI_StringHandle path 
)

Get the node absolute path in the Houdini node network or a relative path any other node.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]relative_to_node_idSet this to -1 to get the absolute path of the node_id. Otherwise, the path will be relative to this node id.
[out]pathThe returned path string, valid until the next call to this function.
HAPI_DECL HAPI_GetOutputNodeId ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  output,
HAPI_NodeId output_node_id 
)

Gets the node id of an output node in a SOP network.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id of a SOP node with at least one output node. The total number of node outputs can be found from the node's HAPI_NodeInfo::outputCount
[in]outputThe output index. Should be between 0 and the node's HAPI_NodeInfo::outputCount - 1.
[out]output_node_idPointer to a HAPI_NodeId where the node id of the output node will be stored.
HAPI_DECL HAPI_GetTotalCookCount ( const HAPI_Session session,
HAPI_NodeId  node_id,
HAPI_NodeTypeBits  node_type_filter,
HAPI_NodeFlagsBits  node_flags_filter,
HAPI_Bool  recursive,
int *  count 
)

Get the specified node's total cook count, including its children, if specified.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]node_type_filterThe node type by which to filter the children.
[in]node_flags_filterThe node flags by which to filter the children.
[in]recursiveWhether or not to include the specified node's children cook count in the tally.
[out]countThe number of cooks in total for this session.
HAPI_DECL HAPI_IsNodeValid ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  unique_node_id,
HAPI_Bool answer 
)

Determine if your instance of the node actually still exists inside the Houdini scene. This is what can be used to determine when the Houdini scene needs to be re-populated using the host application's instances of the nodes. Note that this function will ALWAYS return HAPI_RESULT_SUCCESS.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]unique_node_idThe unique node id from HAPI_NodeInfo::uniqueHoudiniNodeId.
[out]answerAnswer to the question.
HAPI_DECL HAPI_QueryNodeInput ( const HAPI_Session session,
HAPI_NodeId  node_to_query,
int  input_index,
HAPI_NodeId connected_node_id 
)

Query which node is connected to another node's input.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_to_queryThe node to query.
[in]input_indexThe input index. Should be between 0 and the to_node's HAPI_NodeInfo::inputCount - 1.
[out]connected_node_idThe node id of the connected node to this input. If nothing is connected then -1 will be returned.
HAPI_DECL HAPI_QueryNodeOutputConnectedCount ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  output_idx,
HAPI_Bool  into_subnets,
HAPI_Bool  through_dots,
int *  connected_count 
)

Get the number of nodes currently connected to the given node at the output index.

Use the count returned by this function to get the HAPI_NodeId of connected nodes using HAPI_QueryNodeOutputConnectedNodes().

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]output_idxThe output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[in]into_subnetsWhether to search by diving into subnets.
[in]through_dotsWhether to search through dots.
[out]connected_countThe number of nodes currently connected to this node at given output index. Use this count with a call to HAPI_QueryNodeOutputConnectedNodes() to get list of connected nodes.
HAPI_DECL HAPI_QueryNodeOutputConnectedNodes ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  output_idx,
HAPI_Bool  into_subnets,
HAPI_Bool  through_dots,
HAPI_NodeId connected_node_ids_array,
int  start,
int  length 
)

Get the ids of nodes currently connected to the given node at the output index.

Use the connected_count returned by HAPI_QueryNodeOutputConnectedCount().

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]output_idxThe output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[in]into_subnetsWhether to search by diving into subnets.
[in]through_dotsWhether to search through dots.
[out]connected_node_ids_arrayArray of HAPI_NodeId at least the size of length.
[in]startAt least 0 and at most connected_count returned by HAPI_QueryNodeOutputConnectedCount().
[in]lengthGiven connected_count returned by HAPI_QueryNodeOutputConnectedCount(), length should be at least 1 and at most connected_count - start.
HAPI_DECL HAPI_RenameNode ( const HAPI_Session session,
HAPI_NodeId  node_id,
const char *  new_name 
)

Rename a node that you created. Only nodes with their HAPI_NodeInfo::createdPostAssetLoad set to true can be renamed this way.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node to rename.
[in]new_nameThe new node name.
HAPI_DECL HAPI_SetNodeDisplay ( const HAPI_Session session,
HAPI_NodeId  node_id,
int  onOff 
)

Set the specified node's display flag.

Parameters
[in]sessionThe session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]node_idThe node id.
[in]onOffDisplay flag.