#include "SG.h"

Include dependency graph for SG_Com.h:

Data Structures
struct	SG_COM_PlayerConfig
	Structure containing a Player configuration. More...

struct	SG_COM_EngineConfig
	Structure containing an Engine configuration. More...

Macros
#define	SG_COM_VERSION_NAME "5.1.0"
	String representation of SG_Com version Compare this definition with the output of SG_COM_GetVersionString() to ensure that this .h file matches the binary.

Typedefs
typedef struct SG_COM_PlayerConfig	SG_COM_PlayerConfig
	Structure containing a Player configuration.

typedef struct SG_COM_Player *	SG_COM_PlayerHandle
	Handle type.

typedef struct SG_COM_Engine *	SG_COM_EngineHandle
	Handle type.

typedef void(*	SG_COM_EngineBroadcastCallback) (SG_COM_EngineHandle engine_handle, char packet, sg_size packet_bytes, void custom_engine_data)
	Callback that will be called by an Engine to output packets.

typedef void(*	SG_COM_EngineStatusCallback) (SG_COM_EngineHandle engine_handle, SG_COM_Status status, const char message, void custom_engine_data)
	Callback that will be called in the event of Engine status update.

typedef struct SG_COM_EngineConfig	SG_COM_EngineConfig
	Structure containing an Engine configuration.

Enumerations
enum	SG_COM_Error { SG_COM_ERROR_OK , SG_COM_ERROR_LOW_MEMORY , SG_COM_ERROR_INVALID_LICENSE , SG_COM_ERROR_INVALID_HANDLE , SG_COM_ERROR_INVALID_PACKET , SG_COM_ERROR_INVALID_PARAM , SG_COM_ERROR_TICK_IN_PROGRESS , SG_COM_ERROR_OUT_OF_ORDER_PACKET_DISCARDED , SG_COM_ERROR_INPUT_OVERRUN , SG_COM_ERROR_INPUT_UNDERRUN , SG_COM_ERROR_EXCEPTION , SG_COM_ERROR_NOT_IMPLEMENTED , SG_COM_ERROR_UNDEFINED , SG_COM_ERROR_LICENSE_CHECKOUT_FAILURE }
	Enum of error codes. More...

enum	SG_COM_Status { SG_COM_STATUS_MODE_CHANGED , SG_COM_STATUS_AUTO_MODE_CHANGED , SG_COM_STATUS_EXPRESSION_CHANGED , SG_COM_STATUS_VOICE_ACTIVITY_CHANGED , SG_COM_STATUS_BREATH_CHANGED }
	Enum of status codes. More...

enum	SG_COM_Modifier { SG_COM_MOD_SPEECH_MAG , SG_COM_MOD_NONVERBAL_MAG , SG_COM_MOD_NONVERBAL_SPEED , SG_COM_MOD_BREATH_MAG , SG_COM_MOD_BREATH_SPEED , SG_COM_MOD_EXPRESSION_FREQ , SG_COM_MOD_BLINK_FREQ , SG_COM_MOD_DART_FREQ }
	Enum of modifiers. More...

enum	SG_COM_Role { SG_COM_ROLE_SPEAK , SG_COM_ROLE_LISTEN }
	Enum of roles. More...

enum	SG_COM_AutoMode { SG_COM_POSITIVE_MODE , SG_COM_NEGATIVE_MODE , SG_COM_EFFORT_MODE , SG_COM_LAUGH_MODE , SG_COM_ACKNOWLEDGE_MODE }
	Enum of auto modes. More...

enum	SG_COM_EngineConfigFlag { SG_COM_ENGINE_CONFIG_NONE = 0 , SG_COM_ENGINE_CONFIG_ENABLE_IDLE = 1 , SG_COM_ENGINE_CONFIG_FIXED_RANDOM_SEED = 2 }
	Enum of Engine configuration flags. More...

Functions
SG_DYN const char *	SG_COM_GetExceptionText (void)
	Retrieve exception text after SG_ERROR_EXCEPTION error.

