# NNS_SndCaptureStartEffect

## C Specification

      #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 );

## Arguments

`buffer_p` | The pointer to the effect buffer. Must have 32-byte alignment.
`bufSize` | Size of the effect buffer. Must be a multiple of `interval * 64`. The maximum value is 0x7fff8.
`format` | The format of the sample data.
`sampleRate` | This is the sampling rate.
`interval` | Callback interval. This specifies a value of 2 or more.
`callback` | Pointer to the effect callback function.
``arg`` | Parameter for the argument of the effect callback function.

## Return Values

Returns if the effect has started properly.

## Description

Starts the sound capture effect.

After capturing the mixer output using the capture feature and applying the effect process with the callback function, this function outputs the final sound. While the effects are being used, they consume 2 of 16 channels (channels 1 and 3). If channel 1 or channel 3 is being used by a sequence, the sounds from that channel are forcibly stopped.

To use effects, an effect buffer is required. With the smaller effect buffer, the callback function is called frequently. The starting address `buffer_p` must have a 32-byte alignment. The buffer size `bufSize` must be a multiple of `interval * 64`.

`format` takes one of the two values shown in the following table for the sample data format. The 16-bit format provides better sound quality, but the callback function is called twice as often as with the 8-bit format.

Table: `SNDCapture` Format

Label | Description
--- | ---
NNS_SND_CAPTURE_FORMAT_PCM8 | 8-bit PCM
NNS_SND_CAPTURE_FORMAT_PCM16 | 16-bit PCM

The higher the sampling rate `sampleRate`, the better the sound quality of the captured data, but the more frequently the callback function is called.

The callback interval `interval` specifies how often the callback function is called while the entire contents of the effect buffer is being captured. Normally, this should be specified as "2" so that half of the buffer can used for rewriting while the other half is used for playback.

The callback function `callback` is called every time the effect buffer is captured, at the interval specified with the callback interval `interval`. The arguments of this callback function are pointers to the starting addresses of the L and R mixer components `bufferL` and `bufferR` and the buffer size `len`. For the format `format` and the user argument `arg`, the same as the ones used with the `NNS_SndCaptureStartEffect` function is passed. The buffer passed to the argument indicates the region where the capture ended. To correct this area, the actual output sound can be changed.

When the capture thread is started by the `NNS_SndCaptureCreateThread` function, the callback function is called from the capture thread. If the capture thread has not been started, the callback function is called from the IRQ handler.

The effect may fail to start for one of the following reasons.

- Capture is being used for something other than an effect
- Channel 1 or Channel 3 is being used for something other than playing an effect or sequence

### Note

After processing the capture buffer, call the `DC_FlushRange` function or a similar function to ensure that the capture buffer is written to the main memory.

It is not necessary to finish processing the captured area within the callback functions. However, the processing must be complete before the area is used for playback. Otherwise the proper sound may not be output.

If this function is called while sound is being played, the sound is interrupted.

## See Also

NNS_SndCaptureCreateThread

## Revision History

06/27/2005 Added reasons for function failure.

01/06/2005 Deleted the description regarding TEG.

09/14/2004 Added a note about interrupting the sound.

09/13/2004 Added explanation of operation for creating a capture thread.

08/10/2004 Added a note that the callback function is called with the interrupt prohibited.

07/01/2004 Initial version.