Vulkan.Extensions.VK_EXT_present_timing

vkSetSwapchainPresentTimingQueueSizeEXT - Allocate memory for the swapchain-internal timing results queue

Description

If this function is called multiple times, the internal queue is reallocated to fit the new size. If the new size is less than the current number of outstanding results, NOT_READY is returned and no allocation is performed.

Valid Usage

• swapchain must have been created with SwapchainCreateInfoKHR::flags containing SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle

• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• NOT_READY

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_present_timing, Device, SwapchainKHR

vkGetSwapchainTimingPropertiesEXT - Obtain the display timing properties of the PE’s display

Description

If getSwapchainTimingPropertiesEXT returns NOT_READY, the implementation was not able to determine the current refresh cycle duration. Some platforms may not provide timing properties until after at least one image has been presented to the swapchain. If timing properties change for the swapchain, these platforms may not provide updated results until after at least one additional image has been presented to the swapchain.

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle

• pSwapchainTimingProperties must be a valid pointer to a SwapchainTimingPropertiesEXT structure

• If pSwapchainTimingPropertiesCounter is not NULL, pSwapchainTimingPropertiesCounter must be a valid pointer to a uint64_t value

• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• NOT_READY

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_present_timing, Device, SwapchainKHR, SwapchainTimingPropertiesEXT

vkGetSwapchainTimeDomainPropertiesEXT - Obtain the time domains supported by the PE for the swapchain

Description

If upon return SwapchainTimeDomainPropertiesEXT::timeDomainCount is smaller than the number of time domains supported for the given swapchain, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle

• pSwapchainTimeDomainProperties must be a valid pointer to a SwapchainTimeDomainPropertiesEXT structure

• If pTimeDomainsCounter is not NULL, pTimeDomainsCounter must be a valid pointer to a uint64_t value

• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• INCOMPLETE

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_present_timing, Device, SwapchainKHR, SwapchainTimeDomainPropertiesEXT

vkGetPastPresentationTimingEXT - Obtain timing of previously-presented images

Description

If upon return the value of PastPresentationTimingPropertiesEXT::presentationTimingCount is less than the number of available timing records for the given PastPresentationTimingInfoEXT::swapchain, INCOMPLETE is returned instead of SUCCESS to indicate that not all the available values were returned.

Upon return, zero or more slots of the swapchain internal timing results queue, equal to the number of entries written to PastPresentationTimingPropertiesEXT::pPresentationTimings for which reportComplete is TRUE, are made available for future queuePresentKHR calls. Elements of pPresentationTimings are arranged in ascending order of present ids.

Timing information may become available out of order with regards to their associated queuePresentKHR order. PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT can be set in PastPresentationTimingInfoEXT::flags to allow getPastPresentationTimingEXT to return results in that same order. Otherwise, results are returned in the order of their associated queuePresentKHR calls.

There is no requirement for any precise timing relationship between the completion of a present stage and the availability of any associated timing information. However, results must be made available in finite time.

As an exception to the normal rules for objects which are externally synchronized, swapchain may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR and createSwapchainKHR with swapchain used as an oldSwapchain. Access to the swapchain timing information must be atomic within the implementation.

Valid Usage

• If PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT is set in PastPresentationTimingInfoEXT::flags, the presentStageCount value of each element of PastPresentationTimingPropertiesEXT::pPresentationTimings must be at least the maximum number of present stages set in PresentTimingInfoEXT::presentStageQueries among all queuePresentKHR calls, with a non-zero presentStageQueries, for which complete results have not been returned yet by a previous call

• If PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT is not set in PastPresentationTimingInfoEXT::flags, the presentStageCount value of each element of PastPresentationTimingPropertiesEXT::pPresentationTimings must be at least the number of present stages set in PresentTimingInfoEXT::presentStageQueries for the earliest call to queuePresentKHR, with a non-zero presentStageQueries, that corresponds to that element’s index and for which complete results have not been returned yet by a previous call

Valid Usage (Implicit)

• device must be a valid Device handle

• pPastPresentationTimingInfo must be a valid pointer to a valid PastPresentationTimingInfoEXT structure

• pPastPresentationTimingProperties must be a valid pointer to a PastPresentationTimingPropertiesEXT structure

Return Codes

Success

• INCOMPLETE

• SUCCESS

Failure

• ERROR_DEVICE_LOST

• ERROR_OUT_OF_DATE_KHR

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_EXT_present_timing, Device, PastPresentationTimingInfoEXT, PastPresentationTimingPropertiesEXT

