Vulkan용 Swappy

Swappy의 Vulkan 부분입니다.

요약

Typedef
`SwappyVkFunctionProvider`	typedef `struct SwappyVkFunctionProvider` SwappyVk_setFunctionProvider를 호출하여 고유한 Vulkan 함수 래퍼를 제공할 수 있게 하는 구조입니다.

함수
`SwappyVk_destroySwapchain(VkDevice device, VkSwapchainKHR swapchain)`	`void` swapchain에 연결된 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` 지정된 기기 및 swapchain의 SwappyVk를 초기화하고 수직 귀선 기간 사이의 대략적인 지속 시간을 가져옵니다.
`SwappyVk_injectTracer(const SwappyTracer *tracer)`	`void` 각 프레임에 호출될 콜백 함수를 삽입합니다.
`SwappyVk_queuePresent(VkQueue queue, const VkPresentInfoKHR *pPresentInfo)`	`VkResult` 상응하는 swapchain에 하나 이상의 이미지를 제공하도록 Swappy에 지시합니다.
`SwappyVk_setAutoPipelineMode(bool enabled)`	`void` 모든 인스턴스에 대해 Auto-Pipeline-Mode 기능을 사용 설정합니다.
`SwappyVk_setAutoSwapInterval(bool enabled)`	`void` 모든 인스턴스에 대해 Auto-Swap-Interval 기능을 사용 설정합니다.
`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
)

swapchain에 연결된 SwappyVk 인스턴스를 제거합니다.

이 API는 vkDestroySwapchainKHR()을 호출하기 전에 호출될 것으로 예상되므로 Swappy가 내부 상태를 정리할 수 있습니다. 기기에 대해 하나의 swapchain만 있다면 이 함수는 기기와 관련된 리소스도 정리합니다.

세부정보

매개변수

`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
)

지정된 기기 및 swapchain의 SwappyVk를 초기화하고 수직 귀선 기간 사이의 대략적인 지속 시간을 가져옵니다.

JNI를 사용하여 AppVsyncOffset 및 PresentationDeadline을 쿼리합니다.

애플리케이션이 한 번에 둘 이상의 swapchain에 표시되면 swappyVkSetSwapInterval()을 호출하기 전에 각 swapchain에 대해 이 함수를 호출해야 합니다.

수직 귀선 기간 사이의 지속 시간(간격)은 swapchain의 실제 디스플레이 수직 귀선 기간 사이의 대략적인 나노초 수로 표현됩니다.

애플리케이션에서 이 숫자를 소수로 변환(예: 16,666,666나노초를 0.016666666으로 변환)하고 1을 이 소수로 나누면 디스플레이의 대략적인 새로고침 빈도가 나옵니다(예: 16,666,666나노초는 60Hz 디스플레이에 해당하며, 11,111,111나노초는 90Hz 디스플레이에 해당함).

세부정보

매개변수

`env`	- AttachCurrentThread 함수에서 유래한 것으로 추정되는 JNIEnv
`jactivity`	- JNI에 사용된 NativeActivity 객체 핸들
`physicalDevice`	- swapchain과 연결된 VkPhysicalDevice
`device`	- swapchain과 연결된 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
)

상응하는 swapchain에 하나 이상의 이미지를 제공하도록 Swappy에 지시합니다.

Swappy는 애플리케이션의 vkQueuePresentKHR을 호출합니다. Swappy는 VkPresentInfoKHR의 pNext-chain에 구조체를 삽입하거나 원하는 스왑 간격을 준수하기 위해 다른 Vulkan 명령어를 삽입할 수 있습니다.

참고: 애플리케이션이 한 번에 둘 이상의 swapchain에 표시되며 각 swapchain에 서로 다른 스왑 간격을 사용하면 Swappy는 각 swapchain의 스왑 간격을 준수하려고 시도합니다(VK_GOOGLE_display_timing과 같은 기본 프레젠테이션 타이밍 확장을 지원하는 기기에서 더 성공적임).

세부정보

매개변수

`queue`	- 기기 및 swapchain과 연결된 VkQueue
`pPresentInfo`	- 어떤 swapchain에 어떤 이미지를 표시할 것인지에 관한 정보가 포함된 VkPresentInfoKHR에 대한 포인터

SwappyVk_setAutoPipelineMode

void SwappyVk_setAutoPipelineMode(
  bool enabled
)

모든 인스턴스에 대해 Auto-Pipeline-Mode 기능을 사용 설정합니다.

기본적으로 이 기능은 사용 설정되어 있습니다. Swappy 동작 미세 조정을 위해 이 사용 설정을 변경하는 것은 전적으로 선택사항입니다.

세부정보

매개변수

enabled

- true는 사용 설정, false는 사용 중지를 의미합니다.

SwappyVk_setAutoSwapInterval

void SwappyVk_setAutoSwapInterval(
  bool enabled
)

모든 인스턴스에 대해 Auto-Swap-Interval 기능을 사용 설정합니다.

기본적으로 이 기능은 사용 설정되어 있습니다. 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
)

모든 인스턴스에 최대 스왑 기간을 설정합니다.

Auto-Swap-Interval의 최대 기간을 밀리초 단위로 설정합니다. SwappyVk가 Auto-Swap-Interval로 작동하고 프레임 지속 기간이 제공된 기간보다 길다면 SwappyVk는 속도를 지정하지 않고 최대한 빨리 프레임을 제출합니다.

세부정보

매개변수

max_swap_ns

- 최대 스왑 기간(밀리초)

SwappyVk_setQueueFamilyIndex

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

특정 VkQueue를 생성하는 데 사용된 queueFamilyIndex를 Swappy에 알려줍니다.

Swappy는 특정 VkQueue를 생성하는 데 사용된 queueFamilyIndex를 알아야 합니다. 그래야 표시할 때 queueFamilyIndex를 사용할 수 있습니다.

세부정보

매개변수

`device`	- 큐와 연결된 VkDevice
`queue`	- 기기 큐
`queueFamilyIndex`	- VkQueue를 생성하는 데 사용된 큐 패밀리 색인

SwappyVk_setSwapIntervalNS

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

제공된 각 이미지가 표시되어야 하는 기간을 Swappy에 알려줍니다.

애플리케이션이 한 번에 둘 이상의 swapchain에 표시되는 경우 표시되기 전에 각 swapchain에 대해 이 함수를 호출해야 합니다.

세부정보

매개변수

`device`	- swapchain과 연결된 VkDevice
`swapchain`	- 애플리케이션에서 Swappy가 스왑하기를 원하는 VkSwapchainKHR
`swap_ns`	- 제공된 각 이미지가 표시되어야 하는 기간(나노초)

SwappyVk_setWindow

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

ANativeWindow_* API를 호출할 때 사용할 ANativeWindow를 Swappy에 알려줍니다.

세부정보

매개변수

`device`	- swapchain과 연결된 VkDevice
`swapchain`	- 애플리케이션에서 Swappy가 스왑하기를 원하는 VkSwapchainKHR
`window`	- VkSwapchainKHR을 생성하는 데 사용된 ANativeWindow

매크로

VK_NO_PROTOTYPES

 VK_NO_PROTOTYPES 1