Functions
HAPI_DECL	HAPI_CreateInProcessSession (HAPI_Session session, const HAPI_SessionInfo session_info)
	Creates a new in-process session. There can only be one such session per host process. More...

HAPI_DECL	HAPI_StartThriftSocketServer (const HAPI_ThriftServerOptions options, int port, HAPI_ProcessId process_id, const char *log_file)
	Starts a Thrift RPC server process on the local host serving clients on a TCP socket and waits for it to start serving. It is safe to create an RPC session on local host using the specified port after this call succeeds. More...

HAPI_DECL	HAPI_CreateThriftSocketSession (HAPI_Session session, const char host_name, int port, const HAPI_SessionInfo *session_info)
	Creates a Thrift RPC session using a TCP socket as transport. More...

HAPI_DECL	HAPI_StartThriftNamedPipeServer (const HAPI_ThriftServerOptions options, const char pipe_name, HAPI_ProcessId process_id, const char log_file)
	Starts a Thrift RPC server process on the local host serving clients on a Windows named pipe or a Unix domain socket and waits for it to start serving. It is safe to create an RPC session using the specified pipe or socket after this call succeeds. More...

HAPI_DECL	HAPI_CreateThriftNamedPipeSession (HAPI_Session session, const char pipe_name, const HAPI_SessionInfo *session_info)
	Creates a Thrift RPC session using a Windows named pipe or a Unix domain socket as transport. More...

HAPI_DECL	HAPI_StartThriftSharedMemoryServer (const HAPI_ThriftServerOptions options, const char shared_mem_name, HAPI_ProcessId process_id, const char log_file)
	Starts a Thrift RPC server process on the localhost serving clients by utilizing shared memory to transfer data between the client and server and waits for it to start serving. More...

HAPI_DECL	HAPI_CreateThriftSharedMemorySession (HAPI_Session session, const char shared_mem_name, const HAPI_SessionInfo *session_info)
	Creates a Thrift RPC session using a shared memory buffer as the transport mechanism. More...

HAPI_DECL	HAPI_BindCustomImplementation (HAPI_SessionType session_type, const char *dll_path)
	Binds a new implementation DLL to one of the custom session slots. More...

HAPI_DECL	HAPI_CreateCustomSession (HAPI_SessionType session_type, void session_info, HAPI_Session session)
	Creates a new session using a custom implementation. Note that the implementation DLL must already have been bound to the session via calling HAPI_BindCustomImplementation(). More...

HAPI_DECL	HAPI_IsSessionValid (const HAPI_Session *session)
	Checks whether the session identified by HAPI_Session::id is a valid session opened in the implementation identified by HAPI_Session::type. More...

HAPI_DECL	HAPI_CloseSession (const HAPI_Session *session)
	Closes a session. If the session has been established using RPC, then the RPC connection is closed. More...

HAPI_DECL	HAPI_IsInitialized (const HAPI_Session *session)
	Check whether the runtime has been initialized yet using HAPI_Initialize(). Function will return HAPI_RESULT_SUCCESS if the runtime has been initialized and HAPI_RESULT_NOT_INITIALIZED otherwise. More...

HAPI_DECL	HAPI_Initialize (const HAPI_Session session, const HAPI_CookOptions cook_options, HAPI_Bool use_cooking_thread, int cooking_thread_stack_size, const char houdini_environment_files, const char otl_search_path, const char dso_search_path, const char image_dso_search_path, const char *audio_dso_search_path)
	Create the asset manager, set up environment variables, and initialize the main Houdini scene. No license check is done during this step. Only when you try to load an asset library (OTL) do we actually check for licenses. More...

HAPI_DECL	HAPI_Cleanup (const HAPI_Session *session)
	Clean up memory. This will unload all assets and you will need to call HAPI_Initialize() again to be able to use any HAPI methods again. More...

HAPI_DECL	HAPI_Shutdown (const HAPI_Session *session)
	When using an in-process session, this method must be called in order for the host process to shutdown cleanly. This method should be called before HAPI_CloseSession(). More...

