CriAtomExFader API

结构体
struct	CriAtomExFaderConfigTag
	Configuration structure used to attach a fader 更多...

宏定义
#define	CRIATOMEX_IGNORE_FADE_OUT   (-1)
	Value used to disable the fade-out process 更多...
#define	criAtomExFader_SetDefaultConfig(p_config)
	Assign the default values to the configuration structure used to attach a Fader 更多...

类型定义
typedef struct CriAtomExFaderConfigTag	CriAtomExFaderConfig
	Configuration structure used to attach a fader 更多...

函数
CriSint32	criAtomExPlayer_CalculateWorkSizeForFader (const CriAtomExFaderConfig *config)
	Calculate the size of the work buffer required to attach a fader 更多...
void	criAtomExPlayer_AttachFader (CriAtomExPlayerHn player, const CriAtomExFaderConfig *config, void *work, CriSint32 work_size)
	Attach a fader to a player 更多...
void	criAtomExPlayer_DetachFader (CriAtomExPlayerHn player)
	Detach a fader from a player 更多...
void	criAtomExPlayer_SetFadeOutTime (CriAtomExPlayerHn player, CriSint32 ms)
	Set the fade-out time 更多...
CriSint32	criAtomExPlayer_GetFadeOutTime (CriAtomExPlayerHn player)
	Get the fade-out time 更多...
void	criAtomExPlayer_SetFadeInTime (CriAtomExPlayerHn player, CriSint32 ms)
	Set the fade-in time 更多...
CriSint32	criAtomExPlayer_GetFadeInTime (CriAtomExPlayerHn player)
	Get the fade-in time 更多...
void	criAtomExPlayer_SetFadeInStartOffset (CriAtomExPlayerHn player, CriSint32 ms)
	Set the fade-in start offset 更多...
CriSint32	criAtomExPlayer_GetFadeInStartOffset (CriAtomExPlayerHn player)
	Get the fade-in start offset 更多...
void	criAtomExPlayer_SetFadeOutEndDelay (CriAtomExPlayerHn player, CriSint32 ms)
	Set the delay time after the fade-out 更多...
CriSint32	criAtomExPlayer_GetFadeOutEndDelay (CriAtomExPlayerHn player)
	Get the delay time after the fade-out 更多...
CriBool	criAtomExPlayer_IsFading (CriAtomExPlayerHn player)
	Check whether fading is in process or not 更多...
void	criAtomExPlayer_ResetFaderParameters (CriAtomExPlayerHn player)
	Initialize the fader parameters 更多...

详细描述

宏定义说明

CRIATOMEX_IGNORE_FADE_OUT

#define CRIATOMEX_IGNORE_FADE_OUT   (-1)

Value used to disable the fade-out process

Description:

Value used to disable the fade-out process of a fader.
By passing this value as the second argument of the criAtomExPlayer_SetFadeOutTime function, the fade-out process of a fader can be disabled.

参见

criAtomExPlayer_SetFadeOutTime

criAtomExFader_SetDefaultConfig

#define criAtomExFader_SetDefaultConfig

(

p_config

)

值:

{\
    (p_config)->reserved = 0;\
}

Assign the default values to the configuration structure used to attach a Fader

参数

[out]

p_config

pointer to the configuration structure used to attach a Fader

Description:

Assigns the default values to the configuration structure ( CriAtomExFaderConfig ) that is passed to the criAtomExPlayer_AttachFader function.

参见

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

类型定义说明

CriAtomExFaderConfig

typedef struct CriAtomExFaderConfigTag CriAtomExFaderConfig

Configuration structure used to attach a fader

Description:

Configuration structure used to attach a fader. It is passed to the criAtomExPlayer_AttachFader function.

注意

While no parameters can be specified at this time, some may be added in the future. Therefore, when using this structure, it is recommended to call the criAtomExFader_SetDefaultConfig macro to initialize it.

参见

criAtomExFader_SetDefaultConfig, criAtomExPlayer_CalculateWorkSizeForFader, criAtomExPlayer_AttachFader

函数说明

criAtomExPlayer_CalculateWorkSizeForFader()

CriSint32 criAtomExPlayer_CalculateWorkSizeForFader

(

const CriAtomExFaderConfig *

config

)

Calculate the size of the work buffer required to attach a fader

参数

[in]

config

configuration structure used to attach a fader

返回

CriSint32 work buffer size

返回值

>=	0 successfully completed
-1	error occurred

Description:

Calculates the size of the work buffer required to attach a fader to an AtomEx player.
If you attach a fader without having registered a user-allocator, you must first calculate the size of the buffer required with this function, allocate that precise amount of memory, and pass it to the criAtomExPlayer_AttachFader function.

