Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

* Annotate GPUVA

If a title updated DXR resource data by Shader and dispatch the shader at
same commandlist as DXR call, GFXR was not able to read out the DXR data
and patch it.

GFXR capturer annotates all GPUVA, GPU Descriptor Handle and ShaderID
during capture, scans managed CPU memory and marks the data which have been
annotated. When replay the trace file, GFXR only need to translate the marked

If there were artifacts during capture, try to change the MASK of GPUVA by ENV.

* Meger dev branch

Git stats


Failed to load latest commit information.
Latest commit message
Commit time
May 29, 2023 11:16
April 21, 2023 22:35
April 30, 2019 15:48
April 21, 2023 22:35
December 9, 2020 11:32

Project Goals

The primary goal for the GFXReconstruct project is to create an improved version of LunarG's vktrace software for capture and replay of Vulkan API calls. As development progresses, existing vktrace functionality such as trimming and client-server mode will be integrated with the GFXReconstruct codebase. When GFXReconstruct reaches feature parity with vktrace, vktrace will be deprecated in favor of GFXReconstruct.

The initial focus of this effort was to improve the code generation process responsible for generating the Vulkan API call encoding and decoding code, to address some code maintenance and Vulkan API version update issues present with the existing vktrace software. It has also offered an opportunity to explore potential performance and feature enhancements, such as compression for capture files (currently available) and support for multi-threaded replay (to be added in the future).

GFXReconstruct's software architecture is API-agnostic. Capture and replay of D3D12 applications has also been added, including support for DXR workloads.


The GFXReconstruct project is currently Beta quality software. The primary consideration for stability is the capture file format. While this format does not change regularly, it is not yet finalized and may change in ways that are incompatible with the existing format as new features (eg. multi-threaded replay and trimming) are implemented. Once these features are implemented and considered stable, the file format will be assigned a 1.0 version, at which point backward compatibility will be guaranteed across GFXReconstruct versions.

Project Components

The GFXReconstruct project provides tools for the capture and replay of Vulkan and D3D12 API calls, allowing the graphics commands executed by an application to be recorded to a file that may later be replayed to reconstruct the graphics-specific behavior of the captured application. The replay code has been organized with a framework design to make it easy to create additional tools for processing capture files.

The GFXReconstruct components currently provided with this repository are:

  • The VK_LAYER_LUNARG_gfxreconstruct Vulkan layer for capturing Vulkan application commands.
  • The D3D12 capture libraries for capturing D3D12 application commands.
  • The gfxrecon-replay tool to replay GFXReconstruct capture files.
  • The gfxrecon-info tool to print information describing GFXReconstruct capture files.
  • The gfxrecon-compress tool to compress/decompress GFXReconstruct capture files.
    • NOTE: The gfxrecon-compress tool requires LZ4, Zstandard, and/or zlib, which are currently optional build dependencies.
  • The gfxrecon-extract tool to extract SPIR-V binaries from GFXReconstruct capture files.
  • The gfxrecon-convert tool to convert GFXReconstruct capture files to a JSON Lines listing of API calls.
  • The gfxrecon-optimize tool to produce new capture files with improved replay performance.


If you intend to contribute, the preferred work flow is for you to develop your contribution in a fork of this repo in your GitHub account and then submit a pull request. Please see the CONTRIBUTING file in this repository for more details


Instructions for building the contents of this repository can be found in the documentation.


Instructions for using the GFXReconstruct capture and replay tools can be found at the following locations:


This work is licensed under the terms of the MIT License; see LICENSE for more information.

Appropriate Use

GFXReconstruct is a suite of tools intended for the purpose of improving application and platform quality by allowing the analysis of capture and replay of graphics command streams. Use cases include, for example, regression testing, silicon and platform bringup, and reporting bugs. Using GFXReconstruct to extract assets from an application or game for which you don’t have an appropriate license may violate copyrights or software licenses.