man: update documentation related to screenshots

3 files changed, 97 insertions, 16 deletions

diff --git a/DOCS/man/en/mplayer.rst b/DOCS/man/en/mplayer.rst
index 43fb2a47e5..617799bf9f 100644
--- a/DOCS/man/en/mplayer.rst
+++ b/DOCS/man/en/mplayer.rst
@@ -408,6 +408,28 @@ OPTIONS
 
 .. include:: vf.rst
 
+Taking screenshots
+==================
+
+Screenshots of the currently played file can be taken using the 'screenshot'
+slave mode command, which is by default bound to the ``s`` key. Files named
+``shotNNNN.png`` will be saved in the working directory, using the first
+available number - no files will be overwritten.
+
+A screenshot will usually contain the unscaled video contents at the end of the
+video filter chain. Some video output drivers will include subtitles and OSD in
+the video frame as well - this is because of technical restrictions.
+
+The ``screenshot`` video filter is normally not required when using a
+recommended GUI video output driver. The ``screenshot`` filter will be attempted
+to be used if the video output doesn't support screenshots. Note that taking
+screenshots with the video filter is not instant: the screenshot will be only
+saved when the next video frame is displayed. This means attempting to take a
+screenshot while the player is paused will do nothing, until the user unpauses
+or seeks. Also, the screenshot filter is not compatible with hardware decoding,
+and actually will cause initialization failure when use with hardware decodingis
+attempted. Using the ``screenshot`` video filter is not recommended for these
+reasons.
 
 ENVIRONMENT VARIABLES
 =====================
diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst
index 9e71658963..2f507f98f2 100644
--- a/DOCS/man/en/options.rst
+++ b/DOCS/man/en/options.rst
@@ -1663,6 +1663,71 @@
     Seek to byte position. Useful for playback from CD-ROM images or VOB files
     with junk at the beginning. See also ``--ss``.
 
+--screenshot-filetype=<type>
+    Set the image file type used for saving screenshots.
+
+    Available choices:
+
+    :png:   PNG (default)
+    :jpg:   JPEG
+    :jpeg:  JPEG (same as jpg, but with .jpeg file ending)
+
+--screenshot-jpeg-quality=<0-100>
+    Set the JPEG quality level. Higher means better quality. The default is 85.
+
+--screenshot-png-compression=<0-9>
+    Set the PNG compression level. Higher means better compression. This will
+    affect the file size of the written screenshot file, and the time it takes
+    to write a screenshot. Too high compression might occupy enough CPU time to
+    interrupt playback. The default is 7.
+
+--screenshot-template=<template>
+    Specify the filename template used to save screenshots. The template
+    specifies the filename without file extension, and can contain format
+    specifiers, which will be substituted when taking a screeshot.
+    By default the template is ``shot%n``, which results in filenames like
+    ``shot0012.png`` for example.
+
+    The template can start with a relative or absolute path, in order to
+    specify a directory location where screenshots should be saved.
+
+    If the final screenshot filename points to an already existing file, the
+    file won't be overwritten. The screenshot will either not be saved, or if
+    the template contains ``%n``, saved using different, newly generated
+    filename.
+
+    Allowed format specifiers:
+
+    ``%nX``
+        A sequence number, padded with zeros to length X. E.g. passing the
+        format ``%n4`` will yield ``0012`` on the 12th screenshot. The number is
+        incremented every time a screenshot is taken, or if the file already
+        exists. The length ``X`` must be in the range 0-9.
+    ``%f``
+        Filename of the currently played video.
+    ``%F``
+        Same as ``%f``, but strip the file extension, including the dot.
+    ``%p``
+        Current playback time, in the same format as used in the OSD. The
+        result is a string of the form "HH:MM:SS". For example, if the video is
+        at the time position 5 minutes and 34 seconds, ``%p`` will be replaced
+        with "00:05:34".
+    ``%P``
+        Similar to ``%p``, but extended with the playback time in milliseconds.
+        It is formatted as "HH:MM:SS.mmm", with "mmm" being the millisecond
+        part of the playback time. (Note that this is a simple way for getting
+        unique per-frame timestamps. Frame numbers would be more intuitive, but
+        are not easily implementable, because container formats usually use
+        time stamps for identifying frames.)
+    ``%tX``
+        Specify the current local date/time using he format ``X``. This format
+        specifier uses the UNIX ``strftime()`` function internally, and inserts
+        the result of passing "%X" to ``strftime``. For example, ``%tm`` will
+        insert the number of the current month as number. You have to use
+        multiple ``%tX`` specifiers to build a full date/time string.
+    ``%%``
+        Replaced with the ``%`` character itself.
+
 --screenh=<pixels>
     Specify the screen height for video output drivers which do not know the
     screen resolution like fbdev, x11 and TV-out.
diff --git a/DOCS/man/en/vf.rst b/DOCS/man/en/vf.rst
index cf5b8386b9..56bb32571a 100644
--- a/DOCS/man/en/vf.rst
+++ b/DOCS/man/en/vf.rst
@@ -1297,28 +1297,22 @@ remove-logo=/path/to/logo_bitmap_file_name.pgm
         [path] + filename of the filter image.
 
 screenshot
-    Allows acquiring screenshots of the movie using slave mode commands that
-    can be bound to keypresses. See the slave mode documentation and the
-    ``INTERACTIVE CONTROL`` section for details. Files named ``shotNNNN.png``
-    will be saved in the working directory, using the first available number -
-    no files will be overwritten. The filter has no overhead when not used. It
-    does however break playback in some cases, especially VDPAU hardware
-    decoding is incompatible with the filter. Thus it is not completely safe to
-    add the filter to default configuration "just in case you might want to
-    take screenshots". Make sure that the screenshot filter is added after all
-    other filters whose effect you want to record on the saved image. E.g. it
-    should be the last filter if you want to have an exact screenshot of what
-    you see on the monitor.
+    Optional filter for screenshot support. This is only needed if the video
+    output doesn't provide working direct screenshot support. Note that it is
+    not always safe to insert this filter by default. See the
+    ``Taking screenshots`` section for details.
 
 ass
     Moves SSA/ASS subtitle rendering to an arbitrary point in the filter
-    chain. See the ``--ass`` option.
+    chain, or force subtitle rendering in the video filter as opposed to using
+    video output EOSD support. See the ``--ass`` option.
 
     *EXAMPLE*:
 
-    ``--vf=ass,screenshot``
-        Moves SSA/ASS rendering before the screenshot filter. Screenshots
-        taken this way will contain subtitles.
+    ``--vf=ass,eq``
+        Moves SSA/ASS rendering before the eq filter. This will put both
+        subtitle colors and video under the influence of the video equalizer
+        settings.
 
 blackframe[=amount:threshold]
     Detect frames that are (almost) completely black. Can be useful to detect