面向 Vulkan 的 Swappy

Swappy 的 Vulkan 部分。

摘要

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

函数
`SwappyVk_clearStats(VkSwapchainKHR swapchain)`	`void` 清除目前收集到的帧统计信息。
`SwappyVk_destroyDevice(VkDevice device)`	`void` 销毁与设备关联的所有交换链，并清理设备资源。
`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_enableStats(VkSwapchainKHR swapchain, bool enabled)`	`void` 开启/关闭统计信息收集功能。
`SwappyVk_getFenceTimeoutNS()`	`uint64_t` 获取围栏超时参数，适用于驱动程序有故障的设备。
`SwappyVk_getStats(VkSwapchainKHR swapchain, SwappyStats *swappyStats)`	`void` 如果开启了统计信息收集功能，则返回收集到的统计信息。
`SwappyVk_getSupportedRefreshPeriodsNS(uint64_t *out_refreshrates, int allocated_entries, VkSwapchainKHR swapchain)`	`int` 获取此设备支持的刷新周期。
`SwappyVk_getSwapIntervalNS(VkSwapchainKHR swapchain)`	`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_isEnabled(VkSwapchainKHR swapchain, bool *isEnabled)`	`bool` 检查是否为指定的交换链启用了 Swappy。
`SwappyVk_queuePresent(VkQueue queue, const VkPresentInfoKHR *pPresentInfo)`	`VkResult` 告知 Swappy 将一个或多个图像呈现给相应的交换链。
`SwappyVk_recordFrameStart(VkQueue queue, VkSwapchainKHR swapchain, uint32_t image)`	`void` 如果已通过 SwappyVk_enableStats 启用统计信息，则应调用此函数。
`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。
`SwappyVk_uninjectTracer(const SwappyTracer *tracer)`	`void` 移除之前使用 SwappyVk_injectTracer 添加的回调函数。

宏
`VK_NO_PROTOTYPES 1`

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

类型定义

SwappyVkFunctionProvider

struct SwappyVkFunctionProvider SwappyVkFunctionProvider

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

此功能的使用是可选的。

函数

SwappyVk_clearStats

void SwappyVk_clearStats(
  VkSwapchainKHR swapchain
)

清除目前收集到的帧统计信息。

所有收集到的帧统计信息都重置为 0，此调用后会正常收集帧统计信息。有关更多条件，请参阅 SwappyVk_enableStats。

详细信息

参数

swapchain

- 要清除统计信息的交换链。

SwappyVk_destroyDevice

void SwappyVk_destroyDevice(
  VkDevice device
)

销毁与设备关联的所有交换链，并清理设备资源。

如果您不再需要该设备，应在 SwappyVk_destroySwapchain 后调用此函数。

详细信息

参数

device

- 与 SwappyVk 关联的 VkDevice

SwappyVk_destroySwapchain

void SwappyVk_destroySwapchain(
  VkDevice device,
  VkSwapchainKHR swapchain
)

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

预期应在调用 vkDestroySwapchainKHR() 之前调用此 API，以便 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 设备扩展。

面向 Vulkan 的 Swappy (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_enableStats

void SwappyVk_enableStats(
  VkSwapchainKHR swapchain,
  bool enabled
)

开启/关闭统计信息收集功能。

默认情况下，统计信息收集处于关闭状态，且不产生与统计信息相关的开销。应用可以通过调用 SwappyVk_enableStats(swapchain, true) 来开启统计信息收集。然后，应用应在开始执行任何与 CPU 相关的工作之前，为每个帧调用 SwappyVk_recordFrameStart。统计信息将使用“FrameStatistics”标签记录到 logcat 中。应用可以通过调用 SwappyVk_getStats 来获取统计信息。

之前必须为此交换链成功调用过 SwappyVk_initAndGetRefreshCycleDuration，否则此调用无效。仅当平台支持 VK_GOOGLE_display_timing 扩展时，才提供帧统计信息。

详细信息

参数

`swapchain`	- 配置帧统计信息收集的交换链。
`enabled`	- 是否启用/停用帧统计信息收集。

SwappyVk_getFenceTimeoutNS

uint64_t SwappyVk_getFenceTimeoutNS()

获取围栏超时参数，适用于驱动程序有故障的设备。

其默认值为 50,000,000。

SwappyVk_getStats

void SwappyVk_getStats(
  VkSwapchainKHR swapchain,
  SwappyStats *swappyStats
)

如果开启了统计信息收集功能，则返回收集到的统计信息。

鉴于此 API 使用 VkSwapchainKHR 并且此调用可能在不同线程上执行，对 SwappyVk_getStats 的所有调用都必须与 SwappyVk 的其他调用进行外部同步。未同步的调用可能导致未定义的行为。有关更多条件，请参阅 SwappyVk_enableStats。

另请参阅： SwappyStats

详细信息

参数

`swapchain`	- 正在查询统计信息的交换链。
`swappyStats`	- 指向将使用收集到的统计信息填充的 SwappyStats 的指针。不能为 NULL。

SwappyVk_getSupportedRefreshPeriodsNS

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

获取此设备支持的刷新周期。

第一次调用时将 out_refreshrates 设为 nullptr 以获取支持的刷新周期数，然后再次调用时将该数字作为 allocated_entries 传递，并传递一个大小等于 allocated_entries 的数组，该数组将填充刷新周期。

- 要查询的交换链

uint64_t SwappyVk_getSwapIntervalNS(
  VkSwapchainKHR swapchain
)

获取给定交换链的交换间隔值（以纳秒为单位）。

详细信息

参数

swapchain

SwappyVk_getSwapIntervalNS

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），并用一除以此分数，则将得到显示器的近似刷新率（例如，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_isEnabled

bool SwappyVk_isEnabled(
  VkSwapchainKHR swapchain,
  bool *isEnabled
)

检查是否为指定的交换链启用了 Swappy。

详细信息
返回值	如果未为指定的交换链调用 SwappyVk_initAndGetRefreshCycleDuration，则为 false；否则为 true。

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_recordFrameStart

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

如果已通过 SwappyVk_enableStats 启用统计信息，则应调用此函数。

使用 SwappyVk_enableStats 启用统计信息收集后，应用应在开始执行任何与 CPU 相关的工作之前为每个帧调用此函数。假设此函数将在成功调用 vkAcquireNextImageKHR 后调用。有关更多条件，请参阅 SwappyVk_enableStats。

另请参阅：SwappyVk_enableStats。

详细信息

参数

`queue`	- 与设备和交换链关联的 VkQueue
`swapchain`	- 呈现帧的交换链。
`image`	- 交换链中与帧对应的图像。

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

SwappyVk_uninjectTracer

void SwappyVk_uninjectTracer(
  const SwappyTracer *tracer
)

移除之前使用 SwappyVk_injectTracer 添加的回调函数。

仅移除之前使用 SwappyVK_injectTracer 添加的回调函数。如果未调用 SwappyVK_injectTracker 并传入 tracer，则没有效果。

详细信息

参数

tracer

- 回调函数集合

宏

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1