When NULL is specified for config, the default settings are used to calculate the work buffer size (i.e. the same parameters that are set when criAtomExFader_SetDefaultConfig is used).

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

Remarks:

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

注意

You must initialize the library before executing this function.

参见

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

criAtomExPlayer_AttachFader()

void criAtomExPlayer_AttachFader	(	CriAtomExPlayerHn	player,
		const CriAtomExFaderConfig *	config,
		void *	work,
		CriSint32	work_size
	)

Attach a fader to a player

参数

[in]	player	AtomEx player
[in]	config	configuration structure used to attach a fader
[in]	work	work buffer
[in]	work_size	work buffer size

Description:

Attaches a fader to the player and switches it to a crossfade-only player.
(Some of the functions provided by a normal AtomEx player will no longer be available, such as the simultaneous playback of multiple sounds.)

Once this function attaches a fader to a player, the player does the following every time the criAtomExPlayer_Start or the criAtomExPlayer_Prepare functions are executed.

• Stops the sound that is fading out.
• Fades out the sound that is being played (or fading in).
• Fades in the sound that starts being played.

When criAtomExPlayer_Stop is called, the following happens:

• Fading out sounds will be forced to stop.
• The currently playing (or fading in) sounds will fade out.

When attaching a fader to a player, you must pass a memory buffer.
The size of the work buffer required is calculated with the criAtomExPlayer_CalculateWorkSizeForFader function.
(If a user-allocator has already been registered by using the criAtomEx_SetUserAllocator macro, you do not need to pass a work buffer to this function.)

If the function fails to attach a fader, an error callback will occur.
To know the reason of the failure, refer to the error callback message.

Example:

The following shows how to croosfade two Cues (MUSIC1 and MUSIC2).

    :
// Create the AtomEx player
player = criAtomExPlayer_Create(NULL, NULL, 0);
 
// Attach a fader to the player
criAtomExPlayer_AttachFader(player, NULL, NULL, 0);
 
// Specify the fade-in/out times
// Remarks: The following example specifies that the crossfading is performed over five seconds.
criAtomExPlayer_SetFadeInTime(player, 5000);    // Specify the fade-in time
criAtomExPlayer_SetFadeOutTime(player, 5000);   // Specify the fade-out time
 
// Set the audio data to be played
criAtomExPlayer_SetCueName(player, acb_hn, "MUSIC1");
 
// Start the playback
// Remarks: This process plays back MUSIC1 with a five-second fade-in.
criAtomExPlayer_Start(player);
    :
(Playback loop)
    :
// Set the audio data to be played back next
criAtomExPlayer_SetCueName(player, acb_hn, "MUSIC2");
 
// Start the playback
// Remarks: This process plays back MUSIC2 while fading MUSIC1 out and fading MUSIC2 in.
criAtomExPlayer_Start(player);
    :

Remarks:

If the player is already playing sounds when the fader is attached to it, these sounds are stopped when this function is executed.

Every time the criAtomExPlayer_Start or criAtomExPlayer_Stop functions are executed on a player with an attached fader, the fader affects the sounds being played:

1. If a sound is fading out, it is stopped immediately.
2. If a sound is fading in (or being played), it is faded out from its current volume over the time specified by the criAtomExPlayer_SetFadeOutTime function.
3. If the criAtomExPlayer_Start function is executed, the playback of the sound data assigned to the player is started at volume 0, and the sound is faded in over the time specified by the criAtomExPlayer_SetFadeInTime function.

(If you use the criAtomExPlayer_Prepare function instead of the criAtomExPlayer_Start function, the above happens when the pause is canceled.)

注意

If you execute this function, the play/stop operation of the AtomEx player is radically changed.
(The behavior changes significantly before and after fader attachment.)
The number of voices that can be played simultaneously is limited to one (two during cross-fading), and control with CriAtomExPlaybackId becomes unavailable.

This function is required only if you want to achieve crossfading.
To fade in or fade out a single sound, you should use an envelope or a Tween.

If you pass a work buffer to this function, the memory must be maintained by the application until the fader is detached.
(Do not write a value in the work buffer once it has already been passed and do not release the memory.)

Due to the specifications of the fader, only the two previous sounds being played back are faded in or out.
The sounds that were played before that are stopped forcefully when the criAtomExPlayer_Start or criAtomExPlayer_Stop functions are called.
An unexpected noise may occur when the sounds are forcefully stopped. Therefore, please ensure that the number of simultaneous playbacks is not three or more.
(Use the criAtomExPlayer_GetNumPlaybacks function to check the number of sounds being played simultaneously.)

The fade-in and fade-out functions are only available at the player level.
Fade out will not occur for any playback ID acquired by executing the criAtomExPlayer_Start function, even when criAtomExPlayback_Stop is called.
(The fader settings will be ignored and the stop request is immediately processed.)

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

参见

