CriAtomHcaMx API

Data Structures
struct	CriAtomHcaMxConfigTag
	HCA-MX initialization configuration structureThis structure is used for specifying the behavior of the HCA-MX. This structure is specified as an argument of the criAtomHcaMx_Initialize function. More...

Macros
#define	criAtomHcaMx_SetDefaultConfig(p_config)
	Set default values for HCA-MX configuration structure. More...

Typedefs
typedef struct CriAtomHcaMxConfigTag	CriAtomHcaMxConfig
	HCA-MX initialization configuration structureThis structure is used for specifying the behavior of the HCA-MX. This structure is specified as an argument of the criAtomHcaMx_Initialize function. More...

Functions
CriSint32	criAtomHcaMx_CalculateWorkSize (const CriAtomHcaMxConfig *config)
	Calculate work area size required for initializing HCA-MX. More...
void	criAtomHcaMx_SetConfigForWorkSizeCalculation (const CriAtomHcaMxConfig *config)
	Set configuration structure for work area size calculation. More...
void	criAtomHcaMx_Initialize (const CriAtomHcaMxConfig *config, void *work, CriSint32 work_size)
	Initialize HCA-MX. More...
void	criAtomHcaMx_Finalize (void)
	Finalize HCA-MX. More...
void	criAtomHcaMx_SetBusSendLevelByName (CriSint32 mixer_id, const CriChar8 *bus_name, CriFloat32 level)
	Set mixer bus send level. More...
void	criAtomHcaMx_SetFrequencyRatio (CriSint32 mixer_id, CriFloat32 ratio)
	Set output frequency adjustment ratio of mixer. More...

Detailed Description

Macro Definition Documentation

criAtomHcaMx_SetDefaultConfig

#define criAtomHcaMx_SetDefaultConfig

(

p_config

)

Value:

{\
    (p_config)->server_frequency = 60.0f;\
    (p_config)->num_mixers = 1;\
    (p_config)->max_players = 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;\
}

Set default values for HCA-MX configuration structure.

Description:

Sets default values for the configuration structure ( CriAtomHcaMxConfig ) that is set for the criAtomHcaMx_Initialize function.

See also

criAtomHcaMx_Initialize, CriAtomHcaMxConfig

Typedef Documentation

CriAtomHcaMxConfig

typedef struct CriAtomHcaMxConfigTag CriAtomHcaMxConfig

HCA-MX initialization configuration structureThis structure is used for specifying the behavior of the HCA-MX.
This structure is specified as an argument of the criAtomHcaMx_Initialize function.

Remarks:

When using default settings, after setting default parameters for the structure using the criAtomHcaMx_SetDefaultConfig macro, specify the structure in the criAtomHcaMx_Initialize function.

Attention

More members will be added in the future. So, when not using the criAtomHcaMx_SetDefaultConfig macro, make sure to initialize the structure to zero before using it.
(Make sure that no indefinite value is set to any member of the structure.)

See also

criAtomHcaMx_Initialize, criAtomHcaMx_SetDefaultConfig

Function Documentation

criAtomHcaMx_CalculateWorkSize()

CriSint32 criAtomHcaMx_CalculateWorkSize

(

const CriAtomHcaMxConfig *

config

)

Calculate work area size required for initializing HCA-MX.

Parameters

[in]

config

configuration structure for initializing HCA-MX

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtains the work area size required for initializing HCA-MX.
If you are not using the criAtom_SetUserAllocator macro to register the allocator, but using the criAtomHcaMx_Initialize function to initialize HCA-MX, as much memory area as the size calculated by this function must be passed as the work area.

If work area size calculation fails, this function returns -1.
The reason for work area size calculation failure can be determined by viewing the error callback message.

Remarks:

The working memory size required for initializing HCA-MX varies depending on the contents of the configuration structure ( CriAtomHcaMxConfig ) for initializing HCA-MX.

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomHcaMx_SetDefaultConfig is used) are used for calculating the work area size.
Information in argument config is referenced only within the function.
It is not referenced after exiting the function and its area can be released after executing the function.

See also

criAtom_SetUserAllocator, criAtomHcaMx_Initialize

criAtomHcaMx_SetConfigForWorkSizeCalculation()

void criAtomHcaMx_SetConfigForWorkSizeCalculation