VkPhysicalDevicePresentTimingFeaturesEXT - Structure indicating support for present timing

Members

This structure describes the following feature:

Description

If the PhysicalDevicePresentTimingFeaturesEXT structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDevicePresentTimingFeaturesEXT, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_EXT_present_timing, Bool32, StructureType

VkPresentTimingSurfaceCapabilitiesEXT - Structure describing present timing capabilities of a surface

Description

If presentTimingSupported is TRUE, the implementation must also advertise support for at least the PRESENT_STAGE_QUEUE_OPERATIONS_END_BIT_EXT present stage in pname presentStageQueries.

Structure Chaining

Extends the structure

• SurfaceCapabilities2KHR

See Also

VK_EXT_present_timing, Bool32, PresentStageFlagsEXT, StructureType

VkSwapchainTimingPropertiesEXT - Structure containing the RC duration of a display

Description

If refreshDuration is zero, the presentation engine is not able to determine the duration of the refresh cycle. Similarly, if refreshInterval is zero, the presentation engine is not able to determine whether it is operating in VRR mode.

Otherwise, if refreshInterval is the same as refreshDuration, the presentation engine is operating in FRR mode. In this case, refreshDuration is the number of nanoseconds from the start of one refresh cycle to the start of the next refresh cycle.

If refreshInterval is UINT64_MAX, the presentation engine is operating in VRR mode, and refreshDuration is the minimum number of nanoseconds from the start of one refresh cycle to the start of the next refresh cycle.

If refreshDuration and refreshInterval are not zero, refreshInterval is a factor of refreshDuration.

Valid Usage (Implicit)

See Also

VK_EXT_present_timing, StructureType, getSwapchainTimingPropertiesEXT

VkSwapchainTimeDomainPropertiesEXT - List of available time domains for a swapchain

Description

When calling getSwapchainTimeDomainPropertiesEXT, if pTimeDomains is NULL and pTimeDomainIds is NULL, then the number of time domains supported for the given swapchain is returned in timeDomainCount. Otherwise, timeDomainCount must specify the number of elements in pTimeDomains and pTimeDomainIds, and on return is overwritten with the number of values actually written to each array.

Implementations must advertise support for at least one time domain of TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT.

Due to the dynamic nature of their underlying SurfaceKHR properties, swapchains may need to expose multiple swapchain-local opaque time domains using the same TimeDomainKHR value over time, for example when a surface is moved from one display hardware to another. Arbitrary identifiers, provided in timeDomainIds, are used by the implementation to differentiate opaque time domains of identical scopes.

Valid Usage

• pTimeDomains and pTimeDomainIds must both be NULL or both not be NULL

• If pTimeDomains and pTimeDomainIds are not NULL, then timeDomainCount must not be zero

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_TIME_DOMAIN_PROPERTIES_EXT

• pNext must be NULL

See Also

VK_EXT_present_timing, StructureType, TimeDomainKHR, getSwapchainTimeDomainPropertiesEXT

VkPresentStageTimeEXT - Associate a present stage with a timestamp

See Also

VK_EXT_present_timing, PastPresentationTimingEXT, PresentStageFlagsEXT

VkPastPresentationTimingInfoEXT - Structure specifying swapchain present timing query parameters

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PAST_PRESENTATION_TIMING_INFO_EXT

• pNext must be NULL

• flags must be a valid combination of PastPresentationTimingFlagBitsEXT values

• swapchain must be a valid SwapchainKHR handle

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

VK_EXT_present_timing, PastPresentationTimingFlagsEXT, StructureType, SwapchainKHR, getPastPresentationTimingEXT

VkPastPresentationTimingPropertiesEXT - Structure containing details about a swapchain past presentation activity

Description

When calling getPastPresentationTimingEXT, if pPresentationTimings is NULL, then the number of available timing records for the given swapchain is returned in presentationTimingCount. Otherwise, presentationTimingCount must specify the number of elements in the pPresentationTimings array, and on return is overwritten with the number of structures actually written to pPresentationTimings.

if PAST_PRESENTATION_TIMING_ALLOW_PARTIAL_RESULTS_BIT_EXT is specified in PastPresentationTimingInfoEXT::flags, getPastPresentationTimingEXT may return incomplete results, containing only information for a subset of the requested present stages. Further calls to getPastPresentationTimingEXT will keep providing all available results for a previously incomplete entry until it is complete.

