适用于 Vulkan 的 Swappy

Swappy 的 Vulkan 部件。

摘要

类型定义符
`SwappyVkFunctionProvider`	typedef `struct SwappyVkFunctionProvider` 该结构使您可以通过调用 SwappyVk_setFunctionProvider 提供自己的 Vulkan 函数封装容器。

函数
`SwappyVk_destroySwapchain(VkDevice device, VkSwapchainKHR swapchain)`	`void` 销毁与交换链关联的 SwappyVk 实例。
`SwappyVk_determineDeviceExtensions(VkPhysicalDevice physicalDevice, uint32_t availableExtensionCount, VkExtensionProperties pAvailableExtensions, uint32_t pRequiredExtensionCount, char **pRequiredExtensions)`	`void` 确定必须要为新的 VkDevice 启用的任何 Vulkan 设备扩展。
`SwappyVk_getFenceTimeoutNS()`	`uint64_t` 为驱动程序出现问题的设备获取栅栏超时参数。
`SwappyVk_initAndGetRefreshCycleDuration(JNIEnv env, jobject jactivity, VkPhysicalDevice physicalDevice, VkDevice device, VkSwapchainKHR swapchain, uint64_t pRefreshDuration)`	`bool` 针对给定设备和交换链初始化 SwappyVk，并获取两个垂直消隐期间隔的大致持续时间。
`SwappyVk_injectTracer(const SwappyTracer *tracer)`	`void` 注入需要为每个帧调用的回调函数。
`SwappyVk_queuePresent(VkQueue queue, const VkPresentInfoKHR *pPresentInfo)`	`VkResult` 告知 Swappy 向相应交换链呈现一个或多个图像。
`SwappyVk_setAutoPipelineMode(bool enabled)`	`void` 为所有实例启用自动流水线模式功能。
`SwappyVk_setAutoSwapInterval(bool enabled)`	`void` 为所有实例启用自动交换间隔功能。
`SwappyVk_setFenceTimeoutNS(uint64_t fence_timeout_ns)`	`void` 可以为驱动程序故障的设备栅栏超时参数。
`SwappyVk_setFunctionProvider(const SwappyVkFunctionProvider *pSwappyVkFunctionProvider)`	`void` 设置 Vulkan 函数提供程序。
`SwappyVk_setMaxAutoSwapIntervalNS(uint64_t max_swap_ns)`	`void` 为所有实例设置最长交换时长。
`SwappyVk_setQueueFamilyIndex(VkDevice device, VkQueue queue, uint32_t queueFamilyIndex)`	`void` 告知 Swappy 用于创建特定 VkQueue 的 queueFamilyIndex。
`SwappyVk_setSwapIntervalNS(VkDevice device, VkSwapchainKHR swapchain, uint64_t swap_ns)`	`void` 告知 Swappy 每个呈现的图像应显示的时长。
`SwappyVk_setWindow(VkDevice device, VkSwapchainKHR swapchain, ANativeWindow *window)`	`void` 告知 Swappy 调用 ANativeWindow_* API 时要使用哪个 ANativeWindow。

宏
`VK_NO_PROTOTYPES 1`

结构体
SwappyVkFunctionProvider	该结构使您可以通过调用 SwappyVk_setFunctionProvider 提供自己的 Vulkan 函数封装容器。

类型定义符

SwappyVkFunctionProvider

struct SwappyVkFunctionProvider SwappyVkFunctionProvider

该结构使您可以通过调用 SwappyVk_setFunctionProvider 提供自己的 Vulkan 函数封装容器。

您可以选择是否使用此功能。

函数

SwappyVk_destroySwapchain

void SwappyVk_destroySwapchain(
  VkDevice device,
  VkSwapchainKHR swapchain
)

销毁与交换链关联的 SwappyVk 实例。

此 API 应该在调用 vkDestroySwapchainKHR() 之前调用，以便 Swappy 可以清理其内部状态。请注意，如果设备只有一个交换链，此函数也会清理与设备关联的所有资源。

详细信息

参数

