CriAtomExFader API

データ構造
struct	CriAtomExFaderConfigTag
	フェーダーアタッチ用コンフィグ構造体 [詳解]

マクロ定義
#define	CRIATOMEX_IGNORE_FADE_OUT   (-1)
	フェードアウト処理の無効化指定値 [詳解]
#define	criAtomExFader_SetDefaultConfig(p_config)
	フェーダーアタッチ用コンフィグ構造体にデフォルト値をセット [詳解]

型定義
typedef struct CriAtomExFaderConfigTag	CriAtomExFaderConfig
	フェーダーアタッチ用コンフィグ構造体 [詳解]

関数
CriSint32 CRIAPI	criAtomExPlayer_CalculateWorkSizeForFader (const CriAtomExFaderConfig *config)
	フェーダーのアタッチに必要なワーク領域サイズの計算 [詳解]
void CRIAPI	criAtomExPlayer_AttachFader (CriAtomExPlayerHn player, const CriAtomExFaderConfig *config, void *work, CriSint32 work_size)
	プレーヤーにフェーダーを取り付ける [詳解]
void CRIAPI	criAtomExPlayer_DetachFader (CriAtomExPlayerHn player)
	プレーヤーからフェーダーを取り外す [詳解]
void CRIAPI	criAtomExPlayer_SetFadeOutTime (CriAtomExPlayerHn player, CriSint32 ms)
	フェードアウト時間の設定 [詳解]
CriSint32 CRIAPI	criAtomExPlayer_GetFadeOutTime (CriAtomExPlayerHn player)
	フェードアウト時間の取得 [詳解]
void CRIAPI	criAtomExPlayer_SetFadeInTime (CriAtomExPlayerHn player, CriSint32 ms)
	フェードイン時間の設定 [詳解]
CriSint32 CRIAPI	criAtomExPlayer_GetFadeInTime (CriAtomExPlayerHn player)
	フェードイン時間の取得 [詳解]
void CRIAPI	criAtomExPlayer_SetFadeInStartOffset (CriAtomExPlayerHn player, CriSint32 ms)
	フェードイン開始オフセットの設定 [詳解]
CriSint32 CRIAPI	criAtomExPlayer_GetFadeInStartOffset (CriAtomExPlayerHn player)
	フェードイン開始オフセットの取得 [詳解]
void CRIAPI	criAtomExPlayer_SetFadeOutEndDelay (CriAtomExPlayerHn player, CriSint32 ms)
	フェードアウト後のディレイ時間の設定 [詳解]
CriSint32 CRIAPI	criAtomExPlayer_GetFadeOutEndDelay (CriAtomExPlayerHn player)
	フェードアウト後のディレイ時間の取得 [詳解]
CriBool CRIAPI	criAtomExPlayer_IsFading (CriAtomExPlayerHn player)
	フェード処理中かどうかのチェック [詳解]
void CRIAPI	criAtomExPlayer_ResetFaderParameters (CriAtomExPlayerHn player)
	フェーダーパラメーターの初期化 [詳解]

詳解

マクロ定義詳解

CRIATOMEX_IGNORE_FADE_OUT

#define CRIATOMEX_IGNORE_FADE_OUT   (-1)

フェードアウト処理の無効化指定値

説明:

フェーダーのフェードアウト処理を無効化するための値です。
criAtomExPlayer_SetFadeOutTime 関数の第2引数に本パラメーターをセットすることで、 フェードアウト処理を無効化することが可能です。

参照

criAtomExPlayer_SetFadeOutTime

criAtomExFader_SetDefaultConfig

#define criAtomExFader_SetDefaultConfig

(

p_config

)

値:

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

フェーダーアタッチ用コンフィグ構造体にデフォルト値をセット

引数

[out]

p_config

フェーダーアタッチ用コンフィグ構造体へのポインタ

説明:

criAtomExPlayer_AttachFader 関数に設定するコンフィグ構造体 （ CriAtomExFaderConfig ）に、デフォルトの値をセットします。

参照

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

型定義詳解

CriAtomExFaderConfig

