# SNDEX_SetIirFilterAsync

## 定義

  `#include <twl/snd.h>`

      SNDEXResult
      SNDEX_SetIirFilterAsync(SNDEXIirFilterTarget target,
                              const SNDEXIirFilterParam* pParam,
                              SNDEXCallback callback,
                              void* arg)

## 引数

target | IIRフィルタをかける対象 SNDEXIirFilterTarget列挙型。
pParam | IIRフィルタの性能を決定する SNDEXIirFilterParam構造体。
callback | IIRフィルタ設定後に呼ばれるコールバック関数。
arg | コールバック関数に渡す引数。

## 返り値

### 関数への返り値

SNDEX_RESULT_SUCCESS | 非同期処理が正常に開始された場合に返ります。非同期処理の結果はcallbackに登録した関数の引数として通知されます。
SNDEX_RESULT_ILLEGAL_STATE | NITROプラットフォーム上で当関数を呼び出した場合、CODECをCODEC-DSモードで動作させている場合に返ります。
SNDEX_RESULT_BEFORE_INIT | サウンド拡張機能を`SNDEX_Init()`により初期化していない場合に返ります。
SNDEX_RESULT_EXCLUSIVE | 他のサウンド拡張機能に関する処理を実行中の場合に返ります。 p サウンド拡張機能に関する各処理は排他制御により同時には行えませんのでご注意下さい。 SNDEX ライブラリの概要にある通り、シャッター音再生処理中もこのエラーを返します。
SNDEX_RESULT_PXI_SEND_ERROR | ARM7へのPXIコマンド発行に失敗した場合に返ります。 ARM7へのPXI送信キューが飽和した場合や、ハードウェアがエラーを検知した場合に発生するエラーですので、リトライすると状況が改善する可能性があります。
SNDEX_RESULT_ILLEGAL_TARGET | 引数 `target` の値が有効範囲外だった場合に返ります。

### 非同期処理の結果

SNDEX_RESULT_SUCCESS | 一連の処理が正常に完了した場合に通知されます。
SNDEX_RESULT_ILLEGAL_STATE | NITROプラットフォーム上で当関数を呼び出した場合、CODECをCODEC-DSモードで動作させている場合、 および `DSP_PlayShutterSound` によるシャッター音再生中の場合に返ります。
SNDEX_RESULT_EXCLUSIVE | ARM7内での排他制御エラーが発生した場合に通知されます。 ARM7内での処理進捗状況に依存したエラーですので、リトライすると状況が改善する可能性があります。
SNDEX_RESULT_DEVICE_ERROR | ARM7内で外部デバイスに対するスピーカー音量変更操作に失敗した場合に通知されます。 リトライすると状況が改善する可能性がありますが、数回リトライして失敗が続く場合には外部デバイスの暴走等の原因が考えられますので、 成功が通知された場合と同様に扱って構いません。
SNDEX_RESULT_FATAL_ERROR | 通常起こり得ないエラーです。 ライブラリの状態管理を無視して直接不正なPXIコマンドを発行した場合、 ARM7コンポーネントとサウンド拡張機能ライブラリのバージョンが異なる場合、 メモリ破壊等によりライブラリの状態管理が異常な状態に陥った場合等に発生する可能性があります。 ランタイムに復旧する手段はありません。

## 説明

マイク入力される音声データにかけるIIRフィルタ（1〜5段）を設定します。
ただし、多段のフィルタを設定するには、本関数を段数分呼ぶ必要があります。
設定完了後、ユーザが指定したコールバック関数が呼ばれます。

$TwlSDK/docs/TechnicalNotes/IIR_FilterBuilder.xls を使うことで、ローパスフィルタ、ハイパスフィルタ、バンドパスフィルタ、
バンドエリミネーションフィルタのパラメータを作成することができます。ただし、特性を指定してパラメータを算出するといったことはできません。
詳しくは、IIR_FilterBuilder の使い方をご覧下さい。

関数への返り値がSNDEX_RESULT_SUCCESSでない場合には、非同期処理は行われず、コールバックも発生しません。
また、非同期処理の完了はPXI受信割込みによって通知されるため、PXI受信割込みを禁止しているとコールバックが発生しないことに注意して下さい。

また、シャッター音の再生音量を維持するために、`DSP_PlayShutterSound()` 実行中は
SNDEX_RESULT_EXCLUSIVE を返して何もせずに終了します。
さらに、シャッター音再生中はライブラリ側で IIR フィルタの設定を一時的に初期化し、再生後に再設定するようになっています。

IIR フィルタの設定が終了するまでスリープやハードウェアリセットの実行を待つようになっています。
詳しくは、スリープやハードウェアリセット・シャットダウンの概要をご覧下さい。

## 注意

IIR フィルタは一度に1段ずつしか設定できません。IIR フィルタ設定中に本関数を再度呼んでもエラー `SNDEX_RESULT_EXCLUSIVE` が返ります。

IIR フィルタ1段の設定には 数10msec〜100msec の時間がかかります。設定時に ARM7側で SPI の排他制御を行うため、この間は MIC のサンプリングや
TP のサンプリング、PM、NVRAM が待たされてしまい、遅延が発生します。
従って本関数と並行して、以上のデバイスを用いた処理を行う場合は注意する必要があります。

IIR フィルタのパラメータ設定には十分に注意する必要があります。
IIRフィルタを、入力音声データのゲインを大きくするように設定した場合、
入力ソースによっては計算結果が飽和してしまい音が割れたりすることがあります。入力ソースが不定な場合は、基本的にゲインを小さくする方向で IIRフィルタを使用して下さい。
また、IIR フィルタを複数段設定した場合は、各段ごとに飽和しないように注意する必要があります。
入力波形に対して、1段ずつ順番にフィルタがかかるためです（フィルタの適用順については `SNDEXIirFilterTarget` をご覧ください）。
特に、IIRフィルタは過去の出力データを利用するため、それらを増幅するようなパラメータを設定すると本体音量の値や `SNDEX_SetMute()` による消音状態にかかわらず、スピーカーから音が鳴ることがあります。

本関数の使用時には、フィルタを設定する対象`target` によって制限があります。

`target` がマイク入力データの場合（SNDEX_IIR_FILTER_ADC_*）、設定時に A/D コンバータを停止させているため、正しいサンプリングデータを得ることができません。
その間のサンプリングデータを使用しないように気をつけていればよいため、マイクサンプリングそのものを停止させる必要はありません。

## 参照

`SNDEX_SetIirFilter, SNDEXIirFilterTarget, SNDEXIirFilterParam, IIR_FilterBuilder の使い方`

## 履歴

2011/11/01 target の値の調整
2009/05/27 IIR フィルタのパラメータ設定に関しての注意を追記
2008/11/07 シャッター音再生処理時に SNDEX_RESULT_EXCLUSIVE が返ることを追記（2008/09/26 の記述を削除）
2008/11/06 「返り値」非同期処理の結果の誤記修正(SNDEX_RESULT_EXCLUSIVE)
2008/09/26 シャッター音再生時の挙動について追記
2008/09/16 スリープ、ハードウェアリセット・シャットダウンの概要ページへのリンク追加
2008/09/11 返り値の記述を修正。「注意」に処理時間や他のデバイスへの影響について追記
2008/09/06 IIR_FilterBuilder の使い方へのリンク追加
2008/08/26 関数実行時の制限事項について「注意」へ追記
2008/07/08 初版