-
Notifications
You must be signed in to change notification settings - Fork 477
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add spec for VK_QNX_external_memory_screen_buffer (#2138)
* Spec and documentation additions for VK_QNX_external_memory_screen_buffer. * Updates for VK_QNX_external_memory_screen_buffer pull request. Testing: VULKAN_API="vulkan" ./makeAllExts -v html VULKAN_API="vulkansc" ./makeAllExts -version sc1.0 html * Update VK_QNX_external_memory_screen_buffer documentation based on PR reviews. * More updates to VK_QNX_external_memory_screen_buffer from reviews. * Add VkPhysicalDeviceExternalMemoryScreenBufferFeaturesQNX to the VK_QNX_external_memory_screen_buffer extension spec additions
- Loading branch information
1 parent
2f4ef83
commit b5543e9
Showing
12 changed files
with
659 additions
and
37 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
123 changes: 123 additions & 0 deletions
123
chapters/VK_QNX_external_memory_screen_buffer/device_memory.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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[] | ||
| -- |
121 changes: 121 additions & 0 deletions
121
chapters/VK_QNX_external_memory_screen_buffer/qnx_screen_buffer.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.