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_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_overlay /path/to/my_vulkan_app 24 25 26List the available statistics: 27 28.. code-block:: sh 29 30 VK_LOADER_LAYERS_ENABLE=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_LOADER_LAYERS_ENABLE=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_LOADER_LAYERS_ENABLE=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_LOADER_LAYERS_ENABLE=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_LOADER_LAYERS_ENABLE=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