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