Add eval.texi file.
[ffmpeg.git] / doc / eval.texi
1 @chapter Expression Evaluation
2 @c man begin EXPRESSION EVALUATION
3
4 When evaluating an arithemetic 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 mod(x, y)
38 @item max(x, y)
39 @item min(x, y)
40 @item eq(x, y)
41 @item gte(x, y)
42 @item gt(x, y)
43 @item lte(x, y)
44 @item lt(x, y)
45 @item st(var, expr)
46 Allow to store the value of the expression @var{expr} in an internal
47 variable. @var{var} specifies the number of the variable where to
48 store the value, and it is a value ranging from 0 to 9. The function
49 returns the value stored in the internal variable.
50
51 @item ld(var)
52 Allow to load the value of the internal variable with number
53 @var{var}, which was previosly stored with st(@var{var}, @var{expr}).
54 The function returns the loaded value.
55
56 @item while(cond, expr)
57 Evaluate expression @var{expr} while the expression @var{cond} is
58 non-zero, and returns the value of the last @var{expr} evaluation, or
59 NAN if @var{cond} was always false.
60 @end table
61
62 Note that:
63
64 @code{*} works like AND
65
66 @code{+} works like OR
67
68 thus
69 @example
70 if A then B else C
71 @end example
72 is equivalent to
73 @example
74 A*B + not(A)*C
75 @end example
76
77 When A evaluates to either 1 or 0, that is the same as
78 @example
79 A*B + eq(A,0)*C
80 @end example
81
82 In your C code, you can extend the list of unary and binary functions,
83 and define recognized constants, so that they are available for your
84 expressions.
85
86 The evaluator also recognizes the International System number
87 postfixes. If 'i' is appended after the postfix, powers of 2 are used
88 instead of powers of 10. The 'B' postfix multiplies the value for 8,
89 and can be appended after another postfix or used alone. This allows
90 using for example 'KB', 'MiB', 'G' and 'B' as postfix.
91
92 Follows the list of available International System postfixes, with
93 indication of the corresponding powers of 10 and of 2.
94 @table @option
95 @item y
96 -24 / -80
97 @item z
98 -21 / -70
99 @item a
100 -18 / -60
101 @item f
102 -15 / -50
103 @item p
104 -12 / -40
105 @item n
106 -9 / -30
107 @item u
108 -6 / -20
109 @item m
110 -3 / -10
111 @item c
112 -2
113 @item d
114 -1
115 @item h
116 2
117 @item k
118 3 / 10
119 @item K
120 3 / 10
121 @item M
122 6 / 20
123 @item G
124 9 / 30
125 @item T
126 12 / 40
127 @item P
128 15 / 40
129 @item E
130 18 / 50
131 @item Z
132 21 / 60
133 @item Y
134 24 / 70
135 @end table
136
137 @c man end