GFXReconstruct Documentation

GFXReconstruct is a suite of tools designed to capture and replay graphics API calls. It allows developers to record graphics commands executed by an application to a file and later replay them to reconstruct the application's graphics behavior. This is useful for regression testing, platform bringup, and bug reporting.

Core components include:

• VK_LAYER_LUNARG_gfxreconstruct: A Vulkan layer used to capture Vulkan application commands.
• D3D12 capture libraries: Libraries used to capture D3D12 application commands.
• gfxrecon-replay: Tool to replay GFXReconstruct capture files.
• gfxrecon-info: Tool to print descriptive information about capture files.
• gfxrecon-compress: Tool to compress or decompress capture files (requires LZ4, Zstandard, and/or zlib).
• gfxrecon-extract: Tool to extract SPIR-V binaries from capture files.
• gfxrecon-convert: Tool to convert capture files to a JSON Lines listing of API calls (D3D12 support is experimental).
• gfxrecon-optimize: Tool to produce new capture files with improved replay performance.

The primary goal of replay is to achieve execution in the same environment as the capture without user intervention.

Replay Environment

• Target: Ideally, replay occurs on the same GPU model, OS, and driver revision under similar or lower load conditions.
• Portability: While same-environment replay is the priority, the capture format is designed not to make portable replay (different GPUs/OS/drivers) impossible.

Workload and Sequence Fidelity

• GPU Workload: Replay aims to produce a GPU workload (shaders, resources, memory access patterns) as similar to the capture as possible.
• Command Sequence: The replayed sequence should match the captured sequence as closely as possible.

Known Exceptions and Limitations

• Virtual Swapchain: Used to ensure swapchain image index determinism during replay.
• Single-threaded Replay: Currently, replay is single-threaded. This means memory and object creation/access sequences may differ from the original multi-threaded captured workload.
• Trimmed Sequences: For trimmed ranges, the order of commands used to create objects and set state is not guaranteed, though state is kept as close to the original as possible.
• Android: Replay on Android may require the --surface-index parameter to force the selection of a specific surface.

If you need to debug the capture layer from the moment the application starts, you can implement a manual spinlock in VulkanCaptureManager::OverrideCreateInstance(). This prevents the layer from proceeding until a debugger is attached.

Implementation: Add the following loop to the start of VulkanCaptureManager::OverrideCreateInstance():

while (util::platform::GetEnv("debug.gfxrecon.debug_wait") == "1") {
    usleep(100000);
}

Workflow:

1. Set the spinlock property on the device: adb shell setprop debug.gfxrecon.debug_wait 1.
2. Start the application. It will now spin in the loop.
3. Launch your lldb client and attach to the process.
4. Release the spinlock by setting the property to 0: adb shell setprop debug.gfxrecon.debug_wait 0.
5. Continue debugging normally.

// In VulkanCaptureManager::OverrideCreateInstance()
while (util::platform::GetEnv("debug.gfxrecon.debug_wait") == "1") {
    usleep(100000);
}

// Commands to control the spinlock via ADB:
// Enable: adb shell setprop debug.gfxrecon.debug_wait 1
// Disable: adb shell setprop debug.gfxrecon.debug_wait 0

The resource dumping feature generates several files. The primary metadata is stored in a JSON file named after the input file (e.g., vulkanCapture.gfxr becomes vulkanCapture_rd.json).

Output File Types

• JSON Output: Contains the header, drawCallCommands, and dispatchCommands/traceRays details. It maps Vulkan API parameters to specific dumped files.
• Image Files: Created in the specified ImageFormat (bmp or png).
• Binary Files (.bin): All buffers are dumped as raw binary files. Additionally, images that cannot be converted to a standard 32-bit RGBA layout are dumped as raw .bin files.

JSON Structure

1. Header: Contains source path, GFXR/Vulkan versions, and the dumpResourcesOptions used.
2. Draw call commands: An array of entries including Vulkan parameters, color/depth attachments, vertex/index buffers, and immutable descriptors.
3. Dispatch/Trace Rays commands: Includes Vulkan parameters, generated images/buffers, and immutable descriptors.

[
{
  "header": {
    "source-path": "vulkanCapture.gfxr",
    "gfxrecon-version": "1.0.3",
    "vulkan-version": "1.3.275",
    "dumpResourcesOptions": { ... }
  }
},
{
   "drawCallCommands": [
    {
      "drawIndex": 407,
      "parameters": { "drawCallType": "vkCmdDraw", ... },
      "colorAttachments": [{ "file": "Draw_407_..._att_0_aspect_color.bmp" }],
      "descriptors": { "vertex": [...] }
    }
   ]
},
{
   "dispatchCommands": [ ... ]
}]