Skip to content

Commit

Permalink
Address latest review feedback
Browse files Browse the repository at this point in the history 
- Time Domains
  - Rename vkGetSwapchainTimeDomainsEXT -> vkGetSwapchainTimeDomainPropertiesEXT
  - Add a version counter to the time domains for consistency with timing properties
  - Change VkSwapchainTimeDomainPropertiesEXT to hold a list of time domains
- Change parameters of vkGetPastPresentationTimingEXT to use new structs
  • Loading branch information
@nvlduc
nvlduc committed Jun 10, 2024
1 parent a8c62e8 commit dbdb2aa
Show file tree
Hide file tree
Showing 4 changed files with 280 additions and 189 deletions.
241 changes: 137 additions & 104 deletions chapters/VK_EXT_present_timing/queries.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,11 +81,11 @@ include::{generated}/api/protos/vkGetSwapchainTimingPropertiesEXT.adoc[]

* pname:device is the device associated with pname:swapchain.
* pname:swapchain is the swapchain to obtain timing properties for.
* pname:pSwapchainTimingProperties is a pointer to an instance of the
slink:VkSwapchainTimingPropertiesEXT structure.
* pname:pSwapchainTimingPropertiesCounter is `NULL` or a pointer to a
64-bit unsigned integer set by the implementation to the current value of
the swapchain's internal timing properties counter.
* pname:pSwapchainTimingProperties is a pointer to an instance of the
slink:VkSwapchainTimingPropertiesEXT structure.

include::{generated}/validity/protos/vkGetSwapchainTimingPropertiesEXT.adoc[]
--
Expand All @@ -103,12 +103,11 @@ include::{generated}/api/structs/VkSwapchainTimingPropertiesEXT.adoc[]
* pname:refreshDuration is zero or an indication of the duration
of a refresh cycle.
If the presentation engine is operating as an FRR display, this is the
number of nanoseconds from the start of one refresh cycle to the
start of the next refresh cycle.
If the presentation engine is operating as a VRR display
(i.e. refresh cycles may: have variable length), this is the
minimum number of nanoseconds from the start of one refresh cycle
to the start of the next refresh cycle.
number of nanoseconds from the start of one refresh cycle to the start of
the next refresh cycle.
If the presentation engine is operating as a VRR display (i.e. refresh
cycles may: have variable length), this is the minimum number of nanoseconds
from the start of one refresh cycle to the start of the next refresh cycle.
* pname:variableRefreshDelay is undefined: if pname:refreshDuration is
zero; otherwise it is a duration in nanoseconds indicating the maximum
theoretical delay for the presentation engine to start a new refresh
Expand Down Expand Up @@ -170,42 +169,34 @@ feedback of slink:VkPastPresentationTimingEXT values indicates that the
target IPD can be durably achieved.
====

[open,refpage='vkGetSwapchainTimeDomainsEXT',desc='Obtain the time domains supported by the PE for the swapchain',type='protos']
[open,refpage='vkGetSwapchainTimeDomainPropertiesEXT',desc='Obtain the time domains supported by the PE for the swapchain',type='protos']
--
The implementation maintains an internal monotonically increasing counter which
updates when the presentation engine's list of supported time domains for a
swapchain is modified.

To query the time domain used by the presentation engine for a given swapchain,
To query the time domains supported by the presentation engine for a given swapchain,
call:

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

* pname:device is the device associated with pname:swapchain.
* pname:swapchain is the swapchain to obtain timing properties for.
* pname:pSwapchainTimeDomainCount is a pointer to an integer related to the
number of time domains available or queried, as described below.
* pname:pSwapchainTimeDomains is either `NULL` or a pointer to an array of
slink:VkSwapchainTimeDomainPropertiesEXT structs, indicating the supported time
domains of the presentation engine for the swapchain.

If pname:pSwapchainTimeDomains is `NULL`, then the number of time domains
supported for the given pname:swapchain is returned in
pname:pSwapchainTimeDomainCount (if this value is zero, pname:swapchain
does not currently support display timing).
Otherwise, pname:pSwapchainTimeDomainCount must: point to a variable set by the user
to the number of elements in the pname:pSwapchainTimeDomains array, and on return
the variable is overwritten with the number of values actually written to
pname:pSwapchainTimeDomains.
If the value of pname:pSwapchainTimeDomainCount is less than the number of
time domains supported, at most pname:pSwapchainTimeDomainCount values will be
written.
If pname:pSwapchainTimeDomainCount is smaller than the number of time domains
supported for the given pname:swapchain, ename:VK_INCOMPLETE will be returned
instead of ename:VK_SUCCESS to indicate that not all the available values
were returned.

