Author: The Khronos® Vulkan Working Group

# Vulkan® 1.3.276 - A Specification (with all registered extensions)

The Khronos® Vulkan Working Group
version 1.3.276, 2024-01-27 02:00:04Z
from git branch: Git branch not available commit: Git commit not available

Loading… please wait.

Search:

## 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.

- `minimumPresentIntervalUs` 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

  - `VK_ERROR_UNKNOWN`

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 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 | -

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