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.
-
-
Field Summary
Fields Modifier and Type Field and Description static int
VK_ERROR_OUT_OF_DATE_KHR
A surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail.static int
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
must only be used for presenting a swapchain image for display.static java.lang.String
VK_KHR_SWAPCHAIN_EXTENSION_NAME
The extension name.static int
VK_KHR_SWAPCHAIN_SPEC_VERSION
The extension specification version.static int
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHRVkStructureTypestatic int
VK_SUBOPTIMAL_KHR
A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description 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)
Acquires an available presentable image to use, and retrieves the index of that 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)
Creates a swapchain.static void
vkDestroySwapchainKHR(VkDevice device, long swapchain, VkAllocationCallbacks pAllocator)
Destroys a swapchain object.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)
Obtains the array of presentable images associated with a swapchain.static int
vkQueuePresentKHR(VkQueue queue, VkPresentInfoKHR pPresentInfo)
Queues an image for presentation.
-
-
-
Field Detail
-
VK_KHR_SWAPCHAIN_SPEC_VERSION
public static final int VK_KHR_SWAPCHAIN_SPEC_VERSION
The extension specification version.- See Also:
- Constant Field Values
-
VK_KHR_SWAPCHAIN_EXTENSION_NAME
public static final java.lang.String VK_KHR_SWAPCHAIN_EXTENSION_NAME
The extension name.- See Also:
- Constant Field Values
-
VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
public static final int VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
VkStructureType- See Also:
- Constant Field Values
-
VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
public static final int VK_STRUCTURE_TYPE_PRESENT_INFO_KHR
VkStructureType- See Also:
- Constant Field Values
-
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
public static final int VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
must only be used for presenting a swapchain image for display. A swapchain’s image must be transitioned to this layout before callingQueuePresentKHR
, and must be transitioned away from this layout after callingAcquireNextImageKHR
.- See Also:
- Constant Field Values
-
VK_SUBOPTIMAL_KHR
public static final int VK_SUBOPTIMAL_KHR
A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.- See Also:
- Constant Field Values
-
VK_ERROR_OUT_OF_DATE_KHR
public static final int VK_ERROR_OUT_OF_DATE_KHR
A surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface.- See Also:
- Constant Field Values
-
-
Method Detail
-
vkCreateSwapchainKHR
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pSwapchain)
Creates a swapchain.A
VkSwapchainKHR
object (a.k.a. swapchain) provides the ability to present rendering results to a surface. A swapchain is an abstraction for an array of presentable images that are associated with a surface. The swapchain images are represented byVkImage
objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface. A native window cannot be associated with more than one swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.The presentation engine is an abstraction for the platform’s compositor or hardware/software display engine.
The presentation engine may: be synchronous or asynchronous with respect to the application and/or logical device.
Note
Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.
The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by
AcquireNextImageKHR
, and before it is presented byQueuePresentKHR
. This includes transitioning the image layout and rendering commands.An application can acquire use of a presentable image with
AcquireNextImageKHR
. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image's layout, queue rendering commands to it, etc. Finally, the application presents the image withQueuePresentKHR
, which releases the acquisition of the image.The presentation engine controls the order in which presentable images are acquired for use by the application.
Note
This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.
Valid Usage
device
must be a validVkDevice
handlepCreateInfo
must be a pointer to a validVkSwapchainCreateInfoKHR
structure- If
pAllocator
is notNULL
,pAllocator
must be a pointer to a validVkAllocationCallbacks
structure pSwapchain
must be a pointer to aVkSwapchainKHR
handle
Host Synchronization
- Host access to
pCreateInfo.surface
must be externally synchronized - Host access to
pCreateInfo.oldSwapchain
must be externally synchronized
If
vkCreateSwapchainKHR
succeeds, it will return a handle to a swapchain that contains an array of at leastminImageCount
presentable images.The
VkSurfaceKHR
associated with a swapchain must not be destroyed until after the swapchain is destroyed.Like core functions, several WSI fuctions, including
vkCreateSwapchainKHR
returnERROR_DEVICE_LOST
if the logical device was lost. As with most core objects,VkSwapchainKHR
is a child of the device and is affected by the lost state; it must be destroyed before destroying theVkDevice
. However,VkSurfaceKHR
is not a child of anyVkDevice
and is not otherwise affected by the lost device. After successfully recreating aVkDevice
, the sameVkSurfaceKHR
can be used to create a newVkSwapchainKHR
, provided the previous one was destroyed.Note
After a lost device event, the
VkPhysicalDevice
may also be lost. If otherVkPhysicalDevice
are available, they can be used together with the sameVkSurfaceKHR
to create the newVkSwapchainKHR
, however the application must query the surface capabilities again, because they may differ on a per-physical device basis.- Parameters:
device
- the device to create the swapchain forpCreateInfo
- a pointer to an instance of theVkSwapchainCreateInfoKHR
structure specifying the parameters of the created swapchainpAllocator
- controls host memory allocationpSwapchain
- a pointer to aVkSwapchainKHR
handle in which the created swapchain object will be returned
-
vkDestroySwapchainKHR
public static void vkDestroySwapchainKHR(VkDevice device, long swapchain, VkAllocationCallbacks pAllocator)
Destroys a swapchain object.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 platform. 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.Valid Usage
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 pointer to a validVkAllocationCallbacks
structure - Each of
swapchain
anddevice
that are valid handles must have been created, allocated or retrieved from the sameVkInstance
- 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
Host Synchronization
- Host access to
swapchain
must be externally synchronized
- Parameters:
device
- theVkDevice
associated with the swapchainswapchain
- the swapchain to destroypAllocator
- controls host memory allocation
-
vkGetSwapchainImagesKHR
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, java.nio.IntBuffer pSwapchainImageCount, java.nio.LongBuffer pSwapchainImages)
Obtains the array of presentable images associated with a swapchain.If
pSwapchainImages
isNULL
, then the number of presentable images for swapchain 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
device
must be a validVkDevice
handleswapchain
must be a validVkSwapchainKHR
handlepSwapchainImageCount
must be a pointer to auint32_t
value- If the value referenced by
pSwapchainImageCount
is not 0, andpSwapchainImages
is notNULL
,pSwapchainImages
must be a pointer to an array ofpSwapchainImageCount
VkImage
handles - Each of
swapchain
anddevice
must have been created, allocated or retrieved from the sameVkInstance
Note
By knowing all presentable images used in the swapchain, the application can create command buffers that reference these images prior to entering its main rendering loop.
The implementation will have already allocated and bound the memory backing the
VkImages
returned byvkGetSwapchainImagesKHR
. The memory for each image will not alias with the memory for other images or with anyVkDeviceMemory
object. As such, performing any operation affecting the binding of memory to a presentable image results in undefined behavior. All presentable images are initially in theIMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must transition them to a valid layout for the intended use.Further, the lifetime of presentable images is controlled by the implementation so destroying a presentable image with
DestroyImage
results in undefined behavior. SeeDestroySwapchainKHR
for further details on the lifetime of presentable images.- Parameters:
device
- the device associated withswapchain
swapchain
- the swapchain to querypSwapchainImageCount
- a pointer to an integer related to the number of format pairs available or queriedpSwapchainImages
- eitherNULL
or a pointer to an array ofVkSwapchainImageKHR
structures
-
vkAcquireNextImageKHR
public static int vkAcquireNextImageKHR(VkDevice device, long swapchain, long timeout, long semaphore, long fence, java.nio.IntBuffer pImageIndex)
Acquires an available presentable image to use, and retrieves the index of that image.Valid Usage
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 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
- Each of
swapchain
,device
,semaphore
andfence
that are valid handles must have been created, allocated or retrieved from the sameVkInstance
- If
semaphore
is notNULL_HANDLE
it must be unsignaled - 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
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
When successful,
vkAcquireNextImageKHR
acquires a presentable image that the application can use, and setspImageIndex
to the index of that image. The presentation engine may not have finished reading from the image at the time it is acquired, so the application must usesemaphore
and/orfence
to ensure that the image layout and contents are not modified until the presentation engine reads have completed.The presentation engine controls the order in which presentable images are made available to the application. This allows the platform to handle special situations. The order in which images are acquired is implementation-dependent. Images may be acquired in a seemingly random order that is not a simple round-robin.
If a swapchain has enough presentable images, applications can acquire multiple images without an intervening
QueuePresentKHR
. Applications can present images in a different order than the order in which they were acquired.If
timeout
is 0,vkAcquireNextImageKHR
will not block, but will either succeed or returnNOT_READY
. Iftimeout
isUINT64_MAX
, the function will not return until an image is acquired from the presentation engine. Other values fortimeout
will cause the function to return when an image becomes available, or when the specified number of nanoseconds have passed (in which case it will returnTIMEOUT
). An error can also causevkAcquireNextImageKHR
to return early.Note
As mentioned above, the presentation engine may be asynchronous with respect to the application and/or logical device.
vkAcquireNextImageKHR
may return as soon as it can identify which image will be acquired, and can guarantee thatsemaphore
andfence
will be signaled by the presentation engine; and may not successfully return sooner. The application usestimeout
to specify how longvkAcquireNextImageKHR
waits for an image to become acquired.Applications cannot rely on
vkAcquireNextImageKHR
blocking in order to meter their rendering speed. Various factors can interruptvkAcquireNextImageKHR
from blocking.Note
For example, if an error occurs,
vkAcquireNextImageKHR
may return even though no image is available. As another example, some presentation engines are able to enqueue an unbounded number of presentation and acquire next image operations such thatvkAcquireNextImageKHR
never needs to wait for completion of outstanding present operations before returning.The availability of presentable images is influenced by factors such as the implementation of the presentation engine, the
VkPresentModeKHR
being used, the number of images in the swapchain, the number of images that the application has acquired at any given time, and the performance of the application. The value ofVkSurfaceCapabilitiesKHR
::minImageCount
indicates how many images must be in the swapchain in order forvkAcquireNextImageKHR
to acquire an image if the application currently has no acquired images.Let
n
be the total number of images in the swapchain,m
be the value ofVkSurfaceCapabilitiesKHR
::minImageCount
, anda
be the number of presentable images that the application has currently acquired (i.e. images acquired withvkAcquireNextImageKH
R, but not yet presented withQueuePresentKHR
).vkAcquireNextImageKHR
can always succeed ifa <= n - m
at the timevkAcquireNextImageKHR
is called.vkAcquireNextImageKHR
must not be called whena > n - m
; in such a case, and iftimeout
isUINT64_MAX
,vkAcquireNextImageKHR
may block indefinitely.Note
For example, if the
minImageCount
member ofVkSurfaceCapabilitiesKHR
is 2, and the application creates a swapchain with 2 presentable images, the application can: acquire one image, and must present it before trying to acquire another image.If we modify this example so that the application wishes to acquire up to 3 presentable images simultaneously, it must request a minimum image count of 4 when creating the swapchain.
If
semaphore
is notNULL_HANDLE
, the semaphore must be unsignaled and not have any uncompleted signal or wait operations pending. It will become signaled when the application can use the image. Queue operations that access the image contents must wait until the semaphore signals; typically applications should: include the semaphore in thepWaitSemaphores
list for the queue submission that transitions the image away from theIMAGE_LAYOUT_PRESENT_SRC_KHR
layout. Use of the semaphore allows rendering operations to be recorded and submitted before the presentation engine has completed its use of the image.If
fence
is not equal toNULL_HANDLE
, the fence must be unsignaled and not have any uncompleted signal operations pending. It will become signaled when the application can use the image. Applications can use this to meter their frame generation work to match the presentation rate.semaphore
andfence
must not both be equal toNULL_HANDLE
. An application must wait until either thesemaphore
orfence
is signaled before using the presentable image.semaphore
andfence
may already be signaled whenvkAcquireNextImageKHR
returns, if the image is being acquired for the first time, or if the presentable image is immediately ready for use.A successful call to
vkAcquireNextImageKHR
counts as a signal operation on semaphore for the purposes of queue forward-progress requirements. The semaphore is guaranteed to signal, so a wait operation can be queued for the semaphore without risk of deadlock.The
CmdWaitEvents
orCmdPipelineBarrier
used to transition the image away fromIMAGE_LAYOUT_PRESENT_SRC_KHR
layout must havedstStageMask
anddstAccessMask
parameters set based on the next use of the image. ThesrcAccessMask
must includeACCESS_MEMORY_READ_BIT
to ensure that all prior reads by the presentation engine are complete before the image layout transition occurs. The application must use implicit ordering guarantees and execution dependencies to prevent the image transition from occurring before the semaphore passed tovkAcquireNextImageKHR
has signaled.Note
When the swapchain image will be written by some stage
S
, the recommended idiom for ensuring the semaphore signals before the transition occurs is:- The batch that contains the transition includes the image-acquire semaphore in the list of semaphores to wait for, with a wait stage mask that
includes
S
. - The pipeline barrier that performs the transition includes
S
in both thesrcStageMask
anddstStageMask
.
This causes the pipeline barrer to wait at
S
until the semaphore signals before performing the transition and memory barrier, while allowing earlier pipeline stages of subsequent commands to proceed.After a successful return, the image indicated by
pImageIndex
will still be in theIMAGE_LAYOUT_PRESENT_SRC_KHR
layout if it was previously presented, or in theIMAGE_LAYOUT_UNDEFINED
layout if this is the first time it has been acquired.The possible return values for
vkAcquireNextImageKHR
depend on the timeout provided:SUCCESS
is returned if an image became available.ERROR_SURFACE_LOST_KHR
if the surface becomes no longer available.NOT_READY
is returned iftimeout
is zero and no image was available.TIMEOUT
is returned iftimeout
is greater than zero and less thanUINT64_MAX
, and no image became available within the time allowed.SUBOPTIMAL_KHR
is returned if an image became available, and the swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.Note
This may happen, for example, if the platform surface has been resized but the platform is able to scale the presented images to the new size to produce valid surface updates. It is up to applications to decide whether they prefer to continue using the current swapchain indefinitely or temporarily in this state, or to re-create the swapchain to better match the platform surface properties.
ERROR_OUT_OF_DATE_KHR
is returned if the surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface.
If the native surface and presented image sizes no longer match, presentation may not succeed. If presentation does succeed, parts of the native surface may be undefined, parts of the presented image may have been clipped before presentation, and/or the image may have been scaled (uniformly or not uniformly) before presentation. It is the application’s responsibility to detect surface size changes and react appropriately. If presentation does not succeed because of a mismatch in the surface and presented image sizes, a
ERROR_OUT_OF_DATE_KHR
error will be returned.Before an application can present an image, the image’s layout must be transitioned to the
IMAGE_LAYOUT_PRESENT_SRC_KHR
layout. TheCmdWaitEvents
orCmdPipelineBarrier
that perform the transition must havesrcStageMask
andsrcAccessMask
parameters set based on the preceding use of the image. ThedstAccessMask
must includeACCESS_MEMORY_READ_BIT
indicating all prior accesses indicated insrcAccessMask
from stages insrcStageMask
are to be made available to reads by the presentation engine. Any value ofdstStageMask
is valid, but should be set toPIPELINE_STAGE_BOTTOM_OF_PIPE_BIT
to avoid delaying subsequent commands that don’t access the image.- Parameters:
device
- the device assocated withswapchain
swapchain
- the swapchain from which an image is being acquiredtimeout
- indicates how long the function waits, in nanoseconds, if no image is availablesemaphore
- isNULL_HANDLE
or a semaphore to signalfence
- isNULL_HANDLE
or a fence to signalpImageIndex
- 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 byGetSwapchainImagesKHR
).
-
vkQueuePresentKHR
public static int vkQueuePresentKHR(VkQueue queue, VkPresentInfoKHR pPresentInfo)
Queues an image for presentation.Valid Usage
queue
must be a validVkQueue
handlepPresentInfo
must be a pointer to a validVkPresentInfoKHR
structure- Any given 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 toGetPhysicalDeviceSurfaceSupportKHR
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
vkQueuePresentKH
R, releases the acquisition of the images referenced byimageIndices
. A presented images must not be used again before it has been reacquired usingAcquireNextImageKHR
.The processing of the presentation happens in issue order with other queue operations, but semaphores have to be used to ensure that prior rendering and other commands in the specified queue complete before the presentation begins. The presentation command itself does not delay processing of subsequent commands on the queue, however, presentation requests sent to a particular queue are always performed in order. Exact presentation timing is controled by the semantics of the presentation engine and native platform in use.
The result codes
ERROR_OUT_OF_DATE_KHR
andSUBOPTIMAL_KHR
have the same meaning when returned byvkQueuePresentKHR
as they do when returned byAcquireNextImageKHR
. If multiple swapchains are presented, the result code is determined applying the following rules in order:- If the device is lost,
ERROR_DEVICE_LOST
is returned. - If any of the target surfaces are no longer available the error
ERROR_SURFACE_LOST_KHR
is returned. - If any of the presents would have a result of
ERROR_OUT_OF_DATE_KHR
if issued separately thenERROR_OUT_OF_DATE_KHR
is returned. - If any of the presents would have a result of
SUBOPTIMAL_KHR
if issued separately thenSUBOPTIMAL_KHR
is returned. - Otherwise
SUCCESS
is returned.
Presentation is a read-only operation that will not affect the content of the presentable images. Upon reacquiring the image and transitioning it away from the
IMAGE_LAYOUT_PRESENT_SRC_KHR
layout, the contents will be the same as they were prior to transitioning the image to the present source layout and presenting it. However, if a mechanism other than Vulkan is used to modify the platform window associated with the swapchain, the content of all presentable images in the swapchain becomes undefined.- Parameters:
queue
- a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchainpPresentInfo
- a pointer to an instance of theVkPresentInfoKHR
structure specifying the parameters of the presentation
-
vkCreateSwapchainKHR
public static int vkCreateSwapchainKHR(VkDevice device, VkSwapchainCreateInfoKHR pCreateInfo, VkAllocationCallbacks pAllocator, long[] pSwapchain)
Array version of:CreateSwapchainKHR
-
vkGetSwapchainImagesKHR
public static int vkGetSwapchainImagesKHR(VkDevice device, long swapchain, int[] pSwapchainImageCount, 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
-
-