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_LN2
40 #define M_LN2 0.69314718055994530942 /* log_e 2 */
41 #endif
42 #ifndef M_LN10
43 #define M_LN10 2.30258509299404568402 /* log_e 10 */
44 #endif
45 #ifndef M_LOG2_10
46 #define M_LOG2_10 3.32192809488736234787 /* log_2 10 */
47 #endif
48 #ifndef M_PHI
49 #define M_PHI 1.61803398874989484820 /* phi / golden ratio */
50 #endif
51 #ifndef M_PI
52 #define M_PI 3.14159265358979323846 /* pi */
53 #endif
54 #ifndef M_PI_2
55 #define M_PI_2 1.57079632679489661923 /* pi/2 */
56 #endif
57 #ifndef M_SQRT1_2
58 #define M_SQRT1_2 0.70710678118654752440 /* 1/sqrt(2) */
59 #endif
60 #ifndef M_SQRT2
61 #define M_SQRT2 1.41421356237309504880 /* sqrt(2) */
62 #endif
63 #ifndef NAN
64 #define NAN av_int2float(0x7fc00000)
65 #endif
66 #ifndef INFINITY
67 #define INFINITY av_int2float(0x7f800000)
68 #endif
69 
70 /**
71  * @addtogroup lavu_math
72  *
73  * @{
74  */
75 
76 /**
77  * Rounding methods.
78  */
79 enum AVRounding {
80  AV_ROUND_ZERO = 0, ///< Round toward zero.
81  AV_ROUND_INF = 1, ///< Round away from zero.
82  AV_ROUND_DOWN = 2, ///< Round toward -infinity.
83  AV_ROUND_UP = 3, ///< Round toward +infinity.
84  AV_ROUND_NEAR_INF = 5, ///< Round to nearest and halfway cases away from zero.
85  /**
86  * Flag telling rescaling functions to pass `INT64_MIN`/`MAX` through
87  * unchanged, avoiding special cases for #AV_NOPTS_VALUE.
88  *
89  * Unlike other values of the enumeration AVRounding, this value is a
90  * bitmask that must be used in conjunction with another value of the
91  * enumeration through a bitwise OR, in order to set behavior for normal
92  * cases.
93  *
94  * @code{.c}
95  * av_rescale_rnd(3, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX);
96  * // Rescaling 3:
97  * // Calculating 3 * 1 / 2
98  * // 3 / 2 is rounded up to 2
99  * // => 2
100  *
101  * av_rescale_rnd(AV_NOPTS_VALUE, 1, 2, AV_ROUND_UP | AV_ROUND_PASS_MINMAX);
102  * // Rescaling AV_NOPTS_VALUE:
103  * // AV_NOPTS_VALUE == INT64_MIN
104  * // AV_NOPTS_VALUE is passed through
105  * // => AV_NOPTS_VALUE
106  * @endcode
107  */
108  AV_ROUND_PASS_MINMAX = 8192,
109 };
110 
111 /**
112  * Compute the greatest common divisor of two integer operands.
113  *
114  * @param a,b Operands
115  * @return GCD of a and b up to sign; if a >= 0 and b >= 0, return value is >= 0;
116  * if a == 0 and b == 0, returns 0.
117  */
118 int64_t av_const av_gcd(int64_t a, int64_t b);
119 
120 /**
121  * Rescale a 64-bit integer with rounding to nearest.
122  *
123  * The operation is mathematically equivalent to `a * b / c`, but writing that
124  * directly can overflow.
125  *
126  * This function is equivalent to av_rescale_rnd() with #AV_ROUND_NEAR_INF.
127  *
128  * @see av_rescale_rnd(), av_rescale_q(), av_rescale_q_rnd()
129  */
130 int64_t av_rescale(int64_t a, int64_t b, int64_t c) av_const;
131 
132 /**
133  * Rescale a 64-bit integer with specified rounding.
134  *
135  * The operation is mathematically equivalent to `a * b / c`, but writing that
136  * directly can overflow, and does not support different rounding methods.
137  * If the result is not representable then INT64_MIN is returned.
138  *
139  * @see av_rescale(), av_rescale_q(), av_rescale_q_rnd()
140  */
141 int64_t av_rescale_rnd(int64_t a, int64_t b, int64_t c, enum AVRounding rnd) av_const;
142 
143 /**
144  * Rescale a 64-bit integer by 2 rational numbers.
145  *
146  * The operation is mathematically equivalent to `a * bq / cq`.
147  *
148  * This function is equivalent to av_rescale_q_rnd() with #AV_ROUND_NEAR_INF.
149  *
150  * @see av_rescale(), av_rescale_rnd(), av_rescale_q_rnd()
151  */
152 int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq) av_const;
153 
154 /**
155  * Rescale a 64-bit integer by 2 rational numbers with specified rounding.
156  *
157  * The operation is mathematically equivalent to `a * bq / cq`.
158  *
159  * @see av_rescale(), av_rescale_rnd(), av_rescale_q()
160  */
161 int64_t av_rescale_q_rnd(int64_t a, AVRational bq, AVRational cq,
162  enum AVRounding rnd) av_const;
163 
164 /**
165  * Compare two timestamps each in its own time base.
166  *
167  * @return One of the following values:
168  * - -1 if `ts_a` is before `ts_b`
169  * - 1 if `ts_a` is after `ts_b`
170  * - 0 if they represent the same position
171  *
172  * @warning
173  * The result of the function is undefined if one of the timestamps is outside
174  * the `int64_t` range when represented in the other's timebase.
175  */
176 int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b);
177 
178 /**
179  * Compare the remainders of two integer operands divided by a common divisor.
180  *
181  * In other words, compare the least significant `log2(mod)` bits of integers
182  * `a` and `b`.
183  *
184  * @code{.c}
185  * av_compare_mod(0x11, 0x02, 0x10) < 0 // since 0x11 % 0x10 (0x1) < 0x02 % 0x10 (0x2)
186  * av_compare_mod(0x11, 0x02, 0x20) > 0 // since 0x11 % 0x20 (0x11) > 0x02 % 0x20 (0x02)
187  * @endcode
188  *
189  * @param a,b Operands
190  * @param mod Divisor; must be a power of 2
191  * @return
192  * - a negative value if `a % mod < b % mod`
193  * - a positive value if `a % mod > b % mod`
194  * - zero if `a % mod == b % mod`
195  */
196 int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod);
197 
198 /**
199  * Rescale a timestamp while preserving known durations.
200  *
201  * This function is designed to be called per audio packet to scale the input
202  * timestamp to a different time base. Compared to a simple av_rescale_q()
203  * call, this function is robust against possible inconsistent frame durations.
204  *
205  * The `last` parameter is a state variable that must be preserved for all
206  * subsequent calls for the same stream. For the first call, `*last` should be
207  * initialized to #AV_NOPTS_VALUE.
208  *
209  * @param[in] in_tb Input time base
210  * @param[in] in_ts Input timestamp
211  * @param[in] fs_tb Duration time base; typically this is finer-grained
212  * (greater) than `in_tb` and `out_tb`
213  * @param[in] duration Duration till the next call to this function (i.e.
214  * duration of the current packet/frame)
215  * @param[in,out] last Pointer to a timestamp expressed in terms of
216  * `fs_tb`, acting as a state variable
217  * @param[in] out_tb Output timebase
218  * @return Timestamp expressed in terms of `out_tb`
219  *
220  * @note In the context of this function, "duration" is in term of samples, not
221  * seconds.
222  */
223 int64_t av_rescale_delta(AVRational in_tb, int64_t in_ts, AVRational fs_tb, int duration, int64_t *last, AVRational out_tb);
224 
225 /**
226  * Add a value to a timestamp.
227  *
228  * This function guarantees that when the same value is repeatly added that
229  * no accumulation of rounding errors occurs.
230  *
231  * @param[in] ts Input timestamp
232  * @param[in] ts_tb Input timestamp time base
233  * @param[in] inc Value to be added
234  * @param[in] inc_tb Time base of `inc`
235  */
236 int64_t av_add_stable(AVRational ts_tb, int64_t ts, AVRational inc_tb, int64_t inc);
237 
238 
239 /**
240  * @}
241  */
242 
243 #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
rational.h
av_const
#define av_const
Definition: attributes.h:78
b
#define b
Definition: input.c:41
AVRounding
AVRounding
Rounding methods.
Definition: mathematics.h:79
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:83
rnd
#define rnd()
Definition: checkasm.h:104
duration
int64_t duration
Definition: movenc.c:63
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:81
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:84
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:80
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:82
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
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:108
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 Wed Aug 24 2022 21:27:28 for FFmpeg by   doxygen 1.8.17