HAPI_DECL	HAPI_StartPerformanceMonitorProfile (const HAPI_Session session, const char title, int *profile_id)
	Start a Houdini Performance Monitor profile. A profile records time and memory statistics from events that occur in the Houdini session. A profile records node cooks for example; how long it takes to cook a node and how many times a node is cooked. Return HAPI_RESULT_INVALID_ARGUMENT if NULL is passed in for the `profile_id` parameter. More...

HAPI_DECL	HAPI_StopPerformanceMonitorProfile (const HAPI_Session session, int profile_id, const char file_path)
	Stop the Performance Monitor profile that matches the given profile id and save out the profile's statistics to the specified file path on disk. The profile is cleared from memory after its statistics are saved to disk. Return HAPI_RESULT_INVALID_ARGUMENT if no profile exists for the given id. Return HAPI_RESULT_FAILURE if the profile statistics could not be saved out to the specified file path. In this case, the profile is stopped but is not cleared from memory. You can call HAPI_StopPerformanceMonitorProfile to attempt saving the profile to disk again. More...

Detailed Description

Functions for creating and inspecting HAPI session state.

Function Documentation

HAPI_DECL HAPI_BindCustomImplementation	(	HAPI_SessionType	session_type,
		const char *	dll_path
	)

Binds a new implementation DLL to one of the custom session slots.

Parameters

[in]	session_type	Which custom implementation slot to bind the DLL to. Must be one of HAPI_SESSION_CUSTOM1, HAPI_SESSION_CUSTOM2, or HAPI_SESSION_CUSTOM3.
[in]	dll_path	The path to the custom implementation DLL.

HAPI_DECL HAPI_Cleanup ( const HAPI_Session * session )

Clean up memory. This will unload all assets and you will need to call HAPI_Initialize() again to be able to use any HAPI methods again.

Note: This does not release any licenses. The license will be returned when the process terminates.

Parameters

[in] session The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.

HAPI_DECL HAPI_CloseSession ( const HAPI_Session * session )

Closes a session. If the session has been established using RPC, then the RPC connection is closed.

Parameters

[in] session The HAPI_Session to close. After this call, this session is invalid and passing it to HAPI calls other than HAPI_IsSessionValid() may result in undefined behavior.

HAPI_DECL HAPI_CreateCustomSession	(	HAPI_SessionType	session_type,
		void *	session_info,
		HAPI_Session *	session
	)

Creates a new session using a custom implementation. Note that the implementation DLL must already have been bound to the session via calling HAPI_BindCustomImplementation().

Parameters

[in]	session_type	session_type indicates which custom session slot to create the session on.
[in,out]	session_info	Any data required by the custom implementation to create its session.
[out]	session	A HAPI_Session struct to receive the session id, The sessionType parameter of the struct should also match the session_type parameter passed in.

HAPI_DECL HAPI_CreateInProcessSession	(	HAPI_Session *	session,
		const HAPI_SessionInfo *	session_info
	)

Creates a new in-process session. There can only be one such session per host process.

Parameters

[out]	session	A HAPI_Session struct to receive the session id, in this case always 0.
[in]	session_info	A HAPI_SessionInfo struct to specify session configurations.

HAPI_DECL HAPI_CreateThriftNamedPipeSession	(	HAPI_Session *	session,
		const char *	pipe_name,
		const HAPI_SessionInfo *	session_info
	)

Creates a Thrift RPC session using a Windows named pipe or a Unix domain socket as transport.

Parameters

[out]	session	A HAPI_Session struct to receive the unique session id of the new session.
[in]	pipe_name	The name of the pipe or socket.
[in]	session_info	A HAPI_SessionInfo struct to specify session configurations.

HAPI_DECL HAPI_CreateThriftSharedMemorySession	(	HAPI_Session *	session,
		const char *	shared_mem_name,
		const HAPI_SessionInfo *	session_info
	)

Creates a Thrift RPC session using a shared memory buffer as the transport mechanism.

Parameters

[out]	session	A HAPI_Session struct to receive the unique session id of the new session.
[in]	shared_mem_name	The name of the memory buffer. This must match the name of the shared memory buffer of the server that you are wishing to connect to.
[in]	session_info	A HAPI_SessionInfo struct to specify session configurations.

