Mercurial > almixer_isolated

annotate README.txt @ 67:96c61ac12446

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed a copy/paste comment error about the origins of SDL_sound_minimal.c
author Eric Wing <ewing@anscamobile.com>
date Tue, 19 Jun 2012 18:49:27 -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