GFXReconstruct Capture Utility

A Python utility for creating GFXReconstruct captures of Vulkan applications.

Overview

This tool automates the process of running Vulkan applications with the GFXReconstruct capture layer. It supports running multiple applications sequentially and generates both trimmed and non-trimmed captures for each app.

Requirements

• Python 3.6+
• GFXReconstruct layer installed and built
• Vulkan applications to capture

Environment Variables

The tool requires either the VULKAN_SDK environment variable to be set (which allows the Vulkan loader to automatically find GFXReconstruct layers) or the --gfxr-layer-path command-line option to specify the layer path explicitly.

Usage

Basic Usage

python3 create_captures.py --apps-file my_apps.txt

This will load applications from the specified file and create captures in the captures/ directory.

Specifying Applications

The tool requires applications to be specified explicitly. You can either:

1. Use --apps-file to load applications from a file (one application per line, with optional parameters)
2. Use --app to specify individual application paths (can be used multiple times)

# Run specific applications
python3 create_captures.py --app /path/to/app1 --app /path/to/app2

# Load applications from a file (one application per line with optional parameters)
python3 create_captures.py --apps-file my_apps.txt

Apps File Format

Create a text file with one application per line. Each line can contain an application path followed by optional parameters. Lines starting with # are treated as comments and empty lines are ignored:

# My Vulkan applications for capture
/path/to/raytracingbasic --vsync --width 1920
/path/to/raytracingshadows --fullscreen
/path/to/raytracingreflections --vsync

Parameters specified in the apps file override the global --params option for that specific application.

Options

• --apps-file: Path to a file containing applications with optional parameters (one per line)
• --app: Add an application path (can be used multiple times)
• --capture-dir: Output directory for captures (default: captures)
• --frame-range: Frame range for full capture (default: 1-120)
• --frame-range-trim: Frame range for trimmed capture (default: 101-220)
• --params: Default parameters for applications specified with --app (default: --vsync)
• --gfxr-layer-path: Override VK_ADD_LAYER_PATH
• --dry-run: Print commands without executing them
• --timestamp: Set GFXRECON_CAPTURE_FILE_TIMESTAMP (0 or 1)
• --env: Add extra environment variables (KEY=VALUE format, can be used multiple times)

Dry Run

Use --dry-run to see what commands would be executed without actually running them:

python3 create_captures.py --dry-run

Output

For each application, the tool creates:

• A subdirectory named after the application
• Two capture files: {app_name}.gfxr (full capture) and {app_name}.gfxr (trimmed capture)

Environment Variables

The tool sets the following environment variables for captures:

• GFXRECON_CAPTURE_FRAMES: Frame range to capture
• GFXRECON_CAPTURE_FILE: Output file path
• VK_ADD_LAYER_PATH: Path to GFXReconstruct layer
• GFXRECON_CAPTURE_FILE_TIMESTAMP: Timestamp setting