| // Copyright (c) 2018-2020 Google LLC |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| include::{generated}/meta/{refprefix}VK_ANDROID_external_memory_android_hardware_buffer.txt[] |
| |
| === Other Extension Metadata |
| |
| *Last Modified Date*:: |
| 2021-09-30 |
| *IP Status*:: |
| No known IP claims. |
| *Contributors*:: |
| - Ray Smith, ARM |
| - Chad Versace, Google |
| - Jesse Hall, Google |
| - Tobias Hector, Imagination |
| - James Jones, NVIDIA |
| - Tony Zlatinski, NVIDIA |
| - Matthew Netsch, Qualcomm |
| - Andrew Garrard, Samsung |
| |
| === Description |
| |
| This extension enables an application to import Android |
| basetype:AHardwareBuffer objects created outside of the Vulkan device into |
| Vulkan memory objects, where they can: be bound to images and buffers. |
| It also allows exporting an basetype:AHardwareBuffer from a Vulkan memory |
| object for symmetry with other operating systems. |
| But since not all basetype:AHardwareBuffer usages and formats have Vulkan |
| equivalents, exporting from Vulkan provides strictly less functionality than |
| creating the basetype:AHardwareBuffer externally and importing it. |
| |
| Some basetype:AHardwareBuffer images have implementation-defined _external |
| formats_ that may: not correspond to Vulkan formats. |
| Sampler {YCbCr} conversion can: be used to sample from these images and |
| convert them to a known color space. |
| |
| include::{generated}/interfaces/VK_ANDROID_external_memory_android_hardware_buffer.txt[] |
| |
| === Issues |
| |
| 1) Other external memory objects are represented as weakly-typed handles |
| (e.g. Win32 code:HANDLE or POSIX file descriptor), and require a handle type |
| parameter along with handles. |
| basetype:AHardwareBuffer is strongly typed, so naming the handle type is |
| redundant. |
| Does symmetry justify adding handle type parameters/fields anyway? |
| |
| *RESOLVED*: No. |
| The handle type is already provided in places that treat external memory |
| objects generically. |
| In the places we would add it, the application code that would have to |
| provide the handle type value is already dealing with |
| basetype:AHardwareBuffer-specific commands/structures; the extra symmetry |
| would not be enough to make that code generic. |
| |
| 2) The internal layout and therefore size of a basetype:AHardwareBuffer |
| image may depend on native usage flags that do not have corresponding Vulkan |
| counterparts. |
| Do we provide this information to flink:vkCreateImage somehow, or allow the |
| allocation size reported by flink:vkGetImageMemoryRequirements to be |
| approximate? |
| |
| *RESOLVED*: Allow the allocation size to be unspecified when allocating the |
| memory. |
| It has to work this way for exported image memory anyway, since |
| basetype:AHardwareBuffer allocation happens in flink:vkAllocateMemory, and |
| internally is performed by a separate HAL, not the Vulkan implementation |
| itself. |
| There is a similar issue with flink:vkGetImageSubresourceLayout: the layout |
| is determined by the allocator HAL, so it is not known until the image is |
| bound to memory. |
| |
| 3) Should the result of sampling an external-format image with the suggested |
| {YCbCr} conversion parameters yield the same results as using a |
| code:samplerExternalOES in OpenGL ES? |
| |
| *RESOLVED*: This would be desirable, so that apps converting from OpenGL ES |
| to Vulkan could get the same output given the same input. |
| But since sampling and conversion from {YCbCr} images is so loosely defined |
| in OpenGL ES, multiple implementations do it in a way that does not conform |
| to Vulkan's requirements. |
| Modifying the OpenGL ES implementation would be difficult, and would change |
| the output of existing unmodified applications. |
| Changing the output only for applications that are being modified gives |
| developers the chance to notice and mitigate any problems. |
| Implementations are encouraged to minimize differences as much as possible |
| without causing compatibility problems for existing OpenGL ES applications |
| or violating Vulkan requirements. |
| |
| 4) Should an basetype:AHardwareBuffer with code:AHARDWAREBUFFER_USAGE_CPU_* |
| usage be mappable in Vulkan? Should it be possible to export an |
| code:AHardwareBuffers with such usage? |
| |
| *RESOLVED*: Optional, and mapping in Vulkan is not the same as |
| code:AHardwareBuffer_lock. |
| The semantics of these are different: mapping in memory is persistent, just |
| gives a raw view of the memory contents, and does not involve ownership. |
| code:AHardwareBuffer_lock gives the host exclusive access to the buffer, is |
| temporary, and allows for reformatting copy-in/copy-out. |
| Implementations are not required to support host-visible memory types for |
| imported Android hardware buffers or resources backed by them. |
| If a host-visible memory type is supported and used, the memory can be |
| mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw |
| view of the data and does not imply ownership (this means implementations |
| must not internally call code:AHardwareBuffer_lock to implement |
| flink:vkMapMemory, or assume the application has done so). |
| Implementations are not required to support linear-tiled images backed by |
| Android hardware buffers, even if the basetype:AHardwareBuffer has CPU |
| usage. |
| There is no reliable way to allocate memory in Vulkan that can be exported |
| to a basetype:AHardwareBuffer with CPU usage. |
| |
| 5) Android may add new basetype:AHardwareBuffer formats and usage flags over |
| time. |
| Can reference to them be added to this extension, or do they need a new |
| extension? |
| |
| *RESOLVED*: This extension can document the interaction between the new AHB |
| formats/usages and existing Vulkan features. |
| No new Vulkan features or implementation requirements can be added. |
| The extension version number will be incremented when this additional |
| documentation is added, but the version number does not indicate that an |
| implementaiton supports Vulkan memory or resources that map to the new |
| basetype:AHardwareBuffer features: support for that must be queried with |
| flink:vkGetPhysicalDeviceImageFormatProperties2 or is implied by |
| successfully allocating a basetype:AHardwareBuffer outside of Vulkan that |
| uses the new feature and has a GPU usage flag. |
| |
| In essence, these are new features added to a new Android API level, rather |
| than new Vulkan features. |
| The extension will only document how existing Vulkan features map to that |
| new Android feature. |
| |
| === Version History |
| |
| * Revision 4, 2021-09-30 (Jon Leech) |
| - Add interaction with `apiext:VK_KHR_format_feature_flags2` to `vk.xml` |
| * Revision 3, 2019-08-27 (Jon Leech) |
| - Update revision history to correspond to XML version number |
| * Revision 2, 2018-04-09 (Petr Kraus) |
| - Markup fixes and remove incorrect Draft status |
| * Revision 1, 2018-03-04 (Jesse Hall) |
| - Initial version |