Understanding the .gfxr File
What GFXReconstruct Actually Captures and Replays
This is the fourth 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.
If you’ve been following the series so far, you’ve learned how to capture your first Vulkan frames (Part 1), how to trigger captures precisely when you need them (Part 2), and how to replay and trim those captures (Part 3). In this post, we step back and look at the central artifact in all of this: the .gfxr capture file.
This introductory article explains what a .gfxr file contains, how it’s structured, what gets captured (and what does not), and why replay is typically deterministic and visually identical to the original run. Future posts will dive deeper into topics like memory snapshots, optimization, and debugging mismatches during replay.
What Is a .gfxr File?
A .gfxr file is a binary, frame-accurate record of API usage created between the start and end of a capture session. It is produced by the GFXReconstruct capture layer and consumed by the gfxrecon-replay tool.
Think of it as a GPU API tape recorder: it tracks the exact sequence of API calls, the parameters passed to those calls, and—when needed—the relevant GPU memory contents. The intent is that the replay tool can recreate the same command stream on another machine, driver, or even GPU vendor, as long as the API features and extensions match.
In practice, cross-driver or cross-vendor replay can sometimes expose differences (or even reveal bugs). When this happens, the .gfxr file is often the key to diagnosing what’s going wrong.
This article focuses on .gfxr files produced by Vulkan applications on Linux, macOS, and Windows. Android usage will be covered in a future post. In addition to Vulkan, GFXReconstruct can also capture OpenXR and Direct3D API calls.
Structure of a Capture File
A .gfxr file is a single, self-contained binary. You can think of this file as a header that represents the format version and a few options (e.g. compression type, etc.) followed by a stream of blocks, most of which are captured API calls. For up-to-the-minute detailed information about the .gfxr file format, consult the GFXReconstruct documentation.
GFXReconstruct’s capture file format is designed with forward compatibility in mind. This means that capture files created with any given version of GFXReconstruct should be playable (replayable) on all future versions of the tool
However, the reverse is not guaranteed: capture files generated by a newer version of GFXReconstruct may not be compatible with older builds. For instance, if a newer capture includes Vulkan API calls, extensions, or features introduced after an older GFXReconstruct version was released, that older build will typically be unable to process or replay the file correctly.
What Gets Captured
A .gfxr file captures everything required to reconstruct the original GPU workload:
Captured Content
- All commands issued on any queue from an API supported by GFXRecontruct (Vulkan, Direct3D, OpenXR)
- Command buffer contents
- Pipeline, descriptor set, and shader module state
- Buffer and image memory contents necessary to correctly replay the captured API commands
- Swapchain creation and presentation calls
- Debug markers and object names (if VK_EXT_debug_utils is active)
- Extension-specific commands supported by GFXReconstruct (ray tracing, mesh shading, video, etc.)
What Isn’t Captured (by design)
GFXReconstruct records only what is necessary to reproduce GPU behavior. It deliberately does not capture:
- Application CPU logic
- Any window-system events (X11, Wayland, Win32, Cocoa)
- API calls other than Vulkan, Direct3D, and OpenXR (e.g., OpenGL, Metal, CUDA, etc.)
This means a replay focuses strictly on GPU-visible work, not application flow.
Achieving Determinism — Why Replay Is Usually Visually Indistinguishable
GFXReconstruct takes several steps to ensure deterministic results:
- Memory snapshots capture the initial contents of buffers and images precisely when first used by the GPU.
- Command ordering with respect to synchronization.
- Timestamps and fences follow the original logical sequence.
- Swapchain operations are re-acquired and presented in the same order.
The result: On the same OS, driver version, and GPU hardware, replay is typically visually identical. Across vendors and drivers, replay is still usually visually indistinguishable, with deviations generally caused by driver differences, undefined behavior, or unsupported extensions.
Tools You’ll Use Every Day
GFXReconstruct ships several tools that work consistently across Linux, macOS, and Windows:
|
Tool
|
Purpose
|
|---|---|
|
gfxrecon-info
|
Summarizes a .gfxr file (frame count, duration, API version, extensions used)
|
|
gfxrecon-convert
|
Converts a .gfxr file to json
|
|
gfxrecon-replay
|
Replays a .gfxr file
|
|
gfxrecon-optimize
|
Reduces file size by eliminating unused memory snapshots (advanced)
|
The Vulkan SDK is not required if you are capturing OpenXR or Direct3D calls. Platform differences are minimal: just ensure that the Vulkan SDK or standalone GFXReconstruct build you are using matches your OS and architecture.
Portability (and Non-Portability) of .gfxr Files
Here is what you can expect when replaying a capture across different environments:
|
Scenario
|
Expected Result
|
|---|---|
|
Same OS, same driver version
|
Visually indistinguishable
|
|
Same vendor, different driver version
|
Rare visual differences possible
|
|
Different GPU vendor (NVIDIA ↔ AMD ↔ Intel)
|
High success rate if required extensions exist
|
|
Linux → Windows or macOS
|
Works as long as API features match
|
|
Windows → Linux or macOS
|
Works as long as API features match
|
Coming Up Next
Future posts will explore:
- How memory snapshots work (and how to reduce capture size)
- Using gfxrecon-optimize and trimming more effectively
- Automating capture and replay in CI pipelines
For now, grab the latest version of GFXReconstruct from the LunarG GitHub releases page or the Vulkan SDK, and start exploring your .gfxr files with gfxrecon-info. You may be surprised how much insight a single capture file reveals.
Happy debugging!
— The LunarG Team
Previous Posts In This Series
