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