1  include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[]
  2  
  3  *Last Modified Date*::
  4      2018-03-04
  5  *IP Status*::
  6      No known IP claims.
  7  *Contributors*::
  8    - Ray Smith, ARM
  9    - Chad Versace, Google
 10    - Jesse Hall, Google
 11    - Tobias Hector, Imagination
 12    - James Jones, NVIDIA
 13    - Tony Zlatinski, NVIDIA
 14    - Matthew Netsch, Qualcomm
 15    - Andrew Garrard, Samsung
 16  
 17  This extension enables an application to import Android
 18  dlink:AHardwareBuffer objects created outside of the Vulkan device into
 19  Vulkan memory objects, where they can: be bound to images and buffers.
 20  It also allows exporting an dlink:AHardwareBuffer from a Vulkan memory
 21  object for symmetry with other operating systems.
 22  But since not all dlink:AHardwareBuffer usages and formats have Vulkan
 23  equivalents, exporting from Vulkan provides strictly less functionality than
 24  creating the dlink:AHardwareBuffer externally and importing it.
 25  
 26  Some dlink:AHardwareBuffer images have implementation-defined _external
 27  formats_ that may: not correspond to Vulkan formats.
 28  Sampler Y'C~b~C~r~ conversion can: be used to sample from these images and
 29  convert them to a known color space.
 30  
 31  === New Object Types
 32  
 33  None.
 34  
 35  === New Enum Constants
 36  
 37    * Extending elink:VkStructureType:
 38    ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_USAGE_ANDROID
 39    ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_PROPERTIES_ANDROID
 40    ** ename:VK_STRUCTURE_TYPE_ANDROID_HARDWARE_BUFFER_FORMAT_PROPERTIES_ANDROID
 41    ** ename:VK_STRUCTURE_TYPE_IMPORT_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
 42    ** ename:VK_STRUCTURE_TYPE_MEMORY_GET_ANDROID_HARDWARE_BUFFER_INFO_ANDROID
 43    ** ename:VK_STRUCTURE_TYPE_EXTERNAL_FORMAT_ANDROID
 44  
 45    * Extending elink:VkExternalMemoryHandleTypeFlagBits:
 46    ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
 47  
 48  === New Enums
 49  
 50  None.
 51  
 52  === New Structs
 53  
 54    * slink:VkAndroidHardwareBufferUsageANDROID
 55    * slink:VkAndroidHardwareBufferPropertiesANDROID
 56    * slink:VkAndroidHardwareBufferFormatPropertiesANDROID
 57    * slink:VkImportAndroidHardwareBufferInfoANDROID
 58    * slink:VkMemoryGetAndroidHardwareBufferInfoANDROID
 59    * slink:VkExternalFormatANDROID
 60  
 61  === New Functions
 62  
 63    * flink:vkGetAndroidHardwareBufferPropertiesANDROID
 64    * flink:vkGetMemoryAndroidHardwareBufferANDROID
 65  
 66  === Issues
 67  
 68  1) Other external memory objects are represented as weakly-typed handles
 69  (e.g. Win32 code:HANDLE or POSIX file descriptor), and require a handle type
 70  parameter along with handles.
 71  dlink:AHardwareBuffer is strongly typed, so naming the handle type is
 72  redundant.
 73  Does symmetry justify adding handle type parameters/fields anyway?
 74  
 75  *RESOLVED*: No.
 76  The handle type is already provided in places that treat external memory
 77  objects generically.
 78  In the places we would add it, the application code that would have to
 79  provide the handle type value is already dealing with
 80  dlink:AHardwareBuffer-specific commands/structures; the extra symmetry would
 81  not be enough to make that code generic.
 82  
 83  2) The internal layout and therefore size of a dlink:AHardwareBuffer image
 84  may depend on native usage flags that do not have corresponding Vulkan
 85  counterparts.
 86  Do we provide this info to flink:vkCreateImage somehow, or allow the
 87  allocation size reported by flink:vkGetImageMemoryRequirements to be
 88  approximate?
 89  
 90  *RESOLVED*: Allow the allocation size to be unspecified when allocating the
 91  memory.
 92  It has to work this way for exported image memory anyway, since
 93  dlink:AHardwareBuffer allocation happens in flink:vkAllocateMemory, and
 94  internally is performed by a separate HAL, not the Vulkan implementation
 95  itself.
 96  There is a similar issue with flink:vkGetImageSubresourceLayout: the layout
 97  is determined by the allocator HAL, so it is not known until the image is
 98  bound to memory.
 99  
100  3) Should the result of sampling an external-format image with the suggested
101  Y'C~b~C~r~ conversion parameters yield the same results as using a
102  code:samplerExternalOES in OpenGL ES?
103  
104  *RESOLVED*: This would be desirable, so that apps converting from OpenGL ES
105  to Vulkan could get the same output given the same input.
106  But since sampling and conversion from Y'C~b~C~r~ images is so loosely
107  defined in OpenGL ES, multiple implementations do it in a way that doesn't
108  conform to Vulkan's requirements.
109  Modifying the OpenGL ES implementation would be difficult, and would change
110  the output of existing unmodified applications.
111  Changing the output only for applications that are being modified gives
112  developers the chance to notice and mitigate any problems.
113  Implementations are encouraged to minimize differences as much as possible
114  without causing compatibility problems for existing OpenGL ES applications
115  or violating Vulkan requirements.
116  
117  4) Should an dlink:AHardwareBuffer with code:AHARDWAREBUFFER_USAGE_CPU_*
118  usage be mappable in Vulkan? Should it be possible to export an
119  code:AHardwareBuffers with such usage?
120  
121  *RESOLVED*: Optional, and mapping in Vulkan is not the same as
122  code:AHardwareBuffer_lock.
123  The semantics of these are different: mapping in memory is persistent, just
124  gives a raw view of the memory contents, and does not involve ownership.
125  code:AHardwareBuffer_lock gives the host exclusive access to the buffer, is
126  temporary, and allows for reformatting copy-in/copy-out.
127  Implementations are not required to support host-visible memory types for
128  imported Android hardware buffers or resources backed by them.
129  If a host-visible memory type is supported and used, the memory can be
130  mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw
131  view of the data and does not imply ownership (this means implementations
132  must not internally call code:AHardwareBuffer_lock to implement
133  flink:vkMapMemory, or assume the application has done so).
134  Implementations are not required to support linear-tiled images backed by
135  Android hardware buffers, even if the dlink:AHardwareBuffer has CPU usage.
136  There is no reliable way to allocate memory in Vulkan that can be exported
137  to a dlink:AHardwareBuffer with CPU usage.
138  
139  5) Android may add new dlink:AHardwareBuffer formats and usage flags over
140  time.
141  Can reference to them be added to this extension, or do they need a new
142  extension?
143  
144  RESOLVED: This extension can document the interaction between the new AHB
145  formats/usages and existing Vulkan features.
146  No new Vulkan features or implementation requirements can be added.
147  The extension version number will be incremented when this additional
148  documentation is added, but the version number does not indicate that an
149  implementaiton supports Vulkan memory or resources that map to the new
150  dlink:AHardwareBuffer features: support for that must be queried with
151  flink:vkGetPhysicalDeviceImageFormatProperties2 or is implied by
152  successfully allocating a dlink:AHardwareBuffer outside of Vulkan that uses
153  the new feature and has a GPU usage flag.
154  
155  In essence, these are new features added to a new Android API level, rather
156  than new Vulkan features.
157  The extension will only document how existing Vulkan features map to that
158  new Android feature.