SG_DYN SG_COM_Error	SG_COM_Initialize (SG_LoggingLevel logging_level, SG_LoggingCallback logging_callback, const char license_data, const char license_unique_id, const char *license_custom_data)
	Initialize the internal context of SG Com.

SG_DYN SG_COM_Error	SG_COM_Shutdown (void)
	Shut down and dispose of the internal context of SG Com.

SG_DYN const char *	SG_COM_GetVersionString (void)
	Get the runtime version number for this library in string format.

SG_DYN unsigned int	SG_COM_GetVersionNumber (void)
	Get the runtime version number for this library.

SG_DYN SG_COM_Error	SG_COM_CreateEngine (const SG_COM_EngineConfig engine_config, SG_COM_EngineHandle engine_handle)
	Create an Engine.

SG_DYN SG_COM_Error	SG_COM_CreateAltEngine (const SG_COM_EngineConfig engine_config, SG_COM_EngineHandle engine_handle, const unsigned char *algorithms_file, unsigned int algorithms_file_size)
	Create an alternative Engine confguration using algorithms file.

SG_DYN SG_COM_Error	SG_COM_DestroyEngine (SG_COM_EngineHandle engine_handle)
	Destroy an Engine.

SG_DYN SG_COM_Error	SG_COM_InputAudio (SG_COM_EngineHandle engine_handle, const void *data, sg_size data_bytes)
	Input audio data for processing.

SG_DYN SG_COM_Error	SG_COM_InputAuxData (SG_COM_EngineHandle engine_handle, const void *data, sg_size data_bytes)
	Input auxiliary data for processing.

SG_DYN SG_COM_Error	SG_COM_ProcessTick (SG_COM_EngineHandle engine_handle, int processed_frames, int remaining_frames)
	Performs processing necessary to move one 10ms frame through the pipeline.

SG_DYN SG_COM_Error	SG_COM_Reset (SG_COM_EngineHandle engine_handle)
	Clears an Engine and resets to initial state.

SG_DYN SG_COM_Error	SG_COM_SetMode (SG_COM_EngineHandle engine_handle, const char *mode)
	Set the current behavior mode of an Engine.

SG_DYN SG_COM_Error	SG_COM_SetDefaultMode (SG_COM_EngineHandle engine_handle, const char *mode)
	Set the default behavior mode of an Engine.

SG_DYN SG_COM_Error	SG_COM_SetAutoMode (SG_COM_EngineHandle engine_handle, SG_COM_AutoMode auto_mode, const char *mode)
	Define an auto mode by mapping it to a specific behavior mode.

SG_DYN SG_COM_Error	SG_COM_UnsetAutoModes (SG_COM_EngineHandle engine_handle)
	Clear the definitions for all auto modes.

SG_DYN SG_COM_Error	SG_COM_ActivateAutoModes (SG_COM_EngineHandle engine_handle)
	Activate auto modes.

SG_DYN SG_COM_Error	SG_COM_InsertExpression (SG_COM_EngineHandle engine_handle, const char *expression, sg_size duration_ms, float scale)
	Insert an expression.

SG_DYN SG_COM_Error	SG_COM_GetMode (SG_COM_EngineHandle engine_handle, char *mode, sg_size buffersize)
	Get the current behavior mode of an Engine.

SG_DYN SG_COM_Error	SG_COM_GetModeList (SG_COM_EngineHandle engine_handle, char *mode_list, sg_size buffersize)
	Get a list of the available behavior modes in an Engine.

SG_DYN SG_COM_Error	SG_COM_SetRole (SG_COM_EngineHandle engine_handle, SG_COM_Role role)
	Set the role of an Engine vis-a-vis the incoming speech: to move as if speaking, or to move as if listening.

SG_DYN SG_COM_Error	SG_COM_GetRole (SG_COM_EngineHandle engine_handle, SG_COM_Role *role)
	Get the current role of an Engine.

