path: root/DOCS
diff options
authorwm4 <wm4@nowhere>2016-09-17 20:48:22 +0200
committerwm4 <wm4@nowhere>2016-09-17 20:48:22 +0200
commita3e8ff624c8adf3b18dddea0fdede7b7fa8c4eb1 (patch)
treeb5ed419e0ea57138e584e560c17cecb207d49364 /DOCS
parent2d34171bec55294375e57f8bea86e2dee153d2cc (diff)
options: take care of propertly updating options on runtime changes
All option write accesses are now put through the property interface, which means runtime option value verification and runtime updates are applied. This is done even for command line arguments and config files. This has many subtle and not-so-subtle consequences. The potential for unintended and intended subtle or not-subtle behavior changes is very large. Architecturally, this is us literally jumping through hoops. It really should work the other way around, with options being able to have callbacks for value verification and applying runtime updates. But this would require rewriting the entirety of command.c. This change is more practical, and if anything will at least allow incremental changes. Some options are too incompatible for this to work - these are excluded with an explicit blacklist. This change fixes many issues caused by the mismatch between properties and options. For example, this fixes #3281.
Diffstat (limited to 'DOCS')
2 files changed, 17 insertions, 0 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 609f6498a4..6774170aee 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -20,6 +20,15 @@ Interface changes
--- mpv 0.21.0 ---
+ - setting certain options at runtime will now take care of updating them
+ property (see for example issue #3281). On the other hand, it will also
+ do runtime verification and reject option changes that do not work
+ (example: setting the "vf" option to a filter during playback, which fails
+ to initialize - the option value will remain at its old value). In general,
+ "set name value" should be mostly equivalent to "set options/name value"
+ in cases where the "name" property is not deprecated and "options/name"
+ exists - deviations from this are either bugs, or documented as caveats
+ in the "Inconsistencies between options and properties" manpage section.
- deprecate _all_ --vo and --ao suboptions. Generally, all suboptions are
replaced by global options, which do exactly the same. For example,
"--vo=opengl:scale=nearest" turns into "--scale=nearest". In some cases,
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index cc81e6a125..3588d66599 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -2066,11 +2066,15 @@ caveats with some properties (due to historical reasons):
allows setting any track ID, and which tracks to enable is chosen at
loading time.)
+ Option changes at runtime are affected by this as well.
While video is active, this behaves differently from the option. It will
never return the ``auto`` value (but the state as observed by the video
chain). You cannot set ``auto`` either.
+ Option changes at runtime are affected by this as well.
While video is active, always returns the effective aspect ratio.
@@ -2089,11 +2093,15 @@ caveats with some properties (due to historical reasons):
same way. Also, there are no ``vf-add`` etc. properties, but you can use
the ``vf``/``af`` group of commands to achieve the same.
+ Option changes at runtime are affected by this as well.
While playback is *not* active, the property behaves like the option, and
you can set a chapter range. While playback is active, you can set only
the current chapter (to which the player will seek immediately).
+ Option changes at runtime are affected by this as well.
When set as option, the maximum (set by ``--volume-max``) is not checked,
while when set as property, the maximum is enforced.