Search
|
These functions are declared in the following header file. Link with allegro_audio.
Audio typesALLEGRO_AUDIO_DEPTH
Sample depth and type, and signedness. Mixers only use 32-bit signed float (-1..+1), or 16-bit signed integers. The unsigned value is a bit-flag applied to the depth value.
For convenience:
ALLEGRO_AUDIO_PAN_NONE
Special value for the ALLEGRO_AUDIOPROP_PAN property. Use this value to play samples at their original volume with panning disabled. ALLEGRO_CHANNEL_CONF
Speaker configuration (mono, stereo, 2.1, 3, etc).
ALLEGRO_MIXER
A mixer is a type of stream which mixes together attached streams into a single buffer. ALLEGRO_MIXER_QUALITY
ALLEGRO_PLAYMODE
Sample and stream looping mode.
ALLEGRO_SAMPLE_ID
An ALLEGRO_SAMPLE_ID represents a sample being played via al_play_sample. It can be used to later stop the sample with al_stop_sample. ALLEGRO_SAMPLE
An ALLEGRO_SAMPLE object stores the data necessary for playing pre-defined digital audio. It holds information pertaining to data length, frequency, channel configuration, etc. You can have an ALLEGRO_SAMPLE object playing multiple times simultaneously. The object holds a user-specified PCM data buffer, of the format the object is created with. ALLEGRO_SAMPLE_INSTANCE
An ALLEGRO_SAMPLE_INSTANCE object represents a playable instance of a predefined sound effect. It holds information pertaining to the looping mode, loop start/end points, playing position, etc. 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 be played, an ALLEGRO_SAMPLE_INSTANCE object must be attached to an ALLEGRO_VOICE object, or to an ALLEGRO_MIXER object which is itself attached to an ALLEGRO_VOICE object (or to another ALLEGRO_MIXER object which is attached to an ALLEGRO_VOICE object, etc). ALLEGRO_AUDIO_STREAM
An ALLEGRO_AUDIO_STREAM object 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_INSTANCE 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_VOICE object, or to an ALLEGRO_MIXER object which, eventually, reaches an ALLEGRO_VOICE 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 can also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED event if it reaches the end of the file and is not set to loop. ALLEGRO_VOICE
A voice structure that you'd attach a mixer or sample to. Ideally there would be one ALLEGRO_VOICE per system/hardware voice. Setting upal_install_audio
Install the audio subsystem. Returns true on success, false on failure. See also: al_reserve_samples, al_uninstall_audio, al_is_audio_installed al_uninstall_audio
Uninstalls the audio subsystem. See also: al_install_audio al_is_audio_installed
Returns true if al_install_audio was called previously and returned successfully. al_reserve_samples
Reserves 'reserve_samples' number of samples attached to the default mixer. al_install_audio must have been called first. If no default mixer is set, then this function will create a voice with an attached mixer. Returns true on success, false on error. See also: al_set_default_mixer al_get_allegro_audio_version
Returns the (compiled) version of the addon, in the same format as al_get_allegro_version. al_get_audio_depth_sizeReturn the size of a sample, in bytes, for the given format. The format is one of the values listed under ALLEGRO_AUDIO_DEPTH. al_get_channel_countReturn the number of channels for the given channel configuration, which is one of the values listed under ALLEGRO_CHANNEL_CONF. Voice functionsal_create_voice
Creates a voice struct 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 you attach a mixer to the voice, the mixer will convert from the mixer's format to the voice format and you do not have to care about this. If you access the voice directly, make sure to not rely on the parameters passed to this function, but query the returned voice for the actual settings. See also: al_destroy_voice al_destroy_voice
Destroys the voice and deallocates it from the digital driver. Does nothing if the voice is NULL. See also: al_create_voice al_detach_voice
Detaches the sample or mixer stream from the voice. al_attach_audio_stream_to_voice
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, panning, cannot be changed. At this time, we don't recommend attaching audio streams directly to voices. Use a mixer in between. Returns true on success, false on failure. al_attach_mixer_to_voice
Attaches a mixer to a voice. The same rules as al_attach_sample_instance_to_voice apply, with the exception of the depth requirement. Returns true on success, false on failure. al_attach_sample_instance_to_voice
Attaches a sample to a voice, and allows it to play. The sample's volume and loop mode will be ignored, and it must have the same frequency 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 samples directly to voices. Use a mixer in between. Returns true on success, false on failure. al_get_voice_frequency
Return the frequency of the voice, e.g. 44100. al_get_voice_channels
Return the channel configuration of the voice. See also: ALLEGRO_CHANNEL_CONF. al_get_voice_depth
Return the audio depth of the voice. See also: ALLEGRO_AUDIO_DEPTH. al_get_voice_playing
Return true if the voice is currently playing. al_set_voice_playing
Change whether a voice is playing or not. The voice must have a sample or mixer attached to it. Returns true on success, false on failure. al_get_voice_position
When the voice has a non-streaming object attached to it, e.g. a sample, returns the voice's current sample position. Otherwise, returns zero. See also: al_set_voice_position. al_set_voice_position
Set the voice position. This can only work if the voice has a non-streaming object attached to it, e.g. a sample. Returns true on success, false on failure. See also: al_get_voice_position. Sample functionsal_create_sample
Create a sample data structure from the supplied buffer. If To allocate a buffer of the correct size, you can use something like this:
See also: al_destroy_sample. al_destroy_sample
Free the sample data structure. If it was created with the You must stop or destroy any ALLEGRO_SAMPLE_INSTANCE structures which reference this ALLEGRO_SAMPLE beforehand. If you have used al_play_sample at all, it is a very good idea to call al_stop_samples before destroying samples at the end of the program, in case any are still playing. See also: al_destroy_sample_instance, al_stop_sample, al_stop_samples al_play_sample
Plays a sample over the default mixer. al_reserve_samples must have previously been called. Returns true on success, false on failure. Playback may fail because all the reserved samples are currently used. Parameters:
See also: ALLEGRO_PLAYMODE, ALLEGRO_AUDIO_PAN_NONE, ALLEGRO_SAMPLE_ID, al_stop_sample, al_stop_samples. al_stop_sample
Stop the sample started by al_play_sample. See also: al_stop_samples al_stop_samples
Stop all samples started by al_play_sample. See also: al_stop_sample al_get_sample_channels
Return the channel configuration. See also: ALLEGRO_CHANNEL_CONF. al_get_sample_depth
Return the audio depth. See also: ALLEGRO_AUDIO_DEPTH. al_get_sample_frequency
Return the frequency of the sample. al_get_sample_length
Return the length of the sample in sample values. al_get_sample_data
Return a pointer to the raw sample data. Sample instance functionsal_create_sample_instance
Creates a sample stream, using the supplied data. This must be attached to a voice or mixer before it can be played. The argument may be NULL. You can then set the data later with al_set_sample. al_destroy_sample_instance
Detaches the sample stream from anything it may be attached to and frees it (the sample data is not freed!). al_play_sample_instance
Play an instance of a sample data. Returns true on success, false on failure. al_stop_sample_instance
Stop an sample instance playing. al_get_sample_instance_channels
Return the channel configuration. See also: ALLEGRO_CHANNEL_CONF. al_get_sample_instance_depth
Return the audio depth. See also: ALLEGRO_AUDIO_DEPTH. al_get_sample_instance_frequency
Return the frequency of the sample instance. al_get_sample_instance_length
Return the length of the sample instance in sample values. al_set_sample_instance_length
Set the length of the sample instance in sample values. Return true on success, false on failure. Will fail if the sample instance is currently playing. al_get_sample_instance_position
Get the playback position of a sample instance. al_set_sample_instance_position
Set the playback position of a sample instance. Returns true on success, false on failure. al_get_sample_instance_speed
Return the playback speed. al_set_sample_instance_speed
Set the playback speed. Return true on success, false on failure. Will fail if the sample instance is attached directly to a voice. al_get_sample_instance_gain
Return the playback gain. al_set_sample_instance_gain
Set the playback gain. Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice. al_get_sample_instance_pan
Get the pan value. See also: al_set_sample_instance_pan. al_set_sample_instance_pan
Set the pan value on a sample instance. A value of -1.0 means to play the sample only through the left speaker; +1.0 means only through the right speaker; 0.0 means the sample is centre balanced. A constant sound power level is maintained as the sample is panned from left to right. As a consequence, a pan value of 0.0 will play the sample 3 dB softer than the original level. To disable panning and play a sample at its original level, set the pan value to ALLEGRO_AUDIO_PAN_NONE. Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice. (A sound guy should explain that better; I only implemented it. Also this might be more properly called a balance control than pan. Also we don't attempt anything with more than two channels yet.) See also: al_get_sample_instance_pan. al_get_sample_instance_time
Return the length of the sample instance in seconds, assuming a playback speed of 1.0. al_get_sample_instance_playmode
Return the playback mode. al_set_sample_instance_playmode
Set the playback mode. Returns true on success, false on failure. al_get_sample_instance_playing
Return true if the sample instance is playing. al_set_sample_instance_playing
Change whether the sample instance is playing. Returns true on success, false on failure. al_get_sample_instance_attached
Return whether the sample instance is attached to something. al_detach_sample_instance
Detach the sample instance from whatever it's attached to, if anything. Returns true on success. al_get_sample
Return the sample data that the sample instance plays. al_set_sample
Change the sample data that a sample instance plays. This can be quite an involved process. First, the sample is stopped if it is not already. Next, if data is NULL, the sample is detached from its parent (if any). If data is not NULL, the sample may be detached and reattached to its parent (if any). This is not necessary if the old sample data and new sample data have the same frequency, depth and channel configuration. Reattaching may not always succeed. On success, the sample remains stopped. The playback position and loop end points are reset to their default values. The loop mode remains unchanged. Returns true on success, false on failure. On failure, the sample will be stopped and detached from its parent. Mixer functionsal_create_mixer
Creates a mixer stream, to attach sample streams or other mixers to. It will mix into a buffer at the requested frequency and channel count. The only supported audio depths are ALLEGRO_AUDIO_DEPTH_FLOAT32 and ALLEGRO_AUDIO_DEPTH_INT16 (not yet complete). Returns true on success, false on error. See also: al_destroy_mixer al_destroy_mixer
Destroys the mixer stream. See also: al_create_mixer al_get_default_mixer
Return the default mixer, or NULL if one has not been set. Although different configurations of mixers and voices can be used, in most cases a single mixer attached to a voice is what you want. The default mixer is used by al_play_sample. See also: al_reserve_samples, al_play_sample, al_set_default_mixer, al_restore_default_mixer al_set_default_mixer
Sets the default mixer. All samples started with al_play_sample will be stopped. If you are using your own mixer, this should be called before al_reserve_samples. Returns true on success, false on error. See also: al_reserve_samples, al_play_sample, al_get_default_mixer, al_restore_default_mixer al_restore_default_mixer
Restores Allegro's default mixer. All samples started with al_play_sample will be stopped. Returns true on success, false on error. See also: al_get_default_mixer, al_set_default_mixer, al_reserve_samples. al_attach_mixer_to_mixer
Attaches a mixer onto another mixer. The same rules as with al_attach_sample_instance_to_mixer apply, with the added caveat that both mixers must be the same frequency. Returns true on success, false on error. Currently both mixers must have the same audio depth, otherwise the function fails. See also: al_detach_mixer. al_attach_sample_instance_to_mixer
Attach a sample instance to a mixer. The instance must not already be attached to anything. Returns true on success, false on failure. See also: al_detach_sample_instance. al_attach_audio_stream_to_mixer
Attach a stream to a mixer. Returns true on success, false on failure. See also: al_detach_audio_stream. al_get_mixer_frequency
Return the mixer frequency. al_set_mixer_frequency
Set the mixer frequency. This will only work if the mixer is not attached to anything. Returns true on success, false on failure. al_get_mixer_channels
Return the mixer channel configuration. See also: ALLEGRO_CHANNEL_CONF. al_get_mixer_depth
Return the mixer audio depth. See also: ALLEGRO_AUDIO_DEPTH. al_get_mixer_quality
Return the mixer quality. See also: ALLEGRO_MIXER_QUALITY. al_set_mixer_quality
Set the mixer quality. This can only succeed if the mixer does not have anything attached to it. Returns true on success, false on failure. See also: ALLEGRO_MIXER_QUALITY. al_get_mixer_playing
Return true if the mixer is playing. See also: al_set_mixer_playing. al_set_mixer_playing
Change whether the mixer is playing. Returns true on success, false on failure. See also: al_get_mixer_playing. al_get_mixer_attached
Return true if the mixer is attached to something. See also: al_attach_sample_instance_to_mixer, al_attach_audio_stream_to_mixer, al_attach_mixer_to_mixer al_detach_mixer
Detach the mixer from whatever it is attached to, if anything. See also: al_attach_mixer_to_mixer. al_set_mixer_postprocess_callback
Sets a post-processing filter function that's called after the attached streams have been mixed. The buffer's format will be whatever the mixer was created with. The sample count and user-data pointer is also passed. Stream functionsal_create_audio_stream
Creates an ALLEGRO_AUDIO_STREAM. The stream will be set to play by default. It will feed audio data from a buffer, which is split into a number of fragments. Parameters:
The choice of fragment_count, samples and freq directly influences the audio delay. The delay in seconds can be expressed as:
This is only the delay due to Allegro's streaming, there may be additional delay caused by sound drivers and/or hardware. Note: If you know the fragment size in bytes, you can get the size in samples like this:
The size of the complete buffer is:
Note: unlike many Allegro objects, audio streams are not implicitly destroyed when Allegro is shut down. You must destroy them manually with al_destroy_audio_stream before the audio system is shut down. al_destroy_audio_stream
Destroy an audio stream which was created with al_create_audio_stream or al_load_audio_stream. Note: If the stream is still attached to a mixer or voice, al_detach_audio_stream is automatically called on it first. See also: al_drain_audio_stream. al_get_audio_stream_event_source
Retrieve the associated event source. See al_get_audio_stream_fragment for a description of the ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event that audio streams emit. al_drain_audio_stream
You should call this to finalise an audio stream that you will no longer be feeding, to wait for all pending buffers to finish playing. The stream's playing state will change to false. al_rewind_audio_stream
Set the streaming file playing position to the beginning. Returns true on success. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions. al_get_audio_stream_frequency
Return the stream frequency. al_get_audio_stream_channels
Return the stream channel configuration. See also: ALLEGRO_CHANNEL_CONF. al_get_audio_stream_depth
Return the stream audio depth. See also: ALLEGRO_AUDIO_DEPTH. al_get_audio_stream_length
Return the stream length in samples. al_get_audio_stream_speed
Return the playback speed. See also: al_set_audio_stream_speed. al_set_audio_stream_speed
Set the playback speed. Return true on success, false on failure. Will fail if the sample instance is attached directly to a voice. See also: al_get_audio_stream_speed. al_get_audio_stream_gain
Return the playback gain. See also: al_set_audio_stream_gain. al_set_audio_stream_gain
Set the playback gain. Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice. See also: al_get_audio_stream_gain. al_get_audio_stream_pan
Get the pan value. See also: al_set_audio_stream_pan. al_set_audio_stream_pan
Set the pan value on a sample instance. A value of -1.0 means to play the sample only through the left speaker; +1.0 means only through the right speaker; 0.0 means the sample is centre balanced. Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice. See also: al_get_audio_stream_playing. al_get_audio_stream_playing
Return true if the stream is playing. See also: al_set_audio_stream_playing. al_set_audio_stream_playing
Change whether the stream is playing. Returns true on success, false on failure. al_get_audio_stream_playmode
Return the playback mode. See also: ALLEGRO_PLAYMODE, al_set_audio_stream_playmode. al_set_audio_stream_playmode
Set the playback mode. Returns true on success, false on failure. See also: ALLEGRO_PLAYMODE, al_get_audio_stream_playmode. al_get_audio_stream_attached
Return whether the stream is attached to something. See also: al_attach_audio_stream_to_mixer, al_attach_audio_stream_to_voice, al_detach_audio_stream. al_detach_audio_stream
Detach the stream from whatever it's attached to, if anything. See also: al_attach_audio_stream_to_mixer, al_attach_audio_stream_to_voice, al_get_audio_stream_attached. al_get_audio_stream_fragment
When using Allegro's audio streaming, you will use this function to continuously provide new sample data to a stream. If the stream is ready for new data, the function will return the address of an internal buffer to be filled with audio data. The length and format of the buffer are specified with al_create_audio_stream or can be queried with the various functions described here. Once the buffer is filled, you must signal this to Allegro by passing the buffer to al_set_audio_stream_fragment. If the stream is not ready for new data, the function will return NULL. Note: If you listen to events from the stream, an ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event will be generated whenever a new fragment is ready. However, getting an event is not a guarantee that al_get_audio_stream_fragment will not return NULL, so you still must check for it. See also: al_set_audio_stream_fragment, al_get_audio_stream_event_source, al_get_audio_stream_frequency, al_get_audio_stream_channels, al_get_audio_stream_depth, al_get_audio_stream_length al_set_audio_stream_fragment
This function needs to be called for every successful call of al_get_audio_stream_fragment to indicate that the buffer is filled with new data. al_get_audio_stream_fragments
Returns the number of fragments this stream uses. This is the same value as passed to al_create_audio_stream when a new stream is created. al_get_available_audio_stream_fragments
Returns the number of available fragments in the stream, that is, fragments which are not currently filled with data for playback. See also: al_get_audio_stream_fragment al_seek_audio_stream_secs
Set the streaming file playing position to time. Returns true on success. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions. al_get_audio_stream_position_secs
Return the position of the stream in seconds. Currently this can only be called on streams created with al_load_audio_stream. al_get_audio_stream_length_secs
Return the length of the stream in seconds, if known. Otherwise returns zero. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions. al_set_audio_stream_loop_secs
Sets the loop points for the stream in seconds. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions. Audio file I/Oal_register_sample_loader
Register a handler for al_load_sample. The given function will be used to handle the loading of sample files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_register_sample_loader_f
Register a handler for al_load_sample_f. The given function will be used to handle the loading of sample files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_register_sample_saver
Register a handler for al_save_sample. The given function will be used to handle the saving of sample files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_register_sample_saver_f
Register a handler for al_save_sample_f. The given function will be used to handle the saving of sample files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_register_audio_stream_loader
Register a handler for al_load_audio_stream. The given function will be used to open streams from files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_register_audio_stream_loader_f
Register a handler for al_load_audio_stream_f. The given function will be used to open streams from files with the given extension. The extension should include the leading dot ('.') character. It will be matched case-insensitively. The Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist. al_load_sample
Loads a few different audio file formats based on their extension. Some formats require external libraries to be installed prior to compiling the library. 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. Returns the sample on success, NULL on failure. See also: al_register_sample_loader al_load_sample_f
Loads an audio file from an ALLEGRO_FILE stream into an ALLEGRO_SAMPLE. The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot. 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_f. Returns the sample on success, NULL on failure. The file remains open afterwards. See also: al_register_sample_loader_f al_load_audio_stream
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. A stream must be attached to a voice to be used. See ALLEGRO_AUDIO_STREAM for more details. Returns the stream on success, NULL on failure. See also: al_register_audio_stream_loader al_load_audio_stream_f
Loads an audio file from ALLEGRO_FILE stream 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 file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot. A stream must be attached to a voice to be used. See ALLEGRO_AUDIO_STREAM for more details. Returns the stream on success, NULL on failure. On success the file should be considered owned by the audio stream, and will be closed when the audio stream is destroyed. On failure the file will be closed. See also: al_register_audio_stream_loader_f al_save_sample
Writes a sample into a file. Currently, wav is the only supported format, and the extension must be '.wav'. Returns true on success, false on error. See also: al_register_sample_saver al_save_sample_f
Writes a sample into a ALLEGRO_FILE filestream. Currently, wav is the only supported format, and the extension must be '.wav'. Returns true on success, false on error. The file remains open afterwards. See also: al_register_sample_saver_f |
Last updated: 2010-05-26 10:53:34 UTC