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
|
![]() | 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. |
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 |
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.
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.
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.
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.
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.
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 (0xFFFFFFFF, 0xFFFFFFFF).
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
.
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.
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.
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.
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
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.
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
XInitThreads
() before calling any other Xlib functions if they
intend to use Vulkan in multiple threads, or use Vulkan and Xlib in
separate threads.
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 does not imply destroying the native surface,
closing a window, or similar behavior.