Add spec for VK_QNX_external_memory_screen_buffer

appendices/VK_QNX_external_memory_screen_buffer.adoc

@@ -0,0 +1,40 @@
+// Copyright (c) 2023 Blackberry Limited
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_QNX_external_memory_screen_buffer.adoc[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2023-05-17
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Mike Gorchak, QNX / Blackberry Limited
+  - Aaron Ruby, QNX / Blackberry Limited
+
+=== Description
+
+This extension enables an application to import QNX Screen
+code:_screen_buffer objects created outside of the Vulkan device into
+Vulkan memory objects, where they can be bound to images and buffers.
+
+Some code:_screen_buffer images have implementation-defined _external
+formats_ that may: not correspond to Vulkan formats. Sampler {YCbCr}
+conversion can: be used to sample from these images and convert them to a
+known color space.
+
+code:_screen_buffer is strongly typed, so naming the handle type is
+redundant. The internal layout and therefore size of a code:_screen_buffer
+image may depend on native usage flags that do not have corresponding Vulkan
+counterparts.
+
+include::{generated}/interfaces/VK_QNX_external_memory_screen_buffer.adoc[]
+
+=== Issues
+
+=== Version History
+
+  * Revision 1, 2023-05-17 (Mike Gorchak)
+  ** Initial version

appendices/glossary.adoc

@@ -1356,10 +1356,15 @@ Potential Format Features::
     supports for a specified elink:VkFormat, over all supported image
     tilings.
 ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
-    For <<memory-external-android-hardware-buffer-external-formats,external
+    For <<memory-external-android-hardware-buffer-external-formats,Android external
     formats>> the elink:VkFormatFeatureFlagBits is provided by the
     implementation.
 endif::VK_ANDROID_external_memory_android_hardware_buffer[]
+ifdef::VK_QNX_external_memory_screen_buffer[]
+    For <<memory-external-screen-buffer-external-formats,QNX Screen external
+    formats>> the elink:VkFormatFeatureFlagBits is provided by the
+    implementation.
+endif::VK_QNX_external_memory_screen_buffer[]
 
 Pre-rasterization::
     Operations that execute before <<primsrast,rasterization>>, and any

chapters/VK_QNX_external_memory_screen_buffer/device_memory.adoc

@@ -0,0 +1,123 @@
+// Copyright 2023 QNX Software Systems
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+[[qnx-screen-buffer-external-memory]]
+=== QNX Screen Buffer External Memory
+
+[open,refpage='VkImportScreenBufferInfoQNX',desc='Import memory from a QNX Screen buffer',type='structs']
+--
+To import memory created outside of the current Vulkan instance from a QNX
+Screen buffer, add a sname:VkImportScreenBufferInfoQNX structure to the
+pname:pNext chain of the slink:VkMemoryAllocateInfo structure.
+The sname:VkImportScreenBufferInfoQNX structure is defined as:
+
+include::{generated}/api/structs/VkImportScreenBufferInfoQNX.adoc[]
+
+  * pname:sType is the type of this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * pname:buffer is a pointer to a code:struct code:_screen_buffer, the QNX Screen buffer to import
+
+The implementation may: not acquire a reference to the imported Screen
+buffer.
+Therefore, the application must: ensure that the object referred to by
+pname:buffer stays valid as long as the device memory to which it is
+imported is being used.
+
+.Valid Usage
+****
+  * If pname:buffer is not `NULL`, QNX Screen Buffers must: be supported for
+    import, as reported by slink:VkExternalImageFormatProperties or
+    slink:VkExternalBufferProperties
+  * pname:buffer is not `NULL`, it must: be a pointer to
+    <<memory-external-screen-buffer-validity,valid QNX Screen buffer>>
+
+****
+
+include::{generated}/validity/structs/VkImportScreenBufferInfoQNX.adoc[]
+--
+
+[open,refpage='vkGetScreenBufferPropertiesQNX',desc='Get Properties of External Memory QNX Screen Buffers',type='protos']
+--
+To determine the memory parameters to use when importing a QNX Screen
+buffer, call:
+
+include::{generated}/api/protos/vkGetScreenBufferPropertiesQNX.adoc[]
+
+  * pname:device is the logical device that will be importing pname:buffer.
+  * pname:buffer is the QNX Screen buffer which will be imported.
+  * pname:pProperties is a pointer to a slink:VkScreenBufferPropertiesQNX
+    structure in which the properties of pname:buffer are returned.
+
+.Valid Usage
+****
+  * pname:buffer must: be a <<memory-external-screen-buffer-validity,valid QNX Screen buffer>>
+****
+
+include::{generated}/validity/protos/vkGetScreenBufferPropertiesQNX.adoc[]
+--
+
+[open,refpage='VkScreenBufferPropertiesQNX',desc='Properties of External Memory QNX Screen Buffers',type='structs']
+--
+The sname:VkScreenBufferPropertiesQNX structure returned is defined as:
+
+include::{generated}/api/structs/VkScreenBufferPropertiesQNX.adoc[]
+
+  * pname:sType is the type of this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * pname:allocationSize is the size of the external memory.
+  * pname:memoryTypeBits is a bitmask containing one bit set for every
+    memory type which the specified Screen buffer can: be imported as.
+
+include::{generated}/validity/structs/VkScreenBufferPropertiesQNX.adoc[]
+--
+
+[open,refpage='VkScreenBufferFormatPropertiesQNX',desc='Structure describing the image format properties of a QNX Screen buffer',type='structs']
+--
+To obtain format properties of a QNX Screen buffer, include a
+sname:VkScreenBufferFormatPropertiesQNX structure in the pname:pNext chain
+of the slink:VkScreenBufferPropertiesQNX structure passed to
+flink:vkGetScreenBufferPropertiesQNX.
+This structure is defined as:
+
+include::{generated}/api/structs/VkScreenBufferFormatPropertiesQNX.adoc[]
+
+  * pname:sType is the type of this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * pname:format is the Vulkan format corresponding to the Screen 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:VkExternalFormatQNX.
+    It must: not be zero.
+  * pname:screenUsage is an implementation-defined external usage identifier for
+    the QNX Screen buffer.
+  * pname:formatFeatures describes the capabilities of this external format
+    when used with an image bound to memory imported from pname:buffer.
+  * pname:samplerYcbcrConversionComponents is the component swizzle that
+    should: be used in slink:VkSamplerYcbcrConversionCreateInfo.
+  * pname:suggestedYcbcrModel is a suggested color model to use in the
+    slink:VkSamplerYcbcrConversionCreateInfo.
+  * pname:suggestedYcbcrRange is a suggested numerical value range to use in
+    slink:VkSamplerYcbcrConversionCreateInfo.
+  * pname:suggestedXChromaOffset is a suggested X chroma offset to use in
+    slink:VkSamplerYcbcrConversionCreateInfo.
+  * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in
+    slink:VkSamplerYcbcrConversionCreateInfo.
+
+If the QNX Screen buffer has one of the formats listed in the
+<<memory-external-qnx-screen-buffer-formats,QNX Screen Format Equivalence
+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
+QNX Screen buffer can: only be used with an external format.
+The pname:formatFeatures member must: include
+ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and should: include
+ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and
+ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.
+
+include::{generated}/validity/structs/VkScreenBufferFormatPropertiesQNX.adoc[]
+--

chapters/VK_QNX_external_memory_screen_buffer/qnx_screen_buffer.adoc

@@ -0,0 +1,121 @@
+// Copyright 2023 QNX Software Systems
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+[[memory-external-qnx-screen-buffer]]
+==== QNX Screen Buffer
+
+The QNX SDP defines code:_screen_buffer objects, which represent
+a buffer that the QNX Screen graphics subsystem can use directly
+in its windowing system APIs. More specifically, a Screen buffer is an area of memory that
+stores pixel data. It can be attached to Screen windows, streams, or pixmaps.
+These QNX Screen buffer objects may: be imported into
+slink:VkDeviceMemory objects for access via Vulkan.
+An slink:VkImage or slink:VkBuffer can: be bound to the imported
+slink:VkDeviceMemory object if it is created with
+ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
+
+--
+code:struct code:_screen_buffer is strongly typed, so naming the handle type is
+redundant. The internal layout and therefore size of a code:struct code:_screen_buffer
+image may depend on native usage flags that do not have corresponding Vulkan
+counterparts.
+--
+
+[[memory-external-screen-buffer-validity]]
+===== QNX Screen Buffer Validity
+The design of Screen in the QNX SDP makes it difficult to determine the validity of objects from outside of Screen. Therefore, applications must: ensure that QNX Screen buffer objects provided used in various Vulkan
+interfaces are ones created explicitly with QNX Screen APIs. See QNX SDP documentation for more information.
+
+A slink:VkDeviceMemory imported from a QNX Screen buffer has no way to acquire
+a reference to its code:_screen_buffer object. Therefore, during the host
+execution of a Vulkan command that has a QNX Screen buffer as a parameter
+(including indirect parameters via pname:pNext chains), the application must:
+ensure that the QNX Screen buffer resource remains valid.
+
+Generally, for a code:_screen_buffer object to be valid for use within a Vulkan implementation, the buffer object
+should: have a code:_screen_buffer::code:SCREEN_PROPERTY_USAGE that includes at least one of:
+code:SCREEN_USAGE_VULKAN, code:SCREEN_USAGE_OPENGL_ES2, code:SCREEN_USAGE_OPENGL_ES3, or code:SCREEN_USAGE_NATIVE.
+The exact Screen-native usage flags required depends on the Vulkan implementation, and QNX Screen itself will not necessarily enforce these requirements. Note that Screen-native usage flags are in no way related to usage flags in the Vulkan specification.
+
+[[memory-external-screen-buffer-external-formats]]
+===== QNX Screen Buffer External Formats
+
+QNX Screen 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 QNX Screen buffers that have external formats, but
+since the image contents are in an undiscoverable and possibly proprietary
+representation, images with external formats must: only be used as sampled
+images, must: only be sampled with a sampler that has {YCbCr} conversion
+enabled, and must: have optimal tiling.
+
+Images that will be backed by a QNX Screen buffer can: use an
+external format by setting slink:VkImageCreateInfo::pname:format to
+ename:VK_FORMAT_UNDEFINED and including a slink:VkExternalFormatQNX
+structure in the pname:pNext chain.
+Images can: be created with an external format even if the QNX Screen
+buffer has a format which has an
+<<memory-external-qnx-screen-buffer-formats,equivalent Vulkan format>>
+to enable consistent handling of images from sources that might use either
+category of format.
+The external format of a QNX Screen buffer can: be obtained by
+passing a slink:VkScreenBufferFormatPropertiesQNX structure to
+flink:vkGetScreenBufferPropertiesQNX.
+
+
+[[memory-external-qnx-screen-buffer-image-resources]]
+===== QNX Screen Buffer Image Resources
+
+QNX Screen buffers have intrinsic width, height, format, and usage
+properties, so Vulkan images bound to memory imported from a QNX Screen
+buffer must: use dedicated allocations:
+sname:VkMemoryDedicatedRequirements::pname:requiresDedicatedAllocation must:
+be ename:VK_TRUE for images created with
+slink:VkExternalMemoryImageCreateInfo::pname:handleTypes that includes
+ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
+When creating an image that will be bound to an imported QNX Screen buffer,
+the image creation parameters must: be equivalent to the
+code:_screen_buffer properties as described by the valid usage of
+slink:VkMemoryAllocateInfo.
+
+[[memory-external-qnx-screen-buffer-formats]]
+.QNX Screen Buffer Format Equivalence
+[width="100%",options="header"]
+|====
+| QNX Screen Format                              | Vulkan Format
+| code:SCREEN_FORMAT_RGBA8888                    | ename:VK_FORMAT_B8G8R8A8_UNORM
+| code:SCREEN_FORMAT_RGBX8888 ^1^                | ename:VK_FORMAT_B8G8R8A8_UNORM
+| code:SCREEN_FORMAT_BGRA8888                    | ename:VK_FORMAT_R8G8B8A8_UNORM
+| code:SCREEN_FORMAT_BGRX8888 ^1^                | ename:VK_FORMAT_R8G8B8A8_UNORM
+| code:SCREEN_FORMAT_RGBA1010102                 | ename:VK_FORMAT_A2R10G10B10_UNORM_PACK32
+| code:SCREEN_FORMAT_RGBX1010102 ^1^             | ename:VK_FORMAT_A2R10G10B10_UNORM_PACK32
+| code:SCREEN_FORMAT_BGRA1010102                 | ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32
+| code:SCREEN_FORMAT_BGRX1010102 ^1^             | ename:VK_FORMAT_A2B10G10R10_UNORM_PACK32
+| code:SCREEN_FORMAT_RGBA5551                    | ename:VK_FORMAT_A1R5G5B5_UNORM_PACK16
+| code:SCREEN_FORMAT_RGBX5551 ^1^                | ename:VK_FORMAT_A1R5G5B5_UNORM_PACK16
+| code:SCREEN_FORMAT_RGB565                      | ename:VK_FORMAT_R5G6B5_UNORM_PACK16
+| code:SCREEN_FORMAT_RGB888                      | ename:VK_FORMAT_R8G8B8_UNORM
+|====
+
+
+1::
+    Vulkan does not differentiate between
+    code:SCREEN_FORMAT_RGBA8888 and
+    code:SCREEN_FORMAT_RGBX8888: they both behave as
+    ename:VK_FORMAT_R8G8B8A8_UNORM.
+    After an external entity writes to a
+    code:SCREEN_FORMAT_RGBX8888 QNX Screen buffer, the
+    values read by Vulkan from the X/A component are undefined:.
+    To emulate the traditional behavior of the X component during sampling
+    or blending, applications should: use ename:VK_COMPONENT_SWIZZLE_ONE in
+    image view component mappings and ename:VK_BLEND_FACTOR_ONE in color
+    blend factors.
+    There is no way to avoid copying these undefined: values when copying
+    from such an image to another image or buffer.
+    The same behavior applies to the following pairs: code:SCREEN_FORMAT_BGRA8888 and
+    code:SCREEN_FORMAT_BGRX8888, code:SCREEN_FORMAT_RGBA1010102 and
+    code:SCREEN_FORMAT_RGBX1010102, code:SCREEN_FORMAT_BGRA1010102 and
+    code:SCREEN_FORMAT_BGRX1010102, code:SCREEN_FORMAT_RGBA5551 and
+    code:SCREEN_FORMAT_RGBX5551

chapters/capabilities.adoc

@@ -505,6 +505,12 @@ ifdef::VK_NV_external_memory_sci_buf[]
     software (intra-process and inter-process) and hardware (system memory)
     operating domains.
 endif::VK_NV_external_memory_sci_buf[]
+ifdef::VK_QNX_external_memory_screen_buffer[]
+  * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX
+    specifies a code:_screen_buffer object defined by the QNX SDP.
+    See <<memory-external-qnx-screen-buffer,QNX Screen Buffer>>
+    for more details of this handle type.
+endif::VK_QNX_external_memory_screen_buffer[]
 
 <<<
 
@@ -542,6 +548,9 @@ endif::VK_NV_external_memory_rdma[]
 ifdef::VK_NV_external_memory_sci_buf[]
 | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCI_BUF_BIT_NV | No restriction | No restriction
 endif::VK_NV_external_memory_sci_buf[]
+ifdef::VK_QNX_external_memory_screen_buffer[]
+| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX | No restriction | No restriction
+endif::VK_QNX_external_memory_screen_buffer[]
 |====
 
 ifdef::VK_EXT_external_memory_host[]
@@ -679,13 +688,23 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
   * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
     for images only
 endif::VK_ANDROID_external_memory_android_hardware_buffer[]
+ifdef::VK_QNX_external_memory_screen_buffer[]
+  * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX
+    for images only
+endif::VK_QNX_external_memory_screen_buffer[]
 
 ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
 Implementations must: not report
 ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with
 external handle type
 ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID.
 endif::VK_ANDROID_external_memory_android_hardware_buffer[]
+ifdef::VK_QNX_external_memory_screen_buffer[]
+Implementations must: not report
+ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for buffers with
+external handle type
+ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_SCREEN_BUFFER_BIT_QNX.
+endif::VK_QNX_external_memory_screen_buffer[]
 ifdef::VK_EXT_external_memory_host[]
 Implementations must: not report
 ename:VK_EXTERNAL_MEMORY_FEATURE_DEDICATED_ONLY_BIT for images or buffers