doc pass

docsrc/audiosource.mmd

@@ -39,6 +39,9 @@ This function can be used to tell SoLoud that only one instance of this
 sound may be played at the same time.
 
     menuselect.setSingleInstance(1); // Only play it once, Sam
+
+This may be useful if, for example, you play a sound effect every time user
+interacts with a menu, and don't want the effect to overlap.
 
 ### AudioSource.set3dMinMaxDistance()
 

docsrc/backends.mmd

@@ -10,14 +10,14 @@ addition to the optional mutex function pointers.
 Studying the existing back-end implementations' source code, in addition
 to this page, will help creating new ones.
 
-### Soloud.postinit()
+### Soloud.postinit_internal()
 
 
-The back-end should call Soloud.postinit() once it knows what it can do.
+The back-end should call Soloud.postinit_internal() once it knows what it can do.
 
-    void postinit(int aSamplerate, // Sample rate, in Hz
-                  int aBufferSize, // Buffer size, in samples
-                  int aFlags);     // Flags
+    void postinit_internal(int aSamplerate, // Sample rate, in Hz
+                           int aBufferSize, // Buffer size, in samples
+                           int aFlags);     // Flags
 
 The channels and flags most likely come directly from the application,
 while sample rate and buffer size may depend on how the back-end does
@@ -93,12 +93,15 @@ SDL/SDL2 DLL   Yes  Most tested, primary development platform. Cross-platform. L
 SDL Static     ?    Mostly meant for emscripten use.
 SDL2 Static    Yes  Can be used to statically link to SDL2.
 PortAudio      ?    Cross-platform. Very low latency. Dynamic linking.
+MiniAudio      Yes  Cross-platform, very low latency. Included with SoLoud.
 WinMM          Yes  Simplest back-end for Windows-only programs.
 ALSA           Yes  Default audio interface for Linux
+JACK           ?    Alternative audio interface for Linux
 oss (/dev/dsp) Yes  Simplest back-end for Linux-only programs. Experimental.
 OpenAL         ?    Very experimental. Very high latency; if this is your only option, you're probably better off using OpenAL directly.
 WASAPI         Yes  Experimental
 XAudio2        Yes  Experimental
+Nosound        Yes  Plays audio, throws it away.
 Null driver    Yes  Can be used to use SoLoud without audio device.
 
 Some of the backends have not been tested in x64 builds, but as long as everything is x64, there's no real reason why they don't work.

docsrc/basics.mmd

@@ -46,11 +46,12 @@ it prefers, and its default parameters.
 
 Currently, you can select from these flags:
 
-Flag                 | Description
-----                 | ------------
-CLIP_ROUNDOFF        | Use roundoff clipper. Without this flag the clipper defaults to "hard" clipping to -1/+1
-ENABLE_VISUALIZATION | Enable gathering of visualization data. Can be changed at runtime with setVisualizationEnable()
-LEFT_HANDED_3D       | Use left-handed (Direct3D) 3d coordinates. Default is right-handed (OpenGL) coordinates.
+Flag                   | Description
+----                   | ------------
+CLIP_ROUNDOFF          | Use roundoff clipper. Without this flag the clipper defaults to "hard" clipping to -1/+1
+ENABLE_VISUALIZATION   | Enable gathering of visualization data. Can be changed at runtime with setVisualizationEnable()
+LEFT_HANDED_3D         | Use left-handed (Direct3D) 3d coordinates. Default is right-handed (OpenGL) coordinates.
+NO_FPU_REGISTER_CHANGE | Do not alter the FPU state in audio threads. By default, SoLoud uses "fast" fpu options.
 
 Current set of back-ends is:
 
@@ -60,15 +61,18 @@ AUTO          | Select backend automatically
 SDL1          | SDL1 dynamic or static linking
 SDL2          | SDL2 dynamic or static linking
 PORTAUDIO     | PortAudio
+MINIAUDIO     | MiniAudio
 WINMM         | Windows MultiMedia
 XAUDIO2       | XAudio2
 WASAPI        | Windows Audio Session API
 ALSA          | Advanced Linux Sound Architecture
+JACK          | JACK Audio Connection Kit
 OSS           | Open Sound System
 OPENAL        | OpenAL (high latency)
 COREAUDIO     | OSX CoreAudio
 OPENSLES      | OpenSL ES
 VITA_HOMEBREW | Vita console homebrew SDK
+NOSOUND       | No-sound driver
 NULLDRIVER    | Null driver
 
 \pagebreak
@@ -157,6 +161,9 @@ used) to calculate the delay between two sound effects. If a output
 sound buffer threshold is passed between the two sounds, SoLoud will
 adjust the delay accordingly.
 
+Note that if your "physics time" granularity is low, playClocked is
+not really useful. Audio buffers tend to be 40ms long at most.
+
 \pagebreak
 
 ### Soloud.playBackground()

docsrc/biquadfilter.mmd

@@ -15,7 +15,7 @@ The resonance parameter adjusts the sharpness (or bandwidth) of the
 cutoff.
 
     // Set up low-pass filter
-    gBQRFilter.setParams(SoLoud::BiquadResonantFilter::LOWPASS, 44100, 500, 2);  
+    gBQRFilter.setParams(SoLoud::BiquadResonantFilter::LOWPASS, 500, 2);  
     // Set the filter as the second filter of the bus
     gBus.setFilter(1, &gBQRFilter); 
 

docsrc/concepts.mmd

@@ -44,8 +44,8 @@ channels), but surround sound audio sources may practically have any
 number of channels.
 
 In module music (such as mod, s3m, xm, it), "channel" means one of the
-concurrent sounds played, regardless of speaker configuration. Confusing,
-yes.
+concurrent sounds played, regardless of speaker configuration. Confusing?
+Yes.
 
 ### Voice
 
@@ -219,12 +219,12 @@ directly, if needed.
 
 
 SoLoud uses throwaway handles to control sounds. The handle is an
-integer, and internally tracks the channel and sound id, as well as an
+integer, and internally tracks the voice and sound id, as well as an
 "uniqueness" value.
 
 If you try to use a handle after the sound it represents has stopped,
 the operation is quietly discarded (or if you're requesting information,
-some kind of generic value is returned). You can also query the validity
+some kind of generic value is returned, usually 0). You can also query the validity
 of a handle.
 
 ### Latency
@@ -244,8 +244,9 @@ there's no data ready to be played) and the sound breaks down horribly.
 Assuming there's no other sources of latency (and there quite likely
 is), with 2048 sample buffer and 44100Hz playback, the latency is around
 46 milliseconds, which is tolerable in most computer game use cases. A 
-100ms latency is already easily noticeable. For playing drums, 40ms 
-is too much.
+100ms latency is already easily noticeable. In music terms, when playing
+drums, 40ms is too much, but when playing slowly evolving atmospheric pads,
+200ms is fine.
 
 ### Filter
 
@@ -254,7 +255,7 @@ Audio streams can also be modified on the fly for various effects.
 Typical uses are different environmental effects such as echoes or
 reverb, or low pass (bassy sound) / high pass (tinny sound) filters, but
 basically any kind of modification can be done; the primary limitations
-are processor power, imagination, and developer's skill in digital
+are processor power, imagination, and the developer's skill in digital
 signal processing.
 
 SoLoud lets you hook several filters to a single audio stream, as well

docsrc/concepts3d.mmd

@@ -6,7 +6,7 @@ In practise, all the "3d audio" does is adjust panning and play speed of your au
 
 Any audio source can be 3d, including mixing busses. However, true 3d positioning only really makes sense for mono audio sources.
 
-The doppler and attenuation calculations follow the OpenAL functions.
+The doppler and attenuation calculations follow the OpenAL equations.
 
 In order to use the 3d audio, use the 3d versions of the play commands, adjust the positions and velocities of your audio sources and listener with the set3dSource...() and set3dListener...() calls, and call update3dAudio() to ask SoLoud to recalculate the proper panning (and play speed, for doppler).
 

docsrc/dirstruct.mmd

@@ -17,6 +17,7 @@ glue      All the glue libraries for various environments, like rpgmaker, c#, py
 build     The GENie / premake script that can be used to generate build scripts for various IDEs or a gnu makefile.
 demos     SoLoud's demos showing how to use SoLoud's various features.
 src       Source code for SoLoud itself
+contrib   Additional files that are not maintained by SoLoud project itself, such as cmakefiles, but may be useful to some people.
 
 
 ### src
@@ -32,8 +33,8 @@ src/tools       Some command-line tools under the src/tools directory. Most of t
 
 ### demos
 
-Most of the demos use some common code based on Ocornut's Dear ImGui library. This is to make the source for the demo itself mostly about SoLoud and not about putting pixels on the screen, while having an easy to use UI
-for the demos.
+Most of the demos are based on SDL2 and use some common code based on Ocornut's Dear ImGui library. This is to make the source for the demo itself mostly about SoLoud 
+and not about putting pixels on the screen, while having an easy to use UI for the demos.
 
 Directory        Description
 ----             ------------

docsrc/faq.mmd

