Add docs for OpenAL Soft and standard decoder presets

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.

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.

presets/3D7.1.ambdec

@@ -0,0 +1,43 @@
+# AmbDec configuration
+# Written by Ambisonic Decoder Toolbox, version 8.0
+
+/description     3D7_2h1v_allrad_5200_rE_max_1_band
+
+/version         	3
+
+/dec/chan_mask   	1bf
+/dec/freq_bands  	1
+/dec/speakers    	7
+/dec/coeff_scale 	fuma
+
+/opt/input_scale  	fuma
+/opt/nfeff_comp   	output
+/opt/delay_comp   	on
+/opt/level_comp   	on
+/opt/xover_freq   	400.000000
+/opt/xover_ratio  	0.000000
+
+/speakers/{
+#           id     dist          azim       elev     conn
+#-----------------------------------------------------------------------
+add_spkr 	LF	 1.500000	  51.000000	 24.000000
+add_spkr 	RF	 1.500000	 -51.000000	 24.000000
+add_spkr 	CE	 1.500000	   0.000000	  0.000000
+add_spkr 	LB	 1.500000	 180.000000	 55.000000
+add_spkr 	RB	 1.500000	   0.000000	-55.000000
+add_spkr 	LS	 1.500000	 129.000000	-24.000000
+add_spkr 	RS	 1.500000	-129.000000	-24.000000
+/}
+
+/matrix/{
+order_gain	1.000000	0.774597	0.400000	0.000000
+add_row 	 0.325031	 0.357638	 0.206500	 0.234037	 0.202440	 0.135692	 0.116927	-0.098768
+add_row 	 0.325036	-0.357619	 0.206537	 0.234033	-0.202427	-0.135680	 0.116934	-0.098768
+add_row 	 0.080073	-0.000010	-0.000296	 0.155843	-0.000016	-0.000011	-0.000623	 0.163306
+add_row 	 0.353556	 0.000002	 0.408453	-0.288377	-0.000004	-0.000003	-0.221039	 0.077297
+add_row 	 0.325297	 0.000008	-0.414018	 0.232789	 0.000004	 0.000003	-0.232940	 0.018311
+add_row 	 0.353558	 0.352704	-0.203542	-0.290124	-0.191868	-0.134582	 0.110616	-0.038294
+add_row 	 0.353556	-0.352691	-0.203576	-0.290115	 0.191871	 0.134585	 0.110612	-0.038293
+/}
+
+/end

presets/hexagon.ambdec

@@ -0,0 +1,51 @@
+# AmbDec configuration
+# Written by Ambisonic Decoder Toolbox, version 8.0
+
+/description     Hexagon_2h0p_pinv_match_rV_max_rE_2_band
+
+/version         	3
+
+/dec/chan_mask   	11b
+/dec/freq_bands  	2
+/dec/speakers    	6
+/dec/coeff_scale 	fuma
+
+/opt/input_scale  	fuma
+/opt/nfeff_comp   	input
+/opt/delay_comp   	on
+/opt/level_comp   	on
+/opt/xover_freq   	400.000000
+/opt/xover_ratio  	0.000000
+
+/speakers/{
+#            id      dist     azim     elev     conn
+#-----------------------------------------------------------------------
+add_spkr 	LF	 1.000000	 30.000000	 0.000000
+add_spkr 	RF	 1.000000	-30.000000	 0.000000
+add_spkr 	RS	 1.000000	-90.000000	 0.000000
+add_spkr 	RB	 1.000000	-150.000000	 0.000000
+add_spkr 	LB	 1.000000	 150.000000	 0.000000
+add_spkr 	LS	 1.000000	 90.000000	 0.000000
+/}
+
+/lfmatrix/{
+order_gain	1.000000	1.000000	1.000000	0.000000
+add_row 	 0.235702	 0.166667	 0.288675	 0.288675	 0.166667
+add_row 	 0.235702	-0.166667	 0.288675	-0.288675	 0.166667
+add_row 	 0.235702	-0.333333	 0.000000	-0.000000	-0.333333
+add_row 	 0.235702	-0.166667	-0.288675	 0.288675	 0.166667
+add_row 	 0.235702	 0.166667	-0.288675	-0.288675	 0.166667
+add_row 	 0.235702	 0.333333	 0.000000	-0.000000	-0.333333
+/}
+
+/hfmatrix/{
+order_gain	1.414214	1.224745	0.707107	0.000000
+add_row 	 0.235702	 0.166667	 0.288675	 0.288675	 0.166667
+add_row 	 0.235702	-0.166667	 0.288675	-0.288675	 0.166667
+add_row 	 0.235702	-0.333333	 0.000000	-0.000000	-0.333333
+add_row 	 0.235702	-0.166667	-0.288675	 0.288675	 0.166667
+add_row 	 0.235702	 0.166667	-0.288675	-0.288675	 0.166667
+add_row 	 0.235702	 0.333333	 0.000000	-0.000000	-0.333333
+/}
+
+/end