typedef struct CriAtomExFaderConfigTag CriAtomExFaderConfig

フェーダーアタッチ用コンフィグ構造体

説明:

criAtomExPlayer_AttachFader 関数の引数に指定する、フェーダーアタッチ用のコンフィグ構造体です。

注意

現状指定可能なパラメーターはありませんが、将来パラメーターが追加される可能性があるため、 本構造体を使用する際には criAtomExFader_SetDefaultConfig マクロを使用し、 構造体の初期化を行ってください。

参照

criAtomExFader_SetDefaultConfig, criAtomExPlayer_CalculateWorkSizeForFader, criAtomExPlayer_AttachFader

関数詳解

criAtomExPlayer_CalculateWorkSizeForFader()

CriSint32 CRIAPI criAtomExPlayer_CalculateWorkSizeForFader

(

const CriAtomExFaderConfig *

config

)

フェーダーのアタッチに必要なワーク領域サイズの計算

引数

[in]

config

フェーダーアタッチ用コンフィグ構造体

戻り値

CriSint32 ワーク領域サイズ

戻り値

0以上	正常に処理が完了
-1	エラーが発生

説明:

AtomExプレーヤーにフェーダーをアタッチするのに必要な、ワーク領域のサイズを取得します。
アロケーターを登録せずにフェーダーをアタッチする場合、あらかじめ本関数で計算した ワーク領域サイズ分のメモリをワーク領域として criAtomExPlayer_AttachFader 関数に セットする必要があります。

引数にNULLを指定した場合、デフォルト設定 （ criAtomExFader_SetDefaultConfig 適用時と同じパラメーター）で ワーク領域サイズを計算します。

ワーク領域サイズ計算時に失敗した場合、戻り値は -1 になります。
ワーク領域サイズの計算に失敗した理由については、エラーコールバックの メッセージで確認可能です。

備考:

引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。

注意

本関数を実行する前に、ライブラリを初期化しておく必要があります。

参照

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

criAtomExPlayer_AttachFader()

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

プレーヤーにフェーダーを取り付ける

引数

[in]	player	AtomExプレーヤー
[in]	config	フェーダーアタッチ用コンフィグ構造体
[in]	work	ワーク領域
[in]	work_size	ワーク領域サイズ

説明:

プレーヤーにフェーダーをアタッチ（取り付け）し、 AtomExPlayerをクロスフェード専用のプレーヤーに変化させます。
（複数音の同時再生等、従来のAtomExPlayerの持つ機能が一部利用できなくなります。）

本関数でフェーダーをアタッチしたプレーヤーは、以降音声再生開始毎 （ criAtomExPlayer_Start 関数や criAtomExPlayer_Prepare 実行を実行する毎）に、 以下の制御を行います。

• 既にフェードアウト中の音があれば強制停止。
• 現在再生中（またはフェードイン中）の音声をフェードアウト。
• 新規に再生を開始する音声をフェードイン。

また、再生停止時（ criAtomExPlayer_Stop 関数実行時）には、 以下の制御を行います。

• 既にフェードアウト中の音があれば強制停止。
• 現在再生中（またはフェードイン中）の音声をフェードアウト。

プレーヤーにフェーダーを取り付ける際には、ワーク領域としてメモリを渡す必要があります。
必要なメモリのサイズは、 criAtomExPlayer_CalculateWorkSizeForFader 関数で計算します。
（::criAtomEx_SetUserAllocator マクロを使用してアロケーターを登録済みの場合、 本関数にワーク領域を指定する必要はありません。）

フェーダーのアタッチに失敗した場合、関数内でエラーコールバックが発生します。
フェーダーのアタッチに失敗した理由については、エラーコールバックのメッセージを確認してください。

例:

2 つのキュー（ MUSIC1 と MUSIC2 ）をクロスフェードさせる場合の処理は、以下のとおりです。

    ：
// AtomExプレーヤーの作成
player = criAtomExPlayer_Create(NULL, NULL, 0);
 
// プレーヤーにフェーダーをアタッチ
criAtomExPlayer_AttachFader(player, NULL, NULL, 0);
 
