Capturing Your First Frames
This is the third post in a multi-part series designed to give developers a comprehensive understanding of how to use GFXReconstruct and appreciate the value it brings to graphics development workflows. Read this blog as a PDF by clicking here.
Welcome to Part 3 of our Mastering GFXReconstruct series! In Part 1, we introduced GFXReconstruct as the open-source, Vulkan-agnostic GPU capture and replay tool developed by LunarG. In Part 2, we covered installation, environment setup, and validation layer integration. Now, it’s time to capture your first GPU workload and generate a .gfxr trace file—the foundation for debugging, performance analysis, and replay testing.
This guide focuses on practical, hands-on steps, and by the end of this post, you’ll have recorded real GPU commands and verified your capture—all within minutes.
Prerequisites Recap
- GFXReconstruct is installed (see Part 2).
- Vulkan SDK ≥ 1.3.268 is available.
- Your target application uses Vulkan (or supports Vulkan via compatibility layers).
Launching an Application with Capture Enabled
In order to begin capturing, you need to inject the capture layer at runtime. This method requires no code changes to your application.
Set the Capture Layer
Linux/macOS:
export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct
Windows:
set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct
This tells the Vulkan loader to enable the GFXReconstruct capture layer for any Vulkan instance created in the process.
Launch Your App with Capture Settings
Option A: Use environment variables and run your app
Linux/macOS:
export GFXRECON_CAPTURE_FILE=my_first_capture.gfxr
export GFXRECON_CAPTURE_FRAMES=1-100
./your_vulkan_app
Windows:
set GFXRECON_CAPTURE_FILE=my_first_capture.gfxr
set GFXRECON_CAPTURE_FRAMES=1-100
your_vulkan_app.exe
Option B: Use the convenience script
gfxrecon-capture-vulkan.py -o my_first_capture.gfxr -f 1-100 ./your_vulkan_app
(Use your_vulkan_app.exe on Windows.)
Key capture options (environment variables)
|
Variable
|
Description
|
|---|---|
|
GFXRECON_CAPTURE_FRAMES
|
Frame ranges to record (1-100, 50, or 10-20,40-60).
|
|
GFXRECON_CAPTURE_FILE
|
Output .gfxr file. Default: gfxrecon_capture_.gfxr.
|
|
GFXRECON_MEMORY_TRACKING_MODE
|
page_guard (default), userfaultfd (Linux/Android), assisted, unassisted.
|
GFXReconstruct Memory Tracking Modes
|
Memory tracking mode
|
Description
|
|---|---|
|
page_guard (default):
|
Watches memory for changes by protecting it.
Fast and keeps files small. Can clash with apps that install their own crash/signal handlers |
|
userfaultfd (Linux/Android)
|
Uses a kernel feature to catch page changes without signals.
Good fallback if page_guard clashes. A bit slower. |
|
assisted
|
Only saves ranges after the app calls vkFlushMappedMemoryRanges.
Very efficient, but only if the app does this correctly. |
Filtering Captures for Precision
Large applications generate massive traces. Use frame range filtering and hotkeys to capture only what matters.
Frame Range Filtering
With the Vulkan API, the end of one frame and the start of the next one is defined by a call to vkQueuePresentKHR(). GFXReconstruct keeps track of the number of calls to this function and lets you specify which frames to record. In this example, only 6 frames of application data are captured, starting at frame 50:
gfxrecon-capture-vulkan.py -o focused_scene.gfxr -f 50-55 ./your_vulkan_app
(Use your_vulkan_app.exe on Windows.)
Applications that perform offscreen rendering or general computation and never call vkQueuePresentKHR() are not able to use this method.
Hotkey Triggered Capture (Interactive Mode)
To interactively capture a range of frames, start your app normally, then press the configured hotkey during runtime to begin capture, and again to stop. The file is written per start/stop pair. Enable hotkeys with GFXRECON_CAPTURE_TRIGGER and the key you want to use as the trigger (F3 in the example below):
Linux/macOS:
export GFXRECON_CAPTURE_TRIGGER=F3
Windows:
set GFXRECON_CAPTURE_TRIGGER=F3
Notes:
- Hotkeys require the capture layer to be loaded and the app to have keyboard focus.
- Valid triggers include F1–F12, TAB, and CTRL.
Interpreting Capture Output
After execution, you’ll find a .gfxr file in your working directory. Let’s verify and explore it.
Step 1: Inspect capture metadata
gfxrecon-info my_first_capture.gfxr
Sample output:
Exe info:
Application exe name:
Application version: 0.0.0.0
Application Company name:
Product name:
File info:
Compression format: LZ4
Total frames: 198
Vulkan application info:
Application name: vkcube
Application version: 0
Engine name: vkcube
Engine version: 0
Target API version: 4194304 (1.0.0)
Used resolutions: 800x600
Step 2: Convert to JSON for scriptable inspection
gfxrecon-convert my_first_capture.gfxr --output my_first_capture.jsonl
Inspect draw calls, pipeline state, and descriptor bindings in human-readable form, or filter or pretty-print with tools like https://jqlang.org/.
Step 3: Replay the Capture (Validation)
gfxrecon-replay my_first_capture.gfxr
Watch your app replay, frame-by-frame. Any deviation indicates a driver or application bug. Expect near pixel-perfect replay; minor differences can appear due to driver or timing variance.
Quick Start Summary: Your First Capture
Linux/macOS:
gfxrecon-capture-vulkan.py -o demo.gfxr -f 1-10 ./your_vulkan_app
gfxrecon-info demo.gfxr
Windows:
gfxrecon-capture-vulkan.py -o demo.gfxr -f 1-10 your_vulkan_app.exe
gfxrecon-info demo.gfxr
That’s it — you’ve recorded GPU commands into a portable .gfxr file!
Next Steps
Now that you can capture reliably:
- Use gfxrecon-optimize to remove unused resource initialization from trimmed captures.
- Integrate capture/replay into CI using gfxrecon-capture-vulkan.py and gfxrecon-replay.
- Explore resource inspection with vulkan_dump_resources.md and replace shaders at replay with gfxrecon-replay –replace-shaders.
Stay tuned for the next installment of Mastering GFXReconstruct—coming soon!
Have a capture tip or tricky app to trace? Let us know @LunarGInc!
