ALmixer.h

Go to the documentation of this file.

/*
    ALmixer:  A library to make playing pre-loaded sounds and streams easier
        with high performance and potential access to OpenAL effects.
    Copyright 2002, 2010 Eric Wing <ewing . public @ playcontrol.net>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

*/


#ifndef _SDL_ALMIXER_H_
#define _SDL_ALMIXER_H_


#ifndef DOXYGEN_SHOULD_IGNORE_THIS

/* Note: For Doxygen to produce clean output, you should set the 
 * PREDEFINED option to remove ALMIXER_DECLSPEC, ALMIXER_CALL, and
 * the DOXYGEN_SHOULD_IGNORE_THIS blocks.
 * PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 ALMIXER_DECLSPEC= ALMIXER_CALL=
 */
        #if defined(_WIN32)
                #if defined(ALMIXER_BUILD_LIBRARY)
                        #define ALMIXER_DECLSPEC __declspec(dllexport)
                #else
                        #define ALMIXER_DECLSPEC
                #endif
        #else
                #if defined(ALMIXER_BUILD_LIBRARY)
                        #if defined (__GNUC__) && __GNUC__ >= 4
                                #define ALMIXER_DECLSPEC __attribute__((visibility("default")))
                        #else
                                #define ALMIXER_DECLSPEC
                        #endif
                #else
                        #define ALMIXER_DECLSPEC
                #endif
        #endif

        #if defined(_WIN32)
                #define ALMIXER_CALL __cdecl
        #else
                #define ALMIXER_CALL
        #endif

#endif /* DOXYGEN_SHOULD_IGNORE_THIS */



/* Needed for OpenAL types since altypes.h was removed in 1.1 */
#include "al.h"

/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif

typedef struct ALmixer_version
{
        ALubyte major;
        ALubyte minor;
        ALubyte patch;
} ALmixer_version;


/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
 */
#define ALMIXER_MAJOR_VERSION           0
#define ALMIXER_MINOR_VERSION           5
#define ALMIXER_PATCHLEVEL                      0


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

extern ALMIXER_DECLSPEC const ALmixer_version* ALMIXER_CALL ALmixer_GetLinkedVersion(void);

extern ALMIXER_DECLSPEC const char* ALMIXER_CALL ALmixer_GetError(void);
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SetError(const char *fmt, ...);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_GetTicks(void);
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_Delay(ALuint milliseconds_delay);


struct ALmixer_RWops;

#define ALMIXER_DEFAULT_FREQUENCY       0
#define ALMIXER_DEFAULT_REFRESH         0
/* Most of the old sound Windows sound cards that had 16 max are gone. 32 is the current limit on iOS. */
#define ALMIXER_DEFAULT_NUM_CHANNELS    32
#define ALMIXER_DEFAULT_NUM_SOURCES             ALMIXER_DEFAULT_NUM_CHANNELS

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_Init(ALuint playback_frequency, ALuint num_sources, ALuint refresh_rate);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_InitContext(ALuint playback_frequency, ALuint refresh_rate);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_InitMixer(ALuint num_sources);

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_BeginInterruption(void);

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_EndInterruption(void);

extern ALMIXER_DECLSPEC ALboolean ALmixer_IsInInterruption(void);


extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SuspendUpdates(void);

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_ResumeUpdates(void);

extern ALMIXER_DECLSPEC ALboolean ALmixer_AreUpdatesSuspended(void);


extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_SuspendPlayingState(void);

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_ResumePlayingState(void);

extern ALMIXER_DECLSPEC ALboolean ALmixer_IsPlayingStateSuspended(void);

        
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_Quit(void);
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_QuitWithoutFreeData(void);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_IsInitialized(void);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_GetFrequency(void);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_AllocateChannels(ALint num_chans);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ReserveChannels(ALint number_of_reserve_channels);


extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_Update(void);

/*
#define ALmixer_AudioInfo       Sound_AudioInfo
*/

/*
#define ALMIXER_DEFAULT_BUFFERSIZE 32768
#define ALMIXER_DEFAULT_BUFFERSIZE 16384 
*/
#define ALMIXER_DEFAULT_BUFFERSIZE 16384

/* You probably never need to use these macros directly. */
#ifndef ALMIXER_DISABLE_PREDECODED_PRECOMPUTE_BUFFER_SIZE_OPTIMIZATION
        #define ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE ALMIXER_DEFAULT_BUFFERSIZE * 4
#else
        /* I'm picking a smaller buffer because ALmixer will try to create a new larger buffer
         * based on the length of the audio. So creating a large block up-front might just be a waste.
         * However, if my attempts fail for some reason, this buffer size becomes a fallback.
         * Having too small of a buffer might cause performance bottlenecks.
         */
        #define ALMIXER_DEFAULT_PREDECODED_BUFFERSIZE 4096
#endif

/*
#define ALMIXER_DEFAULT_QUEUE_BUFFERS 5
*/
#define ALMIXER_DEFAULT_QUEUE_BUFFERS 12

#define ALMIXER_DEFAULT_STARTUP_BUFFERS 4
/*
#define ALMIXER_DEFAULT_STARTUP_BUFFERS 2 
*/
#define ALMIXER_DEFAULT_BUFFERS_TO_QUEUE_PER_UPDATE_PASS 2

/*
#define ALMIXER_DECODE_STREAM   0
#define ALMIXER_DECODE_ALL              1
*/

