Update mhr format for 24-bit, multi-field, stereo measurements

Currently only single field HRTFs are supported, but the format now allows up
to 16.

1 files changed, 38 insertions, 28 deletions

diff --git a/docs/hrtf.txt b/docs/hrtf.txt
index 37a329d2..ba8cd8fa 100644
--- a/docs/hrtf.txt
+++ b/docs/hrtf.txt
@@ -29,22 +29,31 @@ rates, for example.
 The file format is specified below. It uses little-endian byte order.
 
 ==
-ALchar   magic[8] = "MinPHR01";
+ALchar   magic[8] = "MinPHR02";
 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. */
+ALubyte  sampleType;  /* Can be 0 (16-bit) or 1 (24-bit). */
+ALubyte  channelType; /* Can be 0 (mono) or 1 (stereo). */
+ALubyte  hrirSize;    /* Can be 8 to 128 in steps of 8. */
+ALubyte  fdCount;     /* Can be 1 to 16. */
+
+struct {
+    ALushort distance;        /* Can be 50mm to 2500mm. */
+    ALubyte evCount;          /* Can be 5 to 128. */
+    ALubyte azCount[evCount]; /* Each can be 1 to 128. */
+} fields[fdCount];
+
+/* NOTE: ALtype can be ALshort (16-bit) or ALbyte[3] (24-bit) depending on
+ * sampleType,
+ * hrirCount is the sum of all azCounts.
+ * channels can be 1 (mono) or 2 (stereo) depending on channelType.
+ */
+ALtype coefficients[hrirCount][hrirSize][channels];
+ALubyte delays[hrirCount][channels]; /* 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
+The file first starts with the 8-byte marker, "MinPHR02", 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).
@@ -52,23 +61,24 @@ 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
+The following unsigned 8-bit integer specifies the number of fields used by the
+data set.  Then for each field an unsigned 16-bit short specifies the distance
+for that field (in millimeters), followed by an 8-bit integer for the number of
+elevations.  These 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.  Mono HRTFs use the same HRIRs for both ears by reversing the azimuth
+calculation (ie. left = angle, right = 360-angle).
+
+The actual coefficients follow. Each coefficient is a signed 16-bit or 24-bit
+sample.  Stereo HRTFs interleave left/right ear coefficients.  The HRIRs must
+be minimum-phase.  This allows the use of a smaller filter length, reducing
+computation.  For reference, the default 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.
+reduction by applying minimum-phase reconstruction).
 
 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.
+each HRIR (with stereo HRTFs interleaving left/right ear delays). This is the
+propagation delay (in samples) a signal must wait before being convolved with
+the corresponding minimum-phase HRIR filter.