Cleanup VkPresentTimingInfo

- Remove the VkPresentTimeEXT union, as it does not fit the style of Vulkan
- Remove boolean members and replace them with a new flags type.
- Cleanup some spec language and VUs.

Author: nvlduc

chapters/VK_EXT_present_timing/PresentTimeInfo.adoc

@@ -27,41 +27,26 @@ include::{generated}/api/structs/VkPresentTimingsInfoEXT.adoc[]
     information for the presentation of the image corresponding to the entry
     in the sname:VkPresentInfoKHR::pname:pImageIndices array.
 
-The semantics of target presentation time vary depending on the presentation mode:
-
-  * ename:VK_PRESENT_MODE_FIFO_KHR.
-    Tearing cannot: be observed.
-    The first queued image is dequeued and presented if
-    both: 1) its associated wait semaphore(s) have signaled, and 2)
-    its target present time is less-than or equal-to the current time.
-  * ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR.
-    For images that are presented in time to be displayed at the next
-    vertical blanking period, the semantics are identical as for
-    ename:VK_PRESENT_MODE_FIFO_KHR.
-    For images that are presented late, and are displayed after the start of
-    the vertical blanking period (i.e. with tearing), the values of
-    slink:VkPastPresentationTimingEXT may: be treated as if the image was
-    displayed at the start of the vertical blanking period, or may: be
-    treated the same as for ename:VK_PRESENT_MODE_IMMEDIATE_KHR.
-
-Other presentation modes must: not be used with a target presentation time.
-
 .Valid Usage
 ****
-  * pname:swapchainCount must: be the same value as
-    sname:VkPresentInfoKHR::pname:swapchainCount, where
-    sname:VkPresentInfoKHR is in the pname:pNext chain of this
-    sname:VkPresentTimingsInfoEXT structure.
+  * pname:swapchainCount must: be equal to
+    slink:VkPresentInfoKHR::pname:swapchainCount.
+  * All swapchains in slink:VkPresentInfoKHR::pname:pSwapchains must: have
+    been created with the slink:VkSwapchainCreateInfoKHR::pname:flags field
+    containing ename:VK_SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT
   * For each member of sname:VkPresentInfoKHR::pname:pSwapchains, if the
-    associated sname:VkPresentTimeEXT is non-zero, the current present mode
-    must: be ename:VK_PRESENT_MODE_FIFO_KHR or
+    associated slink:VkPresentTimingInfoEXT::pname:targetTime is not zero,
+    the swapchain's current present mode must: be
+ifdef::VK_KHR_present_mode_fifo_latest_ready[]
+    ename:VK_PRESENT_MODE_FIFO_LATEST_READY_KHR,
+endif::VK_KHR_present_mode_fifo_latest_ready[]
+    ename:VK_PRESENT_MODE_FIFO_KHR or
     ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR.
 ****
 
 include::{generated}/validity/structs/VkPresentTimingsInfoEXT.adoc[]
 --
 
-
 [open,refpage='VkPresentTimingInfoEXT',desc='Specifies per-present timing information',type='structs']
 --
 The sname:VkPresentTimingInfoEXT structure is defined as:
@@ -71,31 +56,41 @@ include::{generated}/api/structs/VkPresentTimingInfoEXT.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:time is a sname:VkPresentTimeEXT specifying the target present
-    time or duration of the presentation request.
+  * pname:flags is a bitmask of elink:VkPresentTimingInfoFlagBitsEXT
+    specifying options for how to interpret the timing information.
+  * pname:targetTime is zero or a value specifying the target present
+    time in nanoseconds of the presentation request.
   * pname:timeDomainId is the id of the time domain used to specify the
     absolute target present time and the timing results obtained in a
     subsequent flink:vkGetPastPresentationTimingEXT call for the current
     presentation request.
   * pname:presentStageQueries is a valid tlink:VkPresentStageFlagsEXT value
     indicating which present stages the presentation engine will collect
     timing information for.
