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 #include "alnumbers.h"
   9
  10
  11 using uint = unsigned int;
  12
  13 /* The maximum number of Ambisonics channels. For a given order (o), the size
  14  * needed will be (o+1)**2, thus zero-order has 1, first-order has 4, second-
  15  * order has 9, third-order has 16, and fourth-order has 25.
  16  */
  17 constexpr uint8_t MaxAmbiOrder{3};
  18 constexpr inline size_t AmbiChannelsFromOrder(size_t order) noexcept
  19 { return (order+1) * (order+1); }
  20 constexpr size_t MaxAmbiChannels{AmbiChannelsFromOrder(MaxAmbiOrder)};
  21
  22 /* A bitmask of ambisonic channels for 0 to 4th order. This only specifies up
  23  * to 4th order, which is the highest order a 32-bit mask value can specify (a
  24  * 64-bit mask could handle up to 7th order).
  25  */
  26 constexpr uint Ambi0OrderMask{0x00000001};
  27 constexpr uint Ambi1OrderMask{0x0000000f};
  28 constexpr uint Ambi2OrderMask{0x000001ff};
  29 constexpr uint Ambi3OrderMask{0x0000ffff};
  30 constexpr uint Ambi4OrderMask{0x01ffffff};
  31
  32 /* A bitmask of ambisonic channels with height information. If none of these
  33  * channels are used/needed, there's no height (e.g. with most surround sound
  34  * speaker setups). This is ACN ordering, with bit 0 being ACN 0, etc.
  35  */
  36 constexpr uint AmbiPeriphonicMask{0xfe7ce4};
  37
  38 /* The maximum number of ambisonic channels for 2D (non-periphonic)
  39  * representation. This is 2 per each order above zero-order, plus 1 for zero-
  40  * order. Or simply, o*2 + 1.
  41  */
  42 constexpr inline size_t Ambi2DChannelsFromOrder(size_t order) noexcept
  43 { return order*2 + 1; }
  44 constexpr size_t MaxAmbi2DChannels{Ambi2DChannelsFromOrder(MaxAmbiOrder)};
  45
  46
  47 /* NOTE: These are scale factors as applied to Ambisonics content. Decoder
  48  * coefficients should be divided by these values to get proper scalings.
  49  */
  50 struct AmbiScale {
  51     static auto& FromN3D() noexcept
  52     {
  53         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  54             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
  55             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f
  56         }};
  57         return ret;
  58     }
  59     static auto& FromSN3D() noexcept
  60     {
  61         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  62             1.000000000f, /* ACN  0, sqrt(1) */
  63             1.732050808f, /* ACN  1, sqrt(3) */
  64             1.732050808f, /* ACN  2, sqrt(3) */
  65             1.732050808f, /* ACN  3, sqrt(3) */
  66             2.236067978f, /* ACN  4, sqrt(5) */
  67             2.236067978f, /* ACN  5, sqrt(5) */
  68             2.236067978f, /* ACN  6, sqrt(5) */
  69             2.236067978f, /* ACN  7, sqrt(5) */
  70             2.236067978f, /* ACN  8, sqrt(5) */
  71             2.645751311f, /* ACN  9, sqrt(7) */
  72             2.645751311f, /* ACN 10, sqrt(7) */
  73             2.645751311f, /* ACN 11, sqrt(7) */
  74             2.645751311f, /* ACN 12, sqrt(7) */
  75             2.645751311f, /* ACN 13, sqrt(7) */
  76             2.645751311f, /* ACN 14, sqrt(7) */
  77             2.645751311f, /* ACN 15, sqrt(7) */
  78         }};
  79         return ret;
  80     }
  81     static auto& FromFuMa() noexcept
  82     {
  83         static constexpr const std::array<float,MaxAmbiChannels> ret{{
  84             1.414213562f, /* ACN  0 (W), sqrt(2) */
  85             1.732050808f, /* ACN  1 (Y), sqrt(3) */
  86             1.732050808f, /* ACN  2 (Z), sqrt(3) */
  87             1.732050808f, /* ACN  3 (X), sqrt(3) */
  88             1.936491673f, /* ACN  4 (V), sqrt(15)/2 */
  89             1.936491673f, /* ACN  5 (T), sqrt(15)/2 */
  90             2.236067978f, /* ACN  6 (R), sqrt(5) */
  91             1.936491673f, /* ACN  7 (S), sqrt(15)/2 */
  92             1.936491673f, /* ACN  8 (U), sqrt(15)/2 */
  93             2.091650066f, /* ACN  9 (Q), sqrt(35/8) */
  94             1.972026594f, /* ACN 10 (O), sqrt(35)/3 */
  95             2.231093404f, /* ACN 11 (M), sqrt(224/45) */
  96             2.645751311f, /* ACN 12 (K), sqrt(7) */
  97             2.231093404f, /* ACN 13 (L), sqrt(224/45) */
  98             1.972026594f, /* ACN 14 (N), sqrt(35)/3 */
  99             2.091650066f, /* ACN 15 (P), sqrt(35/8) */
 100         }};
 101         return ret;
 102     }
 103     static auto& FromUHJ() noexcept
 104     {
 105         static constexpr const std::array<float,MaxAmbiChannels> ret{{
 106             1.000000000f, /* ACN  0 (W), sqrt(1) */
 107             1.224744871f, /* ACN  1 (Y), sqrt(3/2) */
 108             1.224744871f, /* ACN  2 (Z), sqrt(3/2) */
 109             1.224744871f, /* ACN  3 (X), sqrt(3/2) */
 110             /* Higher orders not relevant for UHJ. */
 111             1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
 112         }};
 113         return ret;
 114     }
 115
 116     /* Retrieves per-order HF scaling factors for "upsampling" ambisonic data. */
 117     static std::array<float,MaxAmbiOrder+1> GetHFOrderScales(const uint src_order,
 118         const uint dev_order, const bool horizontalOnly) noexcept;
 119
 120     static const std::array<std::array<float,MaxAmbiChannels>,4> FirstOrderUp;
 121     static const std::array<std::array<float,MaxAmbiChannels>,4> FirstOrder2DUp;
 122     static const std::array<std::array<float,MaxAmbiChannels>,9> SecondOrderUp;
 123     static const std::array<std::array<float,MaxAmbiChannels>,9> SecondOrder2DUp;
 124     static const std::array<std::array<float,MaxAmbiChannels>,16> ThirdOrderUp;
 125     static const std::array<std::array<float,MaxAmbiChannels>,16> ThirdOrder2DUp;
 126     static const std::array<std::array<float,MaxAmbiChannels>,25> FourthOrder2DUp;
 127 };
 128
 129 struct AmbiIndex {
 130     static auto& FromFuMa() noexcept
 131     {
 132         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 133             0,  /* W */
 134             3,  /* X */
 135             1,  /* Y */
 136             2,  /* Z */
 137             6,  /* R */
 138             7,  /* S */
 139             5,  /* T */
 140             8,  /* U */
 141             4,  /* V */
 142             12, /* K */
 143             13, /* L */
 144             11, /* M */
 145             14, /* N */
 146             10, /* O */
 147             15, /* P */
 148             9,  /* Q */
 149         }};
 150         return ret;
 151     }
 152     static auto& FromFuMa2D() noexcept
 153     {
 154         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 155             0,  /* W */
 156             3,  /* X */
 157             1,  /* Y */
 158             8,  /* U */
 159             4,  /* V */
 160             15, /* P */
 161             9,  /* Q */
 162         }};
 163         return ret;
 164     }
 165
 166     static auto& FromACN() noexcept
 167     {
 168         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 169             0,  1,  2,  3,  4,  5,  6,  7,
 170             8,  9, 10, 11, 12, 13, 14, 15
 171         }};
 172         return ret;
 173     }
 174     static auto& FromACN2D() noexcept
 175     {
 176         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 177             0, 1,3, 4,8, 9,15
 178         }};
 179         return ret;
 180     }
 181
 182     static auto& OrderFromChannel() noexcept
 183     {
 184         static constexpr const std::array<uint8_t,MaxAmbiChannels> ret{{
 185             0, 1,1,1, 2,2,2,2,2, 3,3,3,3,3,3,3,
 186         }};
 187         return ret;
 188     }
 189     static auto& OrderFrom2DChannel() noexcept
 190     {
 191         static constexpr const std::array<uint8_t,MaxAmbi2DChannels> ret{{
 192             0, 1,1, 2,2, 3,3,
 193         }};
 194         return ret;
 195     }
 196 };
 197
 198
 199 /**
 200  * Calculates ambisonic encoder coefficients using the X, Y, and Z direction
 201  * components, which must represent a normalized (unit length) vector.
 202  *
 203  * NOTE: The components use ambisonic coordinates. As a result:
 204  *
 205  * Ambisonic Y = OpenAL -X
 206  * Ambisonic Z = OpenAL Y
 207  * Ambisonic X = OpenAL -Z
 208  *
 209  * The components are ordered such that OpenAL's X, Y, and Z are the first,
 210  * second, and third parameters respectively -- simply negate X and Z.
 211  */
 212 constexpr auto CalcAmbiCoeffs(const float y, const float z, const float x)
 213 {
 214     const float xx{x*x}, yy{y*y}, zz{z*z}, xy{x*y}, yz{y*z}, xz{x*z};
 215
 216     return std::array<float,MaxAmbiChannels>{{
 217         /* Zeroth-order */
 218         1.0f, /* ACN 0 = 1 */
 219         /* First-order */
 220         al::numbers::sqrt3_v<float> * y, /* ACN 1 = sqrt(3) * Y */
 221         al::numbers::sqrt3_v<float> * z, /* ACN 2 = sqrt(3) * Z */
 222         al::numbers::sqrt3_v<float> * x, /* ACN 3 = sqrt(3) * X */
 223         /* Second-order */
 224         3.872983346e+00f * xy,               /* ACN 4 = sqrt(15) * X * Y */
 225         3.872983346e+00f * yz,               /* ACN 5 = sqrt(15) * Y * Z */
 226         1.118033989e+00f * (3.0f*zz - 1.0f), /* ACN 6 = sqrt(5)/2 * (3*Z*Z - 1) */
 227         3.872983346e+00f * xz,               /* ACN 7 = sqrt(15) * X * Z */
 228         1.936491673e+00f * (xx - yy),        /* ACN 8 = sqrt(15)/2 * (X*X - Y*Y) */
 229         /* Third-order */
 230         2.091650066e+00f * (y*(3.0f*xx - yy)),   /* ACN  9 = sqrt(35/8) * Y * (3*X*X - Y*Y) */
 231         1.024695076e+01f * (z*xy),               /* ACN 10 = sqrt(105) * Z * X * Y */
 232         1.620185175e+00f * (y*(5.0f*zz - 1.0f)), /* ACN 11 = sqrt(21/8) * Y * (5*Z*Z - 1) */
 233         1.322875656e+00f * (z*(5.0f*zz - 3.0f)), /* ACN 12 = sqrt(7)/2 * Z * (5*Z*Z - 3) */
 234         1.620185175e+00f * (x*(5.0f*zz - 1.0f)), /* ACN 13 = sqrt(21/8) * X * (5*Z*Z - 1) */
 235         5.123475383e+00f * (z*(xx - yy)),        /* ACN 14 = sqrt(105)/2 * Z * (X*X - Y*Y) */
 236         2.091650066e+00f * (x*(xx - 3.0f*yy)),   /* ACN 15 = sqrt(35/8) * X * (X*X - 3*Y*Y) */
 237         /* Fourth-order */
 238         /* ACN 16 = sqrt(35)*3/2 * X * Y * (X*X - Y*Y) */
 239         /* ACN 17 = sqrt(35/2)*3/2 * (3*X*X - Y*Y) * Y * Z */
 240         /* ACN 18 = sqrt(5)*3/2 * X * Y * (7*Z*Z - 1) */
 241         /* ACN 19 = sqrt(5/2)*3/2 * Y * Z * (7*Z*Z - 3) */
 242         /* ACN 20 = 3/8 * (35*Z*Z*Z*Z - 30*Z*Z + 3) */
 243         /* ACN 21 = sqrt(5/2)*3/2 * X * Z * (7*Z*Z - 3) */
 244         /* ACN 22 = sqrt(5)*3/4 * (X*X - Y*Y) * (7*Z*Z - 1) */
 245         /* ACN 23 = sqrt(35/2)*3/2 * (X*X - 3*Y*Y) * X * Z */
 246         /* ACN 24 = sqrt(35)*3/8 * (X*X*X*X - 6*X*X*Y*Y + Y*Y*Y*Y) */
 247     }};
 248 }
 249
 250 #endif /* CORE_AMBIDEFS_H */