1// Copyright 2023 QNX Software Systems
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[qnx-screen-buffer-external-memory]]
6=== QNX Screen Buffer External Memory
7
8[open,refpage='VkImportScreenBufferInfoQNX',desc='Import memory from a QNX Screen buffer',type='structs']
9--
10To import memory created outside of the current Vulkan instance from a QNX
11Screen buffer, add a sname:VkImportScreenBufferInfoQNX structure to the
12pname:pNext chain of the slink:VkMemoryAllocateInfo structure.
13The sname:VkImportScreenBufferInfoQNX structure is defined as:
14
15include::{generated}/api/structs/VkImportScreenBufferInfoQNX.adoc[]
16
17  * pname:sType is a elink:VkStructureType value identifying this structure.
18  * pname:pNext is `NULL` or a pointer to a structure extending this
19    structure.
20  * pname:buffer is a pointer to a code:struct code:_screen_buffer, the QNX
21    Screen buffer to import
22
23The implementation may: not acquire a reference to the imported Screen
24buffer.
25Therefore, the application must: ensure that the object referred to by
26pname:buffer stays valid as long as the device memory to which it is
27imported is being used.
28
29.Valid Usage
30****
31  * [[VUID-VkImportScreenBufferInfoQNX-buffer-08966]]
32    If pname:buffer is not `NULL`, QNX Screen Buffers must: be supported for
33    import, as reported by slink:VkExternalImageFormatProperties or
34    slink:VkExternalBufferProperties
35  * [[VUID-VkImportScreenBufferInfoQNX-buffer-08967]]
36    pname:buffer is not `NULL`, it must: be a pointer to
37    <<memory-external-screen-buffer-validity,valid QNX Screen buffer>>
38
39****
40
41include::{generated}/validity/structs/VkImportScreenBufferInfoQNX.adoc[]
42--
43
44[open,refpage='vkGetScreenBufferPropertiesQNX',desc='Get Properties of External Memory QNX Screen Buffers',type='protos']
45--
46To determine the memory parameters to use when importing a QNX Screen
47buffer, call:
48
49include::{generated}/api/protos/vkGetScreenBufferPropertiesQNX.adoc[]
50
51  * pname:device is the logical device that will be importing pname:buffer.
52  * pname:buffer is the QNX Screen buffer which will be imported.
53  * pname:pProperties is a pointer to a slink:VkScreenBufferPropertiesQNX
54    structure in which the properties of pname:buffer are returned.
55
56.Valid Usage
57****
58  * [[VUID-vkGetScreenBufferPropertiesQNX-buffer-08968]]
59    pname:buffer must: be a <<memory-external-screen-buffer-validity,valid
60    QNX Screen buffer>>
61****
62
63include::{generated}/validity/protos/vkGetScreenBufferPropertiesQNX.adoc[]
64--
65
66[open,refpage='VkScreenBufferPropertiesQNX',desc='Properties of External Memory QNX Screen Buffers',type='structs']
67--
68The sname:VkScreenBufferPropertiesQNX structure returned is defined as:
69
70include::{generated}/api/structs/VkScreenBufferPropertiesQNX.adoc[]
71
72  * pname:sType is a elink:VkStructureType value identifying this structure.
73  * pname:pNext is `NULL` or a pointer to a structure extending this
74    structure.
75  * pname:allocationSize is the size of the external memory.
76  * pname:memoryTypeBits is a bitmask containing one bit set for every
77    memory type which the specified Screen buffer can: be imported as.
78
79include::{generated}/validity/structs/VkScreenBufferPropertiesQNX.adoc[]
80--
81
82[open,refpage='VkScreenBufferFormatPropertiesQNX',desc='Structure describing the image format properties of a QNX Screen buffer',type='structs']
83--
84To obtain format properties of a QNX Screen buffer, include a
85sname:VkScreenBufferFormatPropertiesQNX structure in the pname:pNext chain
86of the slink:VkScreenBufferPropertiesQNX structure passed to
87flink:vkGetScreenBufferPropertiesQNX.
88This structure is defined as:
89
90include::{generated}/api/structs/VkScreenBufferFormatPropertiesQNX.adoc[]
91
92  * pname:sType is a elink:VkStructureType value identifying this structure.
93  * pname:pNext is `NULL` or a pointer to a structure extending this
94    structure.
95  * pname:format is the Vulkan format corresponding to the Screen buffer's
96    format or ename:VK_FORMAT_UNDEFINED if there is not an equivalent Vulkan
97    format.
98  * pname:externalFormat is an implementation-defined external format
99    identifier for use with slink:VkExternalFormatQNX.
100    It must: not be zero.
101  * pname:screenUsage is an implementation-defined external usage identifier
102    for the QNX Screen buffer.
103  * pname:formatFeatures describes the capabilities of this external format
104    when used with an image bound to memory imported from pname:buffer.
105  * pname:samplerYcbcrConversionComponents is the component swizzle that
106    should: be used in slink:VkSamplerYcbcrConversionCreateInfo.
107  * pname:suggestedYcbcrModel is a suggested color model to use in the
108    slink:VkSamplerYcbcrConversionCreateInfo.
109  * pname:suggestedYcbcrRange is a suggested numerical value range to use in
110    slink:VkSamplerYcbcrConversionCreateInfo.
111  * pname:suggestedXChromaOffset is a suggested X chroma offset to use in
112    slink:VkSamplerYcbcrConversionCreateInfo.
113  * pname:suggestedYChromaOffset is a suggested Y chroma offset to use in
114    slink:VkSamplerYcbcrConversionCreateInfo.
115
116If the QNX Screen buffer has one of the formats listed in the
117<<memory-external-qnx-screen-buffer-formats,QNX Screen Format Equivalence
118table>>, then pname:format must: have the equivalent Vulkan format listed in
119the table.
120Otherwise, pname:format may: be ename:VK_FORMAT_UNDEFINED, indicating the
121QNX Screen buffer can: only be used with an external format.
122The pname:formatFeatures member must: include
123ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT and should: include
124ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT and
125ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT.
126
127include::{generated}/validity/structs/VkScreenBufferFormatPropertiesQNX.adoc[]
128--
129