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.
diff --git a/vulkan/doc/implementors_guide.html b/vulkan/doc/implementors_guide.html
index 8186ae3..8d6297a 100644
--- a/vulkan/doc/implementors_guide.html
+++ b/vulkan/doc/implementors_guide.html
@@ -733,7 +733,7 @@
<body class="book">
<div id="header">
<h1>Vulkan on Android Implementor’s Guide</h1>
-<span id="revnumber">version 1</span>
+<span id="revnumber">version 3</span>
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
@@ -843,29 +843,32 @@
.queueFamilyCount = VkSwapChainCreateInfoWSI::queueFamilyCount
.pQueueFamilyIndices = VkSwapChainCreateInfoWSI::pQueueFamilyIndices</pre>
</div></div>
-<div class="paragraph"><p><span class="monospaced">vkImportNativeFenceANDROID</span> imports an externally-signalled native fence into an existing <span class="monospaced">VkSemaphore</span> object:</p></div>
+<div class="paragraph"><p><span class="monospaced">vkAcquireImageANDROID</span> acquires ownership of a swapchain image and imports an externally-signalled native fence into an existing <span class="monospaced">VkSemaphore</span> object:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.6
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>VkResult <span style="color: #008080">VKAPI</span> <span style="font-weight: bold"><span style="color: #000000">vkImportNativeFenceANDROID</span></span><span style="color: #990000">(</span>
- <span style="color: #008080">VkDevice</span> device<span style="color: #990000">,</span>
- <span style="color: #008080">VkSemaphore</span> semaphore<span style="color: #990000">,</span>
- <span style="color: #009900">int</span> nativeFenceFd
+<pre><tt>VkResult <span style="color: #008080">VKAPI</span> <span style="font-weight: bold"><span style="color: #000000">vkAcquireImageANDROID</span></span><span style="color: #990000">(</span>
+ <span style="color: #008080">VkDevice</span> device<span style="color: #990000">,</span>
+ <span style="color: #008080">VkImage</span> image<span style="color: #990000">,</span>
+ <span style="color: #009900">int</span> nativeFenceFd<span style="color: #990000">,</span>
+ VkSemaphore semaphore
+<span style="color: #990000">);</span>
<span style="color: #990000">);</span></tt></pre></div></div>
-<div class="paragraph"><p>This function is called during <span class="monospaced">vkAcquireNextImageWSI</span> to import a native fence into the <span class="monospaced">VkSemaphore</span> object provided by the application. This call puts the <span class="monospaced">VkSemaphore</span> into the same "pending" state as <span class="monospaced">vkQueueSignalSemaphore</span>, so queues can wait on the semaphore. The <span class="monospaced">VkSemaphore</span> 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 <span class="monospaced">VkSemaphore</span> is destroyed, when a different native fence is imported, or any other condition that replaces the <span class="monospaced">VkSemaphore</span>'s underlying synchronization object. If <span class="monospaced">fenceFd</span> is -1, the <span class="monospaced">VkSemaphore</span> will be considered signalled immediately, but it can still be passed to <span class="monospaced">vkQueueWaitSemaphore</span>.</p></div>
-<div class="paragraph"><p><span class="monospaced">vkQueueSignalNativeFenceANDROID</span> creates a native fence and schedules it to be signalled when prior work on the queue has completed.</p></div>
+<div class="paragraph"><p>This function is called during <span class="monospaced">vkAcquireNextImageWSI</span> to import a native fence into the <span class="monospaced">VkSemaphore</span> 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 <span class="monospaced">VkSemaphore</span> into the same "pending" state as <span class="monospaced">vkQueueSignalSemaphore</span>, so queues can wait on the semaphore. The <span class="monospaced">VkSemaphore</span> 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 <span class="monospaced">VkSemaphore</span> is destroyed, when a different native fence is imported, or any other condition that replaces the <span class="monospaced">VkSemaphore</span>'s underlying synchronization object. If <span class="monospaced">fenceFd</span> is -1, the <span class="monospaced">VkSemaphore</span> will be considered signalled immediately, but it can still be passed to <span class="monospaced">vkQueueWaitSemaphore</span>.</p></div>
+<div class="paragraph"><p><span class="monospaced">vkQueueSignalReleaseImageANDROID</span> 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.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.6
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt>VkResult <span style="color: #008080">VKAPI</span> <span style="font-weight: bold"><span style="color: #000000">vkQueueSignalNativeFenceANDROID</span></span><span style="color: #990000">(</span>
- <span style="color: #008080">VkQueue</span> queue<span style="color: #990000">,</span>
- <span style="color: #009900">int</span><span style="color: #990000">*</span> pNativeFenceFd<span style="color: #990000">);</span></tt></pre></div></div>
-<div class="paragraph"><p>This will be called during <span class="monospaced">vkQueuePresentWSI</span> on the provided queue. Effects are similar to <span class="monospaced">vkQueueSignalSemaphore</span>, except with a native fence instead of a semaphore. Unlike <span class="monospaced">vkQueueSignalSemaphore</span>, 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 <span class="monospaced">*pNativeFenceFd</span> to -1. The file descriptor returned in <span class="monospaced">*pNativeFenceFd</span> is owned and will be closed by the caller.</p></div>
+<pre><tt>VkResult <span style="color: #008080">VKAPI</span> <span style="font-weight: bold"><span style="color: #000000">vkQueueSignalReleaseImageANDROID</span></span><span style="color: #990000">(</span>
+ <span style="color: #008080">VkQueue</span> queue<span style="color: #990000">,</span>
+ <span style="color: #008080">VkImage</span> image<span style="color: #990000">,</span>
+ <span style="color: #009900">int</span><span style="color: #990000">*</span> pNativeFenceFd
+<span style="color: #990000">);</span></tt></pre></div></div>
+<div class="paragraph"><p>This will be called during <span class="monospaced">vkQueuePresentWSI</span> on the provided queue. Effects are similar to <span class="monospaced">vkQueueSignalSemaphore</span>, except with a native fence instead of a semaphore. Unlike <span class="monospaced">vkQueueSignalSemaphore</span>, 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 <span class="monospaced">*pNativeFenceFd</span> to -1. The file descriptor returned in <span class="monospaced">*pNativeFenceFd</span> is owned and will be closed by the caller. Many drivers will be able to ignore the <span class="monospaced">image</span> 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 <span class="monospaced">VK_IMAGE_LAYOUT_PRESENT_SRC_KHR</span>.</p></div>
</div>
</div>
<div class="sect1">
@@ -904,6 +907,25 @@
</li>
</ul></div>
</li>
+<li>
+<p>
+<strong>2015-11-04</strong>
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Added vkGetSwapchainGrallocUsageANDROID
+</p>
+</li>
+<li>
+<p>
+Replaced vkImportNativeFenceANDROID and vkQueueSignalNativeFenceANDROID
+ with vkAcquireImageANDROID and vkQueueSignalReleaseImageANDROID, to allow
+ drivers to known the ownership state of swapchain images.
+</p>
+</li>
+</ul></div>
+</li>
</ol></div>
</div>
</div>
@@ -911,8 +933,8 @@
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
-Version 1<br>
-Last updated 2015-11-04 09:13:11 PST
+Version 3<br>
+Last updated 2015-11-04 10:58:22 PST
</div>
</div>
</body>