README.rst
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
