command: add better runtime filter toggling method

Basically, see the example in input.rst.

This is better than the "old" vf-toggle method, because it doesn't
require the user to duplicate the filter string in mpv.conf and
input.conf.

Some aspects of this changes are untested, so enjoy your alpha testing.

1 files changed, 13 insertions, 0 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 9e578867cf..d252bb93a1 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -452,6 +452,9 @@ Input Commands that are Possibly Subject to Change
         (If several filters are passed to the command, this is done for
         each filter.)
 
+        A special variant is combining this with labels, and using ``@name:!``
+        as filter entry. This toggles the enable/disable flag.
+
     del
         Remove the given filters from the video chain. Unlike in the other
         cases, the second parameter is a comma separated list of filter names
@@ -487,6 +490,16 @@ Input Commands that are Possibly Subject to Change
         - ``b vf set ""`` remove all video filters on ``b``
         - ``c vf toggle lavfi=gradfun`` toggle debanding on ``c``
 
+    .. admonition:: Example how to toggle disabled filters at runtime
+
+        - Add something ``vf-add=@deband:!lavfi=[gradfun]`` to ``mpv.conf``. The
+          ``@deband:`` is the label, and ``deband`` is an arbitrary, user-given
+          name for this filter entry. The ``!`` before the filter name disables
+          the filter by default. Everything after this is the normal filter name
+          and the filter parameters.
+        - Add ``a vf toggle @deband:!`` to ``input.conf``. This toggles the
+          "disabled" flag for the filter identified with ``deband``.
+
 ``cycle-values ["!reverse"] <property> "<value1>" "<value2>" ...``
     Cycle through a list of values. Each invocation of the command will set the
     given property to the next value in the list. The command maintains an