37ca137b96fa0008dbef564a902c49aba9664355
[ffmpeg.git] / doc / eval.texi
1 @chapter Expression Evaluation
2 @c man begin EXPRESSION EVALUATION
3
4 When evaluating an arithmetic expression, FFmpeg uses an internal
5 formula evaluator, implemented through the @file{libavutil/eval.h}
6 interface.
7
8 An expression may contain unary, binary operators, constants, and
9 functions.
10
11 Two expressions @var{expr1} and @var{expr2} can be combined to form
12 another expression "@var{expr1};@var{expr2}".
13 @var{expr1} and @var{expr2} are evaluated in turn, and the new
14 expression evaluates to the value of @var{expr2}.
15
16 The following binary operators are available: @code{+}, @code{-},
17 @code{*}, @code{/}, @code{^}.
18
19 The following unary operators are available: @code{+}, @code{-}.
20
21 The following functions are available:
22 @table @option
23 @item sinh(x)
24 Compute hyperbolic sine of @var{x}.
25
26 @item cosh(x)
27 Compute hyperbolic cosine of @var{x}.
28
29 @item tanh(x)
30 Compute hyperbolic tangent of @var{x}.
31
32 @item sin(x)
33 Compute sine of @var{x}.
34
35 @item cos(x)
36 Compute cosine of @var{x}.
37
38 @item tan(x)
39 Compute tangent of @var{x}.
40
41 @item atan(x)
42 Compute arctangent of @var{x}.
43
44 @item asin(x)
45 Compute arcsine of @var{x}.
46
47 @item acos(x)
48 Compute arccosine of @var{x}.
49
50 @item exp(x)
51 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
52
53 @item log(x)
54 Compute natural logarithm of @var{x}.
55
56 @item abs(x)
57 Compute absolute value of @var{x}.
58
59 @item squish(x)
60 Compute expression @code{1/(1 + exp(4*x))}.
61
62 @item gauss(x)
63 Compute Gauss function of @var{x}, corresponding to
64 @code{exp(-x*x/2) / sqrt(2*PI)}.
65
66 @item isinf(x)
67 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
68
69 @item isnan(x)
70 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
71
72 @item mod(x, y)
73 Compute the remainder of division of @var{x} by @var{y}.
74
75 @item max(x, y)
76 Return the maximum between @var{x} and @var{y}.
77
78 @item min(x, y)
79 Return the maximum between @var{x} and @var{y}.
80
81 @item eq(x, y)
82 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
83
84 @item gte(x, y)
85 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
86
87 @item gt(x, y)
88 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
89
90 @item lte(x, y)
91 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
92
93 @item lt(x, y)
94 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
95
96 @item st(var, expr)
97 Allow to store the value of the expression @var{expr} in an internal
98 variable. @var{var} specifies the number of the variable where to
99 store the value, and it is a value ranging from 0 to 9. The function
100 returns the value stored in the internal variable.
101 Note, Variables are currently not shared between expressions.
102
103 @item ld(var)
104 Allow to load the value of the internal variable with number
105 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
106 The function returns the loaded value.
107
108 @item while(cond, expr)
109 Evaluate expression @var{expr} while the expression @var{cond} is
110 non-zero, and returns the value of the last @var{expr} evaluation, or
111 NAN if @var{cond} was always false.
112
113 @item ceil(expr)
114 Round the value of expression @var{expr} upwards to the nearest
115 integer. For example, "ceil(1.5)" is "2.0".
116
117 @item floor(expr)
118 Round the value of expression @var{expr} downwards to the nearest
119 integer. For example, "floor(-1.5)" is "-2.0".
120
121 @item trunc(expr)
122 Round the value of expression @var{expr} towards zero to the nearest
123 integer. For example, "trunc(-1.5)" is "-1.0".
124
125 @item sqrt(expr)
126 Compute the square root of @var{expr}. This is equivalent to
127 "(@var{expr})^.5".
128
129 @item not(expr)
130 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
131
132 @item pow(x, y)
133 Compute the power of @var{x} elevated @var{y}, it is equivalent to
134 "(@var{x})^(@var{y})".
135
136 @item random(x)
137 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
138 internal variable which will be used to save the seed/state.
139
140 @item hypot(x, y)
141 This function is similar to the C function with the same name; it returns
142 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
143 right triangle with sides of length @var{x} and @var{y}, or the distance of the
144 point (@var{x}, @var{y}) from the origin.
145
146 @item gcd(x, y)
147 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
148 @var{y} are 0 or either or both are less than zero then behavior is undefined.
149
150 @item if(x, y)
151 Evaluate @var{x}, and if the result is non-zero return the result of
152 the evaluation of @var{y}, return 0 otherwise.
153
154 @item if(x, y, z)
155 Evaluate @var{x}, and if the result is non-zero return the evaluation
156 result of @var{y}, otherwise the evaluation result of @var{z}.
157
158 @item ifnot(x, y)
159 Evaluate @var{x}, and if the result is zero return the result of the
160 evaluation of @var{y}, return 0 otherwise.
161
162 @item ifnot(x, y, z)
163 Evaluate @var{x}, and if the result is zero return the evaluation
164 result of @var{y}, otherwise the evaluation result of @var{z}.
165
166 @item taylor(expr, x) taylor(expr, x, id)
167 Evaluate a taylor series at x.
168 expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
169 then 0 is assumed.
170 note, when you have the derivatives at y instead of 0
171 taylor(expr, x-y) can be used
172 When the series does not converge the results are undefined.
173
174 @item time(0)
175 Return the current (wallclock) time in seconds.
176
177 @item root(expr, max)
178 Find an input value for which the function represented by @var{expr}
179 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
180
181 The expression in @var{expr} must denote a continuous function or the
182 result is undefined.
183
184 @var{ld(0)} is used to represent the function input value, which means
185 that the given expression will be evaluated multiple times with
186 various input values that the expression can access through
187 @code{ld(0)}. When the expression evaluates to 0 then the
188 corresponding input value will be returned.
189 @end table
190
191 The following constants are available:
192 @table @option
193 @item PI
194 area of the unit disc, approximately 3.14
195 @item E
196 exp(1) (Euler's number), approximately 2.718
197 @item PHI
198 golden ratio (1+sqrt(5))/2, approximately 1.618
199 @end table
200
201 Assuming that an expression is considered "true" if it has a non-zero
202 value, note that:
203
204 @code{*} works like AND
205
206 @code{+} works like OR
207
208 For example the construct:
209 @example
210 if (A AND B) then C
211 @end example
212 is equivalent to:
213 @example
214 if(A*B, C)
215 @end example
216
217 In your C code, you can extend the list of unary and binary functions,
218 and define recognized constants, so that they are available for your
219 expressions.
220
221 The evaluator also recognizes the International System unit prefixes.
222 If 'i' is appended after the prefix, binary prefixes are used, which
223 are based on powers of 1024 instead of powers of 1000.
224 The 'B' postfix multiplies the value by 8, and can be appended after a
225 unit prefix or used alone. This allows using for example 'KB', 'MiB',
226 'G' and 'B' as number postfix.
227
228 The list of available International System prefixes follows, with
229 indication of the corresponding powers of 10 and of 2.
230 @table @option
231 @item y
232 10^-24 / 2^-80
233 @item z
234 10^-21 / 2^-70
235 @item a
236 10^-18 / 2^-60
237 @item f
238 10^-15 / 2^-50
239 @item p
240 10^-12 / 2^-40
241 @item n
242 10^-9 / 2^-30
243 @item u
244 10^-6 / 2^-20
245 @item m
246 10^-3 / 2^-10
247 @item c
248 10^-2
249 @item d
250 10^-1
251 @item h
252 10^2
253 @item k
254 10^3 / 2^10
255 @item K
256 10^3 / 2^10
257 @item M
258 10^6 / 2^20
259 @item G
260 10^9 / 2^30
261 @item T
262 10^12 / 2^40
263 @item P
264 10^15 / 2^40
265 @item E
266 10^18 / 2^50
267 @item Z
268 10^21 / 2^60
269 @item Y
270 10^24 / 2^70
271 @end table
272
273 @c man end