aboutsummaryrefslogtreecommitdiffstats
path: root/doc/eval.texi
blob: c4a8ac564f6a845b17331a5adda9f072d17c183c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@chapter Expression Evaluation
@c man begin EXPRESSION EVALUATION

When evaluating an arithmetic expression, FFmpeg uses an internal
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)
@item cosh(x)
@item tanh(x)
@item sin(x)
@item cos(x)
@item tan(x)
@item atan(x)
@item asin(x)
@item acos(x)
@item exp(x)
@item log(x)
@item abs(x)
@item squish(x)
@item gauss(x)
@item isnan(x)
Return 1.0 if @var{x} is NAN, 0.0 otherwise.

@item mod(x, y)
@item max(x, y)
@item min(x, y)
@item eq(x, y)
@item gte(x, y)
@item gt(x, y)
@item lte(x, y)
@item lt(x, y)
@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.
Note, Variables are currently not shared between expressions.

@item ld(var)
Allow to load the value of the internal variable with number
@var{var}, which was previously stored with st(@var{var}, @var{expr}).
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.

@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".

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

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

@item pow(x, y)
Compute the power of @var{x} elevated @var{y}, it is equivalent to
"(@var{x})^(@var{y})".

@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.

@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.

@item taylor(expr, x) taylor(expr, x, id)
Evaluate a taylor series at x.
expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
then 0 is assumed.
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.
@end table

The following constants are available:
@table @option
@item PI
area of the unit disc, approximately 3.14
@item E
exp(1) (Euler's number), approximately 2.718
@item PHI
golden ratio (1+sqrt(5))/2, approximately 1.618
@end table

Assuming that an expression is considered "true" if it has a non-zero
value, note that:

@code{*} works like AND

@code{+} works like OR

and the construct:
@example
if A then B else C
@end example
is equivalent to
@example
if(A,B) + ifnot(A,C)
@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