Vulkan® 1.3.283 - A Specification (with all registered extensions)

45. Low Latency 2

45.1. Latency Reduction

To enable or disable low latency mode on a swapchain, call:

// Provided by VK_NV_low_latency2
VkResult vkSetLatencySleepModeNV(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    const VkLatencySleepModeInfoNV*             pSleepModeInfo);

device is the device associated with swapchain.
swapchain is the swapchain to enable or disable low latency mode on.
pSleepModeInfo is NULL or a pointer to a VkLatencySleepModeInfoNV structure specifying the parameters of the latency sleep mode.

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

Valid Usage (Implicit)

VUID-vkSetLatencySleepModeNV-device-parameter
device must be a valid VkDevice handle
VUID-vkSetLatencySleepModeNV-swapchain-parameter
swapchain must be a valid VkSwapchainKHR handle
VUID-vkSetLatencySleepModeNV-pSleepModeInfo-parameter
pSleepModeInfo must be a valid pointer to a valid VkLatencySleepModeInfoNV structure
VUID-vkSetLatencySleepModeNV-swapchain-parent
swapchain must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS

Failure

VK_ERROR_INITIALIZATION_FAILED

The VkLatencySleepModeInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepModeInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           lowLatencyMode;
    VkBool32           lowLatencyBoost;
    uint32_t           minimumIntervalUs;
} VkLatencySleepModeInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
lowLatencyMode is the toggle to enable or disable low latency mode.
lowLatencyBoost allows an application to hint to the GPU to increase performance to provide additional latency savings at a cost of increased power consumption.
minimumIntervalUs is the microseconds between vkQueuePresentKHR calls for a given swapchain that vkLatencySleepNV will enforce.

If lowLatencyMode is set to VK_FALSE, lowLatencyBoost will still hint to the GPU to increase its power state and vkLatencySleepNV will still enforce minimumIntervalUs between vkQueuePresentKHR calls.

Valid Usage (Implicit)

VUID-VkLatencySleepModeInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_LATENCY_SLEEP_MODE_INFO_NV

To provide the synchronization primitive used to delay host CPU work for lower latency rendering, call:

// Provided by VK_NV_low_latency2
VkResult vkLatencySleepNV(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    const VkLatencySleepInfoNV*                 pSleepInfo);

device is the device associated with swapchain.
swapchain is the swapchain to delay associated CPU work based on VkLatencySubmissionPresentIdNV submissions.
pSleepInfo is a pointer to a VkLatencySleepInfoNV structure specifying the parameters of the latency sleep.

vkLatencySleepNV returns immediately. Applications should use vkWaitSemaphores 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. It is recommended to call this function before input sampling. When using this function, it should be called exactly once between presents.

Valid Usage (Implicit)

VUID-vkLatencySleepNV-device-parameter
device must be a valid VkDevice handle
VUID-vkLatencySleepNV-swapchain-parameter
swapchain must be a valid VkSwapchainKHR handle
VUID-vkLatencySleepNV-pSleepInfo-parameter
pSleepInfo must be a valid pointer to a valid VkLatencySleepInfoNV structure
VUID-vkLatencySleepNV-swapchain-parent
swapchain must have been created, allocated, or retrieved from device

Return Codes

Success

VK_SUCCESS

Failure

None

The VkLatencySleepInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkSemaphore        signalSemaphore;
    uint64_t           value;
} VkLatencySleepInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
signalSemaphore is a semaphore that is signaled to indicate that the application should resume input sampling work.
value is the value that signalSemaphore is set to for resuming sampling work.

Valid Usage

VUID-VkLatencySleepInfoNV-signalSemaphore-09361
signalSemaphore must be a timeline semaphore

Valid Usage (Implicit)

VUID-VkLatencySleepInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_LATENCY_SLEEP_INFO_NV
VUID-VkLatencySleepInfoNV-signalSemaphore-parameter
signalSemaphore must be a valid VkSemaphore handle

An application can provide timestamps at various stages of its frame generation work by calling:

// Provided by VK_NV_low_latency2
void vkSetLatencyMarkerNV(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    const VkSetLatencyMarkerInfoNV*             pLatencyMarkerInfo);

