// Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[platformCreateSurface_xcb,platformCreateSurface_xcb]]

=== XCB Platform

[open,refpage='vkCreateXcbSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a X11 window, using the XCB client-side library',type='protos']
--

To create a sname:VkSurfaceKHR object for an X11 window, using the XCB
client-side library, call:

include::../../api/protos/vkCreateXcbSurfaceKHR.txt[]

  * pname:instance is the instance to associate the surface with.
  * pname:pCreateInfo is a pointer to an instance of the
    sname:VkXcbSurfaceCreateInfoKHR structure containing parameters
    affecting the creation of the surface object.
  * pname:pAllocator is the allocator used for host memory allocated for the
    surface object when there is no more specific allocator available (see
    <<memory-allocation,Memory Allocation>>).
  * pname:pSurface points to a slink:VkSurfaceKHR handle in which the
    created surface object is returned.

include::../../validity/protos/vkCreateXcbSurfaceKHR.txt[]
--

[open,refpage='VkXcbSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Xcb surface object',type='structs']
--

The sname:VkXcbSurfaceCreateInfoKHR structure is defined as:

include::../../api/structs/VkXcbSurfaceCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is reserved for future use.
  * pname:connection is a pointer to an code:xcb_connection_t to the X
    server.
  * pname:window is the code:xcb_window_t for the X11 window to associate
    the surface with.

.Valid Usage
****
  * [[VUID-VkXcbSurfaceCreateInfoKHR-connection-01310]]
    pname:connection must: point to a valid X11 code:xcb_connection_t.
  * [[VUID-VkXcbSurfaceCreateInfoKHR-window-01311]]
    pname:window must: be a valid X11 code:xcb_window_t.
****

include::../../validity/structs/VkXcbSurfaceCreateInfoKHR.txt[]
--

With Xcb, pname:minImageExtent, pname:maxImageExtent, and
pname:currentExtent must: always equal the window size.

The pname:currentExtent of an Xcb surface must: have both pname:width and
pname:height greater than 0, or both of them 0.

[NOTE]
.Note
====
Due to above restrictions, it is only possible to create a new swapchain on
this platform with pname:imageExtent being equal to the current size of the
window.

The window size may: become [eq]#(0, 0)# on this platform (e.g. when the
window is minimized), and so a swapchain cannot: be created until the size
changes.
====

Some Vulkan functions may: send protocol over the specified xcb connection
when using a swapchain or presentable images created from a
slink:VkSurfaceKHR referring to an xcb window.
Applications must: therefore ensure the xcb connection is available to
Vulkan for the duration of any functions that manipulate such swapchains or
their presentable images, and any functions that build or queue command
buffers that operate on such presentable images.
Specifically, applications using Vulkan with xcb-based swapchains must:

  * Avoid holding a server grab on an xcb connection while waiting for
    Vulkan operations to complete using a swapchain derived from a different
    xcb connection referring to the same X server instance.
    Failing to do so may: result in deadlock.