The implementation must return a PastPresentationTimingEXT for every queuePresentKHR referencing swapchain where a non-zero PresentTimingInfoEXT::presentStageQueries was specified and at least one present stage has available results.

Valid Usage (Implicit)

See Also

VK_EXT_present_timing, PastPresentationTimingEXT, StructureType, getPastPresentationTimingEXT

VkPastPresentationTimingEXT - Structure containing timing information about a previously-presented image

Description

When calling getPastPresentationTimingEXT, the implementation sets presentStageCount to the number of present stages it has written results for. If PAST_PRESENTATION_TIMING_ALLOW_PARTIAL_RESULTS_BIT_EXT was specified in PastPresentationTimingInfoEXT::flags, the implementation may return an incomplete report containing fewer present stage results than were queried by the associated presentation request. Otherwise, results for all the present stages queried by the presentation request are written by the implementation.

Timing information for some present stages may have a time value of 0, indicating that results for that present stage are not available.

For systems with multiple entities operating within the presentation engine, such as multiple displays, pPresentStages will return timing results for one entity which has been affected by the presentation.

timeDomainId may be different than the time domain that was specified in PresentTimingInfoEXT::timeDomainId if the requirements for using this time domain could not be met at the time the presentation engine processed the presentation request. In such a case, the presentation engine may pick a time domain to fall back to, if one is available, and report results in that domain. Applications can continue to use this fallback time domain in future queuePresentKHR calls, or they can call getSwapchainTimeDomainPropertiesEXT to choose from the currently supported time domains.

Valid Usage (Implicit)

See Also

VK_EXT_present_timing, Bool32, PastPresentationTimingPropertiesEXT, PresentStageTimeEXT, StructureType, TimeDomainKHR

VkPresentTimingsInfoEXT - Array of VkPresentTimingInfoEXT to chain with VkPresentInfoKHR

Valid Usage

• swapchainCount must be equal to PresentInfoKHR::swapchainCount

• All swapchains in PresentInfoKHR::pSwapchains must have been created with the SwapchainCreateInfoKHR::flags field containing SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT

• For each member of PresentInfoKHR::pSwapchains, if the associated PresentTimingInfoEXT::targetTime is not zero, the swapchain’s current present mode must be PRESENT_MODE_FIFO_LATEST_READY_KHR, PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PRESENT_TIMINGS_INFO_EXT

• If pTimingInfos is not NULL, pTimingInfos must be a valid pointer to an array of swapchainCount valid PresentTimingInfoEXT structures

• swapchainCount must be greater than 0

Structure Chaining

Extends the structure

• PresentInfoKHR

See Also

VK_EXT_present_timing, PresentTimingInfoEXT, StructureType

VkPresentTimingInfoEXT - Specifies per-present timing information

Description

If targetTime is not zero, the implementation attempts to align the PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage of that presentation request with the time specified in targetTime according to the time domain used. If PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT is not set in flags, it indicates that the application would strictly prefer the image to not be visible before targetTime has lapsed.

If targetTime is not zero and timeDomainId is associated with a TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT time domain, targetTimeDomainPresentStage is used to specify which present stage’s time domain targetTime is specified for. Otherwise, targetTimeDomainPresentStage is ignored.

If presentStageQueries is not zero, a slot in the swapchain’s internal results queue is reserved to hold the requested present timing data until the application retrieves them. If no slots are available, presentation fails and returns ERROR_PRESENT_TIMING_QUEUE_FULL_EXT.

Some platforms, due to hardware or system limitations, may not be able to accurately time targetTime with the actual physical event of the image becoming visible on the display. However, those timing capabilities may still be useful and result in improved animation quality.

As such, the presentAtAbsoluteTime and presentAtRelativeTime features do not provide a strict guarantee regarding the completion of the PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage relative to the targetTime, and implementations must strive to make it as consistent and accurate as possible.

Applications that specify an absolute present time should regularly rebase their calculations for their next target time on the feedback from getPastPresentationTimingEXT to compensate for accumulated precision errors or potential clock drift. It is recommended that when targeting the time of a vertical blanking period, applications set PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT to allow the implementation to compensate for small precision errors that may cause an image to be displayed one refresh cycle later than intended.

Some implementations may not provide timing data for the PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage. Applications should use the supported present stage nearest to it to compute a desired target presentation time.

Valid Usage