device is the device associated with swapchain.
swapchain is the swapchain to capture timestamps on.
pSetLatencyMarkerInfo is a pointer to a VkSetLatencyMarkerInfoNV structure specifying the parameters of the marker to set.

At the beginning and end of simulation and render threads and beginning and end of vkQueuePresentKHR calls, vkSetLatencyMarkerNV can be called to provide timestamps for the application’s reference. These timestamps are returned with a call to vkGetLatencyTimingsNV 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 vkSetLatencyMarkerNV may be simultaneously used by other threads in calls to functions other than vkDestroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Valid Usage (Implicit)

VUID-vkSetLatencyMarkerNV-device-parameter
device must be a valid VkDevice handle
VUID-vkSetLatencyMarkerNV-swapchain-parameter
swapchain must be a valid VkSwapchainKHR handle
VUID-vkSetLatencyMarkerNV-pLatencyMarkerInfo-parameter
pLatencyMarkerInfo must be a valid pointer to a valid VkSetLatencyMarkerInfoNV structure
VUID-vkSetLatencyMarkerNV-swapchain-parent
swapchain must have been created, allocated, or retrieved from device

The VkSetLatencyMarkerInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkSetLatencyMarkerInfoNV {
    VkStructureType      sType;
    const void*          pNext;
    uint64_t             presentID;
    VkLatencyMarkerNV    marker;
} VkSetLatencyMarkerInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
presentId is an application provided value that is used to associate the timestamp with a vkQueuePresentKHR command using VkPresentIdKHR::pPresentIds for a given present.
marker is the type of timestamp to be recorded.

Valid Usage (Implicit)

VUID-VkSetLatencyMarkerInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_SET_LATENCY_MARKER_INFO_NV
VUID-VkSetLatencyMarkerInfoNV-marker-parameter
marker must be a valid VkLatencyMarkerNV value

The VkLatencyMarkerNV enum is defined as:

// Provided by VK_NV_low_latency2
typedef enum VkLatencyMarkerNV {
    VK_LATENCY_MARKER_SIMULATION_START_NV = 0,
    VK_LATENCY_MARKER_SIMULATION_END_NV = 1,
    VK_LATENCY_MARKER_RENDERSUBMIT_START_NV = 2,
    VK_LATENCY_MARKER_RENDERSUBMIT_END_NV = 3,
    VK_LATENCY_MARKER_PRESENT_START_NV = 4,
    VK_LATENCY_MARKER_PRESENT_END_NV = 5,
    VK_LATENCY_MARKER_INPUT_SAMPLE_NV = 6,
    VK_LATENCY_MARKER_TRIGGER_FLASH_NV = 7,
    VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_START_NV = 8,
    VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_END_NV = 9,
    VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_START_NV = 10,
    VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_END_NV = 11,
} VkLatencyMarkerNV;

The members of the VkLatencyMarkerNV are used as arguments for vkSetLatencyMarkerNV in the use cases described below:

VK_LATENCY_MARKER_SIMULATION_START_NV should be called at the start of the simulation execution each frame, but after the call to vkLatencySleepNV.
VK_LATENCY_MARKER_SIMULATION_END_NV should be called at the end of the simulation execution each frame.
VK_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.
VK_LATENCY_MARKER_RENDERSUBMIT_END_NV should be called at the end of the render submission execution each frame.
VK_LATENCY_MARKER_PRESENT_START_NV should be called just before vkQueuePresentKHR.
VK_LATENCY_MARKER_PRESENT_END_NV should be called when vkQueuePresentKHR returns.
VK_LATENCY_MARKER_INPUT_SAMPLE_NV should be called just before the application gathers input data.
VK_LATENCY_MARKER_TRIGGER_FLASH_NV should be called anywhere between VK_LATENCY_MARKER_SIMULATION_START_NV and VK_LATENCY_MARKER_SIMULATION_END_NV whenever a left mouse click occurs.

To get an array containing the newest collected latency data, call:

// Provided by VK_NV_low_latency2
void vkGetLatencyTimingsNV(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    VkGetLatencyMarkerInfoNV*                   pLatencyMarkerInfo);

device is the device associated with swapchain.
swapchain is the swapchain to return data from.
pGetLatencyMarkerInfo is a pointer to a VkGetLatencyMarkerInfoNV structure specifying the parameters for returning latency information.