CriAtomExFaderConfig, criAtomExPlayer_CalculateWorkSizeForFader

criAtomExPlayer_DetachFader()

void criAtomExPlayer_DetachFader

(

CriAtomExPlayerHn

player

)

Detach a fader from a player

参数

[in]

player

AtomEx player

Description:

Detaches a fader from a player.
After this function detaches a fader from a player, the player does not perform fade-in/out control anymore.

Remarks:

If the player from which the fader is detached is still playing sounds, they are all stopped when this function is executed.

If you destroy a player without executing this function, when the player is destroyed (by executing the criAtomExPlayer_Destroy function), the fader is detached within the library.

参见

criAtomExPlayer_AttachFader

criAtomExPlayer_SetFadeOutTime()

void criAtomExPlayer_SetFadeOutTime	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

Set the fade-out time

参数

[in]	player	AtomEx player handle
[in]	ms	fade-out time (in milliseconds)

Description:

Specifies the fade-out time used by a player with an attached fader.
The next time audio playback is performed (by calling the criAtomExPlayer_Start function), the sound will fade out over the time specified by this function.

The default fade-out time is 500 milliseconds.

Remarks:

When a fade-out time has been set, the AtomEx player stops the playback in the following order:

1. It decreases the audio volume to 0 over the specified time.
2. It continues the playback at a volume of 0 until a delay time passes.
3. It stops the playback after the delay time has passed.

The volume control for fade-out is performed before the audio playback is stopped.
Therefore, the release time of an envelope specified in a waveform data in advance is ignored.
(Strictly speaking, the release process of the envelope is applied after the volume is 0.)

Depending on whether the second argument (ms) is set to 0 or CRIATOMEX_IGNORE_FADE_OUT , the behavior of the function is different:

• If 0 is specified: the function immediately turns down the volume to 0 and performs the stopping process.
• If CRIATOMEX_IGNORE_FADE_OUT is specified, the function performs the stopping process without turning down the volume.

If, when the playback is stopped, you want to enable the release process of the envelope (as specified for the waveform beforehand, without performing the fade-out process) specify CRIATOMEX_IGNORE_FADE_OUT for the second argument (ms).
Specifying CRIATOMEX_IGNORE_FADE_OUT disables volume control by the fade-out process. After the criAtomExPlayer_Stop function is called, the standard stopping process is performed (after the delay time has passed).
(If the release of the envelope has been set in the waveform data, a release process will be performed.)

注意

Before calling this function, you must use the criAtomExPlayer_AttachFader function to attach a fader to the player.

