Skip to content

Add proper offscreen frame boundary handling #2507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
marius-pelegrin-arm wants to merge 4 commits into from
Closed

Add proper offscreen frame boundary handling #2507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d5ec287
Fix and cleanup swapchain options
marius-pelegrin-arm Nov 6, 2025
66fce6c
Add proper offscreen frame boundary handling
marius-pelegrin-arm Oct 28, 2025
b6e9814
Refactor 'FindExtFrameBoundaryImage' utility as typesafe template
fabian-lunarg Dec 2, 2025
b94f3c3
Fix offscreen frame boundary increment
marius-pelegrin-arm Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions USAGE_android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -898,14 +898,8 @@ options:
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR. (forwarded to
replay tool).
--offscreen-swapchain-frame-boundary
Should only be used with offscreen swapchain.
Activates the extension VK_EXT_frame_boundary (always
supported if trimming, checks for driver support
otherwise) and inserts command buffer submission with
VkFrameBoundaryEXT where vkQueuePresentKHR was called
in the original capture. This allows preserving frames
when capturing a replay that uses. offscreen
swapchain. (forwarded to replay tool)
Deprecated. Alias to `--use-ext-frame-boundary`.
(forwarded to replay tool)
--mfr START-END, --measurement-frame-range START-END
Custom framerange to measure FPS for. This range will
include the start frame but not the end frame. The
Expand All @@ -930,6 +924,11 @@ options:
for all current GPU work to finish at the start and
end of the measurement range. (forwarded to replay
tool)
--use-ext-frame-boundary
Convert all frame boundaries (offscreen and onscreen)
to `VKFrameBoundaryEXT` submissions.
This option automatically triggers `--swapchain offscreen`.
(forwarded to replay tool)
--flush-inside-measurement-range
If this is specified the replayer will flush and wait
for all current GPU work to finish at end of each
Expand Down
16 changes: 8 additions & 8 deletions USAGE_desktop_Vulkan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -768,7 +768,9 @@ Optional arguments:
virtual Virtual Swapchain of images which match
the swapchain in effect at capture time and
which are copied to the underlying swapchain of the
implementation being replayed on. This is default.
implementation being replayed on. Also displays
offscreen frame boundaries to an additional window.
This is default.
captured Use the swapchain indices stored in the
capture directly on the swapchain setup for replay.
offscreen Disable creating swapchains, surfaces
Expand Down Expand Up @@ -803,6 +805,10 @@ Optional arguments:
If this is specified the replayer will flush
and wait for all current GPU work to finish at the
start and end of the measurement range.
--use-ext-frame-boundary
Convert all frame boundaries (offscreen and onscreen) to
`VKFrameBoundaryEXT` submissions.
This option automatically triggers `--swapchain offscreen`.
--flush-inside-measurement-range
If this is specified the replayer will flush and wait
for all current GPU work to finish at the end of each
Expand All @@ -812,13 +818,7 @@ Optional arguments:
Check if color space is not supported by replay device and
fallback to VK_COLOR_SPACE_SRGB_NONLINEAR_KHR.
--offscreen-swapchain-frame-boundary
Should only be used with offscreen swapchain.
Activates the extension VK_EXT_frame_boundary (always supported if
trimming, checks for driver support otherwise) and inserts command
buffer submission with VkFrameBoundaryEXT where vkQueuePresentKHR
was called in the original capture.
This allows preserving frames when capturing a replay that uses.
offscreen swapchain.
Deprecated. Alias to `--use-ext-frame-boundary`.
--sgfs <status>
Specify behavior to skip calls to vkWaitForFences and vkGetFenceStatus:
status=0 : Don't skip
Expand Down
6 changes: 5 additions & 1 deletion android/scripts/gfxrecon.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,8 @@ def CreateReplayParser():
parser.add_argument('--validate', action='store_true', default=False, help='Enables the Khronos Vulkan validation layer (forwarded to replay tool)')
parser.add_argument('--onhb', '--omit-null-hardware-buffers', action='store_true', default=False, help='Omit Vulkan calls that would pass a NULL AHardwareBuffer* (forwarded to replay tool)')
parser.add_argument('--use-colorspace-fallback', action='store_true', default=False, help='Swap the swapchain color space if unsupported by replay device. Check if color space is not supported by replay device and swap to VK_COLOR_SPACE_SRGB_NONLINEAR_KHR. (forwarded to replay tool).')
parser.add_argument('--offscreen-swapchain-frame-boundary', action='store_true', default=False, help='Should only be used with offscreen swapchain. Activates the extension VK_EXT_frame_boundary (always supported if trimming, checks for driver support otherwise) and inserts command buffer submission with VkFrameBoundaryEXT where vkQueuePresentKHR was called in the original capture. This allows preserving frames when capturing a replay that uses. offscreen swapchain. (forwarded to replay tool)')
parser.add_argument('--offscreen-swapchain-frame-boundary', action='store_true', default=False, help='Deprecated. Alias to `--use-ext-frame-boundary`. (forwarded to replay tool)')
parser.add_argument('--use-ext-frame-boundary', action='store_true', default=False, help='Convert all frame boundaries (offscreen and onscreen) to `VKFrameBoundaryEXT` submissions. This option automatically triggers `--swapchain offscreen`. (forwarded to replay tool)')
parser.add_argument('--mfr', '--measurement-frame-range', metavar='START-END', help='Custom framerange to measure FPS for. This range will include the start frame but not the end frame. The measurement frame range defaults to all frames except the loading frame but can be configured for any range. If the end frame is past the last frame in the trace it will be clamped to the frame after the last (so in that case the results would include the last frame). (forwarded to replay tool)')
parser.add_argument('--measurement-file', metavar='DEVICE_FILE', help='Write measurements to a file at the specified path. Default is: \'/sdcard/gfxrecon-measurements.json\' on android and \'./gfxrecon-measurements.json\' on desktop. (forwarded to replay tool)')
parser.add_argument('--quit-after-measurement-range', action='store_true', default=False, help='If this is specified the replayer will abort when it reaches the <end_frame> specified in the --measurement-frame-range argument. (forwarded to replay tool)')
Expand Down Expand Up @@ -266,6 +267,9 @@ def MakeExtrasString(args):
if args.offscreen_swapchain_frame_boundary:
arg_list.append('--offscreen-swapchain-frame-boundary')

if args.use_ext_frame_boundary:
Copy link
Contributor

@MarkY-LunarG MarkY-LunarG Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if "force_ext_frame_boundary" might be a better name for all of these.

arg_list.append('--use-ext-frame-boundary')

if args.vssb:
arg_list.append('--vssb')

Expand Down
7 changes: 7 additions & 0 deletions framework/decode/custom_vulkan_struct_decoders.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,13 @@
GFXRECON_BEGIN_NAMESPACE(gfxrecon)
GFXRECON_BEGIN_NAMESPACE(decode)

struct Decoded_VkBaseInStructure
{
using struct_type = VkBaseInStructure;
const VkBaseInStructure* decoded_value{ nullptr };
const PNextNode* pNext{ nullptr };
};

// Decoded union wrappers.
struct Decoded_VkClearColorValue
{
Expand Down
4 changes: 2 additions & 2 deletions framework/decode/replay_options.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ struct ReplayOptions
bool flush_measurement_frame_range{ false };
bool flush_inside_measurement_range{ false };
bool force_windowed{ false };
uint32_t windowed_width{ 0 };
uint32_t windowed_height{ 0 };
uint32_t windowed_width{ 320 };
uint32_t windowed_height{ 240 };
Copy link
Contributor

@fabian-lunarg fabian-lunarg Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does that mean? where/how did we populate windowed_width / windowed_height
before?

don't think we should change here.
this should rather define an (invalid) default-state for the struct.
and another place would be better suited to set default values windowed_width/height

Copy link
Contributor Author

@marius-pelegrin-arm marius-pelegrin-arm Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the default place for initialization of all replay options. These magic numbers come from "magic constants" I erased at the top of vulkan_swapchain.h

The PR is cut into two commits and the first commit is just cleaning these default values and how the values are (not) transferred to the WSI

bool force_windowed_origin{ false };
int32_t window_topleft_x{ 0 };
int32_t window_topleft_y{ 0 };
Expand Down
83 changes: 81 additions & 2 deletions framework/decode/vulkan_captured_swapchain.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,85 @@ void VulkanCapturedSwapchain::CmdPipelineBarrier2(PFN_vkCmdPipelineBarrier2 func
func(command_buffer, pDependencyInfo);
}

void VulkanCapturedSwapchain::FrameBoundaryANDROID(PFN_vkFrameBoundaryANDROID func,
const VulkanDeviceInfo* device_info,
const VulkanSemaphoreInfo* semaphore_info,
const VulkanImageInfo* image_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const graphics::VulkanDeviceTable* device_table,
application::Application* application)
{
GFXRECON_UNREFERENCED_PARAMETER(instance_info);
GFXRECON_UNREFERENCED_PARAMETER(instance_table);
GFXRECON_UNREFERENCED_PARAMETER(device_table);
GFXRECON_UNREFERENCED_PARAMETER(application);

GFXRECON_ASSERT(device_info != nullptr);

VkDevice device = device_info->handle;
VkSemaphore semaphore = (semaphore_info == nullptr ? VK_NULL_HANDLE : semaphore_info->handle);
VkImage image = (image_info == nullptr ? VK_NULL_HANDLE : image_info->handle);

func(device, semaphore, image);
}

VkResult VulkanCapturedSwapchain::QueueSubmit(PFN_vkQueueSubmit func,
const VulkanQueueInfo* queue_info,
uint32_t submit_count,
const VkSubmitInfo* submit_infos,
const Decoded_VkSubmitInfo* meta_submit_infos,
const VulkanFenceInfo* fence_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const VulkanDeviceInfo* device_info,
const graphics::VulkanDeviceTable* device_table,
application::Application* application,
const CommonObjectInfoTable& object_info_table)
{
GFXRECON_UNREFERENCED_PARAMETER(meta_submit_infos);
GFXRECON_UNREFERENCED_PARAMETER(instance_info);
GFXRECON_UNREFERENCED_PARAMETER(instance_table);
GFXRECON_UNREFERENCED_PARAMETER(device_info);
GFXRECON_UNREFERENCED_PARAMETER(device_table);
GFXRECON_UNREFERENCED_PARAMETER(application);
GFXRECON_UNREFERENCED_PARAMETER(object_info_table);

GFXRECON_ASSERT(queue_info != nullptr && (submit_infos != nullptr || submit_count == 0));

VkFence fence = (fence_info == nullptr ? VK_NULL_HANDLE : fence_info->handle);

return func(queue_info->handle, submit_count, submit_infos, fence);
}

VkResult VulkanCapturedSwapchain::QueueSubmit2(PFN_vkQueueSubmit2 func,
const VulkanQueueInfo* queue_info,
uint32_t submit_count,
const VkSubmitInfo2* submit_infos,
const Decoded_VkSubmitInfo2* meta_submit_infos,
const VulkanFenceInfo* fence_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const VulkanDeviceInfo* device_info,
const graphics::VulkanDeviceTable* device_table,
application::Application* application,
const CommonObjectInfoTable& object_info_table)
{
GFXRECON_UNREFERENCED_PARAMETER(meta_submit_infos);
GFXRECON_UNREFERENCED_PARAMETER(instance_info);
GFXRECON_UNREFERENCED_PARAMETER(instance_table);
GFXRECON_UNREFERENCED_PARAMETER(device_info);
GFXRECON_UNREFERENCED_PARAMETER(device_table);
GFXRECON_UNREFERENCED_PARAMETER(application);
GFXRECON_UNREFERENCED_PARAMETER(object_info_table);

GFXRECON_ASSERT(queue_info != nullptr && (submit_infos != nullptr || submit_count == 0));

VkFence fence = (fence_info == nullptr ? VK_NULL_HANDLE : fence_info->handle);

return func(queue_info->handle, submit_count, submit_infos, fence);
}

void VulkanCapturedSwapchain::ProcessSetSwapchainImageStateCommand(
const VulkanDeviceInfo* device_info,
VulkanSwapchainKHRInfo* swapchain_info,
Expand Down Expand Up @@ -455,8 +534,8 @@ void VulkanCapturedSwapchain::ProcessSetSwapchainImageStatePreAcquire(
VkImageLayout image_layout = static_cast<VkImageLayout>(image_info[image_index].image_layout);
if ((result == VK_SUCCESS) && (image_layout != VK_IMAGE_LAYOUT_UNDEFINED))
{
image_barrier.newLayout = image_layout;
image_barrier.image = image;
image_barrier.newLayout = image_layout;
image_barrier.image = image;
image_barrier.subresourceRange.aspectMask = graphics::GetFormatAspects(image_entry->format);

result = device_table_->BeginCommandBuffer(transition_command, &begin_info);
Expand Down
35 changes: 35 additions & 0 deletions framework/decode/vulkan_captured_swapchain.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,41 @@ class VulkanCapturedSwapchain : public VulkanSwapchain
VulkanCommandBufferInfo* command_buffer_info,
const VkDependencyInfo* pDependencyInfo) override;

virtual void FrameBoundaryANDROID(PFN_vkFrameBoundaryANDROID func,
const VulkanDeviceInfo* device_info,
const VulkanSemaphoreInfo* semaphore_info,
const VulkanImageInfo* image_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const graphics::VulkanDeviceTable* device_table,
application::Application* application) override;

virtual VkResult QueueSubmit(PFN_vkQueueSubmit func,
const VulkanQueueInfo* queue_info,
uint32_t submit_count,
const VkSubmitInfo* submit_infos,
const Decoded_VkSubmitInfo* meta_submit_infos,
const VulkanFenceInfo* fence_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const VulkanDeviceInfo* device_info,
const graphics::VulkanDeviceTable* device_table,
application::Application* application,
const CommonObjectInfoTable& object_info_table) override;

virtual VkResult QueueSubmit2(PFN_vkQueueSubmit2 func,
const VulkanQueueInfo* queue_info,
uint32_t submit_count,
const VkSubmitInfo2* submit_infos,
const Decoded_VkSubmitInfo2* meta_submit_infos,
const VulkanFenceInfo* fence_info,
VulkanInstanceInfo* instance_info,
const graphics::VulkanInstanceTable* instance_table,
const VulkanDeviceInfo* device_info,
const graphics::VulkanDeviceTable* device_table,
application::Application* application,
const CommonObjectInfoTable& object_info_table) override;

virtual void ProcessSetSwapchainImageStateCommand(const VulkanDeviceInfo* device_info,
VulkanSwapchainKHRInfo* swapchain_info,
uint32_t last_presented_image,
Expand Down
Loading
Loading