mirror of https://git.ffmpeg.org/ffmpeg.git
rational: Extend Doxygen
This commit is contained in:
Timothy Gu
parent
f29ffbc87d
commit
952c4cf7d0
|
|
@ -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);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue