ALmixer (which I sometimes call "SDL-OpenAL-Mixer" or "SDL_ALmixer") is a cross-platform audio library built on top of OpenAL to make playing and managing sounds easier. More...

#include "al.h"

Data Structures
struct	ALmixer_version
	Struct that contains the version information of this library. More...

struct	ALmixer_AudioInfo
	Roughly the equvialent to the Sound_AudioInfo struct in SDL_sound. More...

Macros
#define	ALMIXER_MAJOR_VERSION 0

#define	ALMIXER_MINOR_VERSION 5

#define	ALMIXER_PATCHLEVEL 0

#define	ALMIXER_GET_COMPILED_VERSION(X)
	This macro fills in a version structure with the version of the library you compiled against. More...

#define	ALMIXER_DEFAULT_FREQUENCY 0

#define	ALMIXER_DEFAULT_REFRESH 0

#define	ALMIXER_DEFAULT_NUM_CHANNELS 32

#define	ALMIXER_DEFAULT_NUM_SOURCES ALMIXER_DEFAULT_NUM_CHANNELS

#define	ALMIXER_DEFAULT_BUFFERSIZE 16384

#define	ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE ALMIXER_DEFAULT_BUFFERSIZE * 4

#define	ALMIXER_DEFAULT_QUEUE_BUFFERS 12
	Specifies the maximum number of queue buffers to use for a sound stream. More...

#define	ALMIXER_DEFAULT_STARTUP_BUFFERS 4
	Specifies the number of queue buffers initially filled when first loading a stream. More...

#define	ALMIXER_DEFAULT_BUFFERS_TO_QUEUE_PER_UPDATE_PASS 2

Typedefs
typedef struct ALmixer_Data	ALmixer_Data

typedef void(*	playback_finished_callback) (ALint which_channel, ALuint al_source, ALmixer_Data almixer_data, ALboolean finished_naturally, void ALmixer_SetPlaybackFinishedCallbackContainer)

Functions
const ALmixer_version *	ALmixer_GetLinkedVersion (void)
	Gets the library version of the dynamically linked ALmixer you are using. More...

const char *	ALmixer_GetError (void)
	Gets the last error string that was set by the system and clears the error. More...

void	ALmixer_SetError (const char *fmt,...)
	Sets an error string that can be retrieved by ALmixer_GetError. More...

ALuint	ALmixer_GetTicks (void)

void	ALmixer_Delay (ALuint milliseconds_delay)

ALboolean	ALmixer_Init (ALuint playback_frequency, ALuint num_sources, ALuint refresh_rate)
	This is the recommended Init function. More...

ALboolean	ALmixer_InitContext (ALuint playback_frequency, ALuint refresh_rate)
	InitContext will only initialize the OpenAL context (and not the mixer part). More...

ALboolean	ALmixer_InitMixer (ALuint num_sources)
	InitMixer will only initialize the Mixer system. More...

void	ALmixer_BeginInterruption (void)
	(EXPERIMENTAL) Call to notify ALmixer that your device needs to handle an interruption. More...

void	ALmixer_EndInterruption (void)
	(EXPERIMENTAL) Call to notify ALmixer that your device needs to resume from an interruption. More...

ALboolean	ALmixer_IsInInterruption (void)
	(EXPERIMENTAL) Call to determine if in an interruption. More...

void	ALmixer_SuspendUpdates (void)
	(EXPERIMENTAL) Destroys the background update thread (ENABLE_ALMIXER_THREADS only). More...

void	ALmixer_ResumeUpdates (void)
	(EXPERIMENTAL) Recreates the background update thread (ENABLE_ALMIXER_THREADS only). More...

ALboolean	ALmixer_AreUpdatesSuspended (void)
	(EXPERIMENTAL) Call to determine if in ALmixer_SuspendUpdates(). More...

void	ALmixer_SuspendPlayingState (void)
	(EXPERIMENTAL) Pauses all currently playing channels with the intent that you will want to resume them later with ALmixer_ResumePlayingState(). More...

void	ALmixer_ResumePlayingState (void)
	(EXPERIMENTAL) Resumes all paused channels triggered by ALmixer_SuspendPlayingState. More...

