1A Vulkan layer to take efficient screenshots to reduce performance loss in Vulkan applications. 2 3Building 4======== 5 6The screenshot layer will be built if :code:`screenshot` is passed as a :code:`vulkan-layers` argument. For example: 7 8.. code-block:: sh 9 10 meson -Dvulkan-layers=device-select,screenshot 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_screenshot /path/to/my_vulkan_app 24 25 26List the help menu: 27 28.. code-block:: sh 29 30 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=help /path/to/my_vulkan_app 31 32Enable log output in stdout/stderr: 33 34.. code-block:: sh 35 36 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=log_type=<info|debug> /path/to/my_vulkan_app 37 38Redirect screenshots taken to a different directory: 39 40.. code-block:: sh 41 42 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=output_dir=/path/to/new_dir /path/to/my_vulkan_app 43 44Capture pre-determined screenshots: 45 46.. code-block:: sh 47 48 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=frames=1/5/7/15-4-5 /path/to/my_vulkan_app 49 50Note: 51 - Individual frames are separated by '/' and must be listed before the frame range 52 - The frame range is determined by <range start>-<range count>-<range interval> 53 - Example: '1/5/7/15-4-5' gives individual frames [1,5,7], then the frame range gives [15,20,25,30], combining into [1,5,7,15,20,25,30] 54 55To capture all frames: 56 57.. code-block:: sh 58 59 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=frames=all /path/to/my_vulkan_app 60 61To capture a ImageRegion: 62 63.. code-block:: sh 64 65 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=region=0.20/0.25/0.60/0.75 /path/to/my_vulkan_app 66 67Note: 68 - Using a region will capture a portion of the image on the GPU, meaning the copy time to the CPU memory can be reduced significantly if using a small enough region size, relative to the original image. 69 - The regions are percentages, represented by floating point values. the syntax for a region is 'region=<startX>/<startY>/<endX>/<endY>', where percentages are given for the starting width and starting height, along with ending width and ending height. 70 - - Example with vkcube: 71 72- - - Original size: 500x500 image 73 74.. code-block:: sh 75 76 mesa-screenshot: DEBUG: Screenshot Authorized! 77 mesa-screenshot: DEBUG: Needs 2 steps 78 mesa-screenshot: DEBUG: Time to copy: 123530 nanoseconds 79 80 81- - - Using '0.4/0.4/0.6/0.6' region: 100x100 image 82 83.. code-block:: sh 84 85 mesa-screenshot: DEBUG: Screenshot Authorized! 86 mesa-screenshot: DEBUG: Using region: startX = 40% (200), startY = 40% (200), endX = 60% (300), endY = 60% (300) 87 mesa-screenshot: DEBUG: Needs 2 steps 88 mesa-screenshot: DEBUG: Time to copy: 12679 nanoseconds 89 90Reducing a 500x500 image to a 100x100 image caused a reduction in the copy time by a factor of 10, meaning that we spend less time impacting the frame time and are able to run the workload with a negligible performance impact from the screenshot layer. 91 92Direct Socket Control 93--------------------- 94 95Enabling communication with the client can be done with the following setup: 96 97.. code-block:: sh 98 99 VK_LOADER_LAYERS_ENABLE=VK_LAYER_MESA_screenshot VK_LAYER_MESA_SCREENSHOT_CONFIG=comms /path/to/my_vulkan_app 100 101The Unix socket may be used directly if needed. Once a client connects to the socket, the screenshot layer will immediately 102send the following commands to the client: 103 104.. code-block:: sh 105 106 :MesaScreenshotControlVersion=1; 107 :DeviceName=<device name>; 108 :MesaVersion=<mesa version>; 109 110The client connected to the screenshot layer can trigger a screenshot to be taken by sending the command: 111 112.. code-block:: sh 113 114 :capture=<screenshot_name.png>; 115 116Note that the screenshot name must include '.png', other image types are not supported. 117 118To capture a region, the region information must be added to the 'region' command, along with the 'capture' command, separated by a comma: 119 120.. code-block:: sh 121 122 :region=0.25/0.25/0.75/0.75,capture=<screenshot_name.png>; 123 124.. _docs/install.rst: ../../docs/install.rst 125
