Functions for setting up and using ALmixer. More...

Macros
#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

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

Detailed Description

Functions for setting up and using ALmixer.

Macro Definition Documentation

◆ ALMIXER_DEFAULT_FREQUENCY

#define ALMIXER_DEFAULT_FREQUENCY 0

◆ ALMIXER_DEFAULT_NUM_CHANNELS

#define ALMIXER_DEFAULT_NUM_CHANNELS 32

◆ ALMIXER_DEFAULT_NUM_SOURCES

#define ALMIXER_DEFAULT_NUM_SOURCES ALMIXER_DEFAULT_NUM_CHANNELS

◆ ALMIXER_DEFAULT_REFRESH

#define ALMIXER_DEFAULT_REFRESH 0

◆ ALMIXER_GET_COMPILED_VERSION

#define ALMIXER_GET_COMPILED_VERSION ( X )

Value:

{                                                                       \
                (X)->major = ALMIXER_MAJOR_VERSION;                          \
                (X)->minor = ALMIXER_MINOR_VERSION;                          \
                (X)->patch = ALMIXER_PATCHLEVEL;                             \
        }

This macro fills in a version structure with the version of the library you compiled against.

This is determined by what header the compiler uses. Note that if you dynamically linked the library, you might have a slightly newer or older version at runtime. That version can be determined with ALmixer_GetLinkedVersion(), which, unlike ALMIXER_GET_COMPILED_VERSION, is not a macro.

Note: When compiled with SDL, this macro can be used to fill a version structure compatible with SDL_version.

Parameters

X	A pointer to a ALmixer_version struct to initialize.

See also: ALmixer_version, ALmixer_GetLinkedVersion

Function Documentation

◆ ALmixer_AllocateChannels()

ALint ALmixer_AllocateChannels ( ALint num_chans )

Let's you change the maximum number of channels/sources available.

This function is not heavily tested. It is probably better to simply initialize ALmixer with the number of sources you want when you initialize it instead of dynamically changing it later.

◆ ALmixer_AreUpdatesSuspended()

ALboolean ALmixer_AreUpdatesSuspended ( void )

(EXPERIMENTAL) Call to determine if in ALmixer_SuspendUpdates().

(ENABLE_ALMIXER_THREADS only.)

See also: ALmixer_SuspendUpdates, ALmixer_ResumeUpdates

◆ ALmixer_BeginInterruption()

void ALmixer_BeginInterruption ( void )

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

(EXPERIMENTAL) For devices like iOS that need special handling for interruption events like phone calls and alarms, this function will do the correct platform correct thing to handle the interruption w.r.t. OpenAL. This function will suspend and save all current playing state (so it can be resumed), tear down the background update thread (to avoid wasting CPU if background operations are permitted) and set the current OpenAL context to NULL. While this was intended for iOS interruptions, this function works well on all platforms and can be used as a universal suspend/resume. A weaker form that does not tear down the update thread nor set the OpenAL context to NULL can be found in ALmixer_SuspendPlayingState. This calls ALmixer_SuspendUpdates() and ALmixer_SuspendPlayingState().

See also: ALmixer_SuspendUpdates, ALmixer_SuspendPlayingState, ALmixer_EndInterruption, ALmixer_IsInInterruption

◆ ALmixer_Delay()

void ALmixer_Delay ( ALuint milliseconds_delay )

◆ ALmixer_EndInterruption()

void ALmixer_EndInterruption ( void )

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

(EXPERIMENTAL) For devices like iOS that need special handling for interruption events like phone calls and alarms, this function will do the correct platform correct thing to resume from the interruption w.r.t. OpenAL. This calls ALmixer_ResumePlayingState() and ALmixer_ResumeUpdates().

See also: ALmixer_ResumeUpdates, ALmixer_ResumePlayingState, ALmixer_BeginInterruption, ALmixer_IsInInterruption

◆ ALmixer_GetError()

const char* ALmixer_GetError ( void )

Gets the last error string that was set by the system and clears the error.

Note: When compiled with SDL, this directly uses SDL_GetError.

Returns: Returns a string containing the last error or "" when no error is set.

◆ ALmixer_GetFrequency()

ALuint ALmixer_GetFrequency ( void )

Returns the frequency that OpenAL is set to.

Note: This function is not guaranteed to give correct information and is OpenAL implementation dependent.

Returns: Returns the frequency, e.g. 44100.

◆ ALmixer_GetLinkedVersion()

const ALmixer_version* ALmixer_GetLinkedVersion ( void )

Gets the library version of the dynamically linked ALmixer you are using.

This gets the version of ALmixer that is linked against your program. If you are using a shared library (DLL) version of ALmixer, then it is possible that it will be different than the version you compiled against.

This is a real function; the macro ALMIXER_GET_COMPILED_VERSION tells you what version of tErrorLib you compiled against:

ALmixer_version compiled;
ALmixer_version linked;
ALMIXER_GET_COMPILED_VERSION(&compiled);
ALmixer_GetLinkedVersion(&linked);
printf("We compiled against tError version %d.%d.%d ...\n",
          compiled.major, compiled.minor, compiled.patch);
printf("But we linked against tError version %d.%d.%d.\n",
          linked.major, linked.minor, linked.patch);

See also: ALmixer_version, ALMIXER_GET_COMPILED_VERSION

◆ ALmixer_GetTicks()

ALuint ALmixer_GetTicks ( void )

◆ ALmixer_Init()

ALboolean ALmixer_Init	(	ALuint	playback_frequency,
		ALuint	num_sources,
		ALuint	refresh_rate
	)

This is the recommended Init function.

This will initialize the context, SDL_sound, and the mixer system. You should call this in the setup of your code, after SDL_Init. If you attempt to bypass this function, you do so at your own risk.

Note: ALmixer expects the SDL audio subsystem to be disabled. In some cases, an enabled SDL audio subsystem will interfere and cause problems in your app. This Init method explicitly disables the SDL subsystem if SDL is compiled in.; The maximum number of sources is OpenAL implementation dependent. Currently 16 is lowest common denominator for all OpenAL implementations in current use. 32 is currently the second lowest common denominator. If you try to allocate more sources than are actually available, this function may return false depending if the OpenAL implementation returns an error or not. It is possible for OpenAL to silently fail so be very careful about picking too many sources.

Parameters

playback_frequency	The sample rate you want OpenAL to play at, e.g. 44100 Note that OpenAL is not required to actually respect this value. Pass in 0 or ALMIXER_DEFAULT_FREQUENCY to specify you want to use your implementation's default value.
num_sources	The number of OpenAL sources (also can be thought of as SDL_mixer channels) you wish to allocate. Pass in 0 or ALMIXER_DEFAULT_NUM_SOURCES to use ALmixer's default value.
refresh_rate	The refresh rate you want OpenAL to operate at. Note that OpenAL is not required to respect this value. Pass in 0 or ALMIXER_DEFAULT_REFRESH to use OpenAL default behaviors.

Returns: Returns AL_FALSE on a failure or AL_TRUE if successfully initialized.

◆ ALmixer_InitContext()

ALboolean ALmixer_InitContext	(	ALuint	playback_frequency,
		ALuint	refresh_rate
	)

InitContext will only initialize the OpenAL context (and not the mixer part).

Note that SDL_Sound is also initialized here because load order matters because SDL audio will conflict with OpenAL when using SMPEG. This is only provided as a backdoor and is not recommended.

Note: This is a backdoor in case you need to initialize the AL context and the mixer system separately. I strongly recommend avoiding these two functions and use the normal Init() function.

◆ ALmixer_InitMixer()

ALboolean ALmixer_InitMixer ( ALuint num_sources )

InitMixer will only initialize the Mixer system.

This is provided in the case that you need control over the loading of the context. You may load the context yourself, and then call this function. This is not recommended practice, but is provided as a backdoor in case you have good reason to do this. Be warned that if ALmixer_InitMixer() fails, it will not clean up the AL context. Also be warned that Quit() still does try to clean up everything.

Note: This is a backdoor in case you need to initialize the AL context and the mixer system separately. I strongly recommend avoiding these two functions and use the normal Init() function.

◆ ALmixer_IsInInterruption()

ALboolean ALmixer_IsInInterruption ( void )

(EXPERIMENTAL) Call to determine if in an interruption.

(EXPERIMENTAL) For devices like iOS that need special handling for interruption events like phone calls and alarms, this function will do the correct platform correct thing to determine if in an interruption.

See also: ALmixer_BeginInterruption, ALmixer_EndInterruption

◆ ALmixer_IsInitialized()

ALboolean ALmixer_IsInitialized ( void )

Returns whether ALmixer has been initializatized (via Init) or not.

Returns: Returns true for initialized and false for not initialized.

◆ ALmixer_IsPlayingStateSuspended()

ALboolean ALmixer_IsPlayingStateSuspended ( void )

(EXPERIMENTAL) Call to determine if in ALmixer_SuspendPlayingState().

See also: ALmixer_SuspendPlayingState, ALmixer_ResumePlayingState.

◆ ALmixer_Quit()

void ALmixer_Quit ( void )

This shuts down ALmixer.

Please remember to free your ALmixer_Data* instances before calling this method.

◆ ALmixer_QuitWithoutFreeData()

void ALmixer_QuitWithoutFreeData ( void )

HACK to shutdown ALmixer without freeing ALmixer_Data.

This is a lame hack to get around a really complicated problem relating to: 1) Android doesn't run the reinitialization of static variables to NULL at the top of this program. 2) When dealing with a garbage collected environment, if Quit() is called before the GC environment collects, dangling pointers will be passed to FreeData() 3) We are client of somebody else's environment and can't ensure Quit() is called after the GC environment is clean. 4) Android atexit() doesn't seem to actually trigger anything. This will clean up as much as possible. The linked list of data will be left alive and it will dangle after the program quits. Fortunately ALmixer doesn't null check the linked list and always recreates it on Init(). Calling alBufferData after the OpenAL context is dead may cause problems depending on implementations.

◆ ALmixer_ReserveChannels()

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.

This function will effectively block off a certain number of channels so they won't be automatically assigned to be played on when you call various play functions (applies to both play-channel and play-source functions since they are the same under the hood). The lowest number channels will always be blocked off first. For example, if there are 16 channels available, and you pass 2 into this function, channels 0 and 1 will be reserved so they won't be played on automatically when you specify you want to play a sound on any available channel/source. You can still play on channels 0 and 1 if you explicitly designate you want to play on their channel number or source id. Setting back to 0 will clear all the reserved channels so all will be available again for auto-assignment. As an example, this feature can be useful if you always want your music to be on channel 0 and speech on channel 1 and you don't want sound effects to ever occupy those channels. This allows you to build in certain assumptions about your code, perhaps for deciding which data you want to analyze in a data callback. Specifying the number of reserve channels to the maximum number of channels will effectively disable auto-assignment.

Parameters

number_of_reserve_channels The number of channels/sources to reserve. Or pass -1 to find out how many channels are currently reserved.

Returns: Returns the number of currently reserved channels.

◆ ALmixer_ResumePlayingState()

void ALmixer_ResumePlayingState ( void )

(EXPERIMENTAL) Resumes all paused channels triggered by ALmixer_SuspendPlayingState.

(EXPERIMENTAL) This will resume all channels that were playing at the time of the call to ALmixer_SuspendPlayingState. The primary motivation for this function was to better handle BeginInterruption by saving the playing state so it could be restored on EndInterruption. You don't necessarily want to resume all channels, because some channels may be paused already and you don't want those to automatically resume. This function does those extra checks and book keeping. If you call EndInterruption, you don't need to call this because it calls this on your behalf.

See also: ALmixer_SuspendPlayingState, ALmixer_IsPlayingStateSuspended.

◆ ALmixer_ResumeUpdates()

void ALmixer_ResumeUpdates ( void )

(EXPERIMENTAL) Recreates the background update thread (ENABLE_ALMIXER_THREADS only).

(EXPERIMENTAL) Recreates the background update thread (ENABLE_ALMIXER_THREADS only). EndInterruption used to do this internally, but this was split off due to an iOS OpenAL race condition bug (10081775). Being able to manipulate the thread without manipulating the context was useful for suspend/resume backgrounding when not dealing with a full-blown interruption event.

See also: ALmixer_SuspendUpdates, ALmixer_AreUpdatesSuspended

◆ ALmixer_SetError()

void ALmixer_SetError	(	const char *	fmt,
			...
	)

Sets an error string that can be retrieved by ALmixer_GetError.

Note: When compiled with SDL, this directly uses SDL_SetError.

param The error string to set.

◆ ALmixer_SuspendPlayingState()

void ALmixer_SuspendPlayingState ( void )

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

(EXPERIMENTAL) This will traverse through all currently playing channels, privately mark them as playing, and pause them. The primary motivation for this function was to better handle BeginInterruption by saving the playing state so it could be restored on EndInterruption. You don't necessarily want to resume all channels, because some channels may be paused already and you don't want those to automatically resume. This function does those extra checks and book keeping. If you call BeginInterruption, you don't need to call this because it calls this on your behalf. There is an implicit assumption that you will not attempt any playing or channel manipulation until you call ALmixer_ResumePlayingState. If you want to quickly pause all audio and then later quickly resume all audio, this is a convenient and fast function to use as it does not tear down background threads nor disable the OpenAL context.

See also: ALmixer_ResumePlayingState, ALmixer_IsPlayingStateSuspended.

◆ ALmixer_SuspendUpdates()

void ALmixer_SuspendUpdates ( void )

(EXPERIMENTAL) Destroys the background update thread (ENABLE_ALMIXER_THREADS only).

(EXPERIMENTAL) Destroys the background update thread (ENABLE_ALMIXER_THREADS only). BeginInterruption used to do this internally, but this was split off due to an iOS OpenAL race condition bug (10081775). Being able to manipulate the thread without manipulating the context was useful for suspend/resume backgrounding when not dealing with a full-blown interruption event.

See also: ALmixer_ResumeUpdates, ALmixer_AreUpdatesSuspended

◆ ALmixer_Update()

ALint ALmixer_Update ( void )

The update function that allows ALmixer to update its internal state.

If not compiled with/using threads, this function must be periodically called to poll ALmixer to force streamed music and other events to take place. The typical place to put this function is in your main-loop. If threads are enabled, then this function just returns 0 and is effectively a no-op. With threads, it is not necessary to call this function because updates are handled internally on another thread. However, because threads are still considered experimental, it is recommended you call this function in a proper place in your code in case future versions of this library need to abandon threads.

Returns: Returns 0 if using threads. If not using threads, for debugging purposes, it returns the number of buffers queued during the loop, or a negative value indicating the numer of errors encountered. This is subject to change and should not be relied on.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ALMIXER_DEFAULT_FREQUENCY

◆ ALMIXER_DEFAULT_NUM_CHANNELS

◆ ALMIXER_DEFAULT_NUM_SOURCES

◆ ALMIXER_DEFAULT_REFRESH

◆ ALMIXER_GET_COMPILED_VERSION

Function Documentation

◆ ALmixer_AllocateChannels()

◆ ALmixer_AreUpdatesSuspended()

◆ ALmixer_BeginInterruption()

◆ ALmixer_Delay()

◆ ALmixer_EndInterruption()

◆ ALmixer_GetError()

◆ ALmixer_GetFrequency()

◆ ALmixer_GetLinkedVersion()

◆ ALmixer_GetTicks()

◆ ALmixer_Init()

◆ ALmixer_InitContext()

◆ ALmixer_InitMixer()

◆ ALmixer_IsInInterruption()

◆ ALmixer_IsInitialized()

◆ ALmixer_IsPlayingStateSuspended()

◆ ALmixer_Quit()

◆ ALmixer_QuitWithoutFreeData()

◆ ALmixer_ReserveChannels()

◆ ALmixer_ResumePlayingState()

◆ ALmixer_ResumeUpdates()

◆ ALmixer_SetError()

◆ ALmixer_SuspendPlayingState()

◆ ALmixer_SuspendUpdates()

◆ ALmixer_Update()