ALboolean	ALmixer_IsPlayingStateSuspended (void)
	(EXPERIMENTAL) Call to determine if in ALmixer_SuspendPlayingState(). More...

void	ALmixer_Quit (void)
	This shuts down ALmixer. More...

void	ALmixer_QuitWithoutFreeData (void)
	HACK to shutdown ALmixer without freeing ALmixer_Data. More...

ALboolean	ALmixer_IsInitialized (void)
	Returns whether ALmixer has been initializatized (via Init) or not. More...

ALuint	ALmixer_GetFrequency (void)
	Returns the frequency that OpenAL is set to. More...

ALint	ALmixer_AllocateChannels (ALint num_chans)
	Let's you change the maximum number of channels/sources available. More...

ALint	ALmixer_ReserveChannels (ALint number_of_reserve_channels)
	Allows you to reserve a certain number of channels so they won't be automatically allocated to play on. More...

ALint	ALmixer_Update (void)
	The update function that allows ALmixer to update its internal state. More...

ALmixer_Data *	ALmixer_LoadSample_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a general loader function to load an audio resource from an RWops. More...

ALmixer_Data *	ALmixer_LoadStream_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is the loader function to load an audio resource from an RWops as a stream. More...

ALmixer_Data *	ALmixer_LoadAll_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALuint access_data)
	This is the loader function to completely preload an audio resource from an RWops into RAM. More...

