| @chapter Expression Evaluation |
| @c man begin EXPRESSION EVALUATION |
| |
| When evaluating an arithmetic expression, FFmpeg uses an internal |
| formula evaluator, implemented through the @file{libavutil/eval.h} |
| interface. |
| |
| An expression may contain unary, binary operators, constants, and |
| functions. |
| |
| Two expressions @var{expr1} and @var{expr2} can be combined to form |
| another expression "@var{expr1};@var{expr2}". |
| @var{expr1} and @var{expr2} are evaluated in turn, and the new |
| expression evaluates to the value of @var{expr2}. |
| |
| The following binary operators are available: @code{+}, @code{-}, |
| @code{*}, @code{/}, @code{^}. |
| |
| The following unary operators are available: @code{+}, @code{-}. |
| |
| The following functions are available: |
| @table @option |
| @item sinh(x) |
| Compute hyperbolic sine of @var{x}. |
| |
| @item cosh(x) |
| Compute hyperbolic cosine of @var{x}. |
| |
| @item tanh(x) |
| Compute hyperbolic tangent of @var{x}. |
| |
| @item sin(x) |
| Compute sine of @var{x}. |
| |
| @item cos(x) |
| Compute cosine of @var{x}. |
| |
| @item tan(x) |
| Compute tangent of @var{x}. |
| |
| @item atan(x) |
| Compute arctangent of @var{x}. |
| |
| @item asin(x) |
| Compute arcsine of @var{x}. |
| |
| @item acos(x) |
| Compute arccosine of @var{x}. |
| |
| @item exp(x) |
| Compute exponential of @var{x} (with base @code{e}, the Euler's number). |
| |
| @item log(x) |
| Compute natural logarithm of @var{x}. |
| |
| @item abs(x) |
| Compute absolute value of @var{x}. |
| |
| @item squish(x) |
| Compute expression @code{1/(1 + exp(4*x))}. |
| |
| @item gauss(x) |
| Compute Gauss function of @var{x}, corresponding to |
| @code{exp(-x*x/2) / sqrt(2*PI)}. |
| |
| @item isinf(x) |
| Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise. |
| |
| @item isnan(x) |
| Return 1.0 if @var{x} is NAN, 0.0 otherwise. |
| |
| @item mod(x, y) |
| Compute the remainder of division of @var{x} by @var{y}. |
| |
| @item max(x, y) |
| Return the maximum between @var{x} and @var{y}. |
| |
| @item min(x, y) |
| Return the maximum between @var{x} and @var{y}. |
| |
| @item eq(x, y) |
| Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. |
| |
| @item gte(x, y) |
| Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. |
| |
| @item gt(x, y) |
| Return 1 if @var{x} is greater than @var{y}, 0 otherwise. |
| |
| @item lte(x, y) |
| Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise. |
| |
| @item lt(x, y) |
| Return 1 if @var{x} is lesser than @var{y}, 0 otherwise. |
| |
| @item st(var, expr) |
| Allow to store the value of the expression @var{expr} in an internal |
| variable. @var{var} specifies the number of the variable where to |
| store the value, and it is a value ranging from 0 to 9. The function |
| returns the value stored in the internal variable. |
| Note, Variables are currently not shared between expressions. |
| |
| @item ld(var) |
| Allow to load the value of the internal variable with number |
| @var{var}, which was previously stored with st(@var{var}, @var{expr}). |
| The function returns the loaded value. |
| |
| @item while(cond, expr) |
| Evaluate expression @var{expr} while the expression @var{cond} is |
| non-zero, and returns the value of the last @var{expr} evaluation, or |
| NAN if @var{cond} was always false. |
| |
| @item ceil(expr) |
| Round the value of expression @var{expr} upwards to the nearest |
| integer. For example, "ceil(1.5)" is "2.0". |
| |
| @item floor(expr) |
| Round the value of expression @var{expr} downwards to the nearest |
| integer. For example, "floor(-1.5)" is "-2.0". |
| |
| @item trunc(expr) |
| Round the value of expression @var{expr} towards zero to the nearest |
| integer. For example, "trunc(-1.5)" is "-1.0". |
| |
| @item sqrt(expr) |
| Compute the square root of @var{expr}. This is equivalent to |
| "(@var{expr})^.5". |
| |
| @item not(expr) |
| Return 1.0 if @var{expr} is zero, 0.0 otherwise. |
| |
| @item pow(x, y) |
| Compute the power of @var{x} elevated @var{y}, it is equivalent to |
| "(@var{x})^(@var{y})". |
| |
| @item random(x) |
| Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the |
| internal variable which will be used to save the seed/state. |
| |
| @item hypot(x, y) |
| This function is similar to the C function with the same name; it returns |
| "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a |
| right triangle with sides of length @var{x} and @var{y}, or the distance of the |
| point (@var{x}, @var{y}) from the origin. |
| |
| @item gcd(x, y) |
| Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and |
| @var{y} are 0 or either or both are less than zero then behavior is undefined. |
| |
| @item if(x, y) |
| Evaluate @var{x}, and if the result is non-zero return the result of |
| the evaluation of @var{y}, return 0 otherwise. |
| |
| @item ifnot(x, y) |
| Evaluate @var{x}, and if the result is zero return the result of the |
| evaluation of @var{y}, return 0 otherwise. |
| |
| @item taylor(expr, x) taylor(expr, x, id) |
| Evaluate a taylor series at x. |
| expr represents the LD(id)-th derivates of f(x) at 0. If id is not specified |
| then 0 is assumed. |
| note, when you have the derivatives at y instead of 0 |
| taylor(expr, x-y) can be used |
| When the series does not converge the results are undefined. |
| |
| @item root(expr, max) |
| Finds x where f(x)=0 in the interval 0..max. |
| f() must be continuous or the result is undefined. |
| @end table |
| |
| The following constants are available: |
| @table @option |
| @item PI |
| area of the unit disc, approximately 3.14 |
| @item E |
| exp(1) (Euler's number), approximately 2.718 |
| @item PHI |
| golden ratio (1+sqrt(5))/2, approximately 1.618 |
| @end table |
| |
| Assuming that an expression is considered "true" if it has a non-zero |
| value, note that: |
| |
| @code{*} works like AND |
| |
| @code{+} works like OR |
| |
| and the construct: |
| @example |
| if A then B else C |
| @end example |
| is equivalent to |
| @example |
| if(A,B) + ifnot(A,C) |
| @end example |
| |
| In your C code, you can extend the list of unary and binary functions, |
| and define recognized constants, so that they are available for your |
| expressions. |
| |
| The evaluator also recognizes the International System number |
| postfixes. If 'i' is appended after the postfix, powers of 2 are used |
| instead of powers of 10. The 'B' postfix multiplies the value for 8, |
| and can be appended after another postfix or used alone. This allows |
| using for example 'KB', 'MiB', 'G' and 'B' as postfix. |
| |
| Follows the list of available International System postfixes, with |
| indication of the corresponding powers of 10 and of 2. |
| @table @option |
| @item y |
| -24 / -80 |
| @item z |
| -21 / -70 |
| @item a |
| -18 / -60 |
| @item f |
| -15 / -50 |
| @item p |
| -12 / -40 |
| @item n |
| -9 / -30 |
| @item u |
| -6 / -20 |
| @item m |
| -3 / -10 |
| @item c |
| -2 |
| @item d |
| -1 |
| @item h |
| 2 |
| @item k |
| 3 / 10 |
| @item K |
| 3 / 10 |
| @item M |
| 6 / 20 |
| @item G |
| 9 / 30 |
| @item T |
| 12 / 40 |
| @item P |
| 15 / 40 |
| @item E |
| 18 / 50 |
| @item Z |
| 21 / 60 |
| @item Y |
| 24 / 70 |
| @end table |
| |
| @c man end |