CriAtomExFader API

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

説明:

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

参照:

criAtomExPlayer_SetFadeOutTime

値:

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

引数:

[out]

p_config

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

説明:

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

参照:

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

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

説明:

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

注意:

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

参照:

criAtomExFader_SetDefaultConfig, criAtomExPlayer_CalculateWorkSizeForFader, criAtomExPlayer_AttachFader

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

引数:

[in]

config

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

戻り値:

CriSint32 ワーク領域サイズ

戻り値:

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

説明:

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

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

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

備考:

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

注意:

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

参照:

CriAtomExFaderConfig, criAtomExPlayer_AttachFader

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

引数:

[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

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

引数:

[in]

player

AtomExプレーヤー

説明:

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

備考:

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

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

参照:

criAtomExPlayer_AttachFader

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

引数:

[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

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

引数:

[in]

player

AtomExプレーヤーハンドル

戻り値:

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

説明:

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

備考:

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

参照:

criAtomExPlayer_SetFadeOutTime

フェードイン時間の設定

引数:

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

説明:

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

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

注意:

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

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

参照:

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

フェードイン時間の取得

引数:

[in]

player

AtomExプレーヤーハンドル

戻り値:

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

説明:

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

備考:

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

参照:

criAtomExPlayer_SetFadeInTime

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

引数:

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

説明:

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

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

備考:

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

注意:

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

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

参照:

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

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

引数:

[in]

player

AtomExプレーヤーハンドル

戻り値:

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

説明:

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

備考:

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

参照:

criAtomExPlayer_SetFadeInStartOffset

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

引数:

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

説明:

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

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

備考:

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

注意:

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

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

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

参照:

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime

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

引数:

[in]

player

AtomExプレーヤーハンドル

戻り値:

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

説明:

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

備考:

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

参照:

criAtomExPlayer_SetFadeOutEndDelay

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

引数:

[in]

player

AtomExプレーヤーハンドル

戻り値:

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

説明:

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

備考:

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

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

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

引数:

[in]

player

AtomExプレーヤーハンドル

説明:

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

注意:

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

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

参照:

criAtomExPlayer_AttachFader, criAtomExPlayer_SetFadeInTime