(

const CriAtomHcaMxConfig *

config

)

Set configuration structure for work area size calculation.

Parameters

[in]

config

Configuration structure for HCA-MX initialization

Description:

Tentatively registers a configuration structure ( CriAtomHcaMxConfig structure) for calculating the work area size.

The work area size required for HCA-MX player creation varies depending on the parameters of the structure specified for library initialization (i.e., when the criAtomHcaMx_Initialize function is executed).
Thus, in general, the library must be initialized before calculating the required work area size.
When this function is used to register a configuration structure for HCA-MX initialization, the criAtomPlayer_CalculateWorkSizeForHcaMxPlayer function can be used without initializing the library.

Remarks:

When NULL is specified for the argument (config), the default settings (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForHcaMxPlayer is used) will be used to calculate the work area size.

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

Attention

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

Example:

CriAtomHcaMxConfig hca_mx_config;
 
// Tentatively register HCA-MX initialization parameters for calculating the work area size
criAtomHcaMx_SetDefaultConfig(&hca_mx_config);
criAtomHcaMx_SetConfigForWorkSizeCalculation(&hca_mx_config);
 
// Calculate the work area size for creating a HCA-MX player
hca_mx_vp_work_size = criAtomPlayer_CalculateWorkSizeForHcaMxPlayer(NULL);
    ：

See also

criAtomPlayer_CalculateWorkSizeForHcaMxPlayer, criAtomPlayer_SetDefaultConfigForHcaMxPlayer

criAtomHcaMx_Initialize()

void criAtomHcaMx_Initialize	(	const CriAtomHcaMxConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Initialize HCA-MX.

Parameters

[in]	config	configuration structure for initializing HCA-MX
[in]	work	work area
[in]	work_size	work area size

Description:

Initializes HCA-MX.
By executing this function, the function for outputting HCA-MX data is started.

Remarks:

The working memory size required for initializing HCA-MX varies depending on the contents of the configuration structure ( CriAtomHcaMxConfig ) for initializing HCA-MX.

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomHcaMx_SetDefaultConfig is used) are used for initialization.

Information in argument config is referenced only within the function.
It is not referenced after exiting the function and its area can be released after executing the function.

Attention

You must initialize the library before executing this function.

This function is a blocking function.
Once this function is executed, server processing of the Atom library is blocked for a while.
If this function is executed during audio playback, problems such as interruption of playback may occur. Call this function only when load fluctuations are acceptable, for example, when a game scene is changed.
After executing this function, always execute the criAtomHcaMx_Finalize function.
Also, before executing the criAtomHcaMx_Finalize function, do not execute this function again.

See also

criAtom_SetUserAllocator, criAtomHcaMx_CalculateWorkSize

criAtomHcaMx_Finalize()

void criAtomHcaMx_Finalize

(

void

)

Finalize HCA-MX.

Description:

Finalizes HCA-MX.
By executing this function, output of HCA-MX data is stopped.
If the allocator is registered with the criAtom_SetUserAllocator macro, this function releases the memory area allocated when HCA-MX is initialized.
(If you pass a work area during HCA-MX initialization, the work area can be released after executing this function.)

Attention

This function is a blocking function.
Once this function is executed, server processing of the Atom library is blocked for a while.
If this function is executed during audio playback, problems such as interruption of playback may occur. Call this function only when load fluctuations are acceptable, for example, when a game scene is changed.

See also

criAtom_SetUserAllocator, criAtomHcaMx_Initialize

criAtomHcaMx_SetBusSendLevelByName()

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

Set mixer bus send level.

Parameters

[in]	mixer_id	mixer id
[in]	bus_name	Bus name
[in]	level	send level (0.0f to 1.0f)

Description:

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

criAtomHcaMx_SetFrequencyRatio()

void criAtomHcaMx_SetFrequencyRatio	(	CriSint32	mixer_id,
		CriFloat32	ratio
	)

Set output frequency adjustment ratio of mixer.

Parameters

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

Description:

This function 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 is equal to the scale factor of the playback speed.
When the frequency ratio exceeds 1.0f, sound data is played back faster than the original sound. When the ratio is less than 1.0f, sound data is played back slower than the original sound.
This function enables changing the playback speed of all the players connected to the same mixer. (Disables changing the playback speed of the players individually.)