1 @chapter Expression Evaluation
2 @c man begin EXPRESSION EVALUATION
4 When evaluating an arithmetic expression, FFmpeg uses an internal
5 formula evaluator, implemented through the @file{libavutil/eval.h}
8 An expression may contain unary, binary operators, constants, and
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}.
16 The following binary operators are available: @code{+}, @code{-},
17 @code{*}, @code{/}, @code{^}.
19 The following unary operators are available: @code{+}, @code{-}.
21 The following functions are available:
24 Compute absolute value of @var{x}.
27 Compute arccosine of @var{x}.
30 Compute arcsine of @var{x}.
33 Compute arctangent of @var{x}.
36 Round the value of expression @var{expr} upwards to the nearest
37 integer. For example, "ceil(1.5)" is "2.0".
40 Compute cosine of @var{x}.
43 Compute hyperbolic cosine of @var{x}.
46 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
49 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
52 Round the value of expression @var{expr} downwards to the nearest
53 integer. For example, "floor(-1.5)" is "-2.0".
56 Compute Gauss function of @var{x}, corresponding to
57 @code{exp(-x*x/2) / sqrt(2*PI)}.
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.
64 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
67 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
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.
76 Evaluate @var{x}, and if the result is non-zero return the result of
77 the evaluation of @var{y}, return 0 otherwise.
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}.
84 Evaluate @var{x}, and if the result is zero return the result of the
85 evaluation of @var{y}, return 0 otherwise.
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}.
92 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
95 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
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.
103 Compute natural logarithm of @var{x}.
106 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
109 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
112 Return the maximum between @var{x} and @var{y}.
115 Return the maximum between @var{x} and @var{y}.
118 Compute the remainder of division of @var{x} by @var{y}.
121 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
124 Compute the power of @var{x} elevated @var{y}, it is equivalent to
125 "(@var{x})^(@var{y})".
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.
133 Prints t with loglevel l
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.
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}.
143 The expression in @var{expr} must denote a continuous function or the
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.
153 Compute sine of @var{x}.
156 Compute hyperbolic sine of @var{x}.
159 Compute the square root of @var{expr}. This is equivalent to
163 Compute expression @code{1/(1 + exp(4*x))}.
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.
173 Compute tangent of @var{x}.
176 Compute hyperbolic tangent of @var{x}.
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.
183 When the series does not converge the result is undefined.
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.
190 Note, when you have the derivatives at y instead of 0,
191 @code{taylor(expr, x-y)} can be used.
194 Return the current (wallclock) time in seconds.
197 Round the value of expression @var{expr} towards zero to the nearest
198 integer. For example, "trunc(-1.5)" is "-1.0".
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.
206 The following constants are available:
209 area of the unit disc, approximately 3.14
211 exp(1) (Euler's number), approximately 2.718
213 golden ratio (1+sqrt(5))/2, approximately 1.618
216 Assuming that an expression is considered "true" if it has a non-zero
219 @code{*} works like AND
221 @code{+} works like OR
223 For example the construct:
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
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.
243 The list of available International System prefixes follows, with
244 indication of the corresponding powers of 10 and of 2.