How to Trim a GFXR File Using GFXReconstruct “Recapture”

If you’re working with graphics debugging or Vulkan application analysis, you’ve likely encountered GFXReconstruct—a powerful open-source tool by LunarG for capturing and replaying graphics API calls. But sometimes, those capture files can balloon in size—especially if you’re recording an entire session when you only need a small slice of it to reproduce a bug or analyze a specific moment.

One of the lesser-known but incredibly useful features of GFXReconstruct is the ability to “recapture” during replay, allowing you to trim a lengthy GFXR capture file down to a shorter, more focused version. In this blog post, we’ll go through the process step-by-step. (The discussion here refers to execution on a Windows or Linux or macOS desktop system. Trimming on Android is significantly different and will be the topic of a future tutorial.)

What is GFXReconstruct “Recapture”?

GFXReconstruct’s “recapture” process involves replaying an existing GFXR file with the capture layer enabled, letting you record a new, trimmed capture file that includes only the frames or sections you care about. This method leverages the replay process to create a new file—perfect for isolating specific moments in a graphics workload without slogging through the entire original capture.

Why Trim a GFXR File?

Trimming is invaluable when:

• You’re debugging a bug that occurs in a specific frame range.
• You want to share a concise capture with a colleague or report a bug without sending gigabytes of data.
• You need to optimize replay performance by focusing on a smaller subset of frames.

Let’s dive into how to do it!

Step-by-Step Guide to Trimming a GFXR File with Recapture

Prerequisites

Before starting, ensure you have:

• GFXReconstruct installed: You’ll need the tools (gfxrecon-replay, etc.) from the latest Vulkan SDK or built from the GitHub repository.
• A source GFXR file: This is the original capture you want to trim (e.g., original_capture.gfxr).
• A working Vulkan environment: Since recapture uses replay, your system must support Vulkan and be able to run the original capture successfully.
• Python: The gfxrecon-capture-vulkan.py script requires Python 3.5 or higher

Step 1: Understand Your Source File

First, get a sense of what’s in your original GFXR file. Use the gfxrecon-info tool to inspect it:

gfxrecon-info original_capture.gfxr

This will output details like the total frame count, helping you decide which frames to trim to. For example, if your bug appears around frame 100 to 150, that’s your target range.

Step 2: Capture API calls with a Python Convenience Script

python gfxrecon-capture-vulkan.py -o trimmed_capture.gfxr –capture-frames 100-150 gfxrecon-replay original_capture.gfxr

Explanation:

• -o trimmed_capture.gfxr: Specifies the file name for the new, trimmed capture file.
• –capture-frames 100-150: Specifies the frame range to recapture (replace with your desired range).
• gfxrecon-replay original_capture.gfxr: The capture file that is to be replayed and trimmed.

(Note: On some systems you may have to specify python3 instead of python.)

When you execute this command, here’s what happens:

You’ll see output indicating the replay process, and possibly a note like [gfxrecon] INFO – Recording graphics API capture to game_capture.gfxr if logging is not explicitly disabled.

GFXR will also add the trimming info and a timestamp to a capture file, so in this case it would output “game_capture_frames_100_through_150_{timestamp}.gfxr” where “timestamp” is something like “20250305T111451”.

Step 3: Verify the Trimmed File

Once the replay finishes, check your new file with gfxrecon-info:

gfxrecon-info trimmed_capture.gfxr

Confirm the frame count matches your expected range (e.g., 51 frames for 100-150). You can also replay it to ensure it captures the intended section:

gfxrecon-replay trimmed_capture.gfxr

Tips and Tricks

• Trim During “Live Capture”: You don’t have to capture instructions into a file. You can “trim” during a live session. The same options  and benefits apply, especially in combination with specifying the conditions for capturing data. It is still called “trimming” even though there’s no source file to trim (i.e., we’re “trimming” the commands from the live app).
• Logging for Debugging: If something goes wrong, set GFXRECON_LOG_LEVEL=debug to get detailed output during recapture.
• Performance: Recapture requires a live GPU, so ensure your system matches the original capture system’s configuration (same operating system, GPU, and driver version).  Ideally recapture should occur soon after capture, on the same system.
• Hotkey Alternative: Instead of a frame range, you can use –trigger {key}(e.g., use  F12 for “{key}”) to manually start/stop capturing during replay by pressing the hotkey. This is less precise but useful for interactive trimming.  Optionally provide –trigger-frames to limit triggered frames to a count.
• Optimize the Result: If your trimmed file still feels bloated, run

  gfxrecon-optimize trimmed_capture.gfxr optimized_capture.gfxr

  to remove unused resource data.

Why Not a Dedicated Trim Tool?

You might wonder why we’re jumping through these hoops instead of using a simple offline trim utility. While GFXReconstruct supports capturing specific frames during initial recording, trimming an existing file currently relies on this recapture method. A dedicated tool has been proposed (see GitHub issue #1109), but for now, recapture gets the job done—albeit with a bit more setup.

Wrap-Up

Trimming a GFXR file with GFXReconstruct’s recapture feature is a straightforward way to focus on the frames that matter. Whether you’re debugging a glitch, analyzing performance, or sharing a concise repro, this technique saves time and disk space. Give it a try next time you’re drowning in a sea of frames—your future self will thank you!

Got questions or run into issues? You can find the user’s guide for GFXReconstruct here. If that’s not sufficient, drop a comment below or hit up the GFXReconstruct community on GitHub. Happy debugging!