• If targetTime is not zero and flags does not contain PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the presentAtAbsoluteTime feature must be enabled and the presentAtAbsoluteTimeSupported member of the PresentTimingSurfaceCapabilitiesEXT returned by getPhysicalDeviceSurfaceCapabilities2KHR for the surface associated with the swapchain must be TRUE

• If targetTime is not zero and flags contains PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the presentAtRelativeTime feature must be enabled and the presentAtRelativeTimeSupported member of the PresentTimingSurfaceCapabilitiesEXT returned by getPhysicalDeviceSurfaceCapabilities2KHR for the surface associated with the swapchain must be TRUE

• If timeDomainId is associated with a TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT time domain, and targetTime is not zero, targetTimeDomainPresentStage must be a single PresentStageFlagsEXT value

• timeDomainId must be an id previously returned by getSwapchainTimeDomainPropertiesEXT

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PRESENT_TIMING_INFO_EXT

• pNext must be NULL

• flags must be a valid combination of PresentTimingInfoFlagBitsEXT values

• presentStageQueries must be a valid combination of PresentStageFlagBitsEXT values

• targetTimeDomainPresentStage must be a valid combination of PresentStageFlagBitsEXT values

See Also

VK_EXT_present_timing, PresentStageFlagsEXT, PresentTimingInfoFlagsEXT, PresentTimingsInfoEXT, StructureType

VkSwapchainCalibratedTimestampInfoEXT - Structure specifying the swapchain to calibrate a swapchain-local timestamp query

Description

timeDomainId must be an id previously reported by getSwapchainTimeDomainPropertiesEXT for swapchain. If the timeDomainId is no longer supported by the swapchain, implementations may report zero as the calibrated timestamp value.

Valid Usage

• If the timeDomain member of the CalibratedTimestampInfoKHR structure in this structure’s pNext chain is TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT, presentStage must specify one and only one present stage

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_CALIBRATED_TIMESTAMP_INFO_EXT

• swapchain must be a valid SwapchainKHR handle

• presentStage must be a valid combination of PresentStageFlagBitsEXT values

Structure Chaining

Extends the structure

• CalibratedTimestampInfoKHR

See Also

VK_EXT_present_timing, PresentStageFlagsEXT, StructureType, SwapchainKHR

VkTimeDomainKHR - Supported time domains

Description

• TIME_DOMAIN_DEVICE_KHR specifies the device time domain. Timestamp values in this time domain use the same units and are comparable with device timestamp values captured using cmdWriteTimestamp or cmdWriteTimestamp2 and are defined to be incrementing according to the timestampPeriod of the device.

• TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT specifies a time domain unique to a particular swapchain and a specific present stage. Timestamp values in this time domain are in units of nanosecond and are comparable only with other values from the same swapchain and present stage.

• TIME_DOMAIN_SWAPCHAIN_LOCAL_EXT specifies a time domain unique to a particular swapchain. Timestamp values in this time domain are in units of nanosecond and are comparable only with other values from the same swapchain.

• TIME_DOMAIN_CLOCK_MONOTONIC_KHR specifies the CLOCK_MONOTONIC time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX clock_gettime API as computed by this example:

An implementation supporting VK_KHR_calibrated_timestamps or VK_EXT_calibrated_timestamps will use the same time domain for all its Queue so that timestamp values reported for TIME_DOMAIN_DEVICE_KHR can be matched to any timestamp captured through cmdWriteTimestamp or cmdWriteTimestamp2 .

struct timespec tv;
clock_gettime(CLOCK_MONOTONIC, &tv);
return tv.tv_nsec + tv.tv_sec*1000000000ull;

• TIME_DOMAIN_CLOCK_MONOTONIC_RAW_KHR specifies the CLOCK_MONOTONIC_RAW time domain available on POSIX platforms. Timestamp values in this time domain are in units of nanoseconds and are comparable with platform timestamp values captured using the POSIX clock_gettime API as computed by this example:

struct timespec tv;
clock_gettime(CLOCK_MONOTONIC_RAW, &tv);
return tv.tv_nsec + tv.tv_sec*1000000000ull;

• TIME_DOMAIN_QUERY_PERFORMANCE_COUNTER_KHR specifies the performance counter (QPC) time domain available on Windows. Timestamp values in this time domain are in the same units as those provided by the Windows QueryPerformanceCounter API and are comparable with platform timestamp values captured using that API as computed by this example:

LARGE_INTEGER counter;
QueryPerformanceCounter(&counter);
return counter.QuadPart;