// フェードイン／アウト時間の指定
// 備考）下記の例では5秒でクロスフェードを行うよう指定。
criAtomExPlayer_SetFadeInTime(player, 5000);    // フェードイン時間の指定
criAtomExPlayer_SetFadeOutTime(player, 5000);   // フェードアウト時間の指定
 
// 再生する音声データをセット
criAtomExPlayer_SetCueName(player, acb_hn, "MUSIC1");
 
// 再生の開始
// 備考）この処理により、MUSIC1が5秒でフェードインしながら再生される。
criAtomExPlayer_Start(player);
    ：
（再生ループ）
    ：
// 次に再生する音声データをセット
criAtomExPlayer_SetCueName(player, acb_hn, "MUSIC2");
 
// 再生の開始
// 備考）この処理により、MUSIC1がフェードアウトしつつ、MUSIC2がフェードインしながら再生される。
criAtomExPlayer_Start(player);
    ：

備考:

フェーダーをアタッチするプレーヤーが音声再生中の場合、本関数を実行したタイミングで プレーヤーが再生中の音声は全て停止されます。

フェーダーは、アタッチ中のプレーヤーに対して criAtomExPlayer_Start 関数や、 criAtomExPlayer_Stop 関数が実行される度、 当該プレーヤーで再生中の音声に対して以下の制御を行います。

1. 既にフェードアウト中の音声が存在する場合、その音声を即座に停止する。
2. フェードイン中の音声（または再生中の音声）が存在する場合、 その音声をその時点の音量から criAtomExPlayer_SetFadeOutTime 関数で指定された時間をかけてフェードアウトさせる。
3. criAtomExPlayer_Start 関数が実行された場合、 プレーヤーにセットされている音声データをボリューム0で再生開始し、 criAtomExPlayer_SetFadeInTime 関数で指定された時間をかけてフェードインさせる。

（ criAtomExPlayer_Start 関数の代わりに criAtomExPlayer_Prepare 関数を使用した場合、ポーズを解除する時点で上記の制御が行われます。）

注意

本関数を実行すると、AtomExPlayerに対する再生／停止操作が大きく変更されます。
（フェーダーアタッチ前後で挙動が大きく変わります。）
具体的には、同時に発音可能な音声の数が1音（クロスフェード中のみ2音）に限定され、 CriAtomExPlaybackId を用いた制御も行えなくなります。

本関数は、クロスフェード処理を行いたい場合にのみ必要となります。
1音だけのフェードイン／アウトについては、エンベロープやTweenをご利用ください。

本関数にワーク領域をセットした場合、セットした領域のメモリをフェーダーデタッチ時 までアプリケーション中で保持し続ける必要があります。
（セット済みのワーク領域に値を書き込んだり、メモリ解放したりしてはいけません。）

フェーダーの動作仕様の都合上、フェードイン／アウトの処理対象となるのは、 過去2回の音声再生のみです。
それ以前に再生された音声は、 criAtomExPlayer_Start 関数や criAtomExPlayer_Stop 関数が実行された時点で強制的に停止されます。
強制停止処理のタイミングで意図しないノイズが発生する恐れがありますので、 同時再生数が3音以上にならないよう注意してください。
（ criAtomExPlayer_GetNumPlaybacks 関数で同時再生数を確認してください。）

フェードイン／アウトが機能するのは『AtomExプレーヤーに対する操作』のみです。
criAtomExPlayer_Start 関数実行時に取得した再生IDに対し、 criAtomExPlayback_Stop を実行しても、フェードアウトは行われません。
（フェーダーの設定が無視され、即座に停止処理が行われます。）

引数 config の情報は、関数内でのみ参照されます。
関数を抜けた後は参照されませんので、関数実行後に config の領域を解放しても 問題ありません。

参照

CriAtomExFaderConfig, criAtomExPlayer_CalculateWorkSizeForFader

criAtomExPlayer_DetachFader()

void CRIAPI criAtomExPlayer_DetachFader

(

CriAtomExPlayerHn

player

)

