DOCS/options.rst DOCS/vo.rst: Update discussion of hwdec usage

The documentation's current discussion of hwdec usage is out of date,
and unnecessarily pessemistic when applied to modern hardware. The
reality is that modern APIs on modern hardware produce reasonable
results and there's no need to pretend otherwise. The current language
that tries to drive people away from using hwdecs at all leads to them
making bad choices when they do try to use it.

Let's also make it clearer that users should use vo=gpu with hwdecs
rather than vo=vaapi or vo=vdpau. Even the existing admonitions have
proven insufficient, so let's strengthen that language.

2 files changed, 99 insertions, 90 deletions

diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 12496faca4..717a58ccd2 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -1176,26 +1176,40 @@ Video
     Whether hardware decoding is actually done depends on the video codec. If
     hardware decoding is not possible, mpv will fall back on software decoding.
 
-    Hardware decoding is not enabled by default, because it is typically an
-    additional source of errors. It is worth using only if your CPU is too
-    slow to decode a specific video.
+    Hardware decoding is not enabled by default, to keep the out-of-the-box
+    configuration as reliable as possible. However, when using modern hardware,
+    hardware video decoding should work correctly, offering reduced CPU usage,
+    and possibly lower power consumption. On older systems, it may be necessary
+    to use hardware decoding due to insufficient CPU resources; and even on
+    modern systems, sufficiently complex content (eg: 4K60 AV1) may require it.
 
     .. note::
 
         Use the ``Ctrl+h`` shortcut to toggle hardware decoding at runtime. It
         toggles this option between ``auto`` and ``no``.
 
-        Always enabling HW decoding by putting it into the config file is
-        discouraged. If you use the Ubuntu package, delete ``/etc/mpv/mpv.conf``,
-        as the package tries to enable HW decoding by default by setting
-        ``hwdec=vaapi`` (which is less than ideal, and may even cause
-        sub-optimal wrappers to be used). Or at least change it to
-        ``hwdec=auto-safe``.
-
-    Use one of the auto modes if you want to enable hardware decoding.
-    Explicitly selecting the mode is mostly meant for testing and debugging.
-    It's a bad idea to put explicit selection into the config file if you
-    want thing to just keep working after updates and so on.
+        If you decide you want to use hardware decoding by default, the general
+        recommendation is to try out decoding with the command line option, and
+        prove to yourself that it works as desired for the content you care
+        about. After that, you can add it to your config file.
+
+        When testing, you should start by using ``hwdec=auto-safe`` as it will
+        limit itself to choosing from hwdecs that are actively supported by the
+        development team. If that doesn't result in working hardare decoding,
+        you can try ``hwdec=auto`` to have it attempt to load every possible
+        hwdec, but if ``auto-safe`` didn't work, you will probably need to know
+        exactly which hwdec matches your hardware and read up on that entry
+        below.
+
+        If ``auto-safe`` or ``auto`` produced the desired results, we recommend
+        just sticking with that and only setting a specific hwdec in your config
+        file if it is really necessary.
+
+        If you use the Ubuntu package, keep in mind that their
+        ``/etc/mpv/mpv.conf`` contains ``hwdec=vaapi``, which is less than
+        ideal as it may not be the right choice for your system, and it may end
+        up using an inefficient wrapper library under the covers. We recommend
+        removing this line or deleting the file altogether.
 
     .. note::
 
@@ -1210,8 +1224,7 @@ Video
           ``Ctrl+h`` default binding to enable it at runtime.
         - If you're not sure, but want hardware decoding always enabled by
           default, put ``hwdec=auto-safe`` into your ``mpv.conf``, and
-          acknowledge that this use case is not "really" supported and may cause
-          problems.
+          acknowledge that this may cause problems.
         - If you want to test available hardware decoding methods, pass
           ``--hwdec=auto --hwdec-codecs=all`` and look at the terminal output.
         - If you're a developer, or want to perform elaborate tests, you may
@@ -1224,26 +1237,32 @@ Video
     :yes:       exactly the same as ``auto``
     :auto-safe: enable any whitelisted hw decoder (see below)
     :auto-copy: enable best hw decoder with copy-back (see below)
-    :vdpau:     requires ``--vo=gpu`` with X11, or ``--vo=vdpau`` (Linux only)
-    :vdpau-copy: copies video back into system RAM (Linux with some GPUs only)
-    :vaapi:     requires ``--vo=gpu`` or ``--vo=vaapi`` (Linux only)
-    :vaapi-copy: copies video back into system RAM (Linux with some GPUs only)
+
+    Actively supported hwdecs:
+
+    :d3d11va:   requires ``--vo=gpu`` with ``--gpu-context=d3d11`` or
+                ``--gpu-context=angle`` (Windows 8+ only)
+    :d3d11va-copy: copies video back to system RAM (Windows 8+ only)
     :videotoolbox: requires ``--vo=gpu`` (macOS 10.8 and up),
                    or ``--vo=libmpv`` (iOS 9.0 and up)
     :videotoolbox-copy: copies video back into system RAM (macOS 10.8 or iOS 9.0 and up)