HAPI_DECL HAPI_CreateThriftSocketSession	(	HAPI_Session *	session,
		const char *	host_name,
		int	port,
		const HAPI_SessionInfo *	session_info
	)

Creates a Thrift RPC session using a TCP socket as transport.

Parameters

[out]	session	A HAPI_Session struct to receive the unique session id of the new session.
[in]	host_name	The name of the server host.
[in]	port	The server port to connect to.
[in]	session_info	A HAPI_SessionInfo struct to specify session configurations.

HAPI_DECL HAPI_Initialize	(	const HAPI_Session *	session,
		const HAPI_CookOptions *	cook_options,
		HAPI_Bool	use_cooking_thread,
		int	cooking_thread_stack_size,
		const char *	houdini_environment_files,
		const char *	otl_search_path,
		const char *	dso_search_path,
		const char *	image_dso_search_path,
		const char *	audio_dso_search_path
	)

Create the asset manager, set up environment variables, and initialize the main Houdini scene. No license check is done during this step. Only when you try to load an asset library (OTL) do we actually check for licenses.

Parameters

[in]	session	The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	cook_options	Global cook options used by subsequent default cooks. This can be overwritten by individual cooks but if you choose to instantiate assets with cook_on_load set to true then these cook options will be used.
[in]	use_cooking_thread	Use a separate thread for cooking of assets. This allows for asynchronous cooking and larger stack size.
[in]	cooking_thread_stack_size	Set the stack size of the cooking thread. Use -1 to set the stack size to the Houdini default. This value is in bytes.
[in]	houdini_environment_files	A list of paths, separated by a ";" on Windows and a ":" on Linux and Mac, to .env files that follow the same syntax as the houdini.env file in Houdini's user prefs folder. These will be applied after the default houdini.env file and will overwrite the process' environment variable values. You an use this to enforce a stricter environment when running engine. For more info, see: http://www.sidefx.com/docs/houdini/basics/config_env
[in]	otl_search_path	The directory where OTLs are searched for. You can pass NULL here which will only use the default Houdini OTL search paths. You can also pass in multiple paths separated by a ";" on Windows and a ":" on Linux and Mac. If something other than NULL is passed the default Houdini search paths will be appended to the end of the path string.
[in]	dso_search_path	The directory where generic DSOs (custom plugins) are searched for. You can pass NULL here which will only use the default Houdini DSO search paths. You can also pass in multiple paths separated by a ";" on Windows and a ":" on Linux and Mac. If something other than NULL is passed the default Houdini search paths will be appended to the end of the path string.
[in]	image_dso_search_path	The directory where image DSOs (custom plugins) are searched for. You can pass NULL here which will only use the default Houdini DSO search paths. You can also pass in multiple paths separated by a ";" on Windows and a ":" on Linux and Mac. If something other than NULL is passed the default Houdini search paths will be appended to the end of the path string.
[in]	audio_dso_search_path	The directory where audio DSOs (custom plugins) are searched for. You can pass NULL here which will only use the default Houdini DSO search paths. You can also pass in multiple paths separated by a ";" on Windows and a ":" on Linux and Mac. If something other than NULL is passed the default Houdini search paths will be appended to the end of the path string.

HAPI_DECL HAPI_IsInitialized ( const HAPI_Session * session )

Check whether the runtime has been initialized yet using HAPI_Initialize(). Function will return HAPI_RESULT_SUCCESS if the runtime has been initialized and HAPI_RESULT_NOT_INITIALIZED otherwise.

Parameters

[in] session The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.

HAPI_DECL HAPI_IsSessionValid ( const HAPI_Session * session )

Checks whether the session identified by HAPI_Session::id is a valid session opened in the implementation identified by HAPI_Session::type.

Parameters

[in] session The HAPI_Session to check.

Returns: HAPI_RESULT_SUCCESS if the session is valid. Otherwise, the session is invalid and passing it to other HAPI calls may result in undefined behavior.

HAPI_DECL HAPI_Shutdown ( const HAPI_Session * session )

When using an in-process session, this method must be called in order for the host process to shutdown cleanly. This method should be called before HAPI_CloseSession().

Note: This method should only be called before exiting the program, because HAPI can no longer be used by the process once this method has been called.

Parameters

