commit 4f58faa60bc45a02915b57c77e9e41e6c2950e14
parent d0e3d860cc3486240d834e61adad246a2a8a9be7
Author: [email protected] <[email protected]>
Date: Tue, 4 Apr 2017 02:36:47 +0300
Update documentation
Diffstat:
8 files changed, 41 insertions(+), 10 deletions(-)
diff --git a/include/kfr/base/bitwise.hpp b/include/kfr/base/bitwise.hpp
@@ -42,7 +42,7 @@ CMT_INLINE double bitwiseand(double x, double y) { return fbitcast(ubitcast(x) &
CMT_INLINE double bitwiseandnot(double x, double y) { return fbitcast(ubitcast(x) & ~ubitcast(y)); }
CMT_INLINE double bitwisexor(double x, double y) { return fbitcast(ubitcast(x) ^ ubitcast(y)); }
-/// Bitwise Not
+/// @brief Bitwise Not
template <typename T1>
CMT_INLINE T1 bitwisenot(const T1& x)
{
@@ -50,7 +50,7 @@ CMT_INLINE T1 bitwisenot(const T1& x)
}
KFR_FN(bitwisenot)
-/// Bitwise And
+/// @brief Bitwise And
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> bitwiseand(const T1& x, const T2& y)
{
@@ -63,7 +63,7 @@ constexpr CMT_INLINE T bitwiseand(initialvalue<T>)
}
KFR_FN(bitwiseand)
-/// Bitwise And-Not
+/// @brief Bitwise And-Not
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> bitwiseandnot(const T1& x, const T2& y)
{
@@ -76,7 +76,7 @@ constexpr inline T bitwiseandnot(initialvalue<T>)
}
KFR_FN(bitwiseandnot)
-/// Bitwise Or
+/// @brief Bitwise Or
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> bitwiseor(const T1& x, const T2& y)
{
@@ -89,7 +89,7 @@ constexpr CMT_INLINE T bitwiseor(initialvalue<T>)
}
KFR_FN(bitwiseor)
-/// Bitwise Xor (Exclusive Or)
+/// @brief Bitwise Xor (Exclusive Or)
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> bitwisexor(const T1& x, const T2& y)
{
@@ -102,7 +102,7 @@ constexpr CMT_INLINE T bitwisexor(initialvalue<T>)
}
KFR_FN(bitwisexor)
-/// Bitwise Left shift
+/// @brief Bitwise Left shift
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> shl(const T1& left, const T2& right)
{
@@ -110,7 +110,7 @@ CMT_INLINE common_type<T1, T2> shl(const T1& left, const T2& right)
}
KFR_FN(shl)
-/// Bitwise Right shift
+/// @brief Bitwise Right shift
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> shr(const T1& left, const T2& right)
{
@@ -118,7 +118,7 @@ CMT_INLINE common_type<T1, T2> shr(const T1& left, const T2& right)
}
KFR_FN(shr)
-/// Bitwise Left Rotate
+/// @brief Bitwise Left Rotate
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> rol(const T1& left, const T2& right)
{
@@ -126,7 +126,7 @@ CMT_INLINE common_type<T1, T2> rol(const T1& left, const T2& right)
}
KFR_FN(rol)
-/// Bitwise Right Rotate
+/// @brief Bitwise Right Rotate
template <typename T1, typename T2>
CMT_INLINE common_type<T1, T2> ror(const T1& left, const T2& right)
{
diff --git a/include/kfr/base/clamp.hpp b/include/kfr/base/clamp.hpp
@@ -47,6 +47,7 @@ KFR_SINTRIN vec<T, N> clamp(const vec<T, N>& x, const vec<T, N>& hi)
}
KFR_I_FN(clamp)
+/// @brief Returns the first argument clamped to a range [lo, hi]
template <typename T1, typename T2, typename T3, KFR_ENABLE_IF(is_numeric_args<T1, T2, T3>::value),
typename Tout = common_type<T1, T2, T3>>
KFR_INTRIN Tout clamp(const T1& x, const T2& lo, const T3& hi)
@@ -54,12 +55,14 @@ KFR_INTRIN Tout clamp(const T1& x, const T2& lo, const T3& hi)
return intrinsics::clamp(static_cast<Tout>(x), static_cast<Tout>(lo), static_cast<Tout>(hi));
}
+/// @brief Creates an expression that returns the first argument clamped to a range [lo, hi]
template <typename E1, typename E2, typename E3, KFR_ENABLE_IF(is_input_expressions<E1, E2, E3>::value)>
KFR_INTRIN internal::expression_function<fn::clamp, E1, E2, E3> clamp(E1&& x, E2&& lo, E3&& hi)
{
return { fn::clamp(), std::forward<E1>(x), std::forward<E2>(lo), std::forward<E3>(hi) };
}
+/// @brief Returns the first argument clamped to a range [0, hi]
template <typename T1, typename T2, KFR_ENABLE_IF(is_numeric_args<T1, T2>::value),
typename Tout = common_type<T1, T2>>
KFR_INTRIN Tout clamp(const T1& x, const T2& hi)
@@ -67,6 +70,7 @@ KFR_INTRIN Tout clamp(const T1& x, const T2& hi)
return intrinsics::clamp(static_cast<Tout>(x), static_cast<Tout>(hi));
}
+/// @brief Creates an expression that returns the first argument clamped to a range [0, hi]
template <typename E1, typename E2, KFR_ENABLE_IF(is_input_expressions<E1, E2>::value)>
KFR_INTRIN internal::expression_function<fn::clamp, E1, E2> clamp(E1&& x, E2&& hi)
{
diff --git a/include/kfr/base/filter.hpp b/include/kfr/base/filter.hpp
@@ -32,31 +32,38 @@
namespace kfr
{
+/// @brief Abstract base class for filters with one argument. Mainly for DSP
template <typename T>
class filter
{
public:
virtual ~filter() {}
+
+ /// @brief Resets internal state (such as delay line)
virtual void reset() {}
+ /// @brief Applies filter to a static array
template <size_t Size>
void apply(T (&buffer)[Size])
{
process_buffer(buffer, buffer, Size);
}
+ /// @brief Applies filter to a static array and writes the result to another array
template <size_t Size>
void apply(T (&dest)[Size], T (&src)[Size])
{
process_buffer(dest, src, Size);
}
+ /// @brief Applies filter to a univector
template <size_t Tag>
void apply(univector<T, Tag>& buffer)
{
process_buffer(buffer.data(), buffer.data(), buffer.size());
}
+ /// @brief Applies filter to a univector and write the result to another univector
template <size_t Tag1, size_t Tag2>
void apply(univector<T, Tag1>& dest, const univector<T, Tag2>& src)
{
diff --git a/include/kfr/base/gamma.hpp b/include/kfr/base/gamma.hpp
@@ -67,24 +67,28 @@ KFR_I_FLT_CONVERTER(factorial_approx)
KFR_I_FN(gamma)
KFR_I_FN(factorial_approx)
+/// @brief Returns the approximate gamma function of an argument
template <typename T1, KFR_ENABLE_IF(is_numeric<T1>::value)>
KFR_FUNC flt_type<T1> gamma(const T1& x)
{
return intrinsics::gamma(x);
}
+/// @brief Creates expression that returns the approximate gamma function of an argument
template <typename E1, KFR_ENABLE_IF(is_input_expression<E1>::value)>
KFR_FUNC internal::expression_function<fn::gamma, E1> gamma(E1&& x)
{
return { fn::gamma(), std::forward<E1>(x) };
}
+/// @brief Returns the approximate factorial of an argument
template <typename T1, KFR_ENABLE_IF(is_numeric<T1>::value)>
KFR_FUNC flt_type<T1> factorial_approx(const T1& x)
{
return intrinsics::factorial_approx(x);
}
+/// @brief Creates expression that returns the approximate factorial of an argument
template <typename E1, KFR_ENABLE_IF(is_input_expression<E1>::value)>
KFR_FUNC internal::expression_function<fn::factorial_approx, E1> factorial_approx(E1&& x)
{
diff --git a/include/kfr/base/saturation.hpp b/include/kfr/base/saturation.hpp
@@ -160,6 +160,7 @@ KFR_I_CONVERTER(satsub)
KFR_I_FN(satadd)
KFR_I_FN(satsub)
+/// @brief Adds two arguments using saturation
template <typename T1, typename T2, KFR_ENABLE_IF(is_numeric_args<T1, T2>::value),
typename Tout = common_type<T1, T2>>
KFR_INTRIN Tout satadd(const T1& x, const T2& y)
@@ -167,12 +168,14 @@ KFR_INTRIN Tout satadd(const T1& x, const T2& y)
return intrinsics::satadd(x, y);
}
+/// @brief Creates an expression that adds two arguments using saturation
template <typename E1, typename E2, KFR_ENABLE_IF(is_input_expressions<E1, E2>::value)>
KFR_INTRIN internal::expression_function<fn::satadd, E1, E2> satadd(E1&& x, E2&& y)
{
return { fn::satadd(), std::forward<E1>(x), std::forward<E2>(y) };
}
+/// @brief Subtracts two arguments using saturation
template <typename T1, typename T2, KFR_ENABLE_IF(is_numeric_args<T1, T2>::value),
typename Tout = common_type<T1, T2>>
KFR_INTRIN Tout satsub(const T1& x, const T2& y)
@@ -180,6 +183,7 @@ KFR_INTRIN Tout satsub(const T1& x, const T2& y)
return intrinsics::satsub(x, y);
}
+/// @brief Creates an expression that subtracts two arguments using saturation
template <typename E1, typename E2, KFR_ENABLE_IF(is_input_expressions<E1, E2>::value)>
KFR_INTRIN internal::expression_function<fn::satsub, E1, E2> satsub(E1&& x, E2&& y)
{
diff --git a/include/kfr/io/file.hpp b/include/kfr/io/file.hpp
@@ -113,20 +113,26 @@ struct expression_file_reader : expression_file_base, input_expression
};
}
+/// @brief Creates an expression that returns values from the given file (sequential access)
inline internal::expression_sequential_file_reader sequential_file_reader(const std::string& file_name)
{
return internal::expression_sequential_file_reader(fopen(file_name.c_str(), "rb"));
}
+
+/// @brief Creates an output expression that writes values to the given file (sequential access)
inline internal::expression_sequential_file_writer sequential_file_writer(const std::string& file_name)
{
return internal::expression_sequential_file_writer(fopen(file_name.c_str(), "wb"));
}
+/// @brief Creates an expression that returns values from the given file (random access)
template <typename T = u8>
internal::expression_file_reader<T> file_reader(const std::string& file_name)
{
return internal::expression_file_reader<T>(fopen(file_name.c_str(), "rb"));
}
+
+/// @brief Creates an output expression that writes values to the given file (random access)
template <typename T = u8>
internal::expression_file_writer<T> file_writer(const std::string& file_name)
{
diff --git a/include/kfr/io/tostring.hpp b/include/kfr/io/tostring.hpp
@@ -199,9 +199,14 @@ struct expression_debug_printer : output_expression
}
};
}
+
+/// @brief Returns an output expression that prints the values
inline internal::expression_printer printer() { return internal::expression_printer(); }
+
+/// @brief Returns an output expression that prints the values with their types (used for debug)
inline internal::expression_debug_printer debug_printer() { return internal::expression_debug_printer(); }
+/// @brief Converts dB value to string (uses oo for infinity symbol)
template <typename T>
std::string dB_to_string(const T& value, double minimum = -140.0)
{
@@ -210,6 +215,7 @@ std::string dB_to_string(const T& value, double minimum = -140.0)
return as_string(fmtwidth<0, 2>(value), " dB");
}
+/// @brief Converts dB value to string (uses infinity symbol in utf-8 encoding)
template <typename T>
std::string dB_to_utf8string(const T& value, double minimum = -140.0)
{
diff --git a/include/kfr/version.hpp b/include/kfr/version.hpp
@@ -30,6 +30,6 @@
namespace kfr
{
-/// Returns string representation of the KFR version (including target architecture)
+/// @brief Returns string representation of the KFR version (including target architecture)
inline static const char* library_version() { return KFR_VERSION_FULL; }
}