-  * pname:presentAtRelativeTime specifies whether pname:time is to be
-    interpreted as an absolute or a relative time value.
-  * pname:presentAtNearestRefreshCycle is a flag hinting at when the
-    application would like the image to be visible relative to pname:time.
-
-If pname:time is not zero, the implementation attempts to align the
-ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage with
-the time specified in pname:time according to the time domain used.
-
-If pname:presentAtNearestRefreshCycle is ename:VK_TRUE, it indicates that
-the application would prefer the presentation engine to complete the
-ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT stage at the time
-of the refresh cycle boundary that is closest to pname:time. Otherwise, if
-pname:presentAtNearestRefreshCycle is ename:VK_FALSE, it indicates that the
-application would prefer the image to not be visible earlier than
-pname:time.
+
+If pname:targetTime is not zero, the implementation attempts to align the
+ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage of
+that presentation request with the time specified in pname:targetTime
+according to the time domain used. If
+ename:VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT is not
+set in pname:flags, it indicates that the application would strictly prefer
+the image to not be visible before pname:targetTime has lapsed.
+
+[NOTE]
+.Note
+====
+Some platforms, due to hardware or system limitations, may: not be able to
+accurately time pname:targetTime with the actual physical event of the image
+becoming visible on the display. However, those timing capabilities may:
+still be useful and result in improved animation quality.
+
+As such, the <<features-presentAtAbsoluteTime, pname:presentAtAbsoluteTime>>
+and <<features-presentAtRelativeTime, pname:presentAtRelativeTime>> features
+do not provide a strict guarantee regarding the completion of the
+ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage
+relative to the pname:targetTime, and implementations must: strive to make
+it as consistent and accurate as possible.
+====
 
 [NOTE]
 .Note
@@ -111,32 +106,46 @@ cause an image to be displayed one refresh cycle later than intended.
 
 .Valid Usage
 ****
-  * If pname:presentAtRelativeTime is ename:VK_TRUE, the
+  * If pname:targetTime is not zero and pname:flags does not contain
+    ename:VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the
+    <<features-presentAtAbsoluteTime, pname:presentAtAbsoluteTime>> feature
+    must: be enabled.
+  * If pname:targetTime is not zero and pname:flags contains
+    ename:VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the
     <<features-presentAtRelativeTime, pname:presentAtRelativeTime>> feature
     must: be enabled.
 ****
 
 include::{generated}/validity/structs/VkPresentTimingInfoEXT.adoc[]
 --
 
-
-[open,refpage='VkPresentTimeEXT',desc='Specifying when an image should be presented',type='structs']
+[open,refpage='VkPresentTimingInfoFlagBitsEXT',desc='Bitmask specifying present timing info flags',type='enums']
+--
+Bits which can: be set in slink:VkPresentTimingInfoEXT::pname:flags, specifying options
+for how to interpret timing information:
+
+include::{generated}/api/enums/VkPresentTimingInfoFlagBitsEXT.adoc[]
+
+  * ename:VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT specifies
+    that sname:VkPresentTimingInfoEXT::pname:targetTime is to be interpreted
+    as a relative time from the previous presentation's
+    ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT stage. If the
+    pname:swapchain has never been used to present an image, the provided
+    pname:targetTime is ignored.
+  * ename:VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT
+    specifies that the application would prefer the image to be presented
+    earlier than the time specified in
+    sname:VkPresentTimingInfoEXT::pname:targetTime if that time falls within
+    the first half of a refresh cycle. In that case, the presentation engine
+    may: choose to display the image at the start of that refresh cycle.
 --
 
