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