[in] session The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.

HAPI_DECL HAPI_StartPerformanceMonitorProfile	(	const HAPI_Session *	session,
		const char *	title,
		int *	profile_id
	)

Start a Houdini Performance Monitor profile. A profile records time and memory statistics from events that occur in the Houdini session. A profile records node cooks for example; how long it takes to cook a node and how many times a node is cooked. Return HAPI_RESULT_INVALID_ARGUMENT if NULL is passed in for the profile_id parameter.

Parameters

[in]	session	The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	title	The title of the profile. If NULL is passed into this parameter, then a default title will be chosen for the profile.
[out]	profile_id	The id of the profile. You can pass the id to HAPI_StopPerformanceMonitorProfile to stop the profile.

HAPI_DECL HAPI_StartThriftNamedPipeServer	(	const HAPI_ThriftServerOptions *	options,
		const char *	pipe_name,
		HAPI_ProcessId *	process_id,
		const char *	log_file
	)

Starts a Thrift RPC server process on the local host serving clients on a Windows named pipe or a Unix domain socket and waits for it to start serving. It is safe to create an RPC session using the specified pipe or socket after this call succeeds.

Parameters

[in]	options	Options to configure the server being started.
[in]	pipe_name	The name of the pipe or socket.
[out]	process_id	The process id of the server, if started successfully.
[in]	log_file	When a filepath is provided for this argument, all logs will be appended to the specified file. The specfied path must be an absolute path. The server will create any intermediate directories in the filepath that do not already exist. When this argument is NULL/nullptr, logging will be directed to the standard streams.

HAPI_DECL HAPI_StartThriftSharedMemoryServer	(	const HAPI_ThriftServerOptions *	options,
		const char *	shared_mem_name,
		HAPI_ProcessId *	process_id,
		const char *	log_file
	)

Starts a Thrift RPC server process on the localhost serving clients by utilizing shared memory to transfer data between the client and server and waits for it to start serving.

Parameters

[in]	options	Options to configure the server being started.
[in]	shared_mem_name	The name of the memory buffer. This must be unique to the server in order to avoid any conflicts.
[out]	process_id	The process id of the server, if started successfully.
[in]	log_file	When a filepath is provided for this argument, all logs will be appended to the specified file. The specified path must be an absolute path. The server will create any intermediate directories in the filepath that do not already exist. When this argument is NULL/nullptr, logging will be directed to the standard streams.

HAPI_DECL HAPI_StartThriftSocketServer	(	const HAPI_ThriftServerOptions *	options,
		int	port,
		HAPI_ProcessId *	process_id,
		const char *	log_file
	)

Starts a Thrift RPC server process on the local host serving clients on a TCP socket and waits for it to start serving. It is safe to create an RPC session on local host using the specified port after this call succeeds.

Parameters

[in]	options	Options to configure the server being started.
[in]	port	The TCP socket to create on the server.
[out]	process_id	The process id of the server, if started successfully.
[in]	log_file	When a filepath is provided for this argument, all logs will be appended to the specified file. The specfied path must be an absolute path. The server will create any intermediate directories in the filepath that do not already exist. When this argument is NULL/nullptr, logging will be directed to the standard streams.

HAPI_DECL HAPI_StopPerformanceMonitorProfile	(	const HAPI_Session *	session,
		int	profile_id,
		const char *	file_path
	)

Stop the Performance Monitor profile that matches the given profile id and save out the profile's statistics to the specified file path on disk. The profile is cleared from memory after its statistics are saved to disk. Return HAPI_RESULT_INVALID_ARGUMENT if no profile exists for the given id. Return HAPI_RESULT_FAILURE if the profile statistics could not be saved out to the specified file path. In this case, the profile is stopped but is not cleared from memory. You can call HAPI_StopPerformanceMonitorProfile to attempt saving the profile to disk again.

Parameters

[in]	session	The session of Houdini you are interacting with. See Sessions for more on sessions. Pass NULL to just use the default in-process session.
[in]	profile_id	The id of the profile to stop.
[in]	file_path	The path to the file where the profile statistics should be written to. Use the Performance Monitor file extension, .hperf, in the file name (i.e. /path/to/myProfile.hperf).