| include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[] |
| |
| *Last Modified Date*:: |
| 2018-03-04 |
| *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 |
| |
| This extension enables an application to import Android code: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 code:AHardwareBuffer from a Vulkan memory object |
| for symmetry with other operating systems. |
| But since not all code:AHardwareBuffer usages and formats have Vulkan |
| equivalents, exporting from Vulkan provides strictly less functionality than |
| creating the code:AHardwareBuffer externally and importing it. |
| |
| Some code:AHardwareBuffer images have implementation-defined _external |
| formats_ that may: not correspond to Vulkan formats. |
| Sampler Y'C~b~C~r~ conversion can: be used to sample from these images and |
| convert them to a known color space. |
| |
| === New Object Types |
| |
| None. |
| |
| === New Enum Constants |
| |
| * Extending ename:VkStructureType: |
| ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID |
| ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID |
| ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID |
| ** ename:VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID |
| ** ename:VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID |
| ** ename:VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID |
| |
| * Extending ename:VkExternalMemoryHandleTypeFlagBits: |
| ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| |
| === New Enums |
| |
| None. |
| |
| === New Structs |
| |
| * slink:VkAndroidHardwareBufferUsageANDROID |
| * slink:VkAndroidHardwareBufferPropertiesANDROID |
| * slink:VkAndroidHardwareBufferFormatPropertiesANDROID |
| * slink:VkImportAndroidHardwareBufferInfoANDROID |
| * slink:VkMemoryGetAndroidHardwareBufferInfoANDROID |
| * slink:VkExternalFormatANDROID |
| |
| === New Functions |
| |
| * flink:vkGetAndroidHardwareBufferPropertiesANDROID |
| * flink:vkGetMemoryAndroidHardwareBufferANDROID |
| |
| === 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. |
| code: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 |
| code: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 code:AHardwareBuffer image |
| may depend on native usage flags that do not have corresponding Vulkan |
| counterparts. |
| Do we provide this info 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 |
| code: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 |
| Y'C~b~C~r~ 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 Y'C~b~C~r~ images is so loosely |
| defined in OpenGL ES, multiple implementations do it in a way that doesn't |
| 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 code: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 code:AHardwareBuffer has CPU usage. |
| There is no reliable way to allocate memory in Vulkan that can be exported |
| to a code:AHardwareBuffer with CPU usage. |
| |
| 5) Android may add new code: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 |
| code:AHardwareBuffer features: support for that must be queried with |
| flink:vkGetPhysicalDeviceImageFormatProperties2 or is implied by |
| successfully allocating a code: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. |