From d84e6a27ca8472acc89dddf3b67f704cf2cffdb7 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 | 107 ++++++------- chapters/clears.txt | 24 +-- chapters/copies.txt | 108 ++++++------- chapters/dispatch.txt | 48 +++--- chapters/drawing.txt | 132 ++++++++-------- chapters/features.txt | 2 +- chapters/memory.txt | 144 +++++++++--------- chapters/resources.txt | 36 ++--- 8 files changed, 303 insertions(+), 298 deletions(-) diff --git a/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt b/appendices/VK_ANDROID_external_memory_android_hardware_buffer.txt index a44cd9b4..4574e9c7 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 +where they can: be bound to images and buffers. +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. -Sampler Y'C~b~C~r~ conversion can be used to sample from these images and -convert them to a known colorspace. +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 color space. === New Object Types @@ -36,13 +34,16 @@ 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 + * Extending ename:VkStructureType: + ** 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 + + * Extending ename:VkExternalMemoryHandleTypeFlagBits: + ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID === New Enums @@ -65,9 +66,10 @@ None. === 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 +(e.g. Win32 code: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. +code:AHardwareBuffer is strongly typed, so naming the handle type is +redundant. Does symmetry justify adding handle type parameters/fields anyway? *RESOLVED*: No. @@ -75,27 +77,29 @@ 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. +code:AHardwareBuffer-specific commands/structures; the extra symmetry +would not 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 +2) The internal layout and therefore size of a code:AHardwareBuffer image +may depend on native usage flags that do not have corresponding Vulkan counterparts. -Do we provide this info to vkCreateImage somehow, or allow the allocation -size reported by vkGetImageMemoryRequirements to be approximate? +Do we provide this info to flink:vkCreateImage somehow, or allow the +allocation size reported by flink: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. +code:AHardwareBuffer allocation happens in flink:vkAllocateMemory, and +internally is performed by a separate HAL, not the Vulkan implementation +itself. +There is a similar issue with flink:vkGetImageSubresourceLayout: the layout +is determined by the allocator HAL, so it is not 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? +code: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. @@ -110,29 +114,30 @@ 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? +4) Should an code:AHardwareBuffer with code:AHARDWAREBUFFER_USAGE_CPU_* +usage be mappable in Vulkan? Should it be possible to export an +code:AHardwareBuffers with such usage? *RESOLVED*: Optional, and mapping in Vulkan is not the same as -+AHardwareBuffer_lock+. +code: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 +gives a raw view of the memory contents, and does not involve ownership. +code: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 +Implementations are not 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. +mapped in Vulkan, but doing so follows Vulkan semantics: it is just a raw +view of the data and does not imply ownership (this means implementations +must not internally call code:AHardwareBuffer_lock to implement +flink:vkMapMemory, or assume the application has done so). +Implementations are not required to support linear-tiled images backed by +Android hardware buffers, even if the code:AHardwareBuffer has CPU usage. There is no reliable way to allocate memory in Vulkan that can be exported -to a +AHardwareBuffer+ with CPU usage. +to a code:AHardwareBuffer with CPU usage. -5) Android may add new +AHardwareBuffer+ formats and usage flags over time. +5) Android may add new code:AHardwareBuffer formats and usage flags over +time. Can reference to them be added to this extension, or do they need a new extension? @@ -140,12 +145,12 @@ 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 +documentation is added, but the version number does not indicate that an implementaiton supports Vulkan memory or resources that map to the new -+AHardwareBuffer+ features: support for that must be queried with +code: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. +successfully allocating a code: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. diff --git a/chapters/clears.txt b/chapters/clears.txt index 61c23741..9cea373a 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -63,12 +63,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdClearColorImage-image-01935]] pname:image must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdClearColorImage-image-00002]] @@ -181,12 +181,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdClearDepthStencilImage-image-01936]] pname:image must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdClearDepthStencilImage-image-00009]] diff --git a/chapters/copies.txt b/chapters/copies.txt index bca76515..cb0369b5 100644 --- a/chapters/copies.txt +++ b/chapters/copies.txt @@ -48,9 +48,9 @@ ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] * Source images must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by endif::VK_ANDROID_external_memory_android_hardware_buffer[] sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by @@ -59,9 +59,9 @@ endif::VK_ANDROID_external_memory_android_hardware_buffer[] * Destination images must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by endif::VK_ANDROID_external_memory_android_hardware_buffer[] sname:VkFormatProperties::pname:linearTilingFeatures or sname:VkFormatProperties::pname:optimalTilingFeatures returned by @@ -360,12 +360,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImage-srcImage-01938]] pname:srcImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImage-srcImage-00126]] @@ -413,12 +413,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImage-dstImage-01939]] pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImage-dstImage-00131]] @@ -939,12 +939,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyBufferToImage-dstImage-01940]] pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyBufferToImage-srcBuffer-00176]] @@ -1077,12 +1077,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImageToBuffer-srcImage-01941]] pname:srcImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdCopyImageToBuffer-srcImage-00186]] @@ -1609,12 +1609,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdBlitImage-srcImage-01942]] pname:srcImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_SRC_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -1656,12 +1656,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdBlitImage-dstImage-01943]] pname:dstImage must: use a format that supports ename:VK_FORMAT_FEATURE_TRANSFER_DST_BIT, which is indicated by - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -1728,12 +1728,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] If pname:filter is ename:VK_FILTER_LINEAR, pname:srcImage must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_IMG_filter_cubic[] @@ -1752,12 +1752,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] If pname:filter is ename:VK_FILTER_CUBIC_IMG, pname:srcImage must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned byflink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdBlitImage-filter-00237]] diff --git a/chapters/dispatch.txt b/chapters/dispatch.txt index 878f3057..bbee56f5 100644 --- a/chapters/dispatch.txt +++ b/chapters/dispatch.txt @@ -116,12 +116,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_IMG_filter_cubic[] @@ -142,12 +142,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatch-None-00400]] @@ -284,12 +284,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] ifdef::VK_IMG_filter_cubic[] @@ -310,12 +310,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDispatchIndirect-None-00416]] diff --git a/chapters/drawing.txt b/chapters/drawing.txt index 6b943210..1f3ab690 100644 --- a/chapters/drawing.txt +++ b/chapters/drawing.txt @@ -610,16 +610,16 @@ 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-vkCmdDraw-formatFeatures-01953]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDraw-None-01499]] @@ -643,12 +643,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDraw-None-00452]] @@ -836,16 +836,16 @@ 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-vkCmdDrawIndexed-formatFeatures-01955]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndexed-None-01500]] @@ -869,12 +869,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndexed-None-00472]] @@ -1071,16 +1071,16 @@ 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-vkCmdDrawIndirect-formatFeatures-01957]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndirect-None-01501]] @@ -1104,12 +1104,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndirect-None-00498]] @@ -1570,16 +1570,16 @@ 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-vkCmdDrawIndirectCountAMD-formatFeatures-01959]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndirectCountAMD-None-01502]] @@ -1776,16 +1776,16 @@ 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-vkCmdDrawIndexedIndirect-formatFeatures-01960]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndexedIndirect-None-01503]] @@ -1809,12 +1809,12 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] result of this command must: be of a format which supports cubic filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_IMG flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndexedIndirect-None-00550]] @@ -2284,16 +2284,16 @@ 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-vkCmdDrawIndexedIndirectCountAMD-formatFeatures-01962]] - Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a + Any slink:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in - sname:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures - returned by vkGetAndroidHardwareBufferPropertiesANDROID for external - format images, or by - sname:VkFormatProperties::pname:linearTilingFeatures or - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties for non-external format + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID for + external format images, or by + slink:VkFormatProperties::pname:linearTilingFeatures or + slink:VkFormatProperties::pname:optimalTilingFeatures returned by + flink:vkGetPhysicalDeviceFormatProperties for non-external format linearly or optimally tiled images, respectively endif::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-vkCmdDrawIndexedIndirectCountAMD-None-01504]] 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 f1e360ae..2275030c 100644 --- a/chapters/memory.txt +++ b/chapters/memory.txt @@ -913,6 +913,7 @@ ifdef::VK_KHR_external_memory_win32,VK_KHR_external_memory_fd,VK_EXT_external_me An instance of the slink:VkMemoryAllocateInfo structure defines a memory import operation if the pname:pNext chain contains an instance of one of the following structures: + ifdef::VK_KHR_external_memory_win32[] * slink:VkImportMemoryWin32HandleInfoKHR with non-zero pname:handleType value @@ -1084,7 +1085,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 @@ -1107,19 +1108,20 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] of slink:VkMemoryDedicatedAllocateInfo with pname:image that is not dlink:VK_NULL_HANDLE: ** The Android hardware buffer's usage must: include at least one of - ename:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or - ename:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE - ** The pname:image's format must: be ename:VK_FORMAT_UNDEFINED or the + code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT or + code:AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE + ** The format of pname:image must: be ename:VK_FORMAT_UNDEFINED or the format returned by flink:vkGetAndroidHardwareBufferPropertiesANDROID in slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:format for the Android hardware buffer. - ** The image's and Android hardware buffer's width, height, and array - layer dimensions must: be the same + ** The width, height, and array layer dimensions of pname:image and the + Android hardware buffer must: be identical ** If the Android hardware buffer's usage includes - code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the image must have + code:AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE, the pname:image must: + have [eq]#{lfloor}log~2~(max(code:width, code:height)){rfloor} {plus} 1# - mip levels, otherwise it must have exactly `1` mip level. - ** Each bit set in the image's usage must: be listed in + mip levels, otherwise it must: have exactly `1` mip level. + ** Each bit set in the usage of pname:image must: be listed in <>, and if there is a corresponding code:AHARDWAREBUFFER_USAGE bit listed that bit must: be included in @@ -1881,7 +1883,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] To import memory created outside of the current Vulkan instance from an Android hardware buffer, add a -slink:VkImportAndroidHardwareBufferInfoANDROID structure to the pname:pNext +sname:VkImportAndroidHardwareBufferInfoANDROID structure to the pname:pNext chain of the slink:VkMemoryAllocateInfo structure. The sname:VkImportAndroidHardwareBufferInfoANDROID structure is defined as: @@ -1891,7 +1893,7 @@ include::../api/structs/VkImportAndroidHardwareBufferInfoANDROID.txt[] * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:buffer is the Android hardware buffer to import. -If the fname:vkAllocateMemory command succeeds, the implementation must: +If the flink:vkAllocateMemory command succeeds, the implementation must: acquire a reference to the imported hardware buffer, which it must: release when the device memory object is freed. If the command fails, the implementation must: not retain a reference. @@ -1931,11 +1933,11 @@ include::../api/protos/vkGetMemoryAndroidHardwareBufferANDROID.txt[] 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. +reference held by the slink: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, +slink:VkMemoryGetAndroidHardwareBufferInfoANDROID::pname:memory, fname:vkGetMemoryAndroidHardwareBufferANDROID must: return the same Android hardware buffer object. If the device memory was created by importing an Android hardware buffer, @@ -1967,10 +1969,10 @@ include::../api/structs/VkMemoryGetAndroidHardwareBufferInfoANDROID.txt[] slink:VkExportMemoryAllocateInfoKHR::pname:handleTypes when pname:memory was created. * [[VUID-VkMemoryGetAndroidHardwareBufferInfoANDROID-pNext-01883]] - If the pname:pNext chain of the pname:VkMemoryAllocateInfo used to - allocate pname:memory included a sname:VkMemoryDedicatedAllocateInfo - with non-NULL pname:image member, then that pname:image must: already be - bound to pname:memory. + If the pname:pNext chain of the slink:VkMemoryAllocateInfo used to + allocate pname:memory included a slink:VkMemoryDedicatedAllocateInfo + with non-`NULL` pname:image member, then that pname:image must: already + be bound to pname:memory. **** -- @@ -2028,7 +2030,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. @@ -2051,7 +2053,7 @@ If the Android hardware buffer has one of the formats listed in the table>>, then pname:format must: have the equivalent Vulkan format listed in the table. Otherwise, pname:format may: be ename:VK_FORMAT_UNDEFINED, indicating the -Android hardware buffer can only be used with an external format. +Android hardware buffer can: only be used with an external format. The pname:formatFeatures member must: include ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and at least one of @@ -2065,7 +2067,7 @@ ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT. ==== The pname:formatFeatures member only indicates the features available when using an -> created from the Android hardware buffer. Images from Android hardware buffers with a format other than ename:VK_FORMAT_UNDEFINED are subject to the format capabilities obtained @@ -2073,7 +2075,7 @@ from flink:vkGetPhysicalDeviceFormatProperties2, and flink:vkGetPhysicalDeviceImageFormatProperties2 with appropriate parameters. These sets of features are independent of each other, e.g. the external format will support sampler Y'C~B~C~R~ conversion even if the non-external -format doesn't, and writing to non-external format images is possible but +format does not, and writing to non-external format images is possible but writing to external format images is not. ==== @@ -2100,23 +2102,26 @@ 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 absence of more reliable information obtained through some other means. If the underlying physical device is also usable via OpenGL ES with the -GL_OES_EGL_image_external extension, the implementation should: suggest -values that will produce similar sampled values as would be obtained by -sampling the same external image via code:samplerExternalOES in OpenGL ES -using equivalent sampler parameters. +https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] +extension, the implementation should: suggest values that will produce +similar sampled values as would be obtained by sampling the same external +image via code:samplerExternalOES in OpenGL ES using equivalent sampler +parameters. [NOTE] .Note ==== -Since GL_OES_EGL_image_external does not require the same sampling and -conversion calculations as Vulkan does, achieving identical results between -APIs may: not be possible on some implementations. +Since +https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt[+GL_OES_EGL_image_external+] +does not require the same sampling and conversion calculations as Vulkan +does, achieving identical results between APIs may: not be possible on some +implementations. ==== include::../validity/structs/VkAndroidHardwareBufferFormatPropertiesANDROID.txt[] @@ -2695,36 +2700,35 @@ ifdef::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_ha [[memory-external-handle-types]] === External Memory Handle Types -ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] [[memory-external-android-hardware-buffer]] ==== Android Hardware Buffer -Android's NDK defines code:AHardwareBuffer objects which represent device -memory that is shareable across processes and that can be accessed by a +Android's NDK defines code:AHardwareBuffer objects, which represent device +memory that is shareable across processes and that can: be accessed by a variety of media APIs and the hardware used to implement them. -These Android hardware buffer objects may be imported into -sname:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. +These Android hardware buffer objects may: be imported into +slink:VkDeviceMemory objects for access via Vulkan, or exported from Vulkan. Android hardware buffer objects are reference-counted using Android NDK -functions outside the scope of this specification. -A sname:VkDeviceMemory imported from an Android hardware buffer or that can +functions outside of the scope of this specification. +A slink: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. -Android hardware buffers can be mapped and unmapped for CPU access using NDK -functions. +Android hardware buffers can: be mapped and unmapped for CPU access using +the NDK functions. These lock and unlock APIs are considered to acquire and release ownership of the Android hardware buffer, and applications must: follow the rules described in <> to transfer ownership between the Vulkan instance and these native APIs. Android hardware buffers can: be shared with external APIs and Vulkan -instances on the same device and also with foreign devices. +instances on the same device, and also with foreign devices. When transferring ownership of the Android hardware buffer, the external and foreign special queue families described in <> are not identical. @@ -2742,37 +2746,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 -allocator must: allocate the memory in such a way that it can support Vulkan +code:AHARDWAREBUFFER_USAGE_GPU_* usage bits are included, by default the +allocator must: allocate the memory in such a way that it supports 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 @@ -2781,11 +2784,11 @@ representation, images with external formats must: only be used as sampled images, must: only be sampled with a sampler that has Y'C~B~C~R~ conversion enabled, and must: have optimal tiling. -Images that will be backed by a Android hardware buffer can use an external -format by setting sname:VkImageCreateInfo::pname:format to +Images that will be backed by a Android hardware buffer can: use an external +format by setting slink: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 @@ -2818,16 +2821,16 @@ properties derived from the image: * The code:width and code:height members of code:AHardwareBuffer_desc must: be the same as the pname:width and pname:height members of - pname:VkImageCreateInfo::pname:extent, respectively; + slink:VkImageCreateInfo::pname:extent, respectively. * The code:layers member of code:AHardwareBuffer_desc must: be the same as - the pname:arrayLayers member of sname:VkImageCreateInfo; + the pname:arrayLayers member of slink:VkImageCreateInfo. * The code:format member of code:AHardwareBuffer_desc must: be equivalent - to pname:VkImageCreateInfo::pname:format as defined by + to slink:VkImageCreateInfo::pname:format as defined by <>; + Equivalence>>. * The code:usage member of code:AHardwareBuffer_desc must: include bits - corresponding to bits included in pname:VkImageCreateInfo::pname:usage - and pname:VkImageCreateInfo::pname:flags where such a correspondence + corresponding to bits included in slink:VkImageCreateInfo::pname:usage + and slink:VkImageCreateInfo::pname:flags where such a correspondence exists according to <>. @@ -2839,15 +2842,15 @@ 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 +Support for a given set of parameters can: be determined by passing 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 @@ -2894,11 +2897,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[] @@ -2917,10 +2920,10 @@ 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 -used as the backing store for sname:VkBuffer objects. +and usage that includes code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER can: be +used as the backing store for slink:VkBuffer objects. Such Android hardware buffers have a size in bytes specified by their -code:width; code:height and code:layers are 1. +code:width; code:height and code:layers are both `1`. Unlike images, buffer resources backed by Android hardware buffers do not require dedicated allocations. @@ -2928,10 +2931,7 @@ require dedicated allocations. Exported code:AHardwareBuffer objects that do not have dedicated images must: have a format of code:AHARDWAREBUFFER_FORMAT_BLOB, usage must: include code:AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER, code:width must: equal the -device memory allocation size, and code:height and code:layers must: be -code:1. - -endif::VK_ANDROID_external_memory_android_hardware_buffer[] +device memory allocation size, and code:height and code:layers must: be `1`. endif::VK_KHR_external_memory_capabilities+VK_ANDROID_external_memory_android_hardware_buffer[] diff --git a/chapters/resources.txt b/chapters/resources.txt index bc167010..38040944 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[] @@ -1005,9 +1005,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 @@ -1118,7 +1118,7 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] To create an image with an <>, include an instance of sname:VkExternalFormatANDROID in the -pname:pNext chain of sname:VkImageCreateInfo. +pname:pNext chain of slink:VkImageCreateInfo. sname:VkExternalFormatANDROID is defined as: include::../api/structs/VkExternalFormatANDROID.txt[] @@ -1136,7 +1136,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 @@ -1440,11 +1440,11 @@ If the elink:VkFormat of pname:image is a fname:vkGetImageSubresourceLayout describes one plane of the image. endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] -flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single +fname: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[] @@ -1482,7 +1482,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[] **** @@ -2496,12 +2496,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[] **** @@ -2922,11 +2922,11 @@ calling flink:vkGetImageMemoryRequirements with such an image before it has been bound to memory will result in undefined behavior. When importing Android hardware buffer memory, the pname:allocationSize can: be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID. -When allocating new memory for an image that can: be exported to a Android +When allocating new memory for an image that can: be exported to an 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[] @@ -3161,7 +3161,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[] ****