-The sname:VkPresentTimeEXT union is defined as:
-
-include::{generated}/api/structs/VkPresentTimeEXT.adoc[]
-
-  * pname:targetPresentTime, if non-zero, specifies the earliest time in
-    nanoseconds the application wants the presentation engine to complete a
-    specified target present stage. A value of zero specifies that the
-    presentation engine may: display the image at any time allowed by the
-    current present mode.
-  * pname:presentDuration specifies the minimum duration in nanoseconds that
-    must: separate the ename:VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT
-    present stages of the current and the next presentation requests, if any.
+[open,refpage='VkPresentTimingInfoFlagsEXT',desc='Bitmask of VkPresentTimingInfoFlagBitsEXT',type='flags']
+--
+include::{generated}/api/flags/VkPresentTimingInfoFlagsEXT.adoc[]
 
-include::{generated}/validity/structs/VkPresentTimeEXT.adoc[]
+tname:VkPresentTimingInfoFlagsEXT is a bitmask type for setting a mask
+of zero or more elink:VkPresentTimingInfoFlagBitsEXT.
 --
 
 [open,refpage='VkPresentStageFlagBitsEXT',desc='Bitmask specifying stages of the image presentation process',type='enums']

chapters/VK_KHR_surface/wsi.adoc

@@ -1076,21 +1076,15 @@ include::{generated}/api/structs/VkPresentTimingSurfaceCapabilitiesEXT.adoc[]
     slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface.
   * pname:presentAtAbsoluteTimeSupported indicates whether a swapchain
     created from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface
-    supports presenting images with absolute times using
-    slink:VkPresentTimeEXT::pname:targetPresentTime.
+    supports presenting images with absolute times.
   * pname:presentAtRelativeTimeSupported indicates whether a swapchain
     created from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface
-    supports presenting images with relative times using
-    slink:VkPresentTimeEXT::pname:presentDuration.
+    supports presenting images with relative times.
   * pname:presentStageQueries is a bitmask of
     elink:VkPresentStageFlagBitsEXT indicating which present stages a
     swapchain created from
     slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface is able to provide
     timing information for.
-  * pname:presentStageTargets is a bitmask of
-    elink:VkPresentStageFlagBitsEXT indicating which present stages a
-    swapchain created from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface
-    is able to provide target present times for.
 
 include::{generated}/validity/structs/VkPresentTimingSurfaceCapabilitiesEXT.adoc[]
 --

chapters/features.adoc

@@ -6536,11 +6536,9 @@ This structure describes the following feature:
   * [[features-presentTiming]] pname:presentTiming indicates that the
     implementation supports fname:vkGetPastPresentationTimingEXT.
   * [[features-presentAtAbsoluteTime]] pname:presentAtAbsoluteTime indicates
-    that the implementation supports specifying present times with
-    sname:VkPresentTimeEXT::pname:targetPresentTime.
+    that the implementation supports specifying absolute target present times.
   * [[features-presentAtRelativeTime]] pname:presentAtRelativeTime indicates
-    that the implementation supports specifying relative present times with
-    sname:VkPresentTimeEXT::pname:presentDuration.
+    that the implementation supports specifying relative target present times.
 
 :refpage: VkPhysicalDevicePresentTimingFeaturesEXT
 include::{chapters}/features.adoc[tag=features]

proposals/VK_EXT_present_timing.adoc

@@ -297,19 +297,13 @@ A new struct `VkPresentTimingsInfoEXT` can be appended to the `VkPresentInfoKHR`
 
 [source,c]
 ----