SG_DYN SG_COM_Error	SG_COM_GetModifier (SG_COM_EngineHandle engine_handle, SG_COM_Modifier modifier, float *value)
	Get the value of a modifier.

SG_DYN SG_COM_Error	SG_COM_SetModifier (SG_COM_EngineHandle engine_handle, SG_COM_Modifier modifier, float value)
	Set the value of a modifier.

SG_DYN SG_COM_Error	SG_COM_CreatePlayer (const SG_COM_PlayerConfig player_config, SG_COM_PlayerHandle player_handle)
	Create a Player to play the output from a Broadcast Engine.

SG_DYN SG_COM_Error	SG_COM_DestroyPlayer (SG_COM_PlayerHandle player_handle)
	Destroy a Player.

SG_DYN SG_COM_Error	SG_COM_ReceivePacket (SG_COM_PlayerHandle player_handle, const char *packet, sg_size packet_bytes)
	Receive an output packet from an Engine into the corresponding Player.

SG_DYN SG_COM_Error	SG_COM_GetAnimationNodes (SG_COM_PlayerHandle player_handle, SG_AnimationNode *animation_nodes, sg_size num_animation_nodes)
	Get the animation nodes for a given Player.

SG_DYN SG_COM_Error	SG_COM_UpdateAnimation (SG_COM_PlayerHandle player_handle, double time_ms, double *current_time_ms)
	Set the current play time and update the animation nodes.

SG_DYN SG_COM_Error	SG_COM_GetPlayableRange (SG_COM_PlayerHandle player_handle, double min_time_ms, double max_time_ms)
	Get the range of buffered animation.

Detailed Description

Date: 2019/08/31

Definition in file SG_Com.h.

Macro Definition Documentation

◆ SG_COM_VERSION_NAME

#define SG_COM_VERSION_NAME "5.1.0"

String representation of SG_Com version Compare this definition with the output of SG_COM_GetVersionString() to ensure that this .h file matches the binary.

Definition at line 16 of file SG_Com.h.

Typedef Documentation

◆ SG_COM_EngineBroadcastCallback

typedef void(* SG_COM_EngineBroadcastCallback) (SG_COM_EngineHandle engine_handle, char *packet, sg_size packet_bytes, void *custom_engine_data)

Callback that will be called by an Engine to output packets.

Parameters

engine_handle	The Engine that triggered the callback.
packet	The packet.
packet_bytes	Packet size in bytes.
custom_engine_data	A custom pointer that was provided to the Engine at construction.

Definition at line 112 of file SG_Com.h.

◆ SG_COM_EngineConfig

typedef struct SG_COM_EngineConfig SG_COM_EngineConfig

Structure containing an Engine configuration.

◆ SG_COM_EngineHandle

typedef struct SG_COM_Engine* SG_COM_EngineHandle

Handle type.

Definition at line 103 of file SG_Com.h.

◆ SG_COM_EngineStatusCallback

typedef void(* SG_COM_EngineStatusCallback) (SG_COM_EngineHandle engine_handle, SG_COM_Status status, const char *message, void *custom_engine_data)

Callback that will be called in the event of Engine status update.

Parameters

engine_handle	The Engine that triggered the callback.
status	The status code.
msg	The status message string.
custom_engine_data	A custom pointer that was provided to the Engine at construction.

Definition at line 125 of file SG_Com.h.

◆ SG_COM_PlayerConfig

typedef struct SG_COM_PlayerConfig SG_COM_PlayerConfig

Structure containing a Player configuration.

◆ SG_COM_PlayerHandle

typedef struct SG_COM_Player* SG_COM_PlayerHandle

Handle type.

Definition at line 98 of file SG_Com.h.

Enumeration Type Documentation

◆ SG_COM_AutoMode

enum SG_COM_AutoMode

Enum of auto modes.

