diff --git a/Makefile b/Makefile index b81b65567d..e9d98545a7 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 0000000000..c26893d1bd --- /dev/null +++ b/doc/eval.texi @@ -0,0 +1,137 @@ +@chapter Expression Evaluation +@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}". +@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) +@item cosh(x) +@item tanh(x) +@item sin(x) +@item cos(x) +@item tan(x) +@item atan(x) +@item asin(x) +@item acos(x) +@item exp(x) +@item log(x) +@item abs(x) +@item squish(x) +@item gauss(x) +@item mod(x, y) +@item max(x, 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) +@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. + +@item ld(var) +Allow to load the value of the internal variable with number +@var{var}, which was previosly 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. +@end table + +Note that: + +@code{*} works like AND + +@code{+} works like OR + +thus +@example +if A then B else C +@end example +is equivalent to +@example +A*B + not(A)*C +@end example + +When A evaluates to either 1 or 0, that is the same as +@example +A*B + eq(A,0)*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 diff --git a/doc/ffmpeg-doc.texi b/doc/ffmpeg-doc.texi index eb7c8fdd80..4d707ea567 100644 --- a/doc/ffmpeg-doc.texi +++ b/doc/ffmpeg-doc.texi @@ -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: +@table @var +@item bits2qp(bits) +@item qp2bits(qp) +@end table + +and the following constants are available: +@table @var +@item iTex +@item pTex +@item tex +@item mv +@item fCode +@item iCount +@item mcVar +@item var +@item isI +@item isP +@item isB +@item avgQP +@item qComp +@item avgIITex +@item avgPITex +@item avgPPTex +@item avgBPTex +@item avgTex +@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 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}. - -@anchor{FFmpeg formula evaluator} -@section FFmpeg formula evaluator - -When evaluating a rate control string, FFmpeg uses an internal formula -evaluator. - -The following binary operators are available: @code{+}, @code{-}, -@code{*}, @code{/}, @code{^}. - -The following unary operators are available: @code{+}, @code{-}, -@code{(...)}. - -The following statements are available: @code{ld}, @code{st}, -@code{while}. - -The following functions are available: -@table @var -@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 acos(x) -@item exp(x) -@item log(x) -@item abs(x) -@item squish(x) -@item gauss(x) -@item mod(x, y) -@item max(x, 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) -@item bits2qp(bits) -@item qp2bits(qp) -@end table - -The following constants are available: -@table @var -@item PI -@item E -@item iTex -@item pTex -@item tex -@item mv -@item fCode -@item iCount -@item mcVar -@item var -@item isI -@item isP -@item isB -@item avgQP -@item qComp -@item avgIITex -@item avgPITex -@item avgPPTex -@item avgBPTex -@item avgTex -@end table - @c man end @chapter Tips @@ -970,6 +933,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 +@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 d761f13a3b..07c887565f 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 +@include eval.texi @include indevs.texi @include outdevs.texi @include protocols.texi