replayer/README.md

   1 Replayer
   2 ========
   3
   4 ### Traces definition file
   5
   6 The trace definition file contains information about the traces to run along
   7 with their expected image checksums on each device, and optionally from where to
   8 download them. An example:
   9
  10 ```yaml
  11 traces-db:
  12   download-url: https://minio-packet.freedesktop.org/mesa-tracie-public/
  13
  14 traces:
  15   - path: glmark2/jellyfish.rdc
  16     expectations:
  17       - device: gl-intel-0x3185
  18         checksum: 58359ea4caf6ad44c6b65526881bbd17
  19       - device: gl-vmware-llvmpipe
  20         checksum: d82267c25a0decdad7b563c56bb81106
  21   - path: supertuxkart/supertuxkart-antediluvian-abyss.rdc
  22     expectations:
  23       - device: gl-intel-0x3185
  24         checksum: ff827f7eb069afd87cc305a422cba939
  25 ```
  26
  27 The `traces-db` entry can be absent, in which case it is assumed that
  28 the traces can be found in the `CWD/replayer-db` directory.
  29
  30 Traces that don't have an expectation for the current device are skipped
  31 during trace replay.
  32
  33 Adding a new trace to the list involves uploading the trace to the
  34 remote `traces-db` and adding an entry to the `traces` list. The
  35 reference checksums can be calculated with the `checksum` command.
  36 Alternatively, an arbitrary checksum can be used, and during replay
  37 (see below) the scripts will report the mismatch and expected
  38 checksum.
  39
  40 ### Trace-db download urls
  41
  42 The trace-db:download-url property contains an HTTPS url from which traces can
  43 be downloaded, by appending traces:path properties to it.
  44
  45 ### Trace files
  46
  47 replayer supports renderdoc (.rdc), apitrace (.trace, .trace-dxgi) and
  48 gfxreconstruct (.gfxr) files. Trace files need to have the correct
  49 extension so that replayer can detect them properly.
  50
  51 The trace files that are contained in public `traces-db` stores must
  52 be legally redistributable. This is typically true for FOSS games and
  53 applications. Traces for proprietary games and application are
  54 typically not redistributable, unless specific redistribution rights
  55 have been granted by the publisher.
  56
  57 In order to have reliable comparisons, trace files in a given store
  58 are expected to be immutable. Any change to a trace file means that it
  59 needs to be renamed and updated in the traces definition file (eg. by
  60 appending a _v2 suffix to the file).
  61
  62 ### Replaying traces
  63
  64 If running from the source tree, replayer needs the
  65 `PIGLIT_SOURCE_DIR` env variable:
  66
  67    ```sh
  68    $ PIGLIT_SOURCE_DIR="../" ./replayer.py ...
  69    ```
  70
  71 replayer features a series of commands to deal with traces:
  72  * `checksum`: will calculate the checksum for a given image file.
  73  * `compare`: will download a trace or all the traces in a traces
  74    definition file for a given device, replay them and compare their
  75    checksum against the expected ones.
  76  * `download`: will download a file, given a relative path, from a
  77    remote url.
  78  * `dump`: will dump as images the last call or specified calls from a
  79    trace file, given a specific device.
  80  * `query`: will return the queried information from a given traces
  81    definition file.
  82
  83 You can get a more complete help running:
  84
  85    ```sh
  86    $ replayer.py <command> --help
  87    ```
  88
  89 Examples:
  90
  91    ```sh
  92    $ replayer.py checksum ./vkcube.gfxr-9.png
  93    ```
  94
  95    ```sh
  96    $ replayer.py compare trace \
  97                  --output ./results \
  98                  --device-name gl-vmware-llvmpipe \
  99                  --download-url https://minio-packet.freedesktop.org/mesa-tracie-public/ \
 100                  glmark2/desktop-blur-radius=5:effect=blur:passes=1:separable=true:windows=4.rdc \
 101                  8867f3a41f180626d0d4b7661ff5c0f4
 102    ```
 103
 104    ```sh
 105    $ replayer.py compare yaml \
 106                  --yaml-file ./traces.yml \
 107                  --device-name gl-vmware-llvmpipe \
 108                  --keep-image
 109    ```
 110
 111    ```sh
 112    $ replayer.py download \
 113                  --download-url https://minio-packet.freedesktop.org/mesa-tracie-public/ \
 114                  --db-path ./traces-db \
 115                  --force-download \
 116                  glmark2/desktop-blur-radius=5:effect=blur:passes=1:separable=true:windows=4.rdc
 117    ```
 118
 119    ```sh
 120    $ replayer.py dump \
 121                  --config ./piglit.conf \
 122                  --output ./results \
 123                  --device-name gl-vmware-llvmpipe \
 124                  --calls "3,8,9" \
 125                  glmark2/desktop-blur-radius=5:effect=blur:passes=1:separable=true:windows=4.rdc
 126    ```
 127
 128    ```sh
 129    $ replayer.py query \
 130                  --yaml-file ./traces.yml \
 131                  checksum \
 132                  --device-name gl-vmware-llvmpipe \
 133                  glmark2/desktop-blur-radius=5:effect=blur:passes=1:separable=true:windows=4.rdc
 134    ```
 135
 136    ```sh
 137    $ replayer.py query \
 138                  --yaml-file ./traces.yml \
 139                  traces \
 140                  --device-name gl-vmware-llvmpipe \
 141                  --trace-extensions ".trace,.rdc"
 142                  --checksum
 143    ```
 144
 145    ```sh
 146    $ replayer.py query \
 147                  --yaml-file ./traces.yml \
 148                  traces_db_download_url
 149    ```
 150
 151 Unless specified when comparing or dumping, replayer places the
 152 produced artifacts at the `CWD/results` directory. By default, created
 153 images from traces are only stored in case of a checksum
 154 mismatch. This can be overridden with the `--keep-image` parameter to
 155 force storing images, e.g., to get a complete set of reference images.
 156
 157 By default when dumping, only the image corresponding to the last frame
 158 of the trace is created.  This can be changed with the `--calls`
 159 parameter.
 160
 161 Unless specified with the `--output` parameter, the dumped images are
 162 stored in the subdirectory `./test/<device-name>/<trace_file_path/` ,
 163 with names of the form `trace_file_name-call_num.png`.  The full log
 164 of any commands used while dumping the images is also saved in a file
 165 in the 'test/<device-name>' subdirectory, named after the trace name
 166 with '.log' appended.
 167
 168 ### Specific dependencies for dumping depending of the trace type
 169
 170 Depending on the target 3D API, replayer requires a recent version
 171 of apitrace (and eglretrace) being in the path, and also the renderdoc
 172 python module being available, for GL traces.
 173
 174 To ensure python3 can find the renderdoc python module you need to set
 175 `PYTHONPATH` to point to the location of `renderdoc.so` (binary python modules)
 176 and `LD_LIBRARY_PATH` to point to the location of `librenderdoc.so`. In the
 177 renderdoc build tree, both of these are in `renderdoc/<builddir>/lib`. Note
 178 that renderdoc doesn't install the `renderdoc.so` python module.
 179
 180 In the case of Vulkan traces, replayer needs a recent version of
 181 gfxrecon-info and gfxrecon-replay being in the path, and also the
 182 `VK_LAYER_LUNARG_screenshot` Vulkan layer from LunarG's VulkanTools.
 183
 184 To ensure that this layer can be found when running the trace you need
 185 to set `VK_LAYER_PATH` to point to the location of
 186 `VkLayer_screenshot.json` and `LD_LIBRARY_PATH` to point to the
 187 location of `libVkLayer_screenshot.so`.
 188
 189 In the case of DXGI traces, replayer requires Wine, a recent version
 190 of DXVK installed in the default `WINEPREFIX`, and a recent binary
 191 version of apitrace (and d3dretrace) for Windows which should be
 192 reachable through Windows' `PATH` environment variable.
 193
 194 Alternatively, all of the paths for specific binaries can be set via
 195 piglit's configuration file or env variables. Check the documentation
 196 at [piglit.conf.example](piglit.conf.example) for further details.