diff options
Diffstat (limited to 'libavutil/rational.h')
| -rw-r--r-- | libavutil/rational.h | 139 |
1 files changed, 99 insertions, 40 deletions
diff --git a/libavutil/rational.h b/libavutil/rational.h index 5d7dab7fd0..5c6b67b4e9 100644 --- a/libavutil/rational.h +++ b/libavutil/rational.h @@ -2,26 +2,27 @@ * rational numbers * Copyright (c) 2003 Michael Niedermayer <michaelni@gmx.at> * - * This file is part of Libav. + * This file is part of FFmpeg. * - * Libav is free software; you can redistribute it and/or + * FFmpeg is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * - * Libav is distributed in the hope that it will be useful, + * FFmpeg is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with Libav; if not, write to the Free Software + * License along with FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ /** * @file - * rational numbers + * @ingroup lavu_math_rational + * Utilties for rational number calculation. * @author Michael Niedermayer <michaelni@gmx.at> */ @@ -33,38 +34,72 @@ #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 an AVRational. + * + * Useful for compilers that do not support compound literals. + * + * @note The return value is not reduced. + * @see av_reduce() + */ +static inline AVRational av_make_q(int num, int den) +{ + AVRational r = { num, den }; + return r; +} + +/** * 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; - if(tmp) return ((tmp ^ a.den ^ b.den)>>63)|1; + if(tmp) return (int)((tmp ^ a.den ^ b.den)>>63)|1; else if(b.den && a.den) return 0; else if(a.num && b.num) return (a.num>>31) - (b.num>>31); else return INT_MIN; } /** - * 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; @@ -72,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; @@ -127,28 +164,50 @@ 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); /** + * Convert an AVRational to a IEEE 32-bit `float` expressed in fixed-point + * format. + * + * @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); + +/** * @} */ |