mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-23 19:48:25 +00:00
e665b9e691
* Update release number to 75.
Github Issues:
* Use Github handles (e.g. @handle) for contact information in vk.xml,
when available (partial fix for public issue 630).
* Add size invariance guarantee to slink:VkMemoryRequirements for
buffer/image memory requirements (public issue 661).
* Correct scope (conditional constructs) in valid usage statement for
slink:VkBindImageMemoryInfo (public pull request 684).
* Clean up minor markup issues and typos in the
`VK_ANDROID_external_memory_android_hardware_buffer` extension appendix
(public pull request 698).
* Modify registry processing script to avoid irrelevant warnings of benign
enumerant redefinitions (public pull request 705).
* Fix some duplicate words and some misspelled "`stagess`" (public pull
request 712)
Internal Issues:
* Enable continuous integration tests on the internal Khronos gitlab
server by adding a .gitlab-ci.yml file. Note: this does not implement CI
on the public Github repository (internal issue 408).
* Add link from description of depth clamping in the <<fragops-depth,
depth test>> section to the
slink:VkPipelineRasterizationStateCreateInfo::pname:depthClampEnable
parameter which enables it, making it easily searchable / findable
(internal issue 1125).
* Clarify that arrays of arrays of descriptors are not allowed in the
<<interfaces-resources-descset, Descriptor Set Interface>> and
<<interfaces-resources-setandbinding, DescriptorSet and Binding
Assignment>> sections (internal issue 1192).
* Comment out some redundant nested asciidoctor conditionals in the
slink:VkImageViewCreateInfo valid usage block, and explain in all cases
why the redundant conditional exist and are commented out (internal
issue 1231).
* Move a valid usage statement from slink:VkCommandPoolCreateInfo to the
parent flink:vkCreateCommandPool, where the device queue is known
(internal issue 1233).
* Add new slink:VkBaseInStructure and slink:VkBaseOutStructure types which
can be used by extensions and implementations for handling Vulkan
sType/pNext style structures in a more generic way (internal issue
1265).
* Clarify that
slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures
only applies to external-format images. Add references to this in valid
usage statements that previously only referred to
slink:VkFormatProperties (internal issue 1244).
* Fix the description of elink:VkPipelineCreateFlagBits enumerant
ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT to match the
name (internal issue 1279).
* Add a NOTE to the <<interfaces-resources-setandbinding, DescriptorSet
and Binding Assignment>> section making it clear that variables sharing
a storage class may use identical descriptor set and bindings.
Specifically state the sometimes misunderstood ability to have one or
more differently typed image descriptors sharing a descriptor set and
binding (internal SPIR-V issue 264).
* Make DynamicIndexing features and capabilities also control the
uniformity of the descriptor used in memory access instructions in the
<<interfaces-resources-descset, Descriptor Set Interface>> section. This
makes them also apply to variable_pointer usage, which can bypass the
array indexing operation (internal SPIR-V issue 289).
Other Issues:
* Correct flink:vkCmdBlitImage limitations on cubic blits to be 2D only,
not 3D.
* Update valid usage statements for slink:VkRenderPassCreateInfo and
slink:VkInputAttachmentAspectReference.
* Move YCbCr-related VU statements from slink:VkDescriptorImageInfo to
slink:VkWriteDescriptorSet, where all needed information is known, and
remove redundant statements.
* Move SPIR-V restriction that images be of either sampled or storage
types from the <<interfaces-resources-descset, Descriptor Set
Interface>> section to the <<spirvenv-module-validation, Validation
Rules within a Module>> section of the SPIR-V appendix.
154 lines
6.6 KiB
Plaintext
154 lines
6.6 KiB
Plaintext
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:vkGetPhysicalDeviceImageFormatProperties2 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.
|