Skip to content

Latest commit

 

History

History
186 lines (129 loc) · 9.18 KB

USAGE_desktop_OpenXR.md

File metadata and controls

186 lines (129 loc) · 9.18 KB

LunarG

Creative Commons

Copyright © 2018-2022 LunarG, Inc.

Copyright © 2022 Advanced Micro Devices, Inc.

GFXReconstruct API Capture and Replay - OpenXR

This document describes the GFXReconstruct software for capturing and replaying OpenXR on Desktop systems (i.e. Windows, Linux, MacOS).

If you are looking for capturing/replaying on a different platform, please refer to one of these other documents:

EXPERIMENTAL FEATURE!!!

Be aware the OpenXR support within GFXReconstruct is an experimental feature, with restricted functionality and testing. See List of Known Limitations below.

Index

  1. Capturing API calls
    1. Enabling the Capture Layer
    2. Capture Options
    3. Capture Files
    4. Capture Script
  2. Replaying API Calls
    1. Command Line Arguments
    2. Key Controls
    3. Virtual Swapchain
    4. Dumping resources
  3. Other Capture File Processing Tools
    1. Capture File Info
    2. Capture File Compression
    3. Shader Extraction
    4. Trimmed File Optimization
    5. JSON Lines Conversion
    6. Command Launcher
    7. Options Common To All Tools

Capturing API calls

The GFXReconstruct capture layer is a OpenXR layer that intercepts OpenXR API calls and logs them to a GFXReconstruct capture file. Currently Vulkan capture must also be enabled concurrently when OpenXR Capture is enabled. See GfxReconstruct for Desktop Vulkan for details.

Enabling the Capture Layer

The path to the layer's XrLayer_gfxreconstruct.json file and corresponding VkLayer_gfxreconstruct library must be added to XR_API_LAYER_PATH environment variable for the OpenXR loader to find the layer.

Note that this must be the same path specified for the Vulkan Loader, as capture will not function correctly if different VkLayer_gfxreconstruct libraries are used for the two API's.

After XR_API_LAYER_PATH has been updated, the layer may be enabled through one of the following methods:

  • Adding the XR_APILAYER_LUNARG_gfxreconstruct name string to the XrInstanceCreateInfo::enabledApiLayerNames value when calling xrCreateInstance
  • Adding the XR_APILAYER_LUNARG_gfxreconstruct name string to the list of layer names specified through the XR_ENABLE_API_LAYERS environment variable

Setting XR_API_LAYER_PATH

The XR_API_LAYER_PATH environment variable can be used to tell the OpenXR loader where to find the GFXReconstruct capture layer. (Note: the following not yet supported in SDK, so you will need to manually set the XR_API_LAYER_PATH.) If you are using GFXReconstruct from a Vulkan SDK installation or a Linux package install, there is no need to set XR_API_LAYER_PATH- the installation process will have set up the GFXReconstruct capture layer so that the Vulkan loader can find and load it.

Setting VK_LAYER_PATH for Windows

If you are not using GFXReconstruct from a Vulkan SDK, use the following as an example of how to update the Windows XR_API_LAYER_PATH andVK_LAYER_PATH environment variable for the GFXReconstruct capture layer. The example uses the C:\gfxreconstruct path to represent the location of directory containing the GFXReconstruct project source, and the build folder name to represent the sub-directory specified to CMake as the location to place the build binaries. The following command would be executed from the command prompt to add the Debug build of the layer to VK_LAYER_PATH:

set VK_LAYER_PATH=C:\gfxreconstruct\build\layer\Debug;%VK_LAYER_PATH%
set XR_LAYER_PATH=C:\gfxreconstruct\build\layer\Debug;%XR_LAYER_PATH%
Setting VK_LAYER_PATH for Linux (not supported)

If you are not using GFXReconstruct from the Vulkan SDK or a Linux package, use the following as an example of how to update the Linux VK_LAYER_PATH environment variable for the GFXReconstruct capture layer. The example uses the /gfxreconstruct path to represent the location of directory containing the GFXReconstruct project source, and the build folder name to represent the sub-directory specified to CMake as the location to place the build binaries. The following command would be executed from the command line to add the layer to VK_LAYER_PATH: export VK_LAYER_PATH=/gfxreconstruct/build/layer:$VK_LAYER_PATH

Enabling the capture with Environment Variables

The XR_ENABLE_API_LAYERSand VK_INSTANCE_LAYERS environment variables may be used so that the the GFXReconstruct layer is loaded by the OpenXR and Vulkan loaders respectively.

Enabling the capture for Windows

The following command would be executed from the command prompt to set the XR_ENABLE_API_LAYERS and VK_INSTANCE_LAYERS environment variables:

set XR_ENABLE_API_LAYERS=XR_APILAYER_LUNARG_gfxreconstruct
set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct
Enabling the layer for Linux (not supported)

The following command would be executed from the command line to set the VK_INSTANCE_LAYERS environment variable: export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct

Understanding GFXReconstruct OpenXR Layer Capture and Replay

TODO: Expand this section describing the differences between Vulkan and OpenXR capture and replay.

  • OpenXR realtime head, hand, controller capture will not match replay head, hand, controller data at replay. The latter being largely ignored.
  • OpenXR state machine transitions and events will not match exactly between capture and replay. Event data replay attempts to match events from capture, important for events reflecting runtime state such as XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED
  • Replayed OpenXR frames are displayed at the the same head relative position as captured, and thus are insensitive to replay time head tracking.

Capture Options

The GFXReconstruct OpenXR layer supports several options, which may be enabled through environment variables or a layer settings file.

These match those described in GfxReconstruct for Desktop Vulkan, noting limitations described below.

Replaying API Calls

The GFXReconstruct Replay tool, gfxrecon-replay, can be used to replay files captured with or generated by other GFXReconstruct components. See GfxReconstruct for Desktop Vulkan for full documentation, noting limitations described below.

OpenXR Known Limitations

The current implementation has been written to cover the OpenXR API entry points and usage based on a limited number of test applications (listed below). It is possible that meaningful omissions or errors in capture and/or replay may exist outside the usage tested.

  • Only the Vulkan Graphics binding is supported for OpenXR captures
  • Vulkan Capture must be enabled when OpenXR capture is enabled
  • The VK_LAYER_PATH and XR_LAYER_PATH must resolve to the same VkLayer_gfxreconstruct libraries
  • Only Android and Windows platforms have been tested
  • Only the monado runtime has been tested on Windows. During replay the setting Debug: ATW OFF must be enabled for correct view relative xrEndFrame output.
  • Only the Meta Quest Pro and Meta Quest 3 have been tested as standalone VR headsets
  • Only the applications hello_xr OpenXR-SDK-Source and HelloOpenXRSession_vulkan_openxr_sim (on this IGL fork on branch marky_rollback_igl) applications have be tested on Windows.
  • Only HelloOpenXRSession_vulkan_openxr_sim have been tested on Meta Quest headsets
  • The XR_EXT_debug_utils extension is not implemented in either the VkLayer_gfxreconstruct libraries or the gfxrecon-replay application. This can lead to replay issues (crashes) for captures performed on OpenXR runtimes that also do not support XR_EXT_debug_utils, if the capture time runtime also does not support XR_EXT_debug_utils.

Status of Other Capture File Processing Tools

Capture File Info

Has not been tested with OpenXR captures.

Capture File Compression

Has not been tested with OpenXR captures.

Shader Extraction

Has not been tested with OpenXR.

Trimmed File Optimization

OpenXR capture and replay do no support trimming options.

JSON Lines Conversion

Has been tested and is believed to function correctly for all supported OpenXR commands and datatypes.