core/ambidefs.h

   1 #ifndef CORE_AMBIDEFS_H
   2 #define CORE_AMBIDEFS_H
   3
   4 #include <array>
   5 #include <cstddef>
   6 #include <cstdint>
   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 inline constexpr auto MaxAmbiOrder = std::uint8_t{3};
  18 inline constexpr auto AmbiChannelsFromOrder(std::size_t order) noexcept -> std::size_t
  19 { return (order+1) * (order+1); }
  20 inline constexpr auto MaxAmbiChannels = size_t{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 inline constexpr uint Ambi0OrderMask{0x00000001};
  27 inline constexpr uint Ambi1OrderMask{0x0000000f};
  28 inline constexpr uint Ambi2OrderMask{0x000001ff};
  29 inline constexpr uint Ambi3OrderMask{0x0000ffff};
  30 inline 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 inline 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 inline constexpr auto Ambi2DChannelsFromOrder(std::size_t order) noexcept -> std::size_t
  43 { return order*2 + 1; }
  44 inline constexpr auto MaxAmbi2DChannels = std::size_t{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 inline constexpr std::array<float,MaxAmbiChannels> FromN3D{{
  52         1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
  53         1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f
  54     }};
  55     static inline constexpr std::array<float,MaxAmbiChannels> FromSN3D{{
  56         1.000000000f, /* ACN  0, sqrt(1) */
  57         1.732050808f, /* ACN  1, sqrt(3) */
  58         1.732050808f, /* ACN  2, sqrt(3) */
  59         1.732050808f, /* ACN  3, sqrt(3) */
  60         2.236067978f, /* ACN  4, sqrt(5) */
  61         2.236067978f, /* ACN  5, sqrt(5) */
  62         2.236067978f, /* ACN  6, sqrt(5) */
  63         2.236067978f, /* ACN  7, sqrt(5) */
  64         2.236067978f, /* ACN  8, sqrt(5) */
  65         2.645751311f, /* ACN  9, sqrt(7) */
  66         2.645751311f, /* ACN 10, sqrt(7) */
  67         2.645751311f, /* ACN 11, sqrt(7) */
  68         2.645751311f, /* ACN 12, sqrt(7) */
  69         2.645751311f, /* ACN 13, sqrt(7) */
  70         2.645751311f, /* ACN 14, sqrt(7) */
  71         2.645751311f, /* ACN 15, sqrt(7) */
  72     }};
  73     static inline constexpr std::array<float,MaxAmbiChannels> FromFuMa{{
  74         1.414213562f, /* ACN  0 (W), sqrt(2) */
  75         1.732050808f, /* ACN  1 (Y), sqrt(3) */
  76         1.732050808f, /* ACN  2 (Z), sqrt(3) */
  77         1.732050808f, /* ACN  3 (X), sqrt(3) */
  78         1.936491673f, /* ACN  4 (V), sqrt(15)/2 */
  79         1.936491673f, /* ACN  5 (T), sqrt(15)/2 */
  80         2.236067978f, /* ACN  6 (R), sqrt(5) */
  81         1.936491673f, /* ACN  7 (S), sqrt(15)/2 */
  82         1.936491673f, /* ACN  8 (U), sqrt(15)/2 */
  83         2.091650066f, /* ACN  9 (Q), sqrt(35/8) */
  84         1.972026594f, /* ACN 10 (O), sqrt(35)/3 */
  85         2.231093404f, /* ACN 11 (M), sqrt(224/45) */
  86         2.645751311f, /* ACN 12 (K), sqrt(7) */
  87         2.231093404f, /* ACN 13 (L), sqrt(224/45) */
  88         1.972026594f, /* ACN 14 (N), sqrt(35)/3 */
  89         2.091650066f, /* ACN 15 (P), sqrt(35/8) */
  90     }};
  91     static inline constexpr std::array<float,MaxAmbiChannels> FromUHJ{{
  92         1.000000000f, /* ACN  0 (W), sqrt(1) */
  93         1.224744871f, /* ACN  1 (Y), sqrt(3/2) */
  94         1.224744871f, /* ACN  2 (Z), sqrt(3/2) */
  95         1.224744871f, /* ACN  3 (X), sqrt(3/2) */
  96         /* Higher orders not relevant for UHJ. */
  97         1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f,
  98     }};
  99
 100     /* Retrieves per-order HF scaling factors for "upsampling" ambisonic data. */
 101     static std::array<float,MaxAmbiOrder+1> GetHFOrderScales(const uint src_order,
 102         const uint dev_order, const bool horizontalOnly) noexcept;
 103
 104     static const std::array<std::array<float,MaxAmbiChannels>,4> FirstOrderUp;
 105     static const std::array<std::array<float,MaxAmbiChannels>,4> FirstOrder2DUp;
 106     static const std::array<std::array<float,MaxAmbiChannels>,9> SecondOrderUp;
 107     static const std::array<std::array<float,MaxAmbiChannels>,9> SecondOrder2DUp;
 108     static const std::array<std::array<float,MaxAmbiChannels>,16> ThirdOrderUp;
 109     static const std::array<std::array<float,MaxAmbiChannels>,16> ThirdOrder2DUp;
 110     static const std::array<std::array<float,MaxAmbiChannels>,25> FourthOrder2DUp;
 111 };
 112
 113 struct AmbiIndex {
 114     static inline constexpr std::array<std::uint8_t,MaxAmbiChannels> FromFuMa{{
 115         0,  /* W */
 116         3,  /* X */
 117         1,  /* Y */
 118         2,  /* Z */
 119         6,  /* R */
 120         7,  /* S */
 121         5,  /* T */
 122         8,  /* U */
 123         4,  /* V */
 124         12, /* K */
 125         13, /* L */
 126         11, /* M */
 127         14, /* N */
 128         10, /* O */
 129         15, /* P */
 130         9,  /* Q */
 131     }};
 132     static inline constexpr std::array<std::uint8_t,MaxAmbi2DChannels> FromFuMa2D{{
 133         0,  /* W */
 134         3,  /* X */
 135         1,  /* Y */
 136         8,  /* U */
 137         4,  /* V */
 138         15, /* P */
 139         9,  /* Q */
 140     }};
 141
 142     static inline constexpr std::array<std::uint8_t,MaxAmbiChannels> FromACN{{
 143         0,  1,  2,  3,  4,  5,  6,  7,
 144         8,  9, 10, 11, 12, 13, 14, 15
 145     }};
 146     static inline constexpr std::array<std::uint8_t,MaxAmbi2DChannels> FromACN2D{{
 147         0, 1,3, 4,8, 9,15
 148     }};
 149
 150
 151     static inline constexpr std::array<std::uint8_t,MaxAmbiChannels> OrderFromChannel{{
 152         0, 1,1,1, 2,2,2,2,2, 3,3,3,3,3,3,3,
 153     }};
 154     static inline constexpr std::array<std::uint8_t,MaxAmbi2DChannels> OrderFrom2DChannel{{
 155         0, 1,1, 2,2, 3,3,
 156     }};
 157 };
 158
 159
 160 /**
 161  * Calculates ambisonic encoder coefficients using the X, Y, and Z direction
 162  * components, which must represent a normalized (unit length) vector.
 163  *
 164  * NOTE: The components use ambisonic coordinates. As a result:
 165  *
 166  * Ambisonic Y = OpenAL -X
 167  * Ambisonic Z = OpenAL Y
 168  * Ambisonic X = OpenAL -Z
 169  *
 170  * The components are ordered such that OpenAL's X, Y, and Z are the first,
 171  * second, and third parameters respectively -- simply negate X and Z.
 172  */
 173 constexpr auto CalcAmbiCoeffs(const float y, const float z, const float x)
 174 {
 175     const float xx{x*x}, yy{y*y}, zz{z*z}, xy{x*y}, yz{y*z}, xz{x*z};
 176
 177     return std::array<float,MaxAmbiChannels>{{
 178         /* Zeroth-order */
 179         1.0f, /* ACN 0 = 1 */
 180         /* First-order */
 181         al::numbers::sqrt3_v<float> * y, /* ACN 1 = sqrt(3) * Y */
 182         al::numbers::sqrt3_v<float> * z, /* ACN 2 = sqrt(3) * Z */
 183         al::numbers::sqrt3_v<float> * x, /* ACN 3 = sqrt(3) * X */
 184         /* Second-order */
 185         3.872983346e+00f * xy,               /* ACN 4 = sqrt(15) * X * Y */
 186         3.872983346e+00f * yz,               /* ACN 5 = sqrt(15) * Y * Z */
 187         1.118033989e+00f * (3.0f*zz - 1.0f), /* ACN 6 = sqrt(5)/2 * (3*Z*Z - 1) */
 188         3.872983346e+00f * xz,               /* ACN 7 = sqrt(15) * X * Z */
 189         1.936491673e+00f * (xx - yy),        /* ACN 8 = sqrt(15)/2 * (X*X - Y*Y) */
 190         /* Third-order */
 191         2.091650066e+00f * (y*(3.0f*xx - yy)),   /* ACN  9 = sqrt(35/8) * Y * (3*X*X - Y*Y) */
 192         1.024695076e+01f * (z*xy),               /* ACN 10 = sqrt(105) * Z * X * Y */
 193         1.620185175e+00f * (y*(5.0f*zz - 1.0f)), /* ACN 11 = sqrt(21/8) * Y * (5*Z*Z - 1) */
 194         1.322875656e+00f * (z*(5.0f*zz - 3.0f)), /* ACN 12 = sqrt(7)/2 * Z * (5*Z*Z - 3) */
 195         1.620185175e+00f * (x*(5.0f*zz - 1.0f)), /* ACN 13 = sqrt(21/8) * X * (5*Z*Z - 1) */
 196         5.123475383e+00f * (z*(xx - yy)),        /* ACN 14 = sqrt(105)/2 * Z * (X*X - Y*Y) */
 197         2.091650066e+00f * (x*(xx - 3.0f*yy)),   /* ACN 15 = sqrt(35/8) * X * (X*X - 3*Y*Y) */
 198         /* Fourth-order */
 199         /* ACN 16 = sqrt(35)*3/2 * X * Y * (X*X - Y*Y) */
 200         /* ACN 17 = sqrt(35/2)*3/2 * (3*X*X - Y*Y) * Y * Z */
 201         /* ACN 18 = sqrt(5)*3/2 * X * Y * (7*Z*Z - 1) */
 202         /* ACN 19 = sqrt(5/2)*3/2 * Y * Z * (7*Z*Z - 3) */
 203         /* ACN 20 = 3/8 * (35*Z*Z*Z*Z - 30*Z*Z + 3) */
 204         /* ACN 21 = sqrt(5/2)*3/2 * X * Z * (7*Z*Z - 3) */
 205         /* ACN 22 = sqrt(5)*3/4 * (X*X - Y*Y) * (7*Z*Z - 1) */
 206         /* ACN 23 = sqrt(35/2)*3/2 * (X*X - 3*Y*Y) * X * Z */
 207         /* ACN 24 = sqrt(35)*3/8 * (X*X*X*X - 6*X*X*Y*Y + Y*Y*Y*Y) */
 208     }};
 209 }
 210
 211 #endif /* CORE_AMBIDEFS_H */