core/ambidefs.h

   1 #ifndef CORE_AMBIDEFS_H
   2 #define CORE_AMBIDEFS_H
   3
   4 #include <array>
   5 #include <stddef.h>
   6 #include <stdint.h>
   7
   8 using uint = unsigned int;
   9
  10 /* The maximum number of Ambisonics channels. For a given order (o), the size
  11  * needed will be (o+1)**2, thus zero-order has 1, first-order has 4, second-
  12  * order has 9, third-order has 16, and fourth-order has 25.
  13  */
  14 constexpr uint8_t MaxAmbiOrder{3};
  15 constexpr inline size_t AmbiChannelsFromOrder(size_t order) noexcept
  16 { return (order+1) * (order+1); }
  17 constexpr size_t MaxAmbiChannels{AmbiChannelsFromOrder(MaxAmbiOrder)};
  18
  19 /* A bitmask of ambisonic channels for 0 to 4th order. This only specifies up
  20  * to 4th order, which is the highest order a 32-bit mask value can specify (a
  21  * 64-bit mask could handle up to 7th order).
  22  */
  23 constexpr uint Ambi0OrderMask{0x00000001};
  24 constexpr uint Ambi1OrderMask{0x0000000f};
  25 constexpr uint Ambi2OrderMask{0x000001ff};
  26 constexpr uint Ambi3OrderMask{0x0000ffff};
  27 constexpr uint Ambi4OrderMask{0x01ffffff};
  28
  29 /* A bitmask of ambisonic channels with height information. If none of these
  30  * channels are used/needed, there's no height (e.g. with most surround sound
  31  * speaker setups). This is ACN ordering, with bit 0 being ACN 0, etc.
  32  */
  33 constexpr uint AmbiPeriphonicMask{0xfe7ce4};
  34
  35 /* The maximum number of ambisonic channels for 2D (non-periphonic)
  36  * representation. This is 2 per each order above zero-order, plus 1 for zero-
  37  * order. Or simply, o*2 + 1.
  38  */
  39 constexpr inline size_t Ambi2DChannelsFromOrder(size_t order) noexcept
  40 { return order*2 + 1; }
  41 constexpr size_t MaxAmbi2DChannels{Ambi2DChannelsFromOrder(MaxAmbiOrder)};
  42
  43
  44 /* NOTE: These are scale factors as applied to Ambisonics content. Decoder
  45  * coefficients should be divided by these values to get proper scalings.
  46  */
  47 struct AmbiScale {
  48     static auto& FromN3D() noexcept
  49     {
  50         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  51             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
  52             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f
  53         }};
  54         return ret;
  55     }
  56     static auto& FromSN3D() noexcept
  57     {
  58         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  59             1.000000000f, /* ACN  0, sqrt(1) */
  60             1.732050808f, /* ACN  1, sqrt(3) */
  61             1.732050808f, /* ACN  2, sqrt(3) */
  62             1.732050808f, /* ACN  3, sqrt(3) */
  63             2.236067978f, /* ACN  4, sqrt(5) */
  64             2.236067978f, /* ACN  5, sqrt(5) */
  65             2.236067978f, /* ACN  6, sqrt(5) */
  66             2.236067978f, /* ACN  7, sqrt(5) */
  67             2.236067978f, /* ACN  8, sqrt(5) */
  68             2.645751311f, /* ACN  9, sqrt(7) */
  69             2.645751311f, /* ACN 10, sqrt(7) */
  70             2.645751311f, /* ACN 11, sqrt(7) */
  71             2.645751311f, /* ACN 12, sqrt(7) */
  72             2.645751311f, /* ACN 13, sqrt(7) */
  73             2.645751311f, /* ACN 14, sqrt(7) */
  74             2.645751311f, /* ACN 15, sqrt(7) */
  75         }};
  76         return ret;
  77     }
  78     static auto& FromFuMa() noexcept
  79     {
  80         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  81             1.414213562f, /* ACN  0 (W), sqrt(2) */
  82             1.732050808f, /* ACN  1 (Y), sqrt(3) */
  83             1.732050808f, /* ACN  2 (Z), sqrt(3) */
  84             1.732050808f, /* ACN  3 (X), sqrt(3) */
  85             1.936491673f, /* ACN  4 (V), sqrt(15)/2 */
  86             1.936491673f, /* ACN  5 (T), sqrt(15)/2 */
  87             2.236067978f, /* ACN  6 (R), sqrt(5) */
  88             1.936491673f, /* ACN  7 (S), sqrt(15)/2 */
  89             1.936491673f, /* ACN  8 (U), sqrt(15)/2 */
  90             2.091650066f, /* ACN  9 (Q), sqrt(35/8) */
  91             1.972026594f, /* ACN 10 (O), sqrt(35)/3 */
  92             2.231093404f, /* ACN 11 (M), sqrt(224/45) */
  93             2.645751311f, /* ACN 12 (K), sqrt(7) */
  94             2.231093404f, /* ACN 13 (L), sqrt(224/45) */
  95             1.972026594f, /* ACN 14 (N), sqrt(35)/3 */
  96             2.091650066f, /* ACN 15 (P), sqrt(35/8) */
  97         }};
  98         return ret;
  99     }
 100     static auto& FromUHJ() noexcept
 101     {
 102         static constexpr const std::array<float,MaxAmbiChannels> ret{{
 103             1.000000000f, /* ACN  0 (W), sqrt(1) */
 104             1.224744871f, /* ACN  1 (Y), sqrt(3/2) */
 105             1.224744871f, /* ACN  2 (Z), sqrt(3/2) */
 106             1.224744871f, /* ACN  3 (X), sqrt(3/2) */
 107             /* Higher orders not relevant for UHJ. */
 108             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
 109         }};
 110         return ret;
 111     }
 112
 113     /* Retrieves per-order HF scaling factors for "upsampling" ambisonic data. */
 114     static std::array<float,MaxAmbiOrder+1> GetHFOrderScales(const uint in_order,
 115         const uint out_order) noexcept;
 116 };
 117
 118 struct AmbiIndex {
 119     static auto& FromFuMa() noexcept
 120     {
 121         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 122             0,  /* W */
 123             3,  /* X */
 124             1,  /* Y */
 125             2,  /* Z */
 126             6,  /* R */
 127             7,  /* S */
 128             5,  /* T */
 129             8,  /* U */
 130             4,  /* V */
 131             12, /* K */
 132             13, /* L */
 133             11, /* M */
 134             14, /* N */
 135             10, /* O */
 136             15, /* P */
 137             9,  /* Q */
 138         }};
 139         return ret;
 140     }
 141     static auto& FromFuMa2D() noexcept
 142     {
 143         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 144             0,  /* W */
 145             3,  /* X */
 146             1,  /* Y */
 147             8,  /* U */
 148             4,  /* V */
 149             15, /* P */
 150             9,  /* Q */
 151         }};
 152         return ret;
 153     }
 154
 155     static auto& FromACN() noexcept
 156     {
 157         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 158             0,  1,  2,  3,  4,  5,  6,  7,
 159             8,  9, 10, 11, 12, 13, 14, 15
 160         }};
 161         return ret;
 162     }
 163     static auto& FromACN2D() noexcept
 164     {
 165         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 166             0, 1,3, 4,8, 9,15
 167         }};
 168         return ret;
 169     }
 170
 171     static auto& OrderFromChannel() noexcept
 172     {
 173         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 174             0, 1,1,1, 2,2,2,2,2, 3,3,3,3,3,3,3,
 175         }};
 176         return ret;
 177     }
 178     static auto& OrderFrom2DChannel() noexcept
 179     {
 180         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 181             0, 1,1, 2,2, 3,3,
 182         }};
 183         return ret;
 184     }
 185 };
 186
 187 #endif /* CORE_AMBIDEFS_H */