Deps: Add freesurround

dep/freesurround/include/freesurround_decoder.h

@@ -0,0 +1,191 @@
+// SPDX-FileCopyrightText: 2007-2010 Christian Kothe, 2024 Connor McLaughlin <stenzek@gmail.com>
+// SPDX-License-Identifier: GPL-2.0+
+
+#pragma once
+
+#include "kiss_fftr.h"
+
+#include <array>
+#include <cmath>
+#include <complex>
+#include <span>
+#include <vector>
+
+/**
+ * The FreeSurround decoder.
+ */
+class FreeSurroundDecoder
+{
+public:
+  /**
+   * The supported output channel setups.
+   * A channel setup is defined by the set of channels that are present. Here is a graphic
+   * of the cs_5point1 setup: http://en.wikipedia.org/wiki/File:5_1_channels_(surround_sound)_label.svg
+   */
+  enum class ChannelSetup
+  {
+    Stereo,
+    Surround41,
+    Surround51,
+    Surround71,
+    Legacy, // same channels as cs_5point1 but different upmixing transform; does not support the focus control
+    MaxCount
+  };
+
+  static constexpr int grid_res = 21; // resolution of the lookup grid
+  using LUT = const float (*)[grid_res];
+
+  /**
+   * Create an instance of the decoder.
+   * @param setup The output channel setup -- determines the number of output channels
+   *			   and their place in the sound field.
+   * @param blocksize Granularity at which data is processed by the decode() function.
+   *				   Must be a power of two and should correspond to ca. 10ms worth of single-channel
+   *				   samples (default is 4096 for 44.1Khz data). Do not make it shorter or longer
+   *				   than 5ms to 20ms since the granularity at which locations are decoded
+   *				   changes with this.
+   */
+  FreeSurroundDecoder(ChannelSetup setup = ChannelSetup::Surround51, unsigned blocksize = 4096);
+  ~FreeSurroundDecoder();
+
+  /**
+   * Decode a chunk of stereo sound. The output is delayed by half of the blocksize.
+   * This function is the only one needed for straightforward decoding.
+   * @param input Contains exactly blocksize (multiplexed) stereo samples, i.e. 2*blocksize numbers.
+   * @return A pointer to an internal buffer of exactly blocksize (multiplexed) multichannel samples.
+   *		  The actual number of values depends on the number of output channels in the chosen
+   *		  channel setup.
+   */
+  float* Decode(float* input);
+
+  /**
+   * Flush the internal buffer.
+   */
+  void Flush();
+
+  // --- soundfield transformations
+  // These functions allow to set up geometric transformations of the sound field after it has been decoded.
+  // The sound field is best pictured as a 2-dimensional square with the listener in its
+  // center which can be shifted or stretched in various ways before it is sent to the
+  // speakers. The order in which these transformations are applied is as listed below.
+
+  /**
+   * Allows to wrap the soundfield around the listener in a circular manner.
+   * Determines the angle of the frontal sound stage relative to the listener, in degrees.
+   * A setting of 90° corresponds to standard surround decoding, 180° stretches the front stage from
+   * ear to ear, 270° wraps it around most of the head. The side and rear content of the sound
+   * field is compressed accordingly behind the listerer. (default: 90, range: [0°..360°])
+   */
+  void SetCircularWrap(float v);
+
+  /**
+   * Allows to shift the soundfield forward or backward.
+   * Value range: [-1.0..+1.0]. 0 is no offset, positive values move the sound
+   * forward, negative values move it backwards. (default: 0)
+   */
+  void SetShift(float v);
+
+  /**
+   * Allows to scale the soundfield backwards.
+   * Value range: [0.0..+5.0] -- 0 is all compressed to the front, 1 is no change, 5 is scaled 5x backwards (default: 1)
+   */
+  void SetDepth(float v);
+
+  /**
+   * Allows to control the localization (i.e., focality) of sources.
+   * Value range: [-1.0..+1.0] -- 0 means unchanged, positive means more localized, negative means more ambient
+   * (default: 0)
+   */
+  void SetFocus(float v);
+
+  // --- rendering parameters
+  // These parameters control how the sound field is mapped onto speakers.
+
+  /**
+   * Set the presence of the front center channel(s).
+   * Value range: [0.0..1.0] -- fully present at 1.0, fully replaced by left/right at 0.0 (default: 1).
+   * The default of 1.0 results in spec-conformant decoding ("movie mode") while a value of 0.7 is
+   * better suited for music reproduction (which is usually mixed without a center channel).
+   */
+  void SetCenterImage(float v);
+
+  /**
+   * Set the front stereo separation.
+   * Value range: [0.0..inf] -- 1.0 is default, 0.0 is mono.
+   */
+  void SetFrontSeparation(float v);
+
+  /**
+   * Set the rear stereo separation.
+   * Value range: [0.0..inf] -- 1.0 is default, 0.0 is mono.
+   */
+  void SetRearSeparation(float v);
+
+  // --- bass redirection (to LFE)
+
+  /**
+   * Enable/disable LFE channel (default: false = disabled)
+   */
+  void SetBassRedirection(bool v);
+
+  /**
+   * Set the lower end of the transition band, in Hz/Nyquist (default: 40/22050).
+   */
+  void SetLowCutoff(float v);
+
+  /**
+   * Set the upper end of the transition band, in Hz/Nyquist (default: 90/22050).
+   */
+  void SetHighCutoff(float v);
+
+  // --- info
+
+  /**
+   * Number of samples currently held in the buffer.
+   */
+  unsigned GetSamplesBuffered();
+
+private:
+  using cplx = std::complex<double>;
+
+  struct ChannelMap
+  {
+    std::span<const LUT> luts;
+    const float* xsf;
+  };
+
+  static const std::array<ChannelMap, static_cast<size_t>(ChannelSetup::MaxCount)> s_channel_maps;
+
+  void BufferedDecode(float* input);
+
+  // get the index (and fractional offset!) in a piecewise-linear channel allocation grid
+  static int MapToGrid(double& x);
+
+  // constants
+  const ChannelMap& cmap; // the channel setup
+  unsigned N, C;          // number of samples per input/output block, number of output channels
+
+  // parameters
+  float circular_wrap;    // angle of the front soundstage around the listener (90°=default)
+  float shift;            // forward/backward offset of the soundstage
+  float depth;            // backward extension of the soundstage
+  float focus;            // localization of the sound events
+  float center_image;     // presence of the center speaker
+  float front_separation; // front stereo separation
+  float rear_separation;  // rear stereo separation
+  float lo_cut, hi_cut;   // LFE cutoff frequencies
+  bool use_lfe;           // whether to use the LFE channel
+
+  // FFT data structures
+  std::vector<double> lt, rt, dst; // left total, right total (source arrays), time-domain destination buffer array
+  std::vector<cplx> lf, rf;        // left total / right total in frequency domain
+  kiss_fftr_cfg forward = nullptr;
+  kiss_fftr_cfg inverse = nullptr; // FFT buffers
+
+  // buffers
+  bool buffer_empty = true;              // whether the buffer is currently empty or dirty
+  std::vector<float> inbuf;              // stereo input buffer (multiplexed)
+  std::vector<float> outbuf;             // multichannel output buffer (multiplexed)
+  std::vector<double> wnd;               // the window function, precomputed
+  std::vector<std::vector<cplx>> signal; // the signal to be constructed in every channel, in the frequency domain
+};