Documentation pass

doc/c_api.mmd

@@ -1,13 +1,22 @@
-"C"-api / DLL
+"C" API / DLL
 =============
 
 In order to support non-c++ environments, SoLoud also has a "C" API.
 
 All of the existing interfaces can be used via the "C" API, but 
 features that require extending SoLoud are not available.
 
-API
----
+Using the "C" API
+-----------------
+
+You can either link to the generated DLL, which exposes the "C" API,
+or you can include SoLoud C++ sources (or static library) to your
+project along with the soloud_c.cpp file.
+
+In your C sources, include soloud_c.h header file.
+
+"C" API
+-------
 
 The "C" API mirrors the c++ API.
 
@@ -53,4 +62,4 @@ Converted to the "C" API, this becomes:
     Speech_destroy(speech);
     Soloud_destroy(soloud);
 
-
+For a slightly longer example, check out the "c_test" demo.

doc/codegen.mmd

@@ -1,6 +1,9 @@
 Codegen
 =======
 
+For most cases, you won't need to care about the codegen. Here's
+some information, however, if should you be curious.
+
 In order for SoLoud to be usable from other languages than C++,
 glue code needs to be written. Most environments are able to
 use "C" DLL:s, and this is one of the things SoLoud has.
@@ -17,4 +20,9 @@ won't need to use the codegen yourself.
 The codegen tool parses the SoLoud headers and generates the needed
 headers and wrapper cpp code, as well as the DLL .def file, and a
 Python file which can be used to generate glue libraries for other
-environments, such as Python.
+environments (such as Python itself).
+
+The generated Python file also turned out to be useful in writing
+of this documentation, as it was pretty easy to write a script that
+checks whether a function has been documented or not.
+

doc/concepts.mmd

@@ -7,7 +7,7 @@ Back end
 SoLoud itself "only" performs audio mixing and some resource handling.
 For it to be useful, it needs one or more sound source and a back end.
 Some other audio systems use the term 'sink' for the back-ends. 
-Examples of back-ends would be winmm, portaudio, wasapi and SDL audio. 
+Examples of back-ends would be winmm, oss, portaudio, wasapi and SDL audio. 
 SoLoud comes with several back-ends, and is designed to make back-ends 
 relatively easy to implement.
 
@@ -45,7 +45,7 @@ in any case.
 If all channels are already playing and the application requests another
 sound to play, SoLoud finds the oldest voice and kills it. Since this
 may be your background music, you can protect channels from being killed
-by using the soloud.setProtect call.
+by using the soloud.setProtect() call.
 
 Voice Group
 -----------
@@ -56,6 +56,11 @@ between two versions of the same song.
 
 ![Problem unpausing two voices. Delay may vary, 40ms used as an example.](images/voicegroups)
 
+Even if you try to unpause the two voices at the same time, it's possible,
+due to the multithreaded nature of audio, that the audio engine interrupts
+you between these two calls and your sounds get unpaused to different audio
+buffers.
+
 SoLoud's solution to this are voice groups. Voice groups can be commanded
 the same way as single voices, but instead of affecting just one voice,
 SoLoud performs the command on all of the voices in the group in one
@@ -82,7 +87,7 @@ gets less precision. The roundoff clipper is used by default.
 The roundoff clipper does, however, alter the signal and thus "damages"
 the sound. A more proper way of doing things would be to use the basic
 clipper and adjust the global volume to avoid clipping. The roundoff
-clipper, however, is easier to use.
+clipper is, however, easier to use.
 
 Sample
 ------
@@ -96,7 +101,8 @@ towards floating point samples.
 
 SoLoud also uses floating point samples internally. First and foremost,
 it makes everything much simpler, and second, modern computing devices
-have become fast enough that this is not really a performance issue anymore.
+(even mobile!) have become fast enough that this is not really a 
+performance issue anymore.
 
 Floating point samples also take more space than, for instance, 16 bit
 samples, but memory and storage sizes have also grown enough to make
@@ -112,11 +118,16 @@ Typical sample rates are 8000Hz, 22050Hz, 44100Hz and 48000Hz. Higher
 the sample rates mean clearer sound, but also bigger files, more memory
 and higher processing power requirements.
 
+Due to limitations in human hearing, 44100Hz is generally considered 
+sufficient. Some audiophiles disagree, but then again, some audiophiles
+buy gold-plated USB cables.
+
 Hz
 --
 
-Hertz, SI unit of frequency. 1Hz means "once per second", 10Hz means 
-"10 times per second", and 192kHz means "192000 times per second".
+Hertz, SI unit of frequency. 0.1Hz means "once per 10 seconds", 1Hz means 
+"once per second", 10Hz means "10 times per second", and 192kHz means 
+"192000 times per second".
 
 Play Speed
 ----------
@@ -132,8 +143,8 @@ Relative Play Speed
 -------------------
 
 SoLoud lets you change the relative play speed of samples. Please note
-that asking for a higher relative play speed is more expensive than a
-lower one.
+that asking for a higher relative play speed is always more expensive 
+than a lower one.
 
 Resampling
 ----------
