vkCreateSwapchainKHR
To create a swapchain, call:
VkResult vkCreateSwapchainKHR(
VkDevice device,
const VkSwapchainCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSwapchainKHR* pSwapchain);
device
is the device to create the swapchain for.pCreateInfo
is a pointer to a VkSwapchainCreateInfoKHR structure specifying the parameters of the created swapchain.pAllocator
is the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).pSwapchain
is a pointer to a VkSwapchainKHR handle in which the created swapchain object will be returned.
As mentioned above, if vkCreateSwapchainKHR
succeeds, it will return a
handle to a swapchain containing an array of at least
pCreateInfo→minImageCount
presentable images.
While acquired by the application, presentable images can be used in any way that equivalent non-presentable images can be used. A presentable image is equivalent to a non-presentable image created with the following VkImageCreateInfo parameters:
Value | |
---|---|
all other bits are unset | |
{ | |
1 | |
The pCreateInfo→surface
must not be destroyed until after the
swapchain is destroyed.
If oldSwapchain
is VK_NULL_HANDLE, and
the native window referred to by pCreateInfo→surface
is already
associated with a Vulkan swapchain, VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
must be returned.
If the native window referred to by pCreateInfo→surface
is already
associated with a non-Vulkan graphics API surface,
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
must be returned.
The native window referred to by pCreateInfo→surface
must not become
associated with a non-Vulkan graphics API surface before all associated
Vulkan swapchains have been destroyed.
vkCreateSwapchainKHR
will return VK_ERROR_DEVICE_LOST
if the
logical device was lost.
The VkSwapchainKHR
is a child of the device
, and must be
destroyed before the device
.
However, VkSurfaceKHR
is not a child of any VkDevice
and is not
affected by the lost device.
After successfully recreating a VkDevice
, the same VkSurfaceKHR
can be used to create a new VkSwapchainKHR
, provided the previous one
was destroyed.
If the oldSwapchain
parameter of pCreateInfo
is a valid
swapchain, which has exclusive full-screen access, that access is released
from pCreateInfo→oldSwapchain
.
If the command succeeds in this case, the newly created swapchain will
automatically acquire exclusive full-screen access from
pCreateInfo→oldSwapchain
.
This implicit transfer is intended to avoid exiting and entering full-screen exclusive mode, which may otherwise cause unwanted visual updates to the display.
In some cases, swapchain creation may fail if exclusive full-screen mode is
requested for application control, but for some implementation-specific
reason exclusive full-screen access is unavailable for the particular
combination of parameters provided.
If this occurs, VK_ERROR_INITIALIZATION_FAILED
will be returned.
In particular, it will fail if the imageExtent
member of
pCreateInfo
does not match the extents of the monitor.
Other reasons for failure may include the application not being set as
high-dpi aware, or if the physical device and monitor are not compatible in
this mode.
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkSwapchainPresentBarrierCreateInfoNV structure, then that structure
includes additional swapchain creation parameters specific to the present
barrier.
Swapchain creation may fail if the state of the current system restricts
the usage of the present barrier feature
VkSurfaceCapabilitiesPresentBarrierNV, or a swapchain itself does not
satisfy all the required conditions.
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
When the VkSurfaceKHR in VkSwapchainCreateInfoKHR is a display
surface, then the VkDisplayModeKHR in display surface’s
VkDisplaySurfaceCreateInfoKHR is associated with a particular
VkDisplayKHR.
Swapchain creation may fail if that VkDisplayKHR is not acquired by
the application.
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
Valid Usage (Implicit)
VUID-vkCreateSwapchainKHR-device-parameter
device
must be a valid VkDevice handle
VUID-vkCreateSwapchainKHR-pCreateInfo-parameter
pCreateInfo
must be a valid pointer to a valid VkSwapchainCreateInfoKHR structure
VUID-vkCreateSwapchainKHR-pAllocator-parameter
If pAllocator
is not NULL
, pAllocator
must be a valid pointer to a valid VkAllocationCallbacks structure
VUID-vkCreateSwapchainKHR-pSwapchain-parameter
pSwapchain
must be a valid pointer to a VkSwapchainKHR handle
Host Synchronization
- Host access to
pCreateInfo→surface
must be externally synchronized - Host access to
pCreateInfo→oldSwapchain
must be externally synchronized ::