include::{generated}/validity/protos/vkGetSwapchainTimeDomainsEXT.adoc[]
* pname:swapchain is the swapchain to obtain time domain properties for.
* pname:pTimeDomainsCounter is `NULL` or a pointer to a 64-bit unsigned
integer set by the implementation to the current value of the
swapchain's internal time domain properties counter.
* pname:pSwapchainTimeDomainProperties is a pointer to an instance of the
slink:VkSwapchainTimeDomainPropertiesEXT structure.

If upon return slink:VkSwapchainTimeDomainPropertiesEXT::pname:timeDomainCount
is smaller than the number of time domains supported for the given
pname:swapchain, ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS to indicate that not all the available values were returned.

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

[open,refpage='VkSwapchainTimeDomainPropertiesEXT',desc='An available time domain for a swapchain',type='structs']
[open,refpage='VkSwapchainTimeDomainPropertiesEXT',desc='List of available time domains for a swapchain',type='structs']
--

The sname:VkSwapchainTimeDomainPropertiesEXT structure is defined as:
Expand All @@ -215,20 +206,30 @@ include::{generated}/api/structs/VkSwapchainTimeDomainPropertiesEXT.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:timeDomain is a elink:VkTimeDomainEXT value representing a time
domain that is available for the swapchain.
* pname:timeDomainId is a unique identifier for this time domain within a
swapchain's namespace.
* pname:timeDomainCount is an integer related to the number of time domains
available or queried, as described below.
* pname:pTimeDomains is a pointer to an array of elink:VkTimeDomainEXT values
representing time domains that are available for the swapchain.
* pname:pTimeDomainIds is a pointer to an array of unique identifiers for each
time domain.

When calling flink:vkGetSwapchainTimeDomainPropertiesEXT, if pname:pTimeDomains
is `NULL` and pname:pTimeDomainIds is `NULL`, then the number of time domains
supported for the given pname:swapchain is returned in
pname:timeDomainCount. Otherwise, pname:timeDomainCount must: specify the number
of elements in the pname:pTimeDomains, pname:pTimeDomainIds, or both arrays, and
on return the variable is overwritten with the number of values actually written
to either array.

[NOTE]
.Note
====
Due to the dynamic nature of their underlying sname:VkSurfaceKHR properties,
swapchains may need to expose multiple swapchain-local opaque time domains
using the same elink:VkTimeDomainEXT value, for example when a surface is
moved from one display hardware to another. Arbitrary identifiers, provided
in pname:timeDomainId, are used by the implementation to differentiate opaque
time domains of identical scopes.
swapchains may need to expose multiple swapchain-local opaque time domains using
the same elink:VkTimeDomainEXT value over time, for example when a surface is
moved from one display hardware to another. Arbitrary identifiers, provided in
pname:timeDomainIds, are used by the implementation to differentiate opaque time
domains of identical scopes.
====

include::{generated}/validity/structs/VkSwapchainTimeDomainPropertiesEXT.adoc[]
Expand All @@ -238,8 +239,8 @@ include::{generated}/validity/structs/VkSwapchainTimeDomainPropertiesEXT.adoc[]
--

Because of the asynchronous nature of the presentation engine, the timing
information for a given flink:vkQueuePresentKHR command only becomes
available some time later.
information for a given flink:vkQueuePresentKHR command may: only becomes
available some time after the presentation has occured.
These time values should: be asynchronously queried, and are returned if
available.
All time values are in nanoseconds, according to the time-domain being used.
Expand All @@ -250,32 +251,86 @@ information about one or more previous presents to a given swapchain, call:
include::{generated}/api/protos/vkGetPastPresentationTimingEXT.adoc[]

* pname:device is the device associated with pname:swapchain.
* pname:pPastPresentationTimingInfo is a pointer to an instance of
the slink:VkPastPresentationTimingInfoEXT structure.
* pname:pPastPresentationTimingProperties is a pointer to an instance
of the slink:VkPastPresentationTimingPropertiesEXT structure.

