1// Copyright 2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5 6[[low-latency2]] 7= Low Latency 2 8 9== Latency Reduction 10[open,refpage='vkSetLatencySleepModeNV',desc='Enable or Disable low latency mode on a swapchain',type='protos'] 11-- 12To enable or disable low latency mode on a swapchain, call: 13 14include::{generated}/api/protos/vkSetLatencySleepModeNV.adoc[] 15 16 * pname:device is the device associated with pname:swapchain. 17 * pname:swapchain is the swapchain to enable or disable low latency mode 18 on. 19 * pname:pSleepModeInfo is `NULL` or a pointer to a 20 slink:VkLatencySleepModeInfoNV structure specifying the parameters of 21 the latency sleep mode. 22 23If pname:pSleepModeInfo is `NULL`, fname:vkSetLatencySleepModeNV will 24disable low latency mode, low latency boost, and set the minimum present 25interval previously specified by slink:VkLatencySleepModeInfoNV to zero on 26pname:swapchain. 27 28include::{generated}/validity/protos/vkSetLatencySleepModeNV.adoc[] 29-- 30 31[open,refpage='VkLatencySleepModeInfoNV',desc='Structure to set low latency mode',type='structs'] 32-- 33The sname:VkLatencySleepModeInfoNV structure is defined as: 34 35include::{generated}/api/structs/VkLatencySleepModeInfoNV.adoc[] 36 37 * pname:sType is a elink:VkStructureType value identifying this structure. 38 * pname:pNext is `NULL` or a pointer to a structure extending this 39 structure. 40 * pname:lowLatencyMode is the toggle to enable or disable low latency 41 mode. 42 * pname:lowLatencyBoost allows an application to hint to the GPU to 43 increase performance to provide additional latency savings at a cost of 44 increased power consumption. 45 * pname:minimumPresentIntervalUs is the microseconds between 46 flink:vkQueuePresentKHR calls for a given swapchain that 47 flink:vkLatencySleepNV will enforce. 48 49If pname:lowLatencyMode is set to ename:VK_FALSE, pname:lowLatencyBoost will 50still hint to the GPU to increase its power state and fname:vkLatencySleepNV 51will still enforce pname:minimumIntervalUs between fname:vkQueuePresentKHR 52calls. 53 54include::{generated}/validity/structs/VkLatencySleepModeInfoNV.adoc[] 55-- 56 57[open,refpage='vkLatencySleepNV',desc='Trigger low latency mode Sleep',type='protos'] 58-- 59To provide the synchronization primitive used to delay host CPU work for 60lower latency rendering, call: 61 62include::{generated}/api/protos/vkLatencySleepNV.adoc[] 63 64 * pname:device is the device associated with pname:swapchain. 65 * pname:swapchain is the swapchain to delay associated CPU work based on 66 slink:VkLatencySubmissionPresentIdNV submissions. 67 * pname:pSleepInfo is a pointer to a slink:VkLatencySleepInfoNV structure 68 specifying the parameters of the latency sleep. 69 70fname:vkLatencySleepNV returns immediately. 71Applications should: use flink:vkWaitSemaphores with 72pname:pSleepInfo::pname:signalSemaphore to delay host CPU work. 73CPU work refers to application work done before presenting which includes 74but is not limited to: input sampling, simulation, command buffer recording, 75command buffer submission, and present submission. 76It is recommended to call this function before input sampling. 77When using this function, it should: be called exactly once between 78presents. 79 80include::{generated}/validity/protos/vkLatencySleepNV.adoc[] 81-- 82 83[open,refpage='VkLatencySleepInfoNV',desc='Structure specifying the parameters of vkLatencySleepNV',type='structs'] 84-- 85The sname:VkLatencySleepInfoNV structure is defined as: 86 87include::{generated}/api/structs/VkLatencySleepInfoNV.adoc[] 88 89 * pname:sType is a elink:VkStructureType value identifying this structure. 90 * pname:pNext is `NULL` or a pointer to a structure extending this 91 structure. 92 * pname:signalSemaphore is a semaphore that is signaled to indicate that 93 the application should: resume input sampling work. 94 * pname:value is the value that pname:signalSemaphore is set to for 95 resuming sampling work. 96 97.Valid Usage 98**** 99 * [[VUID-VkLatencySleepInfoNV-signalSemaphore-09361]] 100 pname:signalSemaphore must: be a timeline semaphore 101**** 102 103include::{generated}/validity/structs/VkLatencySleepInfoNV.adoc[] 104-- 105 106[open,refpage='vkSetLatencyMarkerNV',desc='Pass in marker for timing info',type='protos'] 107-- 108An application can: provide timestamps at various stages of its frame 109generation work by calling: 110 111include::{generated}/api/protos/vkSetLatencyMarkerNV.adoc[] 112 113 * pname:device is the device associated with pname:swapchain. 114 * pname:swapchain is the swapchain to capture timestamps on. 115 * pname:pSetLatencyMarkerInfo is a pointer to a 116 slink:VkSetLatencyMarkerInfoNV structure specifying the parameters of 117 the marker to set. 118 119At the beginning and end of simulation and render threads and beginning and 120end of flink:vkQueuePresentKHR calls, fname:vkSetLatencyMarkerNV can: be 121called to provide timestamps for the application's reference. 122These timestamps are returned with a call to flink:vkGetLatencyTimingsNV 123alongside driver provided timestamps at various points of interest with 124regards to latency within the application. 125 126include::{generated}/validity/protos/vkSetLatencyMarkerNV.adoc[] 127-- 128 129[open,refpage='VkSetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkSetLatencyMarkerNV',type='structs'] 130-- 131The sname:VkSetLatencyMarkerInfoNV structure is defined as: 132 133include::{generated}/api/structs/VkSetLatencyMarkerInfoNV.adoc[] 134 135 * pname:sType is a elink:VkStructureType value identifying this structure. 136 * pname:pNext is `NULL` or a pointer to a structure extending this 137 structure. 138 * pname:presentId is an application provided value that is used to 139 associate the timestamp with a fname:vkQueuePresentKHR command using 140 slink:VkPresentIdKHR::pname:pPresentIds for a given present. 141 * pname:marker is the type of timestamp to be recorded. 142 143include::{generated}/validity/structs/VkSetLatencyMarkerInfoNV.adoc[] 144-- 145 146[open,refpage='VkLatencyMarkerNV',desc='Structure used to mark different points in latency',type='enums'] 147-- 148The elink:VkLatencyMarkerNV enum is defined as: 149 150include::{generated}/api/enums/VkLatencyMarkerNV.adoc[] 151 152The members of the elink:VkLatencyMarkerNV are used as arguments for 153flink:vkSetLatencyMarkerNV in the use cases described below: 154 155 * ename:VK_LATENCY_MARKER_SIMULATION_START_NV should: be called at the 156 start of the simulation execution each frame, but after the call to 157 fname:vkLatencySleepNV. 158 * ename:VK_LATENCY_MARKER_SIMULATION_END_NV should: be called at the end 159 of the simulation execution each frame. 160 * ename:VK_LATENCY_MARKER_RENDERSUBMIT_START_NV should: be called at the 161 beginning of the render submission execution each frame. 162 This should: be wherever Vulkan API calls are made and must: not span 163 into asynchronous rendering. 164 * ename:VK_LATENCY_MARKER_RENDERSUBMIT_END_NV should: be called at the end 165 of the render submission execution each frame. 166 * ename:VK_LATENCY_MARKER_PRESENT_START_NV should: be called just before 167 fname:vkQueuePresentKHR. 168 * ename:VK_LATENCY_MARKER_PRESENT_END_NV should: be called when 169 fname:vkQueuePresentKHR returns. 170 * ename:VK_LATENCY_MARKER_INPUT_SAMPLE_NV should: be called just before 171 the application gathers input data. 172 * ename:VK_LATENCY_MARKER_TRIGGER_FLASH_NV should: be called anywhere 173 between ename:VK_LATENCY_MARKER_SIMULATION_START_NV and 174 ename:VK_LATENCY_MARKER_SIMULATION_END_NV whenever a left mouse click 175 occurs. 176-- 177 178[open,refpage='vkGetLatencyTimingsNV',desc='Get latency marker results',type='protos'] 179-- 180To get an array containing the newest collected latency data, call: 181 182include::{generated}/api/protos/vkGetLatencyTimingsNV.adoc[] 183 184 * pname:device is the device associated with pname:swapchain. 185 * pname:swapchain is the swapchain to return data from. 186 * pname:pTimingCount is a pointer to an integer related to the number of 187 of previous frames of latency data available or queried, as described 188 below. 189 * pname:pGetLatencyMarkerInfo is a pointer to a 190 slink:VkGetLatencyMarkerInfoNV structure specifying the parameters for 191 returning latency information. 192 193The timings returned by fname:vkGetLatencyTimingsNV contain the timestamps 194requested from flink:vkSetLatencyMarkerNV and additional 195implementation-specific markers defined in 196slink:VkLatencyTimingsFrameReportNV. 197If pname:pTimings is `NULL`, then the maximum number of queryable frame data 198is returned in pname:pTimingCount. 199Otherwise, pname:pTimingCount must: point to a variable set by the user to 200the number of elements in the pname:pTimings array in 201pname:pGetLatencyMarkerInfo, and on return the variable is overwritten with 202the number of values actually written to pname:pTimings. 203 204include::{generated}/validity/protos/vkGetLatencyTimingsNV.adoc[] 205-- 206 207[open,refpage='VkGetLatencyMarkerInfoNV',desc='Structure specifying the parameters of vkGetLatencyTimingsNV',type='structs'] 208-- 209The sname:VkGetLatencyMarkerInfoNV structure is defined as: 210 211include::{generated}/api/structs/VkGetLatencyMarkerInfoNV.adoc[] 212 213 * pname:sType is a elink:VkStructureType value identifying this structure. 214 * pname:pNext is either `NULL` or a pointer to a structure extending this 215 structure. 216 * pname:pTimings is either `NULL` or a pointer to an array of 217 slink:VkLatencyTimingsFrameReportNV structures. 218 219The elements of pname:pTimings are arranged in the order they were requested 220in, with the oldest data in the first entry. 221 222include::{generated}/validity/structs/VkGetLatencyMarkerInfoNV.adoc[] 223-- 224 225[open,refpage='VkLatencyTimingsFrameReportNV',desc='Structure containing latency data',type='structs'] 226-- 227The slink:VkLatencyTimingsFrameReportNV structure describes latency data 228returned by flink:vkGetLatencyTimingsNV 229 230include::{generated}/api/structs/VkLatencyTimingsFrameReportNV.adoc[] 231 232The members of the slink:VkLatencyTimingsFrameReportNV structure describe 233the following: 234 235 * pname:presentId is the application provided value that is used to 236 associate the timestamp with a fname:vkQueuePresentKHR command using 237 slink:VkPresentIdKHR::pname:pPresentIds for a given present. 238 * pname:simStartTimeUs is the timestamp written when 239 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 240 enum ename:VK_LATENCY_MARKER_SIMULATION_START_NV. 241 * pname:simEndTimeUs is the timestamp written when 242 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 243 enum ename:VK_LATENCY_MARKER_SIMULATION_END_NV 244 * pname:renderStartTimeUs is the timestamp written when 245 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 246 enum ename:VK_LATENCY_MARKER_RENDERSUBMIT_START_NV. 247 * pname:renderEndTimeUs is the timestamp written when 248 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 249 enum ename:VK_LATENCY_MARKER_RENDERSUBMIT_END_NV. 250 * pname:presentStartTimeUs is the timestamp written when 251 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 252 enum ename:VK_LATENCY_MARKER_PRESENT_START_NV. 253 * pname:presentEndTimeUs is the timestamp written when 254 fname:vkSetLatencyMarkerNV is called with the ename:VkLatencyMarkerNV 255 enum ename:VK_LATENCY_MARKER_PRESENT_END_NV. 256 * pname:driverStartTimeUs is the timestamp written when the first 257 fname:vkQueueSubmit for the frame is called. 258 * pname:driverEndTimeUs is the timestamp written when the final 259 fname:vkQueueSubmit hands off from the Vulkan Driver. 260 * pname:osRenderQueueStartTimeUs is the timestamp written when the final 261 fname:vkQueueSubmit hands off from the Vulkan Driver. 262 * pname:osRenderQueueEndTimeUs is the timestamp written when the first 263 submission reaches the GPU. 264 * pname:gpuRenderStartTimeUs is the timestamp written when the first 265 submission reaches the GPU. 266 * pname:gpuRenderEndTimeUs is the timestamp written when the final 267 submission finishes on the GPU for the frame. 268 269include::{generated}/validity/structs/VkLatencyTimingsFrameReportNV.adoc[] 270-- 271 272[open,refpage='VkLatencySubmissionPresentIdNV',desc='Structure used to associate a queueSubmit with a presentId',type='structs'] 273-- 274The slink:VkLatencySubmissionPresentIdNV structure is defined as: 275 276include::{generated}/api/structs/VkLatencySubmissionPresentIdNV.adoc[] 277 278 * pname:sType is a elink:VkStructureType value identifying this structure. 279 * pname:pNext is `NULL` or a pointer to a structure extending this 280 structure. 281 * pname:presentId is used to associate the fname:vkQueueSubmit with the 282 presentId used for a given fname:vkQueuePresentKHR via 283 slink:VkPresentIdKHR::pname:pPresentIds. 284 285For any submission to be tracked with low latency mode pacing, it needs to 286be associated with other submissions in a given present. 287Applications :must include the VkLatencySubmissionPresentIdNV in the pNext 288chain of flink:vkQueueSubmit to associate that submission with the 289pname:presentId present for low latency mode. 290 291include::{generated}/validity/structs/VkLatencySubmissionPresentIdNV.adoc[] 292-- 293 294[open,refpage='vkQueueNotifyOutOfBandNV',desc='Notify out of band queue',type='protos'] 295-- 296An application can mark a queue as Out of Band to indicate that all 297fname:vkQueueSubmit calls on this queue are ignored for latency evaluation 298by calling: 299include::{generated}/api/protos/vkQueueNotifyOutOfBandNV.adoc[] 300 301 * pname:queue is the VkQueue to be marked as out of band. 302 * pname:pQueueTypeInfo is a pointer to a slink:VkOutOfBandQueueTypeInfoNV 303 structure specifying the queue type. 304 305include::{generated}/validity/protos/vkQueueNotifyOutOfBandNV.adoc[] 306-- 307 308[open,refpage='VkOutOfBandQueueTypeInfoNV',desc='Structure used to describe the queue that is being marked as Out of Band',type='structs'] 309-- 310The slink:VkOutOfBandQueueTypeInfoNV structure is defined as: 311 312include::{generated}/api/structs/VkOutOfBandQueueTypeInfoNV.adoc[] 313 314 * pname:sType is a elink:VkStructureType value identifying this structure. 315 * pname:pNext is `NULL` or a pointer to a structure extending this 316 structure. 317 * pname:queueType describes the usage of the queue to be marked as out of 318 band. 319 320include::{generated}/validity/structs/VkOutOfBandQueueTypeInfoNV.adoc[] 321-- 322 323[open,refpage='VkOutOfBandQueueTypeNV',desc='Type of out of band queue',type='enums'] 324-- 325The elink:VkOutOfBandQueueTypeNV enum is defined as: 326 327include::{generated}/api/enums/VkOutOfBandQueueTypeNV.adoc[] 328 329The members of the elink:VkOutOfBandQueueTypeNV are used to describe the 330queue type in slink:VkOutOfBandQueueTypeInfoNV as described below: 331 332 * ename:VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV indicates that work will be 333 submitted to this queue. 334 * ename:VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV indicates that this queue 335 will be presented from. 336-- 337 338[open,refpage='VkSwapchainLatencyCreateInfoNV',desc='Specify that a swapchain will use low latency mode',type='structs'] 339-- 340To allow low latency mode to be used by a swapchain, add a 341sname:VkSwapchainLatencyCreateInfoNV structure to the pname:pNext chain of 342slink:VkSwapchainCreateInfoKHR. 343 344The sname:VkSwapchainLatencyCreateInfoNV structure is defined as: 345 346include::{generated}/api/structs/VkSwapchainLatencyCreateInfoNV.adoc[] 347 348 * pname:sType is a elink:VkStructureType value identifying this structure. 349 * pname:pNext is `NULL` or a pointer to a structure extending this 350 structure. 351 * pname:lowLatencyModeEnable indicates if the swapchain created will 352 utilize low latency mode. 353 354include::{generated}/validity/structs/VkSwapchainLatencyCreateInfoNV.adoc[] 355-- 356 357[open,refpage='VkLatencySurfaceCapabilitiesNV',desc='Structure describing surface optimized presentation modes for use with low latency mode',type='structs'] 358-- 359The sname:VkLatencySurfaceCapabilitiesNV structure is defined as: 360 361include::{generated}/api/structs/VkLatencySurfaceCapabilitiesNV.adoc[] 362 363 * pname:sType is a elink:VkStructureType value identifying this structure. 364 * pname:pNext is `NULL` or a pointer to a structure extending this 365 structure. 366 * pname:presentModeCount is the number of presentation modes provided. 367 * pname:pPresentModes is list of presentation modes optimized for use with 368 low latency mode with pname:presentModeCount entries. 369 370If pname:pPresentModes is `NULL`, then the number of present modes that are 371optimized for use with low latency mode returned in pname:presentModeCount. 372Otherwise, pname:presentModeCount must be set by the user to the number of 373elements in the pname:pPresentModes array, and on return the variable is 374overwritten with the number of values actually written to 375pname:pPresentModes. 376If the value of pname:presentModeCount is less than the number of optimized 377present modes, at most pname:presentModeCount values will be written to 378pname:pPresentModes. 379 380include::{generated}/validity/structs/VkLatencySurfaceCapabilitiesNV.adoc[] 381-- 382