Initial frame looping by antonio-lunarg · Pull Request #2698 · LunarG/gfxreconstruct

antonio-lunarg · 2026-02-17T16:34:42Z

This PR introduces experimental frame looping for replay, so a selected frame can be replayed repeatedly for analysis/profiling.

Changes:

Add --loop-frame and --loop-count to replay options on desktop and Android, plus forwarding in android/scripts/gfxrecon.py.
Add graphics::FrameLoopInfo to track target frame, remaining iterations, and current looping state.
-Loop orchestration lives in Application::Run() so loop behavior follows application frame numbering (including trimmed traces).
Use PreloadFileProcessor automatically when looping is enabled, preload the target frame, and replay it by controlling advance (SetAdvanceToNextFrame).
Skip state blocks during loop iterations to avoid reapplying state setup every repeat.
Extend VulkanFrameLoopReplayConsumer to skip recreating already-created objects while looping (instance/device/swapchain/surfaces/AHB path).
Default pause_frame to uint32_t max to avoid accidental pause at frame 0 when looping starts.

Notes:

This functionality is currently experimental.
Implemented in the Vulkan replay path.

ci-tester-lunarg · 2026-02-20T10:32:06Z

CI gfxreconstruct build queued with queue ID 656236.

ci-tester-lunarg · 2026-02-20T10:35:01Z

CI gfxreconstruct build # 8901 running.

ci-tester-lunarg · 2026-02-20T11:19:19Z

CI gfxreconstruct build # 8901 passed.

tools/tool_settings.h

framework/application/application.cpp

jzulauf-lunarg

Preload section looks good, but I'm going to have to integrate this support in PR #2783 ... @antonio-lunarg -- if frame looping is going to change significantly, we should probably carefully align the changes so nothing gets dropped.

jzulauf-lunarg · 2026-03-16T23:29:27Z

framework/decode/preload_file_processor.cpp

        error_state_ = CheckFileStatus();
        return;
    }
+    if (!advance_to_next_frame_)


This feels more "contractual". Thinking assert in additional to check. The frame looping support state machine only current loads a single frame and only when advance_to_next_frame_ is enabled.

I added an assertion and integrated with more documentation on top of this function's signature.

jzulauf-lunarg · 2026-03-16T23:33:09Z

framework/application/application.cpp

+                // Quit when frame looping has finished.
+                if (frame_loop_info_->GetLoopIterations() == 0)
+                {
+                    running_ = false;


Is this because

a) we never want to continue past looping frame or
b) because we aren't confident that replay past looping is stable? (or are sure it isn't)

--quit-after-measurement-range controls this behavior for FpsInfo.. don't know if a separate --quit-after-looping would be needed.

a) I think we don't really care about continuing after looping, at the moment.
b) But I think replay past looping should work.

I suppose --quit-after-looping might be added later if someone wants it.

Then the someone adding --quit-after-looping would also wrap running_ = false; and break with e..g. if(frame_loop_info_->quit_after_looping)?

jzulauf-lunarg · 2026-03-16T23:51:09Z

framework/decode/preload_file_processor.cpp

        // as StartBlock does it lazily, and thus the last will be present.
        // NOTE: This must be done before SetBatchSinkProc, or we'll record it to preload
        block_parser_->GetBlockAllocator().FlushBatch();
        block_parser_->SetOperationMode(BlockParser::OperationMode::kEnqueued);


This mode means that we store the minimum needed. For uncompressed block, we store the "raw block" information and have the DispatchArgs directly reference it. However for compressed block (combined with BlockParser::DecompressionPolicy::kAlways below) we only the decompressed data and not the raw block data from the file.

For frame looping, I think we only care about being able to replay blocks. For compressed blocks, I would be happy do uncompress once and use the decompressed data later again and again.

jzulauf-lunarg · 2026-03-16T23:53:09Z

framework/decode/preload_file_processor.cpp


    // Use kAlways decompression policy to move the maximum amount of work outside the measurement loop
    auto save_decompression_policy = block_parser_->GetDecompressionPolicy();
    block_parser_->SetDecompressionPolicy(BlockParser::DecompressionPolicy::kAlways);


In order to support frame looping BlockParser::DecompressionPolicy::kAlways isn't just a performance optimization for accurate measurement required to prevent the the issue of having dispatch_args data members pointing at the most recently decompressed data (or stale pointers) on replay.

Probably needs some commentary about this.

I added a comment.

bradgrantham-lunarg · 2026-03-23T15:49:02Z

framework/application/application.cpp

+                    preload_processor->SkipStateBlocks();
+
+                    GFXRECON_LOG_INFO("Looping frame (%i iterations remaining)", frame_loop_info_->GetLoopIterations());
+                    frame_loop_info_->DecrementLoopIterations();


Are the loop iterations abstracted behind methods as a design principle or do you have an expectation here that this may be more than just -- at some point?

I think we can already wrap a couple of these lines within a frame_loop_info->EndFrame().
Or we might even wrap all of them by passing the file_processor as a parameter of EndFrame(..).
What do you think?

