# GFXReconstruct: capturing a Vulkan application and replaying it later

> GFXReconstruct is LunarG's suite for recording graphics API calls to a file and replaying them to reconstruct an application's behaviour, with a Vulkan layer, D3D12 capture libraries, and tools to inspect, compress, convert and optimise captures. Vulkan support spans desktop and Android, and OpenXR support is still a proof of concept.

**LunarG/gfxreconstruct** — Graphics API Capture and Replay Tools for Reconstructing Graphics Application Behavior

- Repository: https://github.com/LunarG/gfxreconstruct
- Website: https://vulkan.lunarg.com/doc/sdk/latest/linux/capture_tools.html
- Stars: 609 · Forks: 205
- Language: C++
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/lunarg-gfxreconstruct

## The capture file is the unit of work

GFXReconstruct provides tools for the capture and replay of graphics API calls, so the graphics commands executed by an application can be recorded to a file that may later be replayed to reconstruct the graphics-specific behavior of the captured application. The replay code is organised with a framework design, and the stated reason is that it makes it easy to create additional tools for processing capture files. That framing explains the whole project. The capture file is a portable record of an application's graphics behaviour, and every tool in the repository is either a way to produce one or a way to read one. The components are listed explicitly. There is the VK_LAYER_LUNARG_gfxreconstruct Vulkan layer for capturing Vulkan application commands, and the D3D12 capture libraries for capturing D3D12 commands. There is gfxrecon-replay to replay the capture files and gfxrecon-info to print information describing them. There is gfxrecon-compress to compress and decompress them, gfxrecon-extract to pull SPIR-V binaries out of them, gfxrecon-convert to convert them into a JSON Lines listing of API calls, and gfxrecon-optimize to produce new capture files with improved replay performance.

## The support matrix is the real documentation

The README carries a capability table across five platforms, Windows, Linux, Mac, Android and Meta Quest, with three APIs, Vulkan, D3D12 and OpenXR, and it is more informative than any prose would be. Vulkan capture and replay are supported on all four desktop and mobile platforms, with Meta Quest marked as under construction. The tool suite under Vulkan is fully supported on Windows, Linux and Mac, and on Android and Meta Quest the tools that operate on the capture file rather than the API are marked as not supported on device, though the desktop tools can still modify the resulting captures. D3D12 support is Windows only across every listed tool, which is what you would expect from an API that exists only there. OpenXR is a separate story, since the README states that OpenXR support is experimental and recommended only for developer use for evaluation, that only a subset of features and a very small number of apps are supported, and that it is limited to the Vulkan graphics API. The legend explains the four markers, with the orange diamond meaning not supported on Android or Meta Quest but with desktop tools able to modify the captures, and the construction marker meaning early preview, alpha or beta. The most important caveat sits underneath the table, that it only represents replay on the same platform and driver version on which the file was captured.

## Cross-platform replay is possible but unsupported and conditional

The README is careful about the difference between what works and what is supported. It is possible in some circumstances to replay on one operating system a trace that was captured on another, but this is not currently supported unless specified. The example given is a Windows capture replaying on Linux, and vice versa, and it requires certain settings to be forced in the replay application, such as overriding the windowing system used, disabling unknown extensions and rebinding memory. On top of that, compatibility libraries have to be enabled to expose operating system behaviour, and the example given is Wine. The practical meaning is that a Windows capture replayed on Linux is a debugging technique you engineer case by case, not a feature you can rely on for a test matrix. And even then the driver version has to line up, since the matrix is explicitly about same platform and same driver. The distinction between possible and supported is the one to hold on to, because a report that says a capture reproduces elsewhere may be describing a hand-tuned session rather than a documented capability.

## Dumping to JSON Lines and pulling SPIR-V out of a capture

Two of the tools turn a capture into something you can process with other tools. gfxrecon-convert converts a capture file into a JSON Lines listing of API calls, which the README links to the jsonlines.org format, and this is marked as experimental for D3D12 captures. A JSON Lines listing is a stream of records, one per line, which is a good shape for grep, for a script, or for loading into a notebook, and it is the difference between a capture file and a data set. The other is gfxrecon-extract, which extracts SPIR-V binaries from capture files, which is the tool you reach for when you want to see the shaders an application actually used rather than what you believe it used. The compression tool is the third piece of that workflow, and it has a build dependency note worth reading, because gfxrecon-compress requires LZ4, Zstandard and/or zlib, which are currently optional build dependencies. So a build that omits them gives you a tool that cannot compress, and the failure mode is a missing feature rather than a build error, which is worth checking if you find the tool present but inert. There is also a vulkan_dump_resources.md document in the tree, which suggests a related facility for enumerating resources.

## Testing uses small apps with known output

