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