Digital sample routines

adjust_sample — Alters the parameters of a sample while it is playing.
allocate_voice — Allocates a sound card voice for a sample.
create_sample — Constructs a new sample structure of the specified type.
deallocate_voice — Frees a sound card voice.
destroy_sample — Destroys a sample structure when you are done with it.
load_sample — Loads a sample from a file.
load_voc — Loads a sample from a Creative Labs VOC file.
load_voc_pf — Packfile version of load_voc.
load_wav — Loads a sample from a RIFF WAV file.
load_wav_pf — Packfile version of load_wav.
lock_sample — Locks all the memory used by a sample.
play_sample — Plays a sample.
reallocate_voice — Switches the sample of an already-allocated voice.
register_sample_file_type — Registers custom loading/saving sample routines.
release_voice — Releases a sound card voice.
save_sample — Writes a sample into a file.
stop_sample — Stops a sample from playing.
voice_check — Checks whether a voice is currently allocated.
voice_get_frequency — Returns the current pitch of the voice.
voice_get_pan — Returns the current pan position.
voice_get_position — Returns the current position of a voice.
voice_get_volume — Returns the current volume of the voice.
voice_ramp_volume — Starts a volume ramp for a voice.
voice_set_echo — Sets the echo parameters for a voice.
voice_set_frequency — Sets the pitch of the voice.
voice_set_pan — Sets the pan position.
voice_set_playmode — Adjusts the loop status of the specified voice.
voice_set_position — Sets the position of a voice.
voice_set_priority — Sets the priority of a voice.
voice_set_tremolo — Sets the tremolo parameters for a voice.
voice_set_vibrato — Sets the vibrato parameters for a voice.
voice_set_volume — Sets the volume of the voice.
voice_start — Activates a voice.
voice_stop — Stops a voice.
voice_stop_frequency_sweep — Interrupts a frequency sweep operation.
voice_stop_pan_sweep — Interrupts a pan sweep operation.
voice_stop_volumeramp — Interrupts a volume ramp operation.
voice_sweep_frequency — Starts a frequency sweep for a voice.
voice_sweep_pan — Starts a pan sweep for a voice.

SAMPLE *load_sample(const char *filename);

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.

SAMPLE *load_wav(const char *filename);

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.

SAMPLE *load_wav_pf(PACKFILE *f);

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.

SAMPLE *load_voc(const char *filename);

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.

SAMPLE *load_voc_pf(PACKFILE *f);

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.

int save_sample(const char *filename, SAMPLE *spl);

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.

SAMPLE *create_sample(int bits, int stereo, int freq, int len);

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.

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. Use this to avoid memory leaks in your program.

See also: load_sample.

Examples using this: exsample.

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). Example:

      SAMPLE *load_mp3(const char *filename)
      {
         ...
      }
      
         register_sample_file_type("mp3", load_mp3, 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 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.

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. 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.

void stop_sample(const SAMPLE *spl);

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.

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. 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.

int allocate_voice(const SAMPLE *spl);

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.

void deallocate_voice(int voice);

Frees a sound card 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 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.

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.

Examples using this: exstream.

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.

Examples using this: exstream.

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 sound card driver can handle.

See also: Voice control.

SAMPLE *voice_check(int voice);

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.

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:

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.

int voice_get_volume(int voice);

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.

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. The volume is a value in the range 0-255.

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