CriAtomPlayer API

Data Structures
struct	CriAtomStandardPlayerConfigTag
struct	CriAtomAdxPlayerConfigTag
struct	CriAtomHcaPlayerConfigTag
struct	CriAtomHcaMxPlayerConfigTag
struct	CriAtomWavePlayerConfigTag
struct	CriAtomAiffPlayerConfigTag
struct	CriAtomRawPcmPlayerConfigTag
struct	CriAtomInstrumentPlayerConfigTag
struct	CriAtomStreamingCacheConfigTag
	Streaming cache creation configuration structure. More...

Macros
#define	CRIATOMPLAYER_NO_LOOP_LIMITATION   (-1)
	Constant for canceling the restriction of the number of loops. More...
#define	criAtomPlayer_SetDefaultConfigForStandardPlayer(p_config)
	Set default parameters for CriAtomStandardPlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForAdxPlayer(p_config)
	Set default parameters for CriAtomAdxPlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForHcaPlayer(p_config)
	Set default parameters for CriAtomHcaPlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForHcaMxPlayer(p_config)
	Set default parameters for CriAtomHcaMxPlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForWavePlayer(p_config)
	Set default parameters for CriAtomWavePlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForRawPcmPlayer(p_config)
	Set default parameters for CriAtomRawPcmPlayerConfig. More...
#define	criAtomPlayer_SetDefaultConfigForInstrumentPlayer(p_config)
	Set default parameters for CriAtomInstrumentPlayerConfig. More...

Typedefs
typedef enum CriAtomParameterIdTag	CriAtomParameterId
	Parameters ID. More...
typedef struct CriAtomStandardPlayerConfigTag	CriAtomStandardPlayerConfig
typedef struct CriAtomAdxPlayerConfigTag	CriAtomAdxPlayerConfig
typedef struct CriAtomHcaPlayerConfigTag	CriAtomHcaPlayerConfig
typedef struct CriAtomHcaMxPlayerConfigTag	CriAtomHcaMxPlayerConfig
typedef struct CriAtomWavePlayerConfigTag	CriAtomWavePlayerConfig
typedef struct CriAtomAiffPlayerConfigTag	CriAtomAiffPlayerConfig
typedef struct CriAtomRawPcmPlayerConfigTag	CriAtomRawPcmPlayerConfig
typedef struct CriAtomInstrumentPlayerConfigTag	CriAtomInstrumentPlayerConfig
typedef enum CriAtomPlayerStatusTag	CriAtomPlayerStatus
	Playback status. More...
typedef struct CriAtomPlayerTag *	CriAtomPlayerHn
	Atom player handle. More...
typedef void(*	CriAtomPlayerDataRequestCbFunc) (void *obj, CriAtomPlayerHn player)
	Data request callback function. More...
typedef void(*	CriAtomPlayerStatusChangeCbFunc) (void *obj, CriAtomPlayerHn player)
	Status change callback function. More...
typedef void(*	CriAtomPlayerParameterChangeCbFunc) (void *obj, CriAtomPlayerHn player, CriAtomParameterId id, CriFloat32 value)
	Parameters change callback function. More...
typedef void(*	CriAtomPlayerFilterCbFunc) (void *obj, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])
	Wave filter callback function. More...
typedef void(*	CriAtomPlayerLoadRequestCbFunc) (void *obj, CriFsBinderHn binder, const CriChar8 *path, CriSint64 offset, CriSint64 length)
	Load request callback function. More...
typedef struct CriAtomStreamingCacheConfigTag	CriAtomStreamingCacheConfig
	Streaming cache creation configuration structure. More...

