almixer_isolated: README.txt annotate

annotate README.txt @ 47:9b772c81b550

Added addition query to get the current number of buffers processed in the new inner buffer decoupling loop because I've been seeing a lot of 59TestingError warnings. I think it is possible the value may become stale after the first iteration of the loop resulting in assumption failures which result in triggering this error. Also changed some // comments to /* */ for C89 compliance.

author	Eric Wing <ewing@anscamobile.com>
date	Thu, 29 Sep 2011 11:33:34 -0700
parents	8cb13d89451a
children

rev	line source
3 a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	1 Introduction:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	2
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	3 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	4
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	5 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,
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	6 and buffer queuing directly.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	7
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	8 ALmixer currently utilizes SDL_sound behind the scenes to decode
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	9 various audio formats such as WAV, MP3, AAC, MP4, OGG, etc.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	10
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	11 This library is targeted towards two major groups:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	12
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	13 - People who just want an easy, high performance, way to play audio (don't care if its OpenAL or not)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	14 - People who want to an easy way to play audio in OpenAL but still want access to OpenAL directly.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	15
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	16 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	17
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	18 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	19
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	20 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	21
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	22 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	23
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	24
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	25 SDL_mixer vs. ALmixer:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	26
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	27 Why would you want to use ALmixer over SDL_mixer?
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	28 - There is no artificial limit or distinction between "music" and "sounds". Instead, you specify if you want to preload a sound fully or as a "stream" and the "play" API automatically and transparently does the right thing. This means you can have multiple streaming sounds playing at the same time like music and speech.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	29 - The callback API allows for void* userdata (a.k.a. context) to be passed through.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	30 - Uses OpenAL as the audio engine instead of SDL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	31 - Not subject to known SDL and SDL_mixer bugs/limitations
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	32 - You can utilize OpenAL for additional features and effects.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	33
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	34
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	35 Why would you want to use SDL_mixer over ALmixer?
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	36 - ALmixer is newer, less proven code
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	37 - OpenAL while an industry cross-platform standard, is still not as ubiquitous as SDL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	38 - OpenAL may have a different set of bugs and there are different implementations of OpenAL which may have different bugs.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	39 - SDL_mixer effects are not ported. (You should utilize OpenAL effects instead.)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	40
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	41
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	42
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	43 Compile Flags:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	44
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	45 There are some #defines you can set to change the behavior at compile time. Most you shouldn't touch.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	46
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	47 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
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	48 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	49
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	50
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	51 Building:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	52
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	53 This project uses CMake.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	54 Check out CMake at http://www.cmake.org
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	55 Check out my screencast tutorial at: http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	56
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	57 Typical commandline: (from inside the ALmixer directory)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	58 mkdir BUILD
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	59 cd BUILD
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	60 cmake ..
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	61 make
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	62
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	63 Or use the ccmake or the CMake GUI to make it easier to configure options like ENABLE_ALMIXER_THREADS.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	64
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	65
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	66 Backstory:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	67
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	68 I originally wrote this library back in roughly 2002 to workaround bugs and limitations I was facing with SDL_mixer. I was experiencing latency problems back then with SDL_mixer on certain platforms and I needed the ability to play both music and speech simultaneously which the design of SDL_mixer does not really facilitate. I also needed more decoding formats than SDL_mixer supported, plus at the time, the SDL_mixer backend for music used a different decoding backend than the rest of the library which made it inconsistent.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	69
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	70 The ALmixer code was written very quickly in a matter of several weeks. But in solving all the problems/limitations I had with SDL_mixer, I encountered a whole set of new problems surrounding OpenAL. Back in 2002, OpenAL was on life-support and the 1.0 OpenAL spec was really broken. The differences between implementations of OpenAL differed greatly which made it very difficult to ship a cross-platform application using OpenAL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	71
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	72 Meanwhile, because the code was written so quickly and also happened to be my first venture into audio (among other things), I felt the code was messy and needed to be cleaned up. The complicated state machine necessary to do what I needed turned out to be very scary. In addition, with all the hacks I needed to add to workaround OpenAL implementation differences, made the code much more complicated.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	73
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	74 So rather than releasing to the public, I decided to sit on the code and vowed to clean it up some day so I don't embarrass myself. I also expected that SDL_mixer would be rewritten to use SDL_sound soon and maybe some of my other issues might finally be fixed.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	75
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	76 Many years passed.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	77
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	78 OpenAL 1.1 was ratified and many of the compatibility issues between OpenAL implementations started going away. Every so often, I re-pickup ALmixer and made small changes to update it to support OpenAL 1.1.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	79
5 8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	80 Fast forward to 2010 (today). I still haven't cleaned up ALmixer. SDL_mixer has still not been rewritten. And there haven't been any great audio libraries that have emerged in all these years. Furthermore, with renewed interest in playing high performance audio with OpenAL due to the enormous success of iPhone, iPod touch, and iPad, I see there is a still a great void that needs to be filled. (In fact, I just co-authored possibly the most comprehensive book on OpenAL ever written: http://playcontrol.net/iphonegamebook)
3 a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	81
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	82 And I have recently been working on a project that would benefit greatly from something like ALmixer. I realized that I don't have the time/money to do the clean-up, nor is it feasible for me to do an entire rewrite. I also realize that despite the scariness of the code, the library seems to generally work.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	83
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	84 So I have decided to finally release ALmixer, even without the clean ups. My hope is people find it useful and I also get some good testing feedback. Maybe some heros will even make it better. Please be kind when reading the code and reporting bugs. I admit the code is scary and many of the comments are now obsolete.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	85
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	86
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	87 Eric Wing <ewing . public @ playcontrol.net>
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	88
5 8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	89 ALmixer Home Page: http://playcontrol.net/opensource/ALmixer
8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	90

rev	line source
3 a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	1 Introduction:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	2
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	3 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	4
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	5 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,
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	6 and buffer queuing directly.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	7
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	8 ALmixer currently utilizes SDL_sound behind the scenes to decode
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	9 various audio formats such as WAV, MP3, AAC, MP4, OGG, etc.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	10
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	11 This library is targeted towards two major groups:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	12
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	13 - People who just want an easy, high performance, way to play audio (don't care if its OpenAL or not)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	14 - People who want to an easy way to play audio in OpenAL but still want access to OpenAL directly.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	15
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	16 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	17
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	18 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	19
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	20 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	21
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	22 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	23
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	24
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	25 SDL_mixer vs. ALmixer:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	26
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	27 Why would you want to use ALmixer over SDL_mixer?
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	28 - There is no artificial limit or distinction between "music" and "sounds". Instead, you specify if you want to preload a sound fully or as a "stream" and the "play" API automatically and transparently does the right thing. This means you can have multiple streaming sounds playing at the same time like music and speech.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	29 - The callback API allows for void* userdata (a.k.a. context) to be passed through.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	30 - Uses OpenAL as the audio engine instead of SDL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	31 - Not subject to known SDL and SDL_mixer bugs/limitations
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	32 - You can utilize OpenAL for additional features and effects.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	33
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	34
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	35 Why would you want to use SDL_mixer over ALmixer?
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	36 - ALmixer is newer, less proven code
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	37 - OpenAL while an industry cross-platform standard, is still not as ubiquitous as SDL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	38 - OpenAL may have a different set of bugs and there are different implementations of OpenAL which may have different bugs.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	39 - SDL_mixer effects are not ported. (You should utilize OpenAL effects instead.)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	40
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	41
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	42
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	43 Compile Flags:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	44
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	45 There are some #defines you can set to change the behavior at compile time. Most you shouldn't touch.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	46
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	47 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
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	48 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.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	49
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	50
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	51 Building:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	52
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	53 This project uses CMake.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	54 Check out CMake at http://www.cmake.org
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	55 Check out my screencast tutorial at: http://playcontrol.net/ewing/screencasts/getting_started_with_cmake_.html
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	56
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	57 Typical commandline: (from inside the ALmixer directory)
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	58 mkdir BUILD
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	59 cd BUILD
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	60 cmake ..
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	61 make
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	62
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	63 Or use the ccmake or the CMake GUI to make it easier to configure options like ENABLE_ALMIXER_THREADS.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	64
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	65
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	66 Backstory:
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	67
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	68 I originally wrote this library back in roughly 2002 to workaround bugs and limitations I was facing with SDL_mixer. I was experiencing latency problems back then with SDL_mixer on certain platforms and I needed the ability to play both music and speech simultaneously which the design of SDL_mixer does not really facilitate. I also needed more decoding formats than SDL_mixer supported, plus at the time, the SDL_mixer backend for music used a different decoding backend than the rest of the library which made it inconsistent.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	69
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	70 The ALmixer code was written very quickly in a matter of several weeks. But in solving all the problems/limitations I had with SDL_mixer, I encountered a whole set of new problems surrounding OpenAL. Back in 2002, OpenAL was on life-support and the 1.0 OpenAL spec was really broken. The differences between implementations of OpenAL differed greatly which made it very difficult to ship a cross-platform application using OpenAL.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	71
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	72 Meanwhile, because the code was written so quickly and also happened to be my first venture into audio (among other things), I felt the code was messy and needed to be cleaned up. The complicated state machine necessary to do what I needed turned out to be very scary. In addition, with all the hacks I needed to add to workaround OpenAL implementation differences, made the code much more complicated.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	73
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	74 So rather than releasing to the public, I decided to sit on the code and vowed to clean it up some day so I don't embarrass myself. I also expected that SDL_mixer would be rewritten to use SDL_sound soon and maybe some of my other issues might finally be fixed.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	75
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	76 Many years passed.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	77
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	78 OpenAL 1.1 was ratified and many of the compatibility issues between OpenAL implementations started going away. Every so often, I re-pickup ALmixer and made small changes to update it to support OpenAL 1.1.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	79
5 8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	80 Fast forward to 2010 (today). I still haven't cleaned up ALmixer. SDL_mixer has still not been rewritten. And there haven't been any great audio libraries that have emerged in all these years. Furthermore, with renewed interest in playing high performance audio with OpenAL due to the enormous success of iPhone, iPod touch, and iPad, I see there is a still a great void that needs to be filled. (In fact, I just co-authored possibly the most comprehensive book on OpenAL ever written: http://playcontrol.net/iphonegamebook)
3 a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	81
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	82 And I have recently been working on a project that would benefit greatly from something like ALmixer. I realized that I don't have the time/money to do the clean-up, nor is it feasible for me to do an entire rewrite. I also realize that despite the scariness of the code, the library seems to generally work.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	83
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	84 So I have decided to finally release ALmixer, even without the clean ups. My hope is people find it useful and I also get some good testing feedback. Maybe some heros will even make it better. Please be kind when reading the code and reporting bugs. I admit the code is scary and many of the comments are now obsolete.
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	85
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	86
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	87 Eric Wing <ewing . public @ playcontrol.net>
a929285e1db0 Added CMake build system. Eric Wing <ewing . public \|-at-\| gmail . com> parents: diff changeset	88
5 8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	89 ALmixer Home Page: http://playcontrol.net/opensource/ALmixer
8cb13d89451a Doxygen support and fixes. Eric Wing <ewing . public \|-at-\| gmail . com> parents: 3 diff changeset	90

Mercurial > almixer_isolated

annotate README.txt @ 47:9b772c81b550