vulkan: allow drivers to see image acquire/release
Change-Id: I8143aeebd1f65142486cc55662c685d081ba41eb
(cherry picked from commit 58b4df743ecad9f1a0fc7cb7c0f5340dd8365308)
diff --git a/vulkan/doc/implementors_guide.adoc b/vulkan/doc/implementors_guide.adoc
index 313a5e1..60a6f61 100644
--- a/vulkan/doc/implementors_guide.adoc
+++ b/vulkan/doc/implementors_guide.adoc
@@ -2,7 +2,7 @@
= Vulkan on Android Implementor's Guide =
:toc: right
:numbered:
-:revnumber: 2
+:revnumber: 3
This document is intended for GPU IHVs writing Vulkan drivers for Android, and OEMs integrating them for specific devices. It describes how a Vulkan driver interacts with the system, how GPU-specific tools should be installed, and Android-specific requirements.
@@ -99,30 +99,33 @@
.pQueueFamilyIndices = VkSwapChainCreateInfoWSI::pQueueFamilyIndices
----
-+vkImportNativeFenceANDROID+ imports an externally-signalled native fence into an existing +VkSemaphore+ object:
++vkAcquireImageANDROID+ acquires ownership of a swapchain image and imports an externally-signalled native fence into an existing +VkSemaphore+ object:
[source,c]
----
-VkResult VKAPI vkImportNativeFenceANDROID(
- VkDevice device,
- VkSemaphore semaphore,
- int nativeFenceFd
+VkResult VKAPI vkAcquireImageANDROID(
+ VkDevice device,
+ VkImage image,
+ int nativeFenceFd,
+ VkSemaphore semaphore
+);
);
----
-This function is called during +vkAcquireNextImageWSI+ to import a native fence into the +VkSemaphore+ object provided by the application. This call puts the +VkSemaphore+ into the same "pending" state as +vkQueueSignalSemaphore+, so queues can wait on the semaphore. The +VkSemaphore+ signals when the underlying native fence signals; if the fence has already signalled, then the semaphore
-will be in the signalled state when this function returns. The driver takes ownership of the fence fd and is responsible for closing it when the +VkSemaphore+ is destroyed, when a different native fence is imported, or any other condition that replaces the +VkSemaphore+'s underlying synchronization object. If +fenceFd+ is -1, the +VkSemaphore+ will be considered signalled immediately, but it can still be passed to +vkQueueWaitSemaphore+.
+This function is called during +vkAcquireNextImageWSI+ to import a native fence into the +VkSemaphore+ object provided by the application. The driver may also use this opportunity to recognize and handle any external changes to the gralloc buffer state; many drivers won't need to do anything here. This call puts the +VkSemaphore+ into the same "pending" state as +vkQueueSignalSemaphore+, so queues can wait on the semaphore. The +VkSemaphore+ signals when the underlying native fence signals; if the fence has already signalled, then the semaphore will be in the signalled state when this function returns. The driver takes ownership of the fence fd and is responsible for closing it when the +VkSemaphore+ is destroyed, when a different native fence is imported, or any other condition that replaces the +VkSemaphore+'s underlying synchronization object. If +fenceFd+ is -1, the +VkSemaphore+ will be considered signalled immediately, but it can still be passed to +vkQueueWaitSemaphore+.
-+vkQueueSignalNativeFenceANDROID+ creates a native fence and schedules it to be signalled when prior work on the queue has completed.
++vkQueueSignalReleaseImageANDROID+ prepares a swapchain image for external use, and creates a native fence and schedules it to be signalled when prior work on the queue has completed.
[source,c]
----
-VkResult VKAPI vkQueueSignalNativeFenceANDROID(
- VkQueue queue,
- int* pNativeFenceFd);
+VkResult VKAPI vkQueueSignalReleaseImageANDROID(
+ VkQueue queue,
+ VkImage image,
+ int* pNativeFenceFd
+);
----
-This will be called during +vkQueuePresentWSI+ on the provided queue. Effects are similar to +vkQueueSignalSemaphore+, except with a native fence instead of a semaphore. Unlike +vkQueueSignalSemaphore+, however, this call creates and returns the synchronization object that will be signalled rather than having it provided as input. If the queue is already idle when this function is called, it is allowed but not required to set +*pNativeFenceFd+ to -1. The file descriptor returned in +*pNativeFenceFd+ is owned and will be closed by the caller.
+This will be called during +vkQueuePresentWSI+ on the provided queue. Effects are similar to +vkQueueSignalSemaphore+, except with a native fence instead of a semaphore. Unlike +vkQueueSignalSemaphore+, however, this call creates and returns the synchronization object that will be signalled rather than having it provided as input. If the queue is already idle when this function is called, it is allowed but not required to set +*pNativeFenceFd+ to -1. The file descriptor returned in +*pNativeFenceFd+ is owned and will be closed by the caller. Many drivers will be able to ignore the +image+ parameter, but some may need to prepare CPU-side data structures associated with a gralloc buffer for use by external image consumers. Preparing buffer contents for use by external consumers should have been done asynchronously as part of transitioning the image to +VK_IMAGE_LAYOUT_PRESENT_SRC_KHR+.
== History ==
@@ -132,3 +135,8 @@
* Wording and formatting changes
* Updated based on resolution of Khronos bug 14265
* Deferred support for multiple drivers
+. *2015-11-04*
+ * Added vkGetSwapchainGrallocUsageANDROID
+ * Replaced vkImportNativeFenceANDROID and vkQueueSignalNativeFenceANDROID
+ with vkAcquireImageANDROID and vkQueueSignalReleaseImageANDROID, to allow
+ drivers to known the ownership state of swapchain images.