Swappy for Vulkan

A structure enabling you to provide your own Vulkan function wrappers by calling SwappyVk_setFunctionProvider.

Usage of this functionality is optional.

Clears the frame statistics collected so far.

All the frame statistics collected are reset to 0, frame statistics are collected normally after this call. See SwappyVk_enableStats for more conditions.

Destroy any swapchains associated with the device and clean up the device's resources.

This function should be called after SwappyVk_destroySwapchain if you no longer need the device.

Destroy the SwappyVk instance associated with a swapchain.

This API is expected to be called before calling vkDestroySwapchainKHR() so Swappy can cleanup its internal state.

Determine any Vulkan device extensions that must be enabled for a new VkDevice.

Swappy-for-Vulkan (SwappyVk) benefits from certain Vulkan device extensions (e.g. VK_GOOGLE_display_timing). Before the application calls vkCreateDevice, SwappyVk needs to look at the list of available extensions (returned by vkEnumerateDeviceExtensionProperties) and potentially identify one or more extensions that the application must add to:

• VkDeviceCreateInfo::enabledExtensionCount
• VkDeviceCreateInfo::ppEnabledExtensionNames

before the application calls vkCreateDevice. For each VkPhysicalDevice that the application will call vkCreateDevice for, the application must call this function, and then must add the identified extension(s) to the list that are enabled for the VkDevice. Similar to many Vulkan functions, this function can be called twice, once to identify the number of required extensions, and again with application-allocated memory that the function can write into.

Toggle statistics collection on/off.

By default, stats collection is off and there is no overhead related to stats. An app can turn on stats collection by calling SwappyVk_enableStats(swapchain, true). Then, the app is expected to call SwappyVk_recordFrameStart for each frame before starting to do any CPU related work. Stats will be logged to logcat with a 'FrameStatistics' tag. An app can get the stats by calling SwappyVk_getStats.

SwappyVk_initAndGetRefreshCycleDuration must have been called successfully before for this swapchain, otherwise there is no effect in this call. Frame stats are only available if the platform supports VK_GOOGLE_display_timing extension.

Get the fence timeout parameter, for devices with faulty drivers.

Its default value is 50,000,000.

Returns the stats collected, if statistics collection was toggled on.

Given that this API uses VkSwapchainKHR and the potential for this call to be done on different threads, all calls to SwappyVk_getStats must be externally synchronized with other SwappyVk calls. Unsynchronized calls may lead to undefined behavior. See SwappyVk_enableStats for more conditions.

See also: SwappyStats

Get the supported refresh periods of this device.

Call once with out_refreshrates set to nullptr to get the number of supported refresh periods, then call again passing that number as allocated_entries and an array of size equal to allocated_entries that will be filled with the refresh periods.

Get the swap interval value, in nanoseconds, for a given swapchain.

Initialize SwappyVk for a given device and swapchain, and obtain the approximate time duration between vertical-blanking periods.

Uses JNI to query AppVsyncOffset and PresentationDeadline.

If your application presents to more than one swapchain at a time, you must call this for each swapchain before calling swappyVkSetSwapInterval() for it.

The duration between vertical-blanking periods (an interval) is expressed as the approximate number of nanoseconds between vertical-blanking periods of the swapchain’s physical display.

If the application converts this number to a fraction (e.g. 16,666,666 nsec to 0.016666666) and divides one by that fraction, it will be the approximate refresh rate of the display (e.g. 16,666,666 nanoseconds corresponds to a 60Hz display, 11,111,111 nsec corresponds to a 90Hz display).

Inject callback functions to be called each frame.

Check if Swappy is enabled for the specified swapchain.

Tell Swappy to present one or more images to corresponding swapchains.

Swappy will call vkQueuePresentKHR for your application. Swappy may insert a struct to the pNext-chain of VkPresentInfoKHR, or it may insert other Vulkan commands in order to attempt to honor the desired swap interval.

Note:If your application presents to more than one swapchain at a time, and if you use a different swap interval for each swapchain, Swappy will attempt to honor the swap interval for each swapchain (being more successful on devices that support an underlying presentation-timing extension, such as VK_GOOGLE_display_timing).

Should be called if stats have been enabled with SwappyVk_enableStats.

When stats collection is enabled with SwappyVk_enableStats, the app is expected to call this function for each frame before starting to do any CPU related work. It is assumed that this function will be called after a successful call to vkAcquireNextImageKHR. See SwappyVk_enableStats for more conditions.

See also:SwappyVk_enableStats.

Enables Auto-Pipeline-Mode feature for all instances.

By default this feature is enabled. Changing it is completely optional for fine-tuning swappy behaviour.

Enables Auto-Swap-Interval feature for all instances.

By default this feature is enabled. Changing it is completely optional for fine-tuning swappy behaviour.

The fence timeout parameter can be set for devices with faulty drivers.

Its default value is 50,000,000.

Set the Vulkan function provider.

This enables you to provide an object that will be used to look up Vulkan functions, e.g. to hook usage of these functions.

To use this functionality, you must call this function before any others.

Usage of this function is entirely optional. If you do not use it, the Vulkan functions required by Swappy will be dynamically loaded from libvulkan.so.

Sets the maximal swap duration for all instances.

Sets the maximal duration for Auto-Swap-Interval in milliseconds. If SwappyVk is operating in Auto-Swap-Interval and the frame duration is longer than the provided duration, SwappyVk will not do any pacing and just submit the frame as soon as possible.

Tell Swappy the queueFamilyIndex used to create a specific VkQueue.

Swappy needs to know the queueFamilyIndex used for creating a specific VkQueue so it can use it when presenting.

Tell Swappy the duration of that each presented image should be visible.

If your application presents to more than one swapchain at a time, you must call this for each swapchain before presenting to it.

Tell Swappy which ANativeWindow to use when calling to ANativeWindow_* API.

Remove callbacks that were previously added using SwappyVk_injectTracer.

Only removes callbacks that were previously added using SwappyVK_injectTracer. If SwappyVK_injectTracker was not called with the tracer, then there is no effect.