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