alc/panning.cpp

   1 /**
   2  * OpenAL cross platform audio library
   3  * Copyright (C) 1999-2010 by authors.
   4  * This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU Library General Public
   6  *  License as published by the Free Software Foundation; either
   7  *  version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  *  Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  *  License along with this library; if not, write to the
  16  *  Free Software Foundation, Inc.,
  17  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  * Or go to http://www.gnu.org/copyleft/lgpl.html
  19  */
  20
  21 #include "config.h"
  22
  23 #include <algorithm>
  24 #include <array>
  25 #include <cassert>
  26 #include <chrono>
  27 #include <cmath>
  28 #include <cstdio>
  29 #include <cstring>
  30 #include <functional>
  31 #include <iterator>
  32 #include <memory>
  33 #include <new>
  34 #include <numeric>
  35 #include <optional>
  36 #include <string>
  37 #include <vector>
  38
  39 #include "AL/al.h"
  40 #include "AL/alc.h"
  41 #include "AL/alext.h"
  42
  43 #include "al/auxeffectslot.h"
  44 #include "albit.h"
  45 #include "alconfig.h"
  46 #include "alc/context.h"
  47 #include "almalloc.h"
  48 #include "alnumbers.h"
  49 #include "alnumeric.h"
  50 #include "alspan.h"
  51 #include "alstring.h"
  52 #include "alu.h"
  53 #include "core/ambdec.h"
  54 #include "core/ambidefs.h"
  55 #include "core/bformatdec.h"
  56 #include "core/bs2b.h"
  57 #include "core/devformat.h"
  58 #include "core/front_stablizer.h"
  59 #include "core/hrtf.h"
  60 #include "core/logging.h"
  61 #include "core/uhjfilter.h"
  62 #include "device.h"
  63 #include "opthelpers.h"
  64
  65
  66 namespace {
  67
  68 using namespace std::string_view_literals;
  69 using std::chrono::seconds;
  70 using std::chrono::nanoseconds;
  71
  72 inline const char *GetLabelFromChannel(Channel channel)
  73 {
  74     switch(channel)
  75     {
  76         case FrontLeft: return "front-left";
  77         case FrontRight: return "front-right";
  78         case FrontCenter: return "front-center";
  79         case LFE: return "lfe";
  80         case BackLeft: return "back-left";
  81         case BackRight: return "back-right";
  82         case BackCenter: return "back-center";
  83         case SideLeft: return "side-left";
  84         case SideRight: return "side-right";
  85
  86         case TopFrontLeft: return "top-front-left";
  87         case TopFrontCenter: return "top-front-center";
  88         case TopFrontRight: return "top-front-right";
  89         case TopCenter: return "top-center";
  90         case TopBackLeft: return "top-back-left";
  91         case TopBackCenter: return "top-back-center";
  92         case TopBackRight: return "top-back-right";
  93
  94         case Aux0: return "Aux0";
  95         case Aux1: return "Aux1";
  96         case Aux2: return "Aux2";
  97         case Aux3: return "Aux3";
  98         case Aux4: return "Aux4";
  99         case Aux5: return "Aux5";
 100         case Aux6: return "Aux6";
 101         case Aux7: return "Aux7";
 102         case Aux8: return "Aux8";
 103         case Aux9: return "Aux9";
 104         case Aux10: return "Aux10";
 105         case Aux11: return "Aux11";
 106         case Aux12: return "Aux12";
 107         case Aux13: return "Aux13";
 108         case Aux14: return "Aux14";
 109         case Aux15: return "Aux15";
 110
 111         case MaxChannels: break;
 112     }
 113     return "(unknown)";
 114 }
 115
 116
 117 std::unique_ptr<FrontStablizer> CreateStablizer(const size_t outchans, const uint srate)
 118 {
 119     auto stablizer = FrontStablizer::Create(outchans);
 120
 121     /* Initialize band-splitting filter for the mid signal, with a crossover at
 122      * 5khz (could be higher).
 123      */
 124     stablizer->MidFilter.init(5000.0f / static_cast<float>(srate));
 125     for(auto &filter : stablizer->ChannelFilters)
 126         filter = stablizer->MidFilter;
 127
 128     return stablizer;
 129 }
 130
 131 void AllocChannels(ALCdevice *device, const size_t main_chans, const size_t real_chans)
 132 {
 133     TRACE("Channel config, Main: %zu, Real: %zu\n", main_chans, real_chans);
 134
 135     /* Allocate extra channels for any post-filter output. */
 136     const size_t num_chans{main_chans + real_chans};
 137
 138     TRACE("Allocating %zu channels, %zu bytes\n", num_chans,
 139         num_chans*sizeof(device->MixBuffer[0]));
 140     device->MixBuffer.resize(num_chans);
 141     al::span<FloatBufferLine> buffer{device->MixBuffer};
 142
 143     device->Dry.Buffer = buffer.first(main_chans);
 144     buffer = buffer.subspan(main_chans);
 145     if(real_chans != 0)
 146     {
 147         device->RealOut.Buffer = buffer.first(real_chans);
 148         buffer = buffer.subspan(real_chans);
 149     }
 150     else
 151         device->RealOut.Buffer = device->Dry.Buffer;
 152 }
 153
 154
 155 using ChannelCoeffs = std::array<float,MaxAmbiChannels>;
 156 enum DecoderMode : bool {
 157     SingleBand = false,
 158     DualBand = true
 159 };
 160
 161 template<DecoderMode Mode, size_t N>
 162 struct DecoderConfig;
 163
 164 template<size_t N>
 165 struct DecoderConfig<SingleBand, N> {
 166     uint8_t mOrder{};
 167     bool mIs3D{};
 168     std::array<Channel,N> mChannels{};
 169     DevAmbiScaling mScaling{};
 170     std::array<float,MaxAmbiOrder+1> mOrderGain{};
 171     std::array<ChannelCoeffs,N> mCoeffs{};
 172 };
 173
 174 template<size_t N>
 175 struct DecoderConfig<DualBand, N> {
 176     uint8_t mOrder{};
 177     bool mIs3D{};
 178     std::array<Channel,N> mChannels{};
 179     DevAmbiScaling mScaling{};
 180     std::array<float,MaxAmbiOrder+1> mOrderGain{};
 181     std::array<ChannelCoeffs,N> mCoeffs{};
 182     std::array<float,MaxAmbiOrder+1> mOrderGainLF{};
 183     std::array<ChannelCoeffs,N> mCoeffsLF{};
 184 };
 185
 186 template<>
 187 struct DecoderConfig<DualBand, 0> {
 188     uint8_t mOrder{};
 189     bool mIs3D{};
 190     al::span<const Channel> mChannels;
 191     DevAmbiScaling mScaling{};
 192     al::span<const float> mOrderGain;
 193     al::span<const ChannelCoeffs> mCoeffs;
 194     al::span<const float> mOrderGainLF;
 195     al::span<const ChannelCoeffs> mCoeffsLF;
 196
 197     template<size_t N>
 198     DecoderConfig& operator=(const DecoderConfig<SingleBand,N> &rhs) noexcept
 199     {
 200         mOrder = rhs.mOrder;
 201         mIs3D = rhs.mIs3D;
 202         mChannels = rhs.mChannels;
 203         mScaling = rhs.mScaling;
 204         mOrderGain = rhs.mOrderGain;
 205         mCoeffs = rhs.mCoeffs;
 206         mOrderGainLF = {};
 207         mCoeffsLF = {};
 208         return *this;
 209     }
 210
 211     template<size_t N>
 212     DecoderConfig& operator=(const DecoderConfig<DualBand,N> &rhs) noexcept
 213     {
 214         mOrder = rhs.mOrder;
 215         mIs3D = rhs.mIs3D;
 216         mChannels = rhs.mChannels;
 217         mScaling = rhs.mScaling;
 218         mOrderGain = rhs.mOrderGain;
 219         mCoeffs = rhs.mCoeffs;
 220         mOrderGainLF = rhs.mOrderGainLF;
 221         mCoeffsLF = rhs.mCoeffsLF;
 222         return *this;
 223     }
 224
 225     explicit operator bool() const noexcept { return !mChannels.empty(); }
 226 };
 227 using DecoderView = DecoderConfig<DualBand, 0>;
 228
 229
 230 void InitNearFieldCtrl(ALCdevice *device, const float ctrl_dist, const uint order, const bool is3d)
 231 {
 232     static const std::array<uint,MaxAmbiOrder+1> chans_per_order2d{{1, 2, 2, 2}};
 233     static const std::array<uint,MaxAmbiOrder+1> chans_per_order3d{{1, 3, 5, 7}};
 234
 235     /* NFC is only used when AvgSpeakerDist is greater than 0. */
 236     if(!device->getConfigValueBool("decoder", "nfc", false) || !(ctrl_dist > 0.0f))
 237         return;
 238
 239     device->AvgSpeakerDist = clampf(ctrl_dist, 0.1f, 10.0f);
 240     TRACE("Using near-field reference distance: %.2f meters\n", device->AvgSpeakerDist);
 241
 242     const float w1{SpeedOfSoundMetersPerSec /
 243         (device->AvgSpeakerDist * static_cast<float>(device->Frequency))};
 244     device->mNFCtrlFilter.init(w1);
 245
 246     auto iter = std::copy_n(is3d ? chans_per_order3d.begin() : chans_per_order2d.begin(), order+1u,
 247         std::begin(device->NumChannelsPerOrder));
 248     std::fill(iter, std::end(device->NumChannelsPerOrder), 0u);
 249 }
 250
 251 void InitDistanceComp(ALCdevice *device, const al::span<const Channel> channels,
 252     const al::span<const float,MaxOutputChannels> dists)
 253 {
 254     const float maxdist{std::accumulate(std::begin(dists), std::end(dists), 0.0f, maxf)};
 255
 256     if(!device->getConfigValueBool("decoder", "distance-comp", true) || !(maxdist > 0.0f))
 257         return;
 258
 259     const auto distSampleScale = static_cast<float>(device->Frequency) / SpeedOfSoundMetersPerSec;
 260     std::vector<DistanceComp::ChanData> ChanDelay;
 261     ChanDelay.reserve(device->RealOut.Buffer.size());
 262     size_t total{0u};
 263     for(size_t chidx{0};chidx < channels.size();++chidx)
 264     {
 265         const Channel ch{channels[chidx]};
 266         const uint idx{device->RealOut.ChannelIndex[ch]};
 267         if(idx == InvalidChannelIndex)
 268             continue;
 269
 270         const float distance{dists[chidx]};
 271
 272         /* Distance compensation only delays in steps of the sample rate. This
 273          * is a bit less accurate since the delay time falls to the nearest
 274          * sample time, but it's far simpler as it doesn't have to deal with
 275          * phase offsets. This means at 48khz, for instance, the distance delay
 276          * will be in steps of about 7 millimeters.
 277          */
 278         float delay{std::floor((maxdist - distance)*distSampleScale + 0.5f)};
 279         if(delay > float{DistanceComp::MaxDelay-1})
 280         {
 281             ERR("Delay for channel %u (%s) exceeds buffer length (%f > %d)\n", idx,
 282                 GetLabelFromChannel(ch), delay, DistanceComp::MaxDelay-1);
 283             delay = float{DistanceComp::MaxDelay-1};
 284         }
 285
 286         ChanDelay.resize(maxz(ChanDelay.size(), idx+1));
 287         ChanDelay[idx].Length = static_cast<uint>(delay);
 288         ChanDelay[idx].Gain = distance / maxdist;
 289         TRACE("Channel %s distance comp: %u samples, %f gain\n", GetLabelFromChannel(ch),
 290             ChanDelay[idx].Length, ChanDelay[idx].Gain);
 291
 292         /* Round up to the next 4th sample, so each channel buffer starts
 293          * 16-byte aligned.
 294          */
 295         total += RoundUp(ChanDelay[idx].Length, 4);
 296     }
 297
 298     if(total > 0)
 299     {
 300         auto chandelays = DistanceComp::Create(total);
 301
 302         ChanDelay[0].Buffer = chandelays->mSamples.data();
 303         auto set_bufptr = [](const DistanceComp::ChanData &last, const DistanceComp::ChanData &cur)
 304             -> DistanceComp::ChanData
 305         {
 306             DistanceComp::ChanData ret{cur};
 307             ret.Buffer = last.Buffer + RoundUp(last.Length, 4);
 308             return ret;
 309         };
 310         std::partial_sum(ChanDelay.begin(), ChanDelay.end(), chandelays->mChannels.begin(),
 311             set_bufptr);
 312         device->ChannelDelays = std::move(chandelays);
 313     }
 314 }
 315
 316
 317 constexpr auto GetAmbiScales(DevAmbiScaling scaletype) noexcept
 318 {
 319     if(scaletype == DevAmbiScaling::FuMa) return al::span{AmbiScale::FromFuMa};
 320     if(scaletype == DevAmbiScaling::SN3D) return al::span{AmbiScale::FromSN3D};
 321     return al::span{AmbiScale::FromN3D};
 322 }
 323
 324 constexpr auto GetAmbiLayout(DevAmbiLayout layouttype) noexcept
 325 {
 326     if(layouttype == DevAmbiLayout::FuMa) return al::span{AmbiIndex::FromFuMa};
 327     return al::span{AmbiIndex::FromACN};
 328 }
 329
 330
 331 DecoderView MakeDecoderView(ALCdevice *device, const AmbDecConf *conf,
 332     DecoderConfig<DualBand,MaxOutputChannels> &decoder)
 333 {
 334     DecoderView ret{};
 335
 336     decoder.mOrder = (conf->ChanMask > Ambi3OrderMask) ? uint8_t{4} :
 337         (conf->ChanMask > Ambi2OrderMask) ? uint8_t{3} :
 338         (conf->ChanMask > Ambi1OrderMask) ? uint8_t{2} : uint8_t{1};
 339     decoder.mIs3D = (conf->ChanMask&AmbiPeriphonicMask) != 0;
 340
 341     switch(conf->CoeffScale)
 342     {
 343     case AmbDecScale::Unset: ASSUME(false); break;
 344     case AmbDecScale::N3D: decoder.mScaling = DevAmbiScaling::N3D; break;
 345     case AmbDecScale::SN3D: decoder.mScaling = DevAmbiScaling::SN3D; break;
 346     case AmbDecScale::FuMa: decoder.mScaling = DevAmbiScaling::FuMa; break;
 347     }
 348
 349     std::copy_n(std::begin(conf->HFOrderGain),
 350         std::min(std::size(conf->HFOrderGain), std::size(decoder.mOrderGain)),
 351         std::begin(decoder.mOrderGain));
 352     std::copy_n(std::begin(conf->LFOrderGain),
 353         std::min(std::size(conf->LFOrderGain), std::size(decoder.mOrderGainLF)),
 354         std::begin(decoder.mOrderGainLF));
 355
 356     const auto num_coeffs = decoder.mIs3D ? AmbiChannelsFromOrder(decoder.mOrder)
 357         : Ambi2DChannelsFromOrder(decoder.mOrder);
 358     const auto idx_map = decoder.mIs3D ? AmbiIndex::FromACN.data()
 359         : AmbiIndex::FromACN2D.data();
 360     const auto hfmatrix = conf->HFMatrix;
 361     const auto lfmatrix = conf->LFMatrix;
 362
 363     uint chan_count{0};
 364     for(auto &speaker : al::span<const AmbDecConf::SpeakerConf>{conf->Speakers})
 365     {
 366         /* NOTE: AmbDec does not define any standard speaker names, however
 367          * for this to work we have to by able to find the output channel
 368          * the speaker definition corresponds to. Therefore, OpenAL Soft
 369          * requires these channel labels to be recognized:
 370          *
 371          * LF = Front left
 372          * RF = Front right
 373          * LS = Side left
 374          * RS = Side right
 375          * LB = Back left
 376          * RB = Back right
 377          * CE = Front center
 378          * CB = Back center
 379          * LFT = Top front left
 380          * RFT = Top front right
 381          * LBT = Top back left
 382          * RBT = Top back right
 383          *
 384          * Additionally, surround51 will acknowledge back speakers for side
 385          * channels, to avoid issues with an ambdec expecting 5.1 to use the
 386          * back channels.
 387          */
 388         Channel ch{};
 389         if(speaker.Name == "LF")
 390             ch = FrontLeft;
 391         else if(speaker.Name == "RF")
 392             ch = FrontRight;
 393         else if(speaker.Name == "CE")
 394             ch = FrontCenter;
 395         else if(speaker.Name == "LS")
 396             ch = SideLeft;
 397         else if(speaker.Name == "RS")
 398             ch = SideRight;
 399         else if(speaker.Name == "LB")
 400             ch = (device->FmtChans == DevFmtX51) ? SideLeft : BackLeft;
 401         else if(speaker.Name == "RB")
 402             ch = (device->FmtChans == DevFmtX51) ? SideRight : BackRight;
 403         else if(speaker.Name == "CB")
 404             ch = BackCenter;
 405         else if(speaker.Name == "LFT")
 406             ch = TopFrontLeft;
 407         else if(speaker.Name == "RFT")
 408             ch = TopFrontRight;
 409         else if(speaker.Name == "LBT")
 410             ch = TopBackLeft;
 411         else if(speaker.Name == "RBT")
 412             ch = TopBackRight;
 413         else
 414         {
 415             int idx{};
 416             char c{};
 417             if(sscanf(speaker.Name.c_str(), "AUX%d%c", &idx, &c) != 1 || idx < 0
 418                 || idx >= MaxChannels-Aux0)
 419             {
 420                 ERR("AmbDec speaker label \"%s\" not recognized\n", speaker.Name.c_str());
 421                 continue;
 422             }
 423             ch = static_cast<Channel>(Aux0+idx);
 424         }
 425
 426         decoder.mChannels[chan_count] = ch;
 427         for(size_t dst{0};dst < num_coeffs;++dst)
 428         {
 429             const size_t src{idx_map[dst]};
 430             decoder.mCoeffs[chan_count][dst] = hfmatrix[chan_count][src];
 431         }
 432         if(conf->FreqBands > 1)
 433         {
 434             for(size_t dst{0};dst < num_coeffs;++dst)
 435             {
 436                 const size_t src{idx_map[dst]};
 437                 decoder.mCoeffsLF[chan_count][dst] = lfmatrix[chan_count][src];
 438             }
 439         }
 440         ++chan_count;
 441     }
 442
 443     if(chan_count > 0)
 444     {
 445         ret.mOrder = decoder.mOrder;
 446         ret.mIs3D = decoder.mIs3D;
 447         ret.mScaling = decoder.mScaling;
 448         ret.mChannels = {decoder.mChannels.data(), chan_count};
 449         ret.mOrderGain = decoder.mOrderGain;
 450         ret.mCoeffs = {decoder.mCoeffs.data(), chan_count};
 451         if(conf->FreqBands > 1)
 452         {
 453             ret.mOrderGainLF = decoder.mOrderGainLF;
 454             ret.mCoeffsLF = {decoder.mCoeffsLF.data(), chan_count};
 455         }
 456     }
 457     return ret;
 458 }
 459
 460 constexpr DecoderConfig<SingleBand, 1> MonoConfig{
 461     0, false, {{FrontCenter}},
 462     DevAmbiScaling::N3D,
 463     {{1.0f}},
 464     {{ {{1.0f}} }}
 465 };
 466 constexpr DecoderConfig<SingleBand, 2> StereoConfig{
 467     1, false, {{FrontLeft, FrontRight}},
 468     DevAmbiScaling::N3D,
 469     {{1.0f, 1.0f}},
 470     {{
 471         {{5.00000000e-1f,  2.88675135e-1f,  5.52305643e-2f}},
 472         {{5.00000000e-1f, -2.88675135e-1f,  5.52305643e-2f}},
 473     }}
 474 };
 475 constexpr DecoderConfig<DualBand, 4> QuadConfig{
 476     1, false, {{BackLeft, FrontLeft, FrontRight, BackRight}},
 477     DevAmbiScaling::N3D,
 478     /*HF*/{{1.41421356e+0f, 1.00000000e+0f}},
 479     {{
 480         {{2.50000000e-1f,  2.04124145e-1f, -2.04124145e-1f}},
 481         {{2.50000000e-1f,  2.04124145e-1f,  2.04124145e-1f}},
 482         {{2.50000000e-1f, -2.04124145e-1f,  2.04124145e-1f}},
 483         {{2.50000000e-1f, -2.04124145e-1f, -2.04124145e-1f}},
 484     }},
 485     /*LF*/{{1.00000000e+0f, 1.00000000e+0f}},
 486     {{
 487         {{2.50000000e-1f,  2.04124145e-1f, -2.04124145e-1f}},
 488         {{2.50000000e-1f,  2.04124145e-1f,  2.04124145e-1f}},
 489         {{2.50000000e-1f, -2.04124145e-1f,  2.04124145e-1f}},
 490         {{2.50000000e-1f, -2.04124145e-1f, -2.04124145e-1f}},
 491     }}
 492 };
 493 constexpr DecoderConfig<DualBand, 5> X51Config{
 494     2, false, {{SideLeft, FrontLeft, FrontCenter, FrontRight, SideRight}},
 495     DevAmbiScaling::FuMa,
 496     /*HF*/{{1.00000000e+0f, 1.00000000e+0f, 1.00000000e+0f}},
 497     {{
 498         {{5.67316000e-1f,  4.22920000e-1f, -3.15495000e-1f, -6.34490000e-2f, -2.92380000e-2f}},
 499         {{3.68584000e-1f,  2.72349000e-1f,  3.21616000e-1f,  1.92645000e-1f,  4.82600000e-2f}},
 500         {{1.83579000e-1f,  0.00000000e+0f,  1.99588000e-1f,  0.00000000e+0f,  9.62820000e-2f}},
 501         {{3.68584000e-1f, -2.72349000e-1f,  3.21616000e-1f, -1.92645000e-1f,  4.82600000e-2f}},
 502         {{5.67316000e-1f, -4.22920000e-1f, -3.15495000e-1f,  6.34490000e-2f, -2.92380000e-2f}},
 503     }},
 504     /*LF*/{{1.00000000e+0f, 1.00000000e+0f, 1.00000000e+0f}},
 505     {{
 506         {{4.90109850e-1f,  3.77305010e-1f, -3.73106990e-1f, -1.25914530e-1f,  1.45133000e-2f}},
 507         {{1.49085730e-1f,  3.03561680e-1f,  1.53290060e-1f,  2.45112480e-1f, -1.50753130e-1f}},
 508         {{1.37654920e-1f,  0.00000000e+0f,  4.49417940e-1f,  0.00000000e+0f,  2.57844070e-1f}},
 509         {{1.49085730e-1f, -3.03561680e-1f,  1.53290060e-1f, -2.45112480e-1f, -1.50753130e-1f}},
 510         {{4.90109850e-1f, -3.77305010e-1f, -3.73106990e-1f,  1.25914530e-1f,  1.45133000e-2f}},
 511     }}
 512 };
 513 constexpr DecoderConfig<SingleBand, 5> X61Config{
 514     2, false, {{SideLeft, FrontLeft, FrontRight, SideRight, BackCenter}},
 515     DevAmbiScaling::N3D,
 516     {{1.0f, 1.0f, 1.0f}},
 517     {{
 518         {{2.04460341e-1f,  2.17177926e-1f, -4.39996780e-2f, -2.60790269e-2f, -6.87239792e-2f}},
 519         {{1.58923161e-1f,  9.21772680e-2f,  1.59658796e-1f,  6.66278083e-2f,  3.84686854e-2f}},
 520         {{1.58923161e-1f, -9.21772680e-2f,  1.59658796e-1f, -6.66278083e-2f,  3.84686854e-2f}},
 521         {{2.04460341e-1f, -2.17177926e-1f, -4.39996780e-2f,  2.60790269e-2f, -6.87239792e-2f}},
 522         {{2.50001688e-1f,  0.00000000e+0f, -2.50000094e-1f,  0.00000000e+0f,  6.05133395e-2f}},
 523     }}
 524 };
 525 constexpr DecoderConfig<DualBand, 6> X71Config{
 526     2, false, {{BackLeft, SideLeft, FrontLeft, FrontRight, SideRight, BackRight}},
 527     DevAmbiScaling::N3D,
 528     /*HF*/{{1.41421356e+0f, 1.22474487e+0f, 7.07106781e-1f}},
 529     {{
 530         {{1.66666667e-1f,  9.62250449e-2f, -1.66666667e-1f, -1.49071198e-1f,  8.60662966e-2f}},
 531         {{1.66666667e-1f,  1.92450090e-1f,  0.00000000e+0f,  0.00000000e+0f, -1.72132593e-1f}},
 532         {{1.66666667e-1f,  9.62250449e-2f,  1.66666667e-1f,  1.49071198e-1f,  8.60662966e-2f}},
 533         {{1.66666667e-1f, -9.62250449e-2f,  1.66666667e-1f, -1.49071198e-1f,  8.60662966e-2f}},
 534         {{1.66666667e-1f, -1.92450090e-1f,  0.00000000e+0f,  0.00000000e+0f, -1.72132593e-1f}},
 535         {{1.66666667e-1f, -9.62250449e-2f, -1.66666667e-1f,  1.49071198e-1f,  8.60662966e-2f}},
 536     }},
 537     /*LF*/{{1.00000000e+0f, 1.00000000e+0f, 1.00000000e+0f}},
 538     {{
 539         {{1.66666667e-1f,  9.62250449e-2f, -1.66666667e-1f, -1.49071198e-1f,  8.60662966e-2f}},
 540         {{1.66666667e-1f,  1.92450090e-1f,  0.00000000e+0f,  0.00000000e+0f, -1.72132593e-1f}},
 541         {{1.66666667e-1f,  9.62250449e-2f,  1.66666667e-1f,  1.49071198e-1f,  8.60662966e-2f}},
 542         {{1.66666667e-1f, -9.62250449e-2f,  1.66666667e-1f, -1.49071198e-1f,  8.60662966e-2f}},
 543         {{1.66666667e-1f, -1.92450090e-1f,  0.00000000e+0f,  0.00000000e+0f, -1.72132593e-1f}},
 544         {{1.66666667e-1f, -9.62250449e-2f, -1.66666667e-1f,  1.49071198e-1f,  8.60662966e-2f}},
 545     }}
 546 };
 547 constexpr DecoderConfig<DualBand, 6> X3D71Config{
 548     1, true, {{Aux0, SideLeft, FrontLeft, FrontRight, SideRight, Aux1}},
 549     DevAmbiScaling::N3D,
 550     /*HF*/{{1.73205081e+0f, 1.00000000e+0f}},
 551     {{
 552         {{1.666666667e-01f,  0.000000000e+00f,  2.356640879e-01f, -1.667265410e-01f}},
 553         {{1.666666667e-01f,  2.033043281e-01f, -1.175581508e-01f, -1.678904388e-01f}},
 554         {{1.666666667e-01f,  2.033043281e-01f,  1.175581508e-01f,  1.678904388e-01f}},
 555         {{1.666666667e-01f, -2.033043281e-01f,  1.175581508e-01f,  1.678904388e-01f}},
 556         {{1.666666667e-01f, -2.033043281e-01f, -1.175581508e-01f, -1.678904388e-01f}},
 557         {{1.666666667e-01f,  0.000000000e+00f, -2.356640879e-01f,  1.667265410e-01f}},
 558     }},
 559     /*LF*/{{1.00000000e+0f, 1.00000000e+0f}},
 560     {{
 561         {{1.666666667e-01f,  0.000000000e+00f,  2.356640879e-01f, -1.667265410e-01f}},
 562         {{1.666666667e-01f,  2.033043281e-01f, -1.175581508e-01f, -1.678904388e-01f}},
 563         {{1.666666667e-01f,  2.033043281e-01f,  1.175581508e-01f,  1.678904388e-01f}},
 564         {{1.666666667e-01f, -2.033043281e-01f,  1.175581508e-01f,  1.678904388e-01f}},
 565         {{1.666666667e-01f, -2.033043281e-01f, -1.175581508e-01f, -1.678904388e-01f}},
 566         {{1.666666667e-01f,  0.000000000e+00f, -2.356640879e-01f,  1.667265410e-01f}},
 567     }}
 568 };
 569 constexpr DecoderConfig<SingleBand, 10> X714Config{
 570     1, true, {{FrontLeft, FrontRight, SideLeft, SideRight, BackLeft, BackRight, TopFrontLeft, TopFrontRight, TopBackLeft, TopBackRight }},
 571     DevAmbiScaling::N3D,
 572     {{1.00000000e+0f, 1.00000000e+0f, 1.00000000e+0f}},
 573     {{
 574         {{1.27149251e-01f,  7.63047539e-02f, -3.64373750e-02f,  1.59700680e-01f}},
 575         {{1.07005418e-01f, -7.67638760e-02f, -4.92129762e-02f,  1.29012797e-01f}},
 576         {{1.26400196e-01f,  1.77494694e-01f, -3.71203389e-02f,  0.00000000e+00f}},
 577         {{1.26396516e-01f, -1.77488059e-01f, -3.71297878e-02f,  0.00000000e+00f}},
 578         {{1.06996956e-01f,  7.67615256e-02f, -4.92166307e-02f, -1.29001640e-01f}},
 579         {{1.27145671e-01f, -7.63003471e-02f, -3.64353304e-02f, -1.59697510e-01f}},
 580         {{8.80919747e-02f,  7.48940670e-02f,  9.08786244e-02f,  6.22527183e-02f}},
 581         {{1.57880745e-01f, -7.28755272e-02f,  1.82364187e-01f,  8.74240284e-02f}},
 582         {{1.57892225e-01f,  7.28944768e-02f,  1.82363474e-01f, -8.74301086e-02f}},
 583         {{8.80892603e-02f, -7.48948724e-02f,  9.08779842e-02f, -6.22480443e-02f}},
 584     }}
 585 };
 586
 587 void InitPanning(ALCdevice *device, const bool hqdec=false, const bool stablize=false,
 588     DecoderView decoder={})
 589 {
 590     if(!decoder)
 591     {
 592         switch(device->FmtChans)
 593         {
 594         case DevFmtMono: decoder = MonoConfig; break;
 595         case DevFmtStereo: decoder = StereoConfig; break;
 596         case DevFmtQuad: decoder = QuadConfig; break;
 597         case DevFmtX51: decoder = X51Config; break;
 598         case DevFmtX61: decoder = X61Config; break;
 599         case DevFmtX71: decoder = X71Config; break;
 600         case DevFmtX714: decoder = X714Config; break;
 601         case DevFmtX3D71: decoder = X3D71Config; break;
 602         case DevFmtAmbi3D:
 603             const auto acnmap = GetAmbiLayout(device->mAmbiLayout);
 604             const auto n3dscale = GetAmbiScales(device->mAmbiScale);
 605
 606             /* For DevFmtAmbi3D, the ambisonic order is already set. */
 607             const size_t count{AmbiChannelsFromOrder(device->mAmbiOrder)};
 608             std::transform(acnmap.begin(), acnmap.begin()+count, std::begin(device->Dry.AmbiMap),
 609                 [n3dscale](const uint8_t &acn) noexcept -> BFChannelConfig
 610                 { return BFChannelConfig{1.0f/n3dscale[acn], acn}; });
 611             AllocChannels(device, count, 0);
 612             device->m2DMixing = false;
 613
 614             float avg_dist{};
 615             if(auto distopt = device->configValue<float>("decoder", "speaker-dist"))
 616                 avg_dist = *distopt;
 617             else if(auto delayopt = device->configValue<float>("decoder", "nfc-ref-delay"))
 618             {
 619                 WARN("nfc-ref-delay is deprecated, use speaker-dist instead\n");
 620                 avg_dist = *delayopt * SpeedOfSoundMetersPerSec;
 621             }
 622
 623             InitNearFieldCtrl(device, avg_dist, device->mAmbiOrder, true);
 624             return;
 625         }
 626     }
 627
 628     const size_t ambicount{decoder.mIs3D ? AmbiChannelsFromOrder(decoder.mOrder) :
 629         Ambi2DChannelsFromOrder(decoder.mOrder)};
 630     const bool dual_band{hqdec && !decoder.mCoeffsLF.empty()};
 631     std::vector<ChannelDec> chancoeffs, chancoeffslf;
 632     for(size_t i{0u};i < decoder.mChannels.size();++i)
 633     {
 634         const uint idx{device->channelIdxByName(decoder.mChannels[i])};
 635         if(idx == InvalidChannelIndex)
 636         {
 637             ERR("Failed to find %s channel in device\n",
 638                 GetLabelFromChannel(decoder.mChannels[i]));
 639             continue;
 640         }
 641
 642         auto ordermap = decoder.mIs3D ? AmbiIndex::OrderFromChannel.data()
 643             : AmbiIndex::OrderFrom2DChannel.data();
 644
 645         chancoeffs.resize(maxz(chancoeffs.size(), idx+1u), ChannelDec{});
 646         al::span<const float,MaxAmbiChannels> src{decoder.mCoeffs[i]};
 647         al::span<float,MaxAmbiChannels> dst{chancoeffs[idx]};
 648         for(size_t ambichan{0};ambichan < ambicount;++ambichan)
 649             dst[ambichan] = src[ambichan] * decoder.mOrderGain[ordermap[ambichan]];
 650
 651         if(!dual_band)
 652             continue;
 653
 654         chancoeffslf.resize(maxz(chancoeffslf.size(), idx+1u), ChannelDec{});
 655         src = decoder.mCoeffsLF[i];
 656         dst = chancoeffslf[idx];
 657         for(size_t ambichan{0};ambichan < ambicount;++ambichan)
 658             dst[ambichan] = src[ambichan] * decoder.mOrderGainLF[ordermap[ambichan]];
 659     }
 660
 661     /* For non-DevFmtAmbi3D, set the ambisonic order. */
 662     device->mAmbiOrder = decoder.mOrder;
 663     device->m2DMixing = !decoder.mIs3D;
 664
 665     const al::span<const uint8_t> acnmap{decoder.mIs3D ? AmbiIndex::FromACN.data() :
 666         AmbiIndex::FromACN2D.data(), ambicount};
 667     const auto coeffscale = GetAmbiScales(decoder.mScaling);
 668     std::transform(acnmap.begin(), acnmap.end(), std::begin(device->Dry.AmbiMap),
 669         [coeffscale](const uint8_t &acn) noexcept
 670         { return BFChannelConfig{1.0f/coeffscale[acn], acn}; });
 671     AllocChannels(device, ambicount, device->channelsFromFmt());
 672
 673     std::unique_ptr<FrontStablizer> stablizer;
 674     if(stablize)
 675     {
 676         /* Only enable the stablizer if the decoder does not output to the
 677          * front-center channel.
 678          */
 679         const size_t cidx{device->RealOut.ChannelIndex[FrontCenter]};
 680         bool hasfc{false};
 681         if(cidx < chancoeffs.size())
 682         {
 683             for(const auto &coeff : chancoeffs[cidx])
 684                 hasfc |= coeff != 0.0f;
 685         }
 686         if(!hasfc && cidx < chancoeffslf.size())
 687         {
 688             for(const auto &coeff : chancoeffslf[cidx])
 689                 hasfc |= coeff != 0.0f;
 690         }
 691         if(!hasfc)
 692         {
 693             stablizer = CreateStablizer(device->channelsFromFmt(), device->Frequency);
 694             TRACE("Front stablizer enabled\n");
 695         }
 696     }
 697
 698     TRACE("Enabling %s-band %s-order%s ambisonic decoder\n",
 699         !dual_band ? "single" : "dual",
 700         (decoder.mOrder > 3) ? "fourth" :
 701         (decoder.mOrder > 2) ? "third" :
 702         (decoder.mOrder > 1) ? "second" : "first",
 703         decoder.mIs3D ? " periphonic" : "");
 704     device->AmbiDecoder = BFormatDec::Create(ambicount, chancoeffs, chancoeffslf,
 705         device->mXOverFreq/static_cast<float>(device->Frequency), std::move(stablizer));
 706 }
 707
 708 void InitHrtfPanning(ALCdevice *device)
 709 {
 710     static constexpr float Deg180{al::numbers::pi_v<float>};
 711     static constexpr float Deg_90{Deg180 / 2.0f /* 90 degrees*/};
 712     static constexpr float Deg_45{Deg_90 / 2.0f /* 45 degrees*/};
 713     static constexpr float Deg135{Deg_45 * 3.0f /*135 degrees*/};
 714     static constexpr float Deg_21{3.648638281e-01f /* 20~ 21 degrees*/};
 715     static constexpr float Deg_32{5.535743589e-01f /* 31~ 32 degrees*/};
 716     static constexpr float Deg_35{6.154797087e-01f /* 35~ 36 degrees*/};
 717     static constexpr float Deg_58{1.017221968e+00f /* 58~ 59 degrees*/};
 718     static constexpr float Deg_69{1.205932499e+00f /* 69~ 70 degrees*/};
 719     static constexpr float Deg111{1.935660155e+00f /*110~111 degrees*/};
 720     static constexpr float Deg122{2.124370686e+00f /*121~122 degrees*/};
 721     static constexpr std::array AmbiPoints1O{
 722         AngularPoint{EvRadians{ Deg_35}, AzRadians{-Deg_45}},
 723         AngularPoint{EvRadians{ Deg_35}, AzRadians{-Deg135}},
 724         AngularPoint{EvRadians{ Deg_35}, AzRadians{ Deg_45}},
 725         AngularPoint{EvRadians{ Deg_35}, AzRadians{ Deg135}},
 726         AngularPoint{EvRadians{-Deg_35}, AzRadians{-Deg_45}},
 727         AngularPoint{EvRadians{-Deg_35}, AzRadians{-Deg135}},
 728         AngularPoint{EvRadians{-Deg_35}, AzRadians{ Deg_45}},
 729         AngularPoint{EvRadians{-Deg_35}, AzRadians{ Deg135}},
 730     };
 731     static constexpr std::array AmbiPoints2O{
 732         AngularPoint{EvRadians{-Deg_32}, AzRadians{   0.0f}},
 733         AngularPoint{EvRadians{   0.0f}, AzRadians{ Deg_58}},
 734         AngularPoint{EvRadians{ Deg_58}, AzRadians{ Deg_90}},
 735         AngularPoint{EvRadians{ Deg_32}, AzRadians{   0.0f}},
 736         AngularPoint{EvRadians{   0.0f}, AzRadians{ Deg122}},
 737         AngularPoint{EvRadians{-Deg_58}, AzRadians{-Deg_90}},
 738         AngularPoint{EvRadians{-Deg_32}, AzRadians{ Deg180}},
 739         AngularPoint{EvRadians{   0.0f}, AzRadians{-Deg122}},
 740         AngularPoint{EvRadians{ Deg_58}, AzRadians{-Deg_90}},
 741         AngularPoint{EvRadians{ Deg_32}, AzRadians{ Deg180}},
 742         AngularPoint{EvRadians{   0.0f}, AzRadians{-Deg_58}},
 743         AngularPoint{EvRadians{-Deg_58}, AzRadians{ Deg_90}},
 744     };
 745     static constexpr std::array AmbiPoints3O{
 746         AngularPoint{EvRadians{ Deg_69}, AzRadians{-Deg_90}},
 747         AngularPoint{EvRadians{ Deg_69}, AzRadians{ Deg_90}},
 748         AngularPoint{EvRadians{-Deg_69}, AzRadians{-Deg_90}},
 749         AngularPoint{EvRadians{-Deg_69}, AzRadians{ Deg_90}},
 750         AngularPoint{EvRadians{   0.0f}, AzRadians{-Deg_69}},
 751         AngularPoint{EvRadians{   0.0f}, AzRadians{-Deg111}},
 752         AngularPoint{EvRadians{   0.0f}, AzRadians{ Deg_69}},
 753         AngularPoint{EvRadians{   0.0f}, AzRadians{ Deg111}},
 754         AngularPoint{EvRadians{ Deg_21}, AzRadians{   0.0f}},
 755         AngularPoint{EvRadians{ Deg_21}, AzRadians{ Deg180}},
 756         AngularPoint{EvRadians{-Deg_21}, AzRadians{   0.0f}},
 757         AngularPoint{EvRadians{-Deg_21}, AzRadians{ Deg180}},
 758         AngularPoint{EvRadians{ Deg_35}, AzRadians{-Deg_45}},
 759         AngularPoint{EvRadians{ Deg_35}, AzRadians{-Deg135}},
 760         AngularPoint{EvRadians{ Deg_35}, AzRadians{ Deg_45}},
 761         AngularPoint{EvRadians{ Deg_35}, AzRadians{ Deg135}},
 762         AngularPoint{EvRadians{-Deg_35}, AzRadians{-Deg_45}},
 763         AngularPoint{EvRadians{-Deg_35}, AzRadians{-Deg135}},
 764         AngularPoint{EvRadians{-Deg_35}, AzRadians{ Deg_45}},
 765         AngularPoint{EvRadians{-Deg_35}, AzRadians{ Deg135}},
 766     };
 767     static constexpr std::array AmbiMatrix1O{
 768         ChannelCoeffs{1.250000000e-01f,  1.250000000e-01f,  1.250000000e-01f,  1.250000000e-01f},
 769         ChannelCoeffs{1.250000000e-01f,  1.250000000e-01f,  1.250000000e-01f, -1.250000000e-01f},
 770         ChannelCoeffs{1.250000000e-01f, -1.250000000e-01f,  1.250000000e-01f,  1.250000000e-01f},
 771         ChannelCoeffs{1.250000000e-01f, -1.250000000e-01f,  1.250000000e-01f, -1.250000000e-01f},
 772         ChannelCoeffs{1.250000000e-01f,  1.250000000e-01f, -1.250000000e-01f,  1.250000000e-01f},
 773         ChannelCoeffs{1.250000000e-01f,  1.250000000e-01f, -1.250000000e-01f, -1.250000000e-01f},
 774         ChannelCoeffs{1.250000000e-01f, -1.250000000e-01f, -1.250000000e-01f,  1.250000000e-01f},
 775         ChannelCoeffs{1.250000000e-01f, -1.250000000e-01f, -1.250000000e-01f, -1.250000000e-01f},
 776     };
 777     static constexpr std::array AmbiMatrix2O{
 778         ChannelCoeffs{8.333333333e-02f,  0.000000000e+00f, -7.588274978e-02f,  1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.591525047e-02f, -1.443375673e-01f,  1.167715449e-01f},
 779         ChannelCoeffs{8.333333333e-02f, -1.227808683e-01f,  0.000000000e+00f,  7.588274978e-02f, -1.443375673e-01f,  0.000000000e+00f, -9.316949906e-02f,  0.000000000e+00f, -7.216878365e-02f},
 780         ChannelCoeffs{8.333333333e-02f, -7.588274978e-02f,  1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.443375673e-01f,  1.090847495e-01f,  0.000000000e+00f, -4.460276122e-02f},
 781         ChannelCoeffs{8.333333333e-02f,  0.000000000e+00f,  7.588274978e-02f,  1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.591525047e-02f,  1.443375673e-01f,  1.167715449e-01f},
 782         ChannelCoeffs{8.333333333e-02f, -1.227808683e-01f,  0.000000000e+00f, -7.588274978e-02f,  1.443375673e-01f,  0.000000000e+00f, -9.316949906e-02f,  0.000000000e+00f, -7.216878365e-02f},
 783         ChannelCoeffs{8.333333333e-02f,  7.588274978e-02f, -1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.443375673e-01f,  1.090847495e-01f,  0.000000000e+00f, -4.460276122e-02f},
 784         ChannelCoeffs{8.333333333e-02f,  0.000000000e+00f, -7.588274978e-02f, -1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.591525047e-02f,  1.443375673e-01f,  1.167715449e-01f},
 785         ChannelCoeffs{8.333333333e-02f,  1.227808683e-01f,  0.000000000e+00f, -7.588274978e-02f, -1.443375673e-01f,  0.000000000e+00f, -9.316949906e-02f,  0.000000000e+00f, -7.216878365e-02f},
 786         ChannelCoeffs{8.333333333e-02f,  7.588274978e-02f,  1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f,  1.443375673e-01f,  1.090847495e-01f,  0.000000000e+00f, -4.460276122e-02f},
 787         ChannelCoeffs{8.333333333e-02f,  0.000000000e+00f,  7.588274978e-02f, -1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f, -1.591525047e-02f, -1.443375673e-01f,  1.167715449e-01f},
 788         ChannelCoeffs{8.333333333e-02f,  1.227808683e-01f,  0.000000000e+00f,  7.588274978e-02f,  1.443375673e-01f,  0.000000000e+00f, -9.316949906e-02f,  0.000000000e+00f, -7.216878365e-02f},
 789         ChannelCoeffs{8.333333333e-02f, -7.588274978e-02f, -1.227808683e-01f,  0.000000000e+00f,  0.000000000e+00f,  1.443375673e-01f,  1.090847495e-01f,  0.000000000e+00f, -4.460276122e-02f},
 790     };
 791     static constexpr std::array AmbiMatrix3O{
 792         ChannelCoeffs{5.000000000e-02f,  3.090169944e-02f,  8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f,  6.454972244e-02f,  9.045084972e-02f,  0.000000000e+00f, -1.232790000e-02f, -1.256118221e-01f,  0.000000000e+00f,  1.126112056e-01f,  7.944389175e-02f,  0.000000000e+00f,  2.421151497e-02f,  0.000000000e+00f},
 793         ChannelCoeffs{5.000000000e-02f, -3.090169944e-02f,  8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -6.454972244e-02f,  9.045084972e-02f,  0.000000000e+00f, -1.232790000e-02f,  1.256118221e-01f,  0.000000000e+00f, -1.126112056e-01f,  7.944389175e-02f,  0.000000000e+00f,  2.421151497e-02f,  0.000000000e+00f},
 794         ChannelCoeffs{5.000000000e-02f,  3.090169944e-02f, -8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -6.454972244e-02f,  9.045084972e-02f,  0.000000000e+00f, -1.232790000e-02f, -1.256118221e-01f,  0.000000000e+00f,  1.126112056e-01f, -7.944389175e-02f,  0.000000000e+00f, -2.421151497e-02f,  0.000000000e+00f},
 795         ChannelCoeffs{5.000000000e-02f, -3.090169944e-02f, -8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f,  6.454972244e-02f,  9.045084972e-02f,  0.000000000e+00f, -1.232790000e-02f,  1.256118221e-01f,  0.000000000e+00f, -1.126112056e-01f, -7.944389175e-02f,  0.000000000e+00f, -2.421151497e-02f,  0.000000000e+00f},
 796         ChannelCoeffs{5.000000000e-02f,  8.090169944e-02f,  0.000000000e+00f,  3.090169944e-02f,  6.454972244e-02f,  0.000000000e+00f, -5.590169944e-02f,  0.000000000e+00f, -7.216878365e-02f, -7.763237543e-02f,  0.000000000e+00f, -2.950836627e-02f,  0.000000000e+00f, -1.497759251e-01f,  0.000000000e+00f, -7.763237543e-02f},
 797         ChannelCoeffs{5.000000000e-02f,  8.090169944e-02f,  0.000000000e+00f, -3.090169944e-02f, -6.454972244e-02f,  0.000000000e+00f, -5.590169944e-02f,  0.000000000e+00f, -7.216878365e-02f, -7.763237543e-02f,  0.000000000e+00f, -2.950836627e-02f,  0.000000000e+00f,  1.497759251e-01f,  0.000000000e+00f,  7.763237543e-02f},
 798         ChannelCoeffs{5.000000000e-02f, -8.090169944e-02f,  0.000000000e+00f,  3.090169944e-02f, -6.454972244e-02f,  0.000000000e+00f, -5.590169944e-02f,  0.000000000e+00f, -7.216878365e-02f,  7.763237543e-02f,  0.000000000e+00f,  2.950836627e-02f,  0.000000000e+00f, -1.497759251e-01f,  0.000000000e+00f, -7.763237543e-02f},
 799         ChannelCoeffs{5.000000000e-02f, -8.090169944e-02f,  0.000000000e+00f, -3.090169944e-02f,  6.454972244e-02f,  0.000000000e+00f, -5.590169944e-02f,  0.000000000e+00f, -7.216878365e-02f,  7.763237543e-02f,  0.000000000e+00f,  2.950836627e-02f,  0.000000000e+00f,  1.497759251e-01f,  0.000000000e+00f,  7.763237543e-02f},
 800         ChannelCoeffs{5.000000000e-02f,  0.000000000e+00f,  3.090169944e-02f,  8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -3.454915028e-02f,  6.454972244e-02f,  8.449668365e-02f,  0.000000000e+00f,  0.000000000e+00f,  0.000000000e+00f,  3.034486645e-02f, -6.779013272e-02f,  1.659481923e-01f,  4.797944664e-02f},
 801         ChannelCoeffs{5.000000000e-02f,  0.000000000e+00f,  3.090169944e-02f, -8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -3.454915028e-02f, -6.454972244e-02f,  8.449668365e-02f,  0.000000000e+00f,  0.000000000e+00f,  0.000000000e+00f,  3.034486645e-02f,  6.779013272e-02f,  1.659481923e-01f, -4.797944664e-02f},
 802         ChannelCoeffs{5.000000000e-02f,  0.000000000e+00f, -3.090169944e-02f,  8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -3.454915028e-02f, -6.454972244e-02f,  8.449668365e-02f,  0.000000000e+00f,  0.000000000e+00f,  0.000000000e+00f, -3.034486645e-02f, -6.779013272e-02f, -1.659481923e-01f,  4.797944664e-02f},
 803         ChannelCoeffs{5.000000000e-02f,  0.000000000e+00f, -3.090169944e-02f, -8.090169944e-02f,  0.000000000e+00f,  0.000000000e+00f, -3.454915028e-02f,  6.454972244e-02f,  8.449668365e-02f,  0.000000000e+00f,  0.000000000e+00f,  0.000000000e+00f, -3.034486645e-02f,  6.779013272e-02f, -1.659481923e-01f, -4.797944664e-02f},
 804         ChannelCoeffs{5.000000000e-02f,  5.000000000e-02f,  5.000000000e-02f,  5.000000000e-02f,  6.454972244e-02f,  6.454972244e-02f,  0.000000000e+00f,  6.454972244e-02f,  0.000000000e+00f,  1.016220987e-01f,  6.338656910e-02f, -1.092600649e-02f, -7.364853795e-02f,  1.011266756e-01f, -7.086833869e-02f, -1.482646439e-02f},
 805         ChannelCoeffs{5.000000000e-02f,  5.000000000e-02f,  5.000000000e-02f, -5.000000000e-02f, -6.454972244e-02f,  6.454972244e-02f,  0.000000000e+00f, -6.454972244e-02f,  0.000000000e+00f,  1.016220987e-01f, -6.338656910e-02f, -1.092600649e-02f, -7.364853795e-02f, -1.011266756e-01f, -7.086833869e-02f,  1.482646439e-02f},
 806         ChannelCoeffs{5.000000000e-02f, -5.000000000e-02f,  5.000000000e-02f,  5.000000000e-02f, -6.454972244e-02f, -6.454972244e-02f,  0.000000000e+00f,  6.454972244e-02f,  0.000000000e+00f, -1.016220987e-01f, -6.338656910e-02f,  1.092600649e-02f, -7.364853795e-02f,  1.011266756e-01f, -7.086833869e-02f, -1.482646439e-02f},
 807         ChannelCoeffs{5.000000000e-02f, -5.000000000e-02f,  5.000000000e-02f, -5.000000000e-02f,  6.454972244e-02f, -6.454972244e-02f,  0.000000000e+00f, -6.454972244e-02f,  0.000000000e+00f, -1.016220987e-01f,  6.338656910e-02f,  1.092600649e-02f, -7.364853795e-02f, -1.011266756e-01f, -7.086833869e-02f,  1.482646439e-02f},
 808         ChannelCoeffs{5.000000000e-02f,  5.000000000e-02f, -5.000000000e-02f,  5.000000000e-02f,  6.454972244e-02f, -6.454972244e-02f,  0.000000000e+00f, -6.454972244e-02f,  0.000000000e+00f,  1.016220987e-01f, -6.338656910e-02f, -1.092600649e-02f,  7.364853795e-02f,  1.011266756e-01f,  7.086833869e-02f, -1.482646439e-02f},
 809         ChannelCoeffs{5.000000000e-02f,  5.000000000e-02f, -5.000000000e-02f, -5.000000000e-02f, -6.454972244e-02f, -6.454972244e-02f,  0.000000000e+00f,  6.454972244e-02f,  0.000000000e+00f,  1.016220987e-01f,  6.338656910e-02f, -1.092600649e-02f,  7.364853795e-02f, -1.011266756e-01f,  7.086833869e-02f,  1.482646439e-02f},
 810         ChannelCoeffs{5.000000000e-02f, -5.000000000e-02f, -5.000000000e-02f,  5.000000000e-02f, -6.454972244e-02f,  6.454972244e-02f,  0.000000000e+00f, -6.454972244e-02f,  0.000000000e+00f, -1.016220987e-01f,  6.338656910e-02f,  1.092600649e-02f,  7.364853795e-02f,  1.011266756e-01f,  7.086833869e-02f, -1.482646439e-02f},
 811         ChannelCoeffs{5.000000000e-02f, -5.000000000e-02f, -5.000000000e-02f, -5.000000000e-02f,  6.454972244e-02f,  6.454972244e-02f,  0.000000000e+00f,  6.454972244e-02f,  0.000000000e+00f, -1.016220987e-01f, -6.338656910e-02f,  1.092600649e-02f,  7.364853795e-02f, -1.011266756e-01f,  7.086833869e-02f,  1.482646439e-02f},
 812     };
 813     static constexpr std::array<float,MaxAmbiOrder+1> AmbiOrderHFGain1O{
 814         /*ENRGY*/ 2.000000000e+00f, 1.154700538e+00f
 815     };
 816     static constexpr std::array<float,MaxAmbiOrder+1> AmbiOrderHFGain2O{
 817         /*ENRGY*/ 1.825741858e+00f, 1.414213562e+00f, 7.302967433e-01f
 818         /*AMP   1.000000000e+00f, 7.745966692e-01f, 4.000000000e-01f*/
 819         /*RMS   9.128709292e-01f, 7.071067812e-01f, 3.651483717e-01f*/
 820     };
 821     static constexpr std::array<float,MaxAmbiOrder+1> AmbiOrderHFGain3O{
 822         /*ENRGY 1.865086714e+00f, 1.606093894e+00f, 1.142055301e+00f, 5.683795528e-01f*/
 823         /*AMP*/ 1.000000000e+00f, 8.611363116e-01f, 6.123336207e-01f, 3.047469850e-01f
 824         /*RMS   8.340921354e-01f, 7.182670250e-01f, 5.107426573e-01f, 2.541870634e-01f*/
 825     };
 826
 827     static_assert(AmbiPoints1O.size() == AmbiMatrix1O.size(), "First-Order Ambisonic HRTF mismatch");
 828     static_assert(AmbiPoints2O.size() == AmbiMatrix2O.size(), "Second-Order Ambisonic HRTF mismatch");
 829     static_assert(AmbiPoints3O.size() == AmbiMatrix3O.size(), "Third-Order Ambisonic HRTF mismatch");
 830
 831     /* A 700hz crossover frequency provides tighter sound imaging at the sweet
 832      * spot with ambisonic decoding, as the distance between the ears is closer
 833      * to half this frequency wavelength, which is the optimal point where the
 834      * response should change between optimizing phase vs volume. Normally this
 835      * tighter imaging is at the cost of a smaller sweet spot, but since the
 836      * listener is fixed in the center of the HRTF responses for the decoder,
 837      * we don't have to worry about ever being out of the sweet spot.
 838      *
 839      * A better option here may be to have the head radius as part of the HRTF
 840      * data set and calculate the optimal crossover frequency from that.
 841      */
 842     device->mXOverFreq = 700.0f;
 843
 844     /* Don't bother with HOA when using full HRTF rendering. Nothing needs it,
 845      * and it eases the CPU/memory load.
 846      */
 847     device->mRenderMode = RenderMode::Hrtf;
 848     uint ambi_order{1};
 849     if(auto modeopt = device->configValue<std::string>({}, "hrtf-mode"))
 850     {
 851         struct HrtfModeEntry {
 852             std::string_view name;
 853             RenderMode mode;
 854             uint order;
 855         };
 856         constexpr std::array hrtf_modes{
 857             HrtfModeEntry{"full"sv, RenderMode::Hrtf, 1},
 858             HrtfModeEntry{"ambi1"sv, RenderMode::Normal, 1},
 859             HrtfModeEntry{"ambi2"sv, RenderMode::Normal, 2},
 860             HrtfModeEntry{"ambi3"sv, RenderMode::Normal, 3},
 861         };
 862
 863         std::string_view mode{*modeopt};
 864         if(al::case_compare(mode, "basic"sv) == 0)
 865         {
 866             ERR("HRTF mode \"%s\" deprecated, substituting \"%s\"\n", modeopt->c_str(), "ambi2");
 867             mode = "ambi2";
 868         }
 869
 870         auto match_entry = [mode](const HrtfModeEntry &entry) -> bool
 871         { return al::case_compare(mode, entry.name) == 0; };
 872         auto iter = std::find_if(std::begin(hrtf_modes), std::end(hrtf_modes), match_entry);
 873         if(iter == std::end(hrtf_modes))
 874             ERR("Unexpected hrtf-mode: %s\n", modeopt->c_str());
 875         else
 876         {
 877             device->mRenderMode = iter->mode;
 878             ambi_order = iter->order;
 879         }
 880     }
 881     TRACE("%u%s order %sHRTF rendering enabled, using \"%s\"\n", ambi_order,
 882         static_cast<const char*>((((ambi_order%100)/10) == 1) ? "th" :
 883         ((ambi_order%10) == 1) ? "st" :
 884         ((ambi_order%10) == 2) ? "nd" :
 885         ((ambi_order%10) == 3) ? "rd" : "th"),
 886         (device->mRenderMode == RenderMode::Hrtf) ? "+ Full " : "",
 887         device->mHrtfName.c_str());
 888
 889     bool perHrirMin{false};
 890     auto AmbiPoints = al::span{AmbiPoints1O}.subspan(0);
 891     auto AmbiMatrix = al::span{AmbiMatrix1O}.subspan(0);
 892     auto AmbiOrderHFGain = al::span{AmbiOrderHFGain1O};
 893     if(ambi_order >= 3)
 894     {
 895         perHrirMin = true;
 896         AmbiPoints = AmbiPoints3O;
 897         AmbiMatrix = AmbiMatrix3O;
 898         AmbiOrderHFGain = AmbiOrderHFGain3O;
 899     }
 900     else if(ambi_order == 2)
 901     {
 902         AmbiPoints = AmbiPoints2O;
 903         AmbiMatrix = AmbiMatrix2O;
 904         AmbiOrderHFGain = AmbiOrderHFGain2O;
 905     }
 906     device->mAmbiOrder = ambi_order;
 907     device->m2DMixing = false;
 908
 909     const size_t count{AmbiChannelsFromOrder(ambi_order)};
 910     std::transform(AmbiIndex::FromACN.begin(), AmbiIndex::FromACN.begin()+count,
 911         device->Dry.AmbiMap.begin(),
 912         [](const uint8_t &index) noexcept { return BFChannelConfig{1.0f, index}; }
 913     );
 914     AllocChannels(device, count, device->channelsFromFmt());
 915
 916     HrtfStore *Hrtf{device->mHrtf.get()};
 917     auto hrtfstate = DirectHrtfState::Create(count);
 918     hrtfstate->build(Hrtf, device->mIrSize, perHrirMin, AmbiPoints, AmbiMatrix, device->mXOverFreq,
 919         AmbiOrderHFGain);
 920     device->mHrtfState = std::move(hrtfstate);
 921
 922     InitNearFieldCtrl(device, Hrtf->mFields[0].distance, ambi_order, true);
 923 }
 924
 925 void InitUhjPanning(ALCdevice *device)
 926 {
 927     /* UHJ is always 2D first-order. */
 928     constexpr size_t count{Ambi2DChannelsFromOrder(1)};
 929
 930     device->mAmbiOrder = 1;
 931     device->m2DMixing = true;
 932
 933     auto acnmap_begin = AmbiIndex::FromFuMa2D.begin();
 934     std::transform(acnmap_begin, acnmap_begin + count, std::begin(device->Dry.AmbiMap),
 935         [](const uint8_t &acn) noexcept -> BFChannelConfig
 936         { return BFChannelConfig{1.0f/AmbiScale::FromUHJ[acn], acn}; });
 937     AllocChannels(device, count, device->channelsFromFmt());
 938 }
 939
 940 } // namespace
 941
 942 void aluInitRenderer(ALCdevice *device, int hrtf_id, std::optional<StereoEncoding> stereomode)
 943 {
 944     /* Hold the HRTF the device last used, in case it's used again. */
 945     HrtfStorePtr old_hrtf{std::move(device->mHrtf)};
 946
 947     device->mHrtfState = nullptr;
 948     device->mHrtf = nullptr;
 949     device->mIrSize = 0;
 950     device->mHrtfName.clear();
 951     device->mXOverFreq = 400.0f;
 952     device->m2DMixing = false;
 953     device->mRenderMode = RenderMode::Normal;
 954
 955     if(device->FmtChans != DevFmtStereo)
 956     {
 957         old_hrtf = nullptr;
 958         if(stereomode && *stereomode == StereoEncoding::Hrtf)
 959             device->mHrtfStatus = ALC_HRTF_UNSUPPORTED_FORMAT_SOFT;
 960
 961         const char *layout{nullptr};
 962         switch(device->FmtChans)
 963         {
 964         case DevFmtQuad: layout = "quad"; break;
 965         case DevFmtX51: layout = "surround51"; break;
 966         case DevFmtX61: layout = "surround61"; break;
 967         case DevFmtX71: layout = "surround71"; break;
 968         case DevFmtX714: layout = "surround714"; break;
 969         case DevFmtX3D71: layout = "surround3d71"; break;
 970         /* Mono, Stereo, and Ambisonics output don't use custom decoders. */
 971         case DevFmtMono:
 972         case DevFmtStereo:
 973         case DevFmtAmbi3D:
 974             break;
 975         }
 976
 977         std::unique_ptr<DecoderConfig<DualBand,MaxOutputChannels>> decoder_store;
 978         DecoderView decoder{};
 979         std::array<float,MaxOutputChannels> speakerdists{};
 980         auto load_config = [device,&decoder_store,&decoder,&speakerdists](const char *config)
 981         {
 982             AmbDecConf conf{};
 983             if(auto err = conf.load(config))
 984             {
 985                 ERR("Failed to load layout file %s\n", config);
 986                 ERR("  %s\n", err->c_str());
 987                 return false;
 988             }
 989             else if(conf.Speakers.size() > MaxOutputChannels)
 990             {
 991                 ERR("Unsupported decoder speaker count %zu (max %zu)\n", conf.Speakers.size(),
 992                     MaxOutputChannels);
 993                 return false;
 994             }
 995             else if(conf.ChanMask > Ambi3OrderMask)
 996             {
 997                 ERR("Unsupported decoder channel mask 0x%04x (max 0x%x)\n", conf.ChanMask,
 998                     Ambi3OrderMask);
 999                 return false;
1000             }
1001
1002             TRACE("Using %s decoder: \"%s\"\n", DevFmtChannelsString(device->FmtChans),
1003                 conf.Description.c_str());
1004             device->mXOverFreq = clampf(conf.XOverFreq, 100.0f, 1000.0f);
1005
1006             decoder_store = std::make_unique<DecoderConfig<DualBand,MaxOutputChannels>>();
1007             decoder = MakeDecoderView(device, &conf, *decoder_store);
1008             for(size_t i{0};i < decoder.mChannels.size();++i)
1009                 speakerdists[i] = conf.Speakers[i].Distance;
1010             return true;
1011         };
1012         bool usingCustom{false};
1013         if(layout)
1014         {
1015             if(auto decopt = device->configValue<std::string>("decoder", layout))
1016                 usingCustom = load_config(decopt->c_str());
1017         }
1018         if(!usingCustom && device->FmtChans != DevFmtAmbi3D)
1019             TRACE("Using built-in %s decoder\n", DevFmtChannelsString(device->FmtChans));
1020
1021         /* Enable the stablizer only for formats that have front-left, front-
1022          * right, and front-center outputs.
1023          */
1024         const bool stablize{device->RealOut.ChannelIndex[FrontCenter] != InvalidChannelIndex
1025             && device->RealOut.ChannelIndex[FrontLeft] != InvalidChannelIndex
1026             && device->RealOut.ChannelIndex[FrontRight] != InvalidChannelIndex
1027             && device->getConfigValueBool({}, "front-stablizer", false)};
1028         const bool hqdec{device->getConfigValueBool("decoder", "hq-mode", true)};
1029         InitPanning(device, hqdec, stablize, decoder);
1030         if(decoder)
1031         {
1032             float accum_dist{0.0f}, spkr_count{0.0f};
1033             for(auto dist : speakerdists)
1034             {
1035                 if(dist > 0.0f)
1036                 {
1037                     accum_dist += dist;
1038                     spkr_count += 1.0f;
1039                 }
1040             }
1041
1042             const float avg_dist{(accum_dist > 0.0f && spkr_count > 0) ? accum_dist/spkr_count :
1043                 device->configValue<float>("decoder", "speaker-dist").value_or(1.0f)};
1044             InitNearFieldCtrl(device, avg_dist, decoder.mOrder, decoder.mIs3D);
1045
1046             if(spkr_count > 0)
1047                 InitDistanceComp(device, decoder.mChannels, speakerdists);
1048         }
1049         if(auto *ambidec{device->AmbiDecoder.get()})
1050         {
1051             device->PostProcess = ambidec->hasStablizer() ? &ALCdevice::ProcessAmbiDecStablized
1052                 : &ALCdevice::ProcessAmbiDec;
1053         }
1054         return;
1055     }
1056
1057
1058     /* If HRTF is explicitly requested, or if there's no explicit request and
1059      * the device is headphones, try to enable it.
1060      */
1061     if(stereomode.value_or(StereoEncoding::Default) == StereoEncoding::Hrtf
1062         || (!stereomode && device->Flags.test(DirectEar)))
1063     {
1064         if(device->mHrtfList.empty())
1065             device->enumerateHrtfs();
1066
1067         if(hrtf_id >= 0 && static_cast<uint>(hrtf_id) < device->mHrtfList.size())
1068         {
1069             const std::string &hrtfname = device->mHrtfList[static_cast<uint>(hrtf_id)];
1070             if(HrtfStorePtr hrtf{GetLoadedHrtf(hrtfname, device->Frequency)})
1071             {
1072                 device->mHrtf = std::move(hrtf);
1073                 device->mHrtfName = hrtfname;
1074             }
1075         }
1076
1077         if(!device->mHrtf)
1078         {
1079             for(const auto &hrtfname : device->mHrtfList)
1080             {
1081                 if(HrtfStorePtr hrtf{GetLoadedHrtf(hrtfname, device->Frequency)})
1082                 {
1083                     device->mHrtf = std::move(hrtf);
1084                     device->mHrtfName = hrtfname;
1085                     break;
1086                 }
1087             }
1088         }
1089
1090         if(device->mHrtf)
1091         {
1092             old_hrtf = nullptr;
1093
1094             HrtfStore *hrtf{device->mHrtf.get()};
1095             device->mIrSize = hrtf->mIrSize;
1096             if(auto hrtfsizeopt = device->configValue<uint>({}, "hrtf-size"))
1097             {
1098                 if(*hrtfsizeopt > 0 && *hrtfsizeopt < device->mIrSize)
1099                     device->mIrSize = maxu(*hrtfsizeopt, MinIrLength);
1100             }
1101
1102             InitHrtfPanning(device);
1103             device->PostProcess = &ALCdevice::ProcessHrtf;
1104             device->mHrtfStatus = ALC_HRTF_ENABLED_SOFT;
1105             return;
1106         }
1107     }
1108     old_hrtf = nullptr;
1109
1110     if(stereomode.value_or(StereoEncoding::Default) == StereoEncoding::Uhj)
1111     {
1112         switch(UhjEncodeQuality)
1113         {
1114         case UhjQualityType::IIR:
1115             device->mUhjEncoder = std::make_unique<UhjEncoderIIR>();
1116             break;
1117         case UhjQualityType::FIR256:
1118             device->mUhjEncoder = std::make_unique<UhjEncoder<UhjLength256>>();
1119             break;
1120         case UhjQualityType::FIR512:
1121             device->mUhjEncoder = std::make_unique<UhjEncoder<UhjLength512>>();
1122             break;
1123         }
1124         assert(device->mUhjEncoder != nullptr);
1125
1126         TRACE("UHJ enabled\n");
1127         InitUhjPanning(device);
1128         device->PostProcess = &ALCdevice::ProcessUhj;
1129         return;
1130     }
1131
1132     device->mRenderMode = RenderMode::Pairwise;
1133     if(device->Type != DeviceType::Loopback)
1134     {
1135         if(auto cflevopt = device->configValue<int>({}, "cf_level"))
1136         {
1137             if(*cflevopt > 0 && *cflevopt <= 6)
1138             {
1139                 auto bs2b = std::make_unique<Bs2b::bs2b>();
1140                 bs2b->set_params(*cflevopt, static_cast<int>(device->Frequency));
1141                 device->Bs2b = std::move(bs2b);
1142                 TRACE("BS2B enabled\n");
1143                 InitPanning(device);
1144                 device->PostProcess = &ALCdevice::ProcessBs2b;
1145                 return;
1146             }
1147         }
1148     }
1149
1150     TRACE("Stereo rendering\n");
1151     InitPanning(device);
1152     device->PostProcess = &ALCdevice::ProcessAmbiDec;
1153 }
1154
1155
1156 void aluInitEffectPanning(EffectSlot *slot, ALCcontext *context)
1157 {
1158     DeviceBase *device{context->mDevice};
1159     const size_t count{AmbiChannelsFromOrder(device->mAmbiOrder)};
1160
1161     slot->mWetBuffer.resize(count);
1162
1163     auto acnmap_begin = AmbiIndex::FromACN.begin();
1164     auto iter = std::transform(acnmap_begin, acnmap_begin + count, slot->Wet.AmbiMap.begin(),
1165         [](const uint8_t &acn) noexcept -> BFChannelConfig
1166         { return BFChannelConfig{1.0f, acn}; });
1167     std::fill(iter, slot->Wet.AmbiMap.end(), BFChannelConfig{});
1168     slot->Wet.Buffer = slot->mWetBuffer;
1169 }