# Digital sample routines

####
- load_sample
- load_wav
- load_voc
- create_sample
- destroy_sample
- lock_sample
- play_sample
- adjust_sample
- stop_sample
- allocate_voice
- deallocate_voice
- reallocate_voice
- release_voice
- voice_start
- voice_stop
- voice_set_priority
- voice_check
- voice_get_position
- voice_set_position
- voice_set_playmode
- voice_get_volume
- voice_set_volume
- voice_ramp_volume
- voice_stop_volumeramp
- voice_get_frequency
- voice_set_frequency
- voice_sweep_frequency
- voice_stop_frequency_sweep
- voice_get_pan
- voice_set_pan
- voice_sweep_pan
- voice_stop_pan_sweep
- voice_set_echo
- voice_set_tremolo
- voice_set_vibrato

SAMPLE *load_sample(const char *filename);
Loads a sample from a file, returning a pointer to it, or NULL on error. At present this function supports both mono and stereo WAV and mono VOC files, in 8 or 16 bit formats.

SAMPLE *load_wav(const char *filename);
Loads a sample from a RIFF WAV file.

SAMPLE *load_voc(const char *filename);
Loads a sample from a Creative Labs VOC file.

SAMPLE *create_sample(int bits, int stereo, int freq, int len);
Constructs a new sample structure of the specified type. The data field points to a block of waveform data: see the structure definition in allegro/digi.h for details.

void destroy_sample(SAMPLE *spl);
Destroys a sample structure when you are done with it. It is safe to call this even when the sample might be playing, because it checks and will kill it off if it is active.

void lock_sample(SAMPLE *spl);
Under DOS, locks all the memory used by a sample. You don't normally need to call this function because load_sample() and create_sample() do it for you.

int play_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
Triggers a sample at the specified volume, pan position, and frequency. The volume and pan range from 0 (min/left) to 255 (max/right). Frequency is relative rather than absolute: 1000 represents the frequency that the sample was recorded at, 2000 is twice this, etc. If the loop flag is set, the sample will repeat until you call stop_sample(), and can be manipulated while it is playing by calling adjust_sample().

void adjust_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
Alters the parameters of a sample while it is playing (useful for manipulating looped sounds). You can alter the volume, pan, and frequency, and can also clear the loop flag, which will stop the sample when it next reaches the end of its loop. If there are several copies of the same sample playing, this will adjust the first one it comes across. If the sample is not playing it has no effect.

void stop_sample(const SAMPLE *spl);
Kills off a sample, which is required if you have set a sample going in looped mode. If there are several copies of the sample playing, it will stop them all.

If you need more detailed control over how samples are played, you can use the lower level voice functions rather than just calling play_sample(). This is rather more work, because you have to explicitly allocate and free the voices rather than them being automatically released when they finish playing, but allows far more precise specification of exactly how you want everything to sound. You may also want to modify a couple of fields from the sample structure:

       int priority;
          Ranging 0-255 (default 128), this controls how voices are
          allocated if you attempt to play more than the driver can handle.
          This may be used to ensure that the less important sounds are
          cut off while the important ones are preserved.

       unsigned long loop_start;
       unsigned long loop_end;
          Loop position in sample units, by default set to the start and end of
          the sample.

int allocate_voice(const SAMPLE *spl);
Allocates a soundcard voice and prepares it for playing the specified sample, setting up sensible default parameters (maximum volume, centre pan, no change of pitch, no looping). When you are finished with the voice you must free it by calling deallocate_voice() or release_voice(). Returns the voice number, or -1 if no voices are available.

void deallocate_voice(int voice);
Frees a soundcard voice, stopping it from playing and releasing whatever resources it is using.

void reallocate_voice(int voice, const SAMPLE *spl);
Switches an already-allocated voice to use a different sample. Calling reallocate_voice(voice, sample) is equivalent to:

          deallocate_voice(voice);
          voice = allocate_voice(sample);

void release_voice(int voice);
Releases a soundcard voice, indicating that you are no longer interested in manipulating it. The sound will continue to play, and any resources that it is using will automatically be freed when it finishes. This is essentially the same as deallocate_voice(), but it waits for the sound to stop playing before taking effect.

void voice_start(int voice);
Activates a voice, using whatever parameters have been set for it.

void voice_stop(int voice);
Stops a voice, storing the current position and state so that it may later be resumed by calling voice_start().

void voice_set_priority(int voice, int priority);
Sets the priority of a voice (range 0-255). This is used to decide which voices should be chopped off, if you attempt to play more than the soundcard driver can handle.

SAMPLE *voice_check(int voice);
Checks whether a voice is currently allocated. It returns a copy of the sample that the voice is using, or NULL if the voice is inactive (ie. it has been deallocated, or the release_voice() function has been called and the sample has then finished playing).

int voice_get_position(int voice);
Returns the current position of a voice, in sample units, or -1 if it has finished playing.

void voice_set_position(int voice, int position);
Sets the position of a voice, in sample units.

void voice_set_playmode(int voice, int playmode);
Adjusts the loop status of the specified voice. This can be done while the voice is playing, so you can start a sample in looped mode (having set the loop start and end positions to the appropriate values), and then clear the loop flag when you want to end the sound, which will cause it to continue past the loop end, play the subsequent part of the sample, and finish in the normal way. The mode parameter is a bitfield containing the following values:

- PLAYMODE_PLAY
  Plays the sample a single time. This is the default if you don't set the loop flag.

- PLAYMODE_LOOP
  Loops repeatedly through the sample, jumping back to the loop start position upon reaching the loop end.

- PLAYMODE_FORWARD
  Plays the sample from beginning to end. This is the default if you don't set the backward flag.

- PLAYMODE_BACKWARD
  Reverses the direction of the sample. If you combine this with the loop flag, the sample jumps to the loop end position upon reaching the loop start (ie. you do not need to reverse the loop start and end values when you play the sample in reverse).

- PLAYMODE_BIDIR
  When used in combination with the loop flag, causes the sample to change direction each time it reaches one of the loop points, so it alternates between playing forwards and in reverse.

int voice_get_volume(int voice);
Returns the current volume of the voice, range 0-255.

void voice_set_volume(int voice, int volume);
Sets the volume of the voice, range 0-255.

void voice_ramp_volume(int voice, int time, int endvol);
Starts a volume ramp (crescendo or diminuendo) from the current volume to the specified ending volume, lasting for time milliseconds.

void voice_stop_volumeramp(int voice);
Interrupts a volume ramp operation.

int voice_get_frequency(int voice);
Returns the current pitch of the voice, in Hz.

void voice_set_frequency(int voice, int frequency);
Sets the pitch of the voice, in Hz.

void voice_sweep_frequency(int voice, int time, int endfreq);
Starts a frequency sweep (glissando) from the current pitch to the specified ending pitch, lasting for time milliseconds.

void voice_stop_frequency_sweep(int voice);
Interrupts a frequency sweep operation.

int voice_get_pan(int voice);
Returns the current pan position, from 0 (left) to 255 (right).

void voice_set_pan(int voice, int pan);
Sets the pan position, ranging from 0 (left) to 255 (right).

void voice_sweep_pan(int voice, int time, int endpan);
Starts a pan sweep (left <-> right movement) from the current position to the specified ending position, lasting for time milliseconds.

void voice_stop_pan_sweep(int voice);
Interrupts a pan sweep operation.

void voice_set_echo(int voice, int strength, int delay);
Sets the echo parameters for a voice (not currently implemented).

void voice_set_tremolo(int voice, int rate, int depth);
Sets the tremolo parameters for a voice (not currently implemented).

void voice_set_vibrato(int voice, int rate, int depth);
Sets the vibrato parameters for a voice (not currently implemented).

Back to Contents