Class KHRSwapchain
- java.lang.Object
-
- org.lwjgl.vulkan.KHRSwapchain
-
public class KHRSwapchain extends java.lang.Object
TheVK_KHR_swapchain
extension is the device-level companion to theVK_KHR_surface
extension. It introducesVkSwapchainKHR
objects, which provide the ability to present rendering results to a surface.Examples
Note
The example code for the
VK_KHR_surface
andVK_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).- Name String
VK_KHR_swapchain
- Extension Type
- Device extension
- Registered Extension Number
- 2
- Revision
- 70
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Requires
VK_KHR_surface
- Contact
- James Jones cubanismo
- Ian Elliott ianelliottus
- 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
- Jason Ekstrand, Intel
- Matthaeus G. Chajdas, AMD
- Ray Smith, ARM
-
-
Field Summary
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static 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, java.nio.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, java.nio.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, java.nio.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, java.nio.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, java.nio.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, java.nio.IntBuffer pSwapchainImageCount, java.nio.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 Detail
-
VK_KHR_SWAPCHAIN_SPEC_VERSION
The extension specification version.
-
VK_KHR_SWAPCHAIN_EXTENSION_NAME
The extension name.
-
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR, VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
ExtendsVkStructureType
.Enum values:
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
ExtendsVkImageLayout
.
-
VK_OBJECT_TYPE_SWAPCHAIN_KHR
ExtendsVkObjectType
.
-
VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR, VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR, VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR, VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR, VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR, VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR
ExtendsVkStructureType
.Enum values:
-
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR, VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
ExtendsVkSwapchainCreateFlagBitsKHR
.Enum values:
-
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
VkDeviceGroupPresentModeFlagBitsKHR - 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
VkDeviceGroupPresentInfoKHR
,VkDeviceGroupPresentModeFlagsKHR
-
-
Method Detail
-
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, java.nio.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
If the
oldSwapchain
parameter ofpCreateInfo
is a valid swapchain, which has exclusive full-screen access, that access is released fromoldSwapchain
. If the command succeeds in this case, the newly created swapchain will automatically acquire exclusive full-screen access fromoldSwapchain
.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.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 an instance of theVkSwapchainCreateInfoKHR
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
public static void nvkDestroySwapchainKHR(VkDevice device, long swapchain, long pAllocator)
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 - Both of
device
, andswapchain
that are valid handles must have been created, allocated, or retrieved from the sameVkInstance
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, java.nio.IntBuffer pSwapchainImageCount, @Nullable java.nio.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. IfpSwapchainImageCount
is smaller than the number of presentable images forswapchain
,INCOMPLETE
will be returned instead ofSUCCESS
to indicate that not all the available values 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 - Both of
device
, andswapchain
must have been created, allocated, or retrieved from the sameVkInstance
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, java.nio.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);
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 the number of currently acquired images is greater than the difference between the number of images in
swapchain
and the value ofVkSurfaceCapabilitiesKHR
::minImageCount
as returned by a call toGetPhysicalDeviceSurfaceCapabilities2KHR
with thesurface
used to createswapchain
,timeout
must not beUINT64_MAX
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
value- 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
- Both of
device
, andswapchain
that are valid handles must have been created, allocated, or retrieved from the sameVkInstance
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
that is set to the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR
).
-
nvkQueuePresentKHR
public static int nvkQueuePresentKHR(VkQueue queue, long pPresentInfo)
Unsafe version of:QueuePresentKHR
-
vkQueuePresentKHR
public static int vkQueuePresentKHR(VkQueue queue, VkPresentInfoKHR pPresentInfo)
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 unsignal operation 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 semaphores that are signaled, or have semaphore signal operations previously 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.
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
orERROR_SURFACE_LOST_KHR
, the set of queue operations are still considered to be enqueued and thus any semaphore to be waited on gets unsignaled when the corresponding queue operation is complete.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 Supported Queue Types Pipeline 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 an instance of theVkPresentInfoKHR
structure specifying the 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 a structure of typeVkDeviceGroupPresentCapabilitiesKHR
that is filled with the logical device’s capabilities.
-
nvkGetDeviceGroupSurfacePresentModesKHR
public static int nvkGetDeviceGroupSurfacePresentModesKHR(VkDevice device, long surface, long pModes)
Unsafe version of:GetDeviceGroupSurfacePresentModesKHR
-
vkGetDeviceGroupSurfacePresentModesKHR
public static int vkGetDeviceGroupSurfacePresentModesKHR(VkDevice device, long surface, java.nio.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 (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 a value of typeVkDeviceGroupPresentModeFlagsKHR
that is filled with the supported device group present modes for the surface.
-
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, java.nio.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. IfpRectCount
is smaller than the number of rectangles used for the givensurface
,INCOMPLETE
will be returned instead ofSUCCESS
to indicate that not all the available values 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 (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
public static int nvkAcquireNextImage2KHR(VkDevice device, long pAcquireInfo, long pImageIndex)
Unsafe version of:AcquireNextImage2KHR
-
vkAcquireNextImage2KHR
public static int vkAcquireNextImage2KHR(VkDevice device, VkAcquireNextImageInfoKHR pAcquireInfo, java.nio.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);
Valid Usage
- If the number of currently acquired images is greater than the difference between the number of images in the
swapchain
member ofpAcquireInfo
and the value ofVkSurfaceCapabilitiesKHR
::minImageCount
as returned by a call toGetPhysicalDeviceSurfaceCapabilities2KHR
with thesurface
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 a structure of typeVkAcquireNextImageInfoKHR
containing parameters of the acquire.pImageIndex
- a pointer to auint32_t
that is set to the index of the next image to use.
- If the number of currently acquired images is greater than the difference between the number of images in 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
-
-