+    :vaapi:     requires ``--vo=gpu`` or ``--vo=vaapi`` (Linux only)
+    :vaapi-copy: copies video back into system RAM (Linux with some GPUs only)
+    :nvdec:     requires ``--vo=gpu`` (Any platform CUDA is available)
+    :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
+
+    Other hwdecs (only use if you know you have to):
+
     :dxva2:     requires ``--vo=gpu`` with ``--gpu-context=d3d11``,
                 ``--gpu-context=angle`` or ``--gpu-context=dxinterop``
                 (Windows only)
     :dxva2-copy: copies video back to system RAM (Windows only)
-    :d3d11va:   requires ``--vo=gpu`` with ``--gpu-context=d3d11`` or
-                ``--gpu-context=angle`` (Windows 8+ only)
-    :d3d11va-copy: copies video back to system RAM (Windows 8+ only)
+    :vdpau:     requires ``--vo=gpu`` with X11, or ``--vo=vdpau`` (Linux only)
+    :vdpau-copy: copies video back into system RAM (Linux with some GPUs only)
     :mediacodec: requires ``--vo=mediacodec_embed`` (Android only)
     :mediacodec-copy: copies video back to system RAM (Android only)
     :mmal:      requires ``--vo=gpu`` (Raspberry Pi only - default if available)
     :mmal-copy: copies video back to system RAM (Raspberry Pi only)
-    :nvdec:     requires ``--vo=gpu`` (Any platform CUDA is available)
-    :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
     :cuda:      requires ``--vo=gpu`` (Any platform CUDA is available)
     :cuda-copy: copies video back to system RAM (Any platform CUDA is available)
     :crystalhd: copies video back to system RAM (Any platform supported by hardware)
@@ -1280,7 +1299,7 @@ Video
 
     Because these copy the decoded video back to system RAM, they're often less
     efficient than the direct modes, and may not help too much over software
-    decoding.
+    decoding if you are short on CPU resources.
 
     .. note::
 
@@ -1309,7 +1328,12 @@ Video
         In theory, hardware decoding does not reduce video quality (at least
         for the codecs h264 and HEVC). However, due to restrictions in video
         output APIs, as well as bugs in the actual hardware decoders, there can
-        be some loss, or even blatantly incorrect results.
+        be some loss, or even blatantly incorrect results. This has largely
+        ceased to be a problem with modern hardware, but there is a lot of
+        hardware out there, so caveat emptor. Known problems are discussed
+        below, but the list cannot be considered exhaustive, as even hwdecs that
+        work well on certain hardware generations may be problematic on other
+        ones.
 
         In some cases, RGB conversion is forced, which means the RGB conversion
         is performed by the hardware decoding API, instead of the shaders
@@ -1325,10 +1349,6 @@ Video
         doesn't support 10 bit or HDR encodings, so these limitations are
         unlikely to be relevant.
 
-        ``vaapi`` and ``d3d11va`` are safe. Enabling deinterlacing (or simply
-        their respective post-processing filters) will possibly at least reduce
-        color quality by converting the output to a 8 bit format.
-
         ``dxva2`` is not safe. It appears to always use BT.601 for forced RGB
         conversion, but actual behavior depends on the GPU drivers. Some drivers
         appear to convert to limited range RGB, which gives a faded appearance.
@@ -1350,20 +1370,9 @@ Video
         conversion. It also discards the top left pixel of each frame for
         some reason.
 
-        All other methods, in particular the copy-back methods (like
-        ``dxva2-copy`` etc.) should hopefully be safe, although they can still
-        cause random decoding issues. At the very least, they shouldn't affect
-        the colors of the image.
-
-        In particular, ``auto-copy`` will only select "safe" modes
-        (although potentially slower than other methods), but there's still no
-        guarantee the chosen hardware decoder will actually work correctly.
-
-        In general, it's very strongly advised to avoid hardware decoding
-        unless **absolutely** necessary, i.e. if your CPU is insufficient to
-        decode the file in questions. If you run into any weird decoding issues,
-        frame glitches or discoloration, and you have ``--hwdec`` turned on,
-        the first thing you should try is disabling it.
+        If you run into any weird decoding issues, frame glitches or
+        discoloration, and you have ``--hwdec`` turned on, the first thing you
+        should try is disabling it.
 
 ``--gpu-hwdec-interop=<auto|all|no|name>``
     This option is for troubleshooting hwdec interop issues. Since it's a
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index 1843a56e4f..6207c7e9cb 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -21,6 +21,46 @@ in the list.
 
 Available video output drivers are:
 
