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]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.

[Note]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.

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.

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]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).

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.