eval.texi 6.24 KB
Newer Older
Stefano Sabatini's avatar
Stefano Sabatini committed
1 2 3
@chapter Expression Evaluation
@c man begin EXPRESSION EVALUATION

4
When evaluating an arithmetic expression, FFmpeg uses an internal
Stefano Sabatini's avatar
Stefano Sabatini committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
formula evaluator, implemented through the @file{libavutil/eval.h}
interface.

An expression may contain unary, binary operators, constants, and
functions.

Two expressions @var{expr1} and @var{expr2} can be combined to form
another expression "@var{expr1};@var{expr2}".
@var{expr1} and @var{expr2} are evaluated in turn, and the new
expression evaluates to the value of @var{expr2}.

The following binary operators are available: @code{+}, @code{-},
@code{*}, @code{/}, @code{^}.

The following unary operators are available: @code{+}, @code{-}.

The following functions are available:
@table @option
@item sinh(x)
24 25
Compute hyperbolic sine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
26
@item cosh(x)
27 28
Compute hyperbolic cosine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
29
@item tanh(x)
30 31
Compute hyperbolic tangent of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
32
@item sin(x)
33 34
Compute sine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
35
@item cos(x)
36 37
Compute cosine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
38
@item tan(x)
39 40
Compute tangent of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
41
@item atan(x)
42 43
Compute arctangent of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
44
@item asin(x)
45 46
Compute arcsine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
47
@item acos(x)
48 49
Compute arccosine of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
50
@item exp(x)
51 52
Compute exponential of @var{x} (with base @code{e}, the Euler's number).

Stefano Sabatini's avatar
Stefano Sabatini committed
53
@item log(x)
54 55
Compute natural logarithm of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
56
@item abs(x)
57 58
Compute absolute value of @var{x}.

Stefano Sabatini's avatar
Stefano Sabatini committed
59
@item squish(x)
60 61
Compute expression @code{1/(1 + exp(4*x))}.

Stefano Sabatini's avatar
Stefano Sabatini committed
62
@item gauss(x)
63 64 65
Compute Gauss function of @var{x}, corresponding to
@code{exp(-x*x/2) / sqrt(2*PI)}.

66 67
@item isinf(x)
Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
68

69 70 71
@item isnan(x)
Return 1.0 if @var{x} is NAN, 0.0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
72
@item mod(x, y)
73 74
Compute the remainder of division of @var{x} by @var{y}.

Stefano Sabatini's avatar
Stefano Sabatini committed
75
@item max(x, y)
76 77
Return the maximum between @var{x} and @var{y}.

Stefano Sabatini's avatar
Stefano Sabatini committed
78
@item min(x, y)
79 80
Return the maximum between @var{x} and @var{y}.

Stefano Sabatini's avatar
Stefano Sabatini committed
81
@item eq(x, y)
82 83
Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
84
@item gte(x, y)
85 86
Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
87
@item gt(x, y)
88 89
Return 1 if @var{x} is greater than @var{y}, 0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
90
@item lte(x, y)
91 92
Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
93
@item lt(x, y)
94 95
Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.

Stefano Sabatini's avatar
Stefano Sabatini committed
96 97 98 99 100
@item st(var, expr)
Allow to store the value of the expression @var{expr} in an internal
variable. @var{var} specifies the number of the variable where to
store the value, and it is a value ranging from 0 to 9. The function
returns the value stored in the internal variable.
101
Note, Variables are currently not shared between expressions.
Stefano Sabatini's avatar
Stefano Sabatini committed
102 103 104

@item ld(var)
Allow to load the value of the internal variable with number
105
@var{var}, which was previously stored with st(@var{var}, @var{expr}).
Stefano Sabatini's avatar
Stefano Sabatini committed
106 107 108 109 110 111
The function returns the loaded value.

@item while(cond, expr)
Evaluate expression @var{expr} while the expression @var{cond} is
non-zero, and returns the value of the last @var{expr} evaluation, or
NAN if @var{cond} was always false.
112 113 114 115 116 117 118 119 120 121 122 123

@item ceil(expr)
Round the value of expression @var{expr} upwards to the nearest
integer. For example, "ceil(1.5)" is "2.0".

@item floor(expr)
Round the value of expression @var{expr} downwards to the nearest
integer. For example, "floor(-1.5)" is "-2.0".

@item trunc(expr)
Round the value of expression @var{expr} towards zero to the nearest
integer. For example, "trunc(-1.5)" is "-1.0".
124 125 126 127

@item sqrt(expr)
Compute the square root of @var{expr}. This is equivalent to
"(@var{expr})^.5".
128 129 130

@item not(expr)
Return 1.0 if @var{expr} is zero, 0.0 otherwise.
131 132 133 134

@item pow(x, y)
Compute the power of @var{x} elevated @var{y}, it is equivalent to
"(@var{x})^(@var{y})".
135 136 137 138 139 140 141 142 143 144 145 146 147 148

@item random(x)
Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
internal variable which will be used to save the seed/state.

@item hypot(x, y)
This function is similar to the C function with the same name; it returns
"sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
right triangle with sides of length @var{x} and @var{y}, or the distance of the
point (@var{x}, @var{y}) from the origin.

@item gcd(x, y)
Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
@var{y} are 0 or either or both are less than zero then behavior is undefined.
149 150 151 152 153 154 155 156

@item if(x, y)
Evaluate @var{x}, and if the result is non-zero return the result of
the evaluation of @var{y}, return 0 otherwise.

@item ifnot(x, y)
Evaluate @var{x}, and if the result is zero return the result of the
evaluation of @var{y}, return 0 otherwise.
157

158
@item taylor(expr, x) taylor(expr, x, id)
159
Evaluate a taylor series at x.
160 161
expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
then 0 is assumed.
162 163 164
note, when you have the derivatives at y instead of 0
taylor(expr, x-y) can be used
When the series does not converge the results are undefined.
165 166 167 168

@item root(expr, max)
Finds x where f(x)=0 in the interval 0..max.
f() must be continuous or the result is undefined.
Stefano Sabatini's avatar
Stefano Sabatini committed
169 170
@end table

171 172 173
The following constants are available:
@table @option
@item PI
174
area of the unit disc, approximately 3.14
175
@item E
176
exp(1) (Euler's number), approximately 2.718
177
@item PHI
178
golden ratio (1+sqrt(5))/2, approximately 1.618
179 180
@end table

181 182
Assuming that an expression is considered "true" if it has a non-zero
value, note that:
Stefano Sabatini's avatar
Stefano Sabatini committed
183 184 185 186 187

@code{*} works like AND

@code{+} works like OR

188
and the construct:
Stefano Sabatini's avatar
Stefano Sabatini committed
189 190 191 192 193
@example
if A then B else C
@end example
is equivalent to
@example
194
if(A,B) + ifnot(A,C)
Stefano Sabatini's avatar
Stefano Sabatini committed
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
@end example

In your C code, you can extend the list of unary and binary functions,
and define recognized constants, so that they are available for your
expressions.

The evaluator also recognizes the International System number
postfixes. If 'i' is appended after the postfix, powers of 2 are used
instead of powers of 10. The 'B' postfix multiplies the value for 8,
and can be appended after another postfix or used alone. This allows
using for example 'KB', 'MiB', 'G' and 'B' as postfix.

Follows the list of available International System postfixes, with
indication of the corresponding powers of 10 and of 2.
@table @option
@item y
-24 / -80
@item z
-21 / -70
@item a
-18 / -60
@item f
-15 / -50
@item p
-12 / -40
@item n
-9 / -30
@item u
-6 / -20
@item m
-3 / -10
@item c
-2
@item d
-1
@item h
2
@item k
3 / 10
@item K
3 / 10
@item M
6 / 20
@item G
9 / 30
@item T
12 / 40
@item P
15 / 40
@item E
18 / 50
@item Z
21 / 60
@item Y
24 / 70
@end table

@c man end