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 abs(x)
  24 Compute absolute value of @var{x}.
  25
  26 @item acos(x)
  27 Compute arccosine of @var{x}.
  28
  29 @item asin(x)
  30 Compute arcsine of @var{x}.
  31
  32 @item atan(x)
  33 Compute arctangent of @var{x}.
  34
  35 @item between(x, min, max)
  36 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
  37 equal to @var{max}, 0 otherwise.
  38
  39 @item bitand(x, y)
  40 @item bitor(x, y)
  41 Compute bitwise and/or operation on @var{x} and @var{y}.
  42
  43 The results of the evaluation of @var{x} and @var{y} are converted to
  44 integers before executing the bitwise operation.
  45
  46 Note that both the conversion to integer and the conversion back to
  47 floating point can lose precision. Beware of unexpected results for
  48 large numbers (usually 2^53 and larger).
  49
  50 @item ceil(expr)
  51 Round the value of expression @var{expr} upwards to the nearest
  52 integer. For example, "ceil(1.5)" is "2.0".
  53
  54 @item cos(x)
  55 Compute cosine of @var{x}.
  56
  57 @item cosh(x)
  58 Compute hyperbolic cosine of @var{x}.
  59
  60 @item eq(x, y)
  61 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
  62
  63 @item exp(x)
  64 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
  65
  66 @item floor(expr)
  67 Round the value of expression @var{expr} downwards to the nearest
  68 integer. For example, "floor(-1.5)" is "-2.0".
  69
  70 @item gauss(x)
  71 Compute Gauss function of @var{x}, corresponding to
  72 @code{exp(-x*x/2) / sqrt(2*PI)}.
  73
  74 @item gcd(x, y)
  75 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
  76 @var{y} are 0 or either or both are less than zero then behavior is undefined.
  77
  78 @item gt(x, y)
  79 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
  80
  81 @item gte(x, y)
  82 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
  83
  84 @item hypot(x, y)
  85 This function is similar to the C function with the same name; it returns
  86 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
  87 right triangle with sides of length @var{x} and @var{y}, or the distance of the
  88 point (@var{x}, @var{y}) from the origin.
  89
  90 @item if(x, y)
  91 Evaluate @var{x}, and if the result is non-zero return the result of
  92 the evaluation of @var{y}, return 0 otherwise.
  93
  94 @item if(x, y, z)
  95 Evaluate @var{x}, and if the result is non-zero return the evaluation
  96 result of @var{y}, otherwise the evaluation result of @var{z}.
  97
  98 @item ifnot(x, y)
  99 Evaluate @var{x}, and if the result is zero return the result of the
 100 evaluation of @var{y}, return 0 otherwise.
 101
 102 @item ifnot(x, y, z)
 103 Evaluate @var{x}, and if the result is zero return the evaluation
 104 result of @var{y}, otherwise the evaluation result of @var{z}.
 105
 106 @item isinf(x)
 107 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
 108
 109 @item isnan(x)
 110 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
 111
 112 @item ld(var)
 113 Allow to load the value of the internal variable with number
 114 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
 115 The function returns the loaded value.
 116
 117 @item log(x)
 118 Compute natural logarithm of @var{x}.
 119
 120 @item lt(x, y)
 121 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
 122
 123 @item lte(x, y)
 124 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
 125
 126 @item max(x, y)
 127 Return the maximum between @var{x} and @var{y}.
 128
 129 @item min(x, y)
 130 Return the maximum between @var{x} and @var{y}.
 131
 132 @item mod(x, y)
 133 Compute the remainder of division of @var{x} by @var{y}.
 134
 135 @item not(expr)
 136 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
 137
 138 @item pow(x, y)
 139 Compute the power of @var{x} elevated @var{y}, it is equivalent to
 140 "(@var{x})^(@var{y})".
 141
 142 @item print(t)
 143 @item print(t, l)
 144 Print the value of expression @var{t} with loglevel @var{l}. If
 145 @var{l} is not specified then a default log level is used.
 146 Returns the value of the expression printed.
 147
 148 Prints t with loglevel l
 149
 150 @item random(x)
 151 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
 152 internal variable which will be used to save the seed/state.
 153
 154 @item root(expr, max)
 155 Find an input value for which the function represented by @var{expr}
 156 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
 157
 158 The expression in @var{expr} must denote a continuous function or the
 159 result is undefined.
 160
 161 @var{ld(0)} is used to represent the function input value, which means
 162 that the given expression will be evaluated multiple times with
 163 various input values that the expression can access through
 164 @code{ld(0)}. When the expression evaluates to 0 then the
 165 corresponding input value will be returned.
 166
 167 @item sin(x)
 168 Compute sine of @var{x}.
 169
 170 @item sinh(x)
 171 Compute hyperbolic sine of @var{x}.
 172
 173 @item sqrt(expr)
 174 Compute the square root of @var{expr}. This is equivalent to
 175 "(@var{expr})^.5".
 176
 177 @item squish(x)
 178 Compute expression @code{1/(1 + exp(4*x))}.
 179
 180 @item st(var, expr)
 181 Allow to store the value of the expression @var{expr} in an internal
 182 variable. @var{var} specifies the number of the variable where to
 183 store the value, and it is a value ranging from 0 to 9. The function
 184 returns the value stored in the internal variable.
 185 Note, Variables are currently not shared between expressions.
 186
 187 @item tan(x)
 188 Compute tangent of @var{x}.
 189
 190 @item tanh(x)
 191 Compute hyperbolic tangent of @var{x}.
 192
 193 @item taylor(expr, x)
 194 @item taylor(expr, x, id)
 195 Evaluate a Taylor series at @var{x}, given an expression representing
 196 the @code{ld(id)}-th derivative of a function at 0.
 197
 198 When the series does not converge the result is undefined.
 199
 200 @var{ld(id)} is used to represent the derivative order in @var{expr},
 201 which means that the given expression will be evaluated multiple times
 202 with various input values that the expression can access through
 203 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
 204
 205 Note, when you have the derivatives at y instead of 0,
 206 @code{taylor(expr, x-y)} can be used.
 207
 208 @item time(0)
 209 Return the current (wallclock) time in seconds.
 210
 211 @item trunc(expr)
 212 Round the value of expression @var{expr} towards zero to the nearest
 213 integer. For example, "trunc(-1.5)" is "-1.0".
 214
 215 @item while(cond, expr)
 216 Evaluate expression @var{expr} while the expression @var{cond} is
 217 non-zero, and returns the value of the last @var{expr} evaluation, or
 218 NAN if @var{cond} was always false.
 219 @end table
 220
 221 The following constants are available:
 222 @table @option
 223 @item PI
 224 area of the unit disc, approximately 3.14
 225 @item E
 226 exp(1) (Euler's number), approximately 2.718
 227 @item PHI
 228 golden ratio (1+sqrt(5))/2, approximately 1.618
 229 @end table
 230
 231 Assuming that an expression is considered "true" if it has a non-zero
 232 value, note that:
 233
 234 @code{*} works like AND
 235
 236 @code{+} works like OR
 237
 238 For example the construct:
 239 @example
 240 if (A AND B) then C
 241 @end example
 242 is equivalent to:
 243 @example
 244 if(A*B, C)
 245 @end example
 246
 247 In your C code, you can extend the list of unary and binary functions,
 248 and define recognized constants, so that they are available for your
 249 expressions.
 250
 251 The evaluator also recognizes the International System unit prefixes.
 252 If 'i' is appended after the prefix, binary prefixes are used, which
 253 are based on powers of 1024 instead of powers of 1000.
 254 The 'B' postfix multiplies the value by 8, and can be appended after a
 255 unit prefix or used alone. This allows using for example 'KB', 'MiB',
 256 'G' and 'B' as number postfix.
 257
 258 The list of available International System prefixes follows, with
 259 indication of the corresponding powers of 10 and of 2.
 260 @table @option
 261 @item y
 262 10^-24 / 2^-80
 263 @item z
 264 10^-21 / 2^-70
 265 @item a
 266 10^-18 / 2^-60
 267 @item f
 268 10^-15 / 2^-50
 269 @item p
 270 10^-12 / 2^-40
 271 @item n
 272 10^-9 / 2^-30
 273 @item u
 274 10^-6 / 2^-20
 275 @item m
 276 10^-3 / 2^-10
 277 @item c
 278 10^-2
 279 @item d
 280 10^-1
 281 @item h
 282 10^2
 283 @item k
 284 10^3 / 2^10
 285 @item K
 286 10^3 / 2^10
 287 @item M
 288 10^6 / 2^20
 289 @item G
 290 10^9 / 2^30
 291 @item T
 292 10^12 / 2^40
 293 @item P
 294 10^15 / 2^40
 295 @item E
 296 10^18 / 2^50
 297 @item Z
 298 10^21 / 2^60
 299 @item Y
 300 10^24 / 2^70
 301 @end table
 302
 303 @c man end