`device`	- 与 SwappyVk 关联的 VkDevice
`swapchain`	- 应用希望 Swappy 进行交换的 VkSwapchainKHR

SwappyVk_determineDeviceExtensions

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

确定必须要为新的 VkDevice 启用的任何 Vulkan 设备扩展。

Swappy-for-Vulkan (SwappyVk) 受益于某些 Vulkan 设备扩展（例如 VK_GOOGLE_display_timing）。在应用调用 vkCreateDevice 之前，SwappyVk 需要查看可用扩展列表（由 vkEnumerateDeviceExtensionProperties 返回），并确定应用必须添加到的一个或多个可能的扩展：

VkDeviceCreateInfo::enabledExtensionCount
VkDeviceCreateInfo::ppEnabledExtensionNames

然后应用调用 vkCreateDevice。对于应用将为之调用 vkCreateDevice 的每个 VkPhysicalDevice，应用都必须调用此函数，然后将识别到的扩展添加到已为 VkDevice 启用的列表中。与许多 Vulkan 函数类似，此函数可被调用两次，一次用于识别所需的扩展数量，另一次用于为应用分配的内存，函数可写入该内存。

详细信息

参数

`physicalDevice`	- 与可用扩展相关联的 VkPhysicalDevice。
`availableExtensionCount`	- 这是从 vkEnumerateDeviceExtensionProperties 返回的 pPropertyCount 值。
`pAvailableExtensions`	- 这是从 vkEnumerateDeviceExtensionProperties 返回的 pProperties 值。
`pRequiredExtensionCount`	- 如果 pRequiredExtensions 为 nullptr，此函数将该值设为所需扩展的数量。如果 pRequiredExtensions 为非 nullptr，这表示该函数应写入 pRequiredExtensions 的所需扩展的数量。
`pRequiredExtensions`	- 如果为非 nullptr，这表示为应用分配的内存，函数将在其中写入所需扩展的名称。它是指向 char* 字符串数组的指针（即与 VkDeviceCreateInfo::ppEnabledExtensionNames 相同）。

SwappyVk_getFenceTimeoutNS

uint64_t SwappyVk_getFenceTimeoutNS()

为驱动程序出现问题的设备获取栅栏超时参数。

其默认值为 50,000,000。

SwappyVk_initAndGetRefreshCycleDuration

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

针对给定设备和交换链初始化 SwappyVk，并获取两个垂直消隐期间隔的大致持续时间。

使用 JNI 查询 AppVsyncOffset 和 PresentationDeadline。

如果您的应用同时向多个交换链呈现，必须先为每个交换链调用此函数，才能为其调用 swappyVkSetSwapInterval()。

垂直消隐期（间隔）间隔的时长表示为交换链实体显示屏的垂直消隐期间隔的大致纳秒数。

如果应用将此数字转换为小数（例如将 16,666,666 纳秒转换为0.016666666），然后用 1 除以该小数，得出的结果将是显示屏的近似刷新频率（例如，16,666,666 纳秒对应于 60Hz 显示屏，11,111,111 纳秒对应于 90Hz 显示屏）。

详细信息

参数

`env`	- 假定来自 AttachCurrentThread 函数的 JNIEnv
`jactivity`	- NativeActivity 对象句柄，用于 JNI
`physicalDevice`	- 与交换链关联的 VkPhysicalDevice
`device`	- 与交换链关联的 VkDevice
`swapchain`	- 应用希望 Swappy 进行交换的 VkSwapchainKHR
`pRefreshDuration`	- 返回的刷新周期持续时间

返回值

bool - 如果 pRefreshDuration 返回的值有效则为 true，否则，如果出错则为 false。

SwappyVk_injectTracer

void SwappyVk_injectTracer(
  const SwappyTracer *tracer
)

注入需要为每个帧调用的回调函数。

详细信息

参数

tracer

- 回调函数集合

SwappyVk_queuePresent

VkResult SwappyVk_queuePresent(
  VkQueue queue,
  const VkPresentInfoKHR *pPresentInfo
)

告知 Swappy 向相应交换链呈现一个或多个图像。

