[FFmpeg-devel] [PATCH 16/16] doc/filters: document framesync options.

[Nicolas George]

Signed-off-by: Nicolas George <george at nsup.org>
---
 Changelog        |  2 ++
 doc/filters.texi | 76 +++++++++++++++++++++++++++++++++-----------------------
 2 files changed, 47 insertions(+), 31 deletions(-)

diff --git a/Changelog b/Changelog
index 78286e3606..d5ffa0a1f2 100644
--- a/Changelog
+++ b/Changelog
@@ -35,6 +35,8 @@ version <next>:
 - The order of options in filters is no longer considered stable. If
   long-term stability is necessary (i.e. for scripts), use named options
   (e.g. overlay=50:100 -> overlay=x=50:y=100).
+- Some video filters with several inputs now use a common set of options:
+  blend, libvmaf, lut3d, overlay, psnr, ssim.
 
 version 3.3:
 - CrystalHD decoder moved to new decode API
diff --git a/doc/filters.texi b/doc/filters.texi
index 470ffa60a1..5c7d48738f 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -316,6 +316,39 @@ See @code{ffmpeg -filters} to view which filters have timeline support.
 
 @c man end FILTERGRAPH DESCRIPTION
 
+ at anchor{framesync}
+ at chapter Options for filters with several inputs (framesync)
+ at c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
+
+Some filters with several inputs support a common set of options.
+These options can only be set by name, not with the short notation.
+
+ at table @option
+ at item eof_action
+The action to take when EOF is encountered on the secondary input; it accepts
+one of the following values:
+
+ at table @option
+ at item repeat
+Repeat the last frame (the default).
+ at item endall
+End both streams.
+ at item pass
+Pass the main input through.
+ at end table
+
+ at item shortest
+If set to 1, force the output to terminate when the shortest input
+terminates. Default value is 0.
+
+ at item repeatlast
+If set to 1, force the filter to draw the last overlay frame over the
+main input until the end of the stream. A value of 0 disables this
+behavior. Default value is 1.
+ at end table
+
+ at c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
+
 @chapter Audio Filters
 @c man begin AUDIO FILTERS
 
@@ -4937,17 +4970,10 @@ Value of pixel component at current location for first video frame (top layer).
 @item BOTTOM, B
 Value of pixel component at current location for second video frame (bottom layer).
 @end table
-
- at item shortest
-Force termination when the shortest input terminates. Default is
- at code{0}. This option is only defined for the @code{blend} filter.
-
- at item repeatlast
-Continue applying the last bottom frame after the end of the stream. A value of
- at code{0} disable the filter after the last frame of the bottom layer is reached.
-Default is @code{1}. This option is only defined for the @code{blend} filter.
 @end table
 
+The @code{blend} filter also supports the @ref{framesync} options.
+
 @subsection Examples
 
 @itemize
@@ -9745,6 +9771,8 @@ Enables computing ms_ssim along with vmaf.
 Set the pool method to be used for computing vmaf.
 @end table
 
+This filter also supports the @ref{framesync} options.
+
 For example:
 @example
 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
@@ -9826,6 +9854,8 @@ Interpolate values using a tetrahedron.
 @end table
 @end table
 
+This filter also supports the @ref{framesync} options.
+
 @section lumakey
 
 Turn certain luma values into transparency.
@@ -10854,19 +10884,6 @@ 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).
 
- at item eof_action
-The action to take when EOF is encountered on the secondary input; it accepts
-one of the following values:
-
- at table @option
- at item repeat
-Repeat the last frame (the default).
- at item endall
-End both streams.
- at item pass
-Pass the main input through.
- at end table
-
 @item eval
 Set when the expressions for @option{x}, and @option{y} are evaluated.
 
@@ -10882,10 +10899,6 @@ evaluate expressions for each incoming frame
 
 Default value is @samp{frame}.
 
- at 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.
 
@@ -10911,11 +10924,6 @@ automatically pick format
 @end table
 
 Default value is @samp{yuv420}.
-
- at item repeatlast
-If set to 1, force the filter to draw the last overlay frame over the
-main input until the end of the stream. A value of 0 disables this
-behavior. Default value is 1.
 @end table
 
 The @option{x}, and @option{y} expressions can contain the following
@@ -10952,6 +10960,8 @@ The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
 
 @end table
 
+This filter also supports the @ref{framesync} options.
+
 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}.
@@ -11829,6 +11839,8 @@ Requires stats_version >= 2. If this is set and stats_version < 2,
 the filter will return an error.
 @end table
 
+This filter also supports the @ref{framesync} options.
+
 The file printed if @var{stats_file} is selected, contains a sequence of
 key/value pairs of the form @var{key}:@var{value} for each compared
 couple of frames.
@@ -13582,6 +13594,8 @@ SSIM of the compared frames for the whole frame.
 Same as above but in dB representation.
 @end table
 
+This filter also supports the @ref{framesync} options.
+
 For example:
 @example
 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
-- 
2.13.2