@@ -142,6 +153,8 @@ SoLoud has to perform resampling when mixing. In an ideal case, all of
 the sources and the destination sample rate are the same, and no
 resampling is needed, but this is often not true. 
 
+![Different resamples (Point / linear / catmull-rom). Red is the ideal signal.](images/resampler)
+
 Currently, SoLoud supports "linear interpolation", which calculates linear 
 interpolation of samples, as well as "point sample" resampling, which 
 means it simply skips or repeats samples as needed.
@@ -215,7 +228,9 @@ are processor power, imagination, and developer's skill in digital
 signal processing.
 
 SoLoud lets you hook several filters to a single audio stream, as well
-as to the global audio output.
+as to the global audio output. By default, you can use up to four filters,
+but this can be easily changed by editing SoLoud.h file and rebuilding
+the library.
 
 Mixing Bus
 ----------
@@ -240,3 +255,7 @@ It's also possible that you have some very complex audio sources, such
 as racing cars. In this case it makes sense to place all the audio
 streams that play from one car into a mixing bus, and then adjust the
 panning (or, eventually, 3d position) of the mixing bus.
+
+Additional feature of the mixing busses in SoLoud is that you can
+request visualization data from a bus, instead of just from the global
+scope.

doc/downloads.mmd

@@ -63,6 +63,7 @@ Documentation: [PDF](soloud_20140622.pdf) | [EPUB](soloud_20140622.epub) | [MOBI
     - Some work towards osx, linux compatibility
     - FFT code moved to its own source so it can be more easily replaced in the future
     - Changed mixer fixed point from 16.16 to 12.20
+    - Various small fixes, as usual.
 
 [soloud_20140521.zip](soloud_20140521.zip) 
 

doc/examples.mmd

@@ -68,7 +68,7 @@ Key  Effect
 2    Play sound repeatedly with play()
 3    Play sound once with playClocked()
 
-To exaggarate the effect a bit, the demo initializes SoLoud with a very large audio buffer. The difference between the play and playClocked
+To exaggarate the effect a bit, the demo requests a very large audio buffer from SoLoud. The difference between the play and playClocked
 effects is that with play(), all sounds triggered between audio buffers begin playing from the start of the next audio buffer, while 
 playClocked spreads the sounds across the audio buffer, making the sounds more separate.
 

doc/htmlpre.txt

@@ -38,6 +38,8 @@
 <a href="voicegroups.html">Core: Voice Groups</a><br>
 <a href="coremisc.html">Core: Misc</a><br>
 <br>
+<a href="mixbus.html">SoLoud::Bus</a><br>
+<br>
 <a href="audiosource.html">SoLoud::AudioSource</a><br>
 <a href="wav.html">SoLoud::Wav</a><br>
 <a href="wavstream.html">SoLoud::WavStream</a><br>
@@ -46,8 +48,6 @@
 <a href="modplug.html">SoLoud::Modplug</a><br>
 <a href="newsoundsources.html">New Audio Sources</a><br>
 <br>
-<a href="mixbus.html">SoLoud::Bus</a><br>
-<br>
 <a href="filters.html">SoLoud::Filter</a><br>
 <a href="biquadfilter.html">SoLoud::BiquadReso..</a><br>
 <a href="echofilter.html">SoLoud::EchoFilter</a><br>

doc/intro.mmd

@@ -38,7 +38,7 @@ so many sounds at once it's channel has been taken over by some other
 sound), the handle is still safe to use - it just doesn't do anything.
 
 There's also a pure "C" version of the whole API which can even be used 
-from non-c languages by using SoLoud as an DLL.
+from non-c languages by using SoLoud as an DLL, such as Python.
 
 How Free?
 ---------
@@ -53,9 +53,9 @@ other things, that:
 - You don't need to add a splash screen. (But you can).
 - You don't need to mention it in your printed manual. (But you can).
 