Enumerator
SG_COM_POSITIVE_MODE	The mode triggered when positive emotion is detected.
SG_COM_NEGATIVE_MODE	The mode triggered when negative emotion is detected.
SG_COM_EFFORT_MODE	The mode triggered when an effort sound is detected.
SG_COM_LAUGH_MODE	The mode triggered when a laugh is detected.
SG_COM_ACKNOWLEDGE_MODE	The mode triggered when a conditions for an acknowledgement are detected in Listen role.

Definition at line 78 of file SG_Com.h.

◆ SG_COM_EngineConfigFlag

enum SG_COM_EngineConfigFlag

Enum of Engine configuration flags.

Enumerator
SG_COM_ENGINE_CONFIG_NONE
SG_COM_ENGINE_CONFIG_ENABLE_IDLE	Enable idle mode.
SG_COM_ENGINE_CONFIG_FIXED_RANDOM_SEED	Use a fixed seed in random number generators for deterministic output.

Definition at line 134 of file SG_Com.h.

◆ SG_COM_Error

enum SG_COM_Error

Enum of error codes.

Enumerator
SG_COM_ERROR_OK	No error.
SG_COM_ERROR_LOW_MEMORY	A low memory condition was detected.
SG_COM_ERROR_INVALID_LICENSE	The license is invalid.
SG_COM_ERROR_INVALID_HANDLE	An invalid Engine or Player was created or referenced.
SG_COM_ERROR_INVALID_PACKET	An invalid data packet was received.
SG_COM_ERROR_INVALID_PARAM	An invalid parameter was passed to a function.
SG_COM_ERROR_TICK_IN_PROGRESS
SG_COM_ERROR_OUT_OF_ORDER_PACKET_DISCARDED	Process tick was called while the previous tick was in progress. A data packet was received out of order and was discarded.
SG_COM_ERROR_INPUT_OVERRUN	The input buffer does not have sufficient free space to perform the requested operation.
SG_COM_ERROR_INPUT_UNDERRUN	The input buffer does not contain sufficient data to perform the requested operation.
SG_COM_ERROR_EXCEPTION	An exception was raised, call SG_COM_GetExceptionText() for details.
SG_COM_ERROR_NOT_IMPLEMENTED	This operation is not implemented.
SG_COM_ERROR_UNDEFINED	An unclassified error occurred.
SG_COM_ERROR_LICENSE_CHECKOUT_FAILURE	Failed to checkout a valid license.

Definition at line 25 of file SG_Com.h.

◆ SG_COM_Modifier

enum SG_COM_Modifier

Enum of modifiers.

Enumerator
SG_COM_MOD_SPEECH_MAG	Adjusts magnitude of speech muscle motion. Default is 1.0.
SG_COM_MOD_NONVERBAL_MAG	Adjusts magnitude of nonverbal muscle motion. Default is 1.0.
SG_COM_MOD_NONVERBAL_SPEED	Adjusts speed of nonverbal muscle motion. Default is 1.0.
SG_COM_MOD_BREATH_MAG	Adjusts magnitude of breath. Default is 1.0.
SG_COM_MOD_BREATH_SPEED	Adjusts speed of breath. Default is 1.0.
SG_COM_MOD_EXPRESSION_FREQ	Adjusts frequency of expression change. Default is 1.0.
SG_COM_MOD_BLINK_FREQ	Adjusts frequency of blinks. Default is 1.0.
SG_COM_MOD_DART_FREQ	Adjusts frequency of microdarts. Default is 1.0.

Definition at line 56 of file SG_Com.h.

◆ SG_COM_Role

enum SG_COM_Role

Enum of roles.

Enumerator
SG_COM_ROLE_SPEAK	Speaking role.
SG_COM_ROLE_LISTEN	Listening role.

Definition at line 70 of file SG_Com.h.

◆ SG_COM_Status

enum SG_COM_Status

Enum of status codes.

