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.


CONFIDENTIAL