bradgrantham-lunarg · 2026-03-23T15:54:07Z

framework/application/application.h

    decode::FileProcessor*                                       file_processor_;    ///< The FileProcessor object responsible for decoding and processing capture file data.
    bool                                                         running_;           ///< Indicates that the application is actively processing system events for playback.
    bool                                                         paused_;            ///< Indicates that the playback has been paused.  When paused the application will stop rendering, but will continue processing system events.
+    graphics::FrameLoopInfo*                                     frame_loop_info_;   ///< Indicates that playback wishes to loop a certain frame


I don't want to cause this PR to be retested, so don't change it for this PR, but for changes in the future and for a possible edit to looping in a future PR, I think this would be better (since it's just a few uint32's and there are only 1 Applications) to embed frame looping info or other Application parameters directly in Application with defaults that mean "no frame looping" to avoid a potential bug in future PRs not checking "frame_loop_info != nullptr".

I actually have been talking with @jzulauf-lunarg about that. While FrameLoopInfo takes inspiration from FpsInfo, I noticed FpsInfo is quite useful for things related to frame-looping and I was also considering merging these two together into something like FrameInfo, focused on frames rather than the concept of frames-per-second.

I created an issue for this: #2810

bradgrantham-lunarg

Very cool, thank you!

bradgrantham-lunarg · 2026-03-23T16:02:42Z

framework/decode/preload_file_processor.cpp

