git.sesse.net Git - ffmpeg/blob - doc/eval.texi

   1 @chapter Expression Evaluation
   2 @c man begin EXPRESSION EVALUATION
   3
   4 When evaluating an arithemetic 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 isnan(x)
  38 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
  39
  40 @item mod(x, y)
  41 @item max(x, y)
  42 @item min(x, y)
  43 @item eq(x, y)
  44 @item gte(x, y)
  45 @item gt(x, y)
  46 @item lte(x, y)
  47 @item lt(x, y)
  48 @item st(var, expr)
  49 Allow to store the value of the expression @var{expr} in an internal
  50 variable. @var{var} specifies the number of the variable where to
  51 store the value, and it is a value ranging from 0 to 9. The function
  52 returns the value stored in the internal variable.
  53
  54 @item ld(var)
  55 Allow to load the value of the internal variable with number
  56 @var{var}, which was previosly stored with st(@var{var}, @var{expr}).
  57 The function returns the loaded value.
  58
  59 @item while(cond, expr)
  60 Evaluate expression @var{expr} while the expression @var{cond} is
  61 non-zero, and returns the value of the last @var{expr} evaluation, or
  62 NAN if @var{cond} was always false.
  63
  64 @item ceil(expr)
  65 Round the value of expression @var{expr} upwards to the nearest
  66 integer. For example, "ceil(1.5)" is "2.0".
  67
  68 @item floor(expr)
  69 Round the value of expression @var{expr} downwards to the nearest
  70 integer. For example, "floor(-1.5)" is "-2.0".
  71
  72 @item trunc(expr)
  73 Round the value of expression @var{expr} towards zero to the nearest
  74 integer. For example, "trunc(-1.5)" is "-1.0".
  75
  76 @item sqrt(expr)
  77 Compute the square root of @var{expr}. This is equivalent to
  78 "(@var{expr})^.5".
  79
  80 @item not(expr)
  81 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
  82
  83 @item pow(x, y)
  84 Compute the power of @var{x} elevated @var{y}, it is equivalent to
  85 "(@var{x})^(@var{y})".
  86
  87 @item random(x)
  88 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
  89 internal variable which will be used to save the seed/state.
  90
  91 @item hypot(x, y)
  92 This function is similar to the C function with the same name; it returns
  93 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
  94 right triangle with sides of length @var{x} and @var{y}, or the distance of the
  95 point (@var{x}, @var{y}) from the origin.
  96
  97 @item gcd(x, y)
  98 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
  99 @var{y} are 0 or either or both are less than zero then behavior is undefined.
 100 @end table
 101
 102 The following constants are available:
 103 @table @option
 104 @item PI
 105 area of the unit disc, approximatively 3.14
 106 @item E
 107 exp(1) (Euler's number), approximatively 2.718
 108 @item PHI
 109 golden ratio (1+sqrt(5))/2, approximatively 1.618
 110 @end table
 111
 112 Note that:
 113
 114 @code{*} works like AND
 115
 116 @code{+} works like OR
 117
 118 thus
 119 @example
 120 if A then B else C
 121 @end example
 122 is equivalent to
 123 @example
 124 A*B + not(A)*C
 125 @end example
 126
 127 In your C code, you can extend the list of unary and binary functions,
 128 and define recognized constants, so that they are available for your
 129 expressions.
 130
 131 The evaluator also recognizes the International System number
 132 postfixes. If 'i' is appended after the postfix, powers of 2 are used
 133 instead of powers of 10. The 'B' postfix multiplies the value for 8,
 134 and can be appended after another postfix or used alone. This allows
 135 using for example 'KB', 'MiB', 'G' and 'B' as postfix.
 136
 137 Follows the list of available International System postfixes, with
 138 indication of the corresponding powers of 10 and of 2.
 139 @table @option
 140 @item y
 141 -24 / -80
 142 @item z
 143 -21 / -70
 144 @item a
 145 -18 / -60
 146 @item f
 147 -15 / -50
 148 @item p
 149 -12 / -40
 150 @item n
 151 -9 / -30
 152 @item u
 153 -6 / -20
 154 @item m
 155 -3 / -10
 156 @item c
 157 -2
 158 @item d
 159 -1
 160 @item h
 161 2
 162 @item k
 163 3 / 10
 164 @item K
 165 3 / 10
 166 @item M
 167 6 / 20
 168 @item G
 169 9 / 30
 170 @item T
 171 12 / 40
 172 @item P
 173 15 / 40
 174 @item E
 175 18 / 50
 176 @item Z
 177 21 / 60
 178 @item Y
 179 24 / 70
 180 @end table
 181
 182 @c man end