プレーヤーからフェーダーを取り外す

引数

[in]

player

AtomExプレーヤー

説明:

プレーヤーからフェーダーをデタッチ（取り外し）します。
本関数でフェーダーをデタッチしたプレーヤーには、以降フェードイン／アウトの処理が行われなくなります。

備考:

フェーダーをデタッチするプレーヤーが音声再生中の場合、本関数を実行したタイミングで プレーヤーが再生中の音声は全て停止されます。

本関数を実行せずにプレーヤーを破棄した場合、プレーヤー破棄時（ criAtomExPlayer_Destroy 関数実行時） にライブラリ内でフェーダーのデタッチが行われます。

参照

criAtomExPlayer_AttachFader

criAtomExPlayer_SetFadeOutTime()

void CRIAPI criAtomExPlayer_SetFadeOutTime	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

フェードアウト時間の設定

引数

[in]	player	AtomExプレーヤーハンドル
[in]	ms	フェードアウト時間（ミリ秒指定）

説明:

フェーダーをアタッチ済みのプレーヤーに対し、フェードアウト時間を指定します。
次回音声再生時（ criAtomExPlayer_Start 関数実行時）には、本関数で設定された 時間で再生中の音声がフェードアウトします。

フェードアウト時間のデフォルト値は 500 ミリ秒です。

備考:

フェードアウト時間が設定されている場合、AtomExプレーヤーは以下の順序で再生を停止します。

1. 指定された時間で音声のボリュームを 0 まで落とす。
2. ボリュームが 0 の状態でディレイ時間が経過するまで再生を続ける。
3. ディレイ時間経過後に再生を停止する。

フェードアウト時のボリュームコントロールは、音声再生停止前に行われます。
そのため、波形データにあらかじめ設定されたエンベロープのリリース時間は無視されます。
（厳密には、ボリュームが 0 になってからエンベロープのリリース処理が適用されます。）

第2引数（ ms ）に 0 を指定する場合と、 CRIATOMEX_IGNORE_FADE_OUT を指定する場合とでは、以下のように挙動が異なります。

• 0指定時：即座にボリュームが 0 に落とされ、停止処理が行われる。
• CRIATOMEX_IGNORE_FADE_OUT指定時：ボリューム変更は行われず、停止処理が行われる。

再生停止時にフェードアウト処理を行わず、波形にあらかじめ設定されている エンベロープのリリース処理を有効にしたい場合、第2引数（ ms ）に、 CRIATOMEX_IGNORE_FADE_OUT を指定してください。
CRIATOMEX_IGNORE_FADE_OUT を指定することで、 フェードアウト処理によるボリューム制御が行われなくなるため、 criAtomExPlayer_Stop 関数実行後、ディレイ時間経過後に通常の停止処理が行われます。
（波形データにエンベロープのリリースが設定されている場合、リリース処理が行われます。）

注意

本関数を実行する前に、 criAtomExPlayer_AttachFader 関数を使用して あらかじめプレーヤーにフェーダーをアタッチしておく必要があります。

本関数で設定した値は、既に再生中の音声には一切影響しません。
本関数で設定したフェード時間は、本関数実行後に criAtomExPlayer_Start 関数や criAtomExPlayer_Stop 関数を実行するタイミングで適用されます。
（既にフェードアウトを開始している音声に対しては、 本関数で後からフェードアウト時間を変更することはできません。）

参照

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeOutTime()

CriSint32 CRIAPI criAtomExPlayer_GetFadeOutTime

(

CriAtomExPlayerHn

player

)

フェードアウト時間の取得

引数

[in]

player

AtomExプレーヤーハンドル

戻り値

CriSint32 フェードアウト時間（ミリ秒単位）

説明:

フェードアウト時間を取得します。

備考:

本関数は criAtomExPlayer_SetFadeOutTime 関数でセットした値を返します。

参照

criAtomExPlayer_SetFadeOutTime

criAtomExPlayer_SetFadeInTime()

void CRIAPI criAtomExPlayer_SetFadeInTime	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

フェードイン時間の設定

引数

