ffmpeg.libavutil.rational source code

1 /*
2  * rational numbers
3  * Copyright (c) 2003 Michael Niedermayer <michaelni@gmx.at>
4  *
5  * This file is part of FFmpeg.
6  *
7  * FFmpeg is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * FFmpeg is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with FFmpeg; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 /**
23  * @file
24  * @ingroup lavu_math_rational
25  * Utilties for rational number calculation.
26  * @author Michael Niedermayer <michaelni@gmx.at>
27  */
28 
29 module ffmpeg.libavutil.rational;
30 
31 extern (C):
32 import ffmpeg; @nogc nothrow:
33 
34 /**
35  * @defgroup lavu_math_rational AVRational
36  * @ingroup lavu_math
37  * Rational number calculation.
38  *
39  * While rational numbers can be expressed as floating-point numbers, the
40  * conversion process is a lossy one, so are floating-point operations. On the
41  * other hand, the nature of FFmpeg demands highly accurate calculation of
42  * timestamps. This set of rational number utilities serves as a generic
43  * interface for manipulating rational numbers as pairs of numerators and
44  * denominators.
45  *
46  * Many of the functions that operate on AVRational's have the suffix `_q`, in
47  * reference to the mathematical symbol "ℚ" (Q) which denotes the set of all
48  * rational numbers.
49  *
50  * @{
51  */
52 
53 /**
54  * Rational number (pair of numerator and denominator).
55  */
56 struct AVRational
57 {
58     int num; ///< Numerator
59     int den; ///< Denominator
60 }
61 
62 /**
63  * Create an AVRational.
64  *
65  * Useful for compilers that do not support compound literals.
66  *
67  * @note The return value is not reduced.
68  * @see av_reduce()
69  */
70 AVRational av_make_q (int num, int den);
71 
72 /**
73  * Compare two rationals.
74  *
75  * @param a First rational
76  * @param b Second rational
77  *
78  * @return One of the following values:
79  *         - 0 if `a == b`
80  *         - 1 if `a > b`
81  *         - -1 if `a < b`
82  *         - `INT_MIN` if one of the values is of the form `0 / 0`
83  */
84 int av_cmp_q (AVRational a, AVRational b);
85 
86 /**
87  * Convert an AVRational to a `double`.
88  * @param a AVRational to convert
89  * @return `a` in floating-point form
90  * @see av_d2q()
91  */
92 double av_q2d (AVRational a);
93 
94 /**
95  * Reduce a fraction.
96  *
97  * This is useful for framerate calculations.
98  *
99  * @param[out] dst_num Destination numerator
100  * @param[out] dst_den Destination denominator
101  * @param[in]      num Source numerator
102  * @param[in]      den Source denominator
103  * @param[in]      max Maximum allowed values for `dst_num` & `dst_den`
104  * @return 1 if the operation is exact, 0 otherwise
105  */
106 int av_reduce (int* dst_num, int* dst_den, long num, long den, long max);
107 
108 /**
109  * Multiply two rationals.
110  * @param b First rational
111  * @param c Second rational
112  * @return b*c
113  */
114 AVRational av_mul_q (AVRational b, AVRational c);
115 
116 /**
117  * Divide one rational by another.
118  * @param b First rational
119  * @param c Second rational
120  * @return b/c
121  */
122 AVRational av_div_q (AVRational b, AVRational c);
123 
124 /**
125  * Add two rationals.
126  * @param b First rational
127  * @param c Second rational
128  * @return b+c
129  */
130 AVRational av_add_q (AVRational b, AVRational c);
131 
132 /**
133  * Subtract one rational from another.
134  * @param b First rational
135  * @param c Second rational
136  * @return b-c
137  */
138 AVRational av_sub_q (AVRational b, AVRational c);
139 
140 /**
141  * Invert a rational.
142  * @param q value
143  * @return 1 / q
144  */
145 AVRational av_inv_q (AVRational q);
146 
147 /**
148  * Convert a double precision floating point number to a rational.
149  *
150  * In case of infinity, the returned value is expressed as `{1, 0}` or
151  * `{-1, 0}` depending on the sign.
152  *
153  * @param d   `double` to convert
154  * @param max Maximum allowed numerator and denominator
155  * @return `d` in AVRational form
156  * @see av_q2d()
157  */
158 AVRational av_d2q (double d, int max);
159 
160 /**
161  * Find which of the two rationals is closer to another rational.
162  *
163  * @param q     Rational to be compared against
164  * @param q1,q2 Rationals to be tested
165  * @return One of the following values:
166  *         - 1 if `q1` is nearer to `q` than `q2`
167  *         - -1 if `q2` is nearer to `q` than `q1`
168  *         - 0 if they have the same distance
169  */
170 int av_nearer_q (AVRational q, AVRational q1, AVRational q2);
171 
172 /**
173  * Find the value in a list of rationals nearest a given reference rational.
174  *
175  * @param q      Reference rational
176  * @param q_list Array of rationals terminated by `{0, 0}`
177  * @return Index of the nearest value found in the array
178  */
179 int av_find_nearest_q_idx (AVRational q, const(AVRational)* q_list);
180 
181 /**
182  * Convert an AVRational to a IEEE 32-bit `float` expressed in fixed-point
183  * format.
184  *
185  * @param q Rational to be converted
186  * @return Equivalent floating-point value, expressed as an unsigned 32-bit
187  *         integer.
188  * @note The returned value is platform-indepedant.
189  */
190 uint av_q2intfloat (AVRational q);
191 
192 /**
193  * @}
194  */
195 
196 /* AVUTIL_RATIONAL_H */