# NNS_SndCaptureStartEffect

## Syntax

      #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` | Format of the sample data.
`sampleRate` | Sampling rate.
`interval` | Callback interval. Specify 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 whether the effect has started properly.

## Description

Starts an effect.

This function captures the mixer output using the capture feature and applys effect processing using a callback function, then outputs the final audio. While the effects are being used, they consume 2 of 16 channels (channels 1 and 3). If channel 1 or 3 is being used by a sequence, the audio being produced by that channel is forcibly stopped.

To use effects, an effect buffer is required. The smaller the effect buffer, the more frequently the callback function is called. The starting address `buffer_p` must have 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: NNSSndCaptureFormat

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 audio quality of the captured data, but the more frequently the callback function is called.

The value set for the callback interval `interval` specifies how many times to call the callback function while the entire effect buffer is captured. This callback interval is normally set to 2, so the second half of the data can be overwritten while the first half is playing.

The callback function `callback` is called when data is captured to the effect buffer, at intervals specified by `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`. The values passed to `format` and the user argument `arg` are the same as those entered as the arguments for the ``NNS_SndCaptureStartEffect`` function. The buffer passed to the argument indicates the region where the capture ended. By adjusting this region, it is possible to change the actual output audio.

When a capture thread has been started by the ``NNS_SndCaptureCreateThread`` function, the callback function is called from the capture thread. If a 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 always necessary to finish adjusting the capture region within the callback functions. However, the processing must be complete before the region is next used for playback. Otherwise the proper audio will not be output.

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

## See Also

NNS_SndCaptureCreateThread

## Revision History

2005/06/27 Added reasons for function failure.
2005/01/06 Deleted the description regarding TEG.
2004/09/14 Added a note about cutting off the audio.
2004/09/13 Added explanation of operations for creating a capture thread.
2004/08/10 Added a note concerning calling of the callback function in interrupt prohibited mode.
2004/07/01 Initial version.

CONFIDENTIAL