@@ -96,6 +96,9 @@ for the future.
 
 Yes. SoLoud supports 1, 2, 4, 5.1 and 7.1 configurations.
 
+The way multi-speaker system is implemented in SoLoud, it would be relatively easy to add any number of speakers,
+but having more output channels also adds overhead. Most people will only ever use stereo output.
+
 ### Are these real questions?
 
 

docsrc/file.mmd

@@ -116,8 +116,8 @@ buffer.
 
 ### soloud_file_hack_on.h, soloud_file_hack_off.h
 
-SoLoud comes with a pair of headers you can use to fool code which uses the FILE*
-interface to use File* instead. 
+SoLoud comes with a pair of headers you can use to fool code which uses the FILE\*
+interface to use File\* instead. 
 
 The files use preprocessor macros to turn FILE* calls into SoLoud's wrapper
 function calls which in turn use the File class interfaces. Since it's a 

docsrc/filters.mmd

@@ -168,7 +168,7 @@ All filters inherit the live parameter access functions.
 - getParamMax()
 - getParamMin()
 
-These functions are mostly useful online, to get information about
+These functions are mostly useful at runtime, to get information about
 filters without knowing which filter you're talking with, such as
 with an editor. See "Filter Folio" demo as an example.
 

docsrc/flangerfilter.mmd

@@ -34,7 +34,7 @@ Set the parameters of the filter.
 Changing the parameters does not affect "live" sounds. If invalid parameters are
 given, the function will return error.
 
-
+\pagebreak
 ### Live Parameter Access
 
 All filters inherit the live parameter access functions.

docsrc/freeverbfilter.mmd

@@ -4,7 +4,7 @@ Freeverb is a reverb filter based on the code written by Jezar at Dreampoint,
 June 2000 http://www.dreampoint.co.uk, and placed under public domain. There
 are other versions of Freeverb out there with different licenses. 
 
-While it sounds great, the filter is relatively heavy.
+While it sounds great, the filter is relatively heavy, and should be used sparingly.
 
 ### FreeverbFilter.setParams()
 

docsrc/legal.mmd

@@ -16,7 +16,7 @@ SoLoud proper is licensed under the ZLib/LibPNG license. The code is a
 clean-room implementation with no outside sources used.
 
     SoLoud audio engine
-    Copyright (c) 2013-2018 Jari Komppa
+    Copyright (c) 2013-2020 Jari Komppa
 
     This software is provided 'as-is', without any express or implied
     warranty. In no event will the authors be held liable for any damages
@@ -257,4 +257,11 @@ SoLoud does not include Openmpt in itself, but can use it through a DLL.
 If you don't need it, you don't need to include the DLL either. If you DO
 need to use it, please look up its license.
 
-
+### FreeVerb
+
+Based on code by Jezar at Dreampoint, June 2000 
+http://www.dreampoint.co.uk, which was placed under public domain.
+
+Note that the version of FreeVerb included in SoLoud is based on the original, public domain
+release, and not the GPL-licensed FreeVerb3. 
+

docsrc/lofifilter.mmd

@@ -26,6 +26,8 @@ WET         Filter's wet signal; 1.0f for fully filtered, 0.0f for original, 0.5
 SAMPLERATE  Filter's samplerate parameter
 BITDEPTH    Filter's bit-depth parameter
 
+Note that the bit depth does not need to be an integer value.
+
 ### LofiFilter.setParams()
 
 Set the parameters of the filter.
@@ -35,7 +37,7 @@ Set the parameters of the filter.
 Changing the parameters does not affect "live" sounds. If invalid parameters are
 given, the function will return error.
 
-
+\pagebreak
 ### Live Parameter Access
 
 All filters inherit the live parameter access functions.

docsrc/mixbus.mmd

@@ -28,6 +28,10 @@ To play a stream through the mixing bus, use the bus play() command.
     int fxhandle = gBus.play(gSoundEffect); // Play sound effect through bus
     gSoloud.setVolume(fxhandle, 0.5f); // set sound effect volume
 
+When chaining busses care should be taken, as resampling will offset the output
+by a number of samples. Point sampling by 0, linear by 1, and higher resamplers
+with higher number of samples.
+
 ### Bus.setChannels()
 
 Set the number of channels this bus should handle. Defaults to 2 (stereo).

docsrc/monotone.mmd

@@ -11,8 +11,8 @@ available at the time of this writing). You can pick the number of
 "hardware" voices used - typically the songs are composed for a single
 voice (PC beeper).
 
-The waveform used is square wave. Other waveforms can be used by 
-modifying the soloud_monotone.cpp.
+The default waveform used is square wave, but other waveforms
+are also supported.
 
 ### Monotone.clear()
 
