Loads a sample from a file, supporting both mono and stereo WAV and mono
   VOC files, in 8 or 16-bit formats, as well as formats handled by functions
   registered using register_sample_file_type(). Example:
      SAMPLE *sample = load_sample(user_input);
      if (!sample)
         abort_on_error("Couldn't load sample!");
Return value:
   Returns a pointer to the SAMPLE or NULL on error. Remember to free this
   sample later to avoid memory leaks.
See also:
destroy_sample,
load_voc,
load_wav,
play_sample,
save_sample,
register_sample_file_type,
Voice control.
Examples using this:
exsample.
   Loads a sample from a RIFF WAV file. Example:
      SAMPLE *sample = load_wav("scream.wav");
      if (!sample)
         abort_on_error("Couldn't scare user!");
Return value:
   Returns a pointer to the SAMPLE or NULL on error. Remember to free this
   sample later to avoid memory leaks.
See also:
load_sample,
register_sample_file_type.
   A version of load_wav() which reads from a packfile. Example:
      PACKFILE *packfile;
      SAMPLE *sample;
   
      packfile = pack_fopen("sound.wav", F_READ);
      if (!packfile)
         abort_on_error("Couldn't open sound.wav");
   
      sample = load_wav_pf(packfile);
      if (!sample)
         abort_on_error("Error loading sound.wav");
Return value:
   Returns a pointer to the SAMPLE or NULL on error. Remember to free this
   sample later to avoid memory leaks.
See also:
load_wav.
   Loads a sample from a Creative Labs VOC file. Example:
      SAMPLE *sample = load_voc("alarm.voc");
      if (!sample)
         abort_on_error("Couldn't alert user!");
Return value:
   Returns a pointer to the SAMPLE or NULL on error. Remember to free this
   sample later to avoid memory leaks.
See also:
load_sample,
register_sample_file_type.
   A version of load_voc() which reads from a packfile. Example:
      PACKFILE *packfile;
      SAMPLE *sample;
   
      packfile = pack_fopen("sound.wav", F_READ);
      if (!packfile)
         abort_on_error("Couldn't open sound.wav");
   
      sample = load_wav_pf(packfile);
      if (!sample)
         abort_on_error("Error loading sound.wav");
Return value:
   Returns a pointer to the SAMPLE or NULL on error. Remember to free this
   sample later to avoid memory leaks.
See also:
load_voc.
   Writes a sample into a file. The output format is determined from the
   filename extension. At present Allegro does not natively support the
   writing of any sample formats, so you must register a custom saver routine
   with register_sample_file_type(). Example:
      if (save_sample("sound.wav", sample) != 0)
         abort_on_error("Couldn't save sample!");
Return value:
   Returns zero on success, non-zero otherwise.
See also:
load_sample,
register_sample_file_type.
   Constructs a new sample structure of the specified type. Read chapter
   "Structures and types defined by Allegro" for an internal description of
   the SAMPLE structure. The `bits' parameter can be 8 or 16, `stereo' can be
   zero for mono samples and non-zero for stereo samples, `freq' is the
   frequency in hertz, and `len' is the number of samples you want to allocate
   for the full sound buffer.
Return value:
   Returns a pointer to the created sample, or NULL if the sample could not
   be created. Remember to free this sample later to avoid memory leaks.
See also:
load_sample,
destroy_sample,
Structures and types defined by Allegro.
   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. Use this to avoid memory leaks in your
   program.
See also:
load_sample.
Examples using this:
exsample.
   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.
See also:
load_sample,
create_sample.
   Informs the load_sample() function of a new sample file type,
   providing routines to read and write samples in this format (either
   function may be NULL). Example:
      SAMPLE *load_mp3(const char *filename)
      {
         ...
      }
      
         register_sample_file_type("mp3", load_mp3, NULL);
See also:
load_sample,
save_sample.
   Triggers a sample at the specified volume, pan position, and frequency. 
   The parameters `vol' 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 `loop' is not
   zero, the sample will repeat until you call stop_sample(), and can be
   manipulated while it is playing by calling adjust_sample(). Example:
      /* Scream from the left speaker, twice the freq. */
      int sound = play_sample(scream, 255, 0, 2000, 0);
