Class KHRSwapchain
VK_KHR_swapchain
extension is the device-level companion to the VK_KHR_surface
extension. It introduces VkSwapchainKHR
objects, which provide the ability to present rendering results to a surface.
Examples
Note
The example code for the VK_KHR_surface
and VK_KHR_swapchain
extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).
VK_KHR_swapchain
- Name String
VK_KHR_swapchain
- Extension Type
- Device extension
- Registered Extension Number
- 2
- Revision
- 70
- Extension and Version Dependencies
VK_KHR_surface
- Contact
- James Jones cubanismo
- Ian Elliott ianelliottus
Other Extension Metadata
- Last Modified Date
- 2017-10-06
- IP Status
- No known IP claims.
- Interactions and External Dependencies
- Interacts with Vulkan 1.1
- Contributors
- Patrick Doane, Blizzard
- Ian Elliott, LunarG
- Jesse Hall, Google
- Mathias Heyer, NVIDIA
- James Jones, NVIDIA
- David Mao, AMD
- Norbert Nopper, Freescale
- Alon Or-bach, Samsung
- Daniel Rakos, AMD
- Graham Sellers, AMD
- Jeff Vigil, Qualcomm
- Chia-I Wu, LunarG
- Faith Ekstrand, Intel
- Matthaeus G. Chajdas, AMD
- Ray Smith, ARM
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesstatic final int
VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesstatic final int
VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesstatic final int
VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesstatic final int
ExtendsVkResult
.static final int
ExtendsVkImageLayout
.static final String
The extension name.static final int
The extension specification version.static final int
ExtendsVkObjectType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkResult
.static final int
ExtendsVkSwapchainCreateFlagBitsKHR
.static final int
ExtendsVkSwapchainCreateFlagBitsKHR
. -
Method Summary
Modifier and TypeMethodDescriptionstatic int
nvkAcquireNextImage2KHR
(VkDevice device, long pAcquireInfo, long pImageIndex) Unsafe version of:AcquireNextImage2KHR
static int
nvkAcquireNextImageKHR
(VkDevice device, long swapchain, long timeout, long semaphore, long fence, long pImageIndex) Unsafe version of:AcquireNextImageKHR
static int
nvkCreateSwapchainKHR
(VkDevice device, long pCreateInfo, long pAllocator, long pSwapchain) Unsafe version of:CreateSwapchainKHR
static void
nvkDestroySwapchainKHR
(VkDevice device, long swapchain, long pAllocator) Unsafe version of:DestroySwapchainKHR
static int
nvkGetDeviceGroupPresentCapabilitiesKHR
(VkDevice device, long pDeviceGroupPresentCapabilities) Unsafe version of:GetDeviceGroupPresentCapabilitiesKHR
static int
nvkGetDeviceGroupSurfacePresentModesKHR
(VkDevice device, long surface, long pModes) Unsafe version of:GetDeviceGroupSurfacePresentModesKHR
static int
nvkGetPhysicalDevicePresentRectanglesKHR
(VkPhysicalDevice physicalDevice, long surface, long pRectCount, long pRects) Unsafe version of:GetPhysicalDevicePresentRectanglesKHR
static int
nvkGetSwapchainImagesKHR
(VkDevice device, long swapchain, long pSwapchainImageCount, long pSwapchainImages) Unsafe version of:GetSwapchainImagesKHR
static int
nvkQueuePresentKHR
(VkQueue queue, long pPresentInfo) Unsafe version of:QueuePresentKHR
static int
vkAcquireNextImage2KHR
(VkDevice device, VkAcquireNextImageInfoKHR pAcquireInfo, int[] pImageIndex) Array version of:AcquireNextImage2KHR
static int
vkAcquireNextImage2KHR
(VkDevice device, VkAcquireNextImageInfoKHR pAcquireInfo, IntBuffer pImageIndex) Retrieve the index of the next available presentable image.static int
vkAcquireNextImageKHR
(VkDevice device, long swapchain, long timeout, long semaphore, long fence, int[] pImageIndex) Array version of:AcquireNextImageKHR
static int
vkAcquireNextImageKHR
(VkDevice device, long swapchain, long timeout, long semaphore, long fence, IntBuffer pImageIndex) Retrieve the index of the next available presentable image.static int
vkCreateSwapchainKHR
(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, long[] pSwapchain) Array version of:CreateSwapchainKHR
static int
vkCreateSwapchainKHR
(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, LongBuffer pSwapchain) Create a swapchain.static void
vkDestroySwapchainKHR
(VkDevice device, long swapchain, VkAllocationCallbacks pAllocator) Destroy a swapchain object.static int
vkGetDeviceGroupPresentCapabilitiesKHR
(VkDevice device, VkDeviceGroupPresentCapabilitiesKHR pDeviceGroupPresentCapabilities) Query present capabilities from other physical devices.static int
vkGetDeviceGroupSurfacePresentModesKHR
(VkDevice device, long surface, int[] pModes) Array version of:GetDeviceGroupSurfacePresentModesKHR
static int
vkGetDeviceGroupSurfacePresentModesKHR
(VkDevice device, long surface, IntBuffer pModes) Query present capabilities for a surface.static int
vkGetPhysicalDevicePresentRectanglesKHR
(VkPhysicalDevice physicalDevice, long surface, int[] pRectCount, VkRect2D.Buffer pRects) Array version of:GetPhysicalDevicePresentRectanglesKHR
static int
vkGetPhysicalDevicePresentRectanglesKHR
(VkPhysicalDevice physicalDevice, long surface, IntBuffer pRectCount, VkRect2D.Buffer pRects) Query present rectangles for a surface on a physical device.static int
vkGetSwapchainImagesKHR
(VkDevice device, long swapchain, int[] pSwapchainImageCount, long[] pSwapchainImages) Array version of:GetSwapchainImagesKHR
static int
vkGetSwapchainImagesKHR
(VkDevice device, long swapchain, IntBuffer pSwapchainImageCount, LongBuffer pSwapchainImages) Obtain the array of presentable images associated with a swapchain.static int
vkQueuePresentKHR
(VkQueue queue, VkPresentInfoKHR pPresentInfo) Queue an image for presentation.
-
Field Details
-
VK_KHR_SWAPCHAIN_SPEC_VERSION
public static final int VK_KHR_SWAPCHAIN_SPEC_VERSIONThe extension specification version.- See Also:
-
VK_KHR_SWAPCHAIN_EXTENSION_NAME
The extension name.- See Also:
-
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
public static final int VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
public static final int VK_STRUCTURE_TYPE_PRESENT_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
public static final int VK_IMAGE_LAYOUT_PRESENT_SRC_KHRExtendsVkImageLayout
.- See Also:
-
VK_SUBOPTIMAL_KHR
public static final int VK_SUBOPTIMAL_KHR- See Also:
-
VK_ERROR_OUT_OF_DATE_KHR
public static final int VK_ERROR_OUT_OF_DATE_KHR- See Also:
-
VK_OBJECT_TYPE_SWAPCHAIN_KHR
public static final int VK_OBJECT_TYPE_SWAPCHAIN_KHRExtendsVkObjectType
.- See Also:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR
public static final int VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR
public static final int VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR
public static final int VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR
public static final int VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
public static final int VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
public static final int VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHRExtendsVkStructureType
.Enum values:
- See Also:
-
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
public static final int VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHRExtendsVkSwapchainCreateFlagBitsKHR
.Enum values:
- See Also:
-
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
public static final int VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHRExtendsVkSwapchainCreateFlagBitsKHR
.Enum values:
- See Also:
-
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
public static final int VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHRVkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesDescription
DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
specifies that any physical device with a presentation engine can present its own swapchain images.DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
specifies that any physical device with a presentation engine can present swapchain images from any physical device in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR
specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
specifies that multiple physical devices with a presentation engine can each present their own swapchain images.
See Also
- See Also:
-
VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
public static final int VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHRVkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesDescription
DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
specifies that any physical device with a presentation engine can present its own swapchain images.DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
specifies that any physical device with a presentation engine can present swapchain images from any physical device in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR
specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
specifies that multiple physical devices with a presentation engine can each present their own swapchain images.
See Also
- See Also:
-
VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR
public static final int VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHRVkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesDescription
DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
specifies that any physical device with a presentation engine can present its own swapchain images.DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
specifies that any physical device with a presentation engine can present swapchain images from any physical device in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR
specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
specifies that multiple physical devices with a presentation engine can each present their own swapchain images.
See Also
- See Also:
-
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
public static final int VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHRVkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modesDescription
DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
specifies that any physical device with a presentation engine can present its own swapchain images.DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
specifies that any physical device with a presentation engine can present swapchain images from any physical device in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR
specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in itspresentMask
.DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
specifies that multiple physical devices with a presentation engine can each present their own swapchain images.
See Also
- See Also:
-
-
Method Details
-
nvkCreateSwapchainKHR
public static int nvkCreateSwapchainKHR(VkDevice device, long pCreateInfo, long pAllocator, long pSwapchain) Unsafe version of:CreateSwapchainKHR
-
vkCreateSwapchainKHR
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, LongBuffer pSwapchain) Create a swapchain.C Specification
To create a swapchain, call:
VkResult vkCreateSwapchainKHR( VkDevice device, const VkSwapchainCreateInfoKHR* pCreateInfo, const VkAllocationCallbacks* pAllocator, VkSwapchainKHR* pSwapchain);
Description
As mentioned above, if
vkCreateSwapchainKHR
succeeds, it will return a handle to a swapchain containing an array of at leastpCreateInfo→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:VkImageCreateInfo
FieldValue flags
IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
is set ifSWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
is setIMAGE_CREATE_PROTECTED_BIT
is set ifSWAPCHAIN_CREATE_PROTECTED_BIT_KHR
is setIMAGE_CREATE_MUTABLE_FORMAT_BIT
andIMAGE_CREATE_EXTENDED_USAGE_BIT_KHR
are both set ifSWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
is set all other bits are unsetimageType
IMAGE_TYPE_2D
format
pCreateInfo→imageFormat
extent
{ pCreateInfo→imageExtent.width
,pCreateInfo→imageExtent.height
, 1}mipLevels
1 arrayLayers
pCreateInfo→imageArrayLayers
samples
SAMPLE_COUNT_1_BIT
tiling
IMAGE_TILING_OPTIMAL
usage
pCreateInfo→imageUsage
sharingMode
pCreateInfo→imageSharingMode
queueFamilyIndexCount
pCreateInfo→queueFamilyIndexCount
pQueueFamilyIndices
pCreateInfo→pQueueFamilyIndices
initialLayout
IMAGE_LAYOUT_UNDEFINED
The
pCreateInfo→surface
must not be destroyed until after the swapchain is destroyed.If
oldSwapchain
isNULL_HANDLE
, and the native window referred to bypCreateInfo→surface
is already associated with a Vulkan swapchain,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,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 returnERROR_DEVICE_LOST
if the logical device was lost. TheVkSwapchainKHR
is a child of thedevice
, and must be destroyed before thedevice
. However,VkSurfaceKHR
is not a child of anyVkDevice
and is not affected by the lost device. After successfully recreating aVkDevice
, the sameVkSurfaceKHR
can be used to create a newVkSwapchainKHR
, provided the previous one was destroyed.If the
oldSwapchain
parameter ofpCreateInfo
is a valid swapchain, which has exclusive full-screen access, that access is released frompCreateInfo→oldSwapchain
. If the command succeeds in this case, the newly created swapchain will automatically acquire exclusive full-screen access frompCreateInfo→oldSwapchain
.Note
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,
ERROR_INITIALIZATION_FAILED
will be returned.Note
In particular, it will fail if the
imageExtent
member ofpCreateInfo
does not match the extents of the monitor. Other reasons for failure may include the app not being set as high-dpi aware, or if the physical device and monitor are not compatible in this mode.If the
pNext
chain ofVkSwapchainCreateInfoKHR
includes aVkSwapchainPresentBarrierCreateInfoNV
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 featureVkSurfaceCapabilitiesPresentBarrierNV
, or a swapchain itself does not satisfy all the required conditions. In this scenarioERROR_INITIALIZATION_FAILED
is returned.When the
VkSurfaceKHR
inVkSwapchainCreateInfoKHR
is a display surface, then theVkDisplayModeKHR
in display surface’sVkDisplaySurfaceCreateInfoKHR
is associated with a particularVkDisplayKHR
. Swapchain creation may fail if thatVkDisplayKHR
is not acquired by the application. In this scenarioERROR_INITIALIZATION_FAILED
is returned.Valid Usage (Implicit)
device
must be a validVkDevice
handlepCreateInfo
must be a valid pointer to a validVkSwapchainCreateInfoKHR
structure- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure pSwapchain
must be a valid pointer to aVkSwapchainKHR
handle
Host Synchronization
- Host access to
pCreateInfo→surface
must be externally synchronized - Host access to
pCreateInfo→oldSwapchain
must be externally synchronized
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
device
- the device to create the swapchain for.pCreateInfo
- a pointer to aVkSwapchainCreateInfoKHR
structure specifying the parameters of the created swapchain.pAllocator
- the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).pSwapchain
- a pointer to aVkSwapchainKHR
handle in which the created swapchain object will be returned.
-
nvkDestroySwapchainKHR
Unsafe version of:DestroySwapchainKHR
-
vkDestroySwapchainKHR
public static void vkDestroySwapchainKHR(VkDevice device, long swapchain, @Nullable VkAllocationCallbacks pAllocator) Destroy a swapchain object.C Specification
To destroy a swapchain object call:
void vkDestroySwapchainKHR( VkDevice device, VkSwapchainKHR swapchain, const VkAllocationCallbacks* pAllocator);
Description
The application must not destroy a swapchain until after completion of all outstanding operations on images that were acquired from the swapchain.
swapchain
and all associatedVkImage
handles are destroyed, and must not be acquired or used any more by the application. The memory of eachVkImage
will only be freed after that image is no longer used by the presentation engine. For example, if one image of the swapchain is being displayed in a window, the memory for that image may not be freed until the window is destroyed, or another swapchain is created for the window. Destroying the swapchain does not invalidate the parentVkSurfaceKHR
, and a new swapchain can be created with it.When a swapchain associated with a display surface is destroyed, if the image most recently presented to the display surface is from the swapchain being destroyed, then either any display resources modified by presenting images from any swapchain associated with the display surface must be reverted by the implementation to their state prior to the first present performed on one of these swapchains, or such resources must be left in their current state.
If
swapchain
has exclusive full-screen access, it is released before the swapchain is destroyed.Valid Usage
- All uses of presentable images acquired from
swapchain
must have completed execution - If
VkAllocationCallbacks
were provided whenswapchain
was created, a compatible set of callbacks must be provided here - If no
VkAllocationCallbacks
were provided whenswapchain
was created,pAllocator
must beNULL
Valid Usage (Implicit)
device
must be a validVkDevice
handle- If
swapchain
is notNULL_HANDLE
,swapchain
must be a validVkSwapchainKHR
handle - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure - If
swapchain
is a valid handle, it must have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
swapchain
must be externally synchronized
See Also
- Parameters:
device
- theVkDevice
associated withswapchain
.swapchain
- the swapchain to destroy.pAllocator
- the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).
- All uses of presentable images acquired from
-
nvkGetSwapchainImagesKHR
public static int nvkGetSwapchainImagesKHR(VkDevice device, long swapchain, long pSwapchainImageCount, long pSwapchainImages) Unsafe version of:GetSwapchainImagesKHR
- Parameters:
pSwapchainImageCount
- a pointer to an integer related to the number of presentable images available or queried, as described below.
-
vkGetSwapchainImagesKHR
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, IntBuffer pSwapchainImageCount, @Nullable LongBuffer pSwapchainImages) Obtain the array of presentable images associated with a swapchain.C Specification
To obtain the array of presentable images associated with a swapchain, call:
VkResult vkGetSwapchainImagesKHR( VkDevice device, VkSwapchainKHR swapchain, uint32_t* pSwapchainImageCount, VkImage* pSwapchainImages);
Description
If
pSwapchainImages
isNULL
, then the number of presentable images forswapchain
is returned inpSwapchainImageCount
. Otherwise,pSwapchainImageCount
must point to a variable set by the user to the number of elements in thepSwapchainImages
array, and on return the variable is overwritten with the number of structures actually written topSwapchainImages
. If the value ofpSwapchainImageCount
is less than the number of presentable images forswapchain
, at mostpSwapchainImageCount
structures will be written, andINCOMPLETE
will be returned instead ofSUCCESS
, to indicate that not all the available presentable images were returned.Valid Usage (Implicit)
device
must be a validVkDevice
handleswapchain
must be a validVkSwapchainKHR
handlepSwapchainImageCount
must be a valid pointer to auint32_t
value- If the value referenced by
pSwapchainImageCount
is not 0, andpSwapchainImages
is notNULL
,pSwapchainImages
must be a valid pointer to an array ofpSwapchainImageCount
VkImage
handles swapchain
must have been created, allocated, or retrieved fromdevice
Return Codes
- On success, this command returns
- On failure, this command returns
- Parameters:
device
- the device associated withswapchain
.swapchain
- the swapchain to query.pSwapchainImageCount
- a pointer to an integer related to the number of presentable images available or queried, as described below.pSwapchainImages
- eitherNULL
or a pointer to an array ofVkImage
handles.
-
nvkAcquireNextImageKHR
public static int nvkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, long pImageIndex) Unsafe version of:AcquireNextImageKHR
-
vkAcquireNextImageKHR
public static int vkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, IntBuffer pImageIndex) Retrieve the index of the next available presentable image.C Specification
To acquire an available presentable image to use, and retrieve the index of that image, call:
VkResult vkAcquireNextImageKHR( VkDevice device, VkSwapchainKHR swapchain, uint64_t timeout, VkSemaphore semaphore, VkFence fence, uint32_t* pImageIndex);
Description
If the
swapchain
has been created with theSWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
flag, the image whose index is returned inpImageIndex
will be fully backed by memory before this call returns to the application, as if it is bound completely and contiguously to a singleVkDeviceMemory
object.Valid Usage
swapchain
must not be in the retired state- If
semaphore
is notNULL_HANDLE
it must be unsignaled - If
semaphore
is notNULL_HANDLE
it must not have any uncompleted signal or wait operations pending - If
fence
is notNULL_HANDLE
it must be unsignaled and must not be associated with any other queue command that has not yet completed execution on that queue semaphore
andfence
must not both be equal toNULL_HANDLE
- If forward progress cannot be guaranteed for the
surface
used to create theswapchain
member ofpAcquireInfo
, thetimeout
member ofpAcquireInfo
must not beUINT64_MAX
semaphore
must have aVkSemaphoreType
ofSEMAPHORE_TYPE_BINARY
Valid Usage (Implicit)
device
must be a validVkDevice
handleswapchain
must be a validVkSwapchainKHR
handle- If
semaphore
is notNULL_HANDLE
,semaphore
must be a validVkSemaphore
handle - If
fence
is notNULL_HANDLE
,fence
must be a validVkFence
handle pImageIndex
must be a valid pointer to auint32_t
valueswapchain
must have been created, allocated, or retrieved fromdevice
- If
semaphore
is a valid handle, it must have been created, allocated, or retrieved fromdevice
- If
fence
is a valid handle, it must have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
swapchain
must be externally synchronized - Host access to
semaphore
must be externally synchronized - Host access to
fence
must be externally synchronized
Return Codes
- On success, this command returns
- On failure, this command returns
- Parameters:
device
- the device associated withswapchain
.swapchain
- the non-retired swapchain from which an image is being acquired.timeout
- specifies how long the function waits, in nanoseconds, if no image is available.semaphore
-NULL_HANDLE
or a semaphore to signal.fence
-NULL_HANDLE
or a fence to signal.pImageIndex
- a pointer to auint32_t
in which the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR
) is returned.
-
nvkQueuePresentKHR
Unsafe version of:QueuePresentKHR
-
vkQueuePresentKHR
Queue an image for presentation.C Specification
After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:
VkResult vkQueuePresentKHR( VkQueue queue, const VkPresentInfoKHR* pPresentInfo);
Description
Note
There is no requirement for an application to present images in the same order that they were acquired - applications can arbitrarily present any image that is currently acquired.
Valid Usage
- Each element of
pSwapchains
member ofpPresentInfo
must be a swapchain that is created for a surface for which presentation is supported fromqueue
as determined using a call tovkGetPhysicalDeviceSurfaceSupportKHR
- If more than one member of
pSwapchains
was created from a display surface, all display surfaces referenced that refer to the same display must use the same display mode - When a semaphore wait operation referring to a binary semaphore defined by the elements of the
pWaitSemaphores
member ofpPresentInfo
executes onqueue
, there must be no other queues waiting on the same semaphore - All elements of the
pWaitSemaphores
member ofpPresentInfo
must be created with aVkSemaphoreType
ofSEMAPHORE_TYPE_BINARY
- All elements of the
pWaitSemaphores
member ofpPresentInfo
must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution
Any writes to memory backing the images referenced by the
pImageIndices
andpSwapchains
members ofpPresentInfo
, that are available beforeQueuePresentKHR
is executed, are automatically made visible to the read access performed by the presentation engine. This automatic visibility operation for an image happens-after the semaphore signal operation, and happens-before the presentation engine accesses the image.Queueing an image for presentation defines a set of queue operations, including waiting on the semaphores and submitting a presentation request to the presentation engine. However, the scope of this set of queue operations does not include the actual processing of the image by the presentation engine.
Note
The origin of the native orientation of the surface coordinate system is not specified in the Vulkan specification; it depends on the platform. For most platforms the origin is by default upper-left, meaning the pixel of the presented
VkImage
at coordinates(0,0)
would appear at the upper left pixel of the platform surface (assumingSURFACE_TRANSFORM_IDENTITY_BIT_KHR
, and the display standing the right way up).If
vkQueuePresentKHR
fails to enqueue the corresponding set of queue operations, it may returnERROR_OUT_OF_HOST_MEMORY
orERROR_OUT_OF_DEVICE_MEMORY
. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced is unaffected by the call or its failure.If
vkQueuePresentKHR
fails in such a way that the implementation is unable to make that guarantee, the implementation must returnERROR_DEVICE_LOST
.However, if the presentation request is rejected by the presentation engine with an error
ERROR_OUT_OF_DATE_KHR
,ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
, orERROR_SURFACE_LOST_KHR
, the set of queue operations are still considered to be enqueued and thus any semaphore wait operation specified inVkPresentInfoKHR
will execute when the corresponding queue operation is complete.Calls to
vkQueuePresentKHR
may block, but must return in finite time.If any
swapchain
member ofpPresentInfo
was created withFULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
,ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
will be returned if that swapchain does not have exclusive full-screen access, possibly for implementation-specific reasons outside of the application’s control.Valid Usage (Implicit)
queue
must be a validVkQueue
handlepPresentInfo
must be a valid pointer to a validVkPresentInfoKHR
structure
Host Synchronization
- Host access to
queue
must be externally synchronized - Host access to
pPresentInfo→pWaitSemaphores
[] must be externally synchronized - Host access to
pPresentInfo→pSwapchains
[] must be externally synchronized
Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type - - - Any - Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
queue
- a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain.pPresentInfo
- a pointer to aVkPresentInfoKHR
structure specifying parameters of the presentation.
- Each element of
-
nvkGetDeviceGroupPresentCapabilitiesKHR
public static int nvkGetDeviceGroupPresentCapabilitiesKHR(VkDevice device, long pDeviceGroupPresentCapabilities) Unsafe version of:GetDeviceGroupPresentCapabilitiesKHR
-
vkGetDeviceGroupPresentCapabilitiesKHR
public static int vkGetDeviceGroupPresentCapabilitiesKHR(VkDevice device, VkDeviceGroupPresentCapabilitiesKHR pDeviceGroupPresentCapabilities) Query present capabilities from other physical devices.C Specification
A logical device that represents multiple physical devices may support presenting from images on more than one physical device, or combining images from multiple physical devices.
To query these capabilities, call:
VkResult vkGetDeviceGroupPresentCapabilitiesKHR( VkDevice device, VkDeviceGroupPresentCapabilitiesKHR* pDeviceGroupPresentCapabilities);
Valid Usage (Implicit)
device
must be a validVkDevice
handlepDeviceGroupPresentCapabilities
must be a valid pointer to aVkDeviceGroupPresentCapabilitiesKHR
structure
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
device
- the logical device.pDeviceGroupPresentCapabilities
- a pointer to aVkDeviceGroupPresentCapabilitiesKHR
structure in which the device’s capabilities are returned.
-
nvkGetDeviceGroupSurfacePresentModesKHR
public static int nvkGetDeviceGroupSurfacePresentModesKHR(VkDevice device, long surface, long pModes) Unsafe version of:GetDeviceGroupSurfacePresentModesKHR
-
vkGetDeviceGroupSurfacePresentModesKHR
public static int vkGetDeviceGroupSurfacePresentModesKHR(VkDevice device, long surface, IntBuffer pModes) Query present capabilities for a surface.C Specification
Some surfaces may not be capable of using all the device group present modes.
To query the supported device group present modes for a particular surface, call:
VkResult vkGetDeviceGroupSurfacePresentModesKHR( VkDevice device, VkSurfaceKHR surface, VkDeviceGroupPresentModeFlagsKHR* pModes);
Description
The modes returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded. These modes must be a subset of the modes returned by
GetDeviceGroupPresentCapabilitiesKHR
.Valid Usage
surface
must be supported by all physical devices associated withdevice
, as reported byGetPhysicalDeviceSurfaceSupportKHR
or an equivalent platform-specific mechanism
Valid Usage (Implicit)
device
must be a validVkDevice
handlesurface
must be a validVkSurfaceKHR
handlepModes
must be a valid pointer to aVkDeviceGroupPresentModeFlagsKHR
value- Both of
device
, andsurface
must have been created, allocated, or retrieved from the sameVkInstance
Host Synchronization
- Host access to
surface
must be externally synchronized
Return Codes
- On success, this command returns
- On failure, this command returns
- Parameters:
device
- the logical device.surface
- the surface.pModes
- a pointer to aVkDeviceGroupPresentModeFlagsKHR
in which the supported device group present modes for the surface are returned.
-
nvkGetPhysicalDevicePresentRectanglesKHR
public static int nvkGetPhysicalDevicePresentRectanglesKHR(VkPhysicalDevice physicalDevice, long surface, long pRectCount, long pRects) Unsafe version of:GetPhysicalDevicePresentRectanglesKHR
- Parameters:
pRectCount
- a pointer to an integer related to the number of rectangles available or queried, as described below.
-
vkGetPhysicalDevicePresentRectanglesKHR
public static int vkGetPhysicalDevicePresentRectanglesKHR(VkPhysicalDevice physicalDevice, long surface, IntBuffer pRectCount, @Nullable VkRect2D.Buffer pRects) Query present rectangles for a surface on a physical device.C Specification
When using
DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
, the application may need to know which regions of the surface are used when presenting locally on each physical device. Presentation of swapchain images to this surface need only have valid contents in the regions returned by this command.To query a set of rectangles used in presentation on the physical device, call:
VkResult vkGetPhysicalDevicePresentRectanglesKHR( VkPhysicalDevice physicalDevice, VkSurfaceKHR surface, uint32_t* pRectCount, VkRect2D* pRects);
Description
If
pRects
isNULL
, then the number of rectangles used when presenting the givensurface
is returned inpRectCount
. Otherwise,pRectCount
must point to a variable set by the user to the number of elements in thepRects
array, and on return the variable is overwritten with the number of structures actually written topRects
. If the value ofpRectCount
is less than the number of rectangles, at mostpRectCount
structures will be written, andINCOMPLETE
will be returned instead ofSUCCESS
, to indicate that not all the available rectangles were returned.The values returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded.
The rectangles returned by this command must not overlap.
Valid Usage
surface
must be a validVkSurfaceKHR
handlesurface
must be supported byphysicalDevice
, as reported byGetPhysicalDeviceSurfaceSupportKHR
or an equivalent platform-specific mechanism
Valid Usage (Implicit)
physicalDevice
must be a validVkPhysicalDevice
handlesurface
must be a validVkSurfaceKHR
handlepRectCount
must be a valid pointer to auint32_t
value- If the value referenced by
pRectCount
is not 0, andpRects
is notNULL
,pRects
must be a valid pointer to an array ofpRectCount
VkRect2D
structures - Both of
physicalDevice
, andsurface
must have been created, allocated, or retrieved from the sameVkInstance
Host Synchronization
- Host access to
surface
must be externally synchronized
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
physicalDevice
- the physical device.surface
- the surface.pRectCount
- a pointer to an integer related to the number of rectangles available or queried, as described below.pRects
- eitherNULL
or a pointer to an array ofVkRect2D
structures.
-
nvkAcquireNextImage2KHR
Unsafe version of:AcquireNextImage2KHR
-
vkAcquireNextImage2KHR
public static int vkAcquireNextImage2KHR(VkDevice device, VkAcquireNextImageInfoKHR pAcquireInfo, IntBuffer pImageIndex) Retrieve the index of the next available presentable image.C Specification
To acquire an available presentable image to use, and retrieve the index of that image, call:
VkResult vkAcquireNextImage2KHR( VkDevice device, const VkAcquireNextImageInfoKHR* pAcquireInfo, uint32_t* pImageIndex);
Description
If the
swapchain
has been created with theSWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
flag, the image whose index is returned inpImageIndex
will be fully backed by memory before this call returns to the application.Valid Usage
- If forward progress cannot be guaranteed for the
surface
used to createswapchain
, thetimeout
member ofpAcquireInfo
must not beUINT64_MAX
Valid Usage (Implicit)
device
must be a validVkDevice
handlepAcquireInfo
must be a valid pointer to a validVkAcquireNextImageInfoKHR
structurepImageIndex
must be a valid pointer to auint32_t
value
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
device
- the device associated withswapchain
.pAcquireInfo
- a pointer to aVkAcquireNextImageInfoKHR
structure containing parameters of the acquire.pImageIndex
- a pointer to auint32_t
that is set to the index of the next image to use.
- If forward progress cannot be guaranteed for the
-
vkCreateSwapchainKHR
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, long[] pSwapchain) Array version of:CreateSwapchainKHR
-
vkGetSwapchainImagesKHR
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, int[] pSwapchainImageCount, @Nullable long[] pSwapchainImages) Array version of:GetSwapchainImagesKHR
-
vkAcquireNextImageKHR
public static int vkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, int[] pImageIndex) Array version of:AcquireNextImageKHR
-
vkGetDeviceGroupSurfacePresentModesKHR
public static int vkGetDeviceGroupSurfacePresentModesKHR(VkDevice device, long surface, int[] pModes) Array version of:GetDeviceGroupSurfacePresentModesKHR
-
vkGetPhysicalDevicePresentRectanglesKHR
public static int vkGetPhysicalDevicePresentRectanglesKHR(VkPhysicalDevice physicalDevice, long surface, int[] pRectCount, @Nullable VkRect2D.Buffer pRects) Array version of:GetPhysicalDevicePresentRectanglesKHR
-
vkAcquireNextImage2KHR
public static int vkAcquireNextImage2KHR(VkDevice device, VkAcquireNextImageInfoKHR pAcquireInfo, int[] pImageIndex) Array version of:AcquireNextImage2KHR
-