Vulkan-Docs/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt

include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[]

*Status*::
    Draft
*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 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 +AHardwareBuffer+ from a Vulkan memory object
for symmetry with other operating systems.
But since not all +AHardwareBuffer+ usages and formats have Vulkan
equivalents, exporting from Vulkan provides strictly less functionality than
creating the +AHardwareBuffer+ externally and importing it.

Some 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 colorspace.

=== New Object Types

None.

=== New Enum Constants

  * 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
  * 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 HANDLE or POSIX file descriptor), and require a handle type
parameter along with handles.
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
AHardwareBuffer-specific commands/structures; the extra symmetry wouldn't be
enough to make that code generic.

2) The internal layout and therefore size of a AHardwareBuffer image may
depend on native usage flags that don't have corresponding Vulkan
counterparts.
Do we provide this info to vkCreateImage somehow, or allow the allocation
size reported by 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
AHardwareBuffer allocation happens in vkAllocateMemory, and internally is
performed by a separate HAL, not the Vulkan implementation itself.
There is a similar issue with vkGetImageSubresourceLayout: the layout is
determined by the allocator HAL, so it isn't 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
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 AHardwareBuffers with +AHARDWAREBUFFER_USAGE_CPU_*+ usage be
mappable in Vulkan? Should it be possible to export AHardwareBuffers with
such usage?

*RESOLVED*: Optional, and mapping in Vulkan is not the same as
+AHardwareBuffer_lock+.
The semantics of these are different: mapping in memory is persistent, just
gives a raw view of the memory contents, and doesn't involve ownership.
+AHardwareBuffer_lock+ gives the host exclusive access to the buffer, is
temporary, and allows for reformatting copy-in/copy-out.
Implementations aren't 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's just a raw
view of the data and doesn't imply ownership (this means implementations
must not internally call +AHardwareBuffer_lock+ to implement
fname:vkMapMemory, or assume the application has done so).
Implementations aren't required to support linear-tiled images backed by
Android hardware buffers, even if the +AHardwareBuffer+ has CPU usage.
There is no reliable way to allocate memory in Vulkan that can be exported
to a +AHardwareBuffer+ with CPU usage.

5) Android may add new +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 doesn't indicate that an
implementaiton supports Vulkan memory or resources that map to the new
+AHardwareBuffer+ features: support for that must be queried with
flink:vkGetPhysicalDeviceImageFormatSupport2 or is implied by successfully
allocating a +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.