Swappy for Vulkan

Vulkan part of Swappy.

Summary

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

Functions
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_getFenceTimeoutNS()
uint64_t
Get the fence timeout parameter, for devices with faulty drivers.
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_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_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.

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

uint64_t SwappyVk_getFenceTimeoutNS()

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

Its default value is 50,000,000.

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

Macros

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1