Enumerator
SG_COM_STATUS_MODE_CHANGED	The current behavior mode of the character changed, either manually or automatically. The accompanying message contains name of the mode.
SG_COM_STATUS_AUTO_MODE_CHANGED	The latest triggered auto mode. The accompanying message contains name of the auto mode.
SG_COM_STATUS_EXPRESSION_CHANGED	The expression of the character changed. The accompanying message contains the path of the expression in the character's behavior mode library, followed by ";" and then the scale of the expression.
SG_COM_STATUS_VOICE_ACTIVITY_CHANGED	A change in voice activity was detected. The accompanying message contains "0" or "1".
SG_COM_STATUS_BREATH_CHANGED	The breath switched either from inhale to exhale or from exhale to inhale. The accompanying message is "inhale" or "exhale" indicating the new direction of breath.

Definition at line 45 of file SG_Com.h.

Function Documentation

◆ SG_COM_ActivateAutoModes()

SG_DYN SG_COM_Error SG_COM_ActivateAutoModes ( SG_COM_EngineHandle engine_handle )

Activate auto modes.

Parameters

engine_handle The Engine.

Returns: Error code indicating success or reason for failure.

For auto modes to be triggered, they must be defined using SG_COM_SetAutoMode(). Auto modes are deactivated when a specific mode is set using SG_COM_SetMode().

◆ SG_COM_CreateAltEngine()

SG_DYN SG_COM_Error SG_COM_CreateAltEngine	(	const SG_COM_EngineConfig *	engine_config,
		SG_COM_EngineHandle *	engine_handle,
		const unsigned char *	algorithms_file,
		unsigned int	algorithms_file_size
	)

Create an alternative Engine confguration using algorithms file.

Parameters

	engine_config	Pointer to an SG_COM_EngineConfig structure.
[out]	engine_handle	Output handle to the created Engine.
	algorithms_file	Pointer to algoritihms file data buffer
	algorithms_file_size	Size of algorithms file data buffer (in bytes)

Returns: Error code indicating success or reason for failure.

◆ SG_COM_CreateEngine()

SG_DYN SG_COM_Error SG_COM_CreateEngine	(	const SG_COM_EngineConfig *	engine_config,
		SG_COM_EngineHandle *	engine_handle
	)

Create an Engine.

Parameters

	engine_config	Pointer to an SG_COM_EngineConfig structure.
[out]	engine_handle	Output handle to the created Engine.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_CreatePlayer()

SG_DYN SG_COM_Error SG_COM_CreatePlayer	(	const SG_COM_PlayerConfig *	player_config,
		SG_COM_PlayerHandle *	player_handle
	)

Create a Player to play the output from a Broadcast Engine.

Parameters

	player_config	Pointer to an SG_COM_PlayerConfig structure.
[out]	player_handle	Output handle to the created Player.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_DestroyEngine()

SG_DYN SG_COM_Error SG_COM_DestroyEngine ( SG_COM_EngineHandle engine_handle )

Destroy an Engine.

Parameters

engine_handle The Engine to destroy.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_DestroyPlayer()

SG_DYN SG_COM_Error SG_COM_DestroyPlayer ( SG_COM_PlayerHandle player_handle )

Destroy a Player.

Parameters

player_handle The Player to be destroyed.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetAnimationNodes()

SG_DYN SG_COM_Error SG_COM_GetAnimationNodes	(	SG_COM_PlayerHandle	player_handle,
		SG_AnimationNode **	animation_nodes,
		sg_size *	num_animation_nodes
	)

Get the animation nodes for a given Player.

Parameters

	player_handle	The Player.
[out]	animation_nodes	An array of animation nodes managed by SG Com.
[out]	num_animation_nodes	The number of animation nodes.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetExceptionText()

SG_DYN const char * SG_COM_GetExceptionText ( void )

Retrieve exception text after SG_ERROR_EXCEPTION error.

Returns: Pointer to null terminated string.

◆ SG_COM_GetMode()

SG_DYN SG_COM_Error SG_COM_GetMode	(	SG_COM_EngineHandle	engine_handle,
		char *	mode,
		sg_size	buffersize
	)

Get the current behavior mode of an Engine.

Parameters

	engine_handle	The Engine.