If upon return the value of
sname:VkPastPresentationTimingPropertiesEXT::pname:presentationTimingCount is
less than the number of available timing records for the given
sname:VkPastPresentationTimingInfoEXT::pname:swapchain, ename:VK_INCOMPLETE is
returned instead of ename:VK_SUCCESS to indicate that not all the available
values were returned.

Timing information may: become available out of order with regards to their
associated presentation request submission order.

Upon return, zero or more slots of the pname:swapchain internal timing results
queue, equal to the number of entries written to
sname:VkPastPresentationTimingPropertiesEXT::pname:pPresentationTimings for
which pname:reportComplete is ename:VK_TRUE, are made available for future
fname:vkQueuePresentKHR calls. Elements of pname:pPresentationTimings are
arranged in ascending order of present ids.

There is no requirement for any precise timing relationship between the
completion of a present stage and the availability of any associated timing
information. However, results must: be made available in finite time.

As an exception to the normal rules for objects which are externally
synchronized, pname:swapchain may: be
simultaneously used by other threads in calls to functions other than
flink:vkDestroySwapchainKHR and flink:vkCreateSwapchainKHR with pname:swapchain
used as an pname:oldSwapchain. Access to the swapchain timing information must:
be atomic within the implementation.

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

[open,refpage='VkPastPresentationTimingInfoEXT',desc='Structure specifying swapchain present timing query parameters',type='structs']
--

The sname:VkPastPresentationTimingInfoEXT structure is defined as:

include::{generated}/api/structs/VkPastPresentationTimingInfoEXT.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:swapchain is the swapchain to obtain presentation timing
information duration for.
* pname:pPresentationTimingCount is a pointer to an integer related to the
number of slink:VkPastPresentationTimingEXT structures to query, as
information for.

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

[open,refpage='VkPastPresentationTimingPropertiesEXT',desc='Structure containing details about a swapchain past presentation activity',type='structs']
--

The sname:VkPastPresentationTimingPropertiesEXT structure is defined as:

include::{generated}/api/structs/VkPastPresentationTimingPropertiesEXT.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:timingPropertiesCounter is a 64-bit unsigned integer set by the
implementation to the current value of the swapchain's internal timing
properties counter.
* pname:timeDomainsCounter is a 64-bit unsigned integer set by the
implementation to the current value of the swapchain's internal time
domains list counter.
* pname:presentationTimingCount is an integer related to the number of number
of slink:VkPastPresentationTimingEXT structures available or queried, as
described below.
* pname:pPresentationTimings is `NULL` or a pointer to an an array
* pname:pPresentationTimings is `NULL` or a pointer to an array
of slink:VkPastPresentationTimingEXT structures.
* pname:pSwapchainTimingPropertiesCounter is `NULL` or a pointer to a
64-bit unsigned integer set by the implementation to the current value of
the swapchain's internal timing properties counter.
* pname:pTimeDomainsChanged is `NULL` or a pointer to a boolean value
indicating if the list of supported time domains supported by the
pname:swapchain has changed since the last call to this function.

If pname:pPresentationTimings is `NULL`, then the number of available
timing records for the given pname:swapchain is returned in
pname:pPresentationTimingCount.
Otherwise, pname:pPresentationTimingCount must: point to a variable set by
the user to the number of elements in the pname:pPresentationTimings array,
and on return the variable is overwritten with the number of structures
actually written to pname:pPresentationTimings.
If the value of pname:pPresentationTimingCount is less than the number of
newly-available timing records for the given pname:swapchain, at most
pname:pPresentationTimingCount structures are written, and
ename:VK_INCOMPLETE is returned instead of ename:VK_SUCCESS to indicate that
not all the available values were returned.

When calling flink:vkGetPastPresentationTimingEXT, if pname:pPresentationTimings
is `NULL`, then the number of available timing records for the given
pname:swapchain is returned in pname:presentationTimingCount. Otherwise,
pname:presentationTimingCount must: specify the number of elements in the
pname:pPresentationTimings array, and on return the variable is overwritten with
the number of structures actually written to pname:pPresentationTimings.

fname:vkGetPastPresentationTimingEXT may: return incomplete results,
containing only information for a subset of the requested present
Expand All @@ -288,30 +343,7 @@ every flink:vkQueuePresentKHR referencing pname:swapchain where a non-zero
slink:VkPresentTimingInfoEXT::pname:presentStageQueries was specified and at
least one present stage has available results.

