Low Latency 2
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 withswapchain
. -
swapchain
is the swapchain to enable or disable low latency mode on. -
pSleepModeInfo
isNULL
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.
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
isNULL
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.
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 withswapchain
. -
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.
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
isNULL
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 thatsignalSemaphore
is set to for resuming sampling work.
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 withswapchain
. -
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.
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
isNULL
or a pointer to a structure extending this structure. -
presentId
is an application provided value that is used to associate the timestamp with avkQueuePresentKHR
command using VkPresentIdKHR::pPresentIds
for a given present. -
marker
is the type of timestamp to be recorded.
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 tovkLatencySleepNV
. -
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 beforevkQueuePresentKHR
. -
VK_LATENCY_MARKER_PRESENT_END_NV
should be called whenvkQueuePresentKHR
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 betweenVK_LATENCY_MARKER_SIMULATION_START_NV
andVK_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 withswapchain
. -
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.
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 eitherNULL
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 eitherNULL
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.
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 avkQueuePresentKHR
command using VkPresentIdKHR::pPresentIds
for a given present. -
simStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_SIMULATION_START_NV
. -
simEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_SIMULATION_END_NV
-
renderStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_RENDERSUBMIT_START_NV
. -
renderEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_RENDERSUBMIT_END_NV
. -
presentStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_PRESENT_START_NV
. -
presentEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_PRESENT_END_NV
. -
driverStartTimeUs
is the timestamp written when the firstvkQueueSubmit
for the frame is called. -
driverEndTimeUs
is the timestamp written when the finalvkQueueSubmit
hands off from the Vulkan Driver. -
osRenderQueueStartTimeUs
is the timestamp written when the finalvkQueueSubmit
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.
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
isNULL
or a pointer to a structure extending this structure. -
presentId
is used to associate thevkQueueSubmit
with the presentId used for a givenvkQueuePresentKHR
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.
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.
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
isNULL
or a pointer to a structure extending this structure. -
queueType
describes the usage of the queue to be marked as out of band.
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
isNULL
or a pointer to a structure extending this structure. -
lowLatencyModeEnable
indicates if the swapchain created will utilize low latency mode.
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
isNULL
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 withpresentModeCount
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
.