Merge remote-tracking branch 'qatar/master'
[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 sinh(x)
24 @item cosh(x)
25 @item tanh(x)
26 @item sin(x)
27 @item cos(x)
28 @item tan(x)
29 @item atan(x)
30 @item asin(x)
31 @item acos(x)
32 @item exp(x)
33 @item log(x)
34 @item abs(x)
35 @item squish(x)
36 @item gauss(x)
37 @item isnan(x)
38 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
39
40 @item mod(x, y)
41 @item max(x, y)
42 @item min(x, y)
43 @item eq(x, y)
44 @item gte(x, y)
45 @item gt(x, y)
46 @item lte(x, y)
47 @item lt(x, y)
48 @item st(var, expr)
49 Allow to store the value of the expression @var{expr} in an internal
50 variable. @var{var} specifies the number of the variable where to
51 store the value, and it is a value ranging from 0 to 9. The function
52 returns the value stored in the internal variable.
53 Note, Variables are currently not shared between expressions.
54
55 @item ld(var)
56 Allow to load the value of the internal variable with number
57 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
58 The function returns the loaded value.
59
60 @item while(cond, expr)
61 Evaluate expression @var{expr} while the expression @var{cond} is
62 non-zero, and returns the value of the last @var{expr} evaluation, or
63 NAN if @var{cond} was always false.
64
65 @item ceil(expr)
66 Round the value of expression @var{expr} upwards to the nearest
67 integer. For example, "ceil(1.5)" is "2.0".
68
69 @item floor(expr)
70 Round the value of expression @var{expr} downwards to the nearest
71 integer. For example, "floor(-1.5)" is "-2.0".
72
73 @item trunc(expr)
74 Round the value of expression @var{expr} towards zero to the nearest
75 integer. For example, "trunc(-1.5)" is "-1.0".
76
77 @item sqrt(expr)
78 Compute the square root of @var{expr}. This is equivalent to
79 "(@var{expr})^.5".
80
81 @item not(expr)
82 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
83
84 @item pow(x, y)
85 Compute the power of @var{x} elevated @var{y}, it is equivalent to
86 "(@var{x})^(@var{y})".
87
88 @item random(x)
89 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
90 internal variable which will be used to save the seed/state.
91
92 @item hypot(x, y)
93 This function is similar to the C function with the same name; it returns
94 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
95 right triangle with sides of length @var{x} and @var{y}, or the distance of the
96 point (@var{x}, @var{y}) from the origin.
97
98 @item gcd(x, y)
99 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
100 @var{y} are 0 or either or both are less than zero then behavior is undefined.
101
102 @item if(x, y)
103 Evaluate @var{x}, and if the result is non-zero return the result of
104 the evaluation of @var{y}, return 0 otherwise.
105
106 @item ifnot(x, y)
107 Evaluate @var{x}, and if the result is zero return the result of the
108 evaluation of @var{y}, return 0 otherwise.
109
110 @item taylor(expr, x) taylor(expr, x, id)
111 Evaluate a taylor series at x.
112 expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
113 then 0 is assumed.
114 note, when you have the derivatives at y instead of 0
115 taylor(expr, x-y) can be used
116 When the series does not converge the results are undefined.
117
118 @item root(expr, max)
119 Finds x where f(x)=0 in the interval 0..max.
120 f() must be continuous or the result is undefined.
121 @end table
122
123 The following constants are available:
124 @table @option
125 @item PI
126 area of the unit disc, approximately 3.14
127 @item E
128 exp(1) (Euler's number), approximately 2.718
129 @item PHI
130 golden ratio (1+sqrt(5))/2, approximately 1.618
131 @end table
132
133 Assuming that an expression is considered "true" if it has a non-zero
134 value, note that:
135
136 @code{*} works like AND
137
138 @code{+} works like OR
139
140 and the construct:
141 @example
142 if A then B else C
143 @end example
144 is equivalent to
145 @example
146 if(A,B) + ifnot(A,C)
147 @end example
148
149 In your C code, you can extend the list of unary and binary functions,
150 and define recognized constants, so that they are available for your
151 expressions.
152
153 The evaluator also recognizes the International System number
154 postfixes. If 'i' is appended after the postfix, powers of 2 are used
155 instead of powers of 10. The 'B' postfix multiplies the value for 8,
156 and can be appended after another postfix or used alone. This allows
157 using for example 'KB', 'MiB', 'G' and 'B' as postfix.
158
159 Follows the list of available International System postfixes, with
160 indication of the corresponding powers of 10 and of 2.
161 @table @option
162 @item y
163 -24 / -80
164 @item z
165 -21 / -70
166 @item a
167 -18 / -60
168 @item f
169 -15 / -50
170 @item p
171 -12 / -40
172 @item n
173 -9 / -30
174 @item u
175 -6 / -20
176 @item m
177 -3 / -10
178 @item c
179 -2
180 @item d
181 -1
182 @item h
183 2
184 @item k
185 3 / 10
186 @item K
187 3 / 10
188 @item M
189 6 / 20
190 @item G
191 9 / 30
192 @item T
193 12 / 40
194 @item P
195 15 / 40
196 @item E
197 18 / 50
198 @item Z
199 21 / 60
200 @item Y
201 24 / 70
202 @end table
203
204 @c man end