Random VK_ANDROID_external_memory_android_hardware_buffer cleanup
This commit is contained in:
Petr Kraus
parent
e1c0e426f3
commit
0c47a7c5b1
|
|
@ -1,7 +1,5 @@
|
|||
include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[]
|
||||
|
||||
*Status*::
|
||||
Draft
|
||||
*Last Modified Date*::
|
||||
2018-03-04
|
||||
*IP Status*::
|
||||
|
|
@ -16,19 +14,19 @@ include::meta/VK_ANDROID_external_memory_android_hardware_buffer.txt[]
|
|||
- Matthew Netsch, Qualcomm
|
||||
- Andrew Garrard, Samsung
|
||||
|
||||
This extension enables an application to import Android AHardwareBuffer
|
||||
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 +AHardwareBuffer+ from a Vulkan memory object
|
||||
It also allows exporting an code:AHardwareBuffer from a Vulkan memory object
|
||||
for symmetry with other operating systems.
|
||||
But since not all +AHardwareBuffer+ usages and formats have Vulkan
|
||||
But since not all code:AHardwareBuffer usages and formats have Vulkan
|
||||
equivalents, exporting from Vulkan provides strictly less functionality than
|
||||
creating the +AHardwareBuffer+ externally and importing it.
|
||||
creating the code:AHardwareBuffer externally and importing it.
|
||||
|
||||
Some AHardwareBuffer images have implementation-defined _external formats_
|
||||
that may not correspond to Vulkan formats.
|
||||
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 colorspace.
|
||||
convert them to a known color space.
|
||||
|
||||
=== New Object Types
|
||||
|
||||
|
|
|
|||
|
|
@ -6814,7 +6814,7 @@ usages or flags are requested.
|
|||
Requiring at least one GPU usage flag ensures that Android hardware buffer
|
||||
memory will be allocated in a memory pool accessible to the Vulkan
|
||||
implementation, and that specializing the memory layout based on usage flags
|
||||
doesn't prevent it from being compatible with Vulkan.
|
||||
does not prevent it from being compatible with Vulkan.
|
||||
Implementations may: avoid unnecessary restrictions caused by this
|
||||
requirement by using vendor usage flags to indicate that only the Vulkan
|
||||
uses indicated in slink:VkImageFormatProperties2 are required.
|
||||
|
|
|
|||
|
|
@ -1084,7 +1084,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|||
** pname:allocationSize must: be the size returned by
|
||||
flink:vkGetAndroidHardwareBufferPropertiesANDROID for the Android
|
||||
hardware buffer
|
||||
** If the pname:pNext chain doesn't contain an instance of
|
||||
** If the pname:pNext chain does not contain an instance of
|
||||
slink:VkMemoryDedicatedAllocateInfo or
|
||||
pname:VkMemoryDedicatedAllocateInfo::pname:image is
|
||||
dlink:VK_NULL_HANDLE, the Android hardware buffer must: have a format
|
||||
|
|
@ -1933,7 +1933,7 @@ Each call to fname:vkGetMemoryAndroidHardwareBufferANDROID must: return an
|
|||
Android hardware buffer with a new reference acquired in addition to the
|
||||
reference held by the sname:VkDeviceMemory.
|
||||
To avoid leaking resources, the application must: release the reference by
|
||||
calling +AHardwareBuffer_release+ when it is no longer needed.
|
||||
calling code:AHardwareBuffer_release when it is no longer needed.
|
||||
When called with the same handle in
|
||||
sname:VkMemoryGetAndroidHardwareBufferInfoANDROID::pname:memory,
|
||||
fname:vkGetMemoryAndroidHardwareBufferANDROID must: return the same Android
|
||||
|
|
@ -2028,7 +2028,7 @@ include::../api/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[]
|
|||
* pname:sType is the type of this structure.
|
||||
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||||
* pname:format is the Vulkan format corresponding to the Android hardware
|
||||
buffer's format, or ename:VK_FORMAT_UNDEFINED if there isn't an
|
||||
buffer's format, or ename:VK_FORMAT_UNDEFINED if there is not an
|
||||
equivalent Vulkan format.
|
||||
* pname:externalFormat is an implementation-defined external format
|
||||
identifier for use with slink:VkExternalFormatANDROID.
|
||||
|
|
@ -2082,7 +2082,7 @@ If pname:format is ename:VK_FORMAT_UNDEFINED, all members of
|
|||
pname:samplerYcbcrConversionComponents must: be
|
||||
ename:VK_COMPONENT_SWIZZLE_IDENTITY.
|
||||
|
||||
Implementations may not always be able to determine the color model,
|
||||
Implementations may: not always be able to determine the color model,
|
||||
numerical range, or chroma offsets of the image contents, so the values in
|
||||
sname:VkAndroidHardwareBufferFormatPropertiesANDROID are only suggestions.
|
||||
Applications should: treat these values as sensible defaults to use in the
|
||||
|
|
@ -2693,7 +2693,7 @@ A sname:VkDeviceMemory imported from an Android hardware buffer or that can
|
|||
be exported to an Android hardware buffer must: acquire a reference to its
|
||||
code:AHardwareBuffer object, and must: release this reference when the
|
||||
device memory is freed.
|
||||
During the host execution of a Vulkan command which has an Android hardware
|
||||
During the host execution of a Vulkan command that has an Android hardware
|
||||
buffer as a parameter (including indirect parameters via pname:pNext
|
||||
chains), the application must: not decrement the Android hardware buffer's
|
||||
reference count to zero.
|
||||
|
|
@ -2724,37 +2724,36 @@ device.
|
|||
Vulkan buffer and image usage flags do not correspond exactly to Android
|
||||
hardware buffer usage flags.
|
||||
When allocating Android hardware buffers with non-Vulkan APIs, if any
|
||||
+AHARDWAREBUFFER_USAGE_GPU_*+ usage bits are included, by default the
|
||||
code:AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the
|
||||
allocator must: allocate the memory in such a way that it can support Vulkan
|
||||
usages and creation flags in the
|
||||
<<memory-external-android-hardware-buffer-usage, usage equivalence table>>
|
||||
which don't have Android hardware buffer equivalents.
|
||||
which do not have Android hardware buffer equivalents.
|
||||
|
||||
The slink:VkAndroidHardwareBufferUsageANDROID structure can: be attached to
|
||||
the pname:pNext chain of a slink:VkImageFormatProperties2 instance passed to
|
||||
flink:vkGetPhysicalDeviceImageFormatProperties2 to obtain optimal Android
|
||||
hardware buffer usage flags for specific Vulkan resource creation
|
||||
parameters.
|
||||
Some usage flags returned by these commands are required based on the input
|
||||
Some usage flags returned by these commands are required: based on the input
|
||||
parameters, but additional vendor-specific usage flags
|
||||
(+AHARDWAREBUFFER_USAGE_VENDOR_*+) may: also be returned.
|
||||
(code:AHARDWAREBUFFER_USAGE_VENDOR_*) may: also be returned.
|
||||
Any Android hardware buffer allocated with these vendor-specific usage flags
|
||||
and imported to Vulkan must: only be bound to resources created with
|
||||
parameters that are a subset of the parameters used to obtain the Android
|
||||
hardware buffer usage, since the memory may: have been allocated in a way
|
||||
incompatible with other parameters.
|
||||
If a Android hardware buffer is successfully allocated with additional
|
||||
If an Android hardware buffer is successfully allocated with additional
|
||||
non-vendor-specific usage flags in addition to the recommended usage, it
|
||||
must: support being used in the same ways as a Android hardware buffer
|
||||
must: support being used in the same ways as an Android hardware buffer
|
||||
allocated with only the recommended usage, and also in ways indicated by the
|
||||
additional usage.
|
||||
|
||||
[[memory-external-android-hardware-buffer-external-formats]]
|
||||
===== Android Hardware Buffer External Formats =====
|
||||
|
||||
Android hardware buffers can represent images using implementation-specific
|
||||
formats, layouts, color models, etc.
|
||||
which don't have Vulkan equivalents.
|
||||
Android hardware buffers may: represent images using implementation-specific
|
||||
formats, layouts, color models, etc., which do not have Vulkan equivalents.
|
||||
Such _external formats_ are commonly used by external image sources such as
|
||||
video decoders or cameras.
|
||||
Vulkan can: import Android hardware buffers that have external formats, but
|
||||
|
|
@ -2767,7 +2766,7 @@ Images that will be backed by a Android hardware buffer can use an external
|
|||
format by setting sname:VkImageCreateInfo::pname:format to
|
||||
ename:VK_FORMAT_UNDEFINED and including an instance of
|
||||
slink:VkExternalFormatANDROID in the pname:pNext chain.
|
||||
Images can be created with an external format even if the Android hardware
|
||||
Images can: be created with an external format even if the Android hardware
|
||||
buffer has a format which has an
|
||||
<<memory-external-android-hardware-buffer-formats,equivalent Vulkan format>>
|
||||
to enable consistent handling of images from sources that might use either
|
||||
|
|
@ -2822,7 +2821,7 @@ properties derived from the image:
|
|||
hardware buffer with usage returned in
|
||||
slink:VkAndroidHardwareBufferUsageANDROID.
|
||||
|
||||
Implementations may support fewer combinations of image creation parameters
|
||||
Implementations may: support fewer combinations of image creation parameters
|
||||
for images with Android hardware buffer external handle type than for
|
||||
non-external images.
|
||||
Support for a given set of parameters can be determined by passing
|
||||
|
|
@ -2830,7 +2829,7 @@ slink:VkExternalImageFormatProperties to
|
|||
flink:vkGetPhysicalDeviceImageFormatProperties2 with pname:handleType set to
|
||||
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
|
||||
Any Android hardware buffer successfully allocated outside Vulkan with usage
|
||||
that includes +AHARDWAREBUFFER_USAGE_GPU_*+ must be supported when using
|
||||
that includes code:AHARDWAREBUFFER_USAGE_GPU_* must: be supported when using
|
||||
equivalent Vulkan image parameters.
|
||||
If a given choice of image parameters are supported for import, they can:
|
||||
also be used to create an image and memory that will be exported to an
|
||||
|
|
@ -2877,11 +2876,11 @@ endif::VK_VERSION_1_1[]
|
|||
2::
|
||||
The code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE flag does not
|
||||
correspond to a Vulkan image usage or creation flag.
|
||||
Instead, it's presence indicates that the Android hardware buffer
|
||||
Instead, its presence indicates that the Android hardware buffer
|
||||
contains a complete set of mip levels
|
||||
(sname:VkImageCreateInfo::pname:mipLevels is
|
||||
[eq]#{lceil}log~2~(max(code:width, code:height)){rceil} {plus} 1#), and
|
||||
it's absence indicates that the Android hardware buffer contains only a
|
||||
its absence indicates that the Android hardware buffer contains only a
|
||||
single mip level.
|
||||
|
||||
ifdef::VK_KHR_image_format_list[]
|
||||
|
|
@ -2900,7 +2899,7 @@ endif::VK_KHR_image_format_list[]
|
|||
===== Android Hardware Buffer Buffer Resources
|
||||
|
||||
Android hardware buffers with a format of code:AHARDWAREBUFFER_FORMAT_BLOB
|
||||
and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER may be
|
||||
and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can: be
|
||||
used as the backing store for sname:VkBuffer objects.
|
||||
Such Android hardware buffers have a size in bytes specified by their
|
||||
code:width; code:height and code:layers are 1.
|
||||
|
|
|
|||
|
|
@ -658,11 +658,11 @@ ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
* [[VUID-VkImageCreateInfo-pNext-01889]]
|
||||
If the pname:pNext chain doesn't contain an instance of
|
||||
If the pname:pNext chain does not contain an instance of
|
||||
slink:VkExternalFormatANDROID, or if pname:format is not
|
||||
VK_FORMAT_UNDEFINED, the combination of pname:format, pname:imageType,
|
||||
pname:tiling, pname:usage, and pname:flags must: be supported, as
|
||||
indicated by a ename:VK_SUCCESS return value from
|
||||
ename:VK_FORMAT_UNDEFINED, the combination of pname:format,
|
||||
pname:imageType, pname:tiling, pname:usage, and pname:flags must: be
|
||||
supported, as indicated by a ename:VK_SUCCESS return value from
|
||||
fname:vkGetPhysicalDeviceImageFormatProperties invoked with the same
|
||||
values passed to the corresponding parameters.
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
|
|
@ -1071,9 +1071,9 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|||
pname:externalFormat member is not `0`
|
||||
* [[VUID-VkImageCreateInfo-pNext-01893]]
|
||||
If the pname:pNext chain includes a slink:VkExternalFormatANDROID
|
||||
structure whose pname:externalFormat member is not code:0:
|
||||
structure whose pname:externalFormat member is not `0`:
|
||||
** pname:format must: be ename:VK_FORMAT_UNDEFINED
|
||||
** pname:flags must: not include VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
||||
** pname:flags must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
||||
** pname:usage must: not include any usages except
|
||||
pname:VK_IMAGE_USAGE_SAMPLED_BIT
|
||||
** pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL
|
||||
|
|
@ -1202,7 +1202,7 @@ sname:VkImageCreateInfo::pname:format must: be ename:VK_FORMAT_UNDEFINED.
|
|||
.Valid Usage
|
||||
****
|
||||
* [[VUID-VkExternalFormatANDROID-externalFormat-01894]]
|
||||
pname:externalFormat must: be code:0 or a value returned in the
|
||||
pname:externalFormat must: be `0` or a value returned in the
|
||||
pname:externalFormat member of
|
||||
slink:VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call
|
||||
to flink:vkGetAndroidHardwareBufferPropertiesANDROID
|
||||
|
|
@ -1510,7 +1510,7 @@ flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single
|
|||
image.
|
||||
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
However, the subresource layout of images in Android hardware buffer
|
||||
external memory isn't known until the image has been bound to memory, so
|
||||
external memory is not known until the image has been bound to memory, so
|
||||
calling fname:vkGetImageSubresourceLayout for such an image before it has
|
||||
been bound will result in undefined behavior.
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
|
|
@ -1548,7 +1548,7 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|||
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
* [[VUID-vkGetImageSubresourceLayout-image-01895]]
|
||||
If pname:image was created with the
|
||||
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
||||
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
||||
external memory handle type, then pname:image must: be bound to memory.
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
****
|
||||
|
|
@ -2508,12 +2508,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|||
If pname:image has an
|
||||
<<memory-external-android-hardware-buffer-external-formats,external
|
||||
format>>:
|
||||
** pname:format must be ename:VK_FORMAT_UNDEFINED
|
||||
** The pname:pNext chain must contain an instance of
|
||||
** pname:format must: be ename:VK_FORMAT_UNDEFINED
|
||||
** The pname:pNext chain must: contain an instance of
|
||||
slink:VkSamplerYcbcrConversionInfo with a pname:conversion object
|
||||
created with the same external format as pname:image
|
||||
** All members of pname:components must be
|
||||
pname:VK_COMPONENT_SWIZZLE_IDENTITY
|
||||
** All members of pname:components must: be
|
||||
ename:VK_COMPONENT_SWIZZLE_IDENTITY
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
****
|
||||
|
||||
|
|
@ -2939,7 +2939,7 @@ When allocating new memory for an image that can: be exported to a Android
|
|||
hardware buffer, the memory's pname:allocationSize must: be zero; the actual
|
||||
size will be determined by the dedicated image's parameters.
|
||||
After the memory has been allocated, the amount of space allocated from the
|
||||
memory's heap can be obtained by getting the image's memory requirements or
|
||||
memory's heap can: be obtained by getting the image's memory requirements or
|
||||
by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID with the
|
||||
Android hardware buffer exported from the memory.
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
|
|
@ -3157,7 +3157,7 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|||
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
* [[VUID-VkImageMemoryRequirementsInfo2-image-01897]]
|
||||
If pname:image was created with the
|
||||
VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
||||
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
||||
external memory handle type, then pname:image must: be bound to memory.
|
||||
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
||||
****
|
||||
|
|
|
|||
Loading…
Reference in New Issue