+``gpu``
+    General purpose, customizable, GPU-accelerated video output driver. It
+    supports extended scaling methods, dithering, color management, custom
+    shaders, HDR, and more.
+
+    See `GPU renderer options`_ for options specific to this VO.
+
+    By default, it tries to use fast and fail-safe settings. Use the
+    ``gpu-hq`` profile to use this driver with defaults set to high quality
+    rendering. The profile can be applied with ``--profile=gpu-hq`` and its
+    contents can be viewed with ``--show-profile=gpu-hq``.
+
+    This VO abstracts over several possible graphics APIs and windowing
+    contexts, which can be influenced using the ``--gpu-api`` and
+    ``--gpu-context`` options.
+
+    Hardware decoding over OpenGL-interop is supported to some degree. Note
+    that in this mode, some corner case might not be gracefully handled, and
+    color space conversion and chroma upsampling is generally in the hand of
+    the hardware decoder APIs.
+
+    ``gpu`` makes use of FBOs by default. Sometimes you can achieve better
+    quality or performance by changing the ``--fbo-format`` option to
+    ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not
+    accepting ``rgb16``, Mesa sometimes not being compiled with float texture
+    support, and some macOS setups being very slow with ``rgb16`` but fast
+    with ``rgb32f``. If you have problems, you can also try enabling the
+    ``--gpu-dumb-mode=yes`` option.
+
+``gpu-next``
+    Experimental video renderer based on ``libplacebo``. This supports almost
+    the same set of features as ``--vo=gpu``. See `GPU renderer options`_ for a
+    list.
+
+    Should generally be faster and higher quality, but some features may still
+    be missing or misbehave. Expect (and report!) bugs. See here for a list of
+    known differences and bugs:
+
+    https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
+
 ``xv`` (X11 only)
     Uses the XVideo extension to enable hardware-accelerated display. This is
     the most compatible VO on X, but may be low-quality, and has issues with
@@ -78,7 +118,9 @@ Available video output drivers are:
 
 ``vdpau`` (X11 only)
     Uses the VDPAU interface to display and optionally also decode video.
-    Hardware decoding is used with ``--hwdec=vdpau``.
+    Hardware decoding is used with ``--hwdec=vdpau``. Note that there is
+    absolutely no reason to use this, other than compatibility. We strongly
+    recommend that you use ``--vo=gpu`` with ``--hwdec=nvdec`` instead.
 
     .. note::
 
@@ -228,46 +270,6 @@ Available video output drivers are:
     ``--vo-direct3d-exact-backbuffer``
         Always resize the backbuffer to window size.
 
-``gpu``
-    General purpose, customizable, GPU-accelerated video output driver. It
-    supports extended scaling methods, dithering, color management, custom
-    shaders, HDR, and more.
-
-    See `GPU renderer options`_ for options specific to this VO.
-
-    By default, it tries to use fast and fail-safe settings. Use the
-    ``gpu-hq`` profile to use this driver with defaults set to high quality
-    rendering. The profile can be applied with ``--profile=gpu-hq`` and its
-    contents can be viewed with ``--show-profile=gpu-hq``.
-
-    This VO abstracts over several possible graphics APIs and windowing
-    contexts, which can be influenced using the ``--gpu-api`` and
-    ``--gpu-context`` options.
-
-    Hardware decoding over OpenGL-interop is supported to some degree. Note
-    that in this mode, some corner case might not be gracefully handled, and
-    color space conversion and chroma upsampling is generally in the hand of
-    the hardware decoder APIs.
-
-    ``gpu`` makes use of FBOs by default. Sometimes you can achieve better
-    quality or performance by changing the ``--fbo-format`` option to
-    ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not
-    accepting ``rgb16``, Mesa sometimes not being compiled with float texture
-    support, and some macOS setups being very slow with ``rgb16`` but fast
-    with ``rgb32f``. If you have problems, you can also try enabling the
-    ``--gpu-dumb-mode=yes`` option.
-
-``gpu-next``
-    Experimental video renderer based on ``libplacebo``. This supports almost
-    the same set of features as ``--vo=gpu``. See `GPU renderer options`_ for a
-    list.
-
-    Should generally be faster and higher quality, but some features may still
-    be missing or misbehave. Expect (and report!) bugs. See here for a list of
-    known differences and bugs:
-
-    https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
-
 ``sdl``
     SDL 2.0+ Render video output driver, depending on system with or without
     hardware acceleration. Should work on all platforms supported by SDL 2.0.
@@ -287,10 +289,8 @@ Available video output drivers are:
 ``vaapi``
     Intel VA API video output driver with support for hardware decoding. Note
     that there is absolutely no reason to use this, other than compatibility.
-    This is low quality, and has issues with OSD.
-
-    .. note:: This driver is for compatibility with crappy systems. You can
-              use vaapi hardware decoding with ``--vo=gpu`` too.
+    This is low quality, and has issues with OSD. We strongly recommend that
+    you use ``--vo=gpu`` with ``--hwdec=vaapi`` instead.
 
     The following global options are supported by this video output: