1// Copyright 2014-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[platformCreateSurface_xcb]]
6=== XCB Platform
7
8[open,refpage='vkCreateXcbSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a X11 window, using the XCB client-side library',type='protos']
9--
10:refpage: vkCreateXcbSurfaceKHR
11
12To create a sname:VkSurfaceKHR object for an X11 window, using the XCB
13client-side library, call:
14
15include::{generated}/api/protos/vkCreateXcbSurfaceKHR.adoc[]
16
17  * pname:instance is the instance to associate the surface with.
18  * pname:pCreateInfo is a pointer to a sname:VkXcbSurfaceCreateInfoKHR
19    structure containing parameters affecting the creation of the surface
20    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/vkCreateXcbSurfaceKHR.adoc[]
28--
29
30[open,refpage='VkXcbSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Xcb surface object',type='structs']
31--
32The sname:VkXcbSurfaceCreateInfoKHR structure is defined as:
33
34include::{generated}/api/structs/VkXcbSurfaceCreateInfoKHR.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:connection is a pointer to an code:xcb_connection_t to the X
41    server.
42  * pname:window is the code:xcb_window_t for the X11 window to associate
43    the surface with.
44
45.Valid Usage
46****
47  * [[VUID-VkXcbSurfaceCreateInfoKHR-connection-01310]]
48    pname:connection must: point to a valid X11 code:xcb_connection_t
49  * [[VUID-VkXcbSurfaceCreateInfoKHR-window-01311]]
50    pname:window must: be a valid X11 code:xcb_window_t
51****
52
53include::{generated}/validity/structs/VkXcbSurfaceCreateInfoKHR.adoc[]
54--
55
56With Xcb, pname:minImageExtent, pname:maxImageExtent, and
57pname:currentExtent must: always equal the window size.
58
59The pname:currentExtent of an Xcb surface must: have both pname:width and
60pname:height greater than 0, or both of them 0.
61
62[NOTE]
63.Note
64====
65Due to above restrictions,
66ifdef::VK_EXT_swapchain_maintenance1[]
67unless slink:VkSwapchainPresentScalingCreateInfoEXT is used to specify
68handling of disparities between surface and swapchain dimensions,
69endif::VK_EXT_swapchain_maintenance1[]
70it is only possible to create a new swapchain on this platform with
71pname:imageExtent being equal to the current size of the window, as reported
72in slink:VkSurfaceCapabilitiesKHR::pname:currentExtent.
73
74The window size may: become [eq]#(0, 0)# on this platform (e.g. when the
75window is minimized), and so a swapchain cannot: be created until the size
76changes.
77====
78
79Some Vulkan functions may: send protocol over the specified xcb connection
80when using a swapchain or presentable images created from a
81slink:VkSurfaceKHR referring to an xcb window.
82Applications must: therefore ensure the xcb connection is available to
83Vulkan for the duration of any functions that manipulate such swapchains or
84their presentable images, and any functions that build or queue command
85buffers that operate on such presentable images.
86Specifically, applications using Vulkan with xcb-based swapchains must:
87
88  * Avoid holding a server grab on an xcb connection while waiting for
89    Vulkan operations to complete using a swapchain derived from a different
90    xcb connection referring to the same X server instance.
91    Failing to do so may: result in deadlock.
92
93[open,refpage='VkXcbSurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
94--
95include::{generated}/api/flags/VkXcbSurfaceCreateFlagsKHR.adoc[]
96
97tname:VkXcbSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
98is currently reserved for future use.
99--
100