From d05f47badbfc33b53e67b927e441d95a7665a6ee Mon Sep 17 00:00:00 2001 From: Marvin Scholz Date: Wed, 26 Nov 2025 15:08:39 +0100 Subject: [PATCH] Docs: Clarify rendering HOAs to binaural doesn't work with MIT HRTF Fix #71 --- docs/AmbisonicBinauralization.md | 4 ++++ docs/RendererOverview.md | 5 +++++ include/AmbisonicBinauralizer.h | 15 +++++++++++---- include/Renderer.h | 6 +++++- 4 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/AmbisonicBinauralization.md b/docs/AmbisonicBinauralization.md index 7cd3485..61ad675 100644 --- a/docs/AmbisonicBinauralization.md +++ b/docs/AmbisonicBinauralization.md @@ -76,6 +76,10 @@ The configuration parameters are: - **HRTFPath**: An optional path to the .SOFA file containing the HRTF. If no path is supplied and the `HAVE_MIT_HRTF` compiler flag is used then the MIT HRTF will be used. - **lowCpuMode**: (Optional) If this is set to true (its default value) then the symmetric head assumption is used to reduce CPU used [[4]](#ref4). +> [!IMPORTANT] +> When libspatialaudios internal MIT HRTF is used instead of SOFA, binauralization +> will only work for 1st order ambisonic, not for HOA like 2nd or 3rd order. + ### Decoding a Signal A B-format signal can be decoded to the binaural signals using the `Process()` function. The processing is non-replacing, so the original B-format signal is unchanged and the decoded signal is contained in the output array. diff --git a/docs/RendererOverview.md b/docs/RendererOverview.md index 4dc3caf..a0d6e20 100644 --- a/docs/RendererOverview.md +++ b/docs/RendererOverview.md @@ -70,6 +70,11 @@ The configuration parameters are: - **reproductionScreen**: (Optional) Reproduction screen details used for screen scaling/locking. - **layoutPositions**: (Optional) Real polar positions for each of the loudspeaker in the layout. This is used if they do not exactly match the ITU specification. Note that they must be within the range allowed by the specification. +> [!IMPORTANT] +> When the renderer is configured for binaural output and the internal MIT HRTF +> is used instead of SOFA, the binauralization will only work for 1st order ambisonics, +> not for higher order ambisonics. + ### AddObject `AddObject()` should be called for every Object stream to be rendered. Its corresponding `ObjectMetadata` should be supplied with it. diff --git a/include/AmbisonicBinauralizer.h b/include/AmbisonicBinauralizer.h index 055c61d..675c734 100644 --- a/include/AmbisonicBinauralizer.h +++ b/include/AmbisonicBinauralizer.h @@ -39,10 +39,17 @@ namespace spaudio { public: AmbisonicBinauralizer(); - /** Re-create the object for the given configuration. Previous data is - * lost. The tailLength variable it updated with the number of taps - * used for the processing, and this can be used to offset the delay - * this causes. The function returns true if the call is successful. + /** + * Configure the ambisonic binauralizer + * + * Re-create the object for the given configuration. Previous data is + * lost. The tailLength variable it updated with the number of taps + * used for the processing, and this can be used to offset the delay + * this causes. The function returns true if the call is successful. + * + * @important + * When libspatialaudios internal MIT HRTF is used instead of SOFA, binauralization + * will only work for 1st order ambisonic, not for higher order ambisonics. * * @param nOrder The order of the signal to be processed. * @param b3D Set to true if the signal to be processed is 3D. Must be true. diff --git a/include/Renderer.h b/include/Renderer.h index b7fd161..6ca4ea1 100644 --- a/include/Renderer.h +++ b/include/Renderer.h @@ -53,7 +53,11 @@ namespace spaudio { Renderer(); ~Renderer(); - /** Configure the ADM Renderer. + /** Configure the Renderer. + * + * @important + * When libspatialaudios internal MIT HRTF is used instead of SOFA, binauralization + * will only work for 1st order ambisonic, not for higher order ambisonics. * * @param outputTarget The target output layout. * @param hoaOrder The ambisonic order of the signal to be rendered.