The testing section describes an approach that is worth borrowing. In addition to unit tests, there are several test apps included that can be used to verify GFXReconstruct output, and these test apps execute small graphics workloads which result in small, known .gfxr outputs. The file extension gives away the native format of a capture, and having known-good small files in the tree means a change to the capture or replay path can be checked against a known result rather than eyeballed. The repository also carries reference files in the tree, test.ref and test_suite.ref, which are the expected outputs the suite compares against. The rest of the tree supports the same discipline. There are CI directories and scripts, a cmake directory, an external directory for vendored dependencies, a layer directory holding the Vulkan layer, a framework directory, a tools directory, an android directory, and a docs directory. Version information is generated, with project_version.cpp, project_version.h.in and project_version_string.h.in alongside a version.rc, which is a Windows resource file for the binaries. The last push to the repository was on 2026-10-20, the default branch is dev, and the recent release tags are SDK builds, with vulkan-sdk-1.4.363.0 for the Android binaries dated 2026-09-28.

## The appropriate use section is unusually direct

GFXReconstruct includes a section titled Appropriate Use, and it is one of the clearer statements of scope in an open source graphics tool. The suite is intended for the purpose of improving application and platform quality by allowing the analysis of capture and replay of graphics command streams, and the listed use cases are regression testing, silicon and platform bringup, and reporting bugs. Then the warning. Using GFXReconstruct to extract assets from an application or game for which you do not have an appropriate license may violate copyrights or software licenses. That sentence exists because a capture file contains the application's resources, its shaders and its data, and the tool that extracts SPIR-V binaries is one command away from being an asset ripper. The stated purpose of the project is the analysis of behaviour, not the recovery of content, and the licence is MIT, which covers the code rather than the assets you might pull out of somebody else's application with it. The repository layout is consistent with that framing, with a LICENSES/ directory for the third party licence texts of the vendored dependencies, a LICENSE.md for the project, and a CODEOWNERS file.

## Where GFXReconstruct is the wrong tool

There are several clear boundaries. If your application is D3D12 based and you are not on Windows, the tools are not available at all, so the answer is a different capture layer. If you are working on OpenXR, the support is a proof of concept with a subset of features and a very small number of apps, it is not enabled in the SDK built version of GFXReconstruct, and you have to pull the source down and build manually. If your workflow needs a capture to replay on a different operating system as a routine thing rather than as a debugging exercise, the project does not support that, and the conditions listed, forced windowing, disabled extensions, rebound memory and a compatibility library such as Wine, are exactly the kind of setup that turns into its own maintenance problem. The other limit is conceptual rather than technical. A capture file reproduces graphics behaviour, so it reproduces the rendering, and it tells you nothing about the application's own logic, its timing outside the graphics pipeline, or its behaviour with different input. For a rendering bug, this is precisely the right tool. For a logic bug, you need a debugger, and for a performance problem you need a profiler, since a replay runs the recorded command stream rather than the work that produced it.

## Conclusion

Adopt GFXReconstruct if you need to reproduce a graphics application frame by frame on a different machine or a different driver, which makes it a strong fit for regression testing, platform bringup and bug reporting. Skip it if you need a D3D12 capture outside Windows, if you need OpenXR beyond a developer evaluation, or if you want to lift assets out of a game you do not own, since the project states plainly that doing so may violate copyrights. Verify first which API and platform combination you are on, since the support matrix is per platform and per tool, and read the replay option documentation before assuming a capture replays on a different operating system.

## FAQ

### What does GFXReconstruct actually do?

It provides tools for the capture and replay of graphics API calls, so the graphics commands an application executes can be recorded to a file and later replayed to reconstruct that application's graphics-specific behaviour. The replay code is organised as a framework to make it easier to build additional tools that process capture files.

### Which platforms does GFXReconstruct support for Vulkan?

Vulkan capture and replay are supported on Windows, Linux, Mac and Android, with Meta Quest marked as under construction. D3D12 support is Windows only, and OpenXR support is experimental, limited to a subset of features and a small number of apps, and is not enabled in the SDK built version.

### Can I replay a capture captured on Windows on Linux?

It is possible in some circumstances, but the README says cross-platform replay is not currently supported unless specified. It requires forcing settings in the replay application, such as overriding the windowing system, disabling unknown extensions and rebinding memory, and enabling compatibility libraries that expose operating system behaviour, with Wine given as the example.

## Sources

- [Issues](https://github.com/LunarG/gfxreconstruct/issues)
- [LunarG/gfxreconstruct on GitHub](https://github.com/LunarG/gfxreconstruct)
- [Project website](https://vulkan.lunarg.com/doc/sdk/latest/linux/capture_tools.html)
- [README](https://github.com/LunarG/gfxreconstruct/blob/dev/README.md)
- [Releases](https://github.com/LunarG/gfxreconstruct/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lunarg-gfxreconstruct