# NNS_SndCaptureStartSampling

## Syntax

      #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` | Format of the sample data.
`sampleRate` | Sampling rate.
`interval` | Callback interval. Specify a value of 2 or more.
`callback` | The pointer to the sampling callback function.
`arg` | Parameter that serves as the argument to the sampling callback function.

## Return Values

Whether sampling was successfully started.

## Description

Starts sampling.

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 3 is being used by a sequence, the audio being produced by that channel is 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 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 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, 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_SndCaptureStartSampling` function. The buffer passed to the argument indicates the region where the capture ended.

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.

Sampling may fail to start for the following reasons.

- Capture is currently being used for something other than sampling.
- Channel 1 or Channel 3 is being used for something other than sampling or generating audio with a sequence.

## See Also

NNS_SndCaptureCreateThread

## Revision History

2005/06/27 Added reasons for function failure.
2005/01/06 Deleted the description regarding TEG.
2004/09/13 Initial version.

CONFIDENTIAL