The timings returned by vkGetLatencyTimingsNV contain the timestamps requested from vkSetLatencyMarkerNV and additional implementation-specific markers defined in VkLatencyTimingsFrameReportNV.

Valid Usage (Implicit)

VUID-vkGetLatencyTimingsNV-device-parameter
device must be a valid VkDevice handle
VUID-vkGetLatencyTimingsNV-swapchain-parameter
swapchain must be a valid VkSwapchainKHR handle
VUID-vkGetLatencyTimingsNV-pLatencyMarkerInfo-parameter
pLatencyMarkerInfo must be a valid pointer to a VkGetLatencyMarkerInfoNV structure
VUID-vkGetLatencyTimingsNV-swapchain-parent
swapchain must have been created, allocated, or retrieved from device

The VkGetLatencyMarkerInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkGetLatencyMarkerInfoNV {
    VkStructureType                   sType;
    const void*                       pNext;
    uint32_t                          timingCount;
    VkLatencyTimingsFrameReportNV*    pTimings;
} VkGetLatencyMarkerInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is either NULL or a pointer to a structure extending this structure.
timingCount is an integer related to the number of previous frames of latency data available or queried, as described below.
pTimings is either NULL or a pointer to an array of VkLatencyTimingsFrameReportNV structures.

If pTimings is NULL then the maximum number of queryable frame data is returned in timingCount. Otherwise, timingCount must be set by the user to the number of elements in the pTimings array, and on return the variable 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)

VUID-VkGetLatencyMarkerInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_GET_LATENCY_MARKER_INFO_NV
VUID-VkGetLatencyMarkerInfoNV-pTimings-parameter
If timingCount is not 0, and pTimings is not NULL, pTimings must be a valid pointer to an array of timingCount VkLatencyTimingsFrameReportNV structures

The VkLatencyTimingsFrameReportNV structure describes latency data returned by vkGetLatencyTimingsNV

// Provided by VK_NV_low_latency2
typedef struct VkLatencyTimingsFrameReportNV {
    VkStructureType    sType;
    const void*        pNext;
    uint64_t           presentID;
    uint64_t           inputSampleTimeUs;
    uint64_t           simStartTimeUs;
    uint64_t           simEndTimeUs;
    uint64_t           renderSubmitStartTimeUs;
    uint64_t           renderSubmitEndTimeUs;
    uint64_t           presentStartTimeUs;
    uint64_t           presentEndTimeUs;
    uint64_t           driverStartTimeUs;
    uint64_t           driverEndTimeUs;
    uint64_t           osRenderQueueStartTimeUs;
    uint64_t           osRenderQueueEndTimeUs;
    uint64_t           gpuRenderStartTimeUs;
    uint64_t           gpuRenderEndTimeUs;
} VkLatencyTimingsFrameReportNV;

The members of the VkLatencyTimingsFrameReportNV structure describe the following:

presentId is the application provided value that is used to associate the timestamp with a vkQueuePresentKHR command using VkPresentIdKHR::pPresentIds for a given present.
simStartTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_SIMULATION_START_NV.
simEndTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_SIMULATION_END_NV
renderStartTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_RENDERSUBMIT_START_NV.
renderEndTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_RENDERSUBMIT_END_NV.
presentStartTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_PRESENT_START_NV.
presentEndTimeUs is the timestamp written when vkSetLatencyMarkerNV is called with the VkLatencyMarkerNV enum VK_LATENCY_MARKER_PRESENT_END_NV.
driverStartTimeUs is the timestamp written when the first vkQueueSubmit for the frame is called.
driverEndTimeUs is the timestamp written when the final vkQueueSubmit hands off from the Vulkan Driver.
osRenderQueueStartTimeUs is the timestamp written when the final vkQueueSubmit hands off from the Vulkan Driver.
osRenderQueueEndTimeUs is the timestamp written when the first submission reaches the GPU.
gpuRenderStartTimeUs is the timestamp written when the first submission reaches the GPU.
gpuRenderEndTimeUs is the timestamp written when the final submission finishes on the GPU for the frame.

Valid Usage (Implicit)

VUID-VkLatencyTimingsFrameReportNV-sType-sType
sType must be VK_STRUCTURE_TYPE_LATENCY_TIMINGS_FRAME_REPORT_NV

The VkLatencySubmissionPresentIdNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkLatencySubmissionPresentIdNV {
    VkStructureType    sType;
    const void*        pNext;
    uint64_t           presentID;
} VkLatencySubmissionPresentIdNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
presentId is used to associate the vkQueueSubmit with the presentId used for a given vkQueuePresentKHR via VkPresentIdKHR::pPresentIds.

For any submission to be tracked with low latency mode pacing, it needs to be associated with other submissions in a given present. Applications must include the VkLatencySubmissionPresentIdNV in the pNext chain of vkQueueSubmit to associate that submission with the presentId present for low latency mode.

Valid Usage (Implicit)

VUID-VkLatencySubmissionPresentIdNV-sType-sType
sType must be VK_STRUCTURE_TYPE_LATENCY_SUBMISSION_PRESENT_ID_NV

An application can mark a queue as Out of Band to indicate that all vkQueueSubmit calls on this queue are ignored for latency evaluation by calling:

// Provided by VK_NV_low_latency2
void vkQueueNotifyOutOfBandNV(
    VkQueue                                     queue,
    const VkOutOfBandQueueTypeInfoNV*           pQueueTypeInfo);

queue is the VkQueue to be marked as out of band.
pQueueTypeInfo is a pointer to a VkOutOfBandQueueTypeInfoNV structure specifying the queue type.

Valid Usage (Implicit)

VUID-vkQueueNotifyOutOfBandNV-queue-parameter
queue must be a valid VkQueue handle
VUID-vkQueueNotifyOutOfBandNV-pQueueTypeInfo-parameter
pQueueTypeInfo must be a valid pointer to a valid VkOutOfBandQueueTypeInfoNV structure

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
-	-	-	Any	-

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Any

The VkOutOfBandQueueTypeInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkOutOfBandQueueTypeInfoNV {
    VkStructureType           sType;
    const void*               pNext;
    VkOutOfBandQueueTypeNV    queueType;
} VkOutOfBandQueueTypeInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
queueType describes the usage of the queue to be marked as out of band.

Valid Usage (Implicit)

VUID-VkOutOfBandQueueTypeInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_OUT_OF_BAND_QUEUE_TYPE_INFO_NV
VUID-VkOutOfBandQueueTypeInfoNV-queueType-parameter
queueType must be a valid VkOutOfBandQueueTypeNV value

The VkOutOfBandQueueTypeNV enum is defined as:

// Provided by VK_NV_low_latency2
typedef enum VkOutOfBandQueueTypeNV {
    VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV = 0,
    VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV = 1,
} VkOutOfBandQueueTypeNV;

The members of the VkOutOfBandQueueTypeNV are used to describe the queue type in VkOutOfBandQueueTypeInfoNV as described below:

VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV indicates that work will be submitted to this queue.
VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV indicates that this queue will be presented from.

To allow low latency mode to be used by a swapchain, add a VkSwapchainLatencyCreateInfoNV structure to the pNext chain of VkSwapchainCreateInfoKHR.

The VkSwapchainLatencyCreateInfoNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkSwapchainLatencyCreateInfoNV {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           latencyModeEnable;
} VkSwapchainLatencyCreateInfoNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
lowLatencyModeEnable indicates if the swapchain created will utilize low latency mode.

Valid Usage (Implicit)

VUID-VkSwapchainLatencyCreateInfoNV-sType-sType
sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_LATENCY_CREATE_INFO_NV

The VkLatencySurfaceCapabilitiesNV structure is defined as:

// Provided by VK_NV_low_latency2
typedef struct VkLatencySurfaceCapabilitiesNV {
    VkStructureType      sType;
    const void*          pNext;
    uint32_t             presentModeCount;
    VkPresentModeKHR*    pPresentModes;
} VkLatencySurfaceCapabilitiesNV;

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
presentModeCount is the number of presentation modes provided.
pPresentModes is list of presentation modes optimized for use with low latency mode with presentModeCount entries.

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 user to the number of elements in the pPresentModes array, and on return the variable 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)

VUID-VkLatencySurfaceCapabilitiesNV-sType-sType
sType must be VK_STRUCTURE_TYPE_LATENCY_SURFACE_CAPABILITIES_NV
VUID-VkLatencySurfaceCapabilitiesNV-pPresentModes-parameter
If presentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of presentModeCount VkPresentModeKHR values