CRI ADX  Last Updated: 2024-07-17 10:47 p
CriAtomExVoicePool API

Data Structures

struct  CriAtomExStandardVoicePoolConfigTag
 Configuration structure used when creating a standard Voice Pool. More...
 
struct  CriAtomExAdxVoicePoolConfigTag
 Configuration structure used when creating an ADX Voice Pool. More...
 
struct  CriAtomExHcaVoicePoolConfigTag
 Configuration structure used when creating a HCA Voice Pool. More...
 
struct  CriAtomExHcaMxVoicePoolConfigTag
 Configuration structure used when creating a HCA-MX Voice Pool. More...
 
struct  CriAtomExWaveVoicePoolConfigTag
 Configuration structure used when creating a Wave Voice Pool. More...
 
struct  CriAtomExAiffVoicePoolConfigTag
 Configuration structure used when creating an AIFF Voice Pool. More...
 
struct  CriAtomExRawPcmVoicePoolConfigTag
 Configuration structure used when creating a raw PCM Voice Pool. More...
 
struct  CriAtomExInstrumentVoicePoolConfigTag
 Configuration structure used when creating an Instrument Voice Pool. More...
 

Macros

#define CRIATOMEX_DEFAULT_VOICES_PER_POOL   (8)
 Default number of voices. More...
 
#define CRIATOMEX_MIN_VOICES_PER_POOL   (1)
 Minimum Voices. More...
 
#define CRIATOMEX_MAX_VOICES_PER_POOL   (32767)
 Maximum Voices. More...
 
#define criAtomExVoicePool_SetDefaultConfigForStandardVoicePool(p_config)
 Assign the default values to the configuration structure used to create a standard Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForAdxVoicePool(p_config)
 Assign the default values to the configuration structure used to create an ADX Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForHcaVoicePool(p_config)
 Assign the default values to the configuration structure used to create an HCA Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool(p_config)
 Assign the default values to the configuration structure used to create a HCA-MX Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForWaveVoicePool(p_config)
 Assign the default values to the configuration structure used to create a Wave Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForAiffVoicePool(p_config)
 Assign the default values to the configuration structure used to create an AIFF Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool(p_config)
 Assign the default values to the configuration structure used to create a raw PCM Voice Pool. More...
 
#define criAtomExVoicePool_SetDefaultConfigForInstrumentVoicePool(p_config)
 Assign the default values to the configuration structure used to create an Instrument Voice Pool. More...
 

Typedefs

typedef struct CriAtomExVoicePoolTag * CriAtomExVoicePoolHn
 Voice Pool handle. More...
 
typedef CriUint32 CriAtomExVoicePoolIdentifier
 Voice Pool identifier. More...
 
typedef struct CriAtomExStandardVoicePoolConfigTag CriAtomExStandardVoicePoolConfig
 Configuration structure used when creating a standard Voice Pool. More...
 
typedef struct CriAtomExAdxVoicePoolConfigTag CriAtomExAdxVoicePoolConfig
 Configuration structure used when creating an ADX Voice Pool. More...
 
typedef struct CriAtomExHcaVoicePoolConfigTag CriAtomExHcaVoicePoolConfig
 Configuration structure used when creating a HCA Voice Pool. More...
 
typedef struct CriAtomExHcaMxVoicePoolConfigTag CriAtomExHcaMxVoicePoolConfig
 Configuration structure used when creating a HCA-MX Voice Pool. More...
 
typedef struct CriAtomExWaveVoicePoolConfigTag CriAtomExWaveVoicePoolConfig
 Configuration structure used when creating a Wave Voice Pool. More...
 
typedef struct CriAtomExAiffVoicePoolConfigTag CriAtomExAiffVoicePoolConfig
 Configuration structure used when creating an AIFF Voice Pool. More...
 
typedef struct CriAtomExRawPcmVoicePoolConfigTag CriAtomExRawPcmVoicePoolConfig
 Configuration structure used when creating a raw PCM Voice Pool. More...
 
typedef struct CriAtomExInstrumentVoicePoolConfigTag CriAtomExInstrumentVoicePoolConfig
 Configuration structure used when creating an Instrument Voice Pool. More...
 
typedef void(* CriAtomExVoicePoolCbFunc) (void *obj, CriAtomExVoicePoolHn pool)
 Voice pool callback function type. More...
 

Functions

