Add docs for OpenAL Soft and standard decoder presets

2 files changed, 201 insertions, 0 deletions

diff --git a/docs/3D7.1.txt b/docs/3D7.1.txt
new file mode 100644
index 00000000..1d40bec6
--- /dev/null
+++ b/docs/3D7.1.txt
@@ -0,0 +1,82 @@
+Overview
+========
+
+3D7.1 is a custom speaker layout designed by Simon Goodwin at Codemasters[1].
+Typical surround sound setups, like quad, 5.1, 6.1, and 7.1, only produce audio
+on a 2D horizontal plane with no verticality, which means the envelopment of
+"surround" sound is limited to left, right, front, and back panning. Sounds
+that should come from above or below will still only play in 2D since there is
+no height difference in the speaker array.
+
+To work around this, 3D7.1 was designed so that some speakers are placed higher
+than the listener while others are lower, in a particular configuration that
+tries to provide balanced output and maintain some compatibility with existing
+audio content and software. Software that recognizes this setup, or can be
+configured for it, can then take advantage of the height difference and
+increase the perception of verticality for true 3D audio. The result is that
+sounds can be perceived as coming from left, right, front, and back, as well as
+up and down.
+
+[1] http://www.codemasters.com/research/3D_sound_for_3D_games.pdf
+
+
+Hardware Setup
+==============
+
+Setting up 3D7.1 requires an audio device capable of raw 8-channel or 7.1
+output, along with a 7.1 speaker kit. The speakers should be hooked up to the
+device in the usual way, with front-left and front-right output going to the
+front-left and front-right speakers, etc. The placement of the speakers should
+be set up according to the table below. Azimuth is the horizontal angle in
+degrees, with 0 directly in front and positive values go /left/, and elevation
+is the vertical angle in degrees, with 0 at head level and positive values go
+/up/.
+
+------------------------------------------------------------
+- Speaker label | Azimuth | Elevation |      New label     -
+------------------------------------------------------------
+- Front left    |    51   |     24    |   Upper front left -
+- Front right   |   -51   |     24    |  Upper front right -
+- Front center  |     0   |      0    |       Front center -
+- Subwoofer/LFE |   N/A   |    N/A    |      Subwoofer/LFE -
+- Side left     |   129   |    -24    |    Lower back left -
+- Side right    |  -129   |    -24    |   Lower back right -
+- Back left     |   180   |     55    |  Upper back center -
+- Back right    |     0   |    -55    | Lower front center -
+------------------------------------------------------------
+
+Note that this speaker layout *IS NOT* compatible with standard 7.1 content.
+Audio that should be played from the back will come out at the wrong location
+since the back speakers are placed in the lower front and upper back positions.
+However, this speaker layout *IS* more or less compatible with standard 5.1
+content. Though slightly tilted, to a listener sitting a bit further back from
+the center, the front and side speakers will be close enough to their intended
+locations that the output won't be too off.
+
+
+Software Setup
+==============
+
+To enable 3D7.1 on OpenAL Soft, first make sure the audio device is configured
+for 7.1 output. Then in the alsoft-config utility, under the Renderer tab,
+select the 3D7.1.ambdec preset for the 7.1 Surround decoder configuration. And
+that's it. Any applications using OpenAL Soft can take advantage of fully 3D
+audio, and multi-channel sounds will be properly remixed for the speaker
+layout.
+
+Playback can be improved by (copying and) modifying the 3D7.1.ambdec preset,
+changing the specified speaker distances to match the the real distance (in
+meters) from the center of the speaker array, then enable High Quality Mode in
+alsoft-config. That will improve the quality when the speakers are not all
+equidistant.
+
+Note that care must be taken that the audio device is not treated as a "true"
+7.1 device by non-3D7.1-capable applications. In particular, the audio server
+should not try to upmix stereo and 5.1 content to "fill out" the back speakers,
+and non-3D7.1 apps should be set to either stereo or 5.1 output.
+
+As such, if your system is capable of it, it may be useful to define a virtual
+5.1 device that maps the front, side, and LFE channels to the main device for
+output and disables upmixing, then use that virtual 5.1 device for apps that do
+normal stereo or surround sound output, and use the main device for apps that
+understand 3D7.1 output.
diff --git a/docs/ambisonics.txt b/docs/ambisonics.txt
new file mode 100644
index 00000000..77ec8ef7
--- /dev/null
+++ b/docs/ambisonics.txt
@@ -0,0 +1,119 @@
+OpenAL Soft's renderer has advanced quite a bit since its start with panned
+stereo output. Among these advancements is support for surround sound output,
+using psychoacoustic modeling and more accurate plane wave reconstruction. The
+concepts in use may not be immediately obvious to people just getting into 3D
+audio, or people who only have more indirect experience through the use of 3D
+audio APIs, so this document aims to introduce the ideas and purpose of
+Ambisonics as used by OpenAL Soft.
+
+
+What Is It?
+===========
+
+Originally developed in the 1970s by Michael Gerzon and a team others,
+Ambisonics was created as a means of recording and playing back 3D sound.
+Taking advantage of the way sound waves propogate, it is possible to record a
+fully 3D soundfield using as few as 4 channels (or even just 3, if you don't
+mind dropping down to 2 dimensions like many surround sound systems are). This
+representation is called B-Format. It was designed to handle audio independent
+of any specific speaker layout, so with a proper decoder the same recording can
+be played back on a variety of speaker setups, from quadrophonic and hexagonal
+to cubic and other periphonic (with height) layouts.
+
+Although it was developed over 30 years ago, various factors held ambisonics
+back from really taking hold in the consumer market. However, given the solid
+theories backing it, as well as the potential and practical benefits on offer,
+it continued to be a topic of research over the years, with improvements being
+made over the original design. One of the improvements made is the use of
+Spherical Harmonics to increase the number of channels for greater spatial
+definition. Where the original 4-channel design is termed as "First-Order
+Ambisonics", or FOA, the increased channel count through the use of Spherical
+Harmonics is termed as "Higher-Order Ambisonics", or HOA. The details of higher
+order ambisonics are out of the scope of this document, but know that the added
+channels are still independent of any speaker layout, and aim to further
+improve the spatial detail for playback.
+
+Today, the processing power available on even low-end computers means real-time
+Ambisonics processing is possible. Not only can decoders be implemented in
+software, but so can encoders, synthesizing a soundfield using multiple panned
+sources, thus taking advantage of what ambisonics offers in a virtual audio
+environment.
+
+
+How Does It Help?
+=================
+
+Positional sound has come a long way from pan-pot stereo (aka pair-wise).
+Although useful at the time, the issues became readily apparent when trying to
+extend it for surround sound. Pan-pot doesn't work as well for depth (front-
+back) or vertical panning, it has a rather small "sweet spot" (the area the
+head needs to be in to perceive the sound in its intended direction), and it
+misses key distance-related details of sound waves.
+
+Ambisonics takes a different approach. It uses all available speakers to help
+localize a sound, and it also takes into account how the brain localizes low
+frequency sounds compared to high frequency ones -- a so-called psychoacoustic
+model. It may seem counter-intuitive (if a sound is coming from the front-left,
+surely just play it on the front-left speaker?), but to properly model a sound
+coming from where a speaker doesn't exist, more needs to be done to construct a
+proper sound wave that's perceived to come from the intended direction. Doing
+this creates a larger sweet spot, allowing the perceived sound direction to
+remain correct over a larger area around the center of the speakers.
+
+
+How Is It Used?
+===============
+
+As a 3D audio API, OpenAL is tasked with playing 3D sound as best it can with
+the speaker setup the user has. Since the OpenAL API does not explicitly handle
+the output channel configuration, it has a lot of leeway in how to deal with
+the audio before it's played back for the user to hear. Consequently, OpenAL
+Soft (or any other OpenAL implementation that wishes to) can render using
+Ambisonics and decode the ambisonic mix for a high level of directional
+accuracy over what simple pan-pot could provide.
+
+This is effectively what the high-quality mode option does, when given an
+appropriate decoder configuation for the playback channel layout. 3D rendering
+is done to an ambisonic buffer, which is later decoded for output utilizing the
+benefits available to ambisonic processing.
+
+The basic, non-high-quality, renderer uses similar principles, however it skips
+the frequency-dependent processing (so low frequency sounds are treated the
+same as high frequency sounds) and does some creative manipulation of the
+involved math to skip the intermediate ambisonic buffer, rendering more
+directly to the output while still taking advantage of all the available
+speakers to reconstruct the sound wave. This method trades away some playback
+quality for less memory and processor usage.
+
+In addition to providing good support for surround sound playback, Ambisonics
+also has benefits with stereo output. 2-channel UHJ is a stereo-compatible
+format that encodes some surround sound information using a wide-band 90-degree
+phase shift filter. It works by taking a B-Format signal, then deriving a
+frontal stereo mix with some of the rear sounds filtered in with it. Although
+the result is not as good as 3-channel (2D) B-Format, it has the distinct
+advantage of only using 2 channels and being compatible with stereo output.
+This means it will sound just fine when played as-is through a normal stereo
+device, or it may optionally be fed to a properly configured surround sound
+receiver which can extract the encoded information and restore some of the
+original surround sound signal.
+
+
+What Are Its Limitations?
+=========================
+
+As good as Ambisonics is, it's not a magic bullet that can overcome all
+problems. One of the bigger issues it has is dealing with irregular speaker
+setups, such as 5.1 surround sound. The problem mainly lies in the imbalanced
+speaker positioning -- there are three speakers within the front 60-degree area
+(meaning only 30-degree gaps in between each of the three speakers), while only
+two speakers cover the back 140-degree area, leaving 80-degree gaps on the
+sides. It should be noted that this problem is inherent to the speaker layout
+itself; there isn't much that can be done to get an optimal surround sound
+response, with ambisonics or not. It will do the best it can, but there are
+trade-offs between detail and accuracy.
+
+Another issue lies with HRTF. While it's certainly possible to play an
+ambisonic mix using HRTF, doing so with a high degree of spatial detail
+requires a fair amount of resources, in both memory and processing time. And
+even with it, mixing sounds with HRTF directly will still be better for
+positional accuracy.