The +format+ and +imageUsage+ parameters are taken from the +VkSwapchainCreateInfoKHR+ structure. The driver should fill +*grallocUsage+ with the gralloc usage flags it requires for that format and usage. These will be combined with the usage flags requested by the swapchain consumer when allocating buffers.
Implementations may further need swapchain buffers to be allocated with implementation-defined private gralloc usage flags that depend not only on +format+ and +imageUsage+, but also on the intended usage of the swapchain. The additional usage bits are defined as
If the driver provides the +vkGetSwapchainGrallocUsage2ANDROID+ function, the platform will use it in preference to +vkGetSwapchainGrallocUsageANDROID+ when translating a requested format, image usage flags, and swapchain image usage flags into gralloc usage flags. +vkGetSwapchainGrallocUsage2ANDROID+ behaves in the same way as +vkGetSwapchainGrallocUsageANDROID+, and is declared as
+VkNativeBufferANDROID+ is a +vkCreateImage+ extension structure for creating an image backed by a gralloc buffer. This structure is provided to +vkCreateImage+ in the +VkImageCreateInfo+ structure chain. Calls to +vkCreateImage+ with this structure will happen during the first call to +vkGetSwapChainInfoWSI(.. VK_SWAP_CHAIN_INFO_TYPE_IMAGES_WSI ..)+. The WSI implementation will allocate the number of native buffers requested for the swapchain, then create a +VkImage+ for each one.
[source,c]
@@ -78,6 +100,7 @@ typedef struct {
----
When creating a gralloc-backed image, the +VkImageCreateInfo+ will have:
[source,txt]
----
.imageType = VK_IMAGE_TYPE_2D
.format = a VkFormat matching the format requested for the gralloc buffer
@@ -93,6 +116,17 @@ When creating a gralloc-backed image, the +VkImageCreateInfo+ will have:
Additionally, when any swapchain image usage flags are required for the swapchain, the platform will provide a +VkSwapchainImageCreateInfoANDROID+ extension structure in the +VkImageCreateInfo+ chain provided to +vkCreateImage+, containing the swapchain image usage flags:
[source,c]
----
typedef struct {
VkStructureType sType; // must be VK_STRUCTURE_TYPE_SWAPCHAIN_IMAGE_CREATE_INFO_ANDROID
const void* pNext;
VkSwapchainImageUsageFlagBitsANDROID usage;
} VkSwapchainImageCreateInfoANDROID;
----
+vkAcquireImageANDROID+ acquires ownership of a swapchain image and imports an
externally-signalled native fence into both an existing VkSemaphore object
This will be called during +vkQueuePresentWSI+ on the provided queue. Effects are similar to +vkQueueSignalSemaphore+, except with a native fence instead of a semaphore. The native fence must: not signal until the +waitSemaphoreCount+ semaphores in +pWaitSemaphores+ have signaled. 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+.
If +image+ was created with +VK_SWAPCHAIN_IMAGE_USAGE_FRONT_BUFFER_BIT_ANDROID+, then the driver must tolerate +vkQueueSignalReleaseImageANDROID+ being called repeatedly without intervening calls to +vkAcquireImageANDROID+.
== History ==
. *2015-07-08* Initial version
@@ -159,3 +195,8 @@ This will be called during +vkQueuePresentWSI+ on the provided queue. Effects ar
* Added waitSemaphoreCount and pWaitSemaphores parameters to vkQueueSignalReleaseImageANDROID.
. *2016-06-17*
* Updates to reflect final behavior, closed some TBDs now that they've BDed.
<h1>Vulkan on Android Implementor’s Guide</h1>
<spanid="revnumber">version 5</span>
@@ -795,7 +795,7 @@ Injected layers, like framerate, social network, or game launcher overlays, whic
<divclass="paragraph"><p>The <spanclass="monospaced">vk_wsi_swapchin</span> and <spanclass="monospaced">vk_wsi_device_swapchain</span> extensions are primarily be implemented by the platform and live in <spanclass="monospaced">libvulkan.so</span>. The <spanclass="monospaced">VkSwapchain</span> object and all interaction with <spanclass="monospaced">ANativeWindow</span> will be handled by the platform and not exposed to drivers. The WSI implementation will rely on a few private interfaces to the driver for this implementation. These will be loaded through the driver’s <spanclass="monospaced">vkGetDeviceProcAddr</span> functions, after passing through any enabled layers.</p></div>
<divclass="paragraph"><p>Implementations may need swapchain buffers to be allocated with implementation-defined private gralloc usage flags. When creating a swapchain, the platform will ask the driver to translate the requested format and image usage flags into gralloc usage flags by calling</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.8
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<divclass="paragraph"><p>The <spanclass="monospaced">format</span> and <spanclass="monospaced">imageUsage</span> parameters are taken from the <spanclass="monospaced">VkSwapchainCreateInfoKHR</span> structure. The driver should fill <spanclass="monospaced">*grallocUsage</span> with the gralloc usage flags it requires for that format and usage. These will be combined with the usage flags requested by the swapchain consumer when allocating buffers.</p></div>
<divclass="paragraph"><p>Implementations may further need swapchain buffers to be allocated with implementation-defined private gralloc usage flags that depend not only on <spanclass="monospaced">format</span> and <spanclass="monospaced">imageUsage</span>, but also on the intended usage of the swapchain. The additional usage bits are defined as</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<divclass="paragraph"><p>If the driver provides the <spanclass="monospaced">vkGetSwapchainGrallocUsage2ANDROID</span> function, the platform will use it in preference to <spanclass="monospaced">vkGetSwapchainGrallocUsageANDROID</span> when translating a requested format, image usage flags, and swapchain image usage flags into gralloc usage flags. <spanclass="monospaced">vkGetSwapchainGrallocUsage2ANDROID</span> behaves in the same way as <spanclass="monospaced">vkGetSwapchainGrallocUsageANDROID</span>, and is declared as</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<divclass="paragraph"><p><spanclass="monospaced">VkNativeBufferANDROID</span> is a <spanclass="monospaced">vkCreateImage</span> extension structure for creating an image backed by a gralloc buffer. This structure is provided to <spanclass="monospaced">vkCreateImage</span> in the <spanclass="monospaced">VkImageCreateInfo</span> structure chain. Calls to <spanclass="monospaced">vkCreateImage</span> with this structure will happen during the first call to <spanclass="monospaced">vkGetSwapChainInfoWSI(.. VK_SWAP_CHAIN_INFO_TYPE_IMAGES_WSI ..)</span>. The WSI implementation will allocate the number of native buffers requested for the swapchain, then create a <spanclass="monospaced">VkImage</span> for each one.</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.8
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<divclass="paragraph"><p>Additionally, when any swapchain image usage flags are required for the swapchain, the platform will provide a <spanclass="monospaced">VkSwapchainImageCreateInfoANDROID</span> extension structure in the <spanclass="monospaced">VkImageCreateInfo</span> chain provided to <spanclass="monospaced">vkCreateImage</span>, containing the swapchain image usage flags:</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<spanstyle="color: #008080">VkStructureType</span> sType<spanstyle="color: #990000">;</span><spanstyle="font-style: italic"><spanstyle="color: #9A1900">// must be VK_STRUCTURE_TYPE_SWAPCHAIN_IMAGE_CREATE_INFO_ANDROID</span></span>
<divclass="paragraph"><p><spanclass="monospaced">vkAcquireImageANDROID</span> acquires ownership of a swapchain image and imports an
externally-signalled native fence into both an existing VkSemaphore object
and an existing VkFence object:</p></div>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.8
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
@@ -872,7 +910,7 @@ neither a semaphore or fence object is provided, or even if
is as if the native fence was already signalled.</p></div>
<divclass="paragraph"><p><spanclass="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>
<divclass="listingblock">
<divclass="content"><!-- Generator: GNU source-highlight 3.1.8
<divclass="content"><!-- Generator: GNU source-highlight 3.1.6
<divclass="paragraph"><p>This will be called during <spanclass="monospaced">vkQueuePresentWSI</span> on the provided queue. Effects are similar to <spanclass="monospaced">vkQueueSignalSemaphore</span>, except with a native fence instead of a semaphore. The native fence must: not signal until the <spanclass="monospaced">waitSemaphoreCount</span> semaphores in <spanclass="monospaced">pWaitSemaphores</span> have signaled. Unlike <spanclass="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 <spanclass="monospaced">*pNativeFenceFd</span> to -1. The file descriptor returned in <spanclass="monospaced">*pNativeFenceFd</span> is owned and will be closed by the caller. Many drivers will be able to ignore the <spanclass="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 <spanclass="monospaced">VK_IMAGE_LAYOUT_PRESENT_SRC_KHR</span>.</p></div>
<divclass="paragraph"><p>If <spanclass="monospaced">image</span> was created with <spanclass="monospaced">VK_SWAPCHAIN_IMAGE_USAGE_FRONT_BUFFER_BIT_ANDROID</span>, then the driver must tolerate <spanclass="monospaced">vkQueueSignalReleaseImageANDROID</span> being called repeatedly without intervening calls to <spanclass="monospaced">vkAcquireImageANDROID</span>.</p></div>
</div>
</div>
<divclass="sect1">
@@ -978,6 +1017,33 @@ Updates to reflect final behavior, closed some TBDs now that they’ve BDed.
</li>
</ul></div>
</li>
<li>
<p>
<strong>2017-01-06</strong>
</p>
<divclass="ulist"><ul>
<li>
<p>
Extension version 6
</p>
</li>
<li>
<p>
Added VkSwapchainImageUsageFlagBitsANDROID
</p>
</li>
<li>
<p>
Added vkGetSwapchainGrallocUsage2ANDROID
</p>
</li>
<li>
<p>
Added VkSwapchainImageCreateInfoANDROID
</p>
</li>
</ul></div>
</li>
</ol></div>
</div>
</div>
@@ -986,7 +1052,7 @@ Updates to reflect final behavior, closed some TBDs now that they’ve BDed.
