# SND_SetupChannelPcm

## Syntax

      #include <nitro/snd.h>

      void SND_SetupChannelPcm(
      int chNo,
      SNDWaveFormat format,
      const void* dataAddr,
      SNDChannelLoop loop,
      int loopStart,
      int loopLen,
      int volume,
      SNDChannelDataShift shift,
      int timer,
      int pan );

## Arguments

chNo | Channel number. Takes a value between 0 and 15.
format | Format of the waveform data.
dataAddr | Starting address of the waveform data. Must have 4-byte alignment.
loop | Loop playback setting.
loopStart | Loop-start position. Expressed in units of words. Takes a value of 0 to `0xffff`.
loopLen | Length of the loop. Expressed in units of words. Takes a value of 0 to `0x3fffff`.
volume | Volume. Takes a value between 0 and 127.
shift | Data shift setting.
timer | Timer. Takes a value between 0x10 and 0xffff.
pan | Pan. Takes values in the range of 0 (left) to 64 (center) to 127 (right).

## Return Values

None.

## Description

Sets up channels for PCM playback.

The function sets the parameters for the channel specified by chNo. The channel must first be locked by the `SND_LockChannel` function. 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` | Continues playing, regardless of the loop setting.
`SND_CHANNEL_LOOP_REPEAT` | When playback has reached the end of the loop (loopStart + loopLen), continues playing from the start of the loop at loopStart.
`SND_CHANNEL_LOOP_1SHOT` | When playback has reached the end of the loop (loopStart + loopLen), playback stops automatically.

The loop starting position loopStart and the loop length loopLen are specified in word units. 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 bits right.
`SND_CHANNEL_DATASHIFT_4BIT` | Shift data 4 bits right.

The timer argument 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

### Note

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

If program execution must be synchronized with process completion, first use the `SND_GetCurrentCommandTag` function to get the command tag immediately after calling this function. Then, after the command is issued, use the command tag and call the `SND_IsFinishedCommandTag` or `SND_WaitForCommandProc` function to confirm that processing 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

2008/11/19 Corrected mistaken explanation of loop length as data length.
2005/02/17 Added precaution about ARM7 command processing.
2004/10/07 Corrected `SND_CHANNEL_LOOP_REPAET` to read `SND_CHANNEL_LOOP_REPEAT`.
2004/07/20 Initial version.

CONFIDENTIAL