Swappy 将为您的应用调用 vkQueuePresentKHR。Swappy 可能会向 VkPresentInfoKHR 的 pNext 链插入一个结构体，也可能会插入其他 Vulkan 命令以尝试满足所需的交换间隔。

注意：如果您的应用同时向多个交换链展示，并且每个交换链使用不同的交换间隔，Swappy 将尝试满足每个交换链的交换间隔（在支持底层呈现时间扩展 [如 VK_GOOGLE_display_timing] 的设备上效果更佳）。

详细信息

参数

`queue`	- 与设备和交换链关联的 VkQueue
`pPresentInfo`	- 指向 VkPresentInfoKHR 的指针，其中包含要在哪些交换链上显示哪些图像的相关信息。

SwappyVk_setAutoPipelineMode

void SwappyVk_setAutoPipelineMode(
  bool enabled
)

为所有实例启用自动流水线模式功能。

此功能默认处于启用状态。是否更改完全可选，可以选择更改以微调 swappy 行为。

详细信息

参数

enabled

- true 表示启用，false 表示停用

SwappyVk_setAutoSwapInterval

void SwappyVk_setAutoSwapInterval(
  bool enabled
)

为所有实例启用自动交换间隔功能。

此功能默认处于启用状态。是否更改完全可选，可以选择更改以微调 swappy 行为。

详细信息

参数

enabled

- true 表示启用，false 表示停用

SwappyVk_setFenceTimeoutNS

void SwappyVk_setFenceTimeoutNS(
  uint64_t fence_timeout_ns
)

可以为驱动程序故障的设备栅栏超时参数。

其默认值为 50,000,000。

SwappyVk_setFunctionProvider

void SwappyVk_setFunctionProvider(
  const SwappyVkFunctionProvider *pSwappyVkFunctionProvider
)

设置 Vulkan 函数提供程序。

这可让您提供一个将用于查找 Vulkan 函数的对象，例如挂接使用这些函数。

如需使用此功能，您必须先调用此函数，然后才能调用任何其他函数。

是否使用此函数完全是可选的。如果您不使用它，Swappy 所需的 Vulkan 函数将从 libvulkan.so 动态加载。

详细信息

参数

provider

- 提供程序对象

SwappyVk_setMaxAutoSwapIntervalNS

void SwappyVk_setMaxAutoSwapIntervalNS(
  uint64_t max_swap_ns
)

为所有实例设置最长交换时长。

设置自动交换间隔的最长持续时间（以毫秒为单位）。如果 SwappyVk 以自动交换间隔运行且帧时长超过所提供的持续时间，SwappyVk 将不会进行任何同步，只会尽快提交帧。

详细信息

参数

max_swap_ns

- 最大交换时长（以毫秒为单位）。

SwappyVk_setQueueFamilyIndex

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

告知 Swappy 用于创建特定 VkQueue 的 queueFamilyIndex。

Swappy 需要知道用于创建特定 VkQueue 的 queueFamilyIndex，以便其能够在展示时使用。

详细信息

参数

`device`	- 与队列关联的 VkDevice
`queue`	- 设备队列。
`queueFamilyIndex`	- 用于创建 VkQueue 的队列系列索引。

SwappyVk_setSwapIntervalNS

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

告知 Swappy 每个呈现的图像应显示的时长。

如果您的应用同时向多个交换链展示，您必须先为每个交换链调用此函数，然后再向它展示。

详细信息

参数

`device`	- 与交换链关联的 VkDevice
`swapchain`	- 应用希望 Swappy 进行交换的 VkSwapchainKHR
`swap_ns`	- 每张展示图像的显示时长（以纳秒为单位）

SwappyVk_setWindow

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

告知 Swappy 调用 ANativeWindow_* API 时要使用哪个 ANativeWindow。

详细信息

参数

`device`	- 与交换链关联的 VkDevice
`swapchain`	- 应用希望 Swappy 进行交换的 VkSwapchainKHR
`window`	- 用于创建 VkSwapchainKHR 的 ANativeWindow

宏

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1