From 0c47a7c5b169577f770b307b7c1b4473d74190d7 Mon Sep 17 00:00:00 2001 From: Petr Kraus Date: Mon, 9 Apr 2018 22:18:25 +0200 Subject: [PATCH] Random VK_ANDROID_external_memory_android_hardware_buffer cleanup --- ...xternal_memory_android_hardware_buffer.txt | 16 ++++---- chapters/features.txt | 2 +- chapters/memory.txt | 39 +++++++++---------- chapters/resources.txt | 30 +++++++------- 4 files changed, 42 insertions(+), 45 deletions(-) diff --git a/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt b/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt index 64cf7520..854d584b 100644 --- a/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt +++ b/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt @@ -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 diff --git a/chapters/features.txt b/chapters/features.txt index f0e9e971..1e21f211 100644 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -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. diff --git a/chapters/memory.txt b/chapters/memory.txt index 816ee5fb..844f5bc8 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -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 <> -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 <> 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. diff --git a/chapters/resources.txt b/chapters/resources.txt index b3002792..69aeac5e 100644 --- a/chapters/resources.txt +++ b/chapters/resources.txt @@ -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 <>: - ** 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[] ****