doc/eval.texi

   1 @chapter Expression Evaluation
   2 @c man begin EXPRESSION EVALUATION
   3
   4 When evaluating an arithemetic expression, Libav 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 @end table
  76
  77 Note that:
  78
  79 @code{*} works like AND
  80
  81 @code{+} works like OR
  82
  83 thus
  84 @example
  85 if A then B else C
  86 @end example
  87 is equivalent to
  88 @example
  89 A*B + not(A)*C
  90 @end example
  91
  92 When A evaluates to either 1 or 0, that is the same as
  93 @example
  94 A*B + eq(A,0)*C
  95 @end example
  96
  97 In your C code, you can extend the list of unary and binary functions,
  98 and define recognized constants, so that they are available for your
  99 expressions.
 100
 101 The evaluator also recognizes the International System number
 102 postfixes. If 'i' is appended after the postfix, powers of 2 are used
 103 instead of powers of 10. The 'B' postfix multiplies the value for 8,
 104 and can be appended after another postfix or used alone. This allows
 105 using for example 'KB', 'MiB', 'G' and 'B' as postfix.
 106
 107 Follows the list of available International System postfixes, with
 108 indication of the corresponding powers of 10 and of 2.
 109 @table @option
 110 @item y
 111 -24 / -80
 112 @item z
 113 -21 / -70
 114 @item a
 115 -18 / -60
 116 @item f
 117 -15 / -50
 118 @item p
 119 -12 / -40
 120 @item n
 121 -9 / -30
 122 @item u
 123 -6 / -20
 124 @item m
 125 -3 / -10
 126 @item c
 127 -2
 128 @item d
 129 -1
 130 @item h
 131 2
 132 @item k
 133 3 / 10
 134 @item K
 135 3 / 10
 136 @item M
 137 6 / 20
 138 @item G
 139 9 / 30
 140 @item T
 141 12 / 40
 142 @item P
 143 15 / 40
 144 @item E
 145 18 / 50
 146 @item Z
 147 21 / 60
 148 @item Y
 149 24 / 70
 150 @end table
 151
 152 @c man end