1// Copyright 2014-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[platformCreateSurface_wayland]]
6=== Wayland Platform
7
8[open,refpage='vkCreateWaylandSurfaceKHR',desc='Create a slink:VkSurfaceKHR object for a Wayland window',type='protos']
9--
10:refpage: vkCreateWaylandSurfaceKHR
11
12To create a sname:VkSurfaceKHR object for a Wayland surface, call:
13
14include::{generated}/api/protos/vkCreateWaylandSurfaceKHR.adoc[]
15
16  * pname:instance is the instance to associate the surface with.
17  * pname:pCreateInfo is a pointer to a slink:VkWaylandSurfaceCreateInfoKHR
18    structure containing parameters affecting the creation of the surface
19    object.
20  * pname:pAllocator is the allocator used for host memory allocated for the
21    surface object when there is no more specific allocator available (see
22    <<memory-allocation,Memory Allocation>>).
23  * pname:pSurface is a pointer to a slink:VkSurfaceKHR handle in which the
24    created surface object is returned.
25
26include::{generated}/validity/protos/vkCreateWaylandSurfaceKHR.adoc[]
27--
28
29[open,refpage='VkWaylandSurfaceCreateInfoKHR',desc='Structure specifying parameters of a newly created Wayland surface object',type='structs']
30--
31The sname:VkWaylandSurfaceCreateInfoKHR structure is defined as:
32
33include::{generated}/api/structs/VkWaylandSurfaceCreateInfoKHR.adoc[]
34
35  * pname:sType is a elink:VkStructureType value identifying this structure.
36  * pname:pNext is `NULL` or a pointer to a structure extending this
37    structure.
38  * pname:flags is reserved for future use.
39  * pname:display and pname:surface are pointers to the Wayland
40    code:wl_display and code:wl_surface to associate the surface with.
41
42.Valid Usage
43****
44  * [[VUID-VkWaylandSurfaceCreateInfoKHR-display-01304]]
45    pname:display must: point to a valid Wayland code:wl_display
46  * [[VUID-VkWaylandSurfaceCreateInfoKHR-surface-01305]]
47    pname:surface must: point to a valid Wayland code:wl_surface
48****
49
50include::{generated}/validity/structs/VkWaylandSurfaceCreateInfoKHR.adoc[]
51--
52
53On Wayland, pname:currentExtent is the special value [eq]#(0xFFFFFFFF,
540xFFFFFFFF)#, indicating that the surface size will be determined by the
55extent of a swapchain targeting the surface.
56Whatever the application sets a swapchain's pname:imageExtent to will be the
57size of the window, after the first image is presented.
58pname:minImageExtent is [eq]#(1,1)#, and pname:maxImageExtent is the maximum
59supported surface size.
60Any calls to flink:vkGetPhysicalDeviceSurfacePresentModesKHR on a surface
61created with fname:vkCreateWaylandSurfaceKHR are required: to return
62ename:VK_PRESENT_MODE_MAILBOX_KHR as one of the valid present modes.
63
64Some Vulkan functions may: send protocol over the specified code:wl_display
65connection when using a swapchain or presentable images created from a
66sname:VkSurfaceKHR referring to a code:wl_surface.
67Applications must: therefore ensure that both the code:wl_display and the
68code:wl_surface remain valid for the lifetime of any sname:VkSwapchainKHR
69objects created from a particular code:wl_display and code:wl_surface.
70Also, calling flink:vkQueuePresentKHR will result in Vulkan sending
71code:wl_surface.commit requests to the underlying code:wl_surface of each
72The code:wl_surface.attach, code:wl_surface.damage, and
73code:wl_surface.commit requests must: be issued by the implementation during
74the call to flink:vkQueuePresentKHR and must: not be issued by the
75implementation outside of flink:vkQueuePresentKHR.
76This ensures that any Wayland requests sent by the client after the call to
77flink:vkQueuePresentKHR returns will be received by the compositor after the
78code:wl_surface.commit.
79Regardless of the mode of swapchain creation, a new code:wl_event_queue
80must: be created for each successful flink:vkCreateWaylandSurfaceKHR call,
81and every Wayland object created by the implementation must: be assigned to
82this event queue.
83If the platform provides Wayland 1.11 or greater, this must: be implemented
84by the use of Wayland proxy object wrappers, to avoid race conditions.
85
86If the application wishes to synchronize any window changes with a
87particular frame, such requests must: be sent to the Wayland display server
88prior to calling flink:vkQueuePresentKHR.
89
90[open,refpage='VkWaylandSurfaceCreateFlagsKHR',desc='Reserved for future use',type='flags']
91--
92include::{generated}/api/flags/VkWaylandSurfaceCreateFlagsKHR.adoc[]
93
94tname:VkWaylandSurfaceCreateFlagsKHR is a bitmask type for setting a mask,
95but is currently reserved for future use.
96--
97