-    if (at_end)
+bool PreloadFileProcessor::AdvanceToNextFrame(ProcessBlockState process_result)
+{
+    if (advance_to_next_frame_)


It seems like "whether to advance to next frame" is an application preference, but it's reaching its fingers into PreloadFileProcessor to do it. That is to say, AdvanceToNextFrame and maybe "move replay cursor" primitive make sense, but what would it mean to call AdvanceToNextFrame but have advance_to_next_frame_ be false? Why not have advance_to_next_frame_ be in the caller, and then whether to call PreloadNextFrames and AdvanceToNextFrame and "move replay cursor" would be up to the caller of FilePreloadProcessor?

The precedent for this is that there is already a SkipStateBlocks that controls playback and the cursor that is a primitive an application may choose to call, and then whether to skip isn't tracked by FilePreloadProcessor.

Please have a look at the last two commits: I replaced the advance_to_next_frame_ mode bit with two explicit functions: ReplayCurrentPreloadedFrame() and AdvancePreloadedFrame(). When looping, Application calls only the replay function and skips the advance, keeping the cursor on the same preloaded frame for every iteration.

MarkY-LunarG

LGTM. Great first step!

Add experimental frame looping by not advancing the preloaded frame after replaying a target frame. - Add `--loop-frame` and `--loop-count` replay options on desktop, Android, and in the launcher script. - Add `VulkanReplayFrameLoopConsumer` to enter loop mode at frame end, idle devices, not advancing to the next frame, and replay it. - Extend `PreloadFileProcessor` with `SetAdvanceToNextFrame()` to skip advancing to the next frame. - Allow Application to keep preloading while frame looping is active. Also, default `pause_frame` to uint32_t max. This is needed to avoid pausing the replay when frame looping is enabled for the first frame. In this case the frame counter is not incremented, therefore it is still 0 when it is checked against `pause_frame` (if default is 0) effectively matching its value which pauses replay. Setting pause_frame default to uint32_t max solves this edge case. Co-authored-by: Nick Driscoll <nick@lunarg.com>

When looping a frame, some objects have already been created during the first iteration of the frame, hence the corresponding vkCreate* commands should be skipped.

Use 0 as first frame index and uint32_t max as default number of loop iterations. Co-authored-by: Antonio Caggiano <antonio@lunarg.com>

Set advance to next frame even when not at loop frame.

When looping, make sure to skip any state blocks to avoid reappling them on each loop iteration.

Rejects empty, non-numeric, and zero values so replay settings only accept meaningful frame targets. Returns success only after the parsed value passes all checks, which makes invalid input handling more predictable and avoids treating frame zero as a usable loop point.

Track the current replay frame in FrameLoopInfo and use it to drive loop-frame preload and replay handling from Application::Run(). This removes the ad hoc local loop state and keeps loop decisions attached to the frame-loop state object.

Require frame-advance mode when preloading frames and document it. Fix IsFileValid() to require both a queued preload head and replay cursor before replaying preloaded frames.

Have ReplayOneFrame report the replay result and next cursor instead of mutating replay_cursor_ directly. Keep cursor advancement and frame-number updates in AdvanceToNextFrame() so preload replay state changes stay in one place.

Replace SetAdvanceToNextFrame() mode bit with explicit ReplayCurrentPreloadedFrame() and AdvancePreloadedFrame() primitives. Whether to advance is now the caller's decision: Application calls ReplayCurrentPreloadedFrame() directly when looping, and the normal ProcessNextFrame() path calls both in sequence. Remove the IsFileValid() override that existed solely to support the advance_to_next_frame_=false mode.

Centralize the "infinite iterations" sentinel for clarity and maintainability, and prevents accidental decrement of the infinite sentinel while preserving current finite-loop behavior.

antonio-lunarg requested review from jzulauf-lunarg and nickdriscoll-lunarg February 17, 2026 16:34

antonio-lunarg requested a review from a team as a code owner February 17, 2026 16:34

antonio-lunarg force-pushed the antonio-frame-loop branch 5 times, most recently from f960c13 to 99e019b Compare February 18, 2026 10:41

antonio-lunarg requested a review from panos-lunarg February 18, 2026 16:02

antonio-lunarg force-pushed the antonio-frame-loop branch 3 times, most recently from 18f0f40 to 4c702b9 Compare February 20, 2026 10:32

panos-lunarg reviewed Feb 23, 2026

View reviewed changes

tools/tool_settings.h Outdated Show resolved Hide resolved

antonio-lunarg added the approved-to-run-ci Can run CI check on internal LunarG machines label Mar 5, 2026

antonio-lunarg force-pushed the antonio-frame-loop branch 2 times, most recently from 0471206 to fca3ffa Compare March 9, 2026 10:44

nickdriscoll-lunarg force-pushed the antonio-frame-loop branch from ed9f6ec to fca3ffa Compare March 9, 2026 16:19

antonio-lunarg force-pushed the antonio-frame-loop branch from fca3ffa to 4cc69c6 Compare March 12, 2026 10:54

antonio-lunarg changed the title ~~Experimental frame looping~~ Initial frame looping Mar 12, 2026

nickdriscoll-lunarg reviewed Mar 12, 2026

View reviewed changes

framework/application/application.cpp Outdated Show resolved Hide resolved

antonio-lunarg force-pushed the antonio-frame-loop branch 2 times, most recently from 603ed4f to fc6ddd4 Compare March 16, 2026 13:17

jzulauf-lunarg reviewed Mar 16, 2026

View reviewed changes

antonio-lunarg force-pushed the antonio-frame-loop branch 3 times, most recently from 505606c to 2fc373a Compare March 19, 2026 10:34

bradgrantham-lunarg reviewed Mar 23, 2026

View reviewed changes

bradgrantham-lunarg requested changes Mar 23, 2026

View reviewed changes

antonio-lunarg force-pushed the antonio-frame-loop branch 2 times, most recently from 4160f3c to 5777fec Compare March 24, 2026 11:21

antonio-lunarg requested a review from bradgrantham-lunarg March 25, 2026 11:17

antonio-lunarg force-pushed the antonio-frame-loop branch from 5777fec to d49e152 Compare March 31, 2026 11:17

MarkY-LunarG approved these changes Mar 31, 2026

View reviewed changes

antonio-lunarg force-pushed the antonio-frame-loop branch 2 times, most recently from c3f7ba2 to 4eacee5 Compare April 1, 2026 15:38

bradgrantham-lunarg approved these changes Apr 1, 2026

View reviewed changes

antonio-lunarg and others added 13 commits April 1, 2026 18:33

loop: Skip creating some objects

a3f41ce

When looping a frame, some objects have already been created during the first iteration of the frame, hence the corresponding vkCreate* commands should be skipped.

loop: Do not re-create AHB

96ba885

Add FrameLoopInfo

aa2ce8d

Use 0 as first frame index and uint32_t max as default number of loop iterations. Co-authored-by: Antonio Caggiano <antonio@lunarg.com>

loop: Fix loop logic and simplify consumer

3f1b17a

Set advance to next frame even when not at loop frame.

loop: Skip state blocks

18f9847

When looping, make sure to skip any state blocks to avoid reappling them on each loop iteration.

decode: Fix preload file validity for frame replay

a48a67c

Require frame-advance mode when preloading frames and document it. Fix IsFileValid() to require both a queued preload head and replay cursor before replaying preloaded frames.

fix regression

918c774

loop: Isolate preload replay state from cursor updates

0321991

Have ReplayOneFrame report the replay result and next cursor instead of mutating replay_cursor_ directly. Keep cursor advancement and frame-number updates in AdvanceToNextFrame() so preload replay state changes stay in one place.

loop: Add INFINITE_ITERATIONS and safe decrement

24e1eb5

Centralize the "infinite iterations" sentinel for clarity and maintainability, and prevents accidental decrement of the infinite sentinel while preserving current finite-loop behavior.

antonio-lunarg force-pushed the antonio-frame-loop branch from 4eacee5 to 24e1eb5 Compare April 1, 2026 16:33

antonio-lunarg merged commit 5cbaa50 into LunarG:dev Apr 1, 2026
7 checks passed

antonio-lunarg deleted the antonio-frame-loop branch April 2, 2026 06:48

Conversation

antonio-lunarg commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ci-tester-lunarg commented Feb 20, 2026

Uh oh!

ci-tester-lunarg commented Feb 20, 2026

Uh oh!

ci-tester-lunarg commented Feb 20, 2026

Uh oh!

Uh oh!

Uh oh!

jzulauf-lunarg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bradgrantham-lunarg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarkY-LunarG left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

antonio-lunarg commented Feb 17, 2026 •

edited

Loading