presets/presets.txt

@@ -0,0 +1,36 @@
+Ambisonic decoder configuration presets are provided here for common surround
+sound speaker layouts. The presets are prepared to work with OpenAL Soft's high
+quality decoder. By default all of the speaker distances within a preset are
+set to the same value, which results in no effect from distance compensation.
+If this doesn't match your physical speaker setup, it may be worth copying the
+preset and modifying the distance values to match (note that modifying the
+azimuth and elevation values in the presets will not have any effect; the
+specified angles do not change the decoder behavior).
+
+Details of the individual presets are as follows.
+
+square.ambdec
+Specifies a basic square speaker setup for Quadrophonic output, with identical
+width and depth. Front speakers are placed at +45 and -45 degrees, and back
+speakers are placed at +135 and -135 degrees.
+
+rectangle.ambdec
+Specifies a narrower speaker setup for Quadrophonic output, with a little less
+width but a little more depth over a basic square setup. Front speakers are
+placed at +30 and -30 degrees, providing a bit more compatibility for existing
+stereo content, with back speakers at +150 and -150 degrees.
+
+hexagon.ambdec
+Specifies a flat-front hexagonal speaker setup for 7.1 Surround output. The
+front left and right speakers are placed at +30 and -30 degrees, the side
+speakers are placed at +90 and -90 degrees, and the back speakers are placed at
++150 and -150 degrees. Although this is for 7.1 output, no front-center speaker
+is defined for the decoder, meaning that speaker will be silent for 3D sound
+(however it may still be used with AL_SOFT_direct_channels or ALC_EXT_DEDICATED
+output). A "proper" 7.1 decoder may be provided in the future, but due to the
+nature of the speaker configuration will have trade-offs.
+
+3D7.1.ambdec
+Specifies a 3D7.1 speaker setup for 7.1 Surround output. Although it's for 7.1
+output, the speakers for such a configuration need to be placed in different
+positions for proper results. Please see docs/3D7.1.txt for more information.

presets/rectangle.ambdec

@@ -0,0 +1,45 @@
+# AmbDec configuration
+# Written by Ambisonic Decoder Toolbox, version 8.0
+
+/description     Rectangle_1h0p_pinv_match_rV_max_rE_2_band
+
+/version         	3
+
+/dec/chan_mask   	b
+/dec/freq_bands  	2
+/dec/speakers    	4
+/dec/coeff_scale 	fuma
+
+/opt/input_scale  	fuma
+/opt/nfeff_comp   	input
+/opt/delay_comp   	on
+/opt/level_comp   	on
+/opt/xover_freq   	400.000000
+/opt/xover_ratio  	0.000000
+
+/speakers/{
+#            id      dist     azim     elev     conn
+#-----------------------------------------------------------------------
+add_spkr 	LF	 1.000000	 30.000000	 0.000000
+add_spkr 	RF	 1.000000	-30.000000	 0.000000
+add_spkr 	RB	 1.000000	-150.000000	 0.000000
+add_spkr 	LB	 1.000000	 150.000000	 0.000000
+/}
+
+/lfmatrix/{
+order_gain	1.000000	1.000000	0.000000	0.000000
+add_row 	 0.353553	 0.500000	 0.288675
+add_row 	 0.353553	-0.500000	 0.288675
+add_row 	 0.353553	-0.500000	-0.288675
+add_row 	 0.353553	 0.500000	-0.288675
+/}
+
+/hfmatrix/{
+order_gain	1.414214	1.000000	0.000000	0.000000
+add_row 	 0.353553	 0.500000	 0.288675
+add_row 	 0.353553	-0.500000	 0.288675
+add_row 	 0.353553	-0.500000	-0.288675
+add_row 	 0.353553	 0.500000	-0.288675
+/}
+
+/end