-Basically the only things the license forbids are suing me, or claiming
-that you made SoLoud. If you redistribute the source code, the license
-needs to be there. But not with the binaries.
+Basically the only things the license forbids are suing the authors, or 
+claiming that you made SoLoud. If you redistribute the source code, the 
+license needs to be there. But not with the binaries.
 
 Parts of the SoLoud package were not made by me, and those either have a
 similar license, or more permissive (such as Unlicense, CC0, WTFPL or
@@ -75,6 +75,8 @@ with powerful functionality. Some of the features include:
 - Mixing busses for grouping of audio into different uses and adjusting their attributes in one go.
 - Gapless looping.
 - Playing several ogg streams at once.
+- Atomic operations for several sounds.
+- "Clocked" playing for rapid sound effects.
 - Sound effects synthesizer.
 - Modplug library capable of playing various multi-channel music formats (including mod, s3m, it, xm, mid, abc).
 - Easy cleanup.

doc/legal.mmd

@@ -8,6 +8,8 @@ similar, like WTFPL or Unlicense, where you don't need to include
 mention of the code in your documentation or splash screens or any such
 nonsense.
 
+Any patches submitted to SoLoud must agree to be under compatible licenses.
+
 SoLoud Proper
 -------------
 

doc/makedoc.py

@@ -24,14 +24,14 @@
     "faders.mmd",
     "voicegroups.mmd", 
     "coremisc.mmd",
+    "mixbus.mmd",
     "audiosource.mmd",
     "wav.mmd",
     "wavstream.mmd",
     "speech.mmd",
     "sfxr.mmd",
     "modplug.mmd",
     "newsoundsources.mmd",
-    "mixbus.mmd",
     "filters.mmd",
     "biquadfilter.mmd",
     "echofilter.mmd",

doc/premake.mmd

@@ -17,19 +17,22 @@ You will most likely want to edit at least the sdl_root variable. After your edi
 
     premake4 vs2010
 
-The current version (4.3) supports codeblocks, codelite, vs2002, vs2003, vs2005, vs2008, vs2010, xcode3 and gnu makefiles (gmake). New version with at least vs2012 support is coming soon (as of this writing).
+The current version (4.3) supports codeblocks, codelite, vs2002, vs2003, vs2005, vs2008, vs2010, xcode3 and gnu makefiles 
+(gmake). New version with at least vs2012 support is coming soon (I hope).
 
-If you wish to use portmidi with the piano example, run premake with an additional parameter:
+You can also use one or more of the optional parameters to change the build behavior. 
 
-    premake4 --with-portmidi vs2010
+Option                Description
+-------------------   -----------
+with-libmodplug       Include libmodplug in build
+with-native-only      Only native backends (winmm/oss) in build
+with-portmidi         Use portmidi to drive midi keyboard in the piano demo
+with-sdl-only         Only include sdl in build
+with-sdlnondyn-only   Only include sdl that doesn't use dyndll in build
+with-tools            Include (optional) tools in build
+with-xaudio2          Include xaudio2 in build
 
-If you wish to include the xaudio2 back-end, use the parameter:
+So for example, in order to build SoLoud with libmodplug and tools on vs2010, use:
 
-    premake4 --with-xaudio2 vs2010
-
-The back-end is not included by default due to the requirement of xaudio2.lib.
-
-To include libmodplug, yet another parameter is needed:
-
-    premake4 --with-libmodplug vs2010
+    premake4 --with-libmodplug --with-tools vs2010 
 

doc/python_api.mmd

@@ -6,8 +6,18 @@ One of the generated glue interfaces for SoLoud is the Python API.
 All of the existing interfaces can be used via the Python API, but
 features that require extending SoLoud are not available.
 
-API
----
+Using the Python API
+-----------------
+
+Include the SoLoud DLL and soloud.py in the same directory as your
+python files, and use
+
+    import soloud
+
+to include SoLoud to your project.
+
+Python API
+----------
 
 The Python API mirrors the c++ API.
 

doc/quickstart.mmd

@@ -1,26 +1,45 @@
 Quick Start
 ===========
 
+This quick start is for c++ developers. If you're using SoLoud with
+some other environment SoLoud supports, you may want to skip this and
+look at the chapter that covers your environment (such as Python).
 
 Download SoLoud
 ---------------
 
 First, you need to download SoLoud sources. You can find the downloads
 on the <http://soloud-audio.com/download.html> page.
 
-Add files to your project
--------------------------
+Add SoLoud to your project
+--------------------------
+
+There's a few ways to include SoLoud to your project. Probably the
+easiest is to use premake4 to create the build files, and build a 
+static library for your compiler / environment.
+
+There may also be a pre-built static library in the SoLoud distribution,
+which you may be able to use. Note that the Windows DLL only exports the 
+"C" API, which may not be what you want.
 
 You can go the lazy way and just add all of the sources to your project,
 or you can copy the things you need to a single directory and include
 those. You'll need the core files, and quite likely the wav files. If
-you need the speech synth, include those, too.
+you need the speech synth, include those, too. If you go this route,
+you'll need to enable one or more of the back-ends via preprocessor
+defines. The current list is:
+
+Preprocessor macro  Description
+------------------  -----------
+WITH_SDL            SDL or SDL2 via runtime dyndll linking
+WITH_SDL_NONDYN     SDL via normal linking
+WITH_PORTAUDIO      Portaudio via runtime dyndll linking
+WITH_OPENAL         OpenAL via runtime dyndll linking (high latency)
+WITH_XAUDIO2        XAudio2 via normal linking
+WITH_WINMM          Windows multimedia
+WITH_WASAPI         WASAPI (experimental)
+WITH_OSS            Linux OSS
 
-There may be a pre-built static library that you can use. You can use 
-that, too. Note that the Windows DLL only exports the "C" API, which may 
-not be what you want.
-
-There's also a premake4 script if you want to go that way.
 
 Include files
 -------------
@@ -99,3 +118,7 @@ Enjoy
 -----
 
 And you're done!
+
+Note that most calls above also return some kind of return code which may
+help you diagnose potential problems. When loading wave files, for instance,
+you may want to check if the file is actually found.