registry/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt

// Copyright 2014-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[platformCreateSurface_xlib,platformCreateSurface_xlib]]
=== Xlib Platform

[open,refpage='vkCreateXlibSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for an X11 window, using the Xlib client-side library',type='protos']
--
To create a sname:VkSurfaceKHR object for an X11 window, using the Xlib
client-side library, call:

include::{generated}/api/protos/vkCreateXlibSurfaceKHR.txt[]

  * pname:instance is the instance to associate the surface with.
  * pname:pCreateInfo is a pointer to a sname:VkXlibSurfaceCreateInfoKHR
    structure containing the 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 is a pointer to a slink:VkSurfaceKHR handle in which the
    created surface object is returned.

include::{generated}/validity/protos/vkCreateXlibSurfaceKHR.txt[]
--

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

The sname:VkXlibSurfaceCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkXlibSurfaceCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:dpy is a pointer to an Xlib code:Display connection to the X
    server.
  * pname:window is an Xlib code:Window to associate the surface with.

.Valid Usage
****
  * [[VUID-VkXlibSurfaceCreateInfoKHR-dpy-01313]]
    pname:dpy must: point to a valid Xlib code:Display
  * [[VUID-VkXlibSurfaceCreateInfoKHR-window-01314]]
    pname:window must: be a valid Xlib code:Window
****

include::{generated}/validity/structs/VkXlibSurfaceCreateInfoKHR.txt[]
--

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

The pname:currentExtent of an Xlib 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 Xlib
code:Display connection when using a swapchain or presentable images created
from a slink:VkSurfaceKHR referring to an Xlib window.
Applications must: therefore ensure the display 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 Xlib-based swapchains must:

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

Some implementations may require threads to implement some presentation
modes so applications must: call code:XInitThreads() before calling any
other Xlib functions.

[open,refpage='VkXlibSurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkXlibSurfaceCreateFlagsKHR.txt[]

tname:VkXlibSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but
is currently reserved for future use.
--