path: root/chapters/VK_NV_low_latency2/low_latency2.adoc

// Copyright 2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0


[[low-latency2]]
= Low Latency 2

== Latency Reduction
[open,refpage='vkSetLatencySleepModeNV',desc='Enable or Disable low latency mode on a swapchain',type='protos']
--
To enable or disable low latency mode on a swapchain, call:

include::{generated}/api/protos/vkSetLatencySleepModeNV.adoc[]

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

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

include::{generated}/validity/protos/vkSetLatencySleepModeNV.adoc[]
--

[open,refpage='VkLatencySleepModeInfoNV',desc='Structure to set low latency mode',type='structs']
--
The sname:VkLatencySleepModeInfoNV structure is defined as:

include::{generated}/api/structs/VkLatencySleepModeInfoNV.adoc[]

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

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

include::{generated}/validity/structs/VkLatencySleepModeInfoNV.adoc[]
--

[open,refpage='vkLatencySleepNV',desc='Trigger low latency mode Sleep',type='protos']
--
To provide the synchronization primitive used to delay host CPU work for
lower latency rendering, call:

include::{generated}/api/protos/vkLatencySleepNV.adoc[]

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

fname:vkLatencySleepNV returns immediately.
Applications should: use flink:vkWaitSemaphores with
pname:pSleepInfo::pname: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.

include::{generated}/validity/protos/vkLatencySleepNV.adoc[]
--

[open,refpage='VkLatencySleepInfoNV',desc='Structure specifying the parameters of vkLatencySleepNV',type='structs']
--
The sname:VkLatencySleepInfoNV structure is defined as:

include::{generated}/api/structs/VkLatencySleepInfoNV.adoc[]

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

.Valid Usage
****
  * [[VUID-VkLatencySleepInfoNV-signalSemaphore-09361]]
    pname:signalSemaphore must: be a timeline semaphore
****

include::{generated}/validity/structs/VkLatencySleepInfoNV.adoc[]
--

[open,refpage='vkSetLatencyMarkerNV',desc='Pass in marker for timing info',type='protos']
--
An application can: provide timestamps at various stages of its frame
generation work by calling:

include::{generated}/api/protos/vkSetLatencyMarkerNV.adoc[]

  * pname:device is the device associated with pname:swapchain.
  * pname:swapchain is the swapchain to capture timestamps on.
  * pname:pSetLatencyMarkerInfo is a pointer to a
    slink: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 flink:vkQueuePresentKHR calls, fname:vkSetLatencyMarkerNV can: be
called to provide timestamps for the application's reference.
These timestamps are returned with a call to flink: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 fname:vkSetLatencyMarkerNV may: be
simultaneously used by other threads in calls to functions other than
flink:vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must: be atomic
within the implementation.

include::{generated}/validity/protos/vkSetLatencyMarkerNV.adoc[]
--

[open,refpage='VkSetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkSetLatencyMarkerNV',type='structs']
--
The sname:VkSetLatencyMarkerInfoNV structure is defined as:

include::{generated}/api/structs/VkSetLatencyMarkerInfoNV.adoc[]

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

include::{generated}/validity/structs/VkSetLatencyMarkerInfoNV.adoc[]
--

[open,refpage='VkLatencyMarkerNV',desc='Structure used to mark different points in latency',type='enums']
--
The elink:VkLatencyMarkerNV enum is defined as:

include::{generated}/api/enums/VkLatencyMarkerNV.adoc[]

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

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

[open,refpage='vkGetLatencyTimingsNV',desc='Get latency marker results',type='protos']
--
To get an array containing the newest collected latency data, call:

include::{generated}/api/protos/vkGetLatencyTimingsNV.adoc[]

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

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

include::{generated}/validity/protos/vkGetLatencyTimingsNV.adoc[]
--

[open,refpage='VkGetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkGetLatencyTimingsNV',type='structs']
--
The sname:VkGetLatencyMarkerInfoNV structure is defined as:

include::{generated}/api/structs/VkGetLatencyMarkerInfoNV.adoc[]

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

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

include::{generated}/validity/structs/VkGetLatencyMarkerInfoNV.adoc[]
--

[open,refpage='VkLatencyTimingsFrameReportNV',desc='Structure containing latency data',type='structs']
--
The slink:VkLatencyTimingsFrameReportNV structure describes latency data
returned by flink:vkGetLatencyTimingsNV

include::{generated}/api/structs/VkLatencyTimingsFrameReportNV.adoc[]

The members of the slink:VkLatencyTimingsFrameReportNV structure describe
the following:

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

include::{generated}/validity/structs/VkLatencyTimingsFrameReportNV.adoc[]
--

[open,refpage='VkLatencySubmissionPresentIdNV',desc='Structure used to associate a queueSubmit with a presentId',type='structs']
--
The slink:VkLatencySubmissionPresentIdNV structure is defined as:

include::{generated}/api/structs/VkLatencySubmissionPresentIdNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:presentId is used to associate the fname:vkQueueSubmit with the
    presentId used for a given fname:vkQueuePresentKHR via
    slink:VkPresentIdKHR::pname: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 flink:vkQueueSubmit to associate that submission with the
pname:presentId present for low latency mode.

include::{generated}/validity/structs/VkLatencySubmissionPresentIdNV.adoc[]
--

[open,refpage='vkQueueNotifyOutOfBandNV',desc='Notify out of band queue',type='protos']
--
An application can mark a queue as Out of Band to indicate that all
fname:vkQueueSubmit calls on this queue are ignored for latency evaluation
by calling:
include::{generated}/api/protos/vkQueueNotifyOutOfBandNV.adoc[]

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

include::{generated}/validity/protos/vkQueueNotifyOutOfBandNV.adoc[]
--

[open,refpage='VkOutOfBandQueueTypeInfoNV',desc='Structure used to describe the queue that is being marked as Out of Band',type='structs']
--
The slink:VkOutOfBandQueueTypeInfoNV structure is defined as:

include::{generated}/api/structs/VkOutOfBandQueueTypeInfoNV.adoc[]

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

include::{generated}/validity/structs/VkOutOfBandQueueTypeInfoNV.adoc[]
--

[open,refpage='VkOutOfBandQueueTypeNV',desc='Type of out of band queue',type='enums']
--
The elink:VkOutOfBandQueueTypeNV enum is defined as:

include::{generated}/api/enums/VkOutOfBandQueueTypeNV.adoc[]

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

  * ename:VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV indicates that work will be
    submitted to this queue.
  * ename:VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV indicates that this queue
    will be presented from.
--

[open,refpage='VkSwapchainLatencyCreateInfoNV',desc='Specify that a swapchain will use low latency mode',type='structs']
--
To allow low latency mode to be used by a swapchain, add a
sname:VkSwapchainLatencyCreateInfoNV structure to the pname:pNext chain of
slink:VkSwapchainCreateInfoKHR.

The sname:VkSwapchainLatencyCreateInfoNV structure is defined as:

include::{generated}/api/structs/VkSwapchainLatencyCreateInfoNV.adoc[]

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

include::{generated}/validity/structs/VkSwapchainLatencyCreateInfoNV.adoc[]
--

[open,refpage='VkLatencySurfaceCapabilitiesNV',desc='Structure describing surface optimized presentation modes for use with low latency mode',type='structs']
--
The sname:VkLatencySurfaceCapabilitiesNV structure is defined as:

include::{generated}/api/structs/VkLatencySurfaceCapabilitiesNV.adoc[]

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

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

include::{generated}/validity/structs/VkLatencySurfaceCapabilitiesNV.adoc[]
--