README.rst
1A Vulkan layer to display information about the running application using an overlay.
2
3Building
4=======
5
6The overlay layer will be built if :code:`overlay` is passed as a :code:`vulkan-layers` argument. For example:
7
8.. code-block:: sh
9
10 meson -Dvulkan-layers=device-select,overlay builddir/
11 ninja -C builddir/
12 sudo ninja -C builddir/ install
13
14See `docs/install.rst <https://gitlab.freedesktop.org/mesa/mesa/-/blob/master/docs/install.rst>`__ for more information.
15
16Basic Usage
17=======
18
19Turn on the layer:
20
21.. code-block:: sh
22
23 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay /path/to/my_vulkan_app
24
25
26List the available statistics:
27
28.. code-block:: sh
29
30 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=help /path/to/my_vulkan_app
31
32
33Turn on some statistics:
34
35.. code-block:: sh
36
37 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics /path/to/my_vulkan_app
38
39Position the overlay:
40
41.. code-block:: sh
42
43 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics,position=top-right /path/to/my_vulkan_app
44
45Logging Statistics
46=======
47
48Log statistics to a file:
49
50.. code-block:: sh
51
52 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=output_file=/tmp/output.txt /path/to/my_vulkan_app
53
54Logging is enabled for the entire lifecycle of the process unless a control socket is specified (see below).
55
56**Note:** some statistics (e.g. :code:`frame_timing` and :code:`gpu_timing`) log values for the entire sample interval instead of per-frame.
57For these statistics, logging the :code:`frame` statistic allows one to compute per-frame statistics after capture.
58
59Log statistics to a file, controlling when such statistics will start to be captured:
60
61.. code-block:: sh
62
63 VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=output_file=/tmp/output.txt,control=mesa_overlay /path/to/my_vulkan_app
64
65The command above will open a Unix socket with the abstract path :code:`mesa_overlay`. When a control socket is specified,
66logging must be explicitly enabled through the control socket. :code:`mesa-overlay-control.py` provides a convenient CLI:
67
68.. code-block:: sh
69
70 mesa-overlay-control.py start-capture
71
72.. code-block:: sh
73
74 mesa-overlay-control.py stop-capture
75
76Direct Socket Control
77------
78
79The Unix socket may be used directly if needed. Once a client connects to the socket, the overlay layer will immediately
80send the following commands to the client:
81
82.. code-block:: sh
83
84 :MesaOverlayControlVersion=1;
85 :DeviceName=<device name>;
86 :MesaVersion=<mesa version>;
87
88The client connected to the overlay layer can enable statistics capturing by sending the command:
89
90.. code-block:: sh
91
92 :capture=1;
93
94And disable it by sending:
95
96.. code-block:: sh
97
98 :capture=0;
99
100.. _docs/install.rst: ../../docs/install.rst
101