diff options
Diffstat (limited to 'media/ffvpx/libavutil/rational.h')
| -rw-r--r-- | media/ffvpx/libavutil/rational.h | 119 |
1 files changed, 80 insertions, 39 deletions
diff --git a/media/ffvpx/libavutil/rational.h b/media/ffvpx/libavutil/rational.h index 289746968..5c6b67b4e 100644 --- a/media/ffvpx/libavutil/rational.h +++ b/media/ffvpx/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); |