ALmixer_Data *	ALmixer_LoadSample (const char *file_name, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a general loader function to load an audio resource from a file. More...

ALmixer_Data *	ALmixer_LoadStream (const char *file_name, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is the loader function to load an audio resource from a file. More...

ALmixer_Data *	ALmixer_LoadAll (const char *file_name, ALuint access_data)
	This is the loader function to completely preload an audio resource from a file into RAM. More...

ALmixer_Data *	ALmixer_LoadSample_RAW_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALmixer_AudioInfo *desired_format, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a back door general loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field. More...

ALmixer_Data *	ALmixer_LoadStream_RAW_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALmixer_AudioInfo *desired_format, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a back door stream loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field. More...

ALmixer_Data *	ALmixer_LoadAll_RAW_RW (struct ALmixer_RWops rw_ops, const char file_ext, ALmixer_AudioInfo *desired_format, ALuint access_data)
	This is a back door loader function for complete preloading RAW samples into RAM or if you need to specify the ALmixer_AudioInfo field. More...

ALmixer_Data *	ALmixer_LoadSample_RAW (const char file_name, ALmixer_AudioInfo desired_format, ALuint buffer_size, ALboolean decode_mode_is_predecoded, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a back door general loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field. More...

ALmixer_Data *	ALmixer_LoadStream_RAW (const char file_name, ALmixer_AudioInfo desired_format, ALuint buffer_size, ALuint max_queue_buffers, ALuint num_startup_buffers, ALuint suggested_number_of_buffers_to_queue_per_update_pass, ALuint access_data)
	This is a back door stream loader function for RAW samples or if you need to specify the ALmixer_AudioInfo field. More...

ALmixer_Data *	ALmixer_LoadAll_RAW (const char file_name, ALmixer_AudioInfo desired_format, ALuint access_data)
	This is a back door loader function for complete preloading RAW samples into RAM or if you need to specify the ALmixer_AudioInfo field. More...

void	ALmixer_FreeData (ALmixer_Data *almixer_data)
	Frees an ALmixer_Data. More...

ALboolean	ALmixer_IsPredecoded (ALmixer_Data *almixer_data)
	Returns true if the almixer_data was completely loaded into memory or false if it was loaded as a stream. More...

void	ALmixer_SetPlaybackFinishedCallback (void(playback_finished_callback)(ALint which_channel, ALuint al_source, ALmixer_Data almixer_data, ALboolean finished_naturally, void user_data), void user_data)
	Allows you to set a callback for when a sound has finished playing on a channel/source. More...

void	ALmixer_SetPlaybackDataCallback (void(playback_data_callback)(ALint which_channel, ALuint al_source, ALbyte pcm_data, ALuint num_bytes, ALuint frequency, ALubyte num_channels_in_sample, ALubyte bit_depth, ALboolean is_unsigned, ALboolean decode_mode_is_predecoded, ALuint length_in_msec, void user_data), void user_data)
	Allows you to set a callback for getting audio data. More...

ALint	ALmixer_GetTotalTime (ALmixer_Data *almixer_data)
	Returns the total time in milliseconds of the audio resource. More...

ALuint	ALmixer_GetSource (ALint which_channel)
	This function will look up the OpenAL source id for the corresponding channel number. More...

ALint	ALmixer_GetChannel (ALuint al_source)
	This function will look up the channel for the corresponding source. More...

ALint	ALmixer_FindFreeChannel (ALint start_channel)
	Will look for a channel available for playback. More...

ALint	ALmixer_PlayChannelTimed (ALint which_channel, ALmixer_Data *almixer_data, ALint number_of_loops, ALint number_of_milliseconds)
	Play a sound on a channel with a time limit. More...

ALint	ALmixer_PlayChannel (ALint which_channel, ALmixer_Data *almixer_data, ALint number_of_loops)
	The same as ALmixer_PlayChannelTimed, but the sound is played without time limits. More...

ALuint	ALmixer_PlaySourceTimed (ALuint al_source, ALmixer_Data *almixer_data, ALint number_of_loops, ALint number_of_milliseconds)
	Play a sound on an OpenAL source with a time limit. More...

ALuint	ALmixer_PlaySource (ALuint al_source, ALmixer_Data *almixer_data, ALint number_of_loops)
	The same as ALmixer_PlaySourceTimed, but the sound is played without time limits. More...

ALint	ALmixer_HaltChannel (ALint which_channel)
	Stops playback on a channel. More...

ALint	ALmixer_HaltSource (ALuint al_source)
	Stops playback on a channel. More...

ALboolean	ALmixer_RewindData (ALmixer_Data *almixer_data)
	Rewinds the sound to the beginning for a given data. More...

ALint	ALmixer_RewindChannel (ALint which_channel)
	Rewinds the sound to the beginning that is playing on a specific channel. More...

ALint	ALmixer_RewindSource (ALuint al_source)
	Rewinds the sound to the beginning that is playing on a specific source. More...

ALboolean	ALmixer_SeekData (ALmixer_Data *almixer_data, ALuint msec_pos)
	Seek the sound for a given data. More...

ALint	ALmixer_SeekChannel (ALint which_channel, ALuint msec_pos)
	Seeks the sound to the beginning that is playing on a specific channel. More...

ALint	ALmixer_SeekSource (ALuint al_source, ALuint msec_pos)
	Seeks the sound to the beginning that is playing on a specific source. More...

ALint	ALmixer_PauseChannel (ALint which_channel)
	Pauses playback on a channel. More...

ALint	ALmixer_PauseSource (ALuint al_source)
	Pauses playback on a source. More...

ALint	ALmixer_ResumeChannel (ALint which_channel)
	Resumes playback on a channel that is paused. More...

ALint	ALmixer_ResumeSource (ALuint al_source)
	Resumes playback on a source that is paused. More...

ALint	ALmixer_ExpireChannel (ALint which_channel, ALint number_of_milliseconds)
	Will cause a currently playing channel to stop playing in the specified number of milliseconds. More...

ALint	ALmixer_ExpireSource (ALuint al_source, ALint number_of_milliseconds)
	Will cause a currently playing source to stop playing in the specified number of milliseconds. More...

ALint	ALmixer_FadeInChannelTimed (ALint which_channel, ALmixer_Data *almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks)
	Similar to ALmixer_PlayChannelTimed except that sound volume fades in from the minimum volume to the current AL_GAIN over the specified amount of time. More...

ALint	ALmixer_FadeInChannel (ALint which_channel, ALmixer_Data *almixer_data, ALint number_of_loops, ALuint fade_ticks)
	The same as ALmixer_FadeInChannelTimed, but the sound is played without time limits. More...

ALuint	ALmixer_FadeInSourceTimed (ALuint al_source, ALmixer_Data *almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks)
	Similar to ALmixer_PlaySourceTimed except that sound volume fades in from the minimum volume to the max volume over the specified amount of time. More...

ALuint	ALmixer_FadeInSource (ALuint al_source, ALmixer_Data *almixer_data, ALint number_of_loops, ALuint fade_ticks)
	The same as ALmixer_FadeInSourceTimed, but the sound is played without time limits. More...

ALint	ALmixer_FadeOutChannel (ALint which_channel, ALuint fade_ticks)
	Fade out a current playing channel. More...

ALint	ALmixer_FadeOutSource (ALuint al_source, ALuint fade_ticks)
	Fade out a current playing source. More...

ALint	ALmixer_FadeChannel (ALint which_channel, ALuint fade_ticks, ALfloat volume)
	Gradually changes the volume from the current AL_GAIN to the specified volume. More...

ALint	ALmixer_FadeSource (ALuint al_source, ALuint fade_ticks, ALfloat volume)
	Gradually changes the volume from the current AL_GAIN to the specified volume. More...

ALboolean	ALmixer_SetVolumeChannel (ALint which_channel, ALfloat volume)
	Sets the volume via the AL_GAIN source property. More...

ALboolean	ALmixer_SetVolumeSource (ALuint al_source, ALfloat volume)
	Sets the volume via the AL_GAIN source property. More...

ALfloat	ALmixer_GetVolumeChannel (ALint which_channel)
	Gets the volume via the AL_GAIN source property. More...

ALfloat	ALmixer_GetVolumeSource (ALuint al_source)
	Gets the volume via the AL_GAIN source property. More...

ALboolean	ALmixer_SetMaxVolumeChannel (ALint which_channel, ALfloat volume)
	Sets the maximum volume via the AL_MAX_GAIN source property. More...

ALboolean	ALmixer_SetMaxVolumeSource (ALuint al_source, ALfloat volume)
	Sets the maximum volume via the AL_MAX_GAIN source property. More...

ALfloat	ALmixer_GetMaxVolumeChannel (ALint which_channel)
	Gets the max volume via the AL_MAX_GAIN source property. More...

ALfloat	ALmixer_GetMaxVolumeSource (ALuint al_source)
	Gets the maximum volume via the AL_MAX_GAIN source property. More...

ALboolean	ALmixer_SetMinVolumeChannel (ALint which_channel, ALfloat volume)
	Sets the minimum volume via the AL_MIN_GAIN source property. More...

ALboolean	ALmixer_SetMinVolumeSource (ALuint al_source, ALfloat volume)
	Sets the minimum volume via the AL_MIN_GAIN source property. More...

ALfloat	ALmixer_GetMinVolumeChannel (ALint which_channel)
	Gets the min volume via the AL_MIN_GAIN source property. More...

ALfloat	ALmixer_GetMinVolumeSource (ALuint al_source)
	Gets the min volume via the AL_MIN_GAIN source property. More...

ALboolean	ALmixer_SetMasterVolume (ALfloat new_volume)
	Sets the OpenAL listener AL_GAIN which can be thought of as the "master volume". More...

ALfloat	ALmixer_GetMasterVolume (void)
	Gets the OpenAL listener AL_GAIN which can be thought of as the "master volume". More...

ALint	ALmixer_IsActiveChannel (ALint which_channel)
	Returns true if the specified channel is currently playing or paused, or if -1 is passed the number of channels that are currently playing or paused. More...

ALint	ALmixer_IsActiveSource (ALuint al_source)
	Returns true if the specified source is currently playing or paused, or if -1 is passed the number of sources that are currently playing or paused. More...

ALint	ALmixer_IsPlayingChannel (ALint which_channel)
	Returns true if the specified channel is currently playing. More...

ALint	ALmixer_IsPlayingSource (ALuint al_source)
	Returns true if the specified sources is currently playing. More...

ALint	ALmixer_IsPausedChannel (ALint which_channel)
	Returns true if the specified channel is currently paused. More...

ALint	ALmixer_IsPausedSource (ALuint al_source)
	Returns true if the specified sources is currently paused. More...

ALuint	ALmixer_CountAllFreeChannels (void)
	Returns the number of channels that are currently available for playback (not playing, not paused). More...

ALuint	ALmixer_CountUnreservedFreeChannels (void)
	Returns the number of channels that are currently available for playback (not playing, not paused), excluding the channels that have been reserved. More...

ALuint	ALmixer_CountAllUsedChannels (void)
	Returns the number of channels that are currently in use (playing/paused). More...

ALuint	ALmixer_CountUnreservedUsedChannels (void)
	Returns the number of channels that are currently in use (playing/paused), excluding the channels that have been reserved. More...

ALuint	ALmixer_CountTotalChannels (void)
	Returns the number of allocated channels. More...

ALuint	ALmixer_CountReservedChannels (void)
	Returns the number of reserved channels. More...

ALboolean	ALmixer_IsDecoderAvailable (const char *usr_ext)
	Returns whether a decoder is available to decode the requested extension. More...

void	ALmixer_OutputDecoders (void)
	This function may be removed in the future. More...

void	ALmixer_OutputOpenALInfo (void)
	This function may be removed in the future. More...

ALboolean	ALmixer_CompiledWithThreadBackend (void)
	This function is experimental. More...

Detailed Description

ALmixer (which I sometimes call "SDL-OpenAL-Mixer" or "SDL_ALmixer") is a cross-platform audio library built on top of OpenAL to make playing and managing sounds easier.

ALmixer provides a simple API inspired by SDL_mixer to make playing sounds easy with having to worry about directly dealing with OpenAL sources, buffers, and buffer queuing directly. ALmixer currently utilizes SDL_sound behind the scenes to decode various audio formats such as WAV, MP3, AAC, MP4, OGG, etc.

This library is targeted towards two major groups:

People who just want an easy, high performance, way to play audio (don't care if its OpenAL or not)
People who want to an easy way to play audio in OpenAL but still want access to OpenAL directly.

ALmixer exposes OpenAL sources in the API so you can freely use ALmixer in larger OpenAL applications that need to apply OpenAL 3D effects and features to playing sounds.

The API is heavily influenced and inspired by SDL_mixer, though there is one major conceptual design difference. ALmixer doesn't divide sound and music playback into two separate play APIs. Instead, there is one unified play API and you specify via the load API whether you want the audio resource loaded as a stream or completely preloaded. This allows you to have any arbitrary number of streaming sources playing simultaneously (such as music and speech) unlike SDL_mixer where you are limited to only one "music" channel.

A less major conceptual design difference is every "Channel" API has a corresponding "Source" API. Every "channel" (in the SDL_mixer definition context) maps to a corresponding OpenAL source id. You can use this source ID directly with OpenAL API commands to utilize OpenAL effects such as position, Doppler, etc. Convenience APIs are provided to let you convert channel numbers to source ids and vice-versa.

Another change which is a pet-peev of mine with SDL_mixer is the lack of a user_data parameter in callbacks. ALmixer callbacks allow you to pass user_data (aka context) pointers through the callback functions.

Note: There are some #defines you can set to change the behavior at compile time. Most you shouldn't touch. The one worth noting is ENABLE_ALMIXER_THREADS. If enabled, ALmixer_Update() is automatically called on a background thread so you no longer have to explicitly call it. (The function turns into a no-op so your existing code won't break.) Having Update run in a separate thread has some advantages, particularly for streaming audio as all the OpenAL buffer queuing happens in this function. It is less likely the background thread will be blocked for long periods and thus less likely your buffer queues will be starved. However, this means you need to be extra careful about what you do in callback functions as they are invoked from the background thread. I still consider this feature a experimental (though I am starting to use it more myself) and there may still be bugs.

Author: Eric Wing

Home Page: http://playcontrol.net/opensource/ALmixer

Macro Definition Documentation

◆ ALMIXER_MAJOR_VERSION

#define ALMIXER_MAJOR_VERSION 0

◆ ALMIXER_MINOR_VERSION

#define ALMIXER_MINOR_VERSION 5

◆ ALMIXER_PATCHLEVEL

#define ALMIXER_PATCHLEVEL 0

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ALMIXER_MAJOR_VERSION

◆ ALMIXER_MINOR_VERSION

◆ ALMIXER_PATCHLEVEL