[out]	mode	User-allocated buffer into which the mode name is written.
	buffersize	The size of the user-allocated buffer.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetModeList()

SG_DYN SG_COM_Error SG_COM_GetModeList	(	SG_COM_EngineHandle	engine_handle,
		char *	mode_list,
		sg_size	buffersize
	)

Get a list of the available behavior modes in an Engine.

Parameters

	engine_handle	The Engine.
[out]	mode_list	User-allocated buffer into which a comma-separated mode list is written.
	buffersize	The size of the user-allocated buffer.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetModifier()

SG_DYN SG_COM_Error SG_COM_GetModifier	(	SG_COM_EngineHandle	engine_handle,
		SG_COM_Modifier	modifier,
		float *	value
	)

Get the value of a modifier.

Parameters

	engine_handle	The Engine.
	modifier	The modifier key.
[out]	value	The returned modifier value.

◆ SG_COM_GetPlayableRange()

SG_DYN SG_COM_Error SG_COM_GetPlayableRange	(	SG_COM_PlayerHandle	player_handle,
		double *	min_time_ms,
		double *	max_time_ms
	)

Get the range of buffered animation.

Parameters

player_handle	The Player.
min_time_ms[out]	The minimum time of the playback window in milliseconds.
max_time_ms[out]	The maximum time of the playback window in millseconds.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetRole()

SG_DYN SG_COM_Error SG_COM_GetRole	(	SG_COM_EngineHandle	engine_handle,
		SG_COM_Role *	role
	)

Get the current role of an Engine.

Parameters

	engine_handle	The Engine.
[out]	role	The role.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_GetVersionNumber()

SG_DYN unsigned int SG_COM_GetVersionNumber ( void )

Get the runtime version number for this library.

Returns: The runtime version number for this library.

The format of the returned value is vvvmmmppp where v is major version, m is minor version and p is patch version.

◆ SG_COM_GetVersionString()

SG_DYN const char * SG_COM_GetVersionString ( void )

Get the runtime version number for this library in string format.

Returns: String representation of the version of this library

The format of the retured value is "major.minor.patch-label", for example 0.1.0-alpha.

◆ SG_COM_Initialize()

SG_DYN SG_COM_Error SG_COM_Initialize	(	SG_LoggingLevel	logging_level,
		SG_LoggingCallback	logging_callback,
		const char *	license_data,
		const char *	license_unique_id,
		const char *	license_custom_data
	)

Initialize the internal context of SG Com.

This must be called once at startup before using any other functions in this API.

Parameters

log_level	The logging level to set, from SG_LoggingLevel.
logging_callback	A callback that can be used for logging (pass nullptr if not used).
license_data	For key-based licensing, the license key string. For cloud-based licensing, the path of the .lic file.
license_unique_id	The unique id of the application for licensing purposes. Can be nullptr.
license_custom_data	Custom data passed to the license server - can be nullptr.

Returns: Error code indicating success or reason for failure.

On Windows, OSX and Linux, if you do not provide a logging callback, SG Com will log to file. Log files will be written to following directories:

Windows : C:\Users\<User Name>\AppData\Local\Speech Graphics\logs
OSX : /Users/<User Name>/Library/Application Support/Speech Graphics/logs
Linux : ~/.carnival/logs/

On all other platforms, SG_Com will not log to file. Instead, you must provide a callback to accept logging messages. Your callback is responsible for directing the message to a logging system such as the Android or iOS log, or perhaps your applications' own custom logger.

◆ SG_COM_InputAudio()

SG_DYN SG_COM_Error SG_COM_InputAudio	(	SG_COM_EngineHandle	engine_handle,
		const void *	data,
		sg_size	data_bytes
	)

Input audio data for processing.

Parameters

engine_handle	The Engine to receive the input.
data	Pointer to the audio data.
data_bytes	The number of bytes of audio data.

Returns: Error code indicating success or reason for failure.

The audio data must be be in linear PCM format, mono, and must conform to the specifications supplied in the SG_EngineConfig struct that was used to create the Engine.

