Next: 6 Stream playback Up: 5 Sample playback Previous: Data types

# Functions

This section describes all functions available for MIDAS sample playback.

## 5.3.1 MIDASallocAutoEffectChannels

    BOOL MIDASallocAutoEffectChannels(unsigned numChannels)

Allocates a number of channels for use as automatic effect channels.

### Input

numChannels
  Number of channels to use

### Description

This function allocates a number of channels that can be used as automatic effect channels by MIDASplaySample. When MIDASplaySample is passed MIDAS_CHANNEL_AUTO as the channel number, it will use one of these automatic channels to play the sound. The channels allocated can be deallocated with MIDASfreeAutoEffectChannels.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASfreeAutoEffectChannels, MIDASplaySample

## 5.3.2 MIDASfreeAutoEffectChannels

    BOOL MIDASfreeAutoEffectChannels(void)

Deallocates the channels allocated for automatic effect channels.

### Input

None.

### Description

This function deallocates the channels allocated by MIDASallocAutoEffectChannels for use as automatic sound effect channels.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASallocAutoEffectChannels

## 5.3.3 MIDASfreeSample

    BOOL MIDASfreeSample(MIDASsample sample)

Deallocates a sound effect sample.

### Input

sample
  Sample to be deallocated

### Description

This function deallocates a sound effect sample that has been previously loaded with MIDASloadRawSample or MIDASloadWaveSample. It removes the sample from the Sound Device and deallocates the memory used. This function may not be called if the sample is still being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASloadRawSample, MIDASloadWaveSample

## 5.3.4 MIDASgetSamplePlayStatus

    DWORD MIDASgetSamplePlayStatus(MIDASsamplePlayHandle sample);

Gets the sample playing status.

### Input

sample
  The sample playing handle

### Description

This function returns the playing handle for the sample with playing handle sample. The playing status can be used to determine if the sample has stopped, and if another sample should be played in its place. Normally manually checking for the sample playing status is unnecessary, however, as new samples can simply be played on top of the old ones.

### Return value

Playing status for the sample, see `enum` MIDASsamplePlayStatus.

### Operating systems

All

### See also

MIDASplaySample, MIDASstopSample

## 5.3.5 MIDASloadRawSample

    MIDASsample MIDASloadRawSample(char *filename, int sampleType,
        int loopSample)

Loads a raw sound effect sample.

### Input

filename
  Sample file name
sampleType
  Sample type, see `enum` MIDASsampleTypes
loopSample
  Sample loop type, see `enum` MIDASloop

### Description

This function loads a sound effect sample into memory and adds it to the Sound Device. The sample file must contain just the raw sample data, and all of it will be loaded into memory. If loopSample is MIDAS_LOOP_YES, the whole sample will be looped. After the sample has been loaded, it can be played using MIDASplaySample, and it should be deallocated with MIDASfreeSample after it is no longer used.

### Return value

Sample handle if successful, NULL if failed.

### Operating systems

All

### See also

MIDASplaySample, MIDASfreeSample

## 5.3.6 MIDASloadWaveSample

    MIDASsample MIDASloadWaveSample(char *filename, int loopSample)

Loads a RIFF WAVE sound effect sample.

### Input

filename
  Sample file name
loopSample
  Sample loop type, see `enum` MIDASloop

### Description

This function loads a sound effect sample into memory and adds it to the Sound Device. The sample file must be a standard RIFF WAVE (`.wav`) sound file, containing raw PCM sound data -- compressed WAVE files are not supported. If loopSample is MIDAS_LOOP_YES, the whole sample will be looped. After the sample has been loaded, it can be played using MIDASplaySample, and it should be deallocated with MIDASfreeSample after it is no longer used.

### Return value

Sample handle if successful, NULL if failed.

### Operating systems

All

### See also

MIDASplaySample, MIDASfreeSample

## 5.3.7 MIDASplaySample

    MIDASsamplePlayHandle MIDASplaySample(MIDASsample sample,
        unsigned channel, int priority, unsigned rate,
        unsigned volume, int panning)

Plays a sound effect sample.

### Input

sample
  The sample that will be played
channel
  The channel number that is used to play the sample. Use MIDAS_CHANNEL_AUTO to let MIDASplaySample select the channel automatically. See `enum` MIDASchannels.
priority
  Sample playing priority. The higher the value the more important the sample is considered.
rate
  Initial sample rate for the sample
volume
  Initial volume for the sample
panning
  Initial panning position for the sample. See `enum` MIDASpanning.

### Description

This function is used to play a sound effect sample on a given channel. The sample will receive as initial parameters the values passed as arguments, and playing the sample will be started. If channel is MIDAS_CHANNEL_AUTO, the channel will be selected automatically. The sample playing priority is used to choose the channel the sample will be played on in this case. Otherwise a channel needs to be allocated with MIDASallocateChannel before the sample can be played.

This function returns a sample playing handle, that can later be used to stop the sample or change its parameters. This makes it possible to refer to samples without knowing the exact channel they are played on.

### Return value

Sample playing handle if successful, NULL if failed.

### Operating systems

All

### See also

MIDASstopSample, MIDASallocAutoEffectChannels

## 5.3.8 MIDASsetSamplePanning

    BOOL MIDASsetSamplePanning(MIDASsamplePlayHandle sample,
        int panning)

Changes the panning position of a sound effect sample.

### Input

sample
  Sample to be changed
panning
  New panning position for the sample (see `enum` MIDASpanning)

### Description

This function changes the panning position of a sound effect sample that is being played. See description of `enum` MIDASpanning for information about the panning position values.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 5.3.9 MIDASsetSamplePriority

    BOOL MIDASsetSamplePriority(MIDASsamplePlayHandle sample,
        int priority)

Changes the playing priority of a sound effect sample.

### Input

sample
  Sample to be changed
priority
  New playing priority for the sample

### Description

This function changes the playing priority a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 5.3.10 MIDASsetSampleRate

    BOOL MIDASsetSampleRate(MIDASsamplePlayHandle sample,
        unsigned rate)

Changes the sample rate for a sound effect sample.

### Input

sample
  Sample to be changed
rate
  New sample rate for the sample

### Description

This function changes the sample rate for a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 5.3.11 MIDASsetSampleVolume

    BOOL MIDASsetSampleVolume(MIDASsamplePlayHandle sample,
        unsigned volume)

Changes the volume for a sound effect sample.

### Input

sample
  Sample to be changed
rate
  New volume for the sample (0-64)

### Description

This function changes the volume for a sound effect sample that is being played.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

## 5.3.12 MIDASstopSample

    BOOL MIDASstopSample(MIDASsamplePlayHandle sample)

Stops playing a sample.

### Input

sample
  Sample to be stopped

### Description

This function stops playing a sound effect sample started with MIDASplaySample. Playing the sound will stop, and the channel is freed for other samples to use. Note that sample is the sample playing handle returned by MIDASplaySample.

### Return value

TRUE if successful, FALSE if not.

### Operating systems

All

### See also

MIDASplaySample

Next: 6 Stream playback Up: 5 Sample playback Previous: Data types