Move some docs to the docs directory

1 files changed, 74 insertions, 0 deletions

diff --git a/docs/hrtf.txt b/docs/hrtf.txt
new file mode 100644
index 00000000..37a329d2
--- /dev/null
+++ b/docs/hrtf.txt
@@ -0,0 +1,74 @@
+HRTF Support
+============
+
+Starting with OpenAL Soft 1.14, HRTFs can be used to enable enhanced
+spatialization for both 3D (mono) and multi-channel sources, when used with
+headphones/stereo output. This can be enabled using the 'hrtf' config option.
+
+For multi-channel sources this creates a virtual speaker effect, making it
+sound as if speakers provide a discrete position for each channel around the
+listener. For mono sources this provides much more versatility in the perceived
+placement of sounds, making it seem as though they are coming from all around,
+including above and below the listener, instead of just to the front, back, and
+sides.
+
+The default data set is based on the KEMAR HRTF data provided by MIT, which can
+be found at <http://sound.media.mit.edu/resources/KEMAR.html>. It's only
+available when using 44100hz or 48000hz playback.
+
+
+Custom HRTF Data Sets
+=====================
+
+OpenAL Soft also provides an option to use user-specified data sets, in
+addition to or in place of the default set. This allows users to provide their
+own data sets, which could be better suited for their heads, or to work with
+stereo speakers instead of headphones, or to support more playback sample
+rates, for example.
+
+The file format is specified below. It uses little-endian byte order.
+
+==
+ALchar   magic[8] = "MinPHR01";
+ALuint   sampleRate;
+
+ALubyte hrirSize;  /* Can be 8 to 128 in steps of 8. */
+ALubyte evCount;   /* Can be 5 to 128. */
+
+ALubyte azCount[evCount]; /* Each can be 1 to 128. */
+
+/* NOTE: hrirCount is the sum of all azCounts */
+ALshort coefficients[hrirCount][hrirSize];
+ALubyte delays[hrirCount]; /* Each can be 0 to 63. */
+==
+
+The data is described as thus:
+
+The file first starts with the 8-byte marker, "MinPHR01", to identify it as an
+HRTF data set. This is followed by an unsigned 32-bit integer, specifying the
+sample rate the data set is designed for (OpenAL Soft will not use it if the
+output device's playback rate doesn't match).
+
+Afterward, an unsigned 8-bit integer specifies how many sample points (or
+finite impulse response filter coefficients) make up each HRIR.
+
+The following unsigned 8-bit integer specifies the number of elevations used
+by the data set. The elevations start at the bottom (-90 degrees), and
+increment upwards.  Following this is an array of unsigned 8-bit integers, one
+for each elevation which specifies the number of azimuths (and thus HRIRs) that
+make up each elevation.  Azimuths start clockwise from the front, constructing
+a full circle for the left ear only. The right ear uses the same HRIRs but in
+reverse (ie, left = angle, right = 360-angle).
+
+The actual coefficients follow. Each coefficient is a signed 16-bit sample,
+with each HRIR being a consecutive number of sample points.  The HRIRs must be
+minimum-phase.  This allows the use of a smaller filter length, reducing
+computation.  For reference, the built-in data set uses a 32-point filter while
+even the smallest data set provided by MIT used a 128-sample filter (a 4x
+reduction by applying minimum-phase reconstruction). Theoretically, one could
+further reduce the minimum-phase version down to a 16-point filter with only a
+small reduction in quality.
+
+After the coefficients is an array of unsigned 8-bit delay values, one for
+each HRIR. This is the propagation delay (in samples) a signal must wait before
+being convolved with the corresponding minimum-phase HRIR filter.