vulkan/overlay: revise and reformat README
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/14784>
This commit is contained in:
parent
9eb1592e57
commit
7483c40ba0
|
@ -1,52 +0,0 @@
|
||||||
A Vulkan layer to display information about the running application
|
|
||||||
using an overlay.
|
|
||||||
|
|
||||||
To turn on the layer run :
|
|
||||||
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
List the available statistics :
|
|
||||||
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=help /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
Turn on some statistics :
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
Position the layer :
|
|
||||||
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics,position=top-right /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
Dump statistics into a file:
|
|
||||||
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=position=top-right,output_file=/tmp/output.txt /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
Dump statistics into a file, controlling when such statistics will start
|
|
||||||
to be captured:
|
|
||||||
|
|
||||||
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=position=top-right,output_file=/tmp/output.txt,control=mesa_overlay /path/to/my_vulkan_app
|
|
||||||
|
|
||||||
The above command will open a unix socket with abstract path
|
|
||||||
'mesa_overlay'. Once a client connects to the socket, the overlay layer
|
|
||||||
will immediately send the following commands to the client:
|
|
||||||
|
|
||||||
:MesaOverlayControlVersion=1;
|
|
||||||
:DeviceName=<device name>;
|
|
||||||
:MesaVersion=<mesa version>;
|
|
||||||
|
|
||||||
The client connected to the overlay layer can enable statistics
|
|
||||||
capturing by sending the command:
|
|
||||||
|
|
||||||
:capture=1;
|
|
||||||
|
|
||||||
And disable it by emitting
|
|
||||||
|
|
||||||
:capture=0;
|
|
||||||
|
|
||||||
By default, capture is enabled when an output_file is specified, but it
|
|
||||||
will be disabled by default when a control socket is in use. In the
|
|
||||||
latter case, it needs to be explicitly enabled through the sockets, by
|
|
||||||
using the commands above.
|
|
||||||
|
|
||||||
The provided script overlay-control.py can be used to start/stop
|
|
||||||
capture. The --path option can be used to specify the socket path. By
|
|
||||||
default, it will try to connect to a path named "mesa_overlay".
|
|
|
@ -0,0 +1,100 @@
|
||||||
|
A Vulkan layer to display information about the running application using an overlay.
|
||||||
|
|
||||||
|
Building
|
||||||
|
=======
|
||||||
|
|
||||||
|
The overlay layer will be built if :code:`overlay` is passed as a :code:`vulkan-layers` argument. For example:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
meson -Dvulkan-layers=device-select,overlay builddir/
|
||||||
|
ninja -C builddir/
|
||||||
|
sudo ninja -C builddir/ install
|
||||||
|
|
||||||
|
See `docs/install.rst <https://gitlab.freedesktop.org/mesa/mesa/-/blob/master/docs/install.rst>`__ for more information.
|
||||||
|
|
||||||
|
Basic Usage
|
||||||
|
=======
|
||||||
|
|
||||||
|
Turn on the layer:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay /path/to/my_vulkan_app
|
||||||
|
|
||||||
|
|
||||||
|
List the available statistics:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=help /path/to/my_vulkan_app
|
||||||
|
|
||||||
|
|
||||||
|
Turn on some statistics:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics /path/to/my_vulkan_app
|
||||||
|
|
||||||
|
Position the overlay:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=submit,draw,pipeline_graphics,position=top-right /path/to/my_vulkan_app
|
||||||
|
|
||||||
|
Logging Statistics
|
||||||
|
=======
|
||||||
|
|
||||||
|
Log statistics to a file:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
VK_INSTANCE_LAYERS=VK_LAYER_MESA_overlay VK_LAYER_MESA_OVERLAY_CONFIG=output_file=/tmp/output.txt /path/to/my_vulkan_app
|
||||||
|
|
||||||
|
Logging is enabled for the entire lifecycle of the process unless a control socket is specified (see below).
|
||||||
|
|
||||||
|
**Note:** some statistics (e.g. :code:`frame_timing` and :code:`gpu_timing`) log values for the entire sample interval instead of per-frame.
|
||||||
|
For these statistics, logging the :code:`frame` statistic allows one to compute per-frame statistics after capture.
|
||||||
|
|
||||||
|
Log statistics to a file, controlling when such statistics will start to be captured:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
The command above will open a Unix socket with the abstract path :code:`mesa_overlay`. When a control socket is specified,
|
||||||
|
logging must be explicitly enabled through the control socket. :code:`mesa-overlay-control.py` provides a convenient CLI:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
mesa-overlay-control.py start-capture
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
mesa-overlay-control.py stop-capture
|
||||||
|
|
||||||
|
Direct Socket Control
|
||||||
|
------
|
||||||
|
|
||||||
|
The Unix socket may be used directly if needed. Once a client connects to the socket, the overlay layer will immediately
|
||||||
|
send the following commands to the client:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
:MesaOverlayControlVersion=1;
|
||||||
|
:DeviceName=<device name>;
|
||||||
|
:MesaVersion=<mesa version>;
|
||||||
|
|
||||||
|
The client connected to the overlay layer can enable statistics capturing by sending the command:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
:capture=1;
|
||||||
|
|
||||||
|
And disable it by sending:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
:capture=0;
|
||||||
|
|
||||||
|
.. _docs/install.rst: ../../docs/install.rst
|
Loading…
Reference in New Issue