Digital sample routines


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, as well as formats handled by functions registered using register_sample_file_type.
See also: destroy_sample, load_voc, load_wav, play_sample, save_sample, register_sample_file_type, Voice control.
SAMPLE *load_wav(const char *filename);

Loads a sample from a RIFF WAV file.
See also: load_sample, register_sample_file_type.
SAMPLE *load_voc(const char *filename);

Loads a sample from a Creative Labs VOC file.
See also: load_sample, register_sample_file_type.
int save_sample(const char *filename, SAMPLE *spl);

Writes a sample into a file, returning non-zero on error. 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().
See also: load_sample, register_sample_file_type.
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.
See also: load_sample, destroy_sample.
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.
See also: load_sample.
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.
See also: load_sample, create_sample.
void register_sample_file_type(const char *ext, SAMPLE *(*load)(const char *filename), int (*save)(const char *filename, SAMPLE *spl));

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).
See also: load_sample, save_sample.
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(). Returns the voice number that was allocated for the sample (a non-negative number if successful).
See also: install_sound, load_sample, adjust_sample, stop_sample, Voice control.
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.
See also: play_sample.
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.
See also: play_sample.

Voice control

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.
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.
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.
See also: Voice control, deallocate_voice, reallocate_voice, release_voice, load_sample.
void deallocate_voice(int voice);

Frees a soundcard voice, stopping it from playing and releasing whatever resources it is using.
See also: allocate_voice, voice_stop.
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);
See also: allocate_voice, deallocate_voice, load_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.
See also: allocate_voice, deallocate_voice.
void voice_start(int voice);

Activates a voice, using whatever parameters have been set for it.
See also: Voice control, allocate_voice, voice_stop, release_voice.
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().
See also: voice_start, deallocate_voice, release_voice.
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.
See also: Voice control.
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).
See also: allocate_voice, voice_start, voice_get_position.
int voice_get_position(int voice);

Returns the current position of a voice, in sample units, or -1 if it has finished playing.
See also: Voice control, voice_set_position.
void voice_set_position(int voice, int position);

Sets the position of a voice, in sample units.
See also: Voice control, voice_get_position, voice_set_playmode.
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:
See also: Voice control.
int voice_get_volume(int voice);

Returns the current volume of the voice, range 0-255.
See also: Voice control, voice_set_volume.
void voice_set_volume(int voice, int volume);

Sets the volume of the voice, range 0-255.
See also: Voice control, voice_get_volume, voice_ramp_volume.
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.
See also: Voice control, voice_set_volume.
void voice_stop_volumeramp(int voice);

Interrupts a volume ramp operation.
See also: voice_ramp_volume.
int voice_get_frequency(int voice);

Returns the current pitch of the voice, in Hz.
See also: Voice control, voice_set_frequency.
void voice_set_frequency(int voice, int frequency);

Sets the pitch of the voice, in Hz.
See also: Voice control, voice_get_frequency, voice_sweep_frequency.
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.
See also: Voice control, voice_set_frequency.
void voice_stop_frequency_sweep(int voice);

Interrupts a frequency sweep operation.
See also: voice_sweep_frequency.
int voice_get_pan(int voice);

Returns the current pan position, from 0 (left) to 255 (right).
See also: Voice control, voice_set_pan.
void voice_set_pan(int voice, int pan);

Sets the pan position, ranging from 0 (left) to 255 (right).
See also: Voice control, voice_get_pan, voice_sweep_pan.
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.
See also: Voice control, voice_set_pan.
void voice_stop_pan_sweep(int voice);

Interrupts a pan sweep operation.
See also: voice_sweep_pan.
void voice_set_echo(int voice, int strength, int delay);

Sets the echo parameters for a voice (not currently implemented).
See also: Voice control.
void voice_set_tremolo(int voice, int rate, int depth);

Sets the tremolo parameters for a voice (not currently implemented).
See also: Voice control.
void voice_set_vibrato(int voice, int rate, int depth);

Sets the vibrato parameters for a voice (not currently implemented).
See also: Voice control.
Back to contents