vkSetLatencySleepModeNV - Enable or Disable low latency mode on a swapchain

Description

If pSleepModeInfo is NULL, setLatencySleepModeNV will disable low latency mode, low latency boost, and set the minimum present interval previously specified by LatencySleepModeInfoNV to zero on swapchain. As an exception to the normal rules for objects which are externally synchronized, the swapchain passed to setLatencySleepModeNV may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Return Codes

Success

• SUCCESS

Failure

• ERROR_INITIALIZATION_FAILED
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_NV_low_latency2, Device, LatencySleepModeInfoNV, SwapchainKHR

vkLatencySleepNV - Trigger low latency mode Sleep

Description

latencySleepNV returns immediately. Applications should use waitSemaphores with pSleepInfo->signalSemaphore to delay host CPU work. CPU work refers to application work done before presenting which includes but is not limited to: input sampling, simulation, command buffer recording, command buffer submission, and present submission. Applications should call this function before input sampling, and exactly once between presents.

Return Codes

Success

• SUCCESS

Failure

• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_NV_low_latency2, Device, LatencySleepInfoNV, SwapchainKHR

vkSetLatencyMarkerNV - Pass in marker for timing info

Description

At the beginning and end of simulation and render threads and beginning and end of queuePresentKHR calls, setLatencyMarkerNV can be called to provide timestamps for the application’s reference. These timestamps are returned with a call to getLatencyTimingsNV alongside driver provided timestamps at various points of interest with regards to latency within the application. As an exception to the normal rules for objects which are externally synchronized, the swapchain passed to setLatencyMarkerNV may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, Device, SetLatencyMarkerInfoNV, SwapchainKHR

vkGetLatencyTimingsNV - Get latency marker results

Description

The timings returned by getLatencyTimingsNV contain the timestamps requested from setLatencyMarkerNV and additional implementation-specific markers defined in LatencyTimingsFrameReportNV.

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, Device, GetLatencyMarkerInfoNV, SwapchainKHR

vkQueueNotifyOutOfBandNV - Notify out of band queue

Command Properties

'

See Also

VK_NV_low_latency2, OutOfBandQueueTypeInfoNV, Queue

VkLatencySleepModeInfoNV - Structure to set low latency mode

Description

If lowLatencyMode is FALSE, lowLatencyBoost will still hint to the GPU to increase its power state and latencySleepNV will still enforce minimumIntervalUs between queuePresentKHR calls.

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, Bool32, StructureType, setLatencySleepModeNV

VkLatencySleepInfoNV - Structure specifying the parameters of vkLatencySleepNV

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, Semaphore, StructureType, latencySleepNV

VkSetLatencyMarkerInfoNV - Structure specifying the parameters of vkSetLatencyMarkerNV

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, LatencyMarkerNV, StructureType, setLatencyMarkerNV

VkGetLatencyMarkerInfoNV - Structure specifying the parameters of vkGetLatencyTimingsNV

Description

If pTimings is NULL then the maximum number of queryable frame data is returned in timingCount. Otherwise, timingCount must be set by the application to the number of elements in the pTimings array, and on return is overwritten with the number of values actually written to pTimings. The elements of pTimings are arranged in the order they were requested in, with the oldest data in the first entry.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_GET_LATENCY_MARKER_INFO_NV

• If timingCount is not 0, and pTimings is not NULL, pTimings must be a valid pointer to an array of timingCount LatencyTimingsFrameReportNV structures

See Also

VK_NV_low_latency2, LatencyTimingsFrameReportNV, StructureType, getLatencyTimingsNV

VkLatencyTimingsFrameReportNV - Structure containing latency data

Members

The members of the LatencyTimingsFrameReportNV structure describe the following:

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, GetLatencyMarkerInfoNV, StructureType

VkOutOfBandQueueTypeInfoNV - Structure used to describe the queue that is being marked as Out of Band

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, OutOfBandQueueTypeNV, StructureType, queueNotifyOutOfBandNV

VkLatencySubmissionPresentIdNV - Structure used to associate a queueSubmit with a presentId

Description

For any submission to be tracked with low latency mode pacing, it needs to be associated with other submissions in a given present. To associate a submission with presentID for low latency mode, the pNext chain of queueSubmit must include a LatencySubmissionPresentIdNV structure.

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, StructureType

VkSwapchainLatencyCreateInfoNV - Specify that a swapchain will use low latency mode

Valid Usage (Implicit)

See Also

VK_NV_low_latency2, Bool32, StructureType

VkLatencySurfaceCapabilitiesNV - Structure describing surface optimized presentation modes for use with low latency mode

Description

If pPresentModes is NULL, then the number of present modes that are optimized for use with low latency mode returned in presentModeCount. Otherwise, presentModeCount must be set by the application to the number of elements in the pPresentModes array, and on return is overwritten with the number of values actually written to pPresentModes. If the value of presentModeCount is less than the number of optimized present modes, at most presentModeCount values will be written to pPresentModes.

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_LATENCY_SURFACE_CAPABILITIES_NV

• If presentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of presentModeCount PresentModeKHR values

See Also

VK_NV_low_latency2, PresentModeKHR, StructureType

VkLatencyMarkerNV - Structure used to mark different points in latency

Description

The members of the LatencyMarkerNV are used as arguments for setLatencyMarkerNV in the use cases described below:

• LATENCY_MARKER_SIMULATION_START_NV should be called at the start of the simulation execution each frame, but after the call to latencySleepNV.
• LATENCY_MARKER_SIMULATION_END_NV should be called at the end of the simulation execution each frame.
• LATENCY_MARKER_RENDERSUBMIT_START_NV should be called at the beginning of the render submission execution each frame. This should be wherever Vulkan API calls are made and must not span into asynchronous rendering.
• LATENCY_MARKER_RENDERSUBMIT_END_NV should be called at the end of the render submission execution each frame.
• LATENCY_MARKER_PRESENT_START_NV should be called just before queuePresentKHR.
• LATENCY_MARKER_PRESENT_END_NV should be called when queuePresentKHR returns.
• LATENCY_MARKER_INPUT_SAMPLE_NV should be called just before the application gathers input data.
• LATENCY_MARKER_TRIGGER_FLASH_NV should be called anywhere between LATENCY_MARKER_SIMULATION_START_NV and LATENCY_MARKER_SIMULATION_END_NV whenever a left mouse click occurs.

See Also

VK_NV_low_latency2, SetLatencyMarkerInfoNV

VkOutOfBandQueueTypeNV - Type of out of band queue

Description

The members of the OutOfBandQueueTypeNV are used to describe the queue type in OutOfBandQueueTypeInfoNV as described below:

• OUT_OF_BAND_QUEUE_TYPE_RENDER_NV specifies that work will be submitted to this queue.
• OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV specifies that this queue will be presented from.

See Also

VK_NV_low_latency2, OutOfBandQueueTypeInfoNV

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

VkPresentModeKHR - Presentation mode supported for a surface

Description

• PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

• PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
• PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.
• PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.
• PRESENT_MODE_FIFO_LATEST_READY_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If using the VK_GOOGLE_display_timing extension or the presentAtAbsoluteTime feature to provide a target present time, the presentation engine checks the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine dequeues the image and checks the next one. The image of the last dequeued request is presented. The other dequeued requests are dropped.
• PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.
• PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

The supported ImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:

Presentable Image Usage Queries

For reference, the mode indicated by PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).

See Also

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityKHR, SurfacePresentModeKHR, SwapchainCreateInfoKHR, SwapchainPresentModeInfoKHR, SwapchainPresentModesCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR