1// Copyright 2014-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[platformCreateSurface_xlib]]
6=== Xlib Platform
7
8[open,refpage='vkCreateXlibSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an X11 window, using the Xlib client-side library',type='protos']
9--
10:refpage: vkCreateXlibSurfaceKHR
11
12To create a sname:VkSurfaceKHR object for an X11 window, using the Xlib
13client-side library, call:
14
15include::{generated}/api/protos/vkCreateXlibSurfaceKHR.adoc[]
16
17  * pname:instance is the instance to associate the surface with.
18  * pname:pCreateInfo is a pointer to a sname:VkXlibSurfaceCreateInfoKHR
19    structure containing the parameters affecting the creation of the
20    surface object.
21  * pname:pAllocator is the allocator used for host memory allocated for the
22    surface object when there is no more specific allocator available (see
23    <<memory-allocation,Memory Allocation>>).
24  * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the
25    created surface object is returned.
26
27include::{generated}/validity/protos/vkCreateXlibSurfaceKHR.adoc[]
28--
29
30[open,refpage='VkXlibSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Xlib surface object',type='structs']
31--
32The sname:VkXlibSurfaceCreateInfoKHR structure is defined as:
33
34include::{generated}/api/structs/VkXlibSurfaceCreateInfoKHR.adoc[]
35
36  * pname:sType is a elink:VkStructureType value identifying this structure.
37  * pname:pNext is `NULL` or a pointer to a structure extending this
38    structure.
39  * pname:flags is reserved for future use.
40  * pname:dpy is a pointer to an Xlib code:Display connection to the X
41    server.
42  * pname:window is an Xlib code:Window to associate the surface with.
43
44.Valid Usage
45****
46  * [[VUID-VkXlibSurfaceCreateInfoKHR-dpy-01313]]
47    pname:dpy must: point to a valid Xlib code:Display
48  * [[VUID-VkXlibSurfaceCreateInfoKHR-window-01314]]
49    pname:window must: be a valid Xlib code:Window
50****
51
52include::{generated}/validity/structs/VkXlibSurfaceCreateInfoKHR.adoc[]
53--
54
55With Xlib, pname:minImageExtent, pname:maxImageExtent, and
56pname:currentExtent must: always equal the window size.
57
58The pname:currentExtent of an Xlib surface must: have both pname:width and
59pname:height greater than 0, or both of them 0.
60
61[NOTE]
62.Note
63====
64Due to above restrictions,
65ifdef::VK_EXT_swapchain_maintenance1[]
66unless slink:VkSwapchainPresentScalingCreateInfoEXT is used to specify
67handling of disparities between surface and swapchain dimensions,
68endif::VK_EXT_swapchain_maintenance1[]
69it is only possible to create a new swapchain on this platform with
70pname:imageExtent being equal to the current size of the window, as reported
71in slink:VkSurfaceCapabilitiesKHR::pname:currentExtent.
72
73The window size may: become [eq]#(0, 0)# on this platform (e.g. when the
74window is minimized), and so a swapchain cannot: be created until the size
75changes.
76====
77
78Some Vulkan functions may: send protocol over the specified Xlib
79code:Display connection when using a swapchain or presentable images created
80from a slink:VkSurfaceKHR referring to an Xlib window.
81Applications must: therefore ensure the display connection is available to
82Vulkan for the duration of any functions that manipulate such swapchains or
83their presentable images, and any functions that build or queue command
84buffers that operate on such presentable images.
85Specifically, applications using Vulkan with Xlib-based swapchains must:
86
87  * Avoid holding a server grab on a display connection while waiting for
88    Vulkan operations to complete using a swapchain derived from a different
89    display connection referring to the same X server instance.
90    Failing to do so may: result in deadlock.
91
92Some implementations may require threads to implement some presentation
93modes so applications must: call code:XInitThreads() before calling any
94other Xlib functions.
95
96[open,refpage='VkXlibSurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
97--
98include::{generated}/api/flags/VkXlibSurfaceCreateFlagsKHR.adoc[]
99
100tname:VkXlibSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
101is currently reserved for future use.
102--
103