Return value:
   Returns the voice number that was allocated for the sample or negative if
   no voices were available.
See also:
install_sound,
load_sample,
adjust_sample,
stop_sample,
Voice control.
Examples using this:
exsample,
exsprite.
   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. The values of the parameters are just like
   those of play_sample(). 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.
See also:
play_sample.
Examples using this:
exsample.
   Stop a sample from playing, 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. You must still destroy the sample using
   destroy_sample().
See also:
play_sample,
destroy_sample.
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. Read chapter "Structures and types defined by Allegro" for
its definition.
See also:
install_sound,
allocate_voice,
deallocate_voice,
reallocate_voice,
release_voice,
voice_start,
voice_set_priority,
voice_check,
voice_set_position,
voice_set_playmode,
voice_set_volume,
voice_set_frequency,
voice_set_pan,
SAMPLE.
   Allocates a sound card 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().
   Allegro can manage up to 256 simultaneous voices, but that limit may be
   lower due to hardware reasons.
Return value:
   Returns the voice number, or -1 if no voices are available.
See also:
Voice control,
deallocate_voice,
reallocate_voice,
release_voice,
load_sample.
   Frees a sound card voice, stopping it from playing and releasing whatever 
   resources it is using.
See also:
allocate_voice,
voice_stop.
   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);
See also:
allocate_voice,
deallocate_voice,
load_sample.
   Releases a sound card 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.
See also:
allocate_voice,
deallocate_voice.
   Activates a voice, using whatever parameters have been set for it.
See also:
Voice control,
allocate_voice,
voice_stop,
release_voice.
Examples using this:
exstream.
   Stops a voice, storing the current position and state so that it may 
   later be resumed by calling voice_start().
See also:
voice_start,
deallocate_voice,
release_voice.
Examples using this:
exstream.
   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 
   sound card driver can handle.
See also:
Voice control.
   Checks whether a voice is currently allocated.
Return value:
   Returns a pointer to 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).
See also:
allocate_voice,
voice_start,
voice_get_position.
   Returns the current position of a voice, in sample units, or -1 if it has 
   finished playing.
See also:
Voice control,
voice_set_position.
   Sets the position of a voice, in sample units.
See also:
Voice control,
voice_get_position,
voice_set_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.
See also:
Voice control.
   Returns the current volume of the voice, range 0-255.  Otherwise it
   returns -1 if that cannot be determined (because it has finished or
   been preempted by a different sound).
See also:
Voice control,
voice_set_volume.
   Sets the volume of the voice, range 0-255.
See also:
Voice control,
voice_get_volume,
voice_ramp_volume.
   Starts a volume ramp (crescendo or diminuendo) from the current volume to 
   the specified ending volume, lasting for time milliseconds. The volume is
   a value in the range 0-255.
See also:
Voice control,
voice_set_volume.
   Interrupts a volume ramp operation.
See also:
voice_ramp_volume.
   Returns the current pitch of the voice, in Hz.
See also:
Voice control,
voice_set_frequency.
   Sets the pitch of the voice, in Hz.
See also:
Voice control,
voice_get_frequency,
voice_sweep_frequency.
   Starts a frequency sweep (glissando) from the current pitch to the 
   specified ending pitch, lasting for time milliseconds.
See also:
Voice control,
voice_set_frequency.
   Interrupts a frequency sweep operation.
See also:
voice_sweep_frequency.
   Returns the current pan position, from 0 (left) to 255 (right).
See also:
Voice control,
voice_set_pan.
   Sets the pan position, ranging from 0 (left) to 255 (right).
See also:
Voice control,
voice_get_pan,
voice_sweep_pan.
   Starts a pan sweep (left <-> right movement) from the current position to
   the specified ending position, lasting for time milliseconds.
See also:
Voice control,
voice_set_pan.
   Interrupts a pan sweep operation.
See also:
voice_sweep_pan.
   Sets the echo parameters for a voice (not currently implemented).
See also:
Voice control.
   Sets the tremolo parameters for a voice (not currently implemented).
See also:
Voice control.
   Sets the vibrato parameters for a voice (not currently implemented).
See also:
Voice control.