SND_SetupChannelPcm

C Specification

#include <nitro/snd.h>
void SND_SetupChannelPcm(
int chNo,
SNDWaveFormat format,
const void* dataAddr,
SNDChannelLoop loop,
int loopStart,
int dataLen,
int volume,
SNDChannelDataShift shift,
int timer,
int pan );

Arguments

chNo The channel number. Takes a value between 0 and 15.
format The format of the waveform data.
dataAddr The starting address of the waveform data. Must have 4-byte alignment.
loop The loop playback setting.
loopStart The loop-start position. Expressed in units of words. Takes a value of 0 to 0xffff.
dataLen The data length. Expressed in units of words. Takes a value of 0 to 0x3fffff.
volume The volume. Takes a value between 0 and 127.
shift The data shift setting.
timer The timer. Takes a value between 0x10 and 0xffff.
pan The pan. Takes values in the range of 0 (left) to 64 (center) to 127 (right).

Return Values

None.

Description

This function sets up channels for PCM playback.

The function sets the parameters for the channel specified by chNo. The channel must be locked by the SND_LockChannel function before the parameters can be set. Once the parameters have been set, call the SND_StartTimer function to begin actual playback.

Choose from among these values for the waveform data format format:

Table. SNDWaveFormat

Label Description
SND_WAVE_FORMAT_PCM8 8-bit PCM
SND_WAVE_FORMAT_PCM16 16-bit PCM
SND_WAVE_FORMAT_ADPCM IMA-ADPCM

The waveform data's starting address dataAddr must have 4-byte alignment.

Choose from among these values for the loop playback setting loop:

Table. SNDChannelLoop

Label Description
SND_CHANNEL_LOOP_MANUAL Continue to play tone, regardless of the setting for data length dataLen.
SND_CHANNEL_LOOP_REPEAT Play to end of data length dataLen and then return to loop-start position loopStart and continue to play.
SND_CHANNEL_LOOP_1SHOT Play to end of data length dataLen and then stop playback automatically.

The loop-start position loopStart is specified in units of words. It is only meaningful when the loop playback setting loop is set to SND_CHANNEL_LOOP_REPEAT.

The data length dataLen specifies the size of the waveform data in units of words. The value is ignored when the loop playback setting loop is set to SND_CHANNEL_LOOP_MANUAL.

Choose from among these values for the data shift setting shift:

Table. SNDChannelDataShift

Label Description
SND_CHANNEL_DATASHIFT_NONE Do not perform a data shift.
SND_CHANNEL_DATASHIFT_1BIT Shift data 1 bit right.
SND_CHANNEL_DATASHIFT_2BIT Shift data 2 bit right.
SND_CHANNEL_DATASHIFT_4BIT Shift data 4 bit right.

timer specifies the number of clock ticks for outputting one sample. The number of ticks per second is approximately 16.757 MHz with SND_TIMER_CLOCK. Thus, if you want to play the waveform data without changing the pitch and the sampling rate is rate Hz, then you calculate timer as follows:

timer = SND_TIMER_CLOCK / rate

Caution

This function is an ARM7 reserved function. After this function is called, processing occurs only after the command is issued with the SND_FlushCommand function.

When it is necessary to synchronize something with the completion of the process, first use SND_GetCurrentCommandTag to obtain the command tag immediately after calling this function. After the command is issued, use the command tag and call either the SND_IsFinishedCommandTag or SND_WaitForCommandProc function to confirm that the process has finished or to wait for it to complete.

See Also

SND_LockChannel, SND_StartTimer, SND_FlushCommand, SND_GetCurrentCommandTag, SND_IsFinishedCommandTag, SND_WaitForCommandProc

Revision History

02/17/2005 Added a note about ARM7 command processing
10/07/2004 Corrected spelling: REPAET to REPEAT.
07/20/2004 Initial version.