[in]	player	AtomExプレーヤーハンドル
[in]	ms	フェードイン時間（ミリ秒指定）

説明:

フェーダーをアタッチ済みのプレーヤーに対し、フェードイン時間を指定します。
次回音声再生時（ criAtomExPlayer_Start 関数実行時）には、本関数で設定された 時間で新規に音声がフェードイン再生されます。

フェードイン時間のデフォルト値は 0 秒です。
そのため、本関数を使用しない場合フェードインは行われず、即座にフルボリューム で音声の再生が開始されます。

注意

本関数を実行する前に、 criAtomExPlayer_AttachFader 関数を使用して あらかじめプレーヤーにフェーダーをアタッチしておく必要があります。

本関数で設定した値は、既に再生中の音声には一切影響しません。
本関数で設定したフェード時間は、本関数実行後に criAtomExPlayer_Start 関数を 実行するタイミングで適用されます。
（既にフェードインを開始している音声に対しては、 本関数で後からフェードイン時間を変更することはできません。）

参照

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeInTime()

CriSint32 CRIAPI criAtomExPlayer_GetFadeInTime

(

CriAtomExPlayerHn

player

)

フェードイン時間の取得

引数

[in]

player

AtomExプレーヤーハンドル

戻り値

CriSint32 フェードイン時間（ミリ秒単位）

説明:

フェードイン時間を取得します。

備考:

本関数は criAtomExPlayer_SetFadeInTime 関数でセットした値を返します。

参照

criAtomExPlayer_SetFadeInTime

criAtomExPlayer_SetFadeInStartOffset()

void CRIAPI criAtomExPlayer_SetFadeInStartOffset	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

フェードイン開始オフセットの設定

引数

[in]	player	AtomExプレーヤーハンドル
[in]	ms	フェードイン開始オフセット（ミリ秒指定）

説明:

フェーダーをアタッチ済みのプレーヤーに対し、フェードイン開始オフセットを指定します。
本関数を使用することで、フェードインを開始するタイミングをフェードアウトに対して 任意の時間早めたり、遅らせることが可能です。
例えば、フェードアウト時間を5秒、フェードイン開始オフセットを5秒に設定した場合、 フェードアウトが5秒で完了した直後に次の音声をフェードインさせることが可能です。
逆に、フェードイン時間を5秒、フェードイン開始オフセットを-5秒に設定した場合、 フェードインが5秒で完了した直後に再生中の音のフェードアウトを開始させることが可能です。

フェードイン開始オフセットのデフォルト値は 0 秒です。
（フェードインとフェードアウトが同時に開始されます。）

備考:

フェードイン開始のタイミングは、フェードインする音声の再生準備が整ったタイミングです。
そのため、フェードイン開始オフセットが 0 秒に設定されている場合でも、フェードイン音声 のバッファリングに時間がかかる場合（ストリーム再生時等）には、フェードアウトの開始までに しばらく時間がかかります。
（本パラメーターは、フェードインとフェードアウトのタイミングを調整するための相対値です。）

注意

本関数を実行する前に、 criAtomExPlayer_AttachFader 関数を使用して あらかじめプレーヤーにフェーダーをアタッチしておく必要があります。

本関数で設定した値は、既に再生中の音声には一切影響しません。
本関数で設定したフェード時間は、本関数実行後に criAtomExPlayer_Start 関数や criAtomExPlayer_Stop 関数を実行するタイミングで適用されます。
（既にフェード処理を開始している音声に対しては、 本関数で後からフェード処理のタイミングを変更することはできません。）

参照

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeInStartOffset()

CriSint32 CRIAPI criAtomExPlayer_GetFadeInStartOffset

(

CriAtomExPlayerHn

player

)

フェードイン開始オフセットの取得

引数

[in]

player

AtomExプレーヤーハンドル

戻り値

CriSint32 フェードイン開始オフセット（ミリ秒単位）

説明:

フェードイン開始オフセットを取得します。

備考:

本関数は criAtomExPlayer_SetFadeInStartOffset 関数でセットした値を返します。

参照