Enumerations
enum	CriAtomParameterIdTag { CRIATOM_PARAMETER_ID_VOLUME = 0 , CRIATOM_PARAMETER_ID_FREQUENCY_RATIO = 1 , CRIATOM_PARAMETER_ID_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Parameters ID. More...
enum	CriAtomPlayerStatusTag {   CRIATOMPLAYER_STATUS_STOP = 0 , CRIATOMPLAYER_STATUS_PREP = 1 , CRIATOMPLAYER_STATUS_PLAYING = 2 , CRIATOMPLAYER_STATUS_PLAYEND = 3 ,   CRIATOMPLAYER_STATUS_ERROR = 4 , CRIATOMPLAYER_STATUS_ENUM_SIZE_IS_4BYTES = 0x7FFFFFFF }
	Playback status. More...

Functions
CriSint32	criAtomPlayer_CalculateWorkSizeForStandardPlayer (const CriAtomStandardPlayerConfig *config)
	Calculate work area size required for creating standard player. More...
CriAtomPlayerHn	criAtomPlayer_CreateStandardPlayer (const CriAtomStandardPlayerConfig *config, void *work, CriSint32 work_size)
	Create standard player. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForAdxPlayer (const CriAtomAdxPlayerConfig *config)
	Calculate work area size required for creating ADX player. More...
CriAtomPlayerHn	criAtomPlayer_CreateAdxPlayer (const CriAtomAdxPlayerConfig *config, void *work, CriSint32 work_size)
	Create an ADX player. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForHcaPlayer (const CriAtomHcaPlayerConfig *config)
	Calculate work area size required for creating HCA player. More...
CriAtomPlayerHn	criAtomPlayer_CreateHcaPlayer (const CriAtomHcaPlayerConfig *config, void *work, CriSint32 work_size)
	Create an HCA player. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForHcaMxPlayer (const CriAtomHcaMxPlayerConfig *config)
	Calculate work area size required for creating HCA-MX player. More...
CriAtomPlayerHn	criAtomPlayer_CreateHcaMxPlayer (const CriAtomHcaMxPlayerConfig *config, void *work, CriSint32 work_size)
	Create an HCA-MX player. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForWavePlayer (const CriAtomWavePlayerConfig *config)
	Calculate work area size required for creating WAVE player. More...
CriAtomPlayerHn	criAtomPlayer_CreateWavePlayer (const CriAtomWavePlayerConfig *config, void *work, CriSint32 work_size)
	Create a WAVE player. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForAiffPlayer (const CriAtomAiffPlayerConfig *config)
	Work area size calculation for AIFF player creation. More...
CriAtomPlayerHn	criAtomPlayer_CreateAiffPlayer (const CriAtomAiffPlayerConfig *config, void *work, CriSint32 work_size)
	AIFF player creation. More...
CriSint32	criAtomPlayer_CalculateWorkSizeForRawPcmPlayer (const CriAtomRawPcmPlayerConfig *config)
	Calculate work area size required for creating raw PCM player. More...
CriAtomPlayerHn	criAtomPlayer_CreateRawPcmPlayer (const CriAtomRawPcmPlayerConfig *config, void *work, CriSint32 work_size)
	Create raw PCM player. More...
void	criAtomPlayer_Destroy (CriAtomPlayerHn player)
	Destroy Atom player. More...
void	criAtomPlayer_SetData (CriAtomPlayerHn player, void *buffer, CriSint32 buffer_size)
	Set sound data (specify On-memory data) More...
void	criAtomPlayer_SetFile (CriAtomPlayerHn player, CriFsBinderHn binder, const CriChar8 *path)
	Set sound data (specify file) More...
void	criAtomPlayer_SetContentId (CriAtomPlayerHn player, CriFsBinderHn binder, CriSint32 id)
	Set sound data (specify CPK content ID) More...
void	criAtomPlayer_SetWaveId (CriAtomPlayerHn player, CriAtomAwbHn awb, CriSint32 id)
	Set sound data (specify sound data ID) More...
void	criAtomPlayer_SetPreviousDataAgain (CriAtomPlayerHn player)
	Re-set same sound data. More...
void	criAtomPlayer_DeferCallback (CriAtomPlayerHn player)
	Callback function re-execution request. More...
void	criAtomPlayer_Start (CriAtomPlayerHn player)
	Start playback. More...
void	criAtomPlayer_Stop (CriAtomPlayerHn player)
	Stop playback. More...
void	criAtomPlayer_Pause (CriAtomPlayerHn player, CriBool flag)
	Pause/resume playback. More...
CriBool	criAtomPlayer_IsPaused (CriAtomPlayerHn player)
	Check whether player is paused. More...
CriAtomPlayerStatus	criAtomPlayer_GetStatus (CriAtomPlayerHn player)
	Get status. More...
CriSint32	criAtomPlayer_GetNumChannels (CriAtomPlayerHn player)
	Get number of channels. More...
CriBool	criAtomPlayer_GetNumPlayedSamples (CriAtomPlayerHn player, CriSint64 *num_played, CriSint32 *sampling_rate)
	Get number of played samples. More...
CriBool	criAtomPlayer_GetNumRenderedSamples (CriAtomPlayerHn player, CriSint64 *num_rendered, CriSint32 *sampling_rate)
	Acquiring the number of samples to write to the sound buffer. More...
CriSint64	criAtomPlayer_GetDecodedDataSize (CriAtomPlayerHn player)
	Acquiring the size of decoded data. More...
CriSint64	criAtomPlayer_GetNumDecodedSamples (CriAtomPlayerHn player)
	Acquiring the number of decoded samples. More...
CriSint64	criAtomPlayer_GetTime (CriAtomPlayerHn player)
	Get playback time. More...
CriBool	criAtomPlayer_GetFormatInfo (CriAtomPlayerHn player, CriAtomFormatInfo *info)
	Get playback sound format information. More...
CriSint32	criAtomPlayer_GetInputBufferRemainSize (CriAtomPlayerHn player)
	Get amount of data remaining in input buffer. More...
CriSint32	criAtomPlayer_GetOutputBufferRemainSamples (CriAtomPlayerHn player)
	Get amount of data remaining in output buffer. More...
void	criAtomPlayer_SetStartTime (CriAtomPlayerHn player, CriSint64 start_time_ms)
	Specify playback start position. More...
void	criAtomPlayer_SetVolume (CriAtomPlayerHn player, CriFloat32 vol)
	Specify volume. More...
CriFloat32	criAtomPlayer_GetVolume (CriAtomPlayerHn player)
	Volume specification. More...
void	criAtomPlayer_SetChannelVolume (CriAtomPlayerHn player, CriSint32 ch, CriFloat32 vol)
	Specify volume for each channel. More...
void	criAtomPlayer_SetSendLevel (CriAtomPlayerHn player, CriSint32 ch, CriAtomSpeakerId spk, CriFloat32 level)
	Set send level. More...
void	criAtomPlayer_ResetSendLevel (CriAtomPlayerHn player)
	Reset send level. More...
void	criAtomPlayer_SetPanAdx1Compatible (CriAtomPlayerHn player, CriSint32 ch, CriFloat32 pan)
	Set pan. More...
void	criAtomPlayer_ResetPan (CriAtomPlayerHn player)
	Reset pan. More...
void	criAtomPlayer_SetFrequencyRatio (CriAtomPlayerHn player, CriFloat32 ratio)
	Set frequency adjustment ratio. More...
void	criAtomPlayer_SetMaxFrequencyRatio (CriAtomPlayerHn player, CriFloat32 ratio)
	Set max of frequency adjustment ratio. More...
void	criAtomPlayer_LimitLoopCount (CriAtomPlayerHn player, CriSint32 count)
	Limit the number of loop playbacks. More...
void	criAtomPlayer_SetHcaMxMixerId (CriAtomPlayerHn player, CriSint32 mixer_id)
	Sepcify HCA-MX decode destination mixer ID. More...
void	criAtomPlayer_SetAsrRackId (CriAtomPlayerHn player, CriSint32 rack_id)
	Specifying the ASR Rack ID. More...
void	criAtomPlayer_SetRawPcmFormat (CriAtomPlayerHn player, CriAtomPcmFormat pcm_format, CriSint32 num_channels, CriSint32 sampling_rate)
	Specify raw PCM format. More...
void	criAtomPlayer_SetDataRequestCallback (CriAtomPlayerHn player, CriAtomPlayerDataRequestCbFunc func, void *obj)
	Register data request callback function. More...
void	criAtomPlayer_SetStatusChangeCallback (CriAtomPlayerHn player, CriAtomPlayerStatusChangeCbFunc func, void *obj)
	Register status change callback function. More...
void	criAtomPlayer_SetParameterChangeCallback (CriAtomPlayerHn player, CriAtomPlayerParameterChangeCbFunc func, void *obj)
	Register parameter change callback function. More...
void	criAtomPlayer_SetFilterCallback (CriAtomPlayerHn player, CriAtomPlayerFilterCbFunc func, void *obj)
	Register wave filter callback function. More...
void	criAtomPlayer_SetLoadRequestCallback (CriAtomPlayerHn player, CriAtomPlayerLoadRequestCbFunc func, void *obj)
	Registering a load request callback function. More...
void	criAtomPlayer_SetHcaFormat (CriAtomPlayerHn player, CriSint32 num_channels, CriSint32 sampling_rate, CriSint32 bitrate)
	Specifying the HCA format. More...

Detailed Description

Macro Definition Documentation

CRIATOMPLAYER_NO_LOOP_LIMITATION

#define CRIATOMPLAYER_NO_LOOP_LIMITATION   (-1)

Constant for canceling the restriction of the number of loops.

Description:

Infinite loop

criAtomPlayer_SetDefaultConfigForStandardPlayer

#define criAtomPlayer_SetDefaultConfigForStandardPlayer

(

p_config

)

Value:

{\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->streaming_flag      = CRI_FALSE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
    (p_config)->decode_latency      = CRIATOM_DEFAULT_DECODE_LATENCY;\
    (p_config)->context             = NULL;\
}

Set default parameters for CriAtomStandardPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating a standard player

Description:

Sets default values for the configuration structure ( CriAtomStandardPlayerConfig ) that is set for the criAtomPlayer_CreateStandardPlayer function.

See also

CriAtomStandardPlayerConfig, criAtomPlayer_CreateStandardPlayer

criAtomPlayer_SetDefaultConfigForAdxPlayer

#define criAtomPlayer_SetDefaultConfigForAdxPlayer

(

p_config

)

Value:

{\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->streaming_flag      = CRI_FALSE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
    (p_config)->decode_latency      = CRIATOM_DEFAULT_DECODE_LATENCY;\
    (p_config)->context             = NULL;\
}

Set default parameters for CriAtomAdxPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating an ADX Player

Description:

Sets default values for the configuration structure ( CriAtomAdxPlayerConfig ) that is set for the criAtomPlayer_CreateAdxPlayer function.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer

criAtomPlayer_SetDefaultConfigForHcaPlayer

#define criAtomPlayer_SetDefaultConfigForHcaPlayer

(

p_config

)

Value:

{\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->streaming_flag      = CRI_FALSE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
    (p_config)->decode_latency      = CRIATOM_DEFAULT_DECODE_LATENCY;\
    (p_config)->context             = NULL;\
}

Set default parameters for CriAtomHcaPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating an HCA Player

Description:

Sets default values for the configuration structure ( CriAtomHcaPlayerConfig ) that is set for the criAtomPlayer_CreateHcaPlayer function.

See also

CriAtomHcaPlayerConfig, criAtomPlayer_CreateHcaPlayer

criAtomPlayer_SetDefaultConfigForHcaMxPlayer

#define criAtomPlayer_SetDefaultConfigForHcaMxPlayer

(

p_config

)

Value:

{\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->streaming_flag      = CRI_FALSE;\
}

Set default parameters for CriAtomHcaMxPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating an HCA-MX Player

Description:

Sets default values for the configuration structure ( CriAtomHcaMxPlayerConfig ) that is set for the criAtomPlayer_CreateHcaMxPlayer function.

See also

CriAtomHcaMxPlayerConfig, criAtomPlayer_CreateHcaMxPlayer

criAtomPlayer_SetDefaultConfigForWavePlayer

#define criAtomPlayer_SetDefaultConfigForWavePlayer

(

p_config

)

Value:

{\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->streaming_flag      = CRI_FALSE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
    (p_config)->decode_latency      = CRIATOM_DEFAULT_DECODE_LATENCY;\
    (p_config)->context             = NULL;\
}

Set default parameters for CriAtomWavePlayerConfig.

Parameters

[out]

p_config

pointer to WAVE player creation configuration structure

Description:

Sets default values for the configuration structure ( CriAtomWavePlayerConfig ) that is set for the criAtomPlayer_CreateWavePlayer function.

See also

CriAtomWavePlayerConfig, criAtomPlayer_CreateWavePlayer

criAtomPlayer_SetDefaultConfigForRawPcmPlayer

#define criAtomPlayer_SetDefaultConfigForRawPcmPlayer

(

p_config

)

Value:

{\
    (p_config)->pcm_format          = CRIATOM_PCM_FORMAT_SINT16;\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
    (p_config)->decode_latency      = CRIATOM_DEFAULT_DECODE_LATENCY;\
    (p_config)->context             = NULL;\
}

Set default parameters for CriAtomRawPcmPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating a raw PCM Player

Description:

Sets default values for the configuration structure ( CriAtomRawPcmPlayerConfig ) that is set for the criAtomPlayer_CreateRawPcmPlayer function.

See also

CriAtomRawPcmPlayerConfig, criAtomPlayer_CreateRawPcmPlayer

criAtomPlayer_SetDefaultConfigForInstrumentPlayer

#define criAtomPlayer_SetDefaultConfigForInstrumentPlayer

(

p_config

)

Value:

{\
    (p_config)->interface_name      = "";\
    (p_config)->instrument_name     = "";\
    (p_config)->max_channels        = CRIATOM_DEFAULT_INPUT_MAX_CHANNELS;\
    (p_config)->max_sampling_rate   = CRIATOM_DEFAULT_INPUT_MAX_SAMPLING_RATE;\
    (p_config)->sound_renderer_type = CRIATOM_SOUND_RENDERER_DEFAULT;\
}

Set default parameters for CriAtomInstrumentPlayerConfig.

Parameters

[out]

p_config

pointer to the configuration structure for creating a Instrument Player

Description:

Sets default values for the configuration structure ( CriAtomRawPcmPlayerConfig ) that is set for the criAtomPlayer_CreateRawPcmPlayer function.

See also

criAtomExVoicePool_AllocateInstrumentVoicePool

Typedef Documentation

CriAtomParameterId

typedef enum CriAtomParameterIdTag CriAtomParameterId

Parameters ID.

Description:

ID for specifying parameters.

CriAtomStandardPlayerConfig

typedef struct CriAtomStandardPlayerConfigTag CriAtomStandardPlayerConfig

Configuration structure for creating a standard player

Description:

Structure for specifying the behavioral specification of a standard player (that supports ADX and HCA codecs) to be created.
This structure is specified as an argument of the criAtomPlayer_CreateStandardPlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when the criAtomPlayer_SetDefaultConfigForStandardPlayer macro is not used, 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

criAtomPlayer_CreateStandardPlayer, criAtomPlayer_SetDefaultConfigForStandardPlayer

CriAtomAdxPlayerConfig

typedef struct CriAtomAdxPlayerConfigTag CriAtomAdxPlayerConfig

ADX player creation configuration structure

Description:

Structure for specifying the behavior when creating a player capable of ADX playback.
This structure is specified as an argument of the criAtomPlayer_CreateAdxPlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when not using the criAtomPlayer_SetDefaultConfigForAdxPlayer 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

criAtomPlayer_CreateAdxPlayer, criAtomPlayer_SetDefaultConfigForAdxPlayer

CriAtomHcaPlayerConfig

typedef struct CriAtomHcaPlayerConfigTag CriAtomHcaPlayerConfig

HCA player creation configuration structure

Description:

Structure for specifying the behavior when creating a player capable of HCA playback.
This structure is specified as an argument of the criAtomPlayer_CreateHcaPlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when not using the criAtomPlayer_SetDefaultConfigForHcaPlayer 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

criAtomPlayer_CreateHcaPlayer, criAtomPlayer_SetDefaultConfigForHcaPlayer

CriAtomHcaMxPlayerConfig

typedef struct CriAtomHcaMxPlayerConfigTag CriAtomHcaMxPlayerConfig

HCA-MX player creation configuration structure

Description:

Structure for specifying the behavior when creating a player capable of HCA-MX playback.
This structure is specified as an argument of the criAtomPlayer_CreateHcaMxPlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when not using the criAtomPlayer_SetDefaultConfigForHcaMxPlayer 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

criAtomPlayer_CreateHcaMxPlayer, criAtomPlayer_SetDefaultConfigForHcaMxPlayer

CriAtomWavePlayerConfig

typedef struct CriAtomWavePlayerConfigTag CriAtomWavePlayerConfig

WAVE player creation configuration structure

Description:

Structure for specifying the behavior when creating a player capable of WAVE playback.
This structure is specified as an argument of the criAtomPlayer_CreateWavePlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when not using the criAtomPlayer_SetDefaultConfigForWavePlayer 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

criAtomPlayer_CreateWavePlayer, criAtomPlayer_SetDefaultConfigForWavePlayer

CriAtomAiffPlayerConfig

typedef struct CriAtomAiffPlayerConfigTag CriAtomAiffPlayerConfig

Configuration structure for AIFF player creation

Description:

Structure for specifying the behavior when creating a player capable of AIFF playback.
This structure is specified as an argument of the criAtomPlayer_CreateAiffPlayer function.

As much internal resources as needed are allocated for the player depending on the settings specified in the structure when a handle to the player is created.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

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

See also

criAtomPlayer_CreateAiffPlayer, criAtomPlayer_SetDefaultConfigForAiffPlayer

CriAtomRawPcmPlayerConfig

typedef struct CriAtomRawPcmPlayerConfigTag CriAtomRawPcmPlayerConfig

Raw PCM player creation configuration structure

Description:

Structure for specifying the behavior when creating a player capable of raw PCM playback.
This structure is specified as an argument of the criAtomPlayer_CreateRawPcmPlayer function.

When a handle to the player is created, as much internal resources as needed are allocated for the player based on the settings specified in the structure.
The size of the work area needed for the player varies depending on the parameters specified in the structure.

Attention

More members will be added in the future. So, when not using the criAtomPlayer_SetDefaultConfigForRawPcmPlayer 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

criAtomPlayer_CreateRawPcmPlayer, criAtomPlayer_SetDefaultConfigForRawPcmPlayer

CriAtomInstrumentPlayerConfig

typedef struct CriAtomInstrumentPlayerConfigTag CriAtomInstrumentPlayerConfig

Instrument Player creation configuration structure

Description:

A structure for specifying behavior specifications when creating a player that can play an instrument.

The created player will reserve as many internal resources as needed, depending on the settings specified in this structure when creating the handle.
The size of the work area required by the player depends on the parameters specified in this structure.

Attention

Be sure to clear the structure to zero before using it because it may increase the number of members in the future.
(Be careful not to enter an undefined value in the structure member.)

CriAtomPlayerStatus

typedef enum CriAtomPlayerStatusTag CriAtomPlayerStatus

Playback status.

Description:

Indicates the playback status of an Atom Player.
The value of the playback status can be acquired by using the criAtomPlayer_GetStatus function.
Usually, the playback status changes in the following order.

1. CRIATOMPLAYER_STATUS_STOP
2. CRIATOMPLAYER_STATUS_PREP
3. CRIATOMPLAYER_STATUS_PLAYING
4. CRIATOMPLAYER_STATUS_PLAYEND

Immediately after an Atom Player is created, the player is in a stop status ( CRIATOMPLAYER_STATUS_STOP ).
By setting data using a function such as the criAtomPlayer_SetData function and then executing the criAtomPlayer_Start function, the player enters a playback preparation status ( CRIATOMPLAYER_STATUS_PREP ) and starts preparing for playback.
Once a sufficient amount of data is provided and the playback is ready, the player enters a playback status ( CRIATOMPLAYER_STATUS_PLAYING ) and starts audio playback.
When the playback of all data that have been set is complete, the player enters a playback completion status ( CRIATOMPLAYER_STATUS_PLAYEND ).

Remarks:

If the criAtomPlayer_Stop function is executed during playback, the status eventually returns to CRIATOMPLAYER_STATUS_STOP regardless of the above flow.
(Depending on when the criAtomPlayer_Stop function is called, it may take time to change the status to CRIATOMPLAYER_STATUS_STOP.)
Also, during playback, if an invalid data is read or file access fails, the status changes to CRIATOMPLAYER_STATUS_ERROR regardless of the above flow.

Attention

When the status is CRIATOMPLAYER_STATUS_PREP or CRIATOMPLAYER_STATUS_PLAYING , data cannot be set ( criAtomPlayer_SetData function) and playback cannot be started ( criAtomPlayer_Start function).
In order to stop the currently playing Atom player and play another data, you must first stop playback with the criAtomPlayer_Stop function and then set/play the next data after the status changes to CRIATOMPLAYER_STATUS_STOP.

See also

criAtomPlayer_GetStatus, criAtomPlayer_SetData, criAtomPlayer_Start, criAtomPlayer_Stop

CriAtomPlayerHn

typedef struct CriAtomPlayerTag* CriAtomPlayerHn

Atom player handle.

Description:

Handle for operating a player created for audio playback.
When the criAtomPlayer_CreateAdxPlayer function is used for creating a player for audio playback, the function returns this "Atom player handle" for operating the player.
Atom player is an abstracted player object that provides an interface for playback control that does not rely on codec.
The method of creating an Atom player depends on the playback sound codec. The API for the Atom player can be used in common to control the created player.
All operations, such as setting data, starting playback, and acquiring status, performed to the player are operated through the Atom player handle.

See also

criAtomPlayer_CreateAdxPlayer

CriAtomPlayerDataRequestCbFunc

typedef void( * CriAtomPlayerDataRequestCbFunc) (void *obj, CriAtomPlayerHn player)

Data request callback function.

Description:

Parameters

[in]	obj	user specified object
[in]	player	Atom player handle

Returns

None

Description:

Callback function for specifying the data to playback next.
Use this to seamlessly concatenate and play back multiple sound data.

Use the criAtomPlayer_SetDataRequestCallback function to register the callback function.
The registered callback function is executed when the Atom player requests the concatenated playback data.
(The callback function is executed when requesting the data to playback next after the previous data is read.) When data is set in Atom player from this function using the criAtomPlayer_SetData function, the set data is seamlessly concatenated to the currently playing data and played back continuously.
Also, if the criAtomPlayer_SetPreviousDataAgain function is executed within this function, the same data can be played back repeatedly.

Remarks:

If data is not specified within this function, after playback of the current data is finished, the Atom player status changes to CRIATOMPLAYER_STATUS_PLAYEND.

If you cannot specify the data due to timing but do not want the status to change to CRIATOMPLAYER_STATUS_PLAYEND , execute the criAtomPlayer_DeferCallback function within the callback function.
By executing the criAtomPlayer_DeferCallback function, the data request callback function is called once more after approximately 1V. (The callback process can be retried.)
However, playback may be interrupted when the criAtomPlayer_DeferCallback function is executed (there may be a certain amount of silence at the concatenation point).

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within this callback function.

See also

criAtomPlayer_SetDataRequestCallback, criAtomPlayer_SetData, criAtomPlayer_SetPreviousDataAgain, criAtomPlayer_DeferCallback

CriAtomPlayerStatusChangeCbFunc

typedef void( * CriAtomPlayerStatusChangeCbFunc) (void *obj, CriAtomPlayerHn player)

Status change callback function.

Description:

Parameters

[in]	obj	user specified object
[in]	player	Atom player handle

Returns

None

Description:

Callback function that is called when the Atom player status is changed.

Use the criAtomPlayer_SetStatusChangeCallback function to register the callback function.
The registered callback function is executed when the Atom player status is updated.
The changed status can be obtained by executing the criAtomPlayer_GetStatus function against the Atom player handle (player) passed with an argument.

Remarks:

Strictly speaking, the timing from status change to execution of the callback function may change because another process can interrupt and run during this interval.

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within this callback function.

See also

criAtomPlayer_SetStatusChangeCallback, criAtomPlayer_GetStatus

CriAtomPlayerParameterChangeCbFunc

typedef void( * CriAtomPlayerParameterChangeCbFunc) (void *obj, CriAtomPlayerHn player, CriAtomParameterId id, CriFloat32 value)

Parameters change callback function.

Description:

Parameters

[in]	obj	user specified object
[in]	player	Atom player handle
[in]	id	Parameter ID
[in]	value	Parameter value

Returns

None

Description:

Callback function that is called when the Atom player parameters is changed.

Use the criAtomPlayer_SetParameterChangeCallback function to register the callback function.
The registered callback function is executed when the Atom player parameter is updated.

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within this callback function.

See also

criAtomPlayer_SetParameterChangeCallback

CriAtomPlayerFilterCbFunc

typedef void( * CriAtomPlayerFilterCbFunc) (void *obj, CriAtomPcmFormat format, CriSint32 num_channels, CriSint32 num_samples, void *data[])

Wave filter callback function.

Description:

Parameters

[in]	obj	user specified object
[in]	format	PCM format
[in]	num_channels	number of channels
[in]	num_samples	number of samples
	[in/out]	data PCM data channel layout

Returns

None

Description:

Callback function that receives decoded PCM data.

Use the criAtomPlayer_SetFilterCallback function to register the callback function.
When this callback function is registered, it is executed each time the Atom player decodes sound data.

The address of an area containing the format of the PCM data, the number of channels in the PCM data, the number of samples accessible, and the actual PCM data is returned to the filter callback function.
Since PCM data can be accessed directly within the callback function, it can be used for applications such as checking the amplitude of the sound during playback.

Also, user unique effects can be applied to the PCM data because modification made to the PCM data within the callback function is reflected during playback.
(However, modification that changes the data size such as time stretch process cannot be performed.)

Remarks:

The PCM data is separated per channel.
(It is not interleaved.)
The sixth argument (data array) contains the top address of each channel's PCM data array.
(Not the top address of the two-dimensional array, but a one-dimensional pointer array containing the top address of each channel's PCM data array.)

The PCM data format depends on the platform.
The data format of the execution environment can be determined from the third argument (format).
If the format of PCM data is 16 bit integer, format is CRIATOM_PCM_FORMAT_SINT16 , if it is 32 bit floating-point, format is CRIATOM_PCM_FORMAT_FLOAT32 .
Not that the range of PCM data is different for each case.

• CRIATOM_PCM_FORMAT_SINT16 : -32768 to +32767
• CRIATOM_PCM_FORMAT_FLOAT32 : -1.0f to +1.0f

(Because no clipping is performed during decoding, for CRIATOM_PCM_FORMAT_FLOAT32 , value slightly exceeding the above range is possible.)

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within this callback function.

See also

criAtomPlayer_SetFilterCallback

CriAtomPlayerLoadRequestCbFunc

typedef void( * CriAtomPlayerLoadRequestCbFunc) (void *obj, CriFsBinderHn binder, const CriChar8 *path, CriSint64 offset, CriSint64 length)

Load request callback function.

Description:

Parameters

[in]	obj	User specified object
[in]	binder	Binder to which the file is loaded
[in]	path	File path
[in]	offset	Load start position
[in]	length	Load request size

Returns

None

Description:

This callback function for debug is used to monitor the file load status of the Atom player.
The criAtomPlayer_SetLoadRequestCallback function is used to register a callback function.

The registered callback function is executed when the Atom player issues a request to load sound data.

Note:

Attention

Note that if processes are blocked in the callback function for a long time, some problems, such as a playback interruption may occur.

See also

criAtomPlayer_SetLoadRequestCallback

CriAtomStreamingCacheConfig

typedef struct CriAtomStreamingCacheConfigTag CriAtomStreamingCacheConfig

Streaming cache creation configuration structure.

Description:

Structure for registering the file size that can be cached when creating a streaming cache for the player.
It is specified as argument of the ::criAtomStreamingCache_CalculateWorkSize function and ::criAtomStreamingCache_Create function.

Attention

Be sure to zero clear the structure before using because members may be added in the future.
(Make sure that no indefinite value is set to any member of the structure.)

See also

criAtomStreamingCache_CalculateWorkSize, criAtomStreamingCache_Create

Enumeration Type Documentation

CriAtomParameterIdTag

enum CriAtomParameterIdTag

Parameters ID.

Description:

ID for specifying parameters.

Enumerator
CRIATOM_PARAMETER_ID_VOLUME	Volume
CRIATOM_PARAMETER_ID_FREQUENCY_RATIO	frequency ratio

CriAtomPlayerStatusTag

enum CriAtomPlayerStatusTag

Playback status.

Description:

Indicates the playback status of an Atom Player.
The value of the playback status can be acquired by using the criAtomPlayer_GetStatus function.
Usually, the playback status changes in the following order.

1. CRIATOMPLAYER_STATUS_STOP
2. CRIATOMPLAYER_STATUS_PREP
3. CRIATOMPLAYER_STATUS_PLAYING
4. CRIATOMPLAYER_STATUS_PLAYEND

Immediately after an Atom Player is created, the player is in a stop status ( CRIATOMPLAYER_STATUS_STOP ).
By setting data using a function such as the criAtomPlayer_SetData function and then executing the criAtomPlayer_Start function, the player enters a playback preparation status ( CRIATOMPLAYER_STATUS_PREP ) and starts preparing for playback.
Once a sufficient amount of data is provided and the playback is ready, the player enters a playback status ( CRIATOMPLAYER_STATUS_PLAYING ) and starts audio playback.
When the playback of all data that have been set is complete, the player enters a playback completion status ( CRIATOMPLAYER_STATUS_PLAYEND ).

Remarks:

If the criAtomPlayer_Stop function is executed during playback, the status eventually returns to CRIATOMPLAYER_STATUS_STOP regardless of the above flow.
(Depending on when the criAtomPlayer_Stop function is called, it may take time to change the status to CRIATOMPLAYER_STATUS_STOP.)
Also, during playback, if an invalid data is read or file access fails, the status changes to CRIATOMPLAYER_STATUS_ERROR regardless of the above flow.

Attention

When the status is CRIATOMPLAYER_STATUS_PREP or CRIATOMPLAYER_STATUS_PLAYING , data cannot be set ( criAtomPlayer_SetData function) and playback cannot be started ( criAtomPlayer_Start function).
In order to stop the currently playing Atom player and play another data, you must first stop playback with the criAtomPlayer_Stop function and then set/play the next data after the status changes to CRIATOMPLAYER_STATUS_STOP.

See also

criAtomPlayer_GetStatus, criAtomPlayer_SetData, criAtomPlayer_Start, criAtomPlayer_Stop

Enumerator
CRIATOMPLAYER_STATUS_STOP	Stopped
CRIATOMPLAYER_STATUS_PREP	In preparation for playback
CRIATOMPLAYER_STATUS_PLAYING	In playback
CRIATOMPLAYER_STATUS_PLAYEND	Playback ended
CRIATOMPLAYER_STATUS_ERROR	An error occurred

Function Documentation

criAtomPlayer_CalculateWorkSizeForStandardPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForStandardPlayer

(

const CriAtomStandardPlayerConfig *

config

)

Calculate work area size required for creating standard player.

Parameters

[in]

config

standard player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtains the work area size required for creating a standard player (player capable of playing ADX and HCA).

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomStandardPlayerConfig ).

If you specify NULL as argument, the default setting (the same parameters as when criAtomPlayer_SetDefaultConfigForStandardPlayer is used) is used to calculate 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.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, you must initialize the library before executing this function.

See also

CriAtomStandardPlayerConfig, criAtomPlayer_CreateStandardPlayer

criAtomPlayer_CreateStandardPlayer()

CriAtomPlayerHn criAtomPlayer_CreateStandardPlayer	(	const CriAtomStandardPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create standard player.

Parameters

[in]	config	standard player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing ADX and HCA.
The Atom player created with this function will have ADX data and HCA data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForStandardPlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.

When using the User Allocator method, you do not need to provide a work area.
You can allocate the required memory with the registered memory allocation function simply by specifying NULL for work and 0 for work_size.
The memory allocated when creating the standard player is released when the standard player is destroyed (when executing the criAtomPlayer_Destroy function).

When using the Fixed Memory method, you must set a separately allocated memory for this function as work area.
The size of the work area can be obtained with the criAtomPlayer_CalculateWorkSizeForStandardPlayer function.
Allocate memory equal to the size obtained with the criAtomPlayer_CalculateWorkSizeForStandardPlayer function before creating the standard player and set it to this function.
Also, if you use the Fixed Memory method, the work area will be used within the library until the standard player is destroyed ( criAtomPlayer_Destroy function).
Do not release the work area memory before destroying the standard player.

Example:

[Creating a Standard Player with the User Allocator method]
When using the User Allocator method, the standard player create/destroy procedure is as follows:

1. Before creating the standard player, use the criAtom_SetUserMallocFunction function and criAtom_SetUserFreeFunction function to register the memory allocation/deallocation function.
   
   1. Set parameters in the standard player creation configuration structure.
      
   2. Create the standard player with the criAtomPlayer_CreateStandardPlayer function.
      (Specify NULL for work and 0 for work_size.)
      
   3. When the handle is no longer necessary, destroy the standard player with the criAtomPlayer_Destroy function.
      

The specific code is as follows:

// User's memory allocation function
void *user_malloc(void *obj, CriUint32 size)
{
    void *mem;
 
    // Allocate a memory
    mem = malloc(size);
 
    return (mem);
}
 
// Prepare user's memory release function
void user_free(void *obj, void *mem)
{
    // Release memory
    free(mem);
 
    return;
}
 
main()
{
    CriAtomStandardPlayerConfig config; // standard player creation configuration structure
    CriAtomPlayerHn player;             // Atom player handle
        :
    // User's memory allocation function
    criAtom_SetUserMallocFunction(user_malloc, NULL);
 
    // Register user's memory deallocation function
    criAtom_SetUserFreeFunction(user_free, NULL);
 
    // Set standard player creation configuration structure
    memset(&config, 0, sizeof(config));
    config.max_channels = 2;            // Create stereo playback capable player
    config.max_sampling_rate = 48000;   // Play maximum 48000Hz sound
 
    // Create standard player
    // Specify NULL and 0 in work area.
    // ->Allocate the required memory using the registered memory allocation function.
    player = criAtomPlayer_CreateStandardPlayer(&config, NULL, 0);
        :
    // Sound playback processing
        :
    // Destroy standard player when it is no longer necessary
    // ->Memory allocated in library when creating the standard player is released.
    criAtomPlayer_Destroy(player);
        :
}

*If memory allocate/deallocate function is registered during library initialization, it need not be registered again when creating the standard player.

[Creating a Standard Player with the Fixed Memory Method]
When using the Fixed Memory method, the standard player create/destroy procedure is as follows:

1. Set parameters in the standard player creation configuration structure.
   
2. Calculate the size of work area necessary to create the standard player with the criAtomPlayer_CalculateWorkSizeForStandardPlayer function.
   
3. Allocate memory equal to the size of the work area.
   
4. Create the standard player with the criAtomPlayer_CreateStandardPlayer function.
   (Specify the address of the allocated memory for work and the size of the work area for work_size.)
   
5. When the handle is no longer necessary, destroy the standard player with the criAtomPlayer_Destroy function.
   
6. Release the work area memory.
   

The specific code is as follows:

main()
{
    CriAtomStandardPlayerConfig config; // standard player creation configuration structure
    CriAtomPlayerHn player;             // Atom player handle
    void *work;                         // work area address
    CriSint32 work_size;                // work area size
        :
    // Set standard player creation configuration structure
    memset(&config, 0, sizeof(config));
    config.max_channels = 2;            // Create stereo playback capable player
    config.max_sampling_rate = 48000;   // Play maximum 48000Hz sound
 
    // Calculate the size of the work area necessary to creat the standard player
    work_size = criAtomPlayer_CalculateWorkSizeForStandardPlayer(&config);
 
    // Allocate memory for the work area
    work = malloc((size_t)work_size);
 
    // Create standard player
    // Specify NULL and 0 in work area.
    // ->Specify allocated work area.
    player = criAtomPlayer_CreateStandardPlayer(&config, work, work_size);
        :
    // Sound playback processing
    // ->Allocated memory is retained during this time.
        :
    // Destroy standard player when it is no longer necessary
    criAtomPlayer_Destroy(player);
 
    // Release work area no longer necessary.
    free(work);
        :
}

When you execute the criAtomPlayer_CreateStandardPlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

   Remarks:

   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.
   
   The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
   When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as the number of player handles.
   
   This function is a blocking function.
   The time required to create the standard player depends on the platform.
   When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
   Create/destroy standard player when change in load is permissible such as at the change of scenes.
   

   See also

   CriAtomStandardPlayerConfig, criAtomPlayer_CalculateWorkSizeForStandardPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateStandardPlayer

criAtomPlayer_CalculateWorkSizeForAdxPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForAdxPlayer

(

const CriAtomAdxPlayerConfig *

config

)

Calculate work area size required for creating ADX player.

Parameters

[in]

config

ADX player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtain the work area size required for creating an ADX playback player.

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomAdxPlayerConfig ).

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForAdxPlayer 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.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, you must initialize the library before executing this function.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer

criAtomPlayer_CreateAdxPlayer()

CriAtomPlayerHn criAtomPlayer_CreateAdxPlayer	(	const CriAtomAdxPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create an ADX player.

Parameters

[in]	config	ADX player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing ADX.
The Atom player created with this function will have ADX data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForAdxPlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.

When using the User Allocator method, you do not need to provide a work area.
You can allocate the required memory with the registered memory allocation function simply by specifying NULL for work and 0 for work_size.
The memory allocated when creating the ADX player is released when ADX player is destroyed (when executing the criAtomPlayer_Destroy function).

When using the Fixed Memory method, you must set a separately allocated memory for this function as work area.
The size of the work area can be obtained with the criAtomPlayer_CalculateWorkSizeForAdxPlayer function.
Allocate memory equal to the size obtained with the criAtomPlayer_CalculateWorkSizeForAdxPlayer function before creating the ADX player and set it to this function.
Also, if you use the Fixed Memory method, the work area will be used within the library until the ADX player is destroyed ( criAtomPlayer_Destroy function).
Do not release the work area memory before destroying the ADX player.

Example:

[Creating an ADX Player with the User Allocator method] When using the User Allocator method, the ADX player create/destroy procedure is as follows:

1. Before creating the ADX player, use the criAtom_SetUserMallocFunction function and criAtom_SetUserFreeFunction function to register the memory allocation/deallocation function.
   
   1. Set parameters in the ADX player creation configuration structure.
      
   2. Create the ADX player with the criAtomPlayer_CreateAdxPlayer function.
      (Specify NULL for work and 0 for work_size.)
      
   3. When the handle is no longer necessary, destroy the ADX player with the criAtomPlayer_Destroy function.
      

The specific code is as follows:

// User's memory allocation function
void *user_malloc(void *obj, CriUint32 size)
{
    void *mem;
 
    // Allocate a memory
    mem = malloc(size);
 
    return (mem);
}
 
// Prepare user's memory release function
void user_free(void *obj, void *mem)
{
    // Release memory
    free(mem);
 
    return;
}
 
main()
{
    CriAtomAdxPlayerConfig config;  // ADX player creation configuration structure
    CriAtomPlayerHn player;         // Atom player handle
        :
    // User's memory allocation function
    criAtom_SetUserMallocFunction(user_malloc, NULL);
 
    // Register user's memory deallocation function
    criAtom_SetUserFreeFunction(user_free, NULL);
 
    // Set ADX player creation configuration structure
    memset(&config, 0, sizeof(config));
    config.max_channels = 2;            // Create stereo playback capable player
    config.max_sampling_rate = 48000;   // Play maximum 48000Hz sound
 
    // Create ADX player
    // Specify NULL and 0 in work area.
    // ->Allocate the required memory using the registered memory allocation function.
    player = criAtomPlayer_CreateAdxPlayer(&config, NULL, 0);
        :
    // Sound playback processing
        :
    // Destroy ADX player when it is no longer necessary 
    // ->Memory allocated in library when creating the ADX player is released.
    criAtomPlayer_Destroy(player);
        :
}

*If memory allocation/release function is registered during library initialization, it need not be registered again when creating the ADX player.

[Creating an ADX Player with the Fixed Memory Method] When using the Fixed Allocator method, the ADX player create/destroy procedure is as follows:

1. Set parameters in the ADX player creation configuration structure.
   
2. Calculate the size of work area necessary to create the ADX player with the criAtomPlayer_CalculateWorkSizeForAdxPlayer function.
   
3. Allocate memory equal to the size of the work area.
   
4. Create the ADX player with the criAtomPlayer_CreateAdxPlayer function.
   (Specify the address of the allocated memory for work and the size of the work area for work_size.)
   
5. When the handle is no longer necessary, destroy the ADX player with the criAtomPlayer_Destroy function.
   
6. Release the work area memory.
   

The specific code is as follows:

main()
{
    CriAtomAdxPlayerConfig config;  // ADX player creation configuration structure
    CriAtomPlayerHn player;         // Atom player handle
    void *work;                     // Work area address
    CriSint32 work_size;            // Work area size
        :
    // Set ADX player creation configuration structure
    memset(&config, 0, sizeof(config));
    config.max_channels = 2;            // Create stereo playback capable player
    config.max_sampling_rate = 48000;   // Play maximum 48000Hz sound
 
    // Calculate the size of the work area necessary to create the ADX player
    work_size = criAtomPlayer_CalculateWorkSizeForAdxPlayer(&config);
 
    // Allocate memory for the work area
    work = malloc((size_t)work_size);
 
    // Create ADX player
    // Specify NULL and 0 in work area.
    // ->Specify allocated work area.
    player = criAtomPlayer_CreateAdxPlayer(&config, work, work_size);
        :
    // Sound playback processing
    // ->Allocated memory is retained during this time.
        :
    // Destroy ADX player when it is no longer necessary
    criAtomPlayer_Destroy(player);
 
    // Release work area no longer necessary.
    free(work);
        :
}

When you execute the criAtomPlayer_CreateAdxPlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

   Remarks:

   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.
   
   The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
   When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as this function.
   
   This function is a blocking function.
   The time required to create the ADX player depends on the platform.
   When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
   Create/destroy ADX player when change in load is permissible such as at the change of scenes.
   

   See also

   CriAtomAdxPlayerConfig, criAtomPlayer_CalculateWorkSizeForAdxPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateAdxPlayer

criAtomPlayer_CalculateWorkSizeForHcaPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForHcaPlayer

(

const CriAtomHcaPlayerConfig *

config

)

Calculate work area size required for creating HCA player.

Parameters

[in]

config

HCA player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtain the work area size required for creating an HCA playback player.

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomHcaPlayerConfig ).

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForHcaPlayer 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.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, you must initialize the library before executing this function.

See also

CriAtomHcaPlayerConfig, criAtomPlayer_CreateHcaPlayer

criAtomPlayer_CreateHcaPlayer()

CriAtomPlayerHn criAtomPlayer_CreateHcaPlayer	(	const CriAtomHcaPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create an HCA player.

Parameters

[in]	config	HCA player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing HCA.
The Atom player created with this function will have HCA data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForHcaPlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.
Refer to the description of the criAtomPlayer_CreateAdxPlayer function for the details of each method.

When you execute the criAtomPlayer_CreateHcaPlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

Remarks:

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.

The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as this function.

This function is a blocking function.
The time required to create the HCA player depends on the platform.
When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
Create/destroy HCA player when change in load is permissible such as at the change of scenes.

See also

CriAtomHcaPlayerConfig, criAtomPlayer_CalculateWorkSizeForHcaPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateHcaPlayer

criAtomPlayer_CalculateWorkSizeForHcaMxPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForHcaMxPlayer

(

const CriAtomHcaMxPlayerConfig *

config

)

Calculate work area size required for creating HCA-MX player.

Parameters

[in]

config

HCA-MX player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtains the work area size required for creating an HCA-MX playback player.

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomHcaMxPlayerConfig ).

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForHcaMxPlayer 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.

Attention

The size of the work area depends on the parameter you specified when initializing HCA-MX (when executing the criAtomHcaMx_Initialize function).
Therefore, you must initialize HCA-MX before executing this function.

See also

CriAtomHcaMxPlayerConfig, criAtomPlayer_CreateHcaMxPlayer

criAtomPlayer_CreateHcaMxPlayer()

CriAtomPlayerHn criAtomPlayer_CreateHcaMxPlayer	(	const CriAtomHcaMxPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create an HCA-MX player.

Parameters

[in]	config	HCA-MX player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing HCA-MX.
The Atom player created with this function will have HCA-MX data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForHcaMxPlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.
Refer to the description of the criAtomPlayer_CreateAdxPlayer function for the details of each method.

When you execute the criAtomPlayer_CreateHcaMxPlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

Remarks:

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

The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as this function.

You must initialize HCA-MX before executing this function.

This function is a blocking function.
The time required to create the HCA-MX player depends on the platform.
When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
Create/destroy HCA-MX player when change in load is permissible such as at the change of scenes.

See also

CriAtomHcaMxPlayerConfig, criAtomPlayer_CalculateWorkSizeForHcaMxPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateHcaMxPlayer

criAtomPlayer_CalculateWorkSizeForWavePlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForWavePlayer

(

const CriAtomWavePlayerConfig *

config

)

Calculate work area size required for creating WAVE player.

Parameters

[in]

config

WAVE player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtain the work area size required for creating a WAVE playback player.

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomWavePlayerConfig ).

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForWavePlayer 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.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, you must initialize the library before executing this function.

See also

CriAtomWavePlayerConfig, criAtomPlayer_CreateWavePlayer

criAtomPlayer_CreateWavePlayer()

CriAtomPlayerHn criAtomPlayer_CreateWavePlayer	(	const CriAtomWavePlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create a WAVE player.

Parameters

[in]	config	WAVE player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing WAVE.
The Atom player created with this function will have WAVE data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForWavePlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.
Refer to the description of the criAtomPlayer_CreateAdxPlayer function for the details of each method.

When you execute the criAtomPlayer_CreateWavePlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

Remarks:

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.

The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as this function.

This function is a blocking function.
The time required to create the WAVE player depends on the platform.
When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
Create/destroy WAVE player when change in load is permissible such as at the change of scenes.

Currently, chunks of Wave files are not strictly analyzed.
Parsing of a Wave file may fail if FORM chunk, COMM chunk, and SSND chunk are not included in this order or the file includes other chunks.
In addition, only monophonic or stereo 16bit uncompressed data is supported at this time.

See also

CriAtomWavePlayerConfig, criAtomPlayer_CalculateWorkSizeForWavePlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateWavePlayer

criAtomPlayer_CalculateWorkSizeForAiffPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForAiffPlayer

(

const CriAtomAiffPlayerConfig *

config

)

Work area size calculation for AIFF player creation.

Parameters

[in]

config

Configuration structure for AIFF player creation

Returns

CriSint32 Work area size

Return values

0	or greater Processing finished normally
-1	Error occurred

Description:

Acquires the work area size required for creating a player for AIFF playback.

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

Remarks:

The amount of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomAiffPlayerConfig ).

If NULL is specified for the argument, the default settings (the same parameters used when ::criAtomPlayer_SetDefaultConfigForAiffPlayer was applied) will be used to calculate the work area size.
The information of the config argument is referenced only in the function.
Information is not referenced once the function exits, so the area used for config can be released without any problem after executing the function.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, the library must be initialized before this function is executed.

See also

CriAtomAiffPlayerConfig, criAtomPlayer_CreateAiffPlayer

criAtomPlayer_CreateAiffPlayer()

CriAtomPlayerHn criAtomPlayer_CreateAiffPlayer	(	const CriAtomAiffPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

AIFF player creation.

Parameters

[in]	config	Configuration structure for AIFF player creation
[in]	work	Work area
[in]	work_size	Work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing AIFF sounds.
The Atom player created with this function will have AIFF data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if the max_sampling_rate is set to 24000 in config, the created player will not be able to play sound data with sampling rate above 24 kHz.
If NULL is specified for config, the default settings (the same parameters used when ::criAtomPlayer_SetDefaultConfigForAiffPlayer was applied) will be used to create the player.
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory Method: This method passes a necessary memory area directly to the library.
Refer to the description of the criAtomPlayer_CreateAdxPlayer function for the details of each method.

When the criAtomPlayer_CreateAiffPlayer function is executed, an Atom player is created and a handle for controlling the player (CriAtomPlayerHn) is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Use the criAtomPlayer_Start function to start playback.
   

Remarks:

The information of the config argument is referenced only in the function.
Information is not referenced once the function exits, so the area used for config can be released without any problem.

Attention

You must initialize the library before executing this function.

The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with settings that can allocate as many loaders as there are player handles.

This function is a blocking function.
The time required to create an AIFF player varies depending on the platform.
If this function is executed in the main game loop or any other time when a screen update is required, processing will be blocked for a few milliseconds which may result in dropped frames.
Only create and destroy AIFF players when a fluctuation in load is acceptable, for example, during a scene change.

Currently, chunks of AIFF files are not strictly analyzed.
Parsing of an AIFF file may fail if FORM chunk, COMM chunk, and SSND chunk are not included in this order or the file includes other chunks.
In addition, only monaural or stereo 16-bit uncompressed data is supported at this time.

See also

CriAtomAiffPlayerConfig, criAtomPlayer_CalculateWorkSizeForAiffPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateAiffPlayer

criAtomPlayer_CalculateWorkSizeForRawPcmPlayer()

CriSint32 criAtomPlayer_CalculateWorkSizeForRawPcmPlayer

(

const CriAtomRawPcmPlayerConfig *

config

)

Calculate work area size required for creating raw PCM player.

Parameters

[in]

config

raw PCM player creation configuration structure

Returns

CriSint32 work area size

Return values

>=	0 successfully completed
-1	error occurred

Description:

Obtain the work area size required for creating a raw PCM playback player.

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 size of work memory required to create a player depends on the content of the player creation configuration structure ( CriAtomRawPcmPlayerConfig ).

If you specify NULL as argument, the work area size is calculated using the default setting (i.e., the same parameters as when criAtomPlayer_SetDefaultConfigForRawPcmPlayer 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.

Attention

The size of the work area depends on the parameter you specified when initializing the library (when executing the criAtom_Initialize function).
Therefore, you must initialize the library before executing this function.

See also

CriAtomRawPcmPlayerConfig, criAtomPlayer_CreateRawPcmPlayer

criAtomPlayer_CreateRawPcmPlayer()

CriAtomPlayerHn criAtomPlayer_CreateRawPcmPlayer	(	const CriAtomRawPcmPlayerConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Create raw PCM player.

Parameters

[in]	config	raw PCM player creation configuration structure
[in]	work	work area
[in]	work_size	work area size

Returns

CriAtomPlayerHn Atom player handle

Description:

Creates a player capable of playing raw PCM.
The Atom player created with this function will have raw PCM data decoding function.

The format of the sound that can be played with the created player is determined by the parameter specified as the first argument (config).
For example, if max_sampling_rate in config is set to 24000, the created player will not be able to play sound data with sampling rate above 24kHz.
If you specify NULL for config, the player is created with the default setting (same parameter as when criAtomPlayer_SetDefaultConfigForRawPcmPlayer is applied).
When creating a player, the memory area (work area) used internally by the library must be allocated.
There are two ways to allocate a work area.
(a) User Allocator method: A user provided function is used to allocate/release memory.
(b) Fixed Memory method: The required memory is passed directly to the library.
Refer to the description of the criAtomPlayer_CreateAdxPlayer function for the details of each method.

When you execute the criAtomPlayer_CreateRawPcmPlayer function, Atom player is created and the handle (CriAtomPlayerHn ) to control the player is returned.
Atom player operations such as set data and decoder, start playback, and get status are all performed against the handle.

The procedure to play sound data using the created Atom player handle is as follows:

1. Use the criAtomPlayer_SetData function and set in the Atom player the data to play.
   (For file playback, use the criAtomPlayer_SetFile function or the criAtomPlayer_SetContentId function.)
   
2. Start playback with the criAtomPlayer_Start function.
   

Remarks:

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.

The stream playback Atom player internally allocates the loader (CriFsLoaderHn).
When creating a stream playback Atom player, the Atom library (or CRI File System library) must be initialized with setting that can allocate as many loaders as this function.

This function is a blocking function.
The time required to create the raw PCM player depends on the platform.
When you execute this function at timing requiring screen refresh such as game loop, processing is blocked by the millisecond, and frames may be dropped.
Create/destroy raw PCM player when change in load is permissible such as at the change of scenes.

See also

CriAtomRawPcmPlayerConfig, criAtomPlayer_CalculateWorkSizeForRawPcmPlayer, CriAtomPlayerHn, criAtomPlayer_Destroy, criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_SetContentId, criAtomPlayer_Start, criAtomPlayer_CreateRawPcmPlayer

criAtomPlayer_Destroy()

void criAtomPlayer_Destroy

(

CriAtomPlayerHn

player

)

Destroy Atom player.

Parameters

[in]

player

Atom player handle

Description:

Destroys an Atom player.
The memory allocated when you created the Atom player is released when you execute this function.
Also, the Atom player handle specified as argument is disabled.

Attention

This function is a blocking function.
If you attempt to destroy the Atom player while playing sound, resources are released after waiting to stop playback within this function.
(If you are playing from a file, there is also a wait for load to complete.)
Therefore, processing may be blocked for an extended time (few frames) within this function.
Create/destroy Atom player when change in load is permissible such as at the change of scenes.

See also

criAtomPlayer_CreateAdxPlayer, CriAtomPlayerHn

criAtomPlayer_SetData()

void criAtomPlayer_SetData	(	CriAtomPlayerHn	player,
		void *	buffer,
		CriSint32	buffer_size
	)

Set sound data (specify On-memory data)

Parameters

[in]	player	Atom player handle
[in]	buffer	buffer address
[in]	buffer_size	buffer size

Description:

Associates the sound data in memory to an Atom player.
Specify the memory address and size with this function, and then start playback with the criAtomPlayer_Start function to play the specified data.

Example:

main()
{
        :
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Note that once data is set, its information is retained within the Atom player until another data is set.
Therefore, when repeatedly playing the same data, you do not need to set the data again each time you play.

Remarks:

When this function is executed within a data request callback function ( CriAtomPlayerDataRequestCbFunc ), next data is played concatenated to the end of the previously set sound.
For example, when the following code is executed, data in buffer1 and buffer2 are seamlessly concatenated and played.
(Then data in buffer2 is played repeatedly.)

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Set data to play successively
    criAtomPlayer_SetData(player, buffer2, buffer_size2);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set sound data
    criAtomPlayer_SetData(player, buffer1, buffer_size1);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

When this function is executed within a data request callback function ( criAtomPlayer_SetFile ), on-memory data and file can be concatenated and played.
(However, if the on-memory data to play first is too short, there may be a break because there is not enough time to load the file to play next.)

Attention

The player only stores the address and size of the buffer.
(The data inside the buffer is not copied.)
Therefore, the buffer must be maintained by the application until playback of the specified data is finished.

This function can be executed only for player that is stopped.

See also

criAtomPlayer_Start

criAtomPlayer_SetFile()

void criAtomPlayer_SetFile	(	CriAtomPlayerHn	player,
		CriFsBinderHn	binder,
		const CriChar8 *	path
	)

Set sound data (specify file)

Parameters

[in]	player	Atom player handle
[in]	binder	binder handle
[in]	path	file path

Description:

Associates a sound file to an Atom player.
After you specify a file with this function, when you start playback with the criAtomPlayer_Start function, specified file is played back in streaming.
Note that file loading is not started when you execute this function.
File loading is started when you execute the criAtomPlayer_Start function.

Example:

main()
{
        :
    // Set sound file
    criAtomPlayer_SetFile(player, NULL, "sample.adx");
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Note that once file is set, its information is retained within the Atom player until another data is set.
Therefore, when repeatedly playing the same data, you do not need to set the data again each time you play.

Remarks:

When this function is executed within a data request callback function ( CriAtomPlayerDataRequestCbFunc ), next data is played concatenated to the end of the previously set sound.
For example, when the following code is executed, "sample1.adx" and "sample2.adx" are seamlessly concatenated and played.
(Then "sample2.adx" is played repeatedly.)

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Set file to play successively
    criAtomPlayer_SetFile(player, NULL, "sample2.adx");
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set sound file
    criAtomPlayer_SetFile(player, NULL, "sample1.adx");
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Note that by specifying a binder for the second argument (binder), you can also play content of CPK file.

main()
{
        :
    // Bind the CPK file
    criFsBinder_BindCpk(binder, "sample.cpk", work, work_size, &bind_id);
 
    // Wait for the completion of binding
    for (;;) {
        // Check status
        criFsBinder_GetStatus(binder, &status);
        if (status == CRIFSBINDER_STATUS_COMPLETE) {
            break;
        }
 
        // Execute server processing
        criFs_ExecuteMain();
 
        // Wait for Vsync etc.
            :
    }
        :
    // Set sound file
    // set content.adx in sample.cpk
    criAtomPlayer_SetFile(player, binder, "content.adx");
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

When this function is executed within a data request callback function ( criAtomPlayer_SetData ), file and on-memory data can be concatenated and played.

Attention

To play from a file, Atom player supporting streaming playback is necessary.
(Atom player must be created setting streaming_flag in CriAtomAdxPlayerConfig to CRI_TRUE.)
This function can be executed only for player that is stopped.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer, criAtomPlayer_Start

criAtomPlayer_SetContentId()

void criAtomPlayer_SetContentId	(	CriAtomPlayerHn	player,
		CriFsBinderHn	binder,
		CriSint32	id
	)

Set sound data (specify CPK content ID)

Parameters

[in]	player	Atom player handle
[in]	binder	binder handle
[in]	id	content ID

Description:

Associates a content to an Atom player.
This function is used to play back a content file in a CPK file using CRI File System library by specifying file ID.
After you specify a binder and content ID with this function, when you start playback with the criAtomPlayer_Start function, specified content file is played back in streaming.
Note that file loading is not started when you execute this function.
File loading is started when you execute the criAtomPlayer_Start function.

Example:

main()
{
        :
    // Bind the CPK file
    criFsBinder_BindCpk(binder, "sample.cpk", work, work_size, &bind_id);
 
    // Wait for the completion of binding
    for (;;) {
        // Check status
        criFsBinder_GetStatus(binder, &status);
        if (status == CRIFSBINDER_STATUS_COMPLETE) {
            break;
        }
 
        // Execute server processing
        criFs_ExecuteMain();
 
        // Wait for Vsync etc.
            :
    }
        :
    // Set sound file
    // Set the first content in sample.cpk
    criAtomPlayer_SetContentId(player, binder, 1);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Note that once file is set, its information is retained within the Atom player until another data is set.
Therefore, when repeatedly playing the same data, you do not need to set the data again each time you play.

Remarks:

When this function is executed within a data request callback function ( CriAtomPlayerDataRequestCbFunc ), next data is played concatenated to the end of the previously set sound.
For example, when the following code is executed, first data and second data are seamlessly concatenated and played.
(Then the second data is played repeatedly.)

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Get binder
    binder = (CriFsBinderHn)obj;
 
    // Set file to play successively
    // ->Set the second content in the binder
    criAtomPlayer_SetContentId(player, binder, 2);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, binder);
 
    // Set sound file
    // ->Set the first content in the binder
    criAtomPlayer_SetContentId(player, binder, 1);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

When this function is executed within a data request callback function ( criAtomPlayer_SetData ), file and on-memory data can be concatenated and played.

Attention

To play from a file, Atom player supporting streaming playback is necessary.
(Atom player must be created setting streaming_flag in CriAtomAdxPlayerConfig to CRI_TRUE.)

This function can be executed only for player that is stopped.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer, criAtomPlayer_Start

criAtomPlayer_SetWaveId()

void criAtomPlayer_SetWaveId	(	CriAtomPlayerHn	player,
		CriAtomAwbHn	awb,
		CriSint32	id
	)

Set sound data (specify sound data ID)

Parameters

[in]	player	Atom player handle
[in]	awb	AWB handle
[in]	id	wave data ID

Description:

Associates a wave data to be played back to an Atom player.
After you specify an AWB handle and wave data ID with this function, when you start playback with the criAtomPlayer_Start function, specified wave data is played back in streaming.
Note that file loading is not started when you execute this function.
File loading is started when you execute the criAtomPlayer_Start function.

Example:

main()
{
        :
    // Create an AWB handle by loading AWB TOC information
    awb = criAtomAwb_LoadToc(NULL, "sample.awb", NULL, 0);
        :
    // Set wave data
    // Set the first wave data in AWB
    criAtomPlayer_SetWaveId(player, awb, 1);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Note that once file is set, its information is retained within the Atom player until another data is set.
Therefore, when repeatedly playing the same data, you do not need to set the data again each time you play.

Remarks:

When this function is executed within a data request callback function ( CriAtomPlayerDataRequestCbFunc ), next data is played concatenated to the end of the previously set sound.
For example, when the following code is executed, first data and second data are seamlessly concatenated and played.
(Then the second data is played repeatedly.)

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Get AWB handle
    awb = (CriAtomAwbHn)obj;
 
    // Set file to play successively
    // ->Set the second wave data in AWB
    criAtomPlayer_SetWaveId(player, awb, 2);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, awb);
 
    // Set wave data
    // Set the first wave data in AWB
    criAtomPlayer_SetWaveId(player, awb, 1);
 
    // Play set wave data data
    criAtomPlayer_Start(player);
        :
}

When this function is executed within a data request callback function ( criAtomPlayer_SetData ), file and on-memory data can be concatenated and played.

Attention

To play from a file, Atom player supporting streaming playback is necessary.
(Atom player must be created setting streaming_flag in CriAtomAdxPlayerConfig to CRI_TRUE.)

This function can be executed only for player that is stopped.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer, criAtomPlayer_Start

criAtomPlayer_SetPreviousDataAgain()

void criAtomPlayer_SetPreviousDataAgain

(

CriAtomPlayerHn

player

)

Re-set same sound data.

Parameters

[in]

player

Atom player handle

Description:

Instructs the Atom player to replay the data last played.

Example:

The same sound data can be played endlessly with the following process:

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Re-set last played data
    criAtomPlayer_SetPreviousDataAgain(player);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Attention

This function is used only within the data request callback function.
(It can be executed from other functions, but there is no effect.)

See also

criAtomPlayer_SetDataRequestCallback

criAtomPlayer_DeferCallback()

void criAtomPlayer_DeferCallback

(

CriAtomPlayerHn

player

)

Callback function re-execution request.

Parameters

[in]

player

Atom player handle

Description:

Delays processing of data request callback function.
When the sound data to play next is not determined at the time the data request callback function is executed, this callback function can be executed to retry the callback function.
(Data request callback function is called once more after a few milliseconds.)

Remarks:

If nothing is performed within data request callback function, Atom player's status changes to CRIATOMPLAYER_STATUS_PLAYEND.
However, if this function is executed within data request callback function, Atom player maintains the status CRIATOMPLAYER_STATUS_PLAYING.

Attention

When this function is executed, Atom player's status remains CRIATOMPLAYER_STATUS_PLAYING, but there may be break in sound output.
(If there is not enough time to read data, there may be silence between the previous sound and the sound to be set next.)

This function can only be used within the data request callback function.
(An error occurs if it is executed outside the data request callback function.)

See also

criAtomPlayer_SetDataRequestCallback

criAtomPlayer_Start()

void criAtomPlayer_Start

(

CriAtomPlayerHn

player

)

Start playback.

Parameters

[in]

player

Atom player handle

Description:

Starts processing for sound data playback.
Before executing this function, you must use the criAtomPlayer_SetData function to set the sound data to play in the Atom player.
For example, when playing On-memory sound data, you must use the criAtomPlayer_SetData function as follows to set the sound data and then execute this function.

main()
{
        :
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

After executing this function, you can check the progress of the playback (sounding is started or playback has completed) by obtaining the status.
Use the criAtomPlayer_GetStatus function to obtain the status.
The criAtomPlayer_GetStatus function returns five types of status.

1. CRIATOMPLAYER_STATUS_STOP
2. CRIATOMPLAYER_STATUS_PREP
3. CRIATOMPLAYER_STATUS_PLAYING
4. CRIATOMPLAYER_STATUS_PLAYEND
5. CRIATOMPLAYER_STATUS_ERROR

At the time Atom player is created, the status of the Atom player is stop status ( CRIATOMPLAYER_STATUS_STOP ).
After setting the sound data to play, the Atom player status changes to preparation status ( CRIATOMPLAYER_STATUS_PREP ) when this function is executed.
(In CRIATOMPLAYER_STATUS_PREP status, the player is waiting to receive data or start decoding.)
When there is sufficient data to start playing, the Atom player status changes to playing status ( CRIATOMPLAYER_STATUS_PLAYING ) and sound output starts.
When playback of all set data completes, the Atom player status changes to play end status ( CRIATOMPLAYER_STATUS_PLAYEND ).
If an error occurs during playback, the Atom player status changes to error status ( CRIATOMPLAYER_STATUS_ERROR ).

By checking the Atom player status and switching processing according to status, you can create a program that is linked with sound playback status.
For example, code as follows to continue processing after waiting for sound playback to complete.

main()
{
        :
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
 
    // Wait for playback completion
    for (;;) {
        // Get status
        status = criAtomPlayer_GetStatus(player);
 
        // Check status
        if (status == CRIATOMPLAYER_STATUS_PLAYEND) {
            // Exit loop when playback is complete
            break;
        }
 
        // Execute server processing
        criAtom_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
        :
}

Remarks:

After starting playback, there is a time lag before the sound is actually played back.
When playing on-memory data (when data is set with the criAtomPlayer_SetData function), after executing this function, the status changes to CRIATOMPLAYER_STATUS_PLAYEND when server process is executed for the first time.
However, during streaming playback, status remains CRIATOMPLAYER_STATUS_PREP until sufficient data necessary to continue playback is buffered.
(Status changes to CRIATOMPLAYER_STATUS_PLAYING when sufficient data is supplied.)

Note that the timing of status change to CRIATOMPLAYER_STATUS_PLAYING is always when playback instruction is issued to the sound library.
Therefore, the time sound is actually output from the speaker depends on the processing time of each platform's sound library.

The sound output start timing for streaming playback varies according to the number of sounds to be played back simultaneously and the loading speed of the device.
In order to start sound output at the desired timing during streaming playback, use the criAtomPlayer_Pause function to pause and resume when Atom player's status changes to CRIATOMPLAYER_STATUS_PLAYING.
(If the status changes to CRIATOMPLAYER_STATUS_PLAYING while paused, sound output starts when the first server process executes after pause is canceled.

The specific code is as follows:

main()
{
        :
    // Set sound file
    criAtomPlayer_SetData(player, NULL, "sample.adx");
 
    // Pause before starting playback
    criAtomPlayer_Pause(player, CRI_TRUE);
 
    // Play set sound data
    criAtomPlayer_Start(player);
 
    // Wait till status changes to CRIATOMPLAYER_STATUS_PLAYING
    for (;;) {
        // Get status
        status = criAtomPlayer_GetStatus(player);
 
        // Check status
        if (status == CRIATOMPLAYER_STATUS_PLAYING) {
            // Exit loop when status becomes CRIATOMPLAYER_STATUS_PLAYING
            break;
        }
 
        // Execute server processing
        criAtom_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
 
    // Resume
    // ->Sound output starts when the next server process is executed
    criAtomPlayer_Pause(player, CRI_FALSE);
        :
}

Attention

This function cannot be executed against an Atom player that has already started playing.
(Unlike the ADX library, an error occurs if an already playing Atom player is instructed to start playback once more.)
When instructing the Atom player to play, be sure to check the status beforehand to check that it is not in preparation ( CRIATOMPLAYER_STATUS_PREP ) or playing ( CRIATOMPLAYER_STATUS_PLAYING ).

See also

criAtomPlayer_SetData, criAtomPlayer_SetFile, criAtomPlayer_GetStatus, criAtomPlayer_Pause, criAtom_ExecuteMain

criAtomPlayer_Stop()

void criAtomPlayer_Stop

(

CriAtomPlayerHn

player

)

Stop playback.

Parameters

[in]

player

Atom player handle

Description:

Issues stop playback request.
When you execute this function against an Atom player that is playing sound, the Atom player stops playback (stops file read, sound output) and changes the status to stop status ( CRIATOMPLAYER_STATUS_STOP ).
If you execute this function against an already stopped Atom player (Atom player with status CRIATOMPLAYER_STATUS_PLAYEND or CRIATOMPLAYER_STATUS_ERROR), the Atom player status changes to CRIATOMPLAYER_STATUS_STOP.

Attention

If you execute this function against Atom player that is playing a sound, the status may not change immediately to CRIATOMPLAYER_STATUS_STOP.
(It may take some time to enter stop status.)
Therefore, to continue playback of another sound data after stopping playback with this function, be sure to check that the status has changed to CRIATOMPLAYER_STATUS_STOP and then set the next data (or start playback).

main()
{
        :
    // Request to stop playback
    criAtomPlayer_Stop(player);
 
    // Wait till status changes to CRIATOMPLAYER_STATUS_STOP
    for (;;) {
        // Get status
        status = criAtomPlayer_GetStatus(player);
 
        // Check status
        if (status == CRIATOMPLAYER_STATUS_STOP) {
            // Exit loop when status becomes CRIATOMPLAYER_STATUS_STOP
            break;
        }
 
        // Execute server processing
        criAtom_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
 
    // Set another sound file
    criAtomPlayer_SetData(player, NULL, "sample.adx");
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

See also

criAtomPlayer_Start, criAtomPlayer_GetStatus

criAtomPlayer_Pause()

void criAtomPlayer_Pause	(	CriAtomPlayerHn	player,
		CriBool	flag
	)

Pause/resume playback.

Parameters

[in]	player	Atom player handle
[in]	flag	operation flag (CRI_TRUE = pause, CRI_FALSE = resume)

Description:

Pauses or resumes playback.
Whether to pause or resume is specified with the argument flag.
Playback is paused when flag is CRI_TRUE.
Playback is resumed when flag is CRI_FALSE.
Whether the Atom player is paused can be checked with the criAtomPlayer_IsPaused function.

This function is mainly used as follows:

• Pause/resume sound output
• Cue streaming playback

[About pause/resume sound output] When an active Atom player is paused, the sound that was output is interrupted.
When a paused Atom player is resumed, playback resumes where it was interrupted.

[About cuing streaming playback] Pause can also be used for Atom player before starting playback.
When an Atom player is paused before starting playback, no sound is output when the criAtomPlayer_Start function is issued for the paused Atom player.
However, preparation for playback is made and if sufficient data is supplied, the status changes to CRIATOMPLAYER_STATUS_PLAYING .

Atom player stopped at status CRIATOMPLAYER_STATUS_PLAYING can start sound output when playback is resumed.
Therefore, the sound output timing for streaming output can be synchronized with other actions according to the following procedure:

1. Pause Atom player with the criAtomPlayer_Pause function.
2. Instruct Atom player to start playback with the criAtomPlayer_Start function.
3. Wait until Atom player status changes to CRIATOMPLAYER_STATUS_PLAYING.
4. Resume playback with the criAtomPlayer_Pause function when ready to start sound output.

The specific code is as follows:

main()
{
        :
    // Set sound file
    criAtomPlayer_SetData(player, NULL, "sample.adx");
 
    // Pause before starting playback
    criAtomPlayer_Pause(player, CRI_TRUE);
 
    // Play set sound data
    criAtomPlayer_Start(player);
 
    // Wait till status changes to CRIATOMPLAYER_STATUS_PLAYING
    for (;;) {
        // Get status
        status = criAtomPlayer_GetStatus(player);
 
        // Check status
        if (status == CRIATOMPLAYER_STATUS_PLAYING) {
            // Exit loop when status becomes CRIATOMPLAYER_STATUS_PLAYING
            break;
        }
 
        // Execute server processing
        criAtom_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
 
    // Resume
    // ->Sound output starts when the next server process is executed
    criAtomPlayer_Pause(player, CRI_FALSE);
        :
}

Remarks:

Strictly speaking, playback is paused the first time server process executes after executing the criAtomPlayer_Pause function.
Therefore, if pause => resume is performed before server process executes, playback continues without any break in sound.
No error will occur if pause is performed for a paused Atom player or resume is performed for an Atom player that is not paused.
(The function returns without any operation.)

See also

criAtomPlayer_IsPaused, criAtomPlayer_Start

criAtomPlayer_IsPaused()

CriBool criAtomPlayer_IsPaused

(

CriAtomPlayerHn

player

)

Check whether player is paused.

Parameters

[in]

player

Atom player handle

Returns

CriBool pause status (CRI_TRUE = paused, CRI_FALSE = resumed)

Description:

Checks whether the Atom player is paused.
Whether the player is paused is determined by the value set in the argument flag.
Atom player is paused when flag is CRI_TRUE.
Atom player is resumed when flag is CRI_FALSE.

Remarks:

This function simply returns the operation flag specified by the criAtomPlayer_Pause function.
(The value set in the second argument of criAtomPlayer_Pause function is returned as the flag.)
Therefore, the result of this function may not correctly represent whether the sound output is actually stopped.
(Due to a time lag between the execution of the criAtomPlayer_Pause function and the sound output actually stopping.)

See also

criAtomPlayer_Pause

criAtomPlayer_GetStatus()

CriAtomPlayerStatus criAtomPlayer_GetStatus

(

CriAtomPlayerHn

player

)

Get status.

Parameters

[in]

player

Atom player handle

Returns

CriAtomPlayerStatus status

Description:

Obtains Atom player status.
Status is a value indicating the playback status of Atom player and can have the following five values:

1. CRIATOMPLAYER_STATUS_STOP
2. CRIATOMPLAYER_STATUS_PREP
3. CRIATOMPLAYER_STATUS_PLAYING
4. CRIATOMPLAYER_STATUS_PLAYEND
5. CRIATOMPLAYER_STATUS_ERROR

At the time Atom player is created, the status of the Atom player is stop status ( CRIATOMPLAYER_STATUS_STOP ).
After setting the sound data to play, execute the criAtomPlayer_Start function to change the Atom player status to preparation status ( CRIATOMPLAYER_STATUS_PREP ).
(In CRIATOMPLAYER_STATUS_PREP status, the player is waiting to receive data or start decoding.)
When there is sufficient data to start playing, the Atom player status changes to playing status ( CRIATOMPLAYER_STATUS_PLAYING ) and sound output starts.
When playback of all set data completes, the Atom player status changes to play end status ( CRIATOMPLAYER_STATUS_PLAYEND ).
If an error occurs during playback, the Atom player status changes to ( CRIATOMPLAYER_STATUS_ERROR ).

By checking the Atom player status and switching processing according to status, you can create a program that is linked with sound playback status.
For example, code as follows to continue processing after waiting for sound playback to complete.

main()
{
        :
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
 
    // Wait for playback completion
    for (;;) {
        // Get status
        status = criAtomPlayer_GetStatus(player);
 
        // Check status
        if (status == CRIATOMPLAYER_STATUS_PLAYEND) {
            // Exit loop when playback is complete
            break;
        }
 
        // Execute server processing
        criAtom_ExecuteMain();
 
        // Refresh screen display etc.
            :
    }
        :
}

Remarks:

If data load from device fails or data error occurs (when invalid data is loaded), the Atom player status will indicate an error.
In order to display an error message from the application when an data load error occurs, check that the status is CRIATOMPLAYER_STATUS_ERROR and display an approriate error message.

main()
{
        :
    // Get status
    status = criAtomPlayer_GetStatus(player);
 
    // Check status
    if (status == CRIATOMPLAYER_STATUS_ERROR) {
        // Display error message when status becomes CRIATOMPLAYER_STATUS_ERROR
            :
    }
        :
}

See also

criAtomPlayer_Start

criAtomPlayer_GetNumChannels()

CriSint32 criAtomPlayer_GetNumChannels

(

CriAtomPlayerHn

player

)

Get number of channels.

Parameters

[in]

player

Atom player handle

Returns

CriSint32 number of channels

Description:

Obtains the number of channels for the sound being played by the Atom player.

This function returns -1 if it cannot obtain the number of channels.

Attention

Playback time cannot be obtained until player status becomes CRIATOMPLAYER_STATUS_PLAYING .
(An error is returned if this function is executed when the status is CRIATOMPLAYER_STATUS_PREP .)

criAtomPlayer_GetNumPlayedSamples()

CriBool criAtomPlayer_GetNumPlayedSamples	(	CriAtomPlayerHn	player,
		CriSint64 *	num_played,
		CriSint32 *	sampling_rate
	)

Get number of played samples.

Parameters

[in]	player	Atom player handle
[out]	num_played	number of played samples (sample units)
[out]	sampling_rate	sampling rate (Hz)

Returns

CriBool whether the number of samples is obtained ( CRI_TRUE = obtained, CRI_FALSE = not obtained)

Description:

Obtains the number of played samples and sampling rate of sound being played with the Atom player.
Playback time is expressed by the number of sample units, and the sampling rate is expressed in Hz.

If the number of samples correctly is obtained, return value is CRI_TRUE.
If the number of played samples cannot be obtained, return value is CRI_FALSE.
(The sampling_rate will be -1.)

Remarks:

NULL can be specified for unnecessary argument.
For example, to obtain only the sampling rate, NULL can be specified for the second argument ( num_played ).

The number of played samples returned by this function is the cumulative value of the output sound data.
Therefore, even during loop playback or seamless concatenated playback, the number of samples will not be rewound according to the playback position.
Also, the player when paused with the criAtomPlayer_Pause function, counting of played samples will also stop.
(Counting will resume when the player is resumed.)

Attention

The number of played samples cannot be obtained until player status becomes CRIATOMPLAYER_STATUS_PLAYING . (An error is returned if this function is executed when the status is CRIATOMPLAYER_STATUS_PREP .)

The accuracy of the played sample count depends on the platform's sound library.

criAtomPlayer_GetNumRenderedSamples()

CriBool criAtomPlayer_GetNumRenderedSamples	(	CriAtomPlayerHn	player,
		CriSint64 *	num_rendered,
		CriSint32 *	sampling_rate
	)

Acquiring the number of samples to write to the sound buffer.

Parameters

[in]	player	Atom player handle
[out]	num_rendered	Number of written samples (in units of sample)
[out]	sampling_rate	Sampling rate (in Hz)

Returns

CriBool whether the number of samples is obtained ( CRI_TRUE = obtained, CRI_FALSE = not obtained)

Description:

Gets the number of samples written to the sound buffer and the sampling rate for the audio being played by the Atom player.
Unlike the criAtomPlayer_GetNumPlayedSamples function,
it returns a value that includes the number of samples of unoutput audio data written to the sound buffer.
If the number of samples is obtained correctly, the return value will be CRI_TRUE.
If the number of written samples could not be obtained, the return value will be CRI_FALSE.
(In that case sampling_rate will be -1.)

Note

Can specify NULL for arguments that do not need to be retrieved.
For example, if you want to get only the sampling rate, you can specify NULL for the second argument (num_rendered).
The number of samples returned by this function is the cumulative value of the number of written samples.
Therefore, the number of samples does not rewind according to the playback position even when loop playback or seamless connected playback is performed.
Also, if you pose with the criAtomPlayer_Pause function, the count-up of the number of written samples will also stop.
(If you cancel the pause, the count-up will resume.)

Attention

The number of written samples cannot be obtained until the player status becomes CRIATOMPLAYER_STATUS_PLAYING .
(If this function is executed at the time of CRIATOMPLAYER_STATUS_PREP , an error value will be returned.)

The accuracy of the number of samples written depends on the platform's sound library.

See also

criAtomPlayer_GetNumPlayedSamples

criAtomPlayer_GetDecodedDataSize()

CriSint64 criAtomPlayer_GetDecodedDataSize

(

CriAtomPlayerHn

player

)

Acquiring the size of decoded data.

Parameters

[in]

player

Atom player handle

Returns

CriSint64 Amount of decoded data (bytes)

Description:

Returns the number of bytes of sound data decoded in the Atom player.

Note

The amount returned by this function shows the accumulated size since playback is started.
Therefore, even during loop playback or seamless concatenated playback, the amount will not be rewound based on the playback position.
When playback is paused with the criAtomPlayer_Pause function, the count-up of the amount is also stopped.
(Count-up starts again when playback is resumed.)

Attention

When HCA-MX is used or in a platform where compressed sound data is sent directly to hardware (codec where decoding is hidden by the platform SDK), this function cannot acquire the amount of decoded data.

criAtomPlayer_GetNumDecodedSamples()

CriSint64 criAtomPlayer_GetNumDecodedSamples

(

CriAtomPlayerHn

player

)

Acquiring the number of decoded samples.

Parameters

[in]

player

Atom player handle

Returns

CriSint64 Number of decoded samples

Description:

Returns the number of decoded samples in the Atom player.

Note

The number of decoded samples that is returned by this function shows the accumulated number since playback is started.
Therefore, even during loop playback or seamless concatenated playback, the number of decoded samples will not be rewound based on the playback position.
When playback is paused with the criAtomPlayer_Pause function, the count-up of the number is also stopped.
(Count-up starts again when playback is resumed.)

Attention

When HCA-MX is used or in a platform where compressed sound data is sent directly to hardware (codec where decoding is hidden by the platform SDK), this function cannot acquire the number of decoded samples.

criAtomPlayer_GetTime()

CriSint64 criAtomPlayer_GetTime

(

CriAtomPlayerHn

player

)

Get playback time.

Parameters

[in]

player

Atom player handle

Returns

CriSint64 playback time (milliseconds)

Description:

Obtains the current playback time for the sound being played by the Atom player.
Playback time is in milliseconds.

This function returns -1 if there is an error in the argument (if player is NULL).
If this function is executed when playback time is unavailable such as when the player is stopped or in preparation, it will return 0.

Note

Playback time is calculated based on the number of played samples.
Therefore, if the pitch is increased with the criAtomPlayer_SetFrequencyRatio function, playback time will be faster than the actual time.
(If the pitch is reduced, playback time will by slower than the actual time.)

The playback time returned by this function is the cumulative value of the output sound data.
Therefore, even during loop playback or seamless concatenated playback, the time will not be rewound according the playback position.
Also, the player when paused with the criAtomPlayer_Pause function, counting of played time will also stop.
(Counting will resume when the player is resumed.)

Attention

Playback time cannot be obtained until player status becomes CRIATOMPLAYER_STATUS_PLAYING .
Zero is returned if this function is executed when the status is CRIATOMPLAYER_STATUS_PREP .)

The accuracy of the playback time depends on the platform's sound library.

See also

criAtomPlayer_GetStatus, criAtomPlayer_SetFrequencyRatio

criAtomPlayer_GetFormatInfo()

CriBool criAtomPlayer_GetFormatInfo	(	CriAtomPlayerHn	player,
		CriAtomFormatInfo *	info
	)

Get playback sound format information.

Parameters

[in]	player	Atom player handle
[out]	info	format information

Returns

CriBool whether information was obtained ( CRI_TRUE = obtained, CRI_FALSE = not obtained)

Description:

Obtains format information for the sound played by the criAtomPlayer_Start function.

If format information is obtained, this function returns CRI_TRUE.
If format information cannot be obtained, this function returns CRI_FALSE.

Attention

This function can obtain format information only during sound playback.
Format information cannot be obtained if this function is executed before starting playback or during playback preparation.

See also

criAtomPlayer_Start, criAtomPlayer_GetStatus

criAtomPlayer_GetInputBufferRemainSize()

CriSint32 criAtomPlayer_GetInputBufferRemainSize

(

CriAtomPlayerHn

player

)

Get amount of data remaining in input buffer.

Parameters

[in]

player

Atom player handle

Returns

CriSint32 amount of data remaining in input buffer (bytes)

Description:

Obtains the amount of data remaining in the Atom player input buffer.

Remarks:

This is a debug function that can be used only for retrieving information.

If audio break problem occurs, this function can be used to check whether there is data remaining in the input buffer.
If the player status is CRIATOMPLAYER_STATUS_PLAYING , but the amount of remaining data is zero for an extended, supply of data may be blocked due to some kind of error.

criAtomPlayer_GetOutputBufferRemainSamples()

CriSint32 criAtomPlayer_GetOutputBufferRemainSamples

(

CriAtomPlayerHn

player

)

Get amount of data remaining in output buffer.

Parameters

[in]

player

Atom player handle

Returns

CriSint32 amount of data remaining in output buffer (number of samples)

Description:

Obtains the amount of data remaining in the Atom player output buffer.

Remarks:

This is a debug function that can be used only for retrieving information.

If audio break problem occurs, this function can be used to check whether there is data remaining in the output buffer.
If the player status is CRIATOMPLAYER_STATUS_PLAYING , but the amount of remaining data is zero for an extended, decode process may be disabled due to some kind of error.

Attention

This function is valid only when decoding sound data in the Atom library.
On platform that sends compressed sound data directly to hardware (codec with decode process hidden by platform SDK), this function cannot be used to obtain the remaining amount of data.

criAtomPlayer_SetStartTime()

void criAtomPlayer_SetStartTime	(	CriAtomPlayerHn	player,
		CriSint64	start_time_ms
	)

Specify playback start position.

Parameters

[in]	player	Atom player handle
[in]	start_time_ms	playback start position (milliseconds)

Description:

Specifies the playback starting position for the sound played by the Atom player.
In order to play sound data from the middle, the playback start position must be specified with this function before starting playback.

Specify the playback start position in milliseconds.
For example, if this function is executed with start_time_ms set to 10000, the next sound data is played from position at 10 seconds.

Remarks:

Even if the playback position is specified with this function, playback may not start exactly at the specified time.
(Depending on the sound codec, playback may start slightly before the specified time.)

When playing from the middle of sound data, start of sound output may be delayed compared to when starting from the beginning of the sound data.
This is because the sound data header is first analyzed, data is reloaded after jumping to the specified position, and then played.

Attention

A 64 bit value can be specified in start_time_ms, but currently playback time greater than 32 bits cannot be specified.

Even if this function is executed during sound playback, playback position of the sound being played is unchanged.
The value set with this function is accessed only when starting sound playback with the criAtomPlayer_Start function .
It may not be possible to specify the playback start position even for device specific sound format.

See also

criAtomPlayer_Start

criAtomPlayer_SetVolume()

void criAtomPlayer_SetVolume	(	CriAtomPlayerHn	player,
		CriFloat32	vol
	)

Specify volume.

Parameters

[in]	player	Atom player handle
[in]	vol	volume

Description:

Specifies the output sound volume.
This function can be used to change the volume of sound played with Atom player.

Volume is the scaling factor for the amplitude of the sound data (unit is not decibel).
For example, if you specify 1.0f, the original sound is output with the volume unchanged.
If you specify 0.5f, sound is output at volume equal to data with half the amplitude of the original sound wave (-6dB).
If you specify (1.0f / 65536.0f) or less, the sound is muted (silent). \Remarks: Volume value greater than or equal to 1.0f can be specified.
(In CRI Atom library Ver.1.21.07, this specification change has been made.)
When specifying a value over 1.0f, waveform can be played at the volume greater than the material depending on the platform.
When specifying a value less than (1.0f / 65536.0f) or less for volume, the value is clipped to 0.0f.
(Even if specifying a value less than 0.0f, the phase is never reversed.)

The setting of this function and the volume setting of the following functions are controlled independently.

• criAtomPlayer_SetChannelVolume
• criAtomPlayer_SetSendLevel

For example, if this function set 0.5f and the criAtomPlayer_SetChannelVolume function also sets 0.5f, the volume of the output sound will be 0.25f times the original sound.
(Calculated as 0.5f x 0.5f=0.25f.)

Attention

If specifying volume over 1.0f, the following points should be considered:

• The volume behavior may differ on each platform.
• The sound cracking may occur.

Even when specifying volume over 1.0f, whether the sound is played at the volume greater than the source waveform depends on the platform or the audio compression codec.
Therefore, when adjusting volume on the multi-platform title, it is recommended not to use volume over 1.0f.
(If specifying volume over 1.0f, even when playing the same waveform, it may be played at the different volume depending on the platform.)

And, even on the platform where volume can be increased, its hardware has the upper limit of the volume at which the sound can be output, and a noise caused by the sound cracking may be generated.

See also

criAtomPlayer_GetVolume

criAtomPlayer_GetVolume()

CriFloat32 criAtomPlayer_GetVolume

(

CriAtomPlayerHn

player

)

Volume specification.

Parameters

[in]

player

Atom player handle

Returns

CriFloat32 Volume value

Description:

Acquires the output sound volume.
Volume is the scaling factor for the amplitude of the sound data (unit is not decibels).

See also

criAtomPlayer_SetVolume

criAtomPlayer_SetChannelVolume()

void criAtomPlayer_SetChannelVolume	(	CriAtomPlayerHn	player,
		CriSint32	ch,
		CriFloat32	vol
	)

Specify volume for each channel.

Parameters

[in]	player	Atom player handle
[in]	ch	channel number
[in]	vol	volume (0.0f to 1.0f)

Description:

Specifies the output sound volume for each channel.
This function can be used to change the volume of the sounde played with Atom player for each channel.

Specify the "sound data channel number" as the channel number in the second argument.
(Not output speaker ID.)
For example, if the volume of monophonic sound number 0 is changed, all volumes of sound output from the speaker are changed.
(Same behavior as executing the criAtomPlayer_SetVolume function.)
On the other hand, if the volume of stereophonic sound number 0 is changed, by defaut, only volume of sound output from the left speaker is changed.
(If the criAtomPlayer_SetSendLevel function is also used, volume of sound output from the left speaker is not always changed.)

Specify a real value between 0.0f and 1.0f for the volume.
Volume is the scaling factor for the amplitude of the sound data (unit is not decibel).
For example, if you specify 1.0f, the original sound is output with the volume unchanged.
If you specify 0.5f, sound is output at volume equal to data with half the amplitude of the original sound wave (-6dB).
If you specify 0.0f, the sound is muted (silent). \Remarks: If value exceeding than 1.0f is specified for volume, the value is clipped to 1.0f.
(Sound is never played at volume greater than the original sound.)
Similarly, if value less than 0.0f is specified for volume, the value is clipped to 0.0f.
(The phase is never reversed.)
The setting of this function and the volume setting of the following functions are controlled independently.

• criAtomPlayer_SetVolume
• criAtomPlayer_SetSendLevel For example, if this function is set to 0.5f and the criAtomPlayer_SetVolume function is also set to 0.5f, the volume of the output sound will be 0.25f times the original sound.
  (Calculated as 0.5f x 0.5f=0.25f.)

See also

criAtomPlayer_SetVolume, criAtomPlayer_SetSendLevel, criAtomPlayer_SetPanAdx1Compatible

criAtomPlayer_SetSendLevel()

void criAtomPlayer_SetSendLevel	(	CriAtomPlayerHn	player,
		CriSint32	ch,
		CriAtomSpeakerId	spk,
		CriFloat32	level
	)

Set send level.

Parameters

[in]	player	Atom player handle
[in]	ch	channel number
[in]	spk	speaker ID
[in]	level	volume (0.0f to 1.0f)

Description:

Specifies the send level.
Send level is a mechanism to specify the volume of the sound output from each speaker for each channel of the sound data.

Specify the "sound data channel number" as the channel number in the second argument.
For speaker ID in the third argument, specify the speaker to output the data of the specified channel and specify the send volume with the fourth argument.
Specify a real value between 0.0f and 1.0f for the volume.
Volume is the scaling factor for the amplitude of the sound data (unit is not decibel).
For example, if you specify 1.0f, the original sound is output with the volume unchanged.
If you specify 0.5f, sound is output at volume equal to data with half the amplitude of the original sound wave (-6dB).
If you specify 0.0f, the sound is muted (silent).
For example, specify as follows to output the data for sound data channel number 0 from the right speaker at full volume (1.0f).

criAtomPlayer_SetSendLevel(player, 0, CRIATOM_SPEAKER_FRONT_RIGHT, 1.0f);

Unlike specifying volume for each channel (criAtomPlayer_SetChannelVolume function), this function allows you to output data for a single channel from multiple speakers with different volumes.
For example, specify as follows to output the sound of channel number 1 at 0.3f from the left speaker, 0.5f from the right speaker, and 0.7f from the center speaker.

criAtomPlayer_SetSendLevel(player, 1, CRIATOM_SPEAKER_FRONT_LEFT, 0.3f);
criAtomPlayer_SetSendLevel(player, 1, CRIATOM_SPEAKER_FRONT_RIGHT, 0.5f);
criAtomPlayer_SetSendLevel(player, 1, CRIATOM_SPEAKER_FRONT_CENTER, 0.7f);

Note that the set sound level can be reset with the criAtomPlayer_ResetSendLevel function.
\Remarks: There are two ways to set the send level: "Auto" and "Manual".
If immediately after creating the Atom player or if the the criAtomPlayer_ResetSendLevel function is used to clear the send level, the send level is set to "Auto".
After executing this function, the send level is set to "Manual".

If "Manual", Atom player routes sound as follows:

[When playing monophonic sound]
Sound of channel 0 is output from the left and right speakers at approximately 0.7f (-3dB).

[When playing stereophonic sound]
Sound of channel 0 is output from the left speaker and sound of channel 1 is output from the right speaker.

[When playing 4-channel sound]
Sound of channel 0 from the left speaker, sound of channel from the right speaker, sound of channel 2 from the left surround speaker, and the sound of channel 3 from the right surround speaker are output, respectively.

[For 5 channel sound playback]
Channel 0 sound is output from the left speaker, channel 1 sound is output from the right speaker, channel 2 sound is output from the center speaker, channel 3 sound is output from the left surround speaker, and channel 4 sound is output from the right surround speaker.
(You can also change the order for 5 channel sound playback with the ::criAtom_SetChannelMapping function.)

[When playing 5.1-channel sound]
Sound of channel 0 from the left speaker, sound of channel from the right speaker, sound of channel 2 from the center speaker, sound of channel 3 from the LFE speaker, and sound of channel 4 from the left surround speaker, and the sound of channel 5 from the right surround speaker are output, respectively.
(You can also change the order for 6 channel sound playback with the ::criAtom_SetChannelMapping function.)

[For 7.1 channel sound playback]
Channel 0 sound is output from the left speaker, channel 1 sound is output from the right speaker, channel 2 sound is output from the center speaker, channel 3 sound is output from the LFE, channel 4 sound is output from the left surround speaker, channel 5 sound is output from the right surround speaker.
channel 6 sound is output from the left surround back speaker, and channel 7 sound is output from the right surround back speaker.

On the other hand, if this function is used to set "Manually", sound is output by the specified route regardless of the number of sound data channels.
(Sound is not output for channel with no send level set.)
To return routing to "Manual" and clear the send level, execute the criAtomPlayer_ResetSendLevel function.

If value exceeding than 1.0f is specified for volume, the value is clipped to 1.0f.
(Sound is never played at volume greater than the original sound.)
Similarly, if value less than 0.0f is specified for volume, the value is clipped to 0.0f.
(The phase is never reversed.)
The setting of this function and the volume setting of the following functions are controlled independently.

• criAtomPlayer_SetVolume
• criAtomPlayer_SetChannelVolume For example, if this function is set to 0.5f and the criAtomPlayer_SetVolume function is also set to 0.5f, the volume of the output sound will be 0.25f times the original sound.
  (Calculated as 0.5f x 0.5f=0.25f.)

Attention

Even if the sound data to be played is multi-channel data, sound is not output for channel with no send level set if the send level is set only for some of the channels.

Do not use this function together with the criAtomPlayer_SetPanAdx1Compatible function.
Since the criAtomPlayer_SetPanAdx1Compatible function internally calls this function, if both functions are used, settings may be overwritten by the function executed later.
Use either this function or the criAtomPlayer_SetPanAdx1Compatible function to control the normal position of the sound source.
(Use this function when using 3D pan and criAtomPlayer_SetPanAdx1Compatible function when using 2D pan only.)
This function is available only on some device models.
(It is not available in every environment because it is difficult to implement depending on the specification of the platform's sound library.)
Refer to the device dependent information page of the manual to determine whether this function is available.

See also

criAtomPlayer_SetVolume, criAtomPlayer_SetChannelVolume, criAtomPlayer_SetPanAdx1Compatible, criAtomPlayer_ResetSendLevel, criAtom_SetChannelMapping

criAtomPlayer_ResetSendLevel()

void criAtomPlayer_ResetSendLevel

(

CriAtomPlayerHn

player

)

Reset send level.

Parameters

[in]

player

Atom player handle

Description:

Resets the send level.
By executing this function, all previously set send levels are cleared.
\Remarks: Two types of the send level settings, "auto setting" and "manual setting" are available.
The send level setting is set to "auto setting" immediately after creating an Atom player or when resetting the send level with this function.
(For details about the routing in the auto setting, see the description in the criAtomPlayer_SetSendLevel function.)

Attention

Do not use this function together with the criAtomPlayer_ResetPan function.
Since the criAtomPlayer_ResetPan function internally calls this function, if both functions are used, settings may be overwritten by the function executed later.

See also

criAtomPlayer_SetSendLevel, criAtomPlayer_ResetPan

criAtomPlayer_SetPanAdx1Compatible()

void criAtomPlayer_SetPanAdx1Compatible	(	CriAtomPlayerHn	player,
		CriSint32	ch,
		CriFloat32	pan
	)

Set pan.

Parameters

[in]	player	Atom player handle
[in]	ch	channel number
[in]	pan	pan setting (-1.0f to 1.0f)

Description:

Specifies pan (normal position of sound source).
By executing this function, the normal position of sound source can be controlled for monophonic and sterophonic sound.

Specify the "sound data channel number" as the channel number in the second argument.
Specify the normal position of the data of the specified channel number as the pan setting in the third argument.
Specify a real value between -1.0f and 1.0f for the pan setting.
The sound source moves to the left of center when a negative number is specified (further away as value decreases) and to the right of center when a positive number is specified (further away as value increases).
(-1.0f is left end, 0.0f is center, and 1.0f is right end.)
The position of the sound source changes linearly from -1.0f to 1.0f. In other words, if the pan setting is changed constantly from -1.0 to 1.0, the sound source moves at constant speed from left end to right end.

Remarks:

There are two ways to set the pan: "Auto" and "Manual".
If immediately after creating the Atom player or if the the criAtomPlayer_ResetPan function is used to clear the pan setting, pan is set to "Auto".
After executing this function, pan is set to "Manual".

If "Manual", Atom player routes sound as follows:

[When playing monophonic sound]
Sound of channel 0 is output from the left and right speakers at approximately 0.7f (-3dB).

[When playing stereophonic sound]
Sound of channel 0 is output from the left speaker and sound of channel 1 is output from the right speaker.

On the other hand, if this function is used to set "Manually", sound is output by the specified route regardless of the number of sound data channels.
To return routing to "Manual" and clear the pan setting, execute the criAtomPlayer_ResetPan function.

Attention

This function can control pan only for monophonic and stereophonic sound.
To control pan for three or more channels, you must use the criAtomPlayer_SetSendLevel function.

If the sound data to be played is stereophonic, pan can be controlled independently for channel number 0 and channel number 1.
However, since there is no distinction between pan setting for monophonic sound and stereophonic sound, if monophonic sound is played on Atom player with pan set for stereophonic sound, the position of the sound source may not be as intended.

If the sound data to be played is stereophonic, but pan is set only for one of the channels, the position of the channel without pan setting will be 0.0f (output from center).
Be sure to set the pan for both channels in order to control pan of stereophonic sound.

Do not use this function together with the criAtomPlayer_SetSendLevel function.
Since this function internally calls the criAtomPlayer_SetSendLevel function, if both functions are used, settings may be overwritten by the function executed later.
Use either this function or the criAtomPlayer_SetSendLevel function to control the normal position of the sound source.
(Use the criAtomPlayer_SetSendLevel function when using 3D pan and this function when using 2D pan only.)

See also

criAtomPlayer_SetVolume, criAtomPlayer_SetChannelVolume, criAtomPlayer_SetPanAdx1Compatible criAtomPlayer_ResetPan

criAtomPlayer_ResetPan()

void criAtomPlayer_ResetPan

(

CriAtomPlayerHn

player

)

Reset pan.

Parameters

[in]

player

Atom player handle

Description:

Resets the pan setting.
By executing this function, all previously set pan settings are cleared.
\Remarks: Two types of the send level settings, "auto setting" and "manual setting" are available.
The send level setting is set to "auto setting" immediately after creating an Atom player or when resetting the send level with this function.
(For details about the routing in the auto setting, see the description in the criAtomPlayer_SetPanAdx1Compatible function.)

Attention

Do not use this function together with the criAtomPlayer_ResetSendLevel function.
Since this function internally calls the criAtomPlayer_ResetSendLevel function, if both functions are used, settings may be overwritten by the function executed later.

See also

criAtomPlayer_SetPanAdx1Compatible, criAtomPlayer_ResetSendLevel

criAtomPlayer_SetFrequencyRatio()

void criAtomPlayer_SetFrequencyRatio	(	CriAtomPlayerHn	player,
		CriFloat32	ratio
	)

Set frequency adjustment ratio.

Parameters

[in]	player	Atom player handle
[in]	ratio	frequency adjustment ratio

Description:

Sets the sound frequency adjustment ratio.
The frequency adjustment ratio is the ratio between the sound data frequency and the playback frequency. It is equivalent to applying a scaling factor to the playback speed.
If the frequency ratio exceeds 1.0f, sound data is played faster than the original sound. If it is less than 1.0f, the sound data is played slower than the original sound.

The frequency ratio affects the pitch of the sound.
For example, if played at a frequency ratio of 1.0f, the sound data has the same pitch than the original sound. However, if the frequency ratio is set to 2.0f, the pitch is raised one octave.
(Because the playback speed is doubled.)

Example:

// Specify to play sound at 1/2 speed (-1 octave)
criAtomPlayer_SetFrequencyRatio(player, 0.5f);

Attention

If the frequency ratio is greater than 1.0f, there may not be sufficient time to supply or decode the sound data because the data for the sound to be played back is used faster than normal.
(Problems such as interruption of playback may occur.)
If you plan on setting the frequency ratio to a value greater than 1.0f, the maximum sampling rate specified when creating the Atom player should take that frequency ratio into account.
(The max_sampling_rate in the CriAtomAdxPlayerConfig structure when creating the Atom player must be a value equal to "sampling rate of original sound x frequency ratio".)

main()
{
    CriAtomAdxPlayerConfig config;  // Atom player creation configuration structure
    CriAtomAdxPlayerHn player;      // Atom player handle
        :
    // Set Atom player creation configuration structure
    memset(&config, 0, sizeof(config));
    config.max_channels = 2;            // Create stereo-capable player
 
    // To play 48000Hz sound at x1.5 speed
    // Create Atom player at 48000 x 1.5=72000Hz
    config.max_sampling_rate = 72000;   // Play maximum 72000Hz sound
 
    // Create Atom player
    // Specify NULL and 0 in work area.
    // ->Required memory is dynamically allocated within the library.
    player = criAtomPlayer_CreateAdxPlayer(&config, NULL, 0);
        :
    // Change frequency ratio
    criAtomPlayer_SetFrequencyRatio(player, 1.5f);
        :
}

This function is available only on some devices.
(It is not available in every environment because it may be difficult to implement depending on the specifications of the target platform's sound library.)
Refer to the device-dependent information page of the manual to determine whether this function is available.

See also

CriAtomAdxPlayerConfig, criAtomPlayer_CreateAdxPlayer, criAtomPlayer_SetMaxFrequencyRatio

criAtomPlayer_SetMaxFrequencyRatio()

void criAtomPlayer_SetMaxFrequencyRatio	(	CriAtomPlayerHn	player,
		CriFloat32	ratio
	)

Set max of frequency adjustment ratio.

Parameters

[in]	player	Atom player handle
[in]	ratio	maximum value of frequency adjustment ratio

Description:

Sets the maximum value of the sound frequency adjustment ratio.
By setting this maximum value, pitch changing within that can be immediately applied.

Remarks:

In the Atom library prior to Ver.2.10.00, there were cases where the sound would be interrupted when the pitch was increased (the playback speed became faster, resulting in insufficient audio data supply).
To address this issue, Atom Ver.2.10.00 has been modified to buffer the audio sufficiently before raising the pitch so that the sound does not get interrupted even when the pitch is raised.
The fix means that the sound will no longer be interrupted by pitch manipulation, but the pitch change will be delayed by the time it takes to buffer when raising the pitch, so the sound change may be slower than in previous versions.
(When the pitch is raised or lowered in a short period of time, the way the sound is produced may change.)

If you set the maximum frequency adjustment ratio in advance with this function, buffering will always be performed assuming the specified speed, so pitch changes will be performed immediately without buffering (for frequencies within the specified range).
When you want to raise or lower the pitch in a short period of time, set the expected maximum frequency adjustment ratio in this function beforehand and then play the file.

See also

criAtomPlayer_SetFrequencyRatio

criAtomPlayer_LimitLoopCount()

void criAtomPlayer_LimitLoopCount	(	CriAtomPlayerHn	player,
		CriSint32	count
	)

Limit the number of loop playbacks.

Parameters

[in]	player	Atom player handle
[in]	count	number of loop playbacks to be limited

Description:

Limits the number of loop playbacks for waveform data.
For example, when specifying one for the count, the playback of waveform data is looped only once and finished.
(After reaching the loop-end point, it is returned to the loop start position.)

Remarks:

By default, the playback of audio data with loop points is looped infinitely.
After limiting the number of loop playbacks, to return it to the infinite loop, just specify CRIATOMPLAYER_NO_LOOP_LIMITATION for the count.

You can specify ::CRIATOMPLAYER_IGNORE_LOOP for count to play sound data that has a loop point without looping.

Attention

Specify the limited number of loop playbacks before starting an audio playback.
Even when executing this function during the playback, it is not changed.
To stop the loop playback at any timing during the playback, do not use the loop playback but control the playback by the seamless concatenated playback.

The limited number of loop playbacks specified by this function is applied only to the case where the waveform data that loop points are embedded beforehand is played.
If loop points are not put into the waveform data, executing this function does not have no effect.

Even if you use this function to specify the number of loops, the waveform data after the loop end point will not be played when the loop ends.
(After looping the specified number of times, playback will stop at the loop end point.)

As an exception, sound data can also be played as a one-shot sample including data after the loop point if the following conditions are met (the sound will not be looped).

• The data is encoded with "-nodelterm" specified as an argument to criatomencd.exe.
• Playback is executed after specifying ::CRIATOMPLAYER_IGNORE_LOOP for this function.

Only the ADX and HCA codecs can be used to limit the number of loops with this function.
Do not execute this function for platform-dependent audio codecs.
(Doing so may result in playback not finishing, noise, or other issues.)

criAtomPlayer_SetHcaMxMixerId()

void criAtomPlayer_SetHcaMxMixerId	(	CriAtomPlayerHn	player,
		CriSint32	mixer_id
	)

Sepcify HCA-MX decode destination mixer ID.

Parameters

[in]	player	Atom player handle
[in]	mixer_id	mixer id

Description:

Specifies the HCA-MX decode destination mixer ID.

Attention

This function is effective only for player created with the criAtomPlayer_CreateHcaMxPlayer function.
(There is no effect on players created with other functions.)

This function can be executed only for player that is stopped.

See also

criAtomPlayer_CreateHcaMxPlayer

criAtomPlayer_SetAsrRackId()

void criAtomPlayer_SetAsrRackId	(	CriAtomPlayerHn	player,
		CriSint32	rack_id
	)

Specifying the ASR Rack ID.

Parameters

[in]	player	Atom player handle
[in]	rack_id	ASR Rack ID

Description:

Specifies the ID of the voice output rack.

Attention

This function can be executed only for the player that is stopped.

criAtomPlayer_SetRawPcmFormat()

void criAtomPlayer_SetRawPcmFormat	(	CriAtomPlayerHn	player,
		CriAtomPcmFormat	pcm_format,
		CriSint32	num_channels,
		CriSint32	sampling_rate
	)

Specify raw PCM format.

Parameters

[in]	player	Atom player handle
[in]	pcm_format	raw PCM data format
[in]	num_channels	number of channels
[in]	sampling_rate	sampling rate (Hz)

Description:

Specifies raw PCM data format information.

Attention

This function is effective only for player created with the criAtomPlayer_CreateRawPcmPlayer function.
(There is no effect on players created with other functions.)

This function can be executed only for player that is stopped.

See also

criAtomPlayer_CreateRawPcmPlayer

criAtomPlayer_SetDataRequestCallback()

void criAtomPlayer_SetDataRequestCallback	(	CriAtomPlayerHn	player,
		CriAtomPlayerDataRequestCbFunc	func,
		void *	obj
	)

Register data request callback function.

Parameters

[in]	player	Atom player handle
[in]	func	data request callback function
[in]	obj	user specified object

Description:

Registers the data request callback function.

Data request callback is used to seamless concatenate and play multiple sound data.
The registered callback function is executed when the Atom player requests the concatenated playback data.
(The callback function is executed when requesting the data to playback next after the previous data is read.)
When the criAtomPlayer_SetData function is used within the registered callback function to set data in Atom player, the set data is seamlessly concatenated and played after the current data.
Also, by executing the criAtomPlayer_SetPreviousDataAgain function within the callback function, the same data can be played back repeatedly.

Remarks:

If no data is specified in the registered callback function, the Atom player status changes to CRIATOMPLAYER_STATUS_PLAYEND when playback of current data ends.

If you cannot specify the data due to timing but do not want the status to change to CRIATOMPLAYER_STATUS_PLAYEND , execute the criAtomPlayer_DeferCallback function within the callback function.
By executing the criAtomPlayer_DeferCallback function, the data request callback function is called once more after approximately 1V. (The callback process can be retried.)
However, playback may be interrupted when the criAtomPlayer_DeferCallback function is executed (there may be a certain amount of silence at the concatenation point).

Example:

When the following code is executed, data in buffer1 and buffer2 are seamlessly concatenated and played.
(Then data in buffer2 is played repeatedly.)

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Set data to play successively
    criAtomPlayer_SetData(player, buffer2, buffer_size2);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set sound data
    criAtomPlayer_SetData(player, buffer1, buffer_size1);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

The same sound data can be played endlessly with the following process:

// Data request callback function
void on_data_request(void *obj, CriAtomPlayerHn player)
{
    // Re-set previously plaed data
    criAtomPlayer_SetPreviousDataAgain(player);
}
 
main()
{
        :
    // Register data request callback function
    criAtomPlayer_SetDataRequestCallback(player, on_data_request, NULL);
 
    // Set sound data
    criAtomPlayer_SetData(player, buffer, buffer_size);
 
    // Play set sound data
    criAtomPlayer_Start(player);
        :
}

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within the data request callback function.

For a codec that seamless concatenated playback is not supported, even when the next data is set within the data request callback function, the data is not continuously played back.
(When using HCA-MX or a platform specific codec, seamless concatenated playback cannot be performed.)

The format of the waveform data used for seamless concatenated playback should all be the same.
Specifically, the following parameters must be the same.

• コーデック
• Number of channels
• Sampling rate

If you try to concatenate waveforms with different parameters, you may encounter problems such as unintended speed of audio data playback or error callbacks.

Also, when waveform data with loop information is set within the data request callback function, the loop playback is not performed.
(The loop points are discarded, and the playback ends.)

Do not destroy the Atom player within the callback function.
Since the resource of the relevant handle is access within the server process for a while after exiting the callback, severe problems such as access violation may occur.
Only one callback function can be registered.
If you register more than once, the already registered callback function will be overwritten by the callback function you registered later.

You can unregister a registered function by specifying NULL for func.

See also

CriAtomPlayerDataRequestCbFunc, criAtomPlayer_SetData, criAtomPlayer_SetPreviousDataAgain, criAtomPlayer_DeferCallback

criAtomPlayer_SetStatusChangeCallback()

void criAtomPlayer_SetStatusChangeCallback	(	CriAtomPlayerHn	player,
		CriAtomPlayerStatusChangeCbFunc	func,
		void *	obj
	)

Register status change callback function.

Parameters

[in]	player	Atom player handle
[in]	func	status change callback function
[in]	obj	user specified object

Description:

Registers the status change callback function.
The registered callback function is executed when the Atom player status is updated.
The changed status can be retrieved by executing the criAtomPlayer_GetStatus function against the Atom player handle passed as an argument of the callback function.

By using the status change callback, certain process can be performed according to the change in Atom player status.
For example, the following code can be used to display a read error message when the status becomes CRIATOMPLAYER_STATUS_ERROR.

// Status change callback function
void on_status_change(void *obj, CriAtomPlayerHn player)
{
    CriAtomPlayerStatus status;
 
    // Get status
    status = criAtomPlayer_GetStatus(player);
    if (status == CRIATOMPLAYER_STATUS_ERROR) {
        // Processing when read error occurs
            :
    }
}
 
main()
{
        :
    // Register status change callback function
    criAtomPlayer_SetStatusChangeCallback(player, on_status_change, NULL);
 
    // Set sound file
    criAtomPlayer_SetFile(player, NULL, "sample.adx");
 
    // Play set sound file
    criAtomPlayer_Start(player);
        :
}

Remarks:

Strictly speaking, the timing from status change to execution of the callback function may change because another process can interrupt and run during this interval.

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within the status change callback function.

The status of the Atom player is unchanged until the status change callback function is exited.
Therefore, if you wait for Atom player status to change within the status change callback function, a deadlock will occur and processing cannot continue.

Do not destroy the Atom player within the callback function.
Since the resource of the relevant handle is access within the server process for a while after exiting the callback, severe problems such as access violation may occur.
Only one callback function can be registered.
If you register more than once, the already registered callback function will be overwritten by the callback function you registered later.

You can unregister a registered function by specifying NULL for func.

See also

criAtomPlayer_GetStatus

criAtomPlayer_SetParameterChangeCallback()

void criAtomPlayer_SetParameterChangeCallback	(	CriAtomPlayerHn	player,
		CriAtomPlayerParameterChangeCbFunc	func,
		void *	obj
	)

Register parameter change callback function.

Parameters

[in]	player	Atom player handle
[in]	func	status change callback function
[in]	obj	user specified object

Description:

Registers the parameter change callback function.
The registered callback function is executed when the Atom player parameter is updated.

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within the status change callback function.

Do not destroy the Atom player within the callback function.
Since the resource of the relevant handle is access within the server process for a while after exiting the callback, severe problems such as access violation may occur.
Only one callback function can be registered.
If you register more than once, the already registered callback function will be overwritten by the callback function you registered later.

You can unregister a registered function by specifying NULL for func.

criAtomPlayer_SetFilterCallback()

void criAtomPlayer_SetFilterCallback	(	CriAtomPlayerHn	player,
		CriAtomPlayerFilterCbFunc	func,
		void *	obj
	)

Register wave filter callback function.

Parameters

[in]	player	Atom player handle
[in]	func	wave filter callback function
[in]	obj	user specified object

Description:

Registers the callback function that receives decoded PCM data.
The registered callback function is called when the Atom player decodes the sound data.

Attention

Note that problems such as interruption of playback may occur if a process is blocked for an extended time within the status change callback function.
When using HCA-MX or a platform specific codec, the filter callback is not available.

Only one callback function can be registered.
If you register more than once, the already registered callback function will be overwritten by the callback function you registered later.

You can unregister a registered function by specifying NULL for func.

See also

CriAtomPlayerFilterCbFunc

criAtomPlayer_SetLoadRequestCallback()

void criAtomPlayer_SetLoadRequestCallback	(	CriAtomPlayerHn	player,
		CriAtomPlayerLoadRequestCbFunc	func,
		void *	obj
	)

Registering a load request callback function.

Parameters

[in]	player	Atom player handle
[in]	func	Load request callback function
[in]	obj	User specified object

Description:

Registers a load request callback function.

A load request callback is used to monitor the file load status of the Atom player.
(You do not usually need to use this function, because it is intended for debugging.)

Attention

Note that when you block the processing in the load request callback function for a long time, some problems, such as playback interruption may occur.

Do not destroy the Atom player within the callback function.
Even after the callback has finished, the resources of that handle will be referenced within the server process for a while, which may cause serious problems such as access violations.
You can register only one callback function.
When you register a callback function again, the registered callback function is overwritten with the new callback function.

By specifying NULL for func, you can unregister the registered function.

See also

CriAtomPlayerLoadRequestCbFunc

criAtomPlayer_SetHcaFormat()

void criAtomPlayer_SetHcaFormat	(	CriAtomPlayerHn	player,
		CriSint32	num_channels,
		CriSint32	sampling_rate,
		CriSint32	bitrate
	)

Specifying the HCA format.

Parameters

[in]	player	Atom player
[in]	num_channels	Number of channels
[in]	sampling_rate	Sampling rate
[in]	bitrate	Bitrate

Description:

Sets the format information of HCA data.
*By executing this function, you can play HCA data without a header.