path: root/DOCS
diff options
authorNiklas Haas <>2017-06-29 17:00:06 +0200
committerNiklas Haas <>2017-07-01 00:58:27 +0200
commitdd78cc6fe72a3c5fadb00563cd47cc70b68f50fb (patch)
tree5050af3285b623499d0a2b06fa0ebb8d040b7cc9 /DOCS
parentf003d8ea367f247e3ff49b672003817a0c3cdb30 (diff)
vo_opengl: refactor vo performance subsystem
This replaces `vo-performance` by `vo-passes`, bringing with it a number of changes and improvements: 1. mpv users can now introspect the vo_opengl passes, which is something that has been requested multiple times. 2. performance data is now measured per-pass, which helps both development and debugging. 3. since adding more passes is cheap, we can now report information for more passes (e.g. the blit pass, and the osd pass). Note: we also switch to nanosecond scale, to be able to measure these passes better. 4. `--user-shaders` authors can now describe their own passes, helping users both identify which user shaders are active at any given time as well as helping shader authors identify performance issues. 5. the timing data per pass is now exported as a full list of samples, so projects like Argon-/mpv-stats can immediately read out all of the samples and render a graph without having to manually poll this option constantly. Due to gl_timer's design being complicated (directly reading performance data would block, so we delay the actual read-back until the next _start command), it's vital not to conflate different passes that might be doing different things from one frame to another. To accomplish this, the actual timers are stored as part of the gl_shader_cache's sc_entry, which makes them unique for that exact shader. Starting and stopping the time measurement is easy to unify with the gl_sc architecture, because the existing API already relies on a "generate, render, reset" flow, so we can just put timer_start and timer_stop in sc_generate and sc_reset, respectively. The ugliest thing about this code is that due to the need to keep pass information relatively stable in between frames, we need to distinguish between "new" and "redrawn" frames, which bloats the code somewhat and also feels hacky and vo_opengl-specific. (But then again, this entire thing is vo_opengl-specific)
Diffstat (limited to 'DOCS')
3 files changed, 51 insertions, 24 deletions
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index a678e0d528..9bdc251eaf 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -46,6 +46,8 @@ Interface changes
--audio-file-paths => --audio-file-path
--sub-paths => --sub-file-path
--opengl-shaders => --opengl-shader
+ - remove property `vo-performance`, and add `vo-passes` as a more general
+ replacement
--- mpv 0.25.0 ---
- remove opengl-cb dxva2 dummy hwdec interop
(see git "vo_opengl: remove dxva2 dummy hwdec backend")
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index ef3ceb1fb5..befcb5c00a 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1883,32 +1883,43 @@ Property list
whether the video window is visible. If the ``--force-window`` option is
used, this is usually always returns ``yes``.
- Some video output performance metrics. Not implemented by all VOs. This has
- a number of sup-properties, of the form ``vo-performance/<metric>-<value>``,
- all of them in milliseconds.
+ Contains introspection about the VO's active render passes and their
+ execution times. Not implemented by all VOs.
- ``<metric>`` refers to one of:
+ This is further subdivided into two frame types, ``vo-passes/fresh`` for
+ fresh frames (which have to be uploaded, scaled, etc.) and
+ ``vo-passes/redraw`` for redrawn frames (which only have to be re-painted).
+ The number of passes for any given subtype can change from frame to frame,
+ and should not be relied upon.
- ``upload``
- Time needed to make the frame available to the GPU (if necessary).
- ``render``
- Time needed to perform all necessary video postprocessing and rendering
- passes (if necessary).
- ``present``
- Time needed to present a rendered frame on-screen.
+ Each frame type has a number of further sub-properties. Replace ``TYPE``
+ with the frame type, ``N`` with the 0-based pass index, and ``M`` with the
+ 0-based sample index.
- When a step is unnecessary or skipped, it will have the value 0.
+ ``vo-passes/TYPE/count``
+ Number of passes.
- ``<value>`` refers to one of:
+ ``vo-passes/TYPE/N/desc``
+ Human-friendy description of the pass.
- ``last``
- Last measured value.
- ``avg``
- Average over a fixed number of past samples. (The exact timeframe
- varies, but it should generally be a handful of seconds)
- ``peak``
- The peak (highest value) within this averaging range.
+ ``vo-passes/TYPE/N/last``
+ Last measured execution time, in nanoseconds.
+ ``vo-passes/TYPE/N/avg``
+ Average execution time of this pass, in nanoseconds. The exact
+ timeframe varies, but it should generally be a handful of seconds.
+ ``vo-passes/TYPE/N/peak``
+ The peak execution time (highest value) within this averaging range, in
+ nanoseconds.
+ ``vo-passes/TYPE/N/count``
+ The number of samples for this pass.
+ ``vo-passes/TYPE/N/samples/M``
+ The raw execution time of a specific sample for this pass, in
+ nanoseconds.
When querying the property with the client API using ``MPV_FORMAT_NODE``,
or with Lua ``mp.get_property_native``, this will return a mpv_node with
@@ -1917,9 +1928,18 @@ Property list
- "<metric>-<value>" MPV_FORMAT_INT64
- (One entry for each ``<metric>`` and ``<value>`` combination)
+ "last" MPV_FORMAT_INT64
+ "avg" MPV_FORMAT_INT64
+ "peak" MPV_FORMAT_INT64
+ "count" MPV_FORMAT_INT64
+ Note that directly accessing this structure via subkeys is not supported,
+ the only access is through aforementioned ``MPV_FORMAT_NODE``.
``video-bitrate``, ``audio-bitrate``, ``sub-bitrate``
Bitrate values calculated on the packet level. This works by dividing the
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 5b2e838243..c1fc4d96dc 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -4195,6 +4195,11 @@ The following video options are currently all specific to ``--vo=opengl`` and
Each block of metadata, along with the non-metadata lines after it, defines
a single pass. Each pass can set the following metadata:
+ DESC <title>
+ User-friendly description of the pass. This is the name used when
+ representing this shader in the list of passes for property
+ `vo-passes`.
HOOK <name> (required)
The texture which to hook into. May occur multiple times within a
metadata block, up to a predetermined limit. See below for a list of