# NNS_SndCaptureStartEffect

## 構文

      #include <nnsys/snd.h>

      typedef void (*NNSSndCaptureEffectCallback)(
          void* bufferL,
          void* bufferR,
          u32 len,
          NNSSndCaptureFormat format,
          void* arg
      );

      BOOL NNS_SndCaptureStartEffect(
              void* buffer_p,
              u32 bufSize,
              NNSSndCaptureFormat format,
              int sampleRate,
              int interval,
              NNSSndCaptureEffectCallback callback,
              void* arg );

## 引数

`buffer_p` | エフェクトバッファのポインタです。32バイトアライメントされている必要があります。
`bufSize` | エフェクトバッファのサイズです。interval * 64の倍数で無ければなりません。 最大値は0x7fff8です。
`format` | サンプルデータのフォーマットです。
`sampleRate` | サンプリングレートです。
`interval` | コールバックインターバルです。2以上の値を指定します。
`callback` | エフェクトコールバック関数のポインタです。
`arg` | エフェクトコールバック関数の引数となるパラメータです。

## 返り値

エフェクトの開始に成功したかどうかを返します。

## 説明

エフェクトを開始します。

キャプチャー機能を使ってミキサー出力をキャプチャし、コールバック関数でエフェクト処理を行った後、 最終音声として出力します。 エフェクト動作中は、16チャンネル中の2チャンネル（チャンネル1及びチャンネル3）を消費します。 チャンネル1またはチャンネル3が、シーケンスによって使用中の場合、発音中の音は強制的に停止させられます。

エフェクトを使うためには、エフェクトバッファが必要になります。 エフェクトバッファが小さいほど頻繁にコールバック関数が呼びだされます。 先頭アドレス`buffer_p`は、32バイトアライメントされている必要があります。 また、バッファサイズ`bufSize`は、`interval` * 64の倍数で無ければなりません。

サンプルデータのフォーマット`format`は、下記の値から選択します。 16ビットの方が、音質は良くなりますが、8ビットの時に比べて２倍の頻度で コールバック関数が呼びだされるようになります。

表 . NNSSndCaptureFormat

ラベル | 説明
--- | ---
NNS_SND_CAPTURE_FORMAT_PCM8 | 8ビットPCM
NNS_SND_CAPTURE_FORMAT_PCM16 | 16ビットPCM

サンプリングレート`sampleRate`は、 値が大きいほどキャプチャしたデータの音質は良くなりますが、その分頻繁にコールバック関数が 呼びだされます。

コールバックインターバル`interval`は、エフェクトバッファが全体にキャプチャする間に、 何回コールバック関数が呼びだされるのかを指定します。 通常は２を指定し、半分を再生中に残り半分を書き換えるようにします。

コールバック関数`callback`は、 コールバックインターバル`interval`で指定した間隔で、エフェクトバッファにキャプチャされる毎に呼びだされます。 引数には、Ｌミキサー成分`bufferL`およびＲミキサー成分`bufferR`の 先頭アドレスのポインタと、バッファのサイズ`len`が入れられます。 フォーマット`format`とユーザー引数`arg`は、 `NNS_SndCaptureStartEffect`関数の引数に入れたものと同じものが渡されます。 引数に渡されるバッファは、キャプチャが完了した領域を指しています。 この領域を修正することで、実際に出力される音を変更することができます。

`NNS_SndCaptureCreateThread`関数で キャプチャースレッドを起動しているときは、コールバック関数はキャプチャースレッドから呼びだされます。 キャプチャースレッドを起動していない場合は、コールバック関数はIRQハンドラから呼びだされます。

エフェクト開始の失敗には、以下の原因が考えられます。

- キャプチャがエフェクト以外の用途で使用中
- チャンネル１またはチャンネル３が、エフェクトやシーケンスによる発音以外の用途で使用中

### 注意

キャプチャバッファを処理した後は、メインメモリに確実に書き込まれるように、 `DC_FlushRange`関数などを呼びだすようにしてください。

必ずしも、コールバック関数内で、キャプチャ領域の修正を完了させる必要はありませんが、 次にその領域が再生されるまでに処理を完了しないと、正常な音声が出力されなくなります。

音声を再生しながらこの関数を呼びだすと、再生される音が途切れます。

## 参照

NNS_SndCaptureCreateThread

## 履歴

2005/06/27 関数失敗の原因を追加
2005/01/06 TEGに関する記述削除
2004/09/14 音途切れの注意追加
2004/09/13 キャプチャースレッド作成時の動作説明追加
2004/08/10 コールバック関数が割り込み禁止で呼びだされる注意書き追加
2004/07/01 初版