From 069a186d174acefc1f48e5397f622b2c5c8fb45f Mon Sep 17 00:00:00 2001 From: jarikomppa Date: Sun, 22 Jun 2014 21:23:52 +0300 Subject: [PATCH] Documentation pass --- doc/c_api.mmd | 17 +++++++++++++---- doc/codegen.mmd | 10 +++++++++- doc/concepts.mmd | 37 ++++++++++++++++++++++++++++--------- doc/downloads.mmd | 1 + doc/examples.mmd | 2 +- doc/htmlpre.txt | 4 ++-- doc/intro.mmd | 10 ++++++---- doc/legal.mmd | 2 ++ doc/makedoc.py | 2 +- doc/premake.mmd | 25 ++++++++++++++----------- doc/python_api.mmd | 14 ++++++++++++-- doc/quickstart.mmd | 39 +++++++++++++++++++++++++++++++-------- 12 files changed, 120 insertions(+), 43 deletions(-) diff --git a/doc/c_api.mmd b/doc/c_api.mmd index f7e5f59c..beae92e8 100644 --- a/doc/c_api.mmd +++ b/doc/c_api.mmd @@ -1,4 +1,4 @@ -"C"-api / DLL +"C" API / DLL ============= In order to support non-c++ environments, SoLoud also has a "C" API. @@ -6,8 +6,17 @@ 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. diff --git a/doc/codegen.mmd b/doc/codegen.mmd index f13dbf72..a28d0c51 100644 --- a/doc/codegen.mmd +++ b/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. + diff --git a/doc/concepts.mmd b/doc/concepts.mmd index 733ad536..2269e25c 100644 --- a/doc/concepts.mmd +++ b/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. diff --git a/doc/downloads.mmd b/doc/downloads.mmd index cb49345f..75d2624a 100644 --- a/doc/downloads.mmd +++ b/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) diff --git a/doc/examples.mmd b/doc/examples.mmd index c08f4cf0..d449da5a 100644 --- a/doc/examples.mmd +++ b/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. diff --git a/doc/htmlpre.txt b/doc/htmlpre.txt index a19d147d..422b699b 100644 --- a/doc/htmlpre.txt +++ b/doc/htmlpre.txt @@ -38,6 +38,8 @@ Core: Voice Groups
Core: Misc

+SoLoud::Bus
+
SoLoud::AudioSource
SoLoud::Wav
SoLoud::WavStream
@@ -46,8 +48,6 @@ SoLoud::Modplug
New Audio Sources

-SoLoud::Bus
-
SoLoud::Filter
SoLoud::BiquadReso..
SoLoud::EchoFilter
diff --git a/doc/intro.mmd b/doc/intro.mmd index 391178e6..6b3c8925 100644 --- a/doc/intro.mmd +++ b/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. diff --git a/doc/legal.mmd b/doc/legal.mmd index 055a54b9..b628fbf2 100644 --- a/doc/legal.mmd +++ b/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 ------------- diff --git a/doc/makedoc.py b/doc/makedoc.py index b6b8102b..f8f51165 100644 --- a/doc/makedoc.py +++ b/doc/makedoc.py @@ -24,6 +24,7 @@ "faders.mmd", "voicegroups.mmd", "coremisc.mmd", + "mixbus.mmd", "audiosource.mmd", "wav.mmd", "wavstream.mmd", @@ -31,7 +32,6 @@ "sfxr.mmd", "modplug.mmd", "newsoundsources.mmd", - "mixbus.mmd", "filters.mmd", "biquadfilter.mmd", "echofilter.mmd", diff --git a/doc/premake.mmd b/doc/premake.mmd index 097f075f..9bc970ca 100644 --- a/doc/premake.mmd +++ b/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 \ No newline at end of file diff --git a/doc/python_api.mmd b/doc/python_api.mmd index 8898fb49..7097c471 100644 --- a/doc/python_api.mmd +++ b/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. diff --git a/doc/quickstart.mmd b/doc/quickstart.mmd index f1913b90..94cd5533 100644 --- a/doc/quickstart.mmd +++ b/doc/quickstart.mmd @@ -1,6 +1,9 @@ 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 --------------- @@ -8,19 +11,35 @@ Download SoLoud First, you need to download SoLoud sources. You can find the downloads on the 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. \ No newline at end of file