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