[FFmpeg-cvslog] r25665 - in trunk: Makefile doc/eval.texi doc/ffmpeg-doc.texi doc/ffplay-doc.texi

[stefano]

Author: stefano
Date: Wed Nov  3 20:43:55 2010
New Revision: 25665

Log:
Add eval.texi file.

Added:
   trunk/doc/eval.texi
Modified:
   trunk/Makefile
   trunk/doc/ffmpeg-doc.texi
   trunk/doc/ffplay-doc.texi

Modified: trunk/Makefile
==============================================================================
--- trunk/Makefile	Wed Nov  3 19:13:09 2010	(r25664)
+++ trunk/Makefile	Wed Nov  3 20:43:55 2010	(r25665)
@@ -115,8 +115,8 @@ documentation: $(addprefix doc/, develop
 
 $(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

Added: trunk/doc/eval.texi
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/doc/eval.texi	Wed Nov  3 20:43:55 2010	(r25665)
@@ -0,0 +1,137 @@
+ at chapter Expression Evaluation
+ at c man begin EXPRESSION EVALUATION
+
+When evaluating an arithemetic 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}".
+ at 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{-},
+ 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} 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.
+ at end table
+
+Note that:
+
+ at code{*} works like AND
+
+ at code{+} works like OR
+
+thus
+ at example
+if A then B else C
+ at end example
+is equivalent to
+ at example
+A*B + not(A)*C
+ at end example
+
+When A evaluates to either 1 or 0, that is the same as
+ at example
+A*B + eq(A,0)*C
+ at 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.
+ 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

Modified: trunk/doc/ffmpeg-doc.texi
==============================================================================
--- trunk/doc/ffmpeg-doc.texi	Wed Nov  3 19:13:09 2010	(r25664)
+++ trunk/doc/ffmpeg-doc.texi	Wed Nov  3 20:43:55 2010	(r25665)
@@ -354,8 +354,39 @@ 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 the following constants are available:
+ at table @var
+ 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}
@@ -694,74 +725,6 @@ directories, where @var{codec_name} is t
 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
@@ -970,6 +933,7 @@ options have to be specified immediately
 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

Modified: trunk/doc/ffplay-doc.texi
==============================================================================
--- trunk/doc/ffplay-doc.texi	Wed Nov  3 19:13:09 2010	(r25664)
+++ trunk/doc/ffplay-doc.texi	Wed Nov  3 20:43:55 2010	(r25665)
@@ -153,6 +153,7 @@ Seek to percentage in file corresponding
 
 @c man end
 
+ at include eval.texi
 @include indevs.texi
 @include outdevs.texi
 @include protocols.texi