See Also

VK_EXT_calibrated_timestamps, VK_KHR_calibrated_timestamps, CalibratedTimestampInfoKHR, PastPresentationTimingEXT, SwapchainTimeDomainPropertiesEXT, getPhysicalDeviceCalibrateableTimeDomainsKHR, getPhysicalDeviceCalibrateableTimeDomainsKHR

VkPresentStageFlagBitsEXT - Bitmask specifying stages of the image presentation process

Description

• PRESENT_STAGE_QUEUE_OPERATIONS_END_BIT_EXT marks the end of the set of queue operations enqueued by queuePresentKHR on the provided Queue for a presentation request.

• PRESENT_STAGE_REQUEST_DEQUEUED_BIT_EXT is the stage after which the presentation request has been dequeued from the swapchain’s internal presentation request queue, if any, as specified by the present mode associated with that request.

• PRESENT_STAGE_IMAGE_FIRST_PIXEL_OUT_BIT_EXT is the stage after which data for the first pixel of the presentation request associated with the image has left the presentation engine for a display hardware.

• PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT is the stage after which a display hardware has made the first pixel visible for the presentation request associated with the image to be presented.

The set of queue operations delimited by PRESENT_STAGE_QUEUE_OPERATIONS_END_BIT_EXT includes the wait for the semaphores specified in PresentInfoKHR::pWaitSemaphores, if any, and any work implicitly enqueued by the implementation.

See Also

VK_EXT_present_timing, PresentStageFlagsEXT

VkPastPresentationTimingFlagBitsEXT - Bitmask specifying past presentation timing query flags

Description

• PAST_PRESENTATION_TIMING_ALLOW_PARTIAL_RESULTS_BIT_EXT specifies that getPastPresentationTimingEXT may return partial results for presentation requests that have not completed all requested present stages.

• PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT specifies that getPastPresentationTimingEXT may return results out of order with respect to the presentation order.

See Also

VK_EXT_present_timing, PastPresentationTimingFlagsEXT

VkPresentTimingInfoFlagBitsEXT - Bitmask specifying present timing info flags

Description

• PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT specifies that PresentTimingInfoEXT::targetTime is to be interpreted as a relative time from the previous presentation’s PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT stage. If the swapchain has never been used to present an image, the provided targetTime is ignored.

• PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT specifies that the application would prefer the image to be presented earlier than the time specified in PresentTimingInfoEXT::targetTime if that time falls within the first half of a refresh cycle. In that case, the presentation engine may choose to display the image at the start of that refresh cycle.

See Also

VK_EXT_present_timing, PresentTimingInfoFlagsEXT

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image 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 non-retired 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 display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

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 released by queuePresentKHR. 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 with queuePresentKHR, which releases the acquisition of the image. The application can also release the acquisition of the image through releaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.

The presentation engine controls the order in which presentable images are acquired for use by the application.

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.

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PastPresentationTimingInfoEXT, PresentInfoKHR, ReleaseSwapchainImagesInfoKHR, SwapchainCalibratedTimestampInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, getSwapchainTimeDomainPropertiesEXT, getSwapchainTimingPropertiesEXT, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, setSwapchainPresentTimingQueueSizeEXT, waitForPresent2KHR, waitForPresentKHR

VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

Description

• SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies that images created from the swapchain (i.e. with the swapchain member of ImageSwapchainCreateInfoKHR set to this swapchain’s handle) must use IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.

• SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images created from the swapchain are protected images.

• SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the images of the swapchain can be used to create a ImageView with a different format than what the swapchain was created with. The list of allowed image view formats is specified by adding a ImageFormatListCreateInfo structure to the pNext chain of SwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats.

• SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR specifies that the implementation may defer allocation of memory associated with each swapchain image until its index is to be returned from acquireNextImageKHR or acquireNextImage2KHR for the first time.

• SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHR specifies that applications can include the PresentId2KHR structure in the pNext chain of the PresentInfoKHR structure to associate an identifier with each presentation request.

• SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR specifies that applications can use waitForPresent2KHR to wait for the presentation engine to have begun presentation of the presentation request associated with PresentWait2InfoKHR::presentId on swapchain.

• SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT specifies that features supported by the swapchain device in PhysicalDevicePresentTimingFeaturesEXT can be used to collect timing information or schedule presentation requests at specific times.

See Also

VK_KHR_swapchain, SwapchainCreateFlagsKHR