manpage: update documentation for smoothmotion

Hopefully, this will really clear up how the thing is supposed to work
(and that it's not SVP, nor MVTools).

I also removed instances of the word "interpolation", since that's a
term that's easily misleading.

Finally, I expanded on smoothmotion-threshold since the purpose/meaning
was a bit confusing.

1 files changed, 27 insertions, 8 deletions

diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index 1fa23f02cd..e1375a8a71 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -611,16 +611,27 @@ Available video output drivers are:
         See ``--osd-color`` option how colors are defined.
 
     ``smoothmotion``
-        Use frame interpolation to reduce stuttering caused by mismatches in
-        video fps and display refresh rate.
+        Reduce stuttering caused by mismatches in video fps and display
+        refresh rate (also known as judder).
 
-        Instead of drawing each frame exactly once, smoothmotion redraws the
-        the OpenGL scene at the display refresh rate. If a vsync is detected
-        to be the one when a frame changes to the next, a linear interpolation
-        of the previous frame with next is shown instead.
+        Instead of drawing source frames for variable durations, smoothmotion
+        will blend frames that overlap the transition between two frames in
+        the source material.
 
-        This means that displaying a 1fps video on a 60hz monitor will blend
-        at most during 1 vsync for each second of playback.
+        For example, a 24 Hz clip played back on a 60 Hz display would normally
+        result in a pattern like this::
+
+            A A A B B C C C D D E E E F F
+
+        which has different lengths, alternating between 3 and 2. This
+        difference in frame duration is what causes judder.
+
+        With smoothmotion enabled, the pattern changes to::
+
+            A A A+B B B C C C+D D D E E E+F F F
+
+        where A+B is a blend of A and B. In this pattern, each frame gets a
+        (consistent) duration of roughly 2.5 - resulting in smooth motion.
 
         GPU drivers or compositing window managers overriding vsync behavior
         can lead to bad results. If the framerate is close to or over the
@@ -633,6 +644,14 @@ Available video output drivers are:
         Mix threshold at which interpolation is skipped (default: 0.0 – never
         skip).
 
+        For example, with a ``smoothmotion-threshold`` of 0.1, if the
+        smoothmotion algorithm would try to blend two frames by a ratio of
+        95% A + 5% B, it would simply display A instead. (Since the
+        distance, 0.05, is lower than the threshold)
+
+        Setting this to 0.5 would be similar to disabling smoothmotion
+        completely, since it would always just display the nearest frame.
+
 ``opengl-hq``
     Same as ``opengl``, but with default settings for high quality rendering.