int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg)
| chan | エフェクトを登録するチャネル, またはMIX_CHANNEL_POST |
| f | チャネルがミックスされるとき実行されるコールバック |
| d | エフェクトが終了したとき呼ばれるコールバック |
| arg | 引数 |
ミックス時にチャネルデータはバッファにコピーされ, 登録されたエフェクト関数に渡される. 全ての関数を通った後に最終的な出力ストリームにミックスされる. バッファへのコピーは1回しか行われない. そのため, 各エフェクト関数は前のエフェクトの出力に対して作用する. チャンクのバッファへのコピーは, エフェクトが登録されていない場合はCPU負荷を下げるため行われないので注意すること. また, エフェクトには常にCPUへの負荷がかかるため, コードは高速でなければならない. さらに, 関数に渡されるデータはサウンドデバイスの形式であり, (多くの場合は同一だが)Mix_OpenAudio()に渡した形式ではないので注意すること. 残念ながら速度の問題でこのようになっている. Mix_QuerySpec()を使用するとエフェクトを登録する前にデータを扱えるか判断でき, 適切な対策を取ることができる.
チャネルの再生が完了したとき呼ばれるMix_EffectDone_tコールバックも登録できる. これはエフェクトの資源の解放などが必要な場合, Mix_ChannelFinished()よりも細かい制御ができる. 必要ない場合はNULLを指定できる.
コールバックはMix_PlayChannel()を呼ぶ前でも後でも設定できる.
Mix_SetPanning()などは組み込まれたエフェクト関数で, これらを使う場合はバッファにコピーするオーバーヘッドが発生しており, エフェクトはあなたが登録したエフェクト関数と共にキューに入れられる. チャネルに登録されたエフェクトはチャンクの再生が完了したとき解除される. 必要ならばMix_PlayChannel()を呼ぶたびにエフェクトを登録する必要がある.
最後のミキシングが発生した後に実行されるエフェクト関数も登録できる. この場合も規約は他のコールバックと同じだが, チャネルを指定したエフェクトはチャネルの他のミキシングが始まる前に呼ばれるのに対して, このコールバックはストリームの全てのチャネルと音楽がミックスされた後に実行される. このグローバルなエフェクトコールバックは「ポストエフェクト」と呼ばれる. ポストエフェクトが呼ばれるのはMix_EffectDone_tコールバックが解除されるときのみである. (メイン出力ストリームはチャネルと同じ意味で「完了」することはない.) 不要になった場合は自分で登録を解除する必要がある. ポストエフェクト処理の場合, チャネルはMIX_CHANNEL_POSTとなる.
全てのエフェクト処理を行うと, Mix_SetPostMix()で登録したコールバックが呼ばれ, ストリームはオーディオデバイスへと渡される.
コールバック関数内でSDL_LockAudio()を呼んではならない. 既にオーディオスレッド内で実行され, 既にロックされている.
他のSDL_mixerとは異なり, この関数は成功ではなくエラーのとき0を戻す.