FFmpeg
mathematics.h
Go to the documentation of this file.
1 /*
2  * copyright (c) 2005-2012 Michael Niedermayer <michaelni@gmx.at>
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 /**
22  * @file
23  * @addtogroup lavu_math
24  * Mathematical utilities for working with timestamp and time base.
25  */
26 
27 #ifndef AVUTIL_MATHEMATICS_H
28 #define AVUTIL_MATHEMATICS_H
29 
30 #include <stdint.h>
31 #include <math.h>
32 #include "attributes.h"
33 #include "rational.h"
34 #include "intfloat.h"
35 
36 #ifndef M_E
37 #define M_E 2.7182818284590452354 /* e */
38 #endif
39 #ifndef M_Ef
40 #define M_Ef 2.7182818284590452354f /* e */
41 #endif
42 #ifndef M_LN2
43 #define M_LN2 0.69314718055994530942 /* log_e 2 */
44 #endif
45 #ifndef M_LN2f
46 #define M_LN2f 0.69314718055994530942f /* log_e 2 */
47 #endif
48 #ifndef M_LN10
49 #define M_LN10 2.30258509299404568402 /* log_e 10 */
50 #endif
51 #ifndef M_LN10f
52 #define M_LN10f 2.30258509299404568402f /* log_e 10 */
53 #endif
54 #ifndef M_LOG2_10
55 #define M_LOG2_10 3.32192809488736234787 /* log_2 10 */
56 #endif
57 #ifndef M_LOG2_10f
58 #define M_LOG2_10f 3.32192809488736234787f /* log_2 10 */
59 #endif
60 #ifndef M_PHI
61 #define M_PHI 1.61803398874989484820 /* phi / golden ratio */
62 #endif
63 #ifndef M_PHIf
64 #define M_PHIf 1.61803398874989484820f /* phi / golden ratio */
65 #endif
66 #ifndef M_PI
67 #define M_PI 3.14159265358979323846 /* pi */
68 #endif
69 #ifndef M_PIf
70 #define M_PIf 3.14159265358979323846f /* pi */
71 #endif
72 #ifndef M_PI_2
73 #define M_PI_2 1.57079632679489661923 /* pi/2 */
74 #endif
75 #ifndef M_PI_2f
76 #define M_PI_2f 1.57079632679489661923f /* pi/2 */
77 #endif
78 #ifndef M_PI_4
79 #define M_PI_4 0.78539816339744830962 /* pi/4 */
80 #endif
81 #ifndef M_PI_4f
82 #define M_PI_4f 0.78539816339744830962f /* pi/4 */
83 #endif
84 #ifndef M_1_PI
85 #define M_1_PI 0.31830988618379067154 /* 1/pi */
86 #endif
87 #ifndef M_1_PIf
88 #define M_1_PIf 0.31830988618379067154f /* 1/pi */
89 #endif
90 #ifndef M_2_PI
91 #define M_2_PI 0.63661977236758134308 /* 2/pi */
92 #endif
93 #ifndef M_2_PIf
94 #define M_2_PIf 0.63661977236758134308f /* 2/pi */
95 #endif
96 #ifndef M_2_SQRTPI
97 #define M_2_SQRTPI 1.12837916709551257390 /* 2/sqrt(pi) */
98 #endif
99 #ifndef M_2_SQRTPIf
100 #define M_2_SQRTPIf 1.12837916709551257390f /* 2/sqrt(pi) */
101 #endif
102 #ifndef M_SQRT1_2
103 #define M_SQRT1_2 0.70710678118654752440 /* 1/sqrt(2) */
104 #endif
105 #ifndef M_SQRT1_2f
106 #define M_SQRT1_2f 0.70710678118654752440f /* 1/sqrt(2) */
107 #endif
108 #ifndef M_SQRT2
109 #define M_SQRT2 1.41421356237309504880 /* sqrt(2) */
110 #endif
111 #ifndef M_SQRT2f
112 #define M_SQRT2f 1.41421356237309504880f /* sqrt(2) */
113 #endif
114 #ifndef NAN
115 #define NAN av_int2float(0x7fc00000)
116 #endif
117 #ifndef INFINITY
118 #define INFINITY av_int2float(0x7f800000)
119 #endif
120 
121 /**
122  * @addtogroup lavu_math
123  *
124  * @{
125  */
126 
127 /**
128  * Rounding methods.
129  */
130 enum AVRounding {
131  AV_ROUND_ZERO = 0, ///< Round toward zero.
132  AV_ROUND_INF = 1, ///< Round away from zero.
133  AV_ROUND_DOWN = 2, ///< Round toward -infinity.
134  AV_ROUND_UP = 3, ///< Round toward +infinity.
135  AV_ROUND_NEAR_INF = 5, ///< Round to nearest and halfway cases away from zero.
136  /**
137  * Flag telling rescaling functions to pass `INT64_MIN`/`MAX` through
138  * unchanged, avoiding special cases for #AV_NOPTS_VALUE.
139  *
140  * Unlike other values of the enumeration AVRounding, this value is a
141  * bitmask that must be used in conjunction with another value of the
142  * enumeration through a bitwise OR, in order to set behavior for normal
143  * cases.
144  *
145  * @code{.c}
146  * av_rescale_rnd(3, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX);
147  * // Rescaling 3:
148  * // Calculating 3 * 1 / 2
149  * // 3 / 2 is rounded up to 2
150  * // => 2
151  *
152  * av_rescale_rnd(AV_NOPTS_VALUE, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX);
153  * // Rescaling AV_NOPTS_VALUE:
154  * // AV_NOPTS_VALUE == INT64_MIN
155  * // AV_NOPTS_VALUE is passed through
156  * // => AV_NOPTS_VALUE
157  * @endcode
158  */
159  AV_ROUND_PASS_MINMAX = 8192,
160 };
161 
162 /**
163  * Compute the greatest common divisor of two integer operands.
164  *
165  * @param a Operand
166  * @param b Operand
167  * @return GCD of a and b up to sign; if a >= 0 and b >= 0, return value is >= 0;
168  * if a == 0 and b == 0, returns 0.
169  */
170 int64_t av_const av_gcd(int64_t a, int64_t b);
171 
172 /**
173  * Rescale a 64-bit integer with rounding to nearest.
174  *
175  * The operation is mathematically equivalent to `a * b / c`, but writing that
176  * directly can overflow.
177  *
178  * This function is equivalent to av_rescale_rnd() with #AV_ROUND_NEAR_INF.
179  *
180  * @see av_rescale_rnd(), av_rescale_q(), av_rescale_q_rnd()
181  */
182 int64_t av_rescale(int64_t a, int64_t b, int64_t c) av_const;
183 
184 /**
185  * Rescale a 64-bit integer with specified rounding.
186  *
187  * The operation is mathematically equivalent to `a * b / c`, but writing that
188  * directly can overflow, and does not support different rounding methods.
189  * If the result is not representable then INT64_MIN is returned.
190  *
191  * @see av_rescale(), av_rescale_q(), av_rescale_q_rnd()
192  */
193 int64_t av_rescale_rnd(int64_t a, int64_t b, int64_t c, enum AVRounding rnd) av_const;
194 
195 /**
196  * Rescale a 64-bit integer by 2 rational numbers.
197  *
198  * The operation is mathematically equivalent to `a * bq / cq`.
199  *
200  * This function is equivalent to av_rescale_q_rnd() with #AV_ROUND_NEAR_INF.
201  *
202  * @see av_rescale(), av_rescale_rnd(), av_rescale_q_rnd()
203  */
204 int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq) av_const;
205 
206 /**
207  * Rescale a 64-bit integer by 2 rational numbers with specified rounding.
208  *
209  * The operation is mathematically equivalent to `a * bq / cq`.
210  *
211  * @see av_rescale(), av_rescale_rnd(), av_rescale_q()
212  */
213 int64_t av_rescale_q_rnd(int64_t a, AVRational bq, AVRational cq,
214  enum AVRounding rnd) av_const;
215 
216 /**
217  * Compare two timestamps each in its own time base.
218  *
219  * @return One of the following values:
220  * - -1 if `ts_a` is before `ts_b`
221  * - 1 if `ts_a` is after `ts_b`
222  * - 0 if they represent the same position
223  *
224  * @warning
225  * The result of the function is undefined if one of the timestamps is outside
226  * the `int64_t` range when represented in the other's timebase.
227  */
228 int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b);
229 
230 /**
231  * Compare the remainders of two integer operands divided by a common divisor.
232  *
233  * In other words, compare the least significant `log2(mod)` bits of integers
234  * `a` and `b`.
235  *
236  * @code{.c}
237  * av_compare_mod(0x11, 0x02, 0x10) < 0 // since 0x11 % 0x10 (0x1) < 0x02 % 0x10 (0x2)
238  * av_compare_mod(0x11, 0x02, 0x20) > 0 // since 0x11 % 0x20 (0x11) > 0x02 % 0x20 (0x02)
239  * @endcode
240  *
241  * @param a Operand
242  * @param b Operand
243  * @param mod Divisor; must be a power of 2
244  * @return
245  * - a negative value if `a % mod < b % mod`
246  * - a positive value if `a % mod > b % mod`
247  * - zero if `a % mod == b % mod`
248  */
249 int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod);
250 
251 /**
252  * Rescale a timestamp while preserving known durations.
253  *
254  * This function is designed to be called per audio packet to scale the input
255  * timestamp to a different time base. Compared to a simple av_rescale_q()
256  * call, this function is robust against possible inconsistent frame durations.
257  *
258  * The `last` parameter is a state variable that must be preserved for all
259  * subsequent calls for the same stream. For the first call, `*last` should be
260  * initialized to #AV_NOPTS_VALUE.
261  *
262  * @param[in] in_tb Input time base
263  * @param[in] in_ts Input timestamp
264  * @param[in] fs_tb Duration time base; typically this is finer-grained
265  * (greater) than `in_tb` and `out_tb`
266  * @param[in] duration Duration till the next call to this function (i.e.
267  * duration of the current packet/frame)
268  * @param[in,out] last Pointer to a timestamp expressed in terms of
269  * `fs_tb`, acting as a state variable
270  * @param[in] out_tb Output timebase
271  * @return Timestamp expressed in terms of `out_tb`
272  *
273  * @note In the context of this function, "duration" is in term of samples, not
274  * seconds.
275  */
276 int64_t av_rescale_delta(AVRational in_tb, int64_t in_ts, AVRational fs_tb, int duration, int64_t *last, AVRational out_tb);
277 
278 /**
279  * Add a value to a timestamp.
280  *
281  * This function guarantees that when the same value is repeatly added that
282  * no accumulation of rounding errors occurs.
283  *
284  * @param[in] ts Input timestamp
285  * @param[in] ts_tb Input timestamp time base
286  * @param[in] inc Value to be added
287  * @param[in] inc_tb Time base of `inc`
288  */
289 int64_t av_add_stable(AVRational ts_tb, int64_t ts, AVRational inc_tb, int64_t inc);
290 
291 /**
292  * 0th order modified bessel function of the first kind.
293  */
294 double av_bessel_i0(double x);
295 
296 /**
297  * @}
298  */
299 
300 #endif /* AVUTIL_MATHEMATICS_H */
av_compare_ts
int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b)
Compare two timestamps each in its own time base.
Definition: mathematics.c:147
av_add_stable
int64_t av_add_stable(AVRational ts_tb, int64_t ts, AVRational inc_tb, int64_t inc)
Add a value to a timestamp.
Definition: mathematics.c:191
av_bessel_i0
double av_bessel_i0(double x)
0th order modified bessel function of the first kind.
Definition: mathematics.c:257
rational.h
av_const
#define av_const
Definition: attributes.h:84
b
#define b
Definition: input.c:41
AVRounding
AVRounding
Rounding methods.
Definition: mathematics.h:130
intfloat.h
av_gcd
int64_t av_const av_gcd(int64_t a, int64_t b)
Compute the greatest common divisor of two integer operands.
Definition: mathematics.c:37
AV_ROUND_UP
@ AV_ROUND_UP
Round toward +infinity.
Definition: mathematics.h:134
rnd
#define rnd()
Definition: checkasm.h:122
duration
int64_t duration
Definition: movenc.c:64
av_rescale_q
int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq) av_const
Rescale a 64-bit integer by 2 rational numbers.
Definition: mathematics.c:142
av_rescale_delta
int64_t av_rescale_delta(AVRational in_tb, int64_t in_ts, AVRational fs_tb, int duration, int64_t *last, AVRational out_tb)
Rescale a timestamp while preserving known durations.
Definition: mathematics.c:168
AV_ROUND_INF
@ AV_ROUND_INF
Round away from zero.
Definition: mathematics.h:132
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AV_ROUND_NEAR_INF
@ AV_ROUND_NEAR_INF
Round to nearest and halfway cases away from zero.
Definition: mathematics.h:135
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
av_rescale_rnd
int64_t av_rescale_rnd(int64_t a, int64_t b, int64_t c, enum AVRounding rnd) av_const
Rescale a 64-bit integer with specified rounding.
Definition: mathematics.c:58
AV_ROUND_ZERO
@ AV_ROUND_ZERO
Round toward zero.
Definition: mathematics.h:131
a
The reader does not expect b to be semantically here and if the code is changed by maybe adding a a division or other the signedness will almost certainly be mistaken To avoid this confusion a new type was SUINT is the C unsigned type but it holds a signed int to use the same example SUINT a
Definition: undefined.txt:41
attributes.h
AV_ROUND_DOWN
@ AV_ROUND_DOWN
Round toward -infinity.
Definition: mathematics.h:133
av_rescale
int64_t av_rescale(int64_t a, int64_t b, int64_t c) av_const
Rescale a 64-bit integer with rounding to nearest.
Definition: mathematics.c:129
mod
static int mod(int a, int b)
Modulo operation with only positive remainders.
Definition: vf_v360.c:750
av_compare_mod
int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod)
Compare the remainders of two integer operands divided by a common divisor.
Definition: mathematics.c:160
AV_ROUND_PASS_MINMAX
@ AV_ROUND_PASS_MINMAX
Flag telling rescaling functions to pass INT64_MIN/MAX through unchanged, avoiding special cases for ...
Definition: mathematics.h:159
av_rescale_q_rnd
int64_t av_rescale_q_rnd(int64_t a, AVRational bq, AVRational cq, enum AVRounding rnd) av_const
Rescale a 64-bit integer by 2 rational numbers with specified rounding.
Definition: mathematics.c:134
Generated on Thu Sep 21 2023 19:22:04 for FFmpeg by   doxygen 1.8.17