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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	parent_node_id	The node id of the parent node.
[in]	node_type_filter	The node type by which to filter the children.
[in]	node_flags_filter	The node flags by which to filter the children.
[in]	recursive	Whether or not to compose the list recursively.
[out]	count	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node whom's input to connect to.
[in]	input_index	The input index. Should be between 0 and the to_node's HAPI_NodeInfo::inputCount - 1.
[in]	node_id_to_connect	The node to connect to node_id's input.
[in]	output_index	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	cook_options	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	parent_node_id	The 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_id	Newly created node's id. Use HAPI_GetNodeInfo() to get more information about the node.
[in]	name	Give 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	parent_node_id	The 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_name	The 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_creation	Set whether the node should cook once created or not.
[out]	new_node_id	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node to delete.

HAPI_DECL HAPI_DisconnectNodeInput	(	const HAPI_Session *	session,
		HAPI_NodeId	node_id,
		int	input_index
	)

Disconnect a node input.

Parameters

[in]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node whom's input to disconnect.
[in]	input_index	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node whom's outputs to disconnect.
[in]	output_index	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	parent_node_id	The node id of the parent node.
[out]	child_node_ids_array	The array of HAPI_NodeId for the child nodes.
[in]	count	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_type	The node network type.
[out]	node_id	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	parent_node_id	If path does not start with "/", search for the path relative to this node. Provide -1 if path is an absolute path.
[in]	path	The 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_id	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[out]	node_info	Return 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	input_idx	The input index. Should be between 0 and the node_to_query's HAPI_NodeInfo::inputCount - 1.
[out]	name	Input 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	output_idx	The output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[out]	name	Output 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	relative_to_node_id	Set this to -1 to get the absolute path of the node_id. Otherwise, the path will be relative to this node id.
[out]	path	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The 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]	output	The output index. Should be between 0 and the node's HAPI_NodeInfo::outputCount - 1.
[out]	output_node_id	Pointer 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	node_type_filter	The node type by which to filter the children.
[in]	node_flags_filter	The node flags by which to filter the children.
[in]	recursive	Whether or not to include the specified node's children cook count in the tally.
[out]	count	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	unique_node_id	The unique node id from HAPI_NodeInfo::uniqueHoudiniNodeId.
[out]	answer	Answer 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_to_query	The node to query.
[in]	input_index	The input index. Should be between 0 and the to_node's HAPI_NodeInfo::inputCount - 1.
[out]	connected_node_id	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	output_idx	The output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[in]	into_subnets	Whether to search by diving into subnets.
[in]	through_dots	Whether to search through dots.
[out]	connected_count	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	output_idx	The output index. Should be between 0 and the to_node's HAPI_NodeInfo::outputCount - 1.
[in]	into_subnets	Whether to search by diving into subnets.
[in]	through_dots	Whether to search through dots.
[out]	connected_node_ids_array	Array of HAPI_NodeId at least the size of length.
[in]	start	At least 0 and at most connected_count returned by HAPI_QueryNodeOutputConnectedCount().
[in]	length	Given 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node to rename.
[in]	new_name	The 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]	session	The session of Houdini you are interacting with. See HAPI_Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	node_id	The node id.
[in]	onOff	Display flag.