aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTimothy Gu <timothygu99@gmail.com>2016-07-30 11:43:24 -0700
committerTimothy Gu <timothygu99@gmail.com>2016-08-02 21:52:40 -0700
commit952c4cf7d0dd05f75dd7220b8dcbcfa81e21434d (patch)
tree1c9b7769e5e33347b61df714ac4aa44485f9ad72
parentf29ffbc87d069cc4fdbcaee589717cf8921d53bc (diff)
downloadffmpeg-952c4cf7d0dd05f75dd7220b8dcbcfa81e21434d.tar.gz
rational: Extend Doxygen
-rw-r--r--libavutil/rational.h119
1 files changed, 80 insertions, 39 deletions
diff --git a/libavutil/rational.h b/libavutil/rational.h
index 2897469680..5c6b67b4e9 100644
--- a/libavutil/rational.h
+++ b/libavutil/rational.h
@@ -21,7 +21,8 @@
/**
* @file
- * rational numbers
+ * @ingroup lavu_math_rational
+ * Utilties for rational number calculation.
* @author Michael Niedermayer <michaelni@gmx.at>
*/
@@ -33,22 +34,39 @@
#include "attributes.h"
/**
- * @addtogroup lavu_math
+ * @defgroup lavu_math_rational AVRational
+ * @ingroup lavu_math
+ * Rational number calculation.
+ *
+ * While rational numbers can be expressed as floating-point numbers, the
+ * conversion process is a lossy one, so are floating-point operations. On the
+ * other hand, the nature of FFmpeg demands highly accurate calculation of
+ * timestamps. This set of rational number utilities serves as a generic
+ * interface for manipulating rational numbers as pairs of numerators and
+ * denominators.
+ *
+ * Many of the functions that operate on AVRational's have the suffix `_q`, in
+ * reference to the mathematical symbol "ℚ" (Q) which denotes the set of all
+ * rational numbers.
+ *
* @{
*/
/**
- * rational number numerator/denominator
+ * Rational number (pair of numerator and denominator).
*/
typedef struct AVRational{
- int num; ///< numerator
- int den; ///< denominator
+ int num; ///< Numerator
+ int den; ///< Denominator
} AVRational;
/**
- * Create a rational.
+ * Create an AVRational.
+ *
* Useful for compilers that do not support compound literals.
- * @note The return value is not reduced.
+ *
+ * @note The return value is not reduced.
+ * @see av_reduce()
*/
static inline AVRational av_make_q(int num, int den)
{
@@ -58,10 +76,15 @@ static inline AVRational av_make_q(int num, int den)
/**
* Compare two rationals.
- * @param a first rational
- * @param b second rational
- * @return 0 if a==b, 1 if a>b, -1 if a<b, and INT_MIN if one of the
- * values is of the form 0/0
+ *
+ * @param a First rational
+ * @param b Second rational
+ *
+ * @return One of the following values:
+ * - 0 if `a == b`
+ * - 1 if `a > b`
+ * - -1 if `a < b`
+ * - `INT_MIN` if one of the values is of the form `0 / 0`
*/
static inline int av_cmp_q(AVRational a, AVRational b){
const int64_t tmp= a.num * (int64_t)b.den - b.num * (int64_t)a.den;
@@ -73,9 +96,10 @@ static inline int av_cmp_q(AVRational a, AVRational b){
}
/**
- * Convert rational to double.
- * @param a rational to convert
- * @return (double) a
+ * Convert an AVRational to a `double`.
+ * @param a AVRational to convert
+ * @return `a` in floating-point form
+ * @see av_d2q()
*/
static inline double av_q2d(AVRational a){
return a.num / (double) a.den;
@@ -83,44 +107,46 @@ static inline double av_q2d(AVRational a){
/**
* Reduce a fraction.
+ *
* This is useful for framerate calculations.
- * @param dst_num destination numerator
- * @param dst_den destination denominator
- * @param num source numerator
- * @param den source denominator
- * @param max the maximum allowed for dst_num & dst_den
- * @return 1 if exact, 0 otherwise
+ *
+ * @param[out] dst_num Destination numerator
+ * @param[out] dst_den Destination denominator
+ * @param[in] num Source numerator
+ * @param[in] den Source denominator
+ * @param[in] max Maximum allowed values for `dst_num` & `dst_den`
+ * @return 1 if the operation is exact, 0 otherwise
*/
int av_reduce(int *dst_num, int *dst_den, int64_t num, int64_t den, int64_t max);
/**
* Multiply two rationals.
- * @param b first rational
- * @param c second rational
+ * @param b First rational
+ * @param c Second rational
* @return b*c
*/
AVRational av_mul_q(AVRational b, AVRational c) av_const;
/**
* Divide one rational by another.
- * @param b first rational
- * @param c second rational
+ * @param b First rational
+ * @param c Second rational
* @return b/c
*/
AVRational av_div_q(AVRational b, AVRational c) av_const;
/**
* Add two rationals.
- * @param b first rational
- * @param c second rational
+ * @param b First rational
+ * @param c Second rational
* @return b+c
*/
AVRational av_add_q(AVRational b, AVRational c) av_const;
/**
* Subtract one rational from another.
- * @param b first rational
- * @param c second rational
+ * @param b First rational
+ * @param c Second rational
* @return b-c
*/
AVRational av_sub_q(AVRational b, AVRational c) av_const;
@@ -138,31 +164,46 @@ static av_always_inline AVRational av_inv_q(AVRational q)
/**
* Convert a double precision floating point number to a rational.
- * inf is expressed as {1,0} or {-1,0} depending on the sign.
*
- * @param d double to convert
- * @param max the maximum allowed numerator and denominator
- * @return (AVRational) d
+ * In case of infinity, the returned value is expressed as `{1, 0}` or
+ * `{-1, 0}` depending on the sign.
+ *
+ * @param d `double` to convert
+ * @param max Maximum allowed numerator and denominator
+ * @return `d` in AVRational form
+ * @see av_q2d()
*/
AVRational av_d2q(double d, int max) av_const;
/**
- * @return 1 if q1 is nearer to q than q2, -1 if q2 is nearer
- * than q1, 0 if they have the same distance.
+ * Find which of the two rationals is closer to another rational.
+ *
+ * @param q Rational to be compared against
+ * @param q1,q2 Rationals to be tested
+ * @return One of the following values:
+ * - 1 if `q1` is nearer to `q` than `q2`
+ * - -1 if `q2` is nearer to `q` than `q1`
+ * - 0 if they have the same distance
*/
int av_nearer_q(AVRational q, AVRational q1, AVRational q2);
/**
- * Find the nearest value in q_list to q.
- * @param q_list an array of rationals terminated by {0, 0}
- * @return the index of the nearest value found in the array
+ * Find the value in a list of rationals nearest a given reference rational.
+ *
+ * @param q Reference rational
+ * @param q_list Array of rationals terminated by `{0, 0}`
+ * @return Index of the nearest value found in the array
*/
int av_find_nearest_q_idx(AVRational q, const AVRational* q_list);
/**
- * Converts a AVRational to a IEEE 32bit float.
+ * Convert an AVRational to a IEEE 32-bit `float` expressed in fixed-point
+ * format.
*
- * The float is returned in a uint32_t and its value is platform indepenant.
+ * @param q Rational to be converted
+ * @return Equivalent floating-point value, expressed as an unsigned 32-bit
+ * integer.
+ * @note The returned value is platform-indepedant.
*/
uint32_t av_q2intfloat(AVRational q);