Getting Started with Installation and Setup
This is the second 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 back to our blog series on GFXReconstruct, the open-source tool for capturing and replaying graphics API calls to debug and analyze applications. If you missed the introduction in Part 1, check it out here for an overview of what GFXReconstruct can do and why it’s a game-changer for graphics developers. In this post, we’ll focus on getting you up and running with GFXReconstruct for Vulkan on Windows and Linux, as well as DirectX 12 on Windows. Our aim is to make onboarding straightforward, so you can start capturing and replaying API calls without unnecessary hurdles. Note that this guide doesn’t cover Android or macOS setups—those will be addressed in future posts in this series.
GFXReconstruct provides a Vulkan capture layer (VK_LAYER_LUNARG_gfxreconstruct), helper capture scripts like gfxrecon-capture-vulkan.py, and a suite of processing tools including:
- gfxrecon-replay (replay)
- gfxrecon-info (introspection)
- gfxrecon-compress (compression)
- gfxrecon-convert (JSON Lines conversion)
- gfxrecon-extract (SPIR-V extraction)
- gfxrecon-optimize (performance optimization), and
- gfxrecon-tocpp (experimental code generation).
We’ll touch on how these fit into the setup process.
Prerequisites for Vulkan and DirectX
For Vulkan (Windows and Linux)
- Operating System: Windows 10/11 (64-bit) or a modern Linux distribution (e.g., Ubuntu 20.04+).
- Vulkan SDK: Download and install the latest Vulkan SDK from LunarG’s website. This includes the Vulkan headers, loader, and GFXReconstruct binaries. Minimum version: SDK 1.3.243 or later for full features.
- Python 3: Version 3.6 or higher, required for capture scripts like gfxrecon-capture-vulkan.py.
- Hardware: A Vulkan-compatible GPU (e.g., NVIDIA GTX 10-series or later, AMD RX 500-series or later).
- Additional for Linux: GCC 7+ and CMake 3.24+ if building from source.
For DirectX 12 (Windows Only)
- Operating System: Windows 10/11 (64-bit) with DirectX 12 support enabled.
- GFXReconstruct Binaries: To get prebuilt binaries that include DirectX 12 support, download the latest GFXReconstruct release from https://github.com/LunarG/gfxreconstruct/releases. Note that DirectX 12 support is not included in the Vulkan SDK build of GFXReconstruct.
- Windows SDK: Version 10.0.26100 or later, installed via Visual Studio or standalone download from Microsoft.
- Hardware: A DirectX 12-compatible GPU (e.g., NVIDIA GTX 900-series or later, AMD RX 400-series or later).
- Python 3: As above, for scripts.
Once installed, verify your Vulkan setup by running vulkaninfo from the SDK (it should list your GPU and supported features). For DirectX 12, use the DirectX Diagnostic Tool (dxdiag) to confirm DX12 support.
Building from Source vs. Prebuilt Binaries
Getting GFXReconstruct up and running is pretty straightforward, whether you grab the ready-to-go binaries or roll up your sleeves and build it from source. For most folks, prebuilt binaries are the way to go for a quick start. But if you’re itching to tweak things or play with experimental features, go ahead and build from source. Here’s the lowdown, made simple.
Prebuilt Binaries: The Easy Route
Want to hit the ground running? Snag GFXReconstruct through the Vulkan SDK or GitHub releases.
- Vulkan SDK Route:
- Head to vulkan.lunarg.com and download the installer.
- Run it, stick with the default settings, and you’re set. On Windows, it adds tools like gfxrecon-replay to your PATH. On Linux, it sorts out the layers automatically.
- Find the tools in the SDK’s Bin folder—ready to roll!
- Heads-up: DirectX 12 support is not included in the Vulkan SDK build of GFXReconstruct
- GitHub Releases for DirectX 12:
- Need DX12? Grab the latest prebuilt binaries from https://github.com/LunarG/gfxreconstruct/releases.
- These are stable, compatible, and ready to use.
- This is the hassle-free option—perfect for jumping straight into capturing and replaying Vulkan or DX12 workloads.
Building from Source: For the Tinkerers
If you need the latest development changes, want to enable experimental features (e.g. OpenXR), or customize build options, build from source instead of using the SDK.
Step 1: Grab the Code
git clone https://github.com/LunarG/gfxreconstruct.git --branch main
cd gfxreconstruct
git submodule update --init
If you want bleeding-edge features or want to extend GFXReconstruct and make a Pull Request, check out the dev branch.
Step 2: Get Your Tools Ready
Check BUILD.md for the latest, but here’s the overview:
- CMake: 3.24+ is recommended.
- Python: 3.6+ for build script and code generation.
- Compiler:
- Windows: Visual Studio 2019 or 2022 with the Desktop C++ workload.
- Linux: GCC 9+ (or Clang) with C++17 support.
- Windows SDK: Use 10.0.26100.0 for DX12 (set with -DCMAKE_SYSTEM_VERSION=10.0.26100.0 if you’ve got multiple SDKs).
- Vulkan SDK: Needed for headers and loader during dev (or grab Vulkan headers via system packages).
- Linux Extras: Install X11/XCB and/or Wayland dev packages x (check BUILD.md for specifics).
Step 3: Easy Mode—Use the Build Script
The helper build script handles submodule sync, configuration, and build.
python scripts/build.py --skip-check-code-style --skip-tests -c Release
Handy flags to know:
- –skip-d3d12-support: Skip DX12 to keep things light.
- –skip-tests: Speed things up by skipping test apps.
- -a arm64: Build for Windows ARM64 (if you’re on an ARM host).
Step 4: Manual CMake (If You Want Control)
Prefer doing it by hand? Here’s how:
- Linux/macOS (Single-config, e.g., Ninja or Makefiles):
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
- Windows (Multi-config, e.g., Visual Studio):
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_SYSTEM_VERSION=10.0.26100.0
cmake --build build --config Release
Useful CMake options:
- -DD3D12_SUPPORT=OFF: skip DX12 components
- -DGFXRECON_ENABLE_OPENXR=OFF: Disable OpenXR
- -DUSE_CCACHE=On: Faster rebuilds with ccache
Step 5: Install (Optional)
Want a clean setup like the SDK? Install the artifacts:
cmake --install build --config Release --prefix ./install
This puts tools like gfxrecon-replay in install/bin/. Skip this, and you’ll find outputs scattered in the build folder (especially messy with Visual Studio’s multi-config setup).
Step 6: Check Your Work
List the tools produced with the following command:
ls install/bin
Depending on the options you chose, you should see:
- gfxrecon-replay
- gfxrecon-info
- gfxrecon-compress
- gfxrecon-convert
- gfxrecon-extract
- gfxrecon-optimize
- gfxrecon-tocpp
- helper scripts like gfxrecon-capture-vulkan.py
Which Should You Choose?
Prebuilt binaries are a no-brainer for quick setup and guaranteed stability. Building from source is perfect if you’re tweaking, experimenting, or chasing the latest features. Either way, you’re now set to capture and replay like a pro.
Checking Your Setup
Once you’ve got GFXReconstruct installed (whether through the Vulkan SDK, a source build, or a quick install), do a fast test to make sure everything’s working for Vulkan and DirectX 12. This section breaks it down into simple, repeatable steps, straight from the official docs.
Step 1: Make the Layer Discoverable
- If you used the Vulkan SDK or ran cmake –install, you should be good to go.
- If you built GFXReconstruct locally and didn’t install it, tell Vulkan where to find the layer by setting VK_LAYER_PATH. For example:
- Windows (command prompt):
set VK_LAYER_PATH=C:\gfxreconstruct\build\layer\Debug;%VK_LAYER_PATH%
- Linux/macOS (terminal):
export VK_LAYER_PATH=/path/to/gfxreconstruct/build/layer:$VK_LAYER_PATH
Step 2: Enable the Layer
Pick one of these options:
- Option 1: Vulkan Configurator (vkconfig) GUI:
- Launch vkconfig from the Vulkan SDK.
- Create or select a configuration and enable the “GFXReconstruct” layer.
- Add your application (or set the configuration as active system-wide), then run from vkconfig.
- If you built locally without install, add your build’s layer manifest folder to vkconfig‘s Layer Paths so it can discover the layer.
- vkconfig applies the needed overrides (VK_INSTANCE_LAYERS and, if necessary, VK_LAYER_PATH) per-app—no manual env vars required.
- Option 2: Environment variable:
- Windows:
set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct
- Linux/macOS
export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_gfxreconstruct
Step 3: Capture a Test
Run a quick capture using the helper script:
gfxrecon-capture-vulkan.py -o test_vulkan.gfxr vkcube
- If vkcube isn’t in your PATH, use the full path (find it in the Vulkan SDK samples).
- Or, just run your own Vulkan app with the layer enabled. The capture file will be gfxrecon_capture.gfxr unless you set GFXRECON_CAPTURE_FILE to something else.
Step 4: Replay and check
- Replay the capture
gfxrecon-replay test_vulkan.gfxr
- Peek at the details
gfxrecon-info test_vulkan.gfxr
What’s a Win?
- The replay window (or headless mode) shows the frames you expect.
- No nasty errors in the log. If something’s funky, crank up the debug info with:
set GFXRECON_LOG_LEVEL=debug # Windows
export GFXRECON_LOG_LEVEL=debug # Linux/macOS
DirectX 12 Test (Windows Only)
Let’s get your DirectX 12 setup humming.
Step 1: Set up capture libraries
Drop these files next to your app’s executable (e.g., my_d3d12_app.exe):
- d3d12.dll
- dxgi.dll
- d3d12_capture.dll
(Grab these from the SDK or your build’s install folder. Delete them after testing to stop capturing.)
Step 2: Keep It Small (optional)
To avoid a massive capture file, limit the frame range. One way to do this is to set a key for toggling capture on and off.
set GFXRECON_CAPTURE_TRIGGER=F3
Want a custom file name? Set:
set GFXRECON_CAPTURE_FILE=dx12_test.gfxr
Step 3: Run Your App
Launch your app from the same Command Prompt (so the environment variables stick):
my_d3d12_app.exe
Play through your scene until you reach the desired starting point, then press the hotkey (e.g., F3) to begin recording. Advance to the end of your target frame range and press the hotkey again to stop. GFXReconstruct will automatically generate a .gfxr file (dx12_test.gfxr or gfxrecon_capture.gfxr) containing only those frames, plus any prerequisite state needed for replay.
Step 4: Replay and Inspect
Replay the capture:
gfxrecon-replay dx12_test.gfxr
Check the details:
gfxrecon-info dx12_test.gfxr
Optional—Optimize for performance:
gfxrecon-optimize -o dx12_test_opt.gfxr dx12_test.gfxr
What’s a Win?
- Replay finishes without “device removed” errors.
- If there’s visual output, it looks like what you expected.
Why This Matters
This quick test ensures your GFXReconstruct setup is solid, so you can capture and replay Vulkan or DirectX 12 workloads without a hitch. It’s like a handshake with your GPU—make sure it’s firm!
Common Options and Tools
|
Goal
|
Command/Action
|
|---|---|
|
Get more detailed output during capture
|
set/export GFXRECON_LOG_LEVEL=debug
|
|
Get more detailed output during replay
|
gfxrecon-replay --log-level debug
|
|
Convert to JSON (inspection)
|
gfxrecon-convert <file.gfxr>
# Creates a new file with the same name # but replaces .gfxr with .json |
Troubleshooting
Common issues and fixes:
- Layer Not Found: Confirm VK_INSTANCE_LAYERS is visible in the app’s environment and that the layer JSON is reachable (try setting VK_LAYER_PATH).
- Capture File Not Generated: Check if your app calls vkCreateInstance/vkDestroyInstance (Vulkan) or loads D3D12/DXGI (DirectX). Verify write permissions for the capture path.
- Memory Tracking Errors: Switch modes with GFXRECON_MEMORY_TRACKING_MODE=unassisted if page_guard conflicts (e.g., with debuggers).
- Replay Fails on DirectX 12: Ensure the Agility SDK is in a D3D12 folder next to gfxrecon-replay.exe. Optimize captures with gfxrecon-optimize for better performance.
- Very large files: Use frame ranges (GFXRECON_CAPTURE_FRAMES) or compress (gfxrecon-compress).
- Hotkey Not Working: Confirm supported keys (F1-F12, TAB, CTRL) and no conflicts with app input.
- Debugger breaks caused by layer memory tracking: disable SIGSEGV breaks in your debugger for the target app. Check USAGE_desktop_Vulkan.md for the LLDB/GDB commands.
- Very large files: Use a hotkey trigger to capture only the frames you need (set GFXRECON_CAPTURE_TRIGGER, e.g., F3, to create a trimmed capture), then optimize the resulting .gfxr to remove unused initial-state data: gfxrecon-optimize <input.gfxr> <output_opt.gfxr> Note: Optimization operates on trimmed captures (created via trigger or frame selection) and produces a smaller, faster-to-replay file.
- General Errors: Set GFXRECON_LOG_LEVEL=debug for detailed logs. Check the USAGE docs for API-specific tips.
If issues persist, consult the GFXReconstruct GitHub issues list.
With GFXReconstruct set up, you’re ready to capture and debug your graphics apps efficiently. Stay tuned for future posts on advanced usage, Android/macOS support, and more. Happy developing!
