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