vo_gpu: add --gamut-mapping-mode

Merge --gamut-clipping and --gamut-warning into a single option,
--gamut-mapping-mode, better corresponding to the new vo_gpu_next APIs
and allowing us to easily extend this option as new modes are added in
the future.

2 files changed, 19 insertions, 19 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 2c59f0f6b5..75516627df 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -35,6 +35,7 @@ Interface changes
     - add `--tone-mapping-crosstalk`
     - add `--tone-mapping` options `auto`, `spline` and `bt.2446a`
     - add `--inverse-tone-mapping`
+    - add `--gamut-mapping-mode`, replacing `--gamut-clipping` and `--gamut-warning`
  --- mpv 0.34.0 ---
     - deprecate selecting by card number with `--drm-connector`, add
       `--drm-device` which can be used instead
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 6742ec1a6c..bd2b9be470 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -6385,6 +6385,24 @@ them.
     it too high will make dark scenes appear unnaturally bright. (``-vo=gpu``
     only)
 
+``--gamut-mapping-mode``
+    Specifies the algorithm used for reducing the gamut of images for the
+    target display, after any tone mapping is done.
+
+    auto
+        Choose the best mode automatically. (Default)
+    clip
+        Hard-clip to the gamut (per-channel).
+    warn
+        Simply highlight out-of-gamut pixels.
+    desaturate
+        Chromatically desaturate out-of-gamut colors towards white.
+    darken
+        Linearly darken the entire image, then clip to the color volume. Unlike
+        ``clip``, this does not destroy detail in saturated regions, but comes
+        at the cost of sometimes significantly lowering output brightness.
+        (``--vo=gpu-next`` only)
+
 ``--hdr-compute-peak=<auto|yes|no>``
     Compute the HDR peak and frame average brightness per-frame instead of
     relying on tagged metadata. These values are averaged over local regions as
@@ -6448,25 +6466,6 @@ them.
     desaturated. The default of 1.5 provides a reasonable balance.  Decreasing
     this exponent makes the curve more aggressive.
 
-``--gamut-warning``
-    If enabled, mpv will mark all clipped/out-of-gamut pixels that exceed a
-    given threshold (currently hard-coded to 101%). The affected pixels will be
-    inverted to make them stand out. Note: This option applies after the
-    effects of all of mpv's color space transformation / tone mapping options,
-    so it's a good idea to combine this with ``--tone-mapping=clip`` and use
-    ``--target-prim`` to set the gamut to simulate. For example,
-    ``--target-prim=bt.709`` would make mpv highlight all pixels that exceed the
-    gamut of a standard gamut (sRGB) display. This option also does not work
-    well with ICC profiles, since the 3DLUTs are always generated against the
-    source color space and have chromatically-accurate clipping built in.
-
-``--gamut-clipping``
-    If enabled (default: yes), mpv will colorimetrically clip out-of-gamut
-    colors by desaturating them (preserving luma), rather than hard-clipping
-    each component individually. This should make playback of wide gamut
-    content on typical (standard gamut) monitors look much more aesthetically
-    pleasing and less blown-out.
-
 ``--use-embedded-icc-profile``
     Load the embedded ICC profile contained in media files such as PNG images.
     (Default: yes). Note that this option only works when also using a display