/* This is a trick I picked up from Lua. Doing the typedef separately 
* (and I guess before the definition) instead of a single 
* entry: typedef struct {...} YourName; seems to allow me
* to use forward declarations. Doing it the other way (like SDL)
* seems to prevent me from using forward declarions as I get conflicting
* definition errors. I don't really understand why though.
*/
typedef struct ALmixer_Data ALmixer_Data;
typedef struct ALmixer_AudioInfo ALmixer_AudioInfo;

struct ALmixer_AudioInfo
{
        ALushort format;  
        ALubyte channels; 
        ALuint rate;    
};



extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL ALmixer_LoadAll_RW(struct ALmixer_RWops* rw_ops, const char* file_ext, ALuint access_data);

extern ALMIXER_DECLSPEC ALmixer_Data * ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL ALmixer_LoadAll(const char* file_name, ALuint access_data);

extern ALMIXER_DECLSPEC ALmixer_Data * ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL ALmixer_LoadAll_RAW_RW(struct ALmixer_RWops* rw_ops, const char* file_ext, ALmixer_AudioInfo* desired_format, ALuint access_data);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALmixer_Data* ALMIXER_CALL ALmixer_LoadAll_RAW(const char* file_name, ALmixer_AudioInfo* desired_format, ALuint access_data);

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_FreeData(ALmixer_Data* almixer_data);


extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_IsPredecoded(ALmixer_Data* almixer_data);

extern ALMIXER_DECLSPEC void ALMIXER_CALL 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);

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


extern ALMIXER_DECLSPEC void ALMIXER_CALL 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);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_GetTotalTime(ALmixer_Data* almixer_data);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_GetSource(ALint which_channel);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_GetChannel(ALuint al_source);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FindFreeChannel(ALint start_channel);



extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PlayChannelTimed(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALint number_of_milliseconds);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PlayChannel(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops);


extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_PlaySourceTimed(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALint number_of_milliseconds);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_PlaySource(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_HaltChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_HaltSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_RewindData(ALmixer_Data* almixer_data);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_RewindChannel(ALint which_channel);
extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_RewindSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SeekData(ALmixer_Data* almixer_data, ALuint msec_pos);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_SeekChannel(ALint which_channel, ALuint msec_pos);
extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_SeekSource(ALuint al_source, ALuint msec_pos);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PauseChannel(ALint which_channel);
extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_PauseSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ResumeChannel(ALint which_channel);

 extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ResumeSource(ALuint al_source);

 
extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ExpireChannel(ALint which_channel, ALint number_of_milliseconds);
extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_ExpireSource(ALuint al_source, ALint number_of_milliseconds);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeInChannelTimed(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeInChannel(ALint which_channel, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_FadeInSourceTimed(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks, ALint expire_ticks);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_FadeInSource(ALuint al_source, ALmixer_Data* almixer_data, ALint number_of_loops, ALuint fade_ticks);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeOutChannel(ALint which_channel, ALuint fade_ticks);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeOutSource(ALuint al_source, ALuint fade_ticks);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeChannel(ALint which_channel, ALuint fade_ticks, ALfloat volume);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_FadeSource(ALuint al_source, ALuint fade_ticks, ALfloat volume);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetVolumeChannel(ALint which_channel, ALfloat volume);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetVolumeSource(ALuint al_source, ALfloat volume);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetVolumeChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetVolumeSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMaxVolumeChannel(ALint which_channel, ALfloat volume);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMaxVolumeSource(ALuint al_source, ALfloat volume);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMaxVolumeChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMaxVolumeSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMinVolumeChannel(ALint which_channel, ALfloat volume);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMinVolumeSource(ALuint al_source, ALfloat volume);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMinVolumeChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMinVolumeSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_SetMasterVolume(ALfloat new_volume);

 extern ALMIXER_DECLSPEC ALfloat ALMIXER_CALL ALmixer_GetMasterVolume(void);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsActiveChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsActiveSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPlayingChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPlayingSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPausedChannel(ALint which_channel);

extern ALMIXER_DECLSPEC ALint ALMIXER_CALL ALmixer_IsPausedSource(ALuint al_source);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountAllFreeChannels(void);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountUnreservedFreeChannels(void);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountAllUsedChannels(void);

extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountUnreservedUsedChannels(void);


extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountTotalChannels(void);




extern ALMIXER_DECLSPEC ALuint ALMIXER_CALL ALmixer_CountReservedChannels(void);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_IsDecoderAvailable(const char* usr_ext);

/* For testing */
#if 0
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputAttributes(void);
#endif

extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputDecoders(void);
extern ALMIXER_DECLSPEC void ALMIXER_CALL ALmixer_OutputOpenALInfo(void);

extern ALMIXER_DECLSPEC ALboolean ALMIXER_CALL ALmixer_CompiledWithThreadBackend(void);

#if 0
extern ALMIXER_DECLSPEC size_t ALMIXER_CALL ALmixer_GetCurrentThreadID(void);

#define ALMIXER_THREAD_TYPE_ORIGINATING 1
#define ALMIXER_THREAD_TYPE_UPDATE 2

extern ALMIXER_DECLSPEC size_t ALMIXER_CALL ALmixer_GetThreadIDForType(int almixer_thread_type);
#endif
        
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif


#endif /* _SDL_ALMIXER_H_ */

/* end of SDL_ALmixer.h ... */