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.