## 29.2. WSI Surface

A `VkSurfaceKHR` object abstracts a native platform surface or window object for use with Vulkan. The VK_KHR_surface extension declares the `VkSurfaceKHR` object, and provides a function for destroying `VkSurfaceKHR` objects. Separate platform-specific extensions each provide a function for creating a `VkSurfaceKHR` object for the respective platform. From the application’s perspective this is an opaque handle, just like the handles of other Vulkan objects.

| Note
On certain platforms, the Vulkan loader and ICDs may have conventions that treat the handle as a pointer to a struct that contains the platform-specific information about the surface. This will be described in the documentation for the loader-ICD interface, and in the "vk_icd.h" header file of the LoaderAndTools source-code repository. This does not affect the loader-layer interface; layers may wrap `VkSurfaceKHR` objects.

| editing-note
TODO: Consider replacing the above note editing note with a pointer to the loader spec when it exists. However, the information is not relevant to users of the API nor does it affect conformance of a Vulkan implementation to this spec.

### 29.2.1. Android Platform

To create a `VkSurfaceKHR` object for an Android native window, call:

    VkResult vkCreateAndroidSurfaceKHR(
        VkInstance                                  instance,
        const VkAndroidSurfaceCreateInfoKHR*        pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

- `instance` is the instance to associate the surface with.
- `pCreateInfo` is a pointer to an instance of the `VkAndroidSurfaceCreateInfoKHR` structure containing parameters affecting the creation of the surface object.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
- `pSurface` points to a `VkSurfaceKHR` handle in which the created surface object is returned.

During the lifetime of a surface created using a particular ANativeWindow handle any attempts to create another surface for the same ANativeWindow and any attempts to connect to the same ANativeWindow through other platform mechanisms will fail.

| NOTE
In particular, only one `VkSurfaceKHR` can exist at a time for a given window. Similarly, a native window cannot be used by both a `VkSurfaceKHR` and EGLSurface simultaneously.

If successful, `vkCreateAndroidSurfaceKHR` increments the ANativeWindow’s reference count, and `vkDestroySurfaceKHR` will decrement it.

On Android, when a swapchain’s `imageExtent` does not match the surface’s `currentExtent`, the swapchain images will be scaled to the surface’s dimensions during presentation. `minImageExtent` is $(1, 1)$ , and `maxImageExtent` is the maximum image size supported by the consumer. For the system compositor, `currentExtent` is the window size (i.e. the consumer’s preferred size).

The `VkAndroidSurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkAndroidSurfaceCreateInfoKHR {
        VkStructureType                   sType;
        const void*                       pNext;
        VkAndroidSurfaceCreateFlagsKHR    flags;
        ANativeWindow*                    window;
    } VkAndroidSurfaceCreateInfoKHR;

- `sType` is the type of this structure and must be `VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR`.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `flags` is reserved for future use.
- `window` is a pointer to the ANativeWindow to associate the surface with.

### 29.2.2. Mir Platform

To create a `VkSurfaceKHR` object for a Mir window, call:

    VkResult vkCreateMirSurfaceKHR(
        VkInstance                                  instance,
        const VkMirSurfaceCreateInfoKHR*            pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

- `instance` is the instance to associate the surface with.
- `pCreateInfo` is a pointer to an instance of the `VkMirSurfaceCreateInfoKHR` structure containing parameters affecting the creation of the surface object.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
- `pSurface` points to a `VkSurfaceKHR` handle in which the created surface object is returned.

The `VkMirSurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkMirSurfaceCreateInfoKHR {
        VkStructureType               sType;
        const void*                   pNext;
        VkMirSurfaceCreateFlagsKHR    flags;
        MirConnection*                connection;
        MirSurface*                   mirSurface;
    } VkMirSurfaceCreateInfoKHR;

- `sType` is the type of this structure and must be `VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR`.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `flags` is reserved for future use.
- `connection` and `surface` are pointers to the MirConnection and MirSurface for the window to associate the surface with.

On Mir, when a swapchain’s `imageExtent` does not match the surface’s `currentExtent`, the swapchain images will be scaled to the surface’s dimensions during presentation. `minImageExtent` is $(1, 1)$ , and `maxImageExtent` is the maximum supported surface size.

### 29.2.3. Wayland Platform

To create a `VkSurfaceKHR` object for a Wayland surface, call:

    VkResult vkCreateWaylandSurfaceKHR(
        VkInstance                                  instance,
        const VkWaylandSurfaceCreateInfoKHR*        pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

- `instance` is the instance to associate the surface with.
- `pCreateInfo` is a pointer to an instance of the `VkWaylandSurfaceCreateInfoKHR` structure containing parameters affecting the creation of the surface object.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
- `pSurface` points to a `VkSurfaceKHR` handle in which the created surface object is returned.

The `VkWaylandSurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkWaylandSurfaceCreateInfoKHR {
        VkStructureType                   sType;
        const void*                       pNext;
        VkWaylandSurfaceCreateFlagsKHR    flags;
        struct wl_display*                display;
        struct wl_surface*                surface;
    } VkWaylandSurfaceCreateInfoKHR;

- `sType` is the type of this structure and must be `VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR`.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `flags` is reserved for future use.
- `display` and `surface` are pointers to the Wayland `wl_display` and `wl_surface` to associate the surface with.

On Wayland, `currentExtent` is undefined $(0,0)$ . Whatever the application sets a swapchain’s `imageExtent` to will be the size of the window, after the first image is presented. `minImageExtent` is $(1,1)$ , and `maxImageExtent` is the maximum supported surface size.

Some Vulkan functions may send protocol over the specified `wl_display` connection when using a swapchain or presentable images created from a `VkSurfaceKHR` referring to a `wl_surface`. Applications must therefore ensure that both the `wl_display` and the `wl_surface` remain valid for the lifetime of any `VkSwapchainKHR` objects created from a particular `wl_display` and `wl_surface`. Also, calling `vkQueuePresentKHR` will result in Vulkan sending `wl_surface`.commit requests to the underlying `wl_surface` of each `VkSwapchainKHR` objects referenced by `pPresentInfo`. Therefore, if the application wishes to synchronize any window changes with a particular frame, such requests must be sent to the Wayland display server prior to calling `vkQueuePresentKHR`.

### 29.2.4. Win32 Platform

To create a `VkSurfaceKHR` object for a Win32 window, call:

    VkResult vkCreateWin32SurfaceKHR(
        VkInstance                                  instance,
        const VkWin32SurfaceCreateInfoKHR*          pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

- `instance` is the instance to associate the surface with.
- `pCreateInfo` is a pointer to an instance of the `VkWin32SurfaceCreateInfoKHR` structure containing parameters affecting the creation of the surface object.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
- `pSurface` points to a `VkSurfaceKHR` handle in which the created surface object is returned.

The `VkWin32SurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkWin32SurfaceCreateInfoKHR {
        VkStructureType                 sType;
        const void*                     pNext;
        VkWin32SurfaceCreateFlagsKHR    flags;
        HINSTANCE                       hinstance;
        HWND                            hwnd;
    } VkWin32SurfaceCreateInfoKHR;

- `sType` is the type of this structure and must be `VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR`.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `flags` is reserved for future use.
- `hinstance` and `hwnd` are the Win32 `HINSTANCE` and `HWND` for the window to associate the surface with.

With Win32, `minImageExtent`, `maxImageExtent`, and `currentExtent` are the window size. Therefore, a swapchain’s `imageExtent` must match the window’s size.

### 29.2.5. XCB Platform

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

    VkResult vkCreateXcbSurfaceKHR(
        VkInstance                                  instance,
        const VkXcbSurfaceCreateInfoKHR*            pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

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

The `VkXcbSurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkXcbSurfaceCreateInfoKHR {
        VkStructureType               sType;
        const void*                   pNext;
        VkXcbSurfaceCreateFlagsKHR    flags;
        xcb_connection_t*             connection;
        xcb_window_t                  window;
    } VkXcbSurfaceCreateInfoKHR;

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

With Xcb, `minImageExtent`, `maxImageExtent`, and `currentExtent` are the window size. Therefore, a swapchain’s `imageExtent` must match the window’s size.

Some Vulkan functions may send protocol over the specified xcb connection when using a swapchain or presentable images created from a VkSurface 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.

### 29.2.6. Xlib Platform

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

    VkResult vkCreateXlibSurfaceKHR(
        VkInstance                                  instance,
        const VkXlibSurfaceCreateInfoKHR*           pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSurfaceKHR*                               pSurface);

- `instance` is the instance to associate the surface with.
- `pCreateInfo` is a pointer to an instance of the `VkXlibSurfaceCreateInfoKHR` structure containing the parameters affecting the creation of the surface object.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
- `pSurface` points to a `VkSurfaceKHR` handle in which the created surface object is returned.

The `VkXlibSurfaceCreateInfoKHR` structure is defined as:

    typedef struct VkXlibSurfaceCreateInfoKHR {
        VkStructureType                sType;
        const void*                    pNext;
        VkXlibSurfaceCreateFlagsKHR    flags;
        Display*                       dpy;
        Window                         window;
    } VkXlibSurfaceCreateInfoKHR;

- `sType` is the type of this structure and must be `VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR`.
- `pNext` is `NULL` or a pointer to an extension-specific structure.
- `flags` is reserved for future use.
- `dpy` is a pointer to an Xlib Display connection to the X server.
- `window` is an Xlib Window to associate the surface with.

With Xlib, `minImageExtent`, `maxImageExtent`, and `currentExtent` are the window size. Therefore, a swapchain’s `imageExtent` must match the window’s size.

Some Vulkan functions may send protocol over the specified Xlib Display connection when using a swapchain or presentable images created from a VkSurface 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

- Call XInitThreads() before calling any other Xlib functions if they intend to use Vulkan in multiple threads, or use Vulkan and Xlib in separate threads.
- 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.

### 29.2.7. Platform-Independent Information

Once created, `VkSurfaceKHR` objects can be used in this and other extensions, in particular the VK_KHR_swapchain extension.

Several WSI functions return `VK_ERROR_SURFACE_LOST_KHR` if the surface becomes no longer available. After such an error, the surface (and any child swapchain, if one exists) should be destroyed, as there is no way to restore them to a not-lost state. Applications may attempt to create a new `VkSurfaceKHR` using the same native platform window object, but whether such re-creation will succeed is platform-dependent and may depend on the reason the surface became unavailable. A lost surface does not otherwise cause devices to be lost.

To destroy a `VkSurfaceKHR` object, call:

    void vkDestroySurfaceKHR(
        VkInstance                                  instance,
        VkSurfaceKHR                                surface,
        const VkAllocationCallbacks*                pAllocator);

- `instance` is the instance used to create the surface.
- `surface` is the surface to destroy.
- `pAllocator` is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

Destroying a `VkSurfaceKHR` merely severs the connection between Vulkan and the native surface, and doesn’t imply destroying the native surface, closing a window, or similar behavior.