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  */
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  *
138  * @see av_rescale(), av_rescale_q(), av_rescale_q_rnd()
139  */
140 int64_t av_rescale_rnd(int64_t a, int64_t b, int64_t c, enum AVRounding rnd) av_const;
141 
142 /**
143  * Rescale a 64-bit integer by 2 rational numbers.
144  *
145  * The operation is mathematically equivalent to `a * bq / cq`.
146  *
147  * This function is equivalent to av_rescale_q_rnd() with #AV_ROUND_NEAR_INF.
148  *
149  * @see av_rescale(), av_rescale_rnd(), av_rescale_q_rnd()
150  */
151 int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq) av_const;
152 
153 /**
154  * Rescale a 64-bit integer by 2 rational numbers with specified rounding.
155  *
156  * The operation is mathematically equivalent to `a * bq / cq`.
157  *
158  * @see av_rescale(), av_rescale_rnd(), av_rescale_q()
159  */
160 int64_t av_rescale_q_rnd(int64_t a, AVRational bq, AVRational cq,
161  enum AVRounding rnd) av_const;
162 
163 /**
164  * Compare two timestamps each in its own time base.
165  *
166  * @return One of the following values:
167  * - -1 if `ts_a` is before `ts_b`
168  * - 1 if `ts_a` is after `ts_b`
169  * - 0 if they represent the same position
170  *
171  * @warning
172  * The result of the function is undefined if one of the timestamps is outside
173  * the `int64_t` range when represented in the other's timebase.
174  */
175 int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b);
176 
177 /**
178  * Compare the remainders of two integer operands divided by a common divisor.
179  *
180  * In other words, compare the least significant `log2(mod)` bits of integers
181  * `a` and `b`.
182  *
183  * @code{.c}
184  * av_compare_mod(0x11, 0x02, 0x10) < 0 // since 0x11 % 0x10 (0x1) < 0x02 % 0x10 (0x2)
185  * av_compare_mod(0x11, 0x02, 0x20) > 0 // since 0x11 % 0x20 (0x11) > 0x02 % 0x20 (0x02)
186  * @endcode
187  *
188  * @param a,b Operands
189  * @param mod Divisor; must be a power of 2
190  * @return
191  * - a negative value if `a % mod < b % mod`
192  * - a positive value if `a % mod > b % mod`
193  * - zero if `a % mod == b % mod`
194  */
195 int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod);
196 
197 /**
198  * Rescale a timestamp while preserving known durations.
199  *
200  * This function is designed to be called per audio packet to scale the input
201  * timestamp to a different time base. Compared to a simple av_rescale_q()
202  * call, this function is robust against possible inconsistent frame durations.
203  *
204  * The `last` parameter is a state variable that must be preserved for all
205  * subsequent calls for the same stream. For the first call, `*last` should be
206  * initialized to #AV_NOPTS_VALUE.
207  *
208  * @param[in] in_tb Input time base
209  * @param[in] in_ts Input timestamp
210  * @param[in] fs_tb Duration time base; typically this is finer-grained
211  * (greater) than `in_tb` and `out_tb`
212  * @param[in] duration Duration till the next call to this function (i.e.
213  * duration of the current packet/frame)
214  * @param[in,out] last Pointer to a timestamp expressed in terms of
215  * `fs_tb`, acting as a state variable
216  * @param[in] out_tb Output timebase
217  * @return Timestamp expressed in terms of `out_tb`
218  *
219  * @note In the context of this function, "duration" is in term of samples, not
220  * seconds.
221  */
222 int64_t av_rescale_delta(AVRational in_tb, int64_t in_ts, AVRational fs_tb, int duration, int64_t *last, AVRational out_tb);
223 
224 /**
225  * Add a value to a timestamp.
226  *
227  * This function guarantees that when the same value is repeatly added that
228  * no accumulation of rounding errors occurs.
229  *
230  * @param[in] ts Input timestamp
231  * @param[in] ts_tb Input timestamp time base
232  * @param[in] inc Value to be added
233  * @param[in] inc_tb Time base of `inc`
234  */
235 int64_t av_add_stable(AVRational ts_tb, int64_t ts, AVRational inc_tb, int64_t inc);
236 
237 
238 /**
239  * @}
240  */
241 
242 #endif /* AVUTIL_MATHEMATICS_H */
#define av_const
Definition: attributes.h:76
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:36
AVRounding
Rounding methods.
Definition: mathematics.h:79
Macro definitions for various function/variable attributes.
Round toward +infinity.
Definition: mathematics.h:83
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
int64_t duration
Definition: movenc.c:63
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
Round away from zero.
Definition: mathematics.h:81
Round to nearest and halfway cases away from zero.
Definition: mathematics.h:84
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
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
#define b
Definition: input.c:41
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
Round toward zero.
Definition: mathematics.h:80
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
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
Rational number (pair of numerator and denominator).
Definition: rational.h:58
Round toward -infinity.
Definition: mathematics.h:82
Utilties for rational number calculation.
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
#define rnd()
Definition: checkasm.h:104
Flag telling rescaling functions to pass INT64_MIN/MAX through unchanged, avoiding special cases for ...
Definition: mathematics.h:108
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
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