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.

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.