criAtomExPlayer_SetFadeInStartOffset

criAtomExPlayer_SetFadeOutEndDelay()

void CRIAPI criAtomExPlayer_SetFadeOutEndDelay	(	CriAtomExPlayerHn	player,
		CriSint32	ms
	)

フェードアウト後のディレイ時間の設定

引数

[in]	player	AtomExプレーヤーハンドル
[in]	ms	フェードイン開始オフセット（ミリ秒指定）

説明:

フェードアウト完了後、ボイスを破棄するまでのディレイ時間を設定します。
本関数を使用することで、フェードアウトを終えたボイスが破棄されるまでのタイミングを任意に設定可能です。

ディレイ時間のデフォルト値は 500 ミリ秒です。
（フェードアウト音を再生するボイスは、ボリュームが 0 に設定された後、 500 ミリ秒後に破棄されます。）

備考:

音声のフェードアウトが完了する前にボイスが停止されるプラットフォーム以外は、 本関数を使用する必要はありません。

注意

本関数を実行する前に、 criAtomExPlayer_AttachFader 関数を使用して あらかじめプレーヤーにフェーダーをアタッチしておく必要があります。

本関数で設定した値は、既に再生中の音声には一切影響しません。
本関数で設定したフェード時間は、本関数実行後に criAtomExPlayer_Start 関数や criAtomExPlayer_Stop 関数を実行するタイミングで適用されます。
（既にフェードアウトを開始している音声に対しては、 本関数で後からフェードアウト後のディレイ時間を変更することはできません。）

ボリュームの制御とボイスの停止が反映されるタイミングは、プラットフォームによって異なります。
そのため、本関数に 0 を指定した場合、プラットフォームによってはボリュームの変更が反映される 前にボイスが停止される恐れがあります。

参照

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

criAtomExPlayer_GetFadeOutEndDelay()

CriSint32 CRIAPI criAtomExPlayer_GetFadeOutEndDelay

(

CriAtomExPlayerHn

player

)

フェードアウト後のディレイ時間の取得

引数

[in]

player

AtomExプレーヤーハンドル

戻り値

CriSint32 フェードアウト後のディレイ時間（ミリ秒単位）

説明:

フェードアウト後のディレイ時間を取得します。

備考:

本関数は criAtomExPlayer_SetFadeOutEndDelay 関数でセットした値を返します。

参照

criAtomExPlayer_SetFadeOutEndDelay

criAtomExPlayer_IsFading()

CriBool CRIAPI criAtomExPlayer_IsFading

(

CriAtomExPlayerHn

player

)

フェード処理中かどうかのチェック

引数

[in]

player

AtomExプレーヤーハンドル

戻り値

CriBool フェード処理中かどうか（CRI_TRUE = フェード処理中、CRI_FALSE = フェード処理中ではない）

説明:

フェード処理が行われている最中かどうかをチェックします。

備考:

本関数は、以下の処理期間中 CRI_TRUE を返します。

• クロスフェード開始のための同期待ち中。
• フェードイン／フェードアウト処理中（ボリューム変更中）。
• フェードアウト完了後のディレイ期間中。

criAtomExPlayer_ResetFaderParameters()

void CRIAPI criAtomExPlayer_ResetFaderParameters

(

CriAtomExPlayerHn

player

)

フェーダーパラメーターの初期化

引数

[in]

player

AtomExプレーヤーハンドル

説明:

フェーダーに設定されている各種パラメーターをクリアし、初期値に戻します。

注意

本関数を実行する前に、 criAtomExPlayer_AttachFader 関数を使用して あらかじめプレーヤーにフェーダーをアタッチしておく必要があります。

本関数でフェーダーパラメーターをクリアしても、既に再生中の音声には一切影響しません。
本関数でクリアしたフェーダーパラメーターは、本関数実行後に criAtomExPlayer_Start 関数や criAtomExPlayer_Stop 関数を実行するタイミングで適用されます。
（既にフェード処理を開始している音声に対しては、 本関数でクリアしたフェーダーパラメーターを適用することはできません。）

参照

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime