Mesa (main): vulkan/overlay: revise and reformat README

[GitLab Mirror]

Module: Mesa
Branch: main
Commit: 7483c40ba09bdb29d7cafac3130914d09e82b59d
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=7483c40ba09bdb29d7cafac3130914d09e82b59d

Author: Caleb Callaway <caleb.callaway at intel.com>
Date:   Fri Jan 28 12:15:59 2022 -0800

vulkan/overlay: revise and reformat README

Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/14784>

---

 src/vulkan/overlay-layer/README     |  52 -------------------
 src/vulkan/overlay-layer/README.rst | 100 ++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+), 52 deletions(-)

diff --git a/src/vulkan/overlay-layer/README b/src/vulkan/overlay-layer/README
deleted file mode 100644
index 20ab73103e7..00000000000
--- a/src/vulkan/overlay-layer/README
+++ /dev/null
@@ -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".
diff --git a/src/vulkan/overlay-layer/README.rst b/src/vulkan/overlay-layer/README.rst
new file mode 100644
index 00000000000..ffb26e8d229
--- /dev/null
+++ b/src/vulkan/overlay-layer/README.rst
@@ -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