diff options
Diffstat (limited to 'doc/eval.texi')
| -rw-r--r-- | doc/eval.texi | 283 |
1 files changed, 215 insertions, 68 deletions
diff --git a/doc/eval.texi b/doc/eval.texi index e1fd7ee484..24db3b853b 100644 --- a/doc/eval.texi +++ b/doc/eval.texi @@ -1,7 +1,7 @@ @chapter Expression Evaluation @c man begin EXPRESSION EVALUATION -When evaluating an arithmetic expression, Libav uses an internal +When evaluating an arithmetic expression, FFmpeg uses an internal formula evaluator, implemented through the @file{libavutil/eval.h} interface. @@ -20,137 +20,284 @@ The following unary operators are available: @code{+}, @code{-}. The following functions are available: @table @option -@item sinh(x) -@item cosh(x) -@item tanh(x) -@item sin(x) -@item cos(x) -@item tan(x) -@item atan(x) -@item asin(x) +@item abs(x) +Compute absolute value of @var{x}. + @item acos(x) +Compute arccosine of @var{x}. + +@item asin(x) +Compute arcsine of @var{x}. + +@item atan(x) +Compute arctangent of @var{x}. + +@item between(x, min, max) +Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or +equal to @var{max}, 0 otherwise. + +@item bitand(x, y) +@item bitor(x, y) +Compute bitwise and/or operation on @var{x} and @var{y}. + +The results of the evaluation of @var{x} and @var{y} are converted to +integers before executing the bitwise operation. + +Note that both the conversion to integer and the conversion back to +floating point can lose precision. Beware of unexpected results for +large numbers (usually 2^53 and larger). + +@item ceil(expr) +Round the value of expression @var{expr} upwards to the nearest +integer. For example, "ceil(1.5)" is "2.0". + +@item cos(x) +Compute cosine of @var{x}. + +@item cosh(x) +Compute hyperbolic cosine of @var{x}. + +@item eq(x, y) +Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. + @item exp(x) -@item log(x) -@item abs(x) -@item squish(x) +Compute exponential of @var{x} (with base @code{e}, the Euler's number). + +@item floor(expr) +Round the value of expression @var{expr} downwards to the nearest +integer. For example, "floor(-1.5)" is "-2.0". + @item gauss(x) +Compute Gauss function of @var{x}, corresponding to +@code{exp(-x*x/2) / sqrt(2*PI)}. + +@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 gt(x, y) +Return 1 if @var{x} is greater than @var{y}, 0 otherwise. + +@item gte(x, y) +Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. + +@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 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 if(x, y, z) +Evaluate @var{x}, and if the result is non-zero return the evaluation +result of @var{y}, otherwise the evaluation result of @var{z}. + +@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 ifnot(x, y, z) +Evaluate @var{x}, and if the result is zero return the evaluation +result of @var{y}, otherwise the evaluation result of @var{z}. + @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) +@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 log(x) +Compute natural logarithm of @var{x}. + +@item lt(x, y) +Return 1 if @var{x} is lesser 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 max(x, y) +Return the maximum between @var{x} and @var{y}. + @item min(x, y) -@item eq(x, y) -@item gte(x, y) -@item gt(x, y) -@item lte(x, y) -@item lt(x, y) +Return the maximum between @var{x} and @var{y}. + +@item mod(x, y) +Compute the remainder of division of @var{x} by @var{y}. + +@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 print(t) +@item print(t, l) +Print the value of expression @var{t} with loglevel @var{l}. If +@var{l} is not specified then a default log level is used. +Returns the value of the expression printed. + +Prints t with loglevel l + +@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 root(expr, max) +Find an input value for which the function represented by @var{expr} +with argument @var{ld(0)} is 0 in the interval 0..@var{max}. + +The expression in @var{expr} must denote a continuous function or the +result is undefined. + +@var{ld(0)} is used to represent the function input value, which means +that the given expression will be evaluated multiple times with +various input values that the expression can access through +@code{ld(0)}. When the expression evaluates to 0 then the +corresponding input value will be returned. + +@item sin(x) +Compute sine of @var{x}. + +@item sinh(x) +Compute hyperbolic sine of @var{x}. + +@item sqrt(expr) +Compute the square root of @var{expr}. This is equivalent to +"(@var{expr})^.5". + +@item squish(x) +Compute expression @code{1/(1 + exp(4*x))}. + @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 tan(x) +Compute tangent of @var{x}. -@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 tanh(x) +Compute hyperbolic tangent of @var{x}. -@item ceil(expr) -Round the value of expression @var{expr} upwards to the nearest -integer. For example, "ceil(1.5)" is "2.0". +@item taylor(expr, x) +@item taylor(expr, x, id) +Evaluate a Taylor series at @var{x}, given an expression representing +the @code{ld(id)}-th derivative of a function at 0. -@item floor(expr) -Round the value of expression @var{expr} downwards to the nearest -integer. For example, "floor(-1.5)" is "-2.0". +When the series does not converge the result is undefined. + +@var{ld(id)} is used to represent the derivative order in @var{expr}, +which means that the given expression will be evaluated multiple times +with various input values that the expression can access through +@code{ld(id)}. If @var{id} is not specified then 0 is assumed. + +Note, when you have the derivatives at y instead of 0, +@code{taylor(expr, x-y)} can be used. + +@item time(0) +Return the current (wallclock) time in seconds. @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 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. +@end table -@item not(expr) -Return 1.0 if @var{expr} is zero, 0.0 otherwise. +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 -Note that: +Assuming that an expression is considered "true" if it has a non-zero +value, note that: @code{*} works like AND @code{+} works like OR -thus +For example the construct: @example -if A then B else C +if (A AND B) then C @end example -is equivalent to +is equivalent to: @example -A*B + not(A)*C +if(A*B, 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. +The evaluator also recognizes the International System unit prefixes. +If 'i' is appended after the prefix, binary prefixes are used, which +are based on powers of 1024 instead of powers of 1000. +The 'B' postfix multiplies the value by 8, and can be appended after a +unit prefix or used alone. This allows using for example 'KB', 'MiB', +'G' and 'B' as number postfix. -Follows the list of available International System postfixes, with +The list of available International System prefixes follows, with indication of the corresponding powers of 10 and of 2. @table @option @item y --24 / -80 +10^-24 / 2^-80 @item z --21 / -70 +10^-21 / 2^-70 @item a --18 / -60 +10^-18 / 2^-60 @item f --15 / -50 +10^-15 / 2^-50 @item p --12 / -40 +10^-12 / 2^-40 @item n --9 / -30 +10^-9 / 2^-30 @item u --6 / -20 +10^-6 / 2^-20 @item m --3 / -10 +10^-3 / 2^-10 @item c --2 +10^-2 @item d --1 +10^-1 @item h -2 +10^2 @item k -3 / 10 +10^3 / 2^10 @item K -3 / 10 +10^3 / 2^10 @item M -6 / 20 +10^6 / 2^20 @item G -9 / 30 +10^9 / 2^30 @item T -12 / 40 +10^12 / 2^40 @item P -15 / 40 +10^15 / 2^40 @item E -18 / 50 +10^18 / 2^50 @item Z -21 / 60 +10^21 / 2^60 @item Y -24 / 70 +10^24 / 2^70 @end table @c man end |