lavfi/overlay: add dynamic expression evaluation support

Add support for dynamic x, y expressions evaluation.

Also add support for an evaluation mode which allows to disable per-frame
evaluation, so that there is no speedloss in case the expression does not
depend on frame variables.

1 files changed, 62 insertions, 17 deletions

diff --git a/doc/filters.texi b/doc/filters.texi
index 512f943d83..4668b7fc53 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -4260,26 +4260,31 @@ arguments are interpreted according to the syntax @var{x}:@var{y}.
 A description of the accepted options follows.
 
 @table @option
-@item x, y
+@item x
+@item y
 Set the expression for the x and y coordinates of the overlayed video
-on the main video. Default value is 0.
-
-The @var{x} and @var{y} expressions can contain the following
-parameters:
-@table @option
-@item main_w, main_h
-main input width and height
+on the main video. Default value is "0" for both expressions. In case
+the expression is invalid, it is set to a huge value (meaning that the
+overlay will not be displayed within the output visible area).
 
-@item W, H
-same as @var{main_w} and @var{main_h}
+@item eval
+Set when the expressions for @option{x} and @option{y} are evaluated.
 
-@item overlay_w, overlay_h
-overlay input width and height
+It accepts the following values:
+@table @samp
+@item init
+only evaluate expressions once during the filter initialization
 
-@item w, h
-same as @var{overlay_w} and @var{overlay_h}
+@item frame
+evaluate expressions for each incoming frame
 @end table
 
+Default value is @samp{frame}.
+
+@item shortest
+If set to 1, force the output to terminate when the shortest input
+terminates. Default value is 0.
+
 @item format
 Set the format for the output video.
 
@@ -4301,12 +4306,45 @@ Default value is @samp{yuv420}.
 If set to 1, force the filter to accept inputs in the RGB
 color space. Default value is 0. This option is deprecated, use
 @option{format} instead.
+@end table
 
-@item shortest
-If set to 1, force the output to terminate when the shortest input
-terminates. Default value is 0.
+The @option{x}, and @option{y} expressions can contain the following
+parameters.
+
+@table @option
+@item main_w, W
+@item main_h, H
+main input width and height
+
+@item overlay_w, w
+@item overlay_h, h
+overlay input width and height
+
+@item x
+@item y
+the computed values for @var{x} and @var{y}. They are evaluated for
+each new frame.
+
+@item hsub
+@item vsub
+horizontal and vertical chroma subsample values of the output
+format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
+@var{vsub} is 1.
+
+@item n
+the number of input frame, starting from 0
+
+@item pos
+the position in the file of the input frame, NAN if unknown
+
+@item t
+timestamp expressed in seconds, NAN if the input timestamp is unknown
 @end table
 
+Note that the @var{n}, @var{pos}, @var{t} variables are available only
+when evaluation is done @emph{per frame}, and will evaluate to NAN
+when @option{eval} is set to @samp{init}.
+
 Be aware that frames are taken from each input video in timestamp
 order, hence, if their initial timestamps differ, it is a a good idea
 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
@@ -4365,6 +4403,13 @@ ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
 @end example
 
 @item
+Make a sliding overlay appearing from the left to the right top part of the
+screen starting since time 2:
+@example
+overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
+@end example
+
+@item
 Compose output by putting two input videos side to side:
 @example
 ffmpeg -i left.avi -i right.avi -filter_complex "