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 @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 Note, Variables are currently not shared between expressions.
  56
  57 @item ld(var)
  58 Allow to load the value of the internal variable with number
  59 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
  60 The function returns the loaded value.
  61
  62 @item while(cond, expr)
  63 Evaluate expression @var{expr} while the expression @var{cond} is
  64 non-zero, and returns the value of the last @var{expr} evaluation, or
  65 NAN if @var{cond} was always false.
  66
  67 @item ceil(expr)
  68 Round the value of expression @var{expr} upwards to the nearest
  69 integer. For example, "ceil(1.5)" is "2.0".
  70
  71 @item floor(expr)
  72 Round the value of expression @var{expr} downwards to the nearest
  73 integer. For example, "floor(-1.5)" is "-2.0".
  74
  75 @item trunc(expr)
  76 Round the value of expression @var{expr} towards zero to the nearest
  77 integer. For example, "trunc(-1.5)" is "-1.0".
  78
  79 @item sqrt(expr)
  80 Compute the square root of @var{expr}. This is equivalent to
  81 "(@var{expr})^.5".
  82
  83 @item not(expr)
  84 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
  85
  86 @item pow(x, y)
  87 Compute the power of @var{x} elevated @var{y}, it is equivalent to
  88 "(@var{x})^(@var{y})".
  89
  90 @item random(x)
  91 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
  92 internal variable which will be used to save the seed/state.
  93
  94 @item hypot(x, y)
  95 This function is similar to the C function with the same name; it returns
  96 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
  97 right triangle with sides of length @var{x} and @var{y}, or the distance of the
  98 point (@var{x}, @var{y}) from the origin.
  99
 100 @item gcd(x, y)
 101 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
 102 @var{y} are 0 or either or both are less than zero then behavior is undefined.
 103
 104 @item if(x, y)
 105 Evaluate @var{x}, and if the result is non-zero return the result of
 106 the evaluation of @var{y}, return 0 otherwise.
 107
 108 @item ifnot(x, y)
 109 Evaluate @var{x}, and if the result is zero return the result of the
 110 evaluation of @var{y}, return 0 otherwise.
 111
 112 @item taylor(expr, x) taylor(expr, x, id)
 113 Evaluate a taylor series at x.
 114 expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified
 115 then 0 is assumed.
 116 note, when you have the derivatives at y instead of 0
 117 taylor(expr, x-y) can be used
 118 When the series does not converge the results are undefined.
 119
 120 @item root(expr, max)
 121 Finds x where f(x)=0 in the interval 0..max.
 122 f() must be continuous or the result is undefined.
 123 @end table
 124
 125 The following constants are available:
 126 @table @option
 127 @item PI
 128 area of the unit disc, approximately 3.14
 129 @item E
 130 exp(1) (Euler's number), approximately 2.718
 131 @item PHI
 132 golden ratio (1+sqrt(5))/2, approximately 1.618
 133 @end table
 134
 135 Assuming that an expression is considered "true" if it has a non-zero
 136 value, note that:
 137
 138 @code{*} works like AND
 139
 140 @code{+} works like OR
 141
 142 and the construct:
 143 @example
 144 if A then B else C
 145 @end example
 146 is equivalent to
 147 @example
 148 if(A,B) + ifnot(A,C)
 149 @end example
 150
 151 In your C code, you can extend the list of unary and binary functions,
 152 and define recognized constants, so that they are available for your
 153 expressions.
 154
 155 The evaluator also recognizes the International System number
 156 postfixes. If 'i' is appended after the postfix, powers of 2 are used
 157 instead of powers of 10. The 'B' postfix multiplies the value for 8,
 158 and can be appended after another postfix or used alone. This allows
 159 using for example 'KB', 'MiB', 'G' and 'B' as postfix.
 160
 161 Follows the list of available International System postfixes, with
 162 indication of the corresponding powers of 10 and of 2.
 163 @table @option
 164 @item y
 165 -24 / -80
 166 @item z
 167 -21 / -70
 168 @item a
 169 -18 / -60
 170 @item f
 171 -15 / -50
 172 @item p
 173 -12 / -40
 174 @item n
 175 -9 / -30
 176 @item u
 177 -6 / -20
 178 @item m
 179 -3 / -10
 180 @item c
 181 -2
 182 @item d
 183 -1
 184 @item h
 185 2
 186 @item k
 187 3 / 10
 188 @item K
 189 3 / 10
 190 @item M
 191 6 / 20
 192 @item G
 193 9 / 30
 194 @item T
 195 12 / 40
 196 @item P
 197 15 / 40
 198 @item E
 199 18 / 50
 200 @item Z
 201 21 / 60
 202 @item Y
 203 24 / 70
 204 @end table
 205
 206 @c man end