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.

Revision History