# 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.

CONFIDENTIAL