If pname:pTimeDomainsChanged is ename:VK_TRUE, applications should: query
the new list of available time domains with flink:vkGetSwapchainTimeDomainsEXT.

Timing information may: become available out of order with regards to their
associated presentation request submission order.

Upon return, zero or more slots of the pname:swapchain internal timing
results queue, equal to the number of entries written to
pname:pPresentationTimings for which pname:reportComplete is ename:VK_TRUE,
are made available for future fname:vkQueuePresentKHR calls. Elements of
pname:pPresentationTimings are arranged in ascending order of present ids.

There is no requirement for any precise timing relationship between the
completion of a present stage and the availability of any associated timing
information.

As an exception to the normal rules for objects which are externally
synchronized, pname:swapchain may: be simultaneously used by other threads
in calls to functions other than flink:vkDestroySwapchainKHR and
flink:vkCreateSwapchainKHR with pname:swapchain used as an
pname:oldSwapchain. Access to the swapchain timing information must: be
atomic within the implementation.

include::{generated}/validity/protos/vkGetPastPresentationTimingEXT.adoc[]
include::{generated}/validity/structs/VkPastPresentationTimingPropertiesEXT.adoc[]
--

[open,refpage='VkPastPresentationTimingEXT',desc='Structure containing timing information about a previously-presented image',type='structs']
Expand All @@ -332,8 +364,9 @@ include::{generated}/api/structs/VkPastPresentationTimingEXT.adoc[]
* pname:pPresentStages a pointer to an array of
slink:VkPresentStageTimeEXT providing timing information for the
presentation request associated with pname:presentId.
* pname:timeDomainId is the id of the time domain used by the presentation
* pname:timeDomain is the time domain used by the presentation
engine to report times in pname:pPresentStages.
* pname:timeDomainId is the id associated with pname:timeDomain.
* pname:reportComplete is ename:VK_TRUE if the presentation engine
has reported all the requested results in pname:pPresentStages.

Expand All @@ -351,15 +384,15 @@ For systems with multiple entities operating within the presentation
engine, such as multiple displays, pname:pPresentStages will return timing
results for at least one entity which has been affected by the presentation.

pname:timeDomain may: be different than the time domain that was specified
in slink:VkPresentTimingInfoEXT::pname:timeDomain if the requirements for
using this time domain could not be met at the time the presentation engine
processed the presentation request. In such a case, the presentation engine
may: pick a time domain to fall back to and report results in that domain.
Applications can: continue to use this fallback time domain in future
pname:timeDomain may: be different than the time domain that was specified in
slink:VkPresentTimingInfoEXT::pname:timeDomain if the requirements for using
this time domain could not be met at the time the presentation engine processed
the presentation request. In such a case, the presentation engine may: pick a
time domain to fall back to, if one is available, and report results in that
domain. Applications can: continue to use this fallback time domain in future
flink:vkQueuePresentKHR calls, or they can: call
flink:vkGetSwapchainTimeDomainsEXT to choose from the currently supported
time domains.
flink:vkGetSwapchainTimeDomainPropertiesEXT to choose from the currently
supported time domains.

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

Expand Down Expand Up @@ -408,7 +441,7 @@ full-screen, the timing properties may: be VRR.
The available time domains for a swapchain may: change for similar or
identical reasons.
Therefore, it is possible that the same event will cause both
pname:timingPropertiesChanged to become ename:VK_TRUE and and
pname:timingPropertiesChanged to become ename:VK_TRUE and
pname:timeDomain to be different than the time domain requested in
slink:VkPresentTimingInfoEXT.
====
Expand Down
2 changes: 1 addition & 1 deletion chapters/synchronization.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7801,7 +7801,7 @@ include::{generated}/api/structs/VkSwapchainCalibratedTimestampInfoEXT.adoc[]
* pname:timeDomainId is the id for the opaque time domain being calibrated.

pname:timeDomainId must: be an id previously reported by
flink:vkGetSwapchainTimeDomainsEXT for pname:swapchain. If the
flink:vkGetSwapchainTimeDomainPropertiesEXT for pname:swapchain. If the
pname:timeDomainId is no longer supported by the pname:swapchain,
implementations may: report zero as the calibrated timestamp value.

Expand Down
Loading

0 comments on commit dbdb2aa

Please sign in to comment.