Unit al5audio

Description

Audio addon.

In order to just play some samples, here's how to quick start with Allegro's audio addon: Call al_reserve_samples with the number of samples you'd like to be able to play simultaneously (don't forget to call al_install_audio beforehand). If these succeed, you can now call al_play_sample, with data obtained by al_load_sample, for example (don't forget to initialize the al5acodec addon). You don't need to worry about voices, mixers or sample instances when using this approach. In order to stop samples, you can use the ALLEGRO_SAMPLE_ID that al_play_sample returns.

If you want to play large audio files (e.g. background music) without loading the whole file at once or if you want to output audio generated in real-time, you can use Allegro's audio streams. The easiest way to setup an audio stream is to attach it to the default mixer (created for you by al_reserve_samples) using al_attach_audio_stream_to_mixer on the return value of al_get_default_mixer. Allegro will feed streams created from files using al_load_audio_stream automatically. However, you can also stream audio data you generate on the fly. In this case, audio streams will emit an event when it's time to provide the next fragment (chunk) of audio data. You can control several playback parameters of audio streams (speed, gain, pan, playmode, played/paused; additionally position and loop points when streaming a file).

For more fine-grained control over audio output, here's a short description of the basic concepts:

Voices represent audio devices on the system. Basically, every audio output chain that you want to be heard needs to end up in a voice. As voices are on the hardware/driver side of things, there is only limited control over their parameters (frequency, sample format, channel configuration). The number of available voices is limited as well. Typically, you will only use one voice and attach a mixer to it. Calling al_reserve_samples will do this for you by setting up a default voice and mixer; it can also be achieved by calling al_restore_default_mixer. Although you can attach sample instances and audio streams directly to a voice without using a mixer, it is, as of now, not recommended. In contrast to mixers, you can only attach a single object to a voice anyway.

Mixers mix several sample instances and/or audio streams into a single output buffer, converting sample data with differing formats according to their output parameters (frequency, depth, channels) in the process. In order to play several samples/streams at once reliably, you will need at least one mixer. A mixer that is not (indirectly) attached to a voice will remain silent. For most use cases, one (default) mixer attached to a single voice will be sufficient. You may attach mixers to other mixers in order to create complex audio chains.

Samples (ALLEGRO_SAMPLEptr) just represent "passive" buffers for sample data in memory. In order to play a sample, a sample instance (ALLEGRO_SAMPLE_INSTANCEptr) needs to be created and attached to a mixer (or voice). Sample instances control how the underlying samples are played. Several playback parameters (position, speed, gain, pan, playmode, playing/paused) can be adjusted. Particularly, multiple instances may be created from the same sample, e.g. with different parameters.

Audio streams (see above) are similar to sample instances insofar as they respond to the same playback parameters and have to be attached to mixers or voices. A single audio stream can only be played once simultaneously.

With this in mind, another look at al_reserve_samples and al_play_sample is due: What the former does internally is to create a specified number of sample instances that are "empty" at first, i.e. with no sample data set. When al_play_sample is called, it'll use one of these internal sample instances that is not currently playing to play the requested sample. All of these sample instances will be attached to the default mixer, which can be changed via al_set_default_mixer.

See Audio recording for Allegro's audio recording API, which is, as of now, still unstable and subject to change.

Overview

Classes, Interfaces, Objects and Records

Name Description
Record ALLEGRO_AUDIO_RECORDER_EVENT  
Record ALLEGRO_SAMPLE_ID Represents a sample being played via al_play_sample.

Functions and Procedures

FUNCTION al_create_sample (buf: AL_VOIDptr; samples, freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF; free_buf: AL_BOOL): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_destroy_sample (spl: ALLEGRO_SAMPLEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_create_sample_instance (data: ALLEGRO_SAMPLEptr): ALLEGRO_SAMPLE_INSTANCEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_destroy_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_frequency (CONST spl: ALLEGRO_SAMPLEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_length (CONST spl: ALLEGRO_SAMPLEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_depth (CONST spl: ALLEGRO_SAMPLEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_channels (CONST spl: ALLEGRO_SAMPLEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_data (CONST spl: ALLEGRO_SAMPLEptr): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_frequency (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_length (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_position (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_speed (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_gain (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_pan (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_time (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_depth (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_channels (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_playmode (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_PLAYMODE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_playing (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample_instance_attached (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_position (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_length (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_speed (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_gain (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_pan (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_playmode (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: ALLEGRO_PLAYMODE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample_instance_playing (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_detach_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_sample (spl: ALLEGRO_SAMPLE_INSTANCEptr; data: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_sample (spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_play_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_stop_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_create_audio_stream (buffer_count: AL_SIZE_T; samples, freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_AUDIO_STREAMptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_destroy_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_drain_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_frequency (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_length (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_fragments (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_available_audio_stream_fragments (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_speed (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_gain (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_pan (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_channels (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_depth (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_playmode (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_PLAYMODE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_playing (CONST spl: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_attached (CONST spl: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_fragment (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_speed (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_gain (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_pan (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_playmode (stream: ALLEGRO_AUDIO_STREAMptr; val: ALLEGRO_PLAYMODE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_playing (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_detach_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_fragment (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_rewind_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_seek_audio_stream_secs (stream: ALLEGRO_AUDIO_STREAMptr; time: AL_DOUBLE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_position_secs (stream: ALLEGRO_AUDIO_STREAMptr): AL_DOUBLE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_length_secs (stream: ALLEGRO_AUDIO_STREAMptr): AL_DOUBLE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_audio_stream_loop_secs (stream: ALLEGRO_AUDIO_STREAMptr; start, finish: AL_DOUBLE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_stream_event_source (stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_create_mixer (freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_MIXERptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_destroy_mixer (mixer: ALLEGRO_MIXERptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_sample_instance_to_mixer (sample: ALLEGRO_SAMPLE_INSTANCEptr; mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_audio_stream_to_mixer (stream: ALLEGRO_AUDIO_STREAMptr; mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_mixer_to_mixer (mixerA, mixerB: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_mixer_postprocess_callback (mixer: ALLEGRO_MIXERptr; cb: ALLEGRO_MIXER_CALLBACK; data: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_frequency (CONST mixer: ALLEGRO_MIXERptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_channels (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_depth (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_quality (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_MIXER_QUALITY; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_gain (CONST mixer: ALLEGRO_MIXERptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_playing (CONST mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_mixer_attached (CONST mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_mixer_frequency (mixer: ALLEGRO_MIXERptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_mixer_quality (mixer: ALLEGRO_MIXERptr; val: ALLEGRO_MIXER_QUALITY): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_mixer_gain (mixer: ALLEGRO_MIXERptr; gain: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_mixer_playing (mixer: ALLEGRO_MIXERptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_detach_mixer (mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_create_voice (freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_VOICEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_destroy_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_sample_instance_to_voice (sample: ALLEGRO_SAMPLE_INSTANCEptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_audio_stream_to_voice (stream: ALLEGRO_AUDIO_STREAMptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_attach_mixer_to_voice (mixer: ALLEGRO_MIXERptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_detach_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_voice_frequency (CONST voice: ALLEGRO_VOICEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_voice_position (CONST voice: ALLEGRO_VOICEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_voice_channels (CONST voice: ALLEGRO_VOICEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_voice_depth (CONST voice: ALLEGRO_VOICEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_voice_playing (CONST voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_voice_position (voice: ALLEGRO_VOICEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_voice_playing (voice: ALLEGRO_VOICEptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_install_audio: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_uninstall_audio; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_is_audio_installed: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_allegro_audio_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_channel_count (conf: ALLEGRO_CHANNEL_CONF): AL_SIZE_T; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_audio_depth_size (conf: ALLEGRO_AUDIO_DEPTH): AL_SIZE_T; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_fill_silence (bur: AL_VOIDptr; samples: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_reserve_samples (reserve_samples: AL_INT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_default_mixer: ALLEGRO_MIXERptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_set_default_mixer (mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_restore_default_mixer: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_play_sample (data: ALLEGRO_SAMPLEptr; gain, pan, speed: AL_FLOAT; loop: ALLEGRO_PLAYMODE; ret_id: ALLEGRO_SAMPLE_IDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_stop_sample (spl_id: ALLEGRO_SAMPLE_IDptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_stop_samples; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_get_default_voice: ALLEGRO_VOICEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
PROCEDURE al_set_default_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_load_sample (CONST filename: AL_STR): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_save_sample (CONST filename: AL_STR; spl: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
FUNCTION al_load_audio_stream (CONST filename: AL_STR; buffer_count: AL_SIZE_T; samples: AL_UINT): ALLEGRO_AUDIO_STREAMptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Types

ALLEGRO_AUDIO_RECORDERptr = AL_POINTER;
ALLEGRO_AUDIO_RECORDER_EVENTptr = ˆALLEGRO_AUDIO_RECORDER_EVENT;
ALLEGRO_AUDIO_DEPTH = (...);
ALLEGRO_CHANNEL_CONF = (...);
ALLEGRO_PLAYMODE = (...);
ALLEGRO_MIXER_QUALITY = (...);
ALLEGRO_SAMPLEptr = AL_POINTER;
ALLEGRO_SAMPLE_IDptr = ˆALLEGRO_SAMPLE_ID;
ALLEGRO_SAMPLE_INSTANCEptr = AL_POINTER;
ALLEGRO_AUDIO_STREAMptr = AL_POINTER;
ALLEGRO_MIXERptr = AL_POINTER;
ALLEGRO_VOICEptr = AL_POINTER;
ALLEGRO_MIXER_CALLBACK = PROCEDURE (buf: AL_VOIDptr; samples: AL_UINT; data: AL_VOIDptr); CDECL;
ALLEGRO_SAMPLE_LOADER = FUNCTION (CONST filename: AL_STRptr): ALLEGRO_SAMPLEptr; CDECL;
ALLEGRO_SAMPLE_SAVER = FUNCTION (CONST filename: AL_STRptr; spl: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL;
ALLEGRO_AUDIO_STREAM_LOADER = FUNCTION (CONST filename: AL_STRptr; buffer_count: AL_SIZE_T; samples: AL_UINT): ALLEGRO_AUDIO_STREAMptr;

Constants

ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT = 513;
ALLEGRO_EVENT_AUDIO_STREAM_FINISHED = 514;
ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT = 515;
ALLEGRO_MAX_CHANNELS = 8;
ALLEGRO_AUDIO_PAN_NONE: AL_FLOAT = -1000.0;

Description

Functions and Procedures

FUNCTION al_create_sample (buf: AL_VOIDptr; samples, freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF; free_buf: AL_BOOL): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Sample functions

PROCEDURE al_destroy_sample (spl: ALLEGRO_SAMPLEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_create_sample_instance (data: ALLEGRO_SAMPLEptr): ALLEGRO_SAMPLE_INSTANCEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Sample instance functions

PROCEDURE al_destroy_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_frequency (CONST spl: ALLEGRO_SAMPLEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_length (CONST spl: ALLEGRO_SAMPLEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_depth (CONST spl: ALLEGRO_SAMPLEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_channels (CONST spl: ALLEGRO_SAMPLEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_data (CONST spl: ALLEGRO_SAMPLEptr): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_frequency (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_length (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_position (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_speed (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_gain (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_pan (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_time (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_depth (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_channels (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_playmode (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_PLAYMODE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_playing (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample_instance_attached (CONST spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_position (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_length (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_speed (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_gain (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_pan (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_playmode (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: ALLEGRO_PLAYMODE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample_instance_playing (spl: ALLEGRO_SAMPLE_INSTANCEptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_detach_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_sample (spl: ALLEGRO_SAMPLE_INSTANCEptr; data: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_sample (spl: ALLEGRO_SAMPLE_INSTANCEptr): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_play_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_stop_sample_instance (spl: ALLEGRO_SAMPLE_INSTANCEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_create_audio_stream (buffer_count: AL_SIZE_T; samples, freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_AUDIO_STREAMptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Stream functions

PROCEDURE al_destroy_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
PROCEDURE al_drain_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_frequency (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_length (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_fragments (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_available_audio_stream_fragments (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_speed (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_gain (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_pan (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_channels (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_depth (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_playmode (CONST stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_PLAYMODE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_playing (CONST spl: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_attached (CONST spl: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_fragment (CONST stream: ALLEGRO_AUDIO_STREAMptr): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_speed (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_gain (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_pan (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_playmode (stream: ALLEGRO_AUDIO_STREAMptr; val: ALLEGRO_PLAYMODE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_playing (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_detach_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_fragment (stream: ALLEGRO_AUDIO_STREAMptr; val: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_rewind_audio_stream (stream: ALLEGRO_AUDIO_STREAMptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_seek_audio_stream_secs (stream: ALLEGRO_AUDIO_STREAMptr; time: AL_DOUBLE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_position_secs (stream: ALLEGRO_AUDIO_STREAMptr): AL_DOUBLE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_length_secs (stream: ALLEGRO_AUDIO_STREAMptr): AL_DOUBLE; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_audio_stream_loop_secs (stream: ALLEGRO_AUDIO_STREAMptr; start, finish: AL_DOUBLE): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_audio_stream_event_source (stream: ALLEGRO_AUDIO_STREAMptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_create_mixer (freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_MIXERptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Mixer functions

PROCEDURE al_destroy_mixer (mixer: ALLEGRO_MIXERptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_attach_sample_instance_to_mixer (sample: ALLEGRO_SAMPLE_INSTANCEptr; mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_attach_audio_stream_to_mixer (stream: ALLEGRO_AUDIO_STREAMptr; mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Attach an audio stream to a mixer. The stream must not already be attached to anything.

Returns

True on success, False on failure.

See also
al_detach_audio_stream
FUNCTION al_attach_mixer_to_mixer (mixerA, mixerB: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_mixer_postprocess_callback (mixer: ALLEGRO_MIXERptr; cb: ALLEGRO_MIXER_CALLBACK; data: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_frequency (CONST mixer: ALLEGRO_MIXERptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_channels (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_depth (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_quality (CONST mixer: ALLEGRO_MIXERptr): ALLEGRO_MIXER_QUALITY; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_gain (CONST mixer: ALLEGRO_MIXERptr): AL_FLOAT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_playing (CONST mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_mixer_attached (CONST mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_mixer_frequency (mixer: ALLEGRO_MIXERptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_mixer_quality (mixer: ALLEGRO_MIXERptr; val: ALLEGRO_MIXER_QUALITY): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_mixer_gain (mixer: ALLEGRO_MIXERptr; gain: AL_FLOAT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_mixer_playing (mixer: ALLEGRO_MIXERptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_detach_mixer (mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_create_voice (freq: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF): ALLEGRO_VOICEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Creates a voice structure and allocates a voice from the digital sound driver. The passed frequency, sample format and channel configuration are used as a hint to what kind of data will be sent to the voice. However, the underlying sound driver is free to use non-matching values. For example, it may be the native format of the sound hardware.

If a mixer is attached to the voice, the mixer will handle the conversion of all its input streams to the voice format and care does not have to be taken for this. However if you access the voice directly, make sure to not rely on the parameters passed to this function, but instead query the returned voice for the actual settings.

See also
al_destroy_voice
Destroys the voice and deallocates it from the digital driver.
PROCEDURE al_destroy_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Destroys the voice and deallocates it from the digital driver. Does nothing if the voice is Nil.

See also
al_create_voice
Creates a voice structure and allocates a voice from the digital sound driver.
FUNCTION al_attach_sample_instance_to_voice (sample: ALLEGRO_SAMPLE_INSTANCEptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Attaches a sample instance to a voice, and allows it to play. The instance's gain and loop mode will be ignored, and it must have the same frequency, channel configuration and depth (including signed-ness) as the voice. This function may fail if the selected driver doesn't support preloading sample data.

At this time, we don't recommend attaching sample instances directly to voices. Use a mixer inbetween. seealso(al_detach_voice)

Returns

True on success, False on failure.

FUNCTION al_attach_audio_stream_to_voice (stream: ALLEGRO_AUDIO_STREAMptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Attaches an audio stream to a voice. The same rules as al_attach_sample_instance_to_voice apply. This may fail if the driver can't create a voice with the buffer count and buffer size the stream uses.

An audio stream attached directly to a voice has a number of limitations: The audio stream plays immediately and cannot be stopped. The stream position, speed, gain and panning cannot be changed. At this time, we don't recommend attaching audio streams directly to voices. Use a mixer inbetween.

Returns

True on success, False on failure.

See also
al_detach_voice
Detaches the mixer, sample instance or audio stream from the voice.
FUNCTION al_attach_mixer_to_voice (mixer: ALLEGRO_MIXERptr; voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Attaches a mixer to a voice. It must have the same frequency and channel configuration, but the depth may be different.

Returns

True on success, False on failure.

See also
al_detach_voice
Detaches the mixer, sample instance or audio stream from the voice.
PROCEDURE al_detach_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Detaches the mixer, sample instance or audio stream from the voice.

See also
al_attach_mixer_to_voice
Attaches a mixer to a voice.
al_attach_sample_instance_to_voice
Attaches a sample instance to a voice, and allows it to play.
al_attach_audio_stream_to_voice
Attaches an audio stream to a voice.
FUNCTION al_get_voice_frequency (CONST voice: ALLEGRO_VOICEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_voice_position (CONST voice: ALLEGRO_VOICEptr): AL_UINT; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_voice_channels (CONST voice: ALLEGRO_VOICEptr): ALLEGRO_CHANNEL_CONF; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_voice_depth (CONST voice: ALLEGRO_VOICEptr): ALLEGRO_AUDIO_DEPTH; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_voice_playing (CONST voice: ALLEGRO_VOICEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_voice_position (voice: ALLEGRO_VOICEptr; val: AL_UINT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_voice_playing (voice: ALLEGRO_VOICEptr; val: AL_BOOL): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_install_audio: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Install the audio subsystem.

Note: most users will call al_reserve_samples and al_init_acodec_addon after this. *)

Returns

True on success, False on failure.

See also
al_reserve_samples
Reserves a number of sample instances, attaching them to the default mixer.
al_uninstall_audio
Uninstall the audio subsystem.
al_is_audio_installed
Returns True if al_install_audio was called previously and returned successfully.
al_init_acodec_addon
Registers all the known audio file type handlers for al_load_sample, al_save_sample, al_load_audio_stream, etc.
PROCEDURE al_uninstall_audio; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Uninstall the audio subsystem.

FUNCTION al_is_audio_installed: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Returns True if al_install_audio was called previously and returned successfully.

FUNCTION al_get_allegro_audio_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

FUNCTION al_get_channel_count (conf: ALLEGRO_CHANNEL_CONF): AL_SIZE_T; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Return the number of channels for the given channel configuration, which is one of the values listed under ALLEGRO_CHANNEL_CONF.

FUNCTION al_get_audio_depth_size (conf: ALLEGRO_AUDIO_DEPTH): AL_SIZE_T; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Return the size of a sample, in bytes, for the given format. The format is one of the values listed under ALLEGRO_AUDIO_DEPTH.

PROCEDURE al_fill_silence (bur: AL_VOIDptr; samples: AL_UINT; depth: ALLEGRO_AUDIO_DEPTH; chan_conf: ALLEGRO_CHANNEL_CONF); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Fill a buffer with silence, for the given format and channel configuration. The buffer must have enough space for the given number of samples, and be properly aligned.

FUNCTION al_reserve_samples (reserve_samples: AL_INT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Reserves a number of sample instances, attaching them to the default mixer. If no default mixer is set when this function is called, then it will create one and attach it to the default voice. If no default voice has been set, it, too, will be created.

This diagram illustrates the structures that are set up:

                                      sample instance 1
                                    / sample instance 2
default voice <-- default mixer <---         .
                                    \        .
                                      sample instance N

Returns

True on success, False on error. al_install_audio must have been called first.

See also
al_set_default_mixer
al_play_sample
Plays a sample on one of the sample instances created by al_reserve_samples.
FUNCTION al_get_default_mixer: ALLEGRO_MIXERptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_set_default_mixer (mixer: ALLEGRO_MIXERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_restore_default_mixer: AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_play_sample (data: ALLEGRO_SAMPLEptr; gain, pan, speed: AL_FLOAT; loop: ALLEGRO_PLAYMODE; ret_id: ALLEGRO_SAMPLE_IDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Plays a sample on one of the sample instances created by al_reserve_samples.

Parameters
gain
relative volume at which the sample is played; 1.0 is normal.
pan
0.0 is centred, -1.0 is left, 1.0 is right, or ALLEGRO_AUDIO_PAN_NONE.
speed
relative speed at which the sample is played; 1.0 is normal.
loop
ALLEGRO_PLAYMODE_ONCE, ALLEGRO_PLAYMODE_LOOP, or ALLEGRO_PLAYMODE_BIDIR.
ret_id
if non-Nil the variable which this points to will be assigned an id representing the sample being played.
Returns

True on success, False on failure. Playback may fail because all the reserved sample instances are currently used.

See also
ALLEGRO_PLAYMODE
Sample and stream playback mode.
ALLEGRO_AUDIO_PAN_NONE
A special value for the pan property of sample instances and audio streams.
ALLEGRO_SAMPLE_ID
Represents a sample being played via al_play_sample.
al_stop_sample
al_stop_samples
PROCEDURE al_stop_sample (spl_id: ALLEGRO_SAMPLE_IDptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
PROCEDURE al_stop_samples; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_get_default_voice: ALLEGRO_VOICEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
PROCEDURE al_set_default_voice (voice: ALLEGRO_VOICEptr); CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_load_sample (CONST filename: AL_STR): ALLEGRO_SAMPLEptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Loads a few different audio file formats based on their extension.

Note that this stores the entire file in memory at once, which may be time consuming. To read the file as it is needed, use al_load_audio_stream.

Note: the al5audio library does not support any audio file formats by default. You must use the al5acodec addon, or register your own format handler.

Returns

The sample on success, Nil on failure.

See also
al_register_sample_loader
al_init_acodec_addon
Registers all the known audio file type handlers for al_load_sample, al_save_sample, al_load_audio_stream, etc.
FUNCTION al_save_sample (CONST filename: AL_STR; spl: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;
 
FUNCTION al_load_audio_stream (CONST filename: AL_STR; buffer_count: AL_SIZE_T; samples: AL_UINT): ALLEGRO_AUDIO_STREAMptr; CDECL; EXTERNAL ALLEGRO_AUDIO_LIB_NAME;

Loads an audio file from disk as it is needed.

Unlike regular streams, the one returned by this function need not be fed by the user; the library will automatically read more of the file as it is needed. The stream will contain buffer_count buffers with samples samples.

The audio stream will start in the playing state. It should be attached to a voice or mixer to generate any output. See ALLEGRO_AUDIO_STREAMptr for more details.

Note: the al5audio library does not support any audio file formats by default. You must use the al5acodec addon, or register your own format handler.

Returns

the stream on success, Nil on failure.

See also
al_init_acodec_addon
Registers all the known audio file type handlers for al_load_sample, al_save_sample, al_load_audio_stream, etc.

Types

ALLEGRO_AUDIO_RECORDERptr = AL_POINTER;
 
ALLEGRO_AUDIO_RECORDER_EVENTptr = ˆALLEGRO_AUDIO_RECORDER_EVENT;
 
ALLEGRO_AUDIO_DEPTH = (...);

Sample depth and type, and signedness. Mixers only use 32-bit signed float (-1..+1). The unsigned value is a bit-flag applied to the depth value.

Values
  • ALLEGRO_AUDIO_DEPTH_INT8 = $00
  • ALLEGRO_AUDIO_DEPTH_INT16 = $01
  • ALLEGRO_AUDIO_DEPTH_INT24 = $02
  • ALLEGRO_AUDIO_DEPTH_FLOAT32 = $03
  • ALLEGRO_AUDIO_DEPTH_UNSIGNED = $08
  • ALLEGRO_AUDIO_DEPTH_UINT16 = $09: ALLEGRO_AUDIO_DEPTH_INT16 OR ALLEGRO_AUDIO_DEPTH_UNSIGNED
  • ALLEGRO_AUDIO_DEPTH_UINT24 = $0A: ALLEGRO_AUDIO_DEPTH_INT24 OR ALLEGRO_AUDIO_DEPTH_UNSIGNED
ALLEGRO_CHANNEL_CONF = (...);

Speaker configuration (mono, stereo, 2.1, 3, etc). With regards to behavior, most of this code makes no distinction between, say, 4.1 and 5 speaker setups.. they both have 5 "channels". However, users would like the distinction, and later when the higher-level stuff is added, the differences will become more important. (v>>4)+(v&0xF) should yield the total channel count.

Values
  • ALLEGRO_CHANNEL_CONF_1 = $10
  • ALLEGRO_CHANNEL_CONF_2 = $20
  • ALLEGRO_CHANNEL_CONF_3 = $30
  • ALLEGRO_CHANNEL_CONF_4 = $40
  • ALLEGRO_CHANNEL_CONF_5_1 = $51
  • ALLEGRO_CHANNEL_CONF_6_1 = $61
  • ALLEGRO_CHANNEL_CONF_7_1 = $71
ALLEGRO_PLAYMODE = (...);

Sample and stream playback mode.

Values
  • ALLEGRO_PLAYMODE_ONCE = $100
  • ALLEGRO_PLAYMODE_LOOP = $101
  • ALLEGRO_PLAYMODE_BIDIR = $102
ALLEGRO_MIXER_QUALITY = (...);
 
Values
  • ALLEGRO_MIXER_QUALITY_POINT = $110: Point sampling.
  • ALLEGRO_MIXER_QUALITY_LINEAR = $111: Linear interpolation.
  • ALLEGRO_MIXER_QUALITY_CUBIC = $112: Cubic interpolation.
ALLEGRO_SAMPLEptr = AL_POINTER;

Pointer to the data necessary for playing pre-defined digital audio. It holds a user-specified PCM data buffer and information about its format (data length, depth, frequency, channel configuration). You can have the same ALLEGRO_SAMPLE playing multiple times simultaneously.

See also
ALLEGRO_SAMPLE_INSTANCEptr
An ALLEGRO_SAMPLE_INSTANCEptr represents a playable instance of a predefined sound effect.
ALLEGRO_SAMPLE_IDptr = ˆALLEGRO_SAMPLE_ID;

Pointer to ALLEGRO_SAMPLE_ID.

ALLEGRO_SAMPLE_INSTANCEptr = AL_POINTER;

An ALLEGRO_SAMPLE_INSTANCEptr represents a playable instance of a predefined sound effect. It holds information about how the effect should be played: These playback parameters consist of the looping mode, loop start/end points, playing position, speed, gain, pan and the playmode. Whether a sample instance is currently playing or paused is also one of its properties.

An instance uses the data from an ALLEGRO_SAMPLE object. Multiple instances may be created from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE must not be destroyed while there are instances which reference it.

To actually produce audio output, an ALLEGRO_SAMPLE_INSTANCEptr must be attached to an ALLEGRO_MIXERptr which eventually reaches an ALLEGRO_VOICEptr object.

See also
ALLEGRO_SAMPLEptr
Pointer to the data necessary for playing pre-defined digital audio.
ALLEGRO_AUDIO_STREAMptr = AL_POINTER;

Pointer to an ALLEGRO_AUDIO_STREAM object that is used to stream generated audio to the sound device, in real-time. This is done by reading from a buffer, which is split into a number of fragments. Whenever a fragment has finished playing, the user can refill it with new data.

As with ALLEGRO_SAMPLE_INSTANCEptr objects, streams store information necessary for playback, so you may not play the same stream multiple times simultaneously. Streams also need to be attached to an ALLEGRO_MIXERptr, which, eventually, reaches an ALLEGRO_VOICEptr object.

While playing, you must periodically fill fragments with new audio data. To know when a new fragment is ready to be filled, you can either directly check with al_get_available_audio_stream_fragments, or listen to events from the stream.

You can register an audio stream event source to an event queue; see al_get_audio_stream_event_source. An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event is generated whenever a new fragment is ready. When you receive an event, use al_get_audio_stream_fragment to obtain a pointer to the fragment to be filled. The size and format are determined by the parameters passed to al_create_audio_stream.

If you're late with supplying new data, the stream will be silent until new data is provided. You must call al_drain_audio_stream when you're finished with supplying data to the stream.

If the stream is created by al_load_audio_stream then it will also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED event if it reaches the end of the file and is not set to loop.

ALLEGRO_MIXERptr = AL_POINTER;

A mixer mixes together attached streams into a single buffer. In the process, it converts channel configurations, sample frequencies and audio depths of the attached sample instances and audio streams accordingly. You can control the quality of this conversion using ALLEGRO_MIXER_QUALITY.

ALLEGRO_VOICEptr = AL_POINTER;

A voice represents an audio device on the system, which may be a real device, or an abstract device provided by the operating system. To play back audio, you would attach a mixer, sample instance or audio stream to a voice.

See also
ALLEGRO_MIXERptr
A mixer mixes together attached streams into a single buffer.
ALLEGRO_SAMPLEptr
Pointer to the data necessary for playing pre-defined digital audio.
ALLEGRO_AUDIO_STREAMptr
Pointer to an ALLEGRO_AUDIO_STREAM object that is used to stream generated audio to the sound device, in real-time.
ALLEGRO_MIXER_CALLBACK = PROCEDURE (buf: AL_VOIDptr; samples: AL_UINT; data: AL_VOIDptr); CDECL;

#ifndef __cplusplus typedef enum ALLEGRO_AUDIO_DEPTH ALLEGRO_AUDIO_DEPTH; typedef enum ALLEGRO_CHANNEL_CONF ALLEGRO_CHANNEL_CONF; typedef enum ALLEGRO_PLAYMODE ALLEGRO_PLAYMODE; typedef enum ALLEGRO_MIXER_QUALITY ALLEGRO_MIXER_QUALITY; #endif

ALLEGRO_SAMPLE_LOADER = FUNCTION (CONST filename: AL_STRptr): ALLEGRO_SAMPLEptr; CDECL;
 
ALLEGRO_SAMPLE_SAVER = FUNCTION (CONST filename: AL_STRptr; spl: ALLEGRO_SAMPLEptr): AL_BOOL; CDECL;
 
ALLEGRO_AUDIO_STREAM_LOADER = FUNCTION (CONST filename: AL_STRptr; buffer_count: AL_SIZE_T; samples: AL_UINT): ALLEGRO_AUDIO_STREAMptr;
 

Constants

ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT = 513;

User event type emitted when a stream fragment is ready to be refilled with more audio data.

Must be in 512 <= n < 1024

ALLEGRO_EVENT_AUDIO_STREAM_FINISHED = 514;

Undocumented. (?)

ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT = 515;

Sent after a user-specified number of samples have been recorded.

You must always check the values for the buffer and samples as they are not guaranteed to be exactly what was originally specified.

Unstable API: It may need a slight redesign.

ALLEGRO_MAX_CHANNELS = 8;
 
ALLEGRO_AUDIO_PAN_NONE: AL_FLOAT = -1000.0;

A special value for the pan property of sample instances and audio streams. Use this value to disable panning on sample instances and audio streams, and play them without attentuation implied by panning support.

ALLEGRO_AUDIO_PAN_NONE is different from a pan value of 0.0 (centered) because, when panning is enabled, we try to maintain a constant sound power level as a sample is panned from left to right. A sound coming out of one speaker should sound as loud as it does when split over two speakers. As a consequence, a sample with pan value 0.0 will be 3 dB softer than the original level.

(Please correct us if this is wrong.)


Generated by PasDoc 0.14.0. Generated on 2017-01-03 13:25:50.