Swappy for Vulkan

Vulkan part of Swappy.

Summary

Functions
`SwappyVk_destroySwapchain(VkDevice device, VkSwapchainKHR swapchain)`	`void` Destroy SwappyVk instance associated to the 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_getFenceTimeoutNS()`	`uint64_t` Get the fence timeout parameter, for devices with faulty drivers.
`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_queuePresent(VkQueue queue, const VkPresentInfoKHR *pPresentInfo)`	`VkResult` Tell Swappy to present one or more images to corresponding swapchains.
`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_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.

Functions

SwappyVk_destroySwapchain

void SwappyVk_destroySwapchain(
  VkDevice device,
  VkSwapchainKHR swapchain
)

Destroy SwappyVk instance associated to the swapchain.

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

Details

Parameters

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

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_getFenceTimeoutNS

uint64_t SwappyVk_getFenceTimeoutNS()

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

Its default value is 50,000,000.

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_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_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_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