SAMPLE *load_sample(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(char *filename);
Loads a sample from a RIFF WAV file.
SAMPLE *load_voc(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.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.
int play_sample(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(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(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(SAMPLE *spl);
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, 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);
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:
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).