[FFmpeg-devel] [PATCH 5/8] Add eval.texi file.

[Stefano Sabatini]

---
 Makefile            |    4 +-
 doc/eval.texi       |  117 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/ffmpeg-doc.texi |  106 ++++++++++++++++------------------------------
 doc/ffplay-doc.texi |    1 +
 4 files changed, 156 insertions(+), 72 deletions(-)
 create mode 100644 doc/eval.texi

diff --git a/Makefile b/Makefile
index b81b655..e9d9854 100644
--- a/Makefile
+++ b/Makefile
@@ -115,8 +115,8 @@ documentation: $(addprefix doc/, developer.html faq.html general.html libavfilte
 
 $(HTMLPAGES) $(MANPAGES): doc/fftools-common-opts.texi
 
-doc/ffmpeg.pod doc/ffmpeg-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
-doc/ffplay.pod doc/ffplay-doc.html: doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
+doc/ffmpeg.pod doc/ffmpeg-doc.html: doc/eval.texi doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
+doc/ffplay.pod doc/ffplay-doc.html: doc/eval.texi doc/indevs.texi doc/filters.texi doc/outdevs.texi doc/protocols.texi
 doc/ffprobe.pod doc/ffprobe-doc.html: doc/indevs.texi doc/protocols.texi
 
 doc/%.html: TAG = HTML
diff --git a/doc/eval.texi b/doc/eval.texi
new file mode 100644
index 0000000..ffd8ed9
--- /dev/null
+++ b/doc/eval.texi
@@ -0,0 +1,117 @@
+ at chapter Expression Evaluation
+ at c man begin EXPRESSION EVALUATION
+
+When evaluating an expression, FFmpeg uses an internal formula
+evaluator, implemeneted through the @file{libavutil/eval.h} interface.
+
+An expression of the kind:
+ at example
+ at var{expr1};@var{expr2}
+ at end example
+
+is again an expression, and evaluates to the value of @var{expr2}.
+
+An expression may contain unary, binary operators, and functions with
+one or two arguments.
+
+The following binary operators are available: @code{+}, @code{-},
+ at code{*}, @code{/}, @code{^}.
+
+The following unary operators are available: @code{+}, @code{-}.
+
+The following functions are available:
+ at table @option
+ at item sinh(x)
+ at item cosh(x)
+ at item tanh(x)
+ at item sin(x)
+ at item cos(x)
+ at item tan(x)
+ at item atan(x)
+ at item asin(x)
+ at item acos(x)
+ at item exp(x)
+ at item log(x)
+ at item abs(x)
+ at item squish(x)
+ at item gauss(x)
+ at item mod(x, y)
+ at item max(x, y)
+ at item min(x, y)
+ at item eq(x, y)
+ at item gte(x, y)
+ at item gt(x, y)
+ at item lte(x, y)
+ at item lt(x, y)
+ at 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.
+
+ at item ld(var)
+Allow to load the value of the internal variable with number
+ at var{var}, which was previosly stored with st(@var{var}, @var{expr}).
+The function returns the loaded value.
+
+ at item while(cond, expr)
+Evaluate expression @var{expr} when the expression @var{cond} is
+true, and returns the value of the last @var{expr} evaluation, or NAN
+if @var{cond} was always false.
+ at end table
+
+It is possible to define more unary and binary functions used in an
+expression, and define a list of the recognized constants.
+
+The evaluator also recognizes the Internation 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 SI postfixes, with indication of the
+corresponding powers of 10 and of 2.
+ at table @option
+ at item y
+-24 / -80
+ at item z
+-21 / -70
+ at item a
+-18 / -60
+ at item f
+-15 / -50
+ at item p
+-12 / -40
+ at item n
+-9 / -30
+ at item u
+-6 / -20
+ at item m
+-3 / -10
+ at item c
+-2
+ at item d
+-1
+ at item h
+2
+ at item k
+3 / 10
+ at item K
+3 / 10
+ at item M
+6 / 20
+ at item G
+9 / 30
+ at item T
+12 / 40
+ at item P
+15 / 40
+ at item E
+18 / 50
+ at item Z
+21 / 60
+ at item Y
+24 / 70
+ at end table
+
+ at c man end
diff --git a/doc/ffmpeg-doc.texi b/doc/ffmpeg-doc.texi
index bf5bdf4..778c508 100644
--- a/doc/ffmpeg-doc.texi
+++ b/doc/ffmpeg-doc.texi
@@ -354,8 +354,41 @@ qp offset between P- and B-frames
 @item -i_qoffset @var{offset}
 qp offset between P- and I-frames
 @item -rc_eq @var{equation}
-Set rate control equation (@pxref{FFmpeg formula
-evaluator}) (default = @code{tex^qComp}).
+Set rate control equation (see section "Expression Evaluation")
+(default = @code{tex^qComp}).
+
+When computing the rate control equation expression, besides the
+standard functions defined in the section "Expression Evaluation", the
+following functions are available
+ at table @var
+ at item bits2qp(bits)
+ at item qp2bits(qp)
+ at end table
+
+and following constants are available:
+ at table @var
+ at item PI
+ at item E
+ at item iTex
+ at item pTex
+ at item tex
+ at item mv
+ at item fCode
+ at item iCount
+ at item mcVar
+ at item var
+ at item isI
+ at item isP
+ at item isB
+ at item avgQP
+ at item qComp
+ at item avgIITex
+ at item avgPITex
+ at item avgPPTex
+ at item avgBPTex
+ at item avgTex
+ at end table
+
 @item -rc_override @var{override}
 rate control override for specific intervals
 @item -me_method @var{method}
@@ -684,74 +717,6 @@ directories, where @var{codec_name} is the name of the codec to which
 the preset file options will be applied. For example, if you select
 the video codec with @code{-vcodec libx264} and use @code{-vpre max},
 then it will search for the file @file{libx264-max.ffpreset}.
-
- at anchor{FFmpeg formula evaluator}
- at section FFmpeg formula evaluator
-
-When evaluating a rate control string, FFmpeg uses an internal formula
-evaluator.
-
-The following binary operators are available: @code{+}, @code{-},
- at code{*}, @code{/}, @code{^}.
-
-The following unary operators are available: @code{+}, @code{-},
- at code{(...)}.
-
-The following statements are available: @code{ld}, @code{st},
- at code{while}.
-
-The following functions are available:
- at table @var
- at item sinh(x)
- at item cosh(x)
- at item tanh(x)
- at item sin(x)
- at item cos(x)
- at item tan(x)
- at item atan(x)
- at item asin(x)
- at item acos(x)
- at item exp(x)
- at item log(x)
- at item abs(x)
- at item squish(x)
- at item gauss(x)
- at item mod(x, y)
- at item max(x, y)
- at item min(x, y)
- at item eq(x, y)
- at item gte(x, y)
- at item gt(x, y)
- at item lte(x, y)
- at item lt(x, y)
- at item bits2qp(bits)
- at item qp2bits(qp)
- at end table
-
-The following constants are available:
- at table @var
- at item PI
- at item E
- at item iTex
- at item pTex
- at item tex
- at item mv
- at item fCode
- at item iCount
- at item mcVar
- at item var
- at item isI
- at item isP
- at item isB
- at item avgQP
- at item qComp
- at item avgIITex
- at item avgPITex
- at item avgPPTex
- at item avgBPTex
- at item avgTex
- at end table
-
 @c man end
 
 @chapter Tips
@@ -960,6 +925,7 @@ options have to be specified immediately after the name of the output
 file to which you want to add them.
 @c man end EXAMPLES
 
+ at include eval.texi
 @include indevs.texi
 @include outdevs.texi
 @include protocols.texi
diff --git a/doc/ffplay-doc.texi b/doc/ffplay-doc.texi
index d761f13..07c8875 100644
--- a/doc/ffplay-doc.texi
+++ b/doc/ffplay-doc.texi
@@ -153,6 +153,7 @@ Seek to percentage in file corresponding to fraction of width.
 
 @c man end
 
+ at include eval.texi
 @include indevs.texi
 @include outdevs.texi
 @include protocols.texi
-- 
1.7.1