Vulkan 用 Swappy

Swappy の Vulkan 部分。

概要

Typedef

SwappyVkFunctionProvider typedef
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 に対して、対応するスワップチェーンに 1 つ以上の画像を提示するように指示します。
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
VkQueue の作成に使用する queueFamilyIndex を Swappy に指示します。
SwappyVk_setSwapIntervalNS(VkDevice device, VkSwapchainKHR swapchain, uint64_t swap_ns)
void
提示された各画像の表示期間を Swappy に指示します。
SwappyVk_setWindow(VkDevice device, VkSwapchainKHR swapchain, ANativeWindow *window)
void
ANativeWindow_* API を呼び出すときに使用する ANativeWindow を Swappy に指示します。

マクロ

VK_NO_PROTOTYPES 1

構造体

SwappyVkFunctionProvider

SwappyVk_setFunctionProvider を呼び出すことにより、独自の Vulkan 関数ラッパーを提供するための構造体。

Typedef

SwappyVkFunctionProvider

struct SwappyVkFunctionProvider SwappyVkFunctionProvider

SwappyVk_setFunctionProvider を呼び出すことにより、独自の Vulkan 関数ラッパーを提供するための構造体。

この機能の使用は任意です。

関数

SwappyVk_destroySwapchain

void SwappyVk_destroySwapchain(
  VkDevice device,
  VkSwapchainKHR swapchain
)

スワップチェーンに関連付けられた SwappyVk のインスタンスを破棄します。

この API は、Swappy が内部状態をクリーンアップできるように、vkDestroySwapchainKHR() を呼び出す前に呼び出すことを想定されています。この関数は、デバイスのスワップチェーンが 1 つだけの場合、デバイスに関連付けられたリソースもクリーンアップします。

詳細
パラメータ
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 で返されます)を確認し、場合によってはアプリで追加すべき拡張機能を 1 つ以上特定する必要があります。

  • VkDeviceCreateInfo::enabledExtensionCount
  • VkDeviceCreateInfo::ppEnabledExtensionNames

その後でアプリから vkCreateDevice を呼び出します。vkCreateDevice を呼び出す VkPhysicalDevice ごとに、この関数を呼び出してから、特定された拡張機能を VkDevice に対して有効にするリストに追加する必要があります。多くの Vulkan 関数と同様に、この関数は 2 回呼び出すことができます。1 回は、必要な拡張機能の数を特定するために呼び出し、もう 1 回は、この関数が書き込めるようにアプリが割り当てたメモリを添えて呼び出します。

詳細
パラメータ
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 ナノ秒は 60 Hz のディスプレイに相当し、11,111,111 ナノ秒は 90 Hz のディスプレイに相当します)。

詳細
パラメータ
env
- AttachCurrentThread 関数からの JNIEnv
jactivity
- JNI に使用される NativeActivity オブジェクトのハンドル
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 に対して、対応するスワップチェーンに 1 つ以上の画像を提示するように指示します。

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 は、フレーム期間が指定期間より長い場合、ペーシングを行わずに、できるだけ早くフレームを送信します。

詳細
パラメータ
max_swap_ns
- 最長スワップ期間(ミリ秒)。

SwappyVk_setQueueFamilyIndex

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

VkQueue の作成に使用する queueFamilyIndex を Swappy に指示します。

VkQueue を作成するには、提示に使用する queueFamilyIndex を Swappy に知らせておく必要があります。

詳細
パラメータ
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
)

ANativeWindow_* API を呼び出すときに使用する ANativeWindow を Swappy に指示します。

詳細
パラメータ
device
- スワップチェーンに関連付けられた VkDevice
swapchain
- アプリからの指示で Swappy がスワップする VkSwapchainKHR
window
- VkSwapchainKHR の作成に使用した ANativeWindow

マクロ

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1