CriSint32 criAtomExVoicePool_CalculateWorkSizeForStandardVoicePool (const CriAtomExStandardVoicePoolConfig *config)
 Calculate the size of the work buffer required to create a standard Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateStandardVoicePool (const CriAtomExStandardVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create a standard Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForAdxVoicePool (const CriAtomExAdxVoicePoolConfig *config)
 Calculate the size of the work buffer required to create an ADX Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateAdxVoicePool (const CriAtomExAdxVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create an ADX Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForHcaVoicePool (const CriAtomExHcaVoicePoolConfig *config)
 Calculate the size of the work buffer required to create an HCA Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateHcaVoicePool (const CriAtomExHcaVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create an HCA Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool (const CriAtomExHcaMxVoicePoolConfig *config)
 Calculate the size of the work buffer required to create an HCA-MX Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateHcaMxVoicePool (const CriAtomExHcaMxVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create an HCA-MX Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForWaveVoicePool (const CriAtomExWaveVoicePoolConfig *config)
 alculate the size of the work buffer required to create a Wave Voice Pool More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateWaveVoicePool (const CriAtomExWaveVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create a Wave Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForAiffVoicePool (const CriAtomExAiffVoicePoolConfig *config)
 Calculate the size of the work buffer required to create an AIFF Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateAiffVoicePool (const CriAtomExAiffVoicePoolConfig *config, void *work, CriSint32 work_size)
 Creates an AIFF Voice Pool. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForRawPcmVoicePool (const CriAtomExRawPcmVoicePoolConfig *config)
 Calculate the size of the work buffer required to create a raw PCM Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateRawPcmVoicePool (const CriAtomExRawPcmVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create a raw PCM Voice Pool. More...
 
CriAtomExVoicePoolHn criAtomExVoicePool_AllocateInstrumentVoicePool (const CriAtomExInstrumentVoicePoolConfig *config, void *work, CriSint32 work_size)
 Create an Instrument Voice Pool. More...
 
void criAtomExVoicePool_Free (CriAtomExVoicePoolHn pool)
 Destroy a Voice Pool. More...
 
void criAtomExVoicePool_FreeAll (void)
 Destroy all the Voice Pools. More...
 
void criAtomExVoicePool_EnumerateVoicePools (CriAtomExVoicePoolCbFunc func, void *obj)
 Voice Pool Enumeration. More...
 
void criAtomExVoicePool_GetNumUsedVoices (CriAtomExVoicePoolHn pool, CriSint32 *cur_num, CriSint32 *limit)
 Get voice usage. More...
 
CriAtomPlayerHn criAtomExVoicePool_GetPlayerHandle (CriAtomExVoicePoolHn pool, CriSint32 index)
 Getting the Player Handle. More...
 
CriSint32 criAtomExVoicePool_CalculateWorkSizeForInstrumentVoicePool (const CriAtomExInstrumentVoicePoolConfig *config)
 Calculation of work area size for creating instrument voice pool. More...
 

Detailed Description

Macro Definition Documentation

◆ CRIATOMEX_DEFAULT_VOICES_PER_POOL

#define CRIATOMEX_DEFAULT_VOICES_PER_POOL   (8)

Default number of voices.

Description:
Default value for the number of voices in a Voice Pool.
When a Voice Pool is created using the default settings, as many voices as specified by CRIATOMEX_DEFAULT_VOICES_PER_POOL are reserved.
See also
criAtomExVoicePool_SetDefaultConfigForStandardVoicePool

◆ CRIATOMEX_MIN_VOICES_PER_POOL

#define CRIATOMEX_MIN_VOICES_PER_POOL   (1)

Minimum Voices.

Description:
The minimum number of voices per voice pool.

◆ CRIATOMEX_MAX_VOICES_PER_POOL

#define CRIATOMEX_MAX_VOICES_PER_POOL   (32767)

Maximum Voices.

Description:
The maximum number of voices per voice pool.

◆ criAtomExVoicePool_SetDefaultConfigForStandardVoicePool

#define criAtomExVoicePool_SetDefaultConfigForStandardVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForStandardPlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}
#define CRIATOMEX_DEFAULT_VOICES_PER_POOL
Default number of voices.
Definition: cri_le_atom_ex.h:117

Assign the default values to the configuration structure used to create a standard Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of a standard Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExStandardVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateStandardVoicePool function.
See also
CriAtomExStandardVoicePoolConfig, criAtomExVoicePool_AllocateStandardVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForAdxVoicePool

#define criAtomExVoicePool_SetDefaultConfigForAdxVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForAdxPlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}

Assign the default values to the configuration structure used to create an ADX Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of an ADX Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExAdxVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateAdxVoicePool function.
See also
CriAtomExAdxVoicePoolConfig, criAtomExVoicePool_AllocateAdxVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForHcaVoicePool

#define criAtomExVoicePool_SetDefaultConfigForHcaVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForHcaPlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}

Assign the default values to the configuration structure used to create an HCA Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of an HCA Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExHcaVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateHcaVoicePool function.
See also
CriAtomExHcaVoicePoolConfig, criAtomExVoicePool_AllocateHcaVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool

#define criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForHcaMxPlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}

Assign the default values to the configuration structure used to create a HCA-MX Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of a HCA-MX Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExHcaMxVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateHcaMxVoicePool function.
See also
CriAtomExHcaMxVoicePoolConfig, criAtomExVoicePool_AllocateHcaMxVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForWaveVoicePool

#define criAtomExVoicePool_SetDefaultConfigForWaveVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForWavePlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}

Assign the default values to the configuration structure used to create a Wave Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of a Wave Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExWaveVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateWaveVoicePool function.
See also
CriAtomExWaveVoicePoolConfig, criAtomExVoicePool_AllocateWaveVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForAiffVoicePool

#define criAtomExVoicePool_SetDefaultConfigForAiffVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForAiffPlayer(&(p_config)->player_config);\
(p_config)->is_streaming_only = CRI_FALSE;\
(p_config)->min_channels = 1;\
}

Assign the default values to the configuration structure used to create an AIFF Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of an AIFF Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExAiffVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateAiffVoicePool function.
See also
CriAtomExAiffVoicePoolConfig, criAtomExVoicePool_AllocateAiffVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool

#define criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForRawPcmPlayer(&(p_config)->player_config);\
}

Assign the default values to the configuration structure used to create a raw PCM Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of a raw PCM Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExRawPcmVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateRawPcmVoicePool function.
See also
CriAtomExRawPcmVoicePoolConfig, criAtomExVoicePool_AllocateRawPcmVoicePool

◆ criAtomExVoicePool_SetDefaultConfigForInstrumentVoicePool

#define criAtomExVoicePool_SetDefaultConfigForInstrumentVoicePool (   p_config)
Value:
{\
(p_config)->identifier = 0;\
(p_config)->num_voices = CRIATOMEX_DEFAULT_VOICES_PER_POOL;\
criAtomPlayer_SetDefaultConfigForInstrumentPlayer(&(p_config)->player_config);\
}

Assign the default values to the configuration structure used to create an Instrument Voice Pool.

Parameters
[out]p_configpointer to the configuration structure used for the creation of an Instrument Voice Pool
Description:
Assigns the default values to the configuration structure ( CriAtomExInstrumentVoicePoolConfig ) that is passed to the criAtomExVoicePool_AllocateInstrumentVoicePool function.
Attention:
The creation of the pool will fail if the default value is left unchanged.
The user must set the instrument name of the registered interface.
See also
CriAtomExInstrumentVoicePoolConfig, criAtomExVoicePool_AllocateInstrumentVoicePool

Typedef Documentation

◆ CriAtomExVoicePoolHn

typedef struct CriAtomExVoicePoolTag* CriAtomExVoicePoolHn

Voice Pool handle.

Description:
Handle used to control a Voice Pool.
When a Voice Pool is created by using a function such as criAtomExVoicePool_AllocateStandardVoicePool , a handle if this type is returned.
The Voice Pool handle can then be used to get information about the Voice Pool or to release it.
See also
criAtomExVoicePool_AllocateStandardVoicePool, criAtomExVoicePool_Free

◆ CriAtomExVoicePoolIdentifier

typedef CriUint32 CriAtomExVoicePoolIdentifier

Voice Pool identifier.

Description:
An unique ID identifying a Voice Pool.
To reference a specific Voice Pool across the application it is necessary to use an identifier of this type.
Remarks:
A Voice Pool identifier must be specified when dealing with:
  • a Voice Pool (the ID is specified in the configuration structure used to create the Voice Pool)
  • a Player (the ID is passed to the PLayer by using the criAtomExPlayer_SetVoicePoolIdentifier function) By setting the identifier for both the Voice Pool and the Player, the Player can then acquire voices from the relevant Voice Pool.

    A single Voice Pool identifier can be specified for multiple Voice Pools.
See also
CriAtomExStandardVoicePoolConfig, criAtomExPlayer_SetVoicePoolIdentifier

◆ CriAtomExStandardVoicePoolConfig

Configuration structure used when creating a standard Voice Pool.

Description:
Structure used to configure a standard Voice Pool.
It is passed to the criAtomExVoicePool_AllocateStandardVoicePool function.
The maximum number of voices you can pool is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForStandardVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateStandardVoicePool, criAtomExVoicePool_SetDefaultConfigForStandardVoicePool

◆ CriAtomExAdxVoicePoolConfig

Configuration structure used when creating an ADX Voice Pool.

Description:
Structure used to configure an ADX Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateAdxVoicePool function.
The maximum number of voices you can pool is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForAdxVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateAdxVoicePool, criAtomExVoicePool_SetDefaultConfigForAdxVoicePool

◆ CriAtomExHcaVoicePoolConfig

Configuration structure used when creating a HCA Voice Pool.

Description:
Structure used to configure an HCA Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateHcaVoicePool function.
The maximum number of voices you can pool is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForHcaVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateHcaVoicePool, criAtomExVoicePool_SetDefaultConfigForHcaVoicePool

◆ CriAtomExHcaMxVoicePoolConfig

Configuration structure used when creating a HCA-MX Voice Pool.

Description:
Structure used to configure a HCA-MX Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateHcaMxVoicePool function.
The maximum number of voices you can pool is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateHcaMxVoicePool, criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool

◆ CriAtomExWaveVoicePoolConfig

Configuration structure used when creating a Wave Voice Pool.

Description:
Structure used to configure a Wave Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateWaveVoicePool function.
The maximum number of voices that can be pooled is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum number is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForWaveVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateWaveVoicePool, criAtomExVoicePool_SetDefaultConfigForWaveVoicePool

◆ CriAtomExAiffVoicePoolConfig

Configuration structure used when creating an AIFF Voice Pool.

Description:
Structure used to configure an AIFF Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateAiffVoicePool function.
The maximum number of voices that can be pooled is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum number is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForAiffVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateAiffVoicePool, criAtomExVoicePool_SetDefaultConfigForAiffVoicePool

◆ CriAtomExRawPcmVoicePoolConfig

Configuration structure used when creating a raw PCM Voice Pool.

Description:
Structure used to configure a raw PCM Voice Pool.
Pass it as an argument to the criAtomExVoicePool_AllocateRawPcmVoicePool function.
The maximum number of voices that can be pooled is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum number is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateRawPcmVoicePool, criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool

◆ CriAtomExInstrumentVoicePoolConfig

Configuration structure used when creating an Instrument Voice Pool.

Description:
Structure used to configure an Instrument Voice Pool.
Pass this as an argument to the criAtomExVoicePool_AllocateInstrumentVoicePool function.
The maximum number of voices that can be pooled is CRIATOMEX_MAX_VOICES_PER_POOL , and the minimum is CRIATOMEX_MIN_VOICES_PER_POOL .
Attention
More members will be added in the future, so if you are not using the criAtomExVoicePool_SetDefaultConfigForInstrumentVoicePool macro, make sure to initialize the whole structure to zero before using it.
(Make sure that no member of the structure has an undefined value.)
See also
criAtomExVoicePool_AllocateInstrumentVoicePool, criAtomExVoicePool_SetDefaultConfigForInstrumentVoicePool

◆ CriAtomExVoicePoolCbFunc

typedef void(* CriAtomExVoicePoolCbFunc) (void *obj, CriAtomExVoicePoolHn pool)

Voice pool callback function type.

Parameters
[in]objUser-specified object
[in]poolVoice pool handle
Description:
This is the type of callback function used to enumerate voice pools.
By registering a callback function of this function type in the criAtomExVoicePool_EnumerateVoicePools function, you can receive created voice pools by callback.

Please note that if you block processing within this callback function for a long period of time, problems such as sound dropouts may occur.
See also
criAtomExVoicePool_EnumerateVoicePools

Function Documentation

◆ criAtomExVoicePool_CalculateWorkSizeForStandardVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForStandardVoicePool ( const CriAtomExStandardVoicePoolConfig config)

Calculate the size of the work buffer required to create a standard Voice Pool.

Parameters
[in]configconfiguration structure to create a standard Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create a standard Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateStandardVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExStandardVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForStandardVoicePool macro).
The information in the configuration structure is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Attention
Since the size of the work buffer depends on the parameters specified when initializing the library (i.e. when executing the criAtomEx_Initialize function), the library must be initialized before executing this function.
See also
criAtomExVoicePool_AllocateStandardVoicePool

◆ criAtomExVoicePool_AllocateStandardVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateStandardVoicePool ( const CriAtomExStandardVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create a standard Voice Pool.

Parameters
[in]configconfiguration structure used to create a standard Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates a standard Voice Pool.
(A standard voice is a voice that supports the playback of both ADX and HCA data.)

When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForStandardVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play ADX and HCA data.
When an AtomEx player needs to play back ADX or HCA data (or a Cue containing ADX or HCA data), it will acquire a voice from the standard Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExStandardVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExStandardVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, there is a possibility that a voice from the stereo voice pool will be used when playing monaural data.

Lowering the sampling rate (player_config.max_sampling_rate of the CriAtomExStandardVoicePoolConfig structure) also reduces the amount of memory required for a Voice Pool, but again, data with a higher sampling rate will become unplayable.
(Only data with a sampling rate equal to or lower than the specified value can be played back.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExStandardVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

When an AtomEx player wants to play back data and all the voices of the Voice Pool are already in use, some voices may be stolen based on a priority system.
(For details about the voice priority, see the description of the criAtomExPlayer_SetVoicePriority function .)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

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.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This is a blocking function.
The time required to create a Voice Pool varies depending on the platform.
If this function is executed during a game loop or at anytime requiring regular screen updates, the processing is blocked by the millisecond and frames may be dropped.
Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when loading a new level.
See also
CriAtomExStandardVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForStandardVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForAdxVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForAdxVoicePool ( const CriAtomExAdxVoicePoolConfig config)

Calculate the size of the work buffer required to create an ADX Voice Pool.

Parameters
[in]configconfiguration structure to create an ADX Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create an ADX Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateAdxVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExAdxVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForAdxVoicePool macro).
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.
Attention
The size of the work area changes depending on the parameters specified when the library is initialized (when the criAtomEx_Initialize function is executed).
Therefore, the library must be initialized before executing this function.
See also
criAtomExVoicePool_AllocateAdxVoicePool

◆ criAtomExVoicePool_AllocateAdxVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateAdxVoicePool ( const CriAtomExAdxVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create an ADX Voice Pool.

Parameters
[in]configconfiguration structure used to create an ADX Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates an ADX Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForAdxVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play ADX data.
When an AtomEx player needs to play back ADX data (or a Cue containing ADX data), it will acquire a voice from the Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExAdxVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExAdxVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, it is possible that a voice from the stereo voice pool may be used when playing mono data.

Lowering the sampling rate (player_config.max_sampling_rate of the CriAtomExAdxVoicePoolConfig structure) also reduces the amount of memory required for a Voice Pool, but again, data with a higher sampling rate will become unplayable.
(Only data with a sampling rate equal to or lower than the specified value can be played back.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExAdxVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

When an AtomEx player wants to play back data and all the voices of the Voice Pool are already in use, some voices may be stolen based on a priority system.
(For details about the voice priority, see the description of the criAtomExPlayer_SetVoicePriority function .)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This is a blocking function.
The time required to create a Voice Pool varies depending on the platform.
If this function is executed during a game loop or at anytime requiring regular screen updates, the processing is blocked by the millisecond and frames may be dropped.
Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when loading a new level.
See also
CriAtomExAdxVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForAdxVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForHcaVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForHcaVoicePool ( const CriAtomExHcaVoicePoolConfig config)

Calculate the size of the work buffer required to create an HCA Voice Pool.

Parameters
[in]configconfiguration structure to create an HCA Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create an HCA Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateHcaVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExHcaVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForHcaVoicePool macro).
The information in the configuration structure is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Attention
The size of the work area changes depending on the parameters specified when the library is initialized (when the criAtomEx_Initialize function is executed).
Therefore, you must initialize the library before executing this function.
See also
criAtomExVoicePool_AllocateHcaVoicePool

◆ criAtomExVoicePool_AllocateHcaVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateHcaVoicePool ( const CriAtomExHcaVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create an HCA Voice Pool.

Parameters
[in]configconfiguration structure used to create an HCA Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates an HCA Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForHcaVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play HCA data.
When an AtomEx player needs to play back HCA data (or a Cue containing HCA data), it will acquire a voice from the HCA Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExHcaVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExHcaVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, there is a possibility that a voice from the stereo voice pool will be used when playing monaural data.

Lowering the sampling rate (player_config.max_sampling_rate of the CriAtomExHcaVoicePoolConfig structure) also reduces the amount of memory required for a Voice Pool, but again, data with a higher sampling rate will become unplayable.
(Only data with a sampling rate equal to or lower than the specified value can be played back.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExHcaVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

When an AtomEx player wants to play back data and all the voices of the Voice Pool are already in use, some voices may be stolen based on a priority system.
(For details about the voice priority, see the description of the criAtomExPlayer_SetVoicePriority function .)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This is a blocking function.
The time required to create a Voice Pool varies depending on the platform.
If this function is executed during a game loop or at anytime requiring regular screen updates, the processing is blocked by the millisecond and frames may be dropped.
Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when loading a new level.
See also
CriAtomExHcaVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForHcaVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool ( const CriAtomExHcaMxVoicePoolConfig config)

Calculate the size of the work buffer required to create an HCA-MX Voice Pool.

Parameters
[in]configconfiguration structure to create an HCA-MX Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create an HCA-MX Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateHcaMxVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExHcaMxVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForHcaMxVoicePool macro).
The information in the configuration structure is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Attention
Since the size of the work buffer depends on the parameters specified when initializing HCA-MX (i.e. when executing the criAtomExHcaMx_Initialize function), HCA-MX must be initialized before executing this function.
See also
criAtomExVoicePool_AllocateHcaMxVoicePool

◆ criAtomExVoicePool_AllocateHcaMxVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateHcaMxVoicePool ( const CriAtomExHcaMxVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create an HCA-MX Voice Pool.

Parameters
[in]configconfiguration structure used to create an HCA-MX Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Create an HCA-MX Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play HCA-MX data.
When an AtomEx player needs to play back HCA-MX data (or a Cue containing HCA-MX data), it will acquire a voice from the HCA-MX Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExHcaMxVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExHcaMxVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, there is a possibility that a voice from the stereo voice pool will be used when playing mono data.

Regarding the sampling rate (player_config.max_sampling_rate in the CriAtomExHcaMxVoicePoolConfig structure), you can also reduce the memory size required for the voice pool by lowering the value, but you will not be able to play HCA-MX data with a sampling rate other than the specified one.
(Unlike other voice pools, only data with the same sampling rate can be played.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExHcaMxVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

If all voices in the voice pool are in use when the AtomEx player plays the data, voice priority will be used to control voice output.
(For details on voice priority, please refer to the description of the criAtomExPlayer_SetVoicePriority function.)
Attention
HCA-MX must be initialized (by calling the criAtomExHcaMx_Initialize function) before being able to call this function.
Furthermore, you cannot play more HCA-MX voices than the number specified when executing the criAtomExHcaMx_Initialize function.
When creating an HCA-MX Voice Pool, make sure that the value of num_voices in the CriAtomExHcaMxVoicePoolConfig structure does not exceed the value of max_voices in the CriAtomExHcaMxConfig structure (specified during HCA-MX initialization).

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is
  • not referenced after that. Therefore, it is safe to release it once the function has returned.
    Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
    When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

    This is a blocking function.
    The time required to create a Voice Pool varies depending on the platform.
    If this function is executed during a game loop or at anytime requiring regular screen updates, the processing is blocked by the millisecond and frames may be dropped.
    Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when loading a new level.
See also
CriAtomExHcaMxVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForHcaMxVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForWaveVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForWaveVoicePool ( const CriAtomExWaveVoicePoolConfig config)

alculate the size of the work buffer required to create a Wave Voice Pool

Parameters
[in]configconfiguration structure to create a Wave Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create a Wave Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateWaveVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExWaveVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForWaveVoicePool macro).
The information in the configuration structure is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Attention
Since the size of the work buffer depends on the parameters specified when initializing the library (i.e. when executing the criAtomEx_Initialize function), the library must be initialized before executing this function.
See also
criAtomExVoicePool_AllocateWaveVoicePool

◆ criAtomExVoicePool_AllocateWaveVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateWaveVoicePool ( const CriAtomExWaveVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create a Wave Voice Pool.

Parameters
[in]configconfiguration structure used to create a Wave Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates a Wave Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForWaveVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play Wave data.
When an AtomEx player needs to play back Wave data (or a Cue containing Wave data), it will acquire a voice from the Wave Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExWaveVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExWaveVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, there is a possibility that a voice from the stereo voice pool will be used when playing mono data.

Lowering the sampling rate (player_config.max_sampling_rate of the CriAtomExWaveVoicePoolConfig structure) also reduces the amount of memory required for a Voice Pool, but again, data with a higher sampling rate will become unplayable.
(Only data with a sampling rate equal to or lower than the specified value can be played back.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExWaveVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

If all voices in the voice pool are in use when the AtomEx player plays the data, voice priority will be used to control voice output.
(For details about voice priority, please refer to the description of the criAtomExPlayer_SetVoicePriority function.)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This function returns after completion.
The time it takes to create a voice pool varies depending on the platform.
If this function is executed during a game loop or other time when a screen update is required, processing may be blocked for milliseconds, resulting in dropped frames.
Please create/destroy voice pools at times when load fluctuations can be tolerated, such as when switching scenes.

Only uncompressed PCM data of 32 bits or less can be played.
When performing loop playback, the smpl chunk must be placed before the data chunk for audio data to be streamed.
See also
CriAtomExWaveVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForWaveVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForAiffVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForAiffVoicePool ( const CriAtomExAiffVoicePoolConfig config)

Calculate the size of the work buffer required to create an AIFF Voice Pool.

Parameters
[in]configconfiguration structure to create an AIFF Voice Pool
Returns
CriSint32 Work buffer size
Return values
0or greater Process finished normally.
-1Error occurred.
Description:
Calculates the size of the work buffer required to create an AIFF Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateAiffVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExAiffVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForAiffVoicePool macro).
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.
Attention
Since the size of the work buffer depends on the parameters specified when initializing the library (i.e. when executing the criAtomEx_Initialize function), the library must be initialized before executing this function.
See also
criAtomExVoicePool_AllocateAiffVoicePool

◆ criAtomExVoicePool_AllocateAiffVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateAiffVoicePool ( const CriAtomExAiffVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Creates an AIFF Voice Pool.

Parameters
[in]configconfiguration structure used to create an AIFF Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates an AIFF Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForAiffVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play AIFF data.
When an AtomEx player needs to play back AIFF data (or a Cue containing AIFF data), it will acquire a voice from the AIFF Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExAiffVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of audio channels (player_config.max_channels in the CriAtomExAiffVoicePoolConfig structure) specified when creating a Voice Pool is the number of audio data channels that can be played using the voices in the Voice Pool.
Decreasing the number of channels reduces the amount of memory required to create the Voice Pool, but data having more channels will become unplayable.
For example, if you create a mono Voice Pool, stereo data cannot be played.
(When playing back stereo data, an AtomEx player can only acquire voices from Voice Pools that support stereo playback.)
However, if you create a stereo voice pool, there is a possibility that a voice from the stereo voice pool will be used when playing mono data.

Lowering the sampling rate (player_config.max_sampling_rate of the CriAtomExAiffVoicePoolConfig structure) also reduces the amount of memory required for a Voice Pool, but again, data with a higher sampling rate will become unplayable.
(Only data with a sampling rate equal to or lower than the specified value can be played back.)

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExAiffVoicePoolConfig structure), also affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

If all voices in the voice pool are in use when the AtomEx player plays the data, voice priority will be used to control voice output.
(For details on voice priority, please refer to the description of the criAtomExPlayer_SetVoicePriority function.)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This function returns to completion.
The time it takes to create a voice pool varies depending on the platform.
If you execute this function during a game loop or other timing that requires updating the screen, the process may be blocked for milliseconds, resulting in dropped frames.
Please create/destroy voice pools at times when load fluctuations can be tolerated, such as when switching scenes.

Only uncompressed PCM data of 32 bits or less can be played.
When performing loop playback, the INST chunk for the audio data for stream playback must be placed before the SSND chunk.
See also
CriAtomExAiffVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForAiffVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_CalculateWorkSizeForRawPcmVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForRawPcmVoicePool ( const CriAtomExRawPcmVoicePoolConfig config)

Calculate the size of the work buffer required to create a raw PCM Voice Pool.

Parameters
[in]configconfiguration structure to create a raw PCM Voice Pool
Returns
CriSint32 work buffer size
Return values
>=0 successfully completed
-1error occurred
Description:
Calculates the size of the work buffer required to create a raw PCM Voice Pool.
If no user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, you must pass a work buffer of the size returned by this function when creating a Voice Pool with the criAtomExVoicePool_AllocateRawPcmVoicePool function.

If the function fails to calculate the size of the work buffer, it returns -1.
To know the reason of the failure, refer to the error callback message.
Remarks:
The size of the work buffer required for the creation of a Voice Pool depends on the values of the parameters in the configuration structure ( CriAtomExRawPcmVoicePoolConfig ).

When NULL is specified for the argument, the size is calculated using the default settings (i.e. the same parameters than when using the criAtomExVoicePool_SetDefaultConfigForRawPcmVoicePool macro).
The information in the configuration structure is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Attention
The size of the work area changes depending on the parameters specified when the library is initialized (when the criAtomEx_Initialize function is executed).
Therefore, you must initialize the library before executing this function.
See also
criAtomExVoicePool_AllocateRawPcmVoicePool

◆ criAtomExVoicePool_AllocateRawPcmVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateRawPcmVoicePool ( const CriAtomExRawPcmVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create a raw PCM Voice Pool.

Parameters
[in]configconfiguration structure used to create a raw PCM Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExVoicePoolHn Voice Pool handle
Description:
Creates a raw PCM Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForRawPcmVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play raw PCM data.
When an AtomEx player needs to play back raw PCM data (or a Cue containing raw PCM data), it will acquire a voice from the raw PCM Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
Remarks:
The number of voices created for the Voice Pool will correspond to the number specified in the configuration structure for the Voice Pool creation (i.e. num_voices in CriAtomExRawPcmVoicePoolConfig).
The greater the number of voices created, the greater the number of voices that can be played back simultaneously, but also the larger the amount of memory required.

When creating a Voice Pool, in addition to specifying the number of voices, you can also specify the number of audio channels that can be played, the sampling frequency and the availability of streaming playback.

The number of sound channels specified when creating a Voice Pool (player_config.max_channels in the CriAtomExRawPcmVoicePoolConfig structure) corresponds to the number of channels expected from the data in raw PCM format.

Similarly, the sampling rate set for player_config.max_sampling_rate in the CriAtomExRawPcmVoicePoolConfig structure specifies the sampling rate of the data provided in raw PCM format.

The availability of streaming playback (as specified by the player_config.streaming_flag in the CriAtomExRawPcmVoicePoolConfig structure), affects the amount of memory required by a Voice Pool, with Voice Pools that only support in-memory playback requiring less memory than Voice Pools that support streaming playback.

When an AtomEx player wants to play back data and all the raw PCM voices of the Voice Pool are already in use, some voices may be stolen based on a priority system.
(For details about the voice priority, see the description of the criAtomExPlayer_SetVoicePriority function .)
Attention
The library must be initialized before executing this function.

If a work buffer is passed to this function, it must be maintained by the application until the Voice Pool is destroyed.
(Do not write into the work buffer or release its memory.)

The information in the configuration structure that is passed is only used within this function and is not referenced after that. Therefore, it is safe to release it once the function has returned.
Voice Pools for streaming playback internally allocate a loader (CriFsLoaderHn) for each voice.
When creating a Voice Pool for streaming playback, the Atom library (or CRI File System library) must be initialized with settings that allow the allocation of as many loaders as there are voices.

This is a blocking function.
The time required to create a Voice Pool varies depending on the platform.
If this function is executed during a game loop or at anytime requiring regular screen updates, the processing is blocked by the millisecond and frames may be dropped.
Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when loading a new level.
See also
CriAtomExRawPcmVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForRawPcmVoicePool, criAtomExVoicePool_Free

◆ criAtomExVoicePool_AllocateInstrumentVoicePool()

CriAtomExVoicePoolHn criAtomExVoicePool_AllocateInstrumentVoicePool ( const CriAtomExInstrumentVoicePoolConfig config,
void *  work,
CriSint32  work_size 
)

Create an Instrument Voice Pool.

Parameters
[in]configconfiguration structure used to create an Instrument Voice Pool
[in]workwork buffer
[in]work_sizework buffer size
Returns
CriAtomExInstrumentVoicePoolHn Voice Pool handle
Description:
Creates an Instrument Voice Pool.
When creating a Voice Pool, a work buffer must be passed to this function.
The size of the buffer required is calculated by calling the criAtomExVoicePool_CalculateWorkSizeForInstrumentVoicePool function.
(If a user-allocator was previously registered using the criAtomEx_SetUserAllocator macro, it is not necessary to pass a work buffer.)

Executing this function pools voices that can be used to play Instrument data.
When an AtomEx player needs to play back Instrument data (or a Cue containing Instrument data), it will acquire a voice from the Instrument Voice Pool that has been created.

When a Voice Pool is created successfully, the function returns the Voice Pool handle.
Then, when exiting the application, the Voice Pool must be destroyed using the criAtomExVoicePool_Free function.

If the function fails to create a Voice Pool, it returns NULL.
To know the reason of the failure, refer to the error callback message.
See also
CriAtomExInstrumentVoicePoolConfig, criAtomExVoicePool_CalculateWorkSizeForInstrumentVoicePool, criAtomExVoicePool_Free,

◆ criAtomExVoicePool_Free()

void criAtomExVoicePool_Free ( CriAtomExVoicePoolHn  pool)

Destroy a Voice Pool.

Parameters
[in]poolVoice Pool handle
Description:
Destroys a Voice Pool.
If a user-allocator was registered with the criAtomEx_SetUserAllocator macro, the memory allocated when creating the Voice Pool is automatically released.
If you passed a work buffer when creating the Voice Pool, it can be released after executing this function.
Attention
This is a blocking function.
If a Voice Pool is destroyed while playing a sound, the resource is released after waiting for the playback to be stopped within this function.
(If you are playing from a file, there is also a waiting period for the loading to complete.)
Therefore, processing may be blocked for an extended time (a few frames) within this function.
Create or destroy a Voice Pool only when a fluctuation in load is acceptable, for example when a new gane level is being loaded.
See also
criAtomExVoicePool_AllocateStandardVoicePool

◆ criAtomExVoicePool_FreeAll()

void criAtomExVoicePool_FreeAll ( void  )

Destroy all the Voice Pools.

Description:
Destroys all the Voice Pools.
If a user-allocator was registered with the criAtomEx_SetUserAllocator macro, the memory allocated when creating the Voice Pools is automatically released.
If you passed work buffers when creating the Voice Pools, they can be released after executing this function.
Attention
This is a blocking function.
If the Voice Pools are destroyed while playing sounds, their resources are released after waiting for the playback to be stopped within this function.
(If you are playing from a file, there is also a waiting period for the loading to complete.)
Therefore, processing may be blocked for an extended time (a few frames) within this function.
Create or destroy Voice Pools only when a fluctuation in load is acceptable, for example when a new gane level is being loaded.
See also
criAtomExVoicePool_AllocateStandardVoicePool

◆ criAtomExVoicePool_EnumerateVoicePools()

void criAtomExVoicePool_EnumerateVoicePools ( CriAtomExVoicePoolCbFunc  func,
void *  obj 
)

Voice Pool Enumeration.

Parameters
[in]funcVoice Pool Callback Function
[in]objUser-specified objects
Description:
Enumerates the voice pools created in the application.

When this function is executed, the callback function set in the first argument (func) will be called the number of times equal to the number of voice pools.
(The voice pool handle is passed as an argument to the callback function.)
Remarks:
The value set in the second argument (obj) will be passed as an argument to the callback function.
For other arguments to the callback function, please refer to the separate explanation of : CriAtomExVoicePoolCbFunc .
See also
CriAtomExVoicePoolCbFunc

◆ criAtomExVoicePool_GetNumUsedVoices()

void criAtomExVoicePool_GetNumUsedVoices ( CriAtomExVoicePoolHn  pool,
CriSint32 *  cur_num,
CriSint32 *  limit 
)

Get voice usage.

Parameters
[in]poolVoice Pool Handle
[out]cur_numNumber of voices currently in use
[out]limitMaximum number of voices available
Description:
Gets the number of voices currently in use and the maximum number of voices available in the voice pool (= the number of max_voices specified when the pool was created).

◆ criAtomExVoicePool_GetPlayerHandle()

CriAtomPlayerHn criAtomExVoicePool_GetPlayerHandle ( CriAtomExVoicePoolHn  pool,
CriSint32  index 
)

Getting the Player Handle.

Parameters
[in]poolVoice Pool handle
[in]indexPlayer index
Returns
CriAtomPlayerHn Atom player handle
Description:
Gets the Atom player handle created within the voice pool.
Remarks:
This function is a debug function that can only be used to obtain information.

◆ criAtomExVoicePool_CalculateWorkSizeForInstrumentVoicePool()

CriSint32 criAtomExVoicePool_CalculateWorkSizeForInstrumentVoicePool ( const CriAtomExInstrumentVoicePoolConfig config)

Calculation of work area size for creating instrument voice pool.

Parameters
[in]configConfig structure for instrument voice pool creation
Returns
CriSint32 Work area size
Return values
0or more Completed
-1An error has occured
Description:
Calculates the size of the work area required to create an instrument voice pool.
When creating a voice pool using the criAtomExVoicePool_AllocateInstrumentVoicePool function without registering an allocator using the criAtomEx_SetUserAllocator macro, you must pass memory of the size returned by this function to the criAtomExVoicePool_AllocateInstrumentVoicePool function as a working area.

If the calculation of the work area size fails, this function returns -1.
The reason for the failure to calculate the work area size can be checked in the error callback message.
See also
criAtomExVoicePool_AllocateInstrumentVoicePool