The value set by this function does not affect the sounds during playback.
The fading time set by this function is only applied when the criAtomExPlayer_Start or criAtomExPlayer_Stop functions are called later.
(If a sound's fade-out process has already started, you cannot change the fade-out time.)

参见

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeOutTime()

CriSint32 criAtomExPlayer_GetFadeOutTime

(

CriAtomExPlayerHn

player

)

Get the fade-out time

参数

[in]

player

AtomEx player handle

返回

CriSint32 fade-out time (in milliseconds)

Description:

Gets the fade-out time.

Remarks:

This function returns the value set by the criAtomExPlayer_SetFadeOutTime function.

参见

criAtomExPlayer_SetFadeOutTime

criAtomExPlayer_SetFadeInTime()

void criAtomExPlayer_SetFadeInTime	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

Set the fade-in time

参数

[in]	player	AtomEx player handle
[in]	ms	fade-in time (in milliseconds)

Description:

Specifies the fade-in time used by a player with an attached fader.
The next time audio playback is performed (by calling the criAtomExPlayer_Start function), the sound will fade in over the time specified by this function.

The default fade-in time is 0 seconds.
Therefore, if this function is not used, a fade-in process is not performed, and the audio playback starts immediately at full volume.

注意

Before executing this function, you must call the criAtomExPlayer_AttachFader function to attach a fader to the player.

The value set by this function does not affect the sounds during playback.
The fading time set by this function is only applied when the criAtomExPlayer_Start or criAtomExPlayer_Stop functions are called later.
(If a sound's fade-in process has already started, you cannot change the fade-in time.)

参见

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeInTime()

CriSint32 criAtomExPlayer_GetFadeInTime

(

CriAtomExPlayerHn

player

)

Get the fade-in time

参数

[in]

player

AtomEx player handle

返回

CriSint32 fade-in time (in milliseconds)

Description:

Gets the fade-in time.

Remarks:

This function returns the value set by the criAtomExPlayer_SetFadeInTime function.

参见

criAtomExPlayer_SetFadeInTime

criAtomExPlayer_SetFadeInStartOffset()

void criAtomExPlayer_SetFadeInStartOffset	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

Set the fade-in start offset

参数

[in]	player	AtomEx player handle
[in]	ms	fade-in start offset (in milliseconds)

Description:

Specifies the fade-in start offset for a player with an attached fader.
By using this function, you can arbitrarily advance or delay the beginning of a fade-in relatively to a fade-out.
For example, if you set the fade-out time to 5 seconds and the fade-in start offset to 5 seconds, you can fade in the next sound immediately after the fade-out for 5 seconds.
On the other hand, if you set the fade-in time to 5 seconds and the fade-in start offset to -5 seconds, you can start fading out the sound during playback immediately after the fade-in for 5 seconds.

The default fade-in start offset is 0 seconds.
(Fade-in and fade-out start simultaneously.)

Remarks:

A fade-in starts when a sound to be faded in is ready to be played back.
Therefore, even if the fade-in start offset is set to 0 seconds, it may take a while to actually start the fade-in, especially if it takes time to buffer the sound (e.g. during streaming playback).
(This parameter is a relative value for adjusting the timings of the fade-in and fade-out.)

注意

Before executing this function, you must call the criAtomExPlayer_AttachFader function to attach a fader to the player.

The value set by this function does not affect the sounds during playback.
The fading time is applied when the criAtomExPlayer_Start or the criAtomExPlayer_Stop functions are called (after this function).
(It is not possible to change the fading offset of a sound whose fading process has already started by using this function.)

参见

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeInStartOffset()

CriSint32 criAtomExPlayer_GetFadeInStartOffset

(

CriAtomExPlayerHn

player

)

Get the fade-in start offset

参数

[in]

player

AtomEx player handle

返回

CriSint32 fade-in start offset (in milliseconds)

Description:

Gets the fade-in start offset.

Remarks:

Returns the value set by the criAtomExPlayer_SetFadeInStartOffset function.

参见

criAtomExPlayer_SetFadeInStartOffset

criAtomExPlayer_SetFadeOutEndDelay()

void criAtomExPlayer_SetFadeOutEndDelay	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

Set the delay time after the fade-out

参数

[in]	player	AtomEx player handle
[in]	ms	delay time after fade-out (in milliseconds)

Description:

Specifies the delay time after the end of a fade-out and before a voice is destroyed.
By using this function, you can arbitrarily set the time at which a voice will be destroyed after having faded out.

The default delay time is 500 milliseconds.
(i.e. a voice that plays a fade-out sound is destroyed 500 milliseconds after the volume has reached 0.)

Remarks:

Except on platforms for which a voice is stopped before the sound is faded out, you do not need to use this function.

注意

Before calling this function, you must call the criAtomExPlayer_AttachFader function to attach a fader to the player.

The value set by this function does not affect the sounds during playback.
The delay time set by this function is applied when the criAtomExPlayer_Start or criAtomExPlayer_Stop functions are called (after this function).
(It is not possible to change the delay time of a sound for which the fade-out process has already started.)

When the volume is controlled and when the voice is stopped differs depending on the platforms.
Therefore, if 0 is specified by this function, the voice may be stopped before the volume is changed on some platforms.

参见

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeOutEndDelay()

CriSint32 criAtomExPlayer_GetFadeOutEndDelay

(

CriAtomExPlayerHn

player

)

Get the delay time after the fade-out

参数

[in]

player

AtomEx player handle

返回

CriSint32 delay time that after a fade-out (in milliseconds)

Description:

Gets the delay time after the fade-out.

Remarks:

This function returns the value set by the criAtomExPlayer_SetFadeOutEndDelay function.

参见

criAtomExPlayer_SetFadeOutEndDelay

criAtomExPlayer_IsFading()

CriBool criAtomExPlayer_IsFading

(

CriAtomExPlayerHn

player

)

Check whether fading is in process or not

参数

[in]

player

AtomEx player handle

返回

CriBool fading status (CRI_TRUE = fading, CRI_FALSE = not fading)

Description:

Checks whether fading is in process or not.

Remarks:

This function returns CRI_TRUE in the following cases:

• when it is waiting for the synchronization to start a crossfade.
• when it is processing the fade-in/fade-out (changing volume).
• during the fade-out delay time.

criAtomExPlayer_ResetFaderParameters()

void criAtomExPlayer_ResetFaderParameters

(

CriAtomExPlayerHn

player

)

Initialize the fader parameters

参数

[in]

player

AtomEx player handle

Description:

Clears the parameters set for the fader and restores them to their initial values.

注意

Before calling this function, you must use the criAtomExPlayer_AttachFader function to attach a fader to the player.

Clearing the fader parameters with this function does not affect the sounds that are already being played.
The fader parameters cleared by this function take effect when the criAtomExPlayer_Start or the criAtomExPlayer_Stop functions are executed.
(You cannot apply a parameter reset using this function to a sound for which a fading process has already started.)

参见

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime