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

Swappy for Vulkan

Summary

Typedefs

Functions

Macros

Structs

Typedefs

SwappyVkFunctionProvider

Functions

SwappyVk_destroyDevice

SwappyVk_destroySwapchain

SwappyVk_determineDeviceExtensions

SwappyVk_getFenceTimeoutNS

SwappyVk_getSwapIntervalNS

SwappyVk_initAndGetRefreshCycleDuration

SwappyVk_injectTracer

SwappyVk_queuePresent

SwappyVk_setAutoPipelineMode

SwappyVk_setAutoSwapInterval

SwappyVk_setFenceTimeoutNS

SwappyVk_setFunctionProvider

SwappyVk_setMaxAutoSwapIntervalNS

SwappyVk_setQueueFamilyIndex

SwappyVk_setSwapIntervalNS

SwappyVk_setWindow

Macros

VK_NO_PROTOTYPES