@@ -67,8 +67,20 @@ MONOTONE file.
 Most songs are composed for a single hardware channel. SoLoud supports
 up to 12 hardware channels (more can be easily added by editing soloud_monotone.cpp)
 
-For waveform, along with the default SQUARE, the SAW, SIN and SAWSIN waveforms are 
-supported. The SAWSIN is simply saw(t)*sin(t).
+The supported waveforms include:
+
+| Waveform | Description |
+|:---------|:-----------------------|
+|WAVE_SQUARE|Raw, harsh square wave|
+|WAVE_SAW|Raw, harsh saw wave|
+|WAVE_SIN|Sine wave|
+|WAVE_TRIANGLE|Triangle wave|
+|WAVE_BOUNCE|Bounce, i.e, abs(sin())|
+|WAVE_JAWS|Quater sine wave, rest of period quiet|
+|WAVE_HUMPS|Half sine wave, rest of period quiet|
+|WAVE_FSQUARE|"Fourier" square wave; less noisy|
+|WAVE_FSAW|"Fourier" saw wave; less noisy|
+
 
 
 ### Monotone.setLooping()

docsrc/newsoundsources.mmd

@@ -99,7 +99,7 @@ function.
 
 Optionally, you can implement a seek function. The base implementation
 will simply request (and discard) samples from the sound source until
-the desired position has been reached; for many sound sources, a smarter
+the desired position has been reached; for many sound sources, some smarter
 way exists.
 
 ### AudioSourceInstance.rewind()

docsrc/premake.mmd

@@ -29,10 +29,14 @@ Option                  Description
 soloud-devel            Shorthand for options used while developing SoLoud
 with-common-backends    Includes common backends in build
 with-coreaudio          Include OS X CoreAudio backend in build
+with-jack               Include JACK backend in build
+with-jack-only          Only include JACK backend in build
+with-miniaudio          Include MiniAudio in build
+with-miniaudio-only     Only include MiniAudio in build
 with-native-only        Only native backends (winmm/oss) in build (default)
+with-nosound            Include nosound backend in build
 with-openal             Include OpenAL backend in build
 with-portaudio          Include PortAudio backend in build
-with-portmidi           Use PortMidi to drive midi keyboard in the piano demo
 with-sdl                Include SDL backend in build
 with-sdl-only           Only include sdl in build
 with-sdl2               Include SDL2 backend in build

docsrc/quickstart.mmd

@@ -13,26 +13,28 @@ on the <http://soloud-audio.com/downloads.html> page.
 #### Add SoLoud to your project
 
 
-There's a few ways to include SoLoud to your project. Probably the
-easiest is to use GENie / premake4 to create the build files, and build a 
-static library for your compiler / environment.
+There's a few ways to include SoLoud to your project. 
 
-Note that the Windows DLL only exports the  "C" API, which may not 
-be what you want.
+You can, for example, include all the SoLoud source files to your project,
+define one or more of the backend defines (see table below), and you're good
+to go.
+
+A bit more structured way is to use GENie / premake4 to create the build
+files, and build a static library for your compiler / environment.
 
-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. 
+Note that the Windows DLL only exports the  "C" API, which may not 
+be what you want - it's primarily meant for foreign interface use.
 
-You'll need the core files, at least one backend, and at least one 
-audio source. For example, for wav file playing, you'll need the files from
+If you're including the sources directly to your project, You'll need the 
+core files, at least one backend, and at least one audio source. For 
+example, for wav file playing, you'll need the files from
 audiosource/wav. 
 
-If you go this route, you'll need to enable one or more of the back-ends 
-via preprocessor defines. The current list is:
+The current list of back-ends is:
 
 Preprocessor macro  Description
 ----                ------------
+WITH_MINIAUDIO      MiniAudio cross-platform audio backend
 WITH_SDL            SDL or SDL2 via runtime dyndll linking
 WITH_SDL1           SDL1 via runtime dyndll linking
 WITH_SDL2           SDL2 via runtime dyndll linking
@@ -49,7 +51,9 @@ WITH_ALSA           Linux ALSA
 WITH_OPENSLES       OpenSL ES
 WITH_COREAUDIO		OSX CoreAudio
 WITH_VITA_HOMEBREW	Sony Vita homebrew backend
-WITH_NULL           No audio device
+WITH_JACK           Linux JACK
+WITH_NOSOUND        Nosound audio device
+WITH_NULL           Special use "no backend"
 
 The backend with no audio device may seem odd, but that can be used to
 call SoLoud's mix function manually, which can be useful in some cases