◆ SG_COM_InputAuxData()

SG_DYN SG_COM_Error SG_COM_InputAuxData	(	SG_COM_EngineHandle	engine_handle,
		const void *	data,
		sg_size	data_bytes
	)

Input auxiliary data for processing.

Parameters

engine_handle	The Engine to receive the input.
data	Pointer to the data.
data_bytes	The number of bytes of aux data.

Returns: Error code indicating success or reason for failure.

Auxiliary data is currently assumed to have a sample rate of 100 Hz.

◆ SG_COM_InsertExpression()

SG_DYN SG_COM_Error SG_COM_InsertExpression	(	SG_COM_EngineHandle	engine_handle,
		const char *	expression,
		sg_size	duration_ms,
		float	scale
	)

Insert an expression.

Parameters

engine_handle	The Engine.
expression	The path of the expression in the character's behavior mode library. If nullptr, an expression will be automatically selected from the current behavior mode.
duration_ms	The desired duration of the expression in milliseconds. If 0, the duration will be automatically determined.
scale	The desired scale of the expression (from 0 to 1). If 0, the scale will be automatically determined.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_ProcessTick()

SG_DYN SG_COM_Error SG_COM_ProcessTick	(	SG_COM_EngineHandle	engine_handle,
		int *	processed_frames,
		int *	remaining_frames
	)

Performs processing necessary to move one 10ms frame through the pipeline.

If there is no input and idle is enabled, will generate idle animation.

Parameters

	engine_handle	The Engine on which to execute processing.
[out]	processed_frames	The number of frames that were processed (0 or 1).
[out]	remaining_frames	The number of frames that remain in the input buffer.

Returns: Error code indicating success or reason for failure.

This function is designed to be called on a background thread or threadpool, and in that case can return SG_COM_ERROR_TICK_IN_PROGRESS if the tick is called before the previous tick (on another thread) has had time to complete.

This function is NOT thread-safe relative to SG_COM_DestroyEngine() or SG_COM_Reset() calls. It is recommended to ensure proper synchronization when using this function concurrently with those calls.

◆ SG_COM_ReceivePacket()

SG_DYN SG_COM_Error SG_COM_ReceivePacket	(	SG_COM_PlayerHandle	player_handle,
		const char *	packet,
		sg_size	packet_bytes
	)

Receive an output packet from an Engine into the corresponding Player.

Parameters

player_handle	The Player.
packet	The packet.
packet_bytes	The packet size in bytes.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_Reset()

SG_DYN SG_COM_Error SG_COM_Reset ( SG_COM_EngineHandle engine_handle )

Clears an Engine and resets to initial state.

Parameters

engine_handle The Engine to reset.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_SetAutoMode()

SG_DYN SG_COM_Error SG_COM_SetAutoMode	(	SG_COM_EngineHandle	engine_handle,
		SG_COM_AutoMode	auto_mode,
		const char *	mode
	)

Define an auto mode by mapping it to a specific behavior mode.

Parameters

engine_handle	The Engine.
auto_mode	The auto mode to define.
mode	The behavior mode.

Returns: Error code indicating success or reason for failure.

An auto mode is triggered only if it is defined. If undefined or set to nullptr, it will not be triggered.

◆ SG_COM_SetDefaultMode()

SG_DYN SG_COM_Error SG_COM_SetDefaultMode	(	SG_COM_EngineHandle	engine_handle,
		const char *	mode
	)

Set the default behavior mode of an Engine.

This mode will be active if no other mode is automatically triggered or explicitly set.

Parameters

engine_handle	The Engine.
mode	The behavior mode by name. Must be one of the behavior modes of the character.

Returns: Error code indicating success or reason for failure.

If this function is not called, the default behavior mode will be the one marked 'default' in the character's mode library.

◆ SG_COM_SetMode()

SG_DYN SG_COM_Error SG_COM_SetMode	(	SG_COM_EngineHandle	engine_handle,
		const char *	mode
	)

Set the current behavior mode of an Engine.

This operation overrides automatic mode detection. To re-engage auto modes, call SG_COM_ActivateAutoModes().

Parameters

engine_handle	The Engine.
mode	The behavior mode by name. Must be one of the behavior modes of the character. Use keyword 'default' to choose the default behavior mode.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_SetModifier()

SG_DYN SG_COM_Error SG_COM_SetModifier	(	SG_COM_EngineHandle	engine_handle,
		SG_COM_Modifier	modifier,
		float	value
	)

Set the value of a modifier.

Parameters

engine_handle	The Engine.
modifier	The modifier key.
value	The modifier value.

◆ SG_COM_SetRole()

SG_DYN SG_COM_Error SG_COM_SetRole	(	SG_COM_EngineHandle	engine_handle,
		SG_COM_Role	role
	)

Set the role of an Engine vis-a-vis the incoming speech: to move as if speaking, or to move as if listening.

Parameters

engine_handle	The Engine.
role	The role.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_Shutdown()

SG_DYN SG_COM_Error SG_COM_Shutdown ( void )

Shut down and dispose of the internal context of SG Com.

This must be the last function call to SG Com.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_UnsetAutoModes()

SG_DYN SG_COM_Error SG_COM_UnsetAutoModes ( SG_COM_EngineHandle engine_handle )

Clear the definitions for all auto modes.

Parameters

engine_handle The Engine.

Returns: Error code indicating success or reason for failure.

After calling this, the auto modes will not be triggered until they are defined using SG_COM_SetAutoMode().

◆ SG_COM_UpdateAnimation()

SG_DYN SG_COM_Error SG_COM_UpdateAnimation	(	SG_COM_PlayerHandle	player_handle,
		double	time_ms,
		double *	current_time_ms
	)

Set the current play time and update the animation nodes.

The time value will be clamped to the playable range.

Parameters

player_handle	The Player.
time_ms	The time (in milliseconds).
current_time_ms[out]	The new current time. If range clamping occurred, this will be different from the input time. May be nullptr.

Returns: Error code.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SG_COM_VERSION_NAME

Typedef Documentation

◆ SG_COM_EngineBroadcastCallback

◆ SG_COM_EngineConfig

◆ SG_COM_EngineHandle

◆ SG_COM_EngineStatusCallback

◆ SG_COM_PlayerConfig

◆ SG_COM_PlayerHandle

Enumeration Type Documentation

◆ SG_COM_AutoMode

◆ SG_COM_EngineConfigFlag

◆ SG_COM_Error

◆ SG_COM_Modifier

◆ SG_COM_Role

◆ SG_COM_Status

Function Documentation

◆ SG_COM_ActivateAutoModes()

◆ SG_COM_CreateAltEngine()

◆ SG_COM_CreateEngine()

◆ SG_COM_CreatePlayer()

◆ SG_COM_DestroyEngine()

◆ SG_COM_DestroyPlayer()

◆ SG_COM_GetAnimationNodes()

◆ SG_COM_GetExceptionText()

◆ SG_COM_GetMode()

◆ SG_COM_GetModeList()

◆ SG_COM_GetModifier()

◆ SG_COM_GetPlayableRange()

◆ SG_COM_GetRole()

◆ SG_COM_GetVersionNumber()

◆ SG_COM_GetVersionString()

◆ SG_COM_Initialize()

◆ SG_COM_InputAudio()

◆ SG_COM_InputAuxData()

◆ SG_COM_InsertExpression()

◆ SG_COM_ProcessTick()

◆ SG_COM_ReceivePacket()

◆ SG_COM_Reset()

◆ SG_COM_SetAutoMode()

◆ SG_COM_SetDefaultMode()

◆ SG_COM_SetMode()

◆ SG_COM_SetModifier()

◆ SG_COM_SetRole()

◆ SG_COM_Shutdown()

◆ SG_COM_UnsetAutoModes()

◆ SG_COM_UpdateAnimation()