commit 218b1a43ab670820786fdec12b6c13edf34867a6
parent bacf6f6498d6ef3d40e8d7e6af97a36ece729f6b
Author: [email protected] <[email protected]>
Date: Wed, 24 Aug 2016 04:50:47 +0300
Add documentation for DSP functions
Diffstat:
6 files changed, 139 insertions(+), 3 deletions(-)
diff --git a/include/kfr/dsp/delay.hpp b/include/kfr/dsp/delay.hpp
@@ -92,6 +92,15 @@ struct expression_delay<1, E> : expression<E>
};
}
+/**
+ * @brief Returns template expression that applies delay to the input (uses ring buffer internally)
+ * @param e1 an input expression
+ * @param samples delay in samples (must be a compile time value)
+ * @code
+ * univector<double, 10> v = counter();
+ * auto d = delay(v, csize<4>);
+ * @endcode
+ */
template <size_t samples = 1, typename E1>
CMT_INLINE internal::expression_delay<samples, E1> delay(E1&& e1, csize_t<samples> = csize<samples>)
{
diff --git a/include/kfr/dsp/fir.hpp b/include/kfr/dsp/fir.hpp
@@ -101,16 +101,28 @@ struct expression_fir : expression<E1>
};
}
+/**
+ * @brief Returns template expression that applies FIR filter to the input
+ * @param e1 an input expression
+ * @param taps coefficients for the FIR filter
+ */
template <typename T, typename E1, size_t Tag>
CMT_INLINE internal::expression_fir<T, E1> fir(E1&& e1, const univector<T, Tag>& taps)
{
return internal::expression_fir<T, E1>(std::forward<E1>(e1), taps.ref());
}
+
+/**
+ * @brief Returns template expression that applies FIR filter to the input (count of coefficients must be in
+ * range 2..32)
+ * @param e1 an input expression
+ * @param taps coefficients for the FIR filter
+ */
template <typename T, size_t TapCount, typename E1>
CMT_INLINE internal::expression_short_fir<TapCount, T, E1> short_fir(E1&& e1,
const univector<T, TapCount>& taps)
{
- static_assert(TapCount >= 1 && TapCount <= 32, "Use short_fir only for small FIR filters");
+ static_assert(TapCount >= 2 && TapCount <= 32, "Use short_fir only for small FIR filters");
return internal::expression_short_fir<TapCount, T, E1>(std::forward<E1>(e1), taps.ref());
}
}
diff --git a/include/kfr/dsp/fir_design.hpp b/include/kfr/dsp/fir_design.hpp
@@ -122,24 +122,57 @@ KFR_I_FN(fir_highpass)
KFR_I_FN(fir_bandpass)
KFR_I_FN(fir_bandstop)
+/**
+ * @brief Calculates coefficients for the low-pass FIR filter
+ * @param taps array where computed coefficients are stored
+ * @param cutoff Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param window pointer to a window function
+ * @param normalize true for normalized coefficients
+ */
template <typename T, size_t Tag>
CMT_INLINE void fir_lowpass(univector<T, Tag>& taps, identity<T> cutoff, const expression_pointer<T>& window,
bool normalize = true)
{
return intrinsics::fir_lowpass(taps.slice(), cutoff, window, normalize);
}
+
+/**
+ * @brief Calculates coefficients for the high-pass FIR filter
+ * @param taps array where computed coefficients are stored
+ * @param cutoff Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param window pointer to a window function
+ * @param normalize true for normalized coefficients
+ */
template <typename T, size_t Tag>
CMT_INLINE void fir_highpass(univector<T, Tag>& taps, identity<T> cutoff, const expression_pointer<T>& window,
bool normalize = true)
{
return intrinsics::fir_highpass(taps.slice(), cutoff, window, normalize);
}
+
+/**
+ * @brief Calculates coefficients for the band-pass FIR filter
+ * @param taps array where computed coefficients are stored
+ * @param frequency1 Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param frequency2 Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param window pointer to a window function
+ * @param normalize true for normalized coefficients
+ */
template <typename T, size_t Tag>
CMT_INLINE void fir_bandpass(univector<T, Tag>& taps, identity<T> frequency1, identity<T> frequency2,
const expression_pointer<T>& window, bool normalize = true)
{
return intrinsics::fir_bandpass(taps.slice(), frequency1, frequency2, window, normalize);
}
+
+/**
+ * @brief Calculates coefficients for the band-stop FIR filter
+ * @param taps array where computed coefficients are stored
+ * @param frequency1 Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param frequency2 Normalized frequency (frequency_Hz / samplerate_Hz)
+ * @param window pointer to a window function
+ * @param normalize true for normalized coefficients
+ */
template <typename T, size_t Tag>
CMT_INLINE void fir_bandstop(univector<T, Tag>& taps, identity<T> frequency1, identity<T> frequency2,
const expression_pointer<T>& window, bool normalize = true)
@@ -147,24 +180,39 @@ CMT_INLINE void fir_bandstop(univector<T, Tag>& taps, identity<T> frequency1, id
return intrinsics::fir_bandstop(taps.slice(), frequency1, frequency2, window, normalize);
}
+/**
+ * @copydoc kfr::fir_lowpass
+ */
template <typename T>
CMT_INLINE void fir_lowpass(const univector_ref<T>& taps, identity<T> cutoff,
const expression_pointer<T>& window, bool normalize = true)
{
return intrinsics::fir_lowpass(taps, cutoff, window, normalize);
}
+
+/**
+ * @copydoc kfr::fir_highpass
+ */
template <typename T>
CMT_INLINE void fir_highpass(const univector_ref<T>& taps, identity<T> cutoff,
const expression_pointer<T>& window, bool normalize = true)
{
return intrinsics::fir_highpass(taps, cutoff, window, normalize);
}
+
+/**
+ * @copydoc kfr::fir_bandpass
+ */
template <typename T>
CMT_INLINE void fir_bandpass(const univector_ref<T>& taps, identity<T> frequency1, identity<T> frequency2,
const expression_pointer<T>& window, bool normalize = true)
{
return intrinsics::fir_bandpass(taps, frequency1, frequency2, window, normalize);
}
+
+/**
+ * @copydoc kfr::fir_bandstop
+ */
template <typename T>
CMT_INLINE void fir_bandstop(const univector_ref<T>& taps, identity<T> frequency1, identity<T> frequency2,
const expression_pointer<T>& window, bool normalize = true)
diff --git a/include/kfr/dsp/impulse.hpp b/include/kfr/dsp/impulse.hpp
@@ -30,7 +30,9 @@
namespace kfr
{
-
+/**
+ * @brief Returns expression template that generates unit impulse
+ */
inline auto simpleimpulse()
{
return lambda([](cinput_t, size_t index, auto x) {
diff --git a/include/kfr/dsp/mixdown.hpp b/include/kfr/dsp/mixdown.hpp
@@ -29,7 +29,9 @@
namespace kfr
{
-
+/**
+ * @brief Returns template expression that returns the sum of all the inputs
+ */
template <typename... E>
internal::expression_function<fn_add, E...> mixdown(E&&... e)
{
@@ -57,6 +59,10 @@ struct stereo_matrix
constexpr f64x2x2 matrix_sum_diff() { return { f64x2{ 1, 1 }, f64x2{ 1, -1 } }; }
constexpr f64x2x2 matrix_halfsum_halfdiff() { return { f64x2{ 0.5, 0.5 }, f64x2{ 0.5, -0.5 } }; }
+/**
+ * @brief Returns template expression that returns the vector of length 2 containing mix of the left and right
+ * channels
+ */
template <typename Left, typename Right,
typename Result = internal::expression_function<
internal::stereo_matrix, internal::expression_pack<internal::arg<Left>, internal::arg<Right>>>>
diff --git a/include/kfr/dsp/window.hpp b/include/kfr/dsp/window.hpp
@@ -468,46 +468,83 @@ KFR_WINDOW_BY_TYPE(lanczos)
#undef KFR_WINDOW_BY_TYPE
}
+/**
+ * @brief Returns template expression that generates Rrectangular window of length @c size
+ */
CMT_INLINE internal::expression_rectangular<fbase> window_rectangular(size_t size)
{
return internal::expression_rectangular<fbase>(size, fbase());
}
+
+/**
+ * @brief Returns template expression that generates Triangular window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_triangular<T> window_triangular(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_triangular<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Bartlett window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_bartlett<T> window_bartlett(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_bartlett<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Cosine window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_cosine<T> window_cosine(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_cosine<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Hann window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_hann<T> window_hann(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_hann<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Bartlett-Hann window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_bartlett_hann<T> window_bartlett_hann(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_bartlett_hann<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Hamming window of length @c size where α = @c
+ * alpha
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_hamming<T> window_hamming(size_t size, identity<T> alpha = 0.54,
ctype_t<T> = ctype_t<T>())
{
return internal::expression_hamming<T>(size, alpha);
}
+
+/**
+ * @brief Returns template expression that generates Bohman window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_bohman<T> window_bohman(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_bohman<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Blackman window of length @c size where α = @c
+ * alpha
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_blackman<T> window_blackman(
size_t size, identity<T> alpha = 0.16, window_symmetry symmetry = window_symmetry::symmetric,
@@ -515,29 +552,51 @@ CMT_INLINE internal::expression_blackman<T> window_blackman(
{
return internal::expression_blackman<T>(size, alpha, symmetry);
}
+
+/**
+ * @brief Returns template expression that generates Blackman-Harris window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_blackman_harris<T> window_blackman_harris(
size_t size, window_symmetry symmetry = window_symmetry::symmetric, ctype_t<T> = ctype_t<T>())
{
return internal::expression_blackman_harris<T>(size, T(), symmetry);
}
+
+/**
+ * @brief Returns template expression that generates Kaiser window of length @c size where β = @c
+ * beta
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_kaiser<T> window_kaiser(size_t size, identity<T> beta = T(0.5),
ctype_t<T> = ctype_t<T>())
{
return internal::expression_kaiser<T>(size, beta);
}
+
+/**
+ * @brief Returns template expression that generates Flat top window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_flattop<T> window_flattop(size_t size, ctype_t<T> = ctype_t<T>())
{
return internal::expression_flattop<T>(size);
}
+
+/**
+ * @brief Returns template expression that generates Gaussian window of length @c size where α = @c
+ * alpha
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_gaussian<T> window_gaussian(size_t size, identity<T> alpha = 2.5,
ctype_t<T> = ctype_t<T>())
{
return internal::expression_gaussian<T>(size, alpha);
}
+
+/**
+ * @brief Returns template expression that generates Lanczos window of length @c size
+ */
template <typename T = fbase>
CMT_INLINE internal::expression_lanczos<T> window_lanczos(size_t size, ctype_t<T> = ctype_t<T>())
{
