Using samples is the easiest way to add sound effects and other miscellaneous sounds to a program with MIDAS Digital Audio System. This section describes how samples are used in MIDAS.
Before samples can be used, they naturally need to be loaded into memory. MIDAS Digital Audio System currently supports samples in two formats: raw audio data files and RIFF WAVE files. Raw sample files can be loaded with MIDASloadRawSample, and RIFF WAVE samples with MIDASloadWaveSample. Both functions require as arguments the name of the sample file, and sample looping flag -- 1 if the sample should be looped, 0 if not. MIDASloadRawSample also requires the sample type as an argument, MIDASloadWaveSample determines it from the file header. Both functions return a sample handle of type MIDASsample that can be used to refer to the sample.
After the samples are no longer used, they should be deallocated with MIDASfreeSample. You need to make sure, however, that the sample is no longer being played on any sound channel when it is deallocated.
Samples that have been loaded into memory can be played with the function MIDASplaySample. It takes as arguments the sample handle, playback channel number, and initial values for sample priority, playback rate, volume and panning. The function returns a MIDAS sample playback handle of type MIDASsamplePlayHandle that can be used to refer to the sample as it is being played. A single sample can be played any number of times simultaneously.
Sample playback can be stopped with MIDASstopSample, but this is not necessary before the sample will be deallocated -- a new sample can simply be played on the same channel, and it will then replace the previous one. The sample handles will be recycled as necessary, so there is no danger of memory leaks.
One sound channel can be used to play a single sample, and therefore MIDASplaySample requires the number of the channel that is used to play the sample as an argument. The channel number can be set manually, or MIDAS Digital Audio System can handle the channel selection automatically.
If the channel number for the sample is set manually, the channel used should be allocated with MIDASallocateChannel to ensure that the channel is not being used for other purposes. If a free channel is available, the function will return its number that can then be used with MIDASplaySample. After the channel is no longer used, it should be deallocated with MIDASfreeChannel.
Another possibility is to let MIDAS select the channel automatically. A number of channels can be allocated for use as automatic effect channels with MIDASallocAutoEffectChannels. MIDASplaySample can then be passed MIDAS_CHANNEL_AUTO as the channel number, and it will automatically select the channel that will be used to play the effect. After the automatic effect channels are no longer used, they should be deallocated with MIDASfreeAutoEffectChannels.
Most sample playback properties can be changed while it is being played. MIDASsetSampleRate can be used to change its playback rate, MIDASsetSampleVolume its volume, MIDASsetSamplePanning its panning position and MIDASsetSamplePriority its playback priority. All of these functions take as an argument the sample playback handle from MIDASplaySample, and the new value for the playback property.
The sample playback properties can be changed at any point after the sample playback has been started until the sample playback is stopped with MIDASstopSample. If the sample has reached its end, or has been replaced by another sample with automatic channel selection, the function call is simply ignored.
The sample playback status can be monitored with MIDASgetSamplePlayStatus. It takes as an argument the sample playback handle, and returns the current sample playback status. The playback status information can be used to determine whether or not a sample has already reached its end.