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})".
128 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
129 internal variable which will be used to save the seed/state.
131 @item root(expr, max)
132 Find an input value for which the function represented by @var{expr}
133 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
135 The expression in @var{expr} must denote a continuous function or the
138 @var{ld(0)} is used to represent the function input value, which means
139 that the given expression will be evaluated multiple times with
140 various input values that the expression can access through
141 @code{ld(0)}. When the expression evaluates to 0 then the
142 corresponding input value will be returned.
145 Compute sine of @var{x}.
148 Compute hyperbolic sine of @var{x}.
151 Compute the square root of @var{expr}. This is equivalent to
155 Compute expression @code{1/(1 + exp(4*x))}.
158 Allow to store the value of the expression @var{expr} in an internal
159 variable. @var{var} specifies the number of the variable where to
160 store the value, and it is a value ranging from 0 to 9. The function
161 returns the value stored in the internal variable.
162 Note, Variables are currently not shared between expressions.
165 Compute tangent of @var{x}.
168 Compute hyperbolic tangent of @var{x}.
170 @item taylor(expr, x)
171 @item taylor(expr, x, id)
172 Evaluate a Taylor series at @var{x}, given an expression representing
173 the @code{ld(id)}-th derivative of a function at 0.
175 When the series does not converge the result is undefined.
177 @var{ld(id)} is used to represent the derivative order in @var{expr},
178 which means that the given expression will be evaluated multiple times
179 with various input values that the expression can access through
180 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
182 Note, when you have the derivatives at y instead of 0,
183 @code{taylor(expr, x-y)} can be used.
186 Return the current (wallclock) time in seconds.
189 Round the value of expression @var{expr} towards zero to the nearest
190 integer. For example, "trunc(-1.5)" is "-1.0".
192 @item while(cond, expr)
193 Evaluate expression @var{expr} while the expression @var{cond} is
194 non-zero, and returns the value of the last @var{expr} evaluation, or
195 NAN if @var{cond} was always false.
198 The following constants are available:
201 area of the unit disc, approximately 3.14
203 exp(1) (Euler's number), approximately 2.718
205 golden ratio (1+sqrt(5))/2, approximately 1.618
208 Assuming that an expression is considered "true" if it has a non-zero
211 @code{*} works like AND
213 @code{+} works like OR
215 For example the construct:
224 In your C code, you can extend the list of unary and binary functions,
225 and define recognized constants, so that they are available for your
228 The evaluator also recognizes the International System unit prefixes.
229 If 'i' is appended after the prefix, binary prefixes are used, which
230 are based on powers of 1024 instead of powers of 1000.
231 The 'B' postfix multiplies the value by 8, and can be appended after a
232 unit prefix or used alone. This allows using for example 'KB', 'MiB',
233 'G' and 'B' as number postfix.
235 The list of available International System prefixes follows, with
236 indication of the corresponding powers of 10 and of 2.