-typedef union VkPresentTimeEXT {
-    uint64_t    targetPresentTime;
-    uint64_t    presentDuration;
-} VkPresentTimeEXT;
-
 typedef struct VkPresentTimingInfoEXT {
     VkStructureType           sType;
     const void*               pNext;
-    VkPresentTimeEXT          time;
+    VkPresentTimingInfoFlags  flags;
+    uint64_t                  targetTime;
     uint64_t                  timeDomainId;
     VkPresentStageFlagsEXT    presentStageQueries;
-    VkBool32                  presentAtRelativeTime;
-    VkBool32                  presentAtNearestRefreshCycle;
 } VkPresentTimingInfoEXT;
 
 typedef struct VkPresentTimingsInfoEXT {
@@ -321,28 +315,31 @@ typedef struct VkPresentTimingsInfoEXT {
 ----
 For each swapchain referenced in `VkPresentInfoKHR`, a `VkPresentTimingInfoEXT` is specified:
 
-* `time` is the absolute or relative time used to schedule this presentation request.
+* `targetTime` is the absolute or relative time used to schedule this presentation request.
 * `timeDomainId` is the id of the time domain used to specify `time` and to query timing results.
 * `presentStageQueries` is a bitmask specifying all the present stages the application would like timings for.
-* `presentAtRelativeTime` specifies whether `time` is to be interpreted as an absolute or a relative time value.
-* `presentAtNearestRefreshCycle` specifies that the application would like to present at the refresh cycle that is nearest to the target present time.
 
-`VkPresentTimeEXT` is interpreted according to the `VkPresentTimingInfoEXT::presentAtRelativeTime` flag:
+If `presentStageQueries` is not zero, and the swapchain's internal timing queue is full, calling `vkQueuePresentKHR` yields a new error: `VK_ERROR_PRESENT_TIMING_QUEUE_FULL_EXT`.
+
+The semantics of specifying a target present time only apply to FIFO present modes (`VK_PRESENT_MODE_FIFO_KHR`, `VK_PRESENT_MODE_FIFO_RELAXED_KHR` and `VK_PRESENT_MODE_FIFO_LATEST_READY_KHR`). When attempting to dequeue a presentation request from the FIFO queue, the presentation engine checks the current time against the target time.
+
+The `VkPresentTimingInfoFlags` flags are defined as:
+[source,c]
+----
+typedef enum VkPresentTimingInfoFlagBitsEXT {
+    VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT = 0x00000001,
+    VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT = 0x00000002
+} VkPresentStageFlagBitsEXT;
+----
+`VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT` specifies whether `time` is to be interpreted as an absolute or a relative time value. If `time` is interpreted as an absolute time, it specifies the earliest time in nanoseconds at which the image should be visible. Otherwise, if it is interpreted as a relative time, it specifies the minimum duration in nanoseconds the previously presented image should be visible.
 
-* `targetPresentTime` specifies the earliest time in nanoseconds at which the image should be visible.
-* `presentDuration` specifies the minimum duration in nanoseconds the image should be visible.
+If `VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT` is set, it indicates that the application would prefer the image to be made visible during the refresh cycle that is closest to the target present time, even if that refresh cycle starts earlier than the specified `time`.
 
 [NOTE]
 ====
 More specifically, the implementation attempts to align the `VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT` present stage with the requested target present time.
 ====
 
-If `presentStageQueries` is not zero, and the swapchain's internal timing queue is full, calling `vkQueuePresentKHR` yields a new error: `VK_ERROR_PRESENT_TIMING_QUEUE_FULL_EXT`.
-
-`presentAtNearestRefreshCycle` indicates whether the application prefers that the image be visible during the refresh cycle that is closer to the target present time, or if the presentation engine should hold presentation until the target present time has strictly passed.
-
-The semantics of specifying a target present time only apply to FIFO present modes (`VK_PRESENT_MODE_FIFO_KHR`, `VK_PRESENT_MODE_FIFO_RELAXED_KHR` and `VK_PRESENT_MODE_FIFO_LATEST_READY_KHR`). When attempting to dequeue a presentation request from the FIFO queue, the presentation engine checks the current time against the target time.
-
 [NOTE]
 ====
 To maintain a constant image present duration (IPD), applications should use timing information collected via `vkGetPastPresentationTimingEXT` to determine the target time of each present. If the presentation engine is operating with a fixed refresh rate, the application's IPD should be a multiple of `VkSwapchainTimingPropertiesEXT::refreshInterval`. That is, the quanta for changing the IPD is `refreshInterval`. For example, if `refreshDuration` is 16.67ms, the IPD can be 16.67ms, 33.33ms, 50.0ms, etc.