Swappy for Vulkan

Vulkan part of Swappy.

Summary

Typedefs
`SwappyVkFunctionProvider`	typedef `struct SwappyVkFunctionProvider` A structure enabling you to provide your own Vulkan function wrappers by calling SwappyVk_setFunctionProvider.

Functions
`SwappyVk_clearStats(VkSwapchainKHR swapchain)`	`void` Clears the frame statistics collected so far.
`SwappyVk_destroyDevice(VkDevice device)`	`void` Destroy any swapchains associated with the device and clean up the device's resources.
`SwappyVk_destroySwapchain(VkDevice device, VkSwapchainKHR swapchain)`	`void` Destroy the SwappyVk instance associated with a swapchain.
`SwappyVk_determineDeviceExtensions(VkPhysicalDevice physicalDevice, uint32_t availableExtensionCount, VkExtensionProperties pAvailableExtensions, uint32_t pRequiredExtensionCount, char **pRequiredExtensions)`	`void` Determine any Vulkan device extensions that must be enabled for a new VkDevice.
`SwappyVk_enableStats(VkSwapchainKHR swapchain, bool enabled)`	`void` Toggle statistics collection on/off.
`SwappyVk_getFenceTimeoutNS()`	`uint64_t` Get the fence timeout parameter, for devices with faulty drivers.
`SwappyVk_getStats(VkSwapchainKHR swapchain, SwappyStats *swappyStats)`	`void` Returns the stats collected, if statistics collection was toggled on.
`SwappyVk_getSupportedRefreshPeriodsNS(uint64_t *out_refreshrates, int allocated_entries, VkSwapchainKHR swapchain)`	`int` Get the supported refresh periods of this device.
`SwappyVk_getSwapIntervalNS(VkSwapchainKHR swapchain)`	`uint64_t` Get the swap interval value, in nanoseconds, for a given swapchain.
`SwappyVk_initAndGetRefreshCycleDuration(JNIEnv env, jobject jactivity, VkPhysicalDevice physicalDevice, VkDevice device, VkSwapchainKHR swapchain, uint64_t pRefreshDuration)`	`bool` Initialize SwappyVk for a given device and swapchain, and obtain the approximate time duration between vertical-blanking periods.
`SwappyVk_injectTracer(const SwappyTracer *tracer)`	`void` Inject callback functions to be called each frame.
`SwappyVk_isEnabled(VkSwapchainKHR swapchain, bool *isEnabled)`	`bool` Check if Swappy is enabled for the specified swapchain.
`SwappyVk_queuePresent(VkQueue queue, const VkPresentInfoKHR *pPresentInfo)`	`VkResult` Tell Swappy to present one or more images to corresponding swapchains.
`SwappyVk_recordFrameStart(VkQueue queue, VkSwapchainKHR swapchain, uint32_t image)`	`void` Should be called if stats have been enabled with SwappyVk_enableStats.
`SwappyVk_setAutoPipelineMode(bool enabled)`	`void` Enables Auto-Pipeline-Mode feature for all instances.
`SwappyVk_setAutoSwapInterval(bool enabled)`	`void` Enables Auto-Swap-Interval feature for all instances.
`SwappyVk_setFenceTimeoutNS(uint64_t fence_timeout_ns)`	`void` The fence timeout parameter can be set for devices with faulty drivers.
`SwappyVk_setFunctionProvider(const SwappyVkFunctionProvider *pSwappyVkFunctionProvider)`	`void` Set the Vulkan function provider.
`SwappyVk_setMaxAutoSwapIntervalNS(uint64_t max_swap_ns)`	`void` Sets the maximal swap duration for all instances.
`SwappyVk_setQueueFamilyIndex(VkDevice device, VkQueue queue, uint32_t queueFamilyIndex)`	`void` Tell Swappy the queueFamilyIndex used to create a specific VkQueue.
`SwappyVk_setSwapIntervalNS(VkDevice device, VkSwapchainKHR swapchain, uint64_t swap_ns)`	`void` Tell Swappy the duration of that each presented image should be visible.
`SwappyVk_setWindow(VkDevice device, VkSwapchainKHR swapchain, ANativeWindow *window)`	`void` Tell Swappy which ANativeWindow to use when calling to ANativeWindow_* API.
`SwappyVk_uninjectTracer(const SwappyTracer *tracer)`	`void` Remove callbacks that were previously added using SwappyVk_injectTracer.

Macros
`VK_NO_PROTOTYPES 1`

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

Typedefs

SwappyVkFunctionProvider

struct SwappyVkFunctionProvider SwappyVkFunctionProvider

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

Usage of this functionality is optional.

Functions

SwappyVk_clearStats

void SwappyVk_clearStats(
  VkSwapchainKHR swapchain
)

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.

Details

Parameters

swapchain

- The swapchain for which stats are being cleared.

SwappyVk_destroyDevice

void SwappyVk_destroyDevice(
  VkDevice device
)

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.

Details

Parameters

device

- The VkDevice associated with SwappyVk

SwappyVk_destroySwapchain

void SwappyVk_destroySwapchain(
  VkDevice device,
  VkSwapchainKHR swapchain
)

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.

Details

Parameters

`device`	- The VkDevice associated with SwappyVk
`swapchain`	- The VkSwapchainKHR the application wants Swappy to destroy

SwappyVk_determineDeviceExtensions

void SwappyVk_determineDeviceExtensions(
  VkPhysicalDevice physicalDevice,
  uint32_t availableExtensionCount,
  VkExtensionProperties *pAvailableExtensions,
  uint32_t *pRequiredExtensionCount,
  char **pRequiredExtensions
)

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.

Details

Parameters

`physicalDevice`	- The VkPhysicalDevice associated with the available extensions.
`availableExtensionCount`	- This is the returned value of pPropertyCount from vkEnumerateDeviceExtensionProperties.
`pAvailableExtensions`	- This is the returned value of pProperties from vkEnumerateDeviceExtensionProperties.
`pRequiredExtensionCount`	- If pRequiredExtensions is nullptr, the function sets this to the number of extensions that are required. If pRequiredExtensions is non-nullptr, this is the number of required extensions that the function should write into pRequiredExtensions.
`pRequiredExtensions`	- If non-nullptr, this is application-allocated memory into which the function will write the names of required extensions. It is a pointer to an array of char* strings (i.e. the same as VkDeviceCreateInfo::ppEnabledExtensionNames).

SwappyVk_enableStats

void SwappyVk_enableStats(
  VkSwapchainKHR swapchain,
  bool enabled
)

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.

Details

Parameters

`swapchain`	- The swapchain for which frame stat collection is configured.
`enabled`	- Whether to enable/disable frame stat collection.

SwappyVk_getFenceTimeoutNS

uint64_t SwappyVk_getFenceTimeoutNS()

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

Its default value is 50,000,000.

SwappyVk_getStats

void SwappyVk_getStats(
  VkSwapchainKHR swapchain,
  SwappyStats *swappyStats
)

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

Details

Parameters

`swapchain`	- The swapchain for which stats are being queried.
`swappyStats`	- Pointer to a SwappyStats that will be populated with the collected stats. Cannot be NULL.

SwappyVk_getSupportedRefreshPeriodsNS

int SwappyVk_getSupportedRefreshPeriodsNS(
  uint64_t *out_refreshrates,
  int allocated_entries,
  VkSwapchainKHR swapchain
)

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.

SwappyVk_getSwapIntervalNS

uint64_t SwappyVk_getSwapIntervalNS(
  VkSwapchainKHR swapchain
)

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

Details

Parameters

swapchain

- the swapchain to query

SwappyVk_initAndGetRefreshCycleDuration

bool SwappyVk_initAndGetRefreshCycleDuration(
  JNIEnv *env,
  jobject jactivity,
  VkPhysicalDevice physicalDevice,
  VkDevice device,
  VkSwapchainKHR swapchain,
  uint64_t *pRefreshDuration
)

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).

Details

Parameters

`env`	- JNIEnv that is assumed to be from AttachCurrentThread function
`jactivity`	- NativeActivity object handle, used for JNI
`physicalDevice`	- The VkPhysicalDevice associated with the swapchain
`device`	- The VkDevice associated with the swapchain
`swapchain`	- The VkSwapchainKHR the application wants Swappy to swap
`pRefreshDuration`	- The returned refresh cycle duration

Returns

bool - true if the value returned by pRefreshDuration is valid, otherwise false if an error.

SwappyVk_injectTracer

void SwappyVk_injectTracer(
  const SwappyTracer *tracer
)

Inject callback functions to be called each frame.

Details

Parameters

tracer

- Collection of callback functions

SwappyVk_isEnabled

bool SwappyVk_isEnabled(
  VkSwapchainKHR swapchain,
  bool *isEnabled
)

Check if Swappy is enabled for the specified swapchain.

Details
Returns	false if SwappyVk_initAndGetRefreshCycleDuration was not called for the specified swapchain, true otherwise.

SwappyVk_queuePresent

VkResult SwappyVk_queuePresent(
  VkQueue queue,
  const VkPresentInfoKHR *pPresentInfo
)

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).

Details

Parameters

`queue`	- The VkQueue associated with the device and swapchain
`pPresentInfo`	- A pointer to the VkPresentInfoKHR containing the information about what image(s) to present on which swapchain(s).

SwappyVk_recordFrameStart

void SwappyVk_recordFrameStart(
  VkQueue queue,
  VkSwapchainKHR swapchain,
  uint32_t image
)

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.

Details

Parameters

`queue`	- The VkQueue associated with the device and swapchain
`swapchain`	- The swapchain where the frame is presented to.
`image`	- The image in swapchain that corresponds to the frame.

SwappyVk_setAutoPipelineMode

void SwappyVk_setAutoPipelineMode(
  bool enabled
)

Enables Auto-Pipeline-Mode feature for all instances.

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

Details

Parameters

enabled

- True means enable, false means disable

SwappyVk_setAutoSwapInterval

void SwappyVk_setAutoSwapInterval(
  bool enabled
)

Enables Auto-Swap-Interval feature for all instances.

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

Details

Parameters

enabled

- True means enable, false means disable

SwappyVk_setFenceTimeoutNS

void SwappyVk_setFenceTimeoutNS(
  uint64_t fence_timeout_ns
)

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

Its default value is 50,000,000.

SwappyVk_setFunctionProvider

void SwappyVk_setFunctionProvider(
  const SwappyVkFunctionProvider *pSwappyVkFunctionProvider
)

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.

Details

Parameters

provider

- provider object

SwappyVk_setMaxAutoSwapIntervalNS

void SwappyVk_setMaxAutoSwapIntervalNS(
  uint64_t max_swap_ns
)

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.

Details

Parameters

max_swap_ns

- maximal swap duration in milliseconds.

SwappyVk_setQueueFamilyIndex

void SwappyVk_setQueueFamilyIndex(
  VkDevice device,
  VkQueue queue,
  uint32_t queueFamilyIndex
)

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.

Details

Parameters

`device`	- The VkDevice associated with the queue
`queue`	- A device queue.
`queueFamilyIndex`	- The queue family index used to create the VkQueue.

SwappyVk_setSwapIntervalNS

void SwappyVk_setSwapIntervalNS(
  VkDevice device,
  VkSwapchainKHR swapchain,
  uint64_t swap_ns
)

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.

Details

Parameters

`device`	- The VkDevice associated with the swapchain
`swapchain`	- The VkSwapchainKHR the application wants Swappy to swap
`swap_ns`	- The duration of that each presented image should be visible in nanoseconds

SwappyVk_setWindow

void SwappyVk_setWindow(
  VkDevice device,
  VkSwapchainKHR swapchain,
  ANativeWindow *window
)

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

Details

Parameters

`device`	- The VkDevice associated with the swapchain
`swapchain`	- The VkSwapchainKHR the application wants Swappy to swap
`window`	- The ANativeWindow that was used to create the VkSwapchainKHR

SwappyVk_uninjectTracer

void SwappyVk_uninjectTracer(
  const SwappyTracer *tracer
)

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.

Details

Parameters

tracer

- Collection of callback functions

Macros

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1

Swappy for Vulkan

Summary

Typedefs

Functions

Macros

Structs

Typedefs

SwappyVkFunctionProvider

Functions

SwappyVk_clearStats

SwappyVk_destroyDevice

SwappyVk_destroySwapchain

SwappyVk_determineDeviceExtensions

SwappyVk_enableStats

SwappyVk_getFenceTimeoutNS

SwappyVk_getStats

SwappyVk_getSupportedRefreshPeriodsNS

SwappyVk_getSwapIntervalNS

SwappyVk_initAndGetRefreshCycleDuration

SwappyVk_injectTracer

SwappyVk_isEnabled

SwappyVk_queuePresent

SwappyVk_recordFrameStart

SwappyVk_setAutoPipelineMode

SwappyVk_setAutoSwapInterval

SwappyVk_setFenceTimeoutNS

SwappyVk_setFunctionProvider

SwappyVk_setMaxAutoSwapIntervalNS

SwappyVk_setQueueFamilyIndex

SwappyVk_setSwapIntervalNS

SwappyVk_setWindow

SwappyVk_uninjectTracer

Macros

VK_NO_PROTOTYPES