CriAtomExHcaMx API

Data Structures
struct	CriAtomExHcaMxConfigTag
	Configuration structure used to initialize HCA-MXThis is a structure for specifying the operation specifications of HCA-MX. This is specified as an argument to the criAtomExHcaMx_Initialize function. More...

Macros
#define	criAtomExHcaMx_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to initialize HCA-MX. More...

Typedefs
typedef struct CriAtomExHcaMxConfigTag	CriAtomExHcaMxConfig
	Configuration structure used to initialize HCA-MXThis is a structure for specifying the operation specifications of HCA-MX. This is specified as an argument to the criAtomExHcaMx_Initialize function. More...

Functions
CriSint32	criAtomExHcaMx_CalculateWorkSize (const CriAtomExHcaMxConfig *config)
	Calculate the size of the work buffer required to initialize HCA-MX. More...
void	criAtomExHcaMx_SetConfigForWorkSizeCalculation (const CriAtomExHcaMxConfig *config)
	Set the configuration structure used to calculate the size of the work buffer. More...
void	criAtomExHcaMx_Initialize (const CriAtomExHcaMxConfig *config, void *work, CriSint32 work_size)
	Initialize HCA-MX. More...
void	criAtomExHcaMx_Finalize (void)
	Finalize the HCA-MX. More...
void	criAtomExHcaMx_SetBusSendLevelByName (CriSint32 mixer_id, const CriChar8 *bus_name, CriFloat32 level)
	Setting the bus send level for the mixer. More...
void	criAtomExHcaMx_SetFrequencyRatio (CriSint32 mixer_id, CriFloat32 ratio)
	Set the output frequency adjustment ratio of a mixer. More...
void	criAtomExHcaMx_SetAsrRackId (CriSint32 mixer_id, CriSint32 rack_id)
	Specify the ASR Rack ID. More...

Detailed Description

Macro Definition Documentation

criAtomExHcaMx_SetDefaultConfig

#define criAtomExHcaMx_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->server_frequency = 60.0f;\
    (p_config)->num_mixers = 1;\
    (p_config)->max_voices = 16;\
    (p_config)->max_input_channels = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate = CRIATOM_DEFAULT_OUTPUT_SAMPLING_RATE;\
    (p_config)->output_channels = CRIATOM_DEFAULT_OUTPUT_CHANNELS;\
    (p_config)->output_sampling_rate = CRIATOM_DEFAULT_OUTPUT_SAMPLING_RATE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
}

Assign the default values to the configuration structure used to initialize HCA-MX.

Parameters

[out]

p_config

pointer to the configuration structure used for the HCA-MX initialization

Description:

Assigns the default values to the configuration structure ( CriAtomExHcaMxConfig ) that is passed to the criAtomExHcaMx_Initialize function.

See also

criAtomExHcaMx_Initialize, CriAtomExHcaMxConfig

Typedef Documentation

CriAtomExHcaMxConfig

typedef struct CriAtomExHcaMxConfigTag CriAtomExHcaMxConfig

Configuration structure used to initialize HCA-MXThis is a structure for specifying the operation specifications of HCA-MX.
This is specified as an argument to the criAtomExHcaMx_Initialize function.

Remarks:

If you want to use the default settings, set the default parameters in a structure using the criAtomExHcaMx_SetDefaultConfig macro, then specify the structure in the criAtomExHcaMx_Initialize function.

Attention

More members will be added in the future. Therefore, if you are not using the criAtomExHcaMx_SetDefaultConfig macro, make sure to initialize the structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)

See also

criAtomExHcaMx_Initialize, criAtomExHcaMx_SetDefaultConfig

Function Documentation

criAtomExHcaMx_CalculateWorkSize()

CriSint32 criAtomExHcaMx_CalculateWorkSize

(

const CriAtomExHcaMxConfig *

config

)

Calculate the size of the work buffer required to initialize HCA-MX.

Parameters

[in]

config

configuration structure used to initialize HCA-MX

Returns

CriSint32 work buffer size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Calculates the size of the work buffer required to initialize HCA-MX.
When criAtomExHcaMx_Initialize is called to initialize HCA-MX and no user allocator has been registered using the criAtomEx_SetUserAllocator macro, a memory buffer of the size returned by this function must be passed.

If this function fails to calculate the size, it returns -1.
To know the reason of the failure, refer to the error callback message.

Remarks:

The size of the working buffer required to initialize HCA-MX depends on the value of the parameters of the configuration structure ( CriAtomExHcaMxConfig ).

If NULL is passed for config, the default settings are used to calculate the size of the work buffer (i.e. the same parameters than when criAtomExHcaMx_SetDefaultConfig is used).
The config argument information is referenced only within the function.
It is not referenced after the function has exited, so there is no problem in freeing the config area after the function has been executed.

See also

criAtomEx_SetUserAllocator, criAtomExHcaMx_Initialize

criAtomExHcaMx_SetConfigForWorkSizeCalculation()

void criAtomExHcaMx_SetConfigForWorkSizeCalculation

(

const CriAtomExHcaMxConfig *

config

)

Set the configuration structure used to calculate the size of the work buffer.

Parameters

[in]

config

Configuration structure for the HCA-MX initialization

Description:

Tentatively registers a configuration structure ( CriAtomExHcaMxConfig structure) to calculate the size of the work buffer needed.

The size of the work buffer required to create a HCA-MX player depends on the value of the parameters in the configuration structure (i.e. when the criAtomExHcaMx_Initialize function is executed).
Therefore, the library must usually be initialized before being able to calculate the size of the work buffer required.
However, when this function is called to register a configuration structure for the HCA-MX initialization, the criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool function can be used without initializing the library.

Remarks:

When NULL is specified for the argument (config), the default settings (the same parameters than when criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool is called) will be used to calculate the size of the work buffer.

This function currently cannot be undone. Once executed, there is no way to restore the previous state (in which the library has not been initialized and the calculation of the size of the work buffer results in an error).
(It is still possible to overwrite the parameters by executing the function again.)

Attention

The configuration structure registered by this function is only used to calculate the size of the work buffer when the HCA-MX library has not been initialized.
Once the library is initialized, instead of the parameters of this configuration structure, the parameters specified during the initialization will be taken into account to calculate the size of the work buffer.
(If the parameters of the structure registered by this function differ from the parameters of the structure used for the library's initialization, the handle creation may fail due to an insufficient work buffer size.)

Example:

CriAtomExHcaMxConfig hca_mx_config;
 
// Tentatively register HCA-MX initialization parameters to calculate the size of the work buffer
criAtomExHcaMx_SetDefaultConfig(&hca_mx_config);
criAtomExHcaMx_SetConfigForWorkSizeCalculation(&hca_mx_config);
 
// Calculate the size of the work buffer needed to create a HCA-MX player
hca_mx_vp_work_size = criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool(NULL);
    ：

See also

criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool, criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool

criAtomExHcaMx_Initialize()

void criAtomExHcaMx_Initialize	(	const CriAtomExHcaMxConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Initialize HCA-MX.

Parameters

[in]	config	configuration structure to initializing HCA-MX
[in]	work	work buffer
[in]	work_size	work buffer size

Description:

Initializes HCA-MX.
By executing this function, it becomes possible to output HCA-MX data.

Remarks:

The size of the working buffer required to initialize HCA-MX depends on the values of the parameters of the configuration structure ( CriAtomExHcaMxConfig ).

When NULL is specified for the argument, the default settings are used for the initialization (i.e. the same parameters than when the criAtomExHcaMx_SetDefaultConfig macro is called).

The information in the configuration structure is only used during the initialization and is not referenced after that. Therefore, it is safe to release it once the function has returned.

Attention

The library must be initialized before this function is executed.

This is a blocking function.
Executing this function blocks the server processing of the Atom library for a while.
If this function is executed during audio playback, problems such as audio breakups may occur. Call this function only when a fluctuation in the load is acceptable, for example when loading a new level.
If you call this function, you must always call the criAtomExHcaMx_Finalize function later.
Do not call this function again until you have called the criAtomExHcaMx_Finalize function.

See also

criAtomEx_SetUserAllocator, criAtomExHcaMx_CalculateWorkSize

criAtomExHcaMx_Finalize()

void criAtomExHcaMx_Finalize

(

void

)

Finalize the HCA-MX.

Description:

Finalizes the HCA-MX.
By executing this function, the HCA-MX data output is stopped.
If an allocator was registered using the criAtomEx_SetUserAllocator macro, this function releases the memory allocated when HCA-MX was initialized.
(If a work buffer was passed when HCA-MX was initialized, the the work buffer can be released after this function is executed.)

Attention

This is a blocking function.
Executing this function blocks the server processing of the Atom library for a while.
If this function is executed during audio playback, problems such as audio breakups may occur. Call this function only when a fluctuation in the load is acceptable, for example when loading a new level.

See also

criAtomEx_SetUserAllocator, criAtomExHcaMx_Initialize

criAtomExHcaMx_SetBusSendLevelByName()

void criAtomExHcaMx_SetBusSendLevelByName	(	CriSint32	mixer_id,
		const CriChar8 *	bus_name,
		CriFloat32	level
	)

Setting the bus send level for the mixer.

Parameters

[in]	mixer_id	Mixer ID
[in]	bus_name	Bus name
[in]	level	Send level value (0.0f to 1.0f)

Description:

Sets the bus send level for the mixer.
By default, the HCA-MX decoding results are stored in the mixer and then sent to bus 0 at 1.0f level.
By using this function, decoding results can be sent to other buses.
(A different bus effect can be applied to each mixer.)

criAtomExHcaMx_SetFrequencyRatio()

void criAtomExHcaMx_SetFrequencyRatio	(	CriSint32	mixer_id,
		CriFloat32	ratio
	)

Set the output frequency adjustment ratio of a mixer.

Parameters

[in]	mixer_id	mixer ID
[in]	ratio	send level (0.25f to 4.0f)

Description:

Sets the output frequency adjustment ratio of a mixer.
The frequency adjustment ratio is the ratio of the audio data frequency to the playback frequency, and it is also equal to the scale factor of the playback speed.
If the frequency ratio is greater than 1.0f, the audio data will be played faster than the original sound, and if it is less than 1.0f, the audio data will be played slower than the original sound.
By using this function, the playback speed will be changed for all HCA-MX voices (playback of voice data encoded for HCA-MX) played by players using the target mixer. (When playing back HCA-MX voices, the playback speed setting of each individual player is ignored.)

criAtomExHcaMx_SetAsrRackId()

void criAtomExHcaMx_SetAsrRackId	(	CriSint32	mixer_id,
		CriSint32	rack_id
	)

Specify the ASR Rack ID.

Parameters

[in]	mixer_id	Mixer ID
[in]	rack_id	ASR Rack ID

Description:

Specifies the ASR Rack ID for the given mixer output.
This function changes the rack ID of the ASR for all the HCA-MX voices (audio data encoded for HCA-MX) played on the target mixer. (When playing back HCA-MX voices, the ASR Rack ID setting of each individual player is ignored.)

Attention

This function takes effect only when the ASR is used as the mixer's sound renderer type.
(Settings in this function are ignored for all other sound renderer types.)

See also

CriAtomExAsr_CreateRack