# NNS_SndCaptureStartSampling

## C Specification

      #include <nnsys/snd.h>

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

      BOOL NNS_SndCaptureStartSampling(
      void* buffer_p,
      u32 bufSize,
      NNSSndCaptureFormat format,
      +int sampleRate,
      int interval,
      NNSSndCaptureCallback callback,
      void* arg );

## Arguments

`buffer_p` | The pointer to the sampling buffer. Must have 32-byte alignment.
`bufSize` | The size of the sampling 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` | The pointer to the sampling callback function.
``arg`` | The parameters that serve as the arguments of the sampling callback function.

## Return Values

The success or failure of the start of sampling.

## Description

This function begins the sampling process.

Output from the mixer is captured using the capture feature and the sampled data is retrieved using the callback function. The sampling operation consumes two of the 16 channels (channel 1 and channel 3). If channel 1 or channel 3 is being used by a sequence, the sounds from that channel are forcibly stopped.

Using the sampling process requires a sampling buffer. The smaller the sampling buffer, the more often the callback function is called. 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 value set for `interval` specifies how many times to call the callback function while the entire sampling buffer is captured. This callback interval is normally set to 2, so the second half of the data is sampled while the first half is loaded.

The callback function `callback` is called when data is captured to the sampling buffer, with a recurrence rate specified by the `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 the `format` and the user argument `arg` are the same as those entered as the arguments for the `NNS_SndCaptureStartSampling` function. The buffer passed to the argument indicates the region where the capture ended.

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.

Sampling may fail to start for one of the following reasons.

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

## See Also

NNS_SndCaptureCreateThread

## Revision History

06/27/2005 Added reasons for function failure.

01/06/2005 Deleted the description regarding TEG.

09/13/2004 Initial version.