status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-17 16:57:09 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt
Jon Leech ce60b9c887 Change log for March 7, 2018 Vulkan 1.1.70 spec update: 
* Vulkan 1.1 initial release. Bump API patch number and header version
    number to 70 for this update. The patch number will be used for both
    Vulkan 1.1 and Vulkan 1.0 updates, and continues to increment
    continuously from the previous Vulkan 1.0.69 update.

    NOTE: We are not publishing an updated 1.0.70 specification, or 1.1
    reference pages, along with 1.1.70. There are still minor issues to work
    out with those build targets. However, we will soon generate all three
    types of documents as part of the regular spec update cycle.

    NOTE: The GitHub KhronosGroup/Vulkan-Docs repository now maintains the
    current specification in the `master` branch. The `1.0` branch is out of
    date and will not be maintained, since we will be generating both 1.1
    and 1.0 specifications from the `master` branch in the future.

Github Issues:

  * Clarify how mapped memory ranges are flushed in
    flink:vkFlushMappedMemoryRanges (public issue 127).
  * Specify that <<synchronization-pipeline-stages, Pipeline Stages>> are a
    list of tasks that each command performs, rather than necessarily being
    discrete pieces of hardware that one task flows through. Add a
    "`synchronization command`" pipeline type which all synchronization
    command execute (it's just TOP + BOTTOM), with an explanatory note
    (public issue 554).

Internal Issues:

  * Regenerate all images used in the spec in Inkscape with a consistent
    look-and-feel, and adjust image size attributes so they're all legible,
    and not too large with respect to the spec body text (internal issue
    701).
  * Document in the <<extensions,extensions>> appendix and in the style
    guide that `KHX` extensions are no longer supported or used in the
    Vulkan 1.1 timeframe (internal issue 714).
  * Remove the leftover equations_temp directory after PDF build completes
    (internal issue 925).
  * Update the <<credits, Credits (Informative)>> appendix to include
    contributors to Vulkan 1.1, and to list them according to the API
    version(s) they contributed to (internal issue 987).
  * Add a NOTE to the introduction explaining that interfaces defined by
    extensions which were promoted to Vulkan 1.1 are now expressed as
    aliases of the Vulkan 1.1 type (internal issue 991).
  * Instrument spec source conditionals so spec can be built with 1.1
    features, extensions promoted to 1.1, or both (internal issues 992,
    998).
  * Modify the XML schema and tools to support explicit aliasing of types,
    structures, and commands, and use this to express the promotion of 1.0
    extensions to 1.1 core features, by making the extension interfaces
    aliases of the core features they were promoted to. Mark up promoted
    interfaces to allow still generating 1.0 + extension specifications
    (internal issue 991).
  * Platform names, along with corresponding preprocessor symbols to enable
    extensions specific to those platforms, are now reserved in vk.xml using
    the <platform> tag. Update the registry schema and schema specification
    to match (internal issue 1011).
  * Updated the <<textures-texel-replacement, Texel Replacement>> section to
    clarify that reads from invalid texels for image resources result in
    undefined values (internal issue 1014).
  * Modify description of patch version so it continues to increment across
    minor version changes (internal issue 1033).
  * Clarify and unify language describing physical device-level core and
    extension functionality in the <<fundamentals-validusage-extensions,
    Valid Usage for Extensions>>, <<fundamentals-validusage-versions, Valid
    Usage for Newer Core Versions>>, <<initialization-functionpointers
    Command Function Pointers>>, <<initialization-phys-dev-extensions,
    Extending Physical Device From Device Extensions>>
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> sections and for
    flink:vkGetPhysicalDeviceImageFormatProperties2. This documents that
    instance-level functionality is tied to the loader, and independent of
    the ICD; physical device-level functionality is tied to the ICD, and
    associated with device extensions; physical devices are treated more
    uniformly between core and extensions; and instance and physical
    versions can be different (internal issue 1048).
  * Updated the <<commandbuffers-lifecycle, Command Buffer Lifecycle>>
    section to clarify the ability for pending command buffers to transition
    to the invalid state after submission, and add a command buffer
    lifecycle diagram (internal issue 1050).
  * Clarify that some flink:VkDescriptorUpdateTemplateCreateInfo parameters
    are ignored when push descriptors are not supported (internal issue
    1054).
  * Specify that flink:vkCreateImage will return an error if the image is
    too large, in a NOTE in the slink:VkImageFormatProperties description
    (internal issue 1078).
  * Remove near-duplicate NOTEs about when to query function pointers
    dynamically in the <<initialization, Initialization>> chapter and
    replace by extending the NOTE in the <<fundamentals-abi, Application
    Binary Interface>> section (internal issue 1085).
  * Restore missing references to "`Sparse Resource Features`" in the
    flink:VkBufferCreateFlagBits description (internal issue 1086).
  * Tidy up definitions of descriptor types in the `GL_KHR_vulkan_glsl`
    specification, the <<descriptorsets, Resource Descriptors>> section and
    its subsections, and the <<interfaces-resources-descset, Descriptor Set
    Interface>> for consistency, reduction of duplicate information, and
    removal of GLSL correspondance/examples (internal issue 1090).
  * Correctly describe code:PrimitiveId as an Input for tessellation control
    and evaluation shaders, not an Output (internal issue 1109).
  * Relax the requirements on chroma offsets for nearest filtering in
    <<textures-implict-reconstruction, Implicit Reconstruction>> (internal
    issue 1116).

Other Issues:

  * Clarify the intended relationship between specification language and
    certain terms defined in the Khronos Intellectual Property Rights
    policy. Specific changes include:
  ** Rewrote IP/Copyright preamble and introduction to better agree with
     normative language both as laid out in the introduction, and the
     Khronos IPR policy.
  ** Added notion of fully informative sections, which are now tagged with
     "`(Informative)`" in their titles.
  ** Removed non-normative uses of the phrase "`not required`"
  ** Clarified the distinction between terms "`optional`" and "`not
     required:`" as they relate to the IPR Policy, and updated specification
     text to use terms consistent with the intent.
  ** Reduced additions to RFC 2119, and ensured the specification agreed
     with the leaner language.
  ** Removed the terms "`hardware`", "`software`", "`CPU`", and "`GPU`" from
     normative text.
  ** Moved several paragraphs that should not have been normative to
     informative notes.
  ** Clarified a number of definitions in the Glossary.
  ** Updated the document writing guide to match new terminology changes.
  * Explicitly state in the <<fundamentals-objectmodel-lifetime-acquire,
    application memory lifetime>> language that that for objects other than
    descriptor sets, a slink:VkDescriptorSetLayout object used in the
    creation of another object (such as slink:VkPipelineLayout or
    slink:VkDescriptorUpdateTemplateKHR) is only in use during the creation
    of that object and can be safely destroyed afterwards.
  * Updated the <<textures-scale-factor, Scale Factor Operation>> section to
    use the ratio of anisotropy, rather than the integer sample rate, to
    perform the LOD calculation. The spec still allows use of the sample
    rate as the value used to calculate the LOD, but no longer requires it.
  * Update `vulkan_ext.c` to include all platform-related definitions from
    the Vulkan platform headers, following the split of the headers into
    platform-specific and non-platform-specific files.
  * Fix bogus anchor name in the <<commandbuffers, Command Buffers>> chapter
    which accidentally duplicated an anchor in the pipelines chapter. There
    were no reference to this anchor, fortunately.
  * Add valid usage statement for slink:VkWriteDescriptorSet and
    slink:VkCopyDescriptorSet requiring that the slink:VkDescriptorSetLayout
    used to allocate the source and destination sets must not have been
    destroyed at the time flink:vkUpdateDescriptorSets is called.
  * Document mapping of subgroup barrier functions to SPIR-V, and clarify a
    place where subgroupBarrier sounds like it's execution-only in the
    standalone `GL_KHR_shader_subgroup` specification.
  * Use an HTML stylesheet derived from the Asciidoctor `colony` theme, with
    the default Arial font family replaced by the sans-serif Noto font
    family.
  * Numerous minor updates to README.adoc, build scripts, Makefiles, and
    registry and style guide specifications to support Vulkan 1.1 outputs,
    use them as defaults, and remove mention of `KHX` extensions, which are
    no longer supported.

New Extensions:

  * `VK_EXT_vertex_attrib_divisor`
2018-03-07 04:18:52 -08:00

269 lines
13 KiB
Plaintext
Raw Blame History

// Copyright (c) 2016-2018 Google Inc. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
== Display Timing Queries
Traditional game and real-time-animation applications frequently use
ename:VK_PRESENT_MODE_FIFO_KHR so that presentable images are updated during
the vertical blanking period of a given refresh cycle (RC) of the
presentation engine's display.
This avoids the visual anomaly known as tearing.
However, synchronizing the presentation of images with the RC does not
prevent all forms of visual anomalies.
Stuttering occurs when the geometry for each presentable image isn't
accurately positioned for when that image will be displayed.
The geometry may appear to move too little some RCs, and too much for
others.
Sometimes the animation appears to freeze, when the same image is used for
more than one RC.
In order to minimize stuttering, an application needs to correctly position
their geometry for when the presentable image will be displayed to the user.
To accomplish this, applications need various timing information about the
presentation engine's display.
They need to know when presentable images were actually presented, and when
they could have been presented.
Applications also need to tell the presentation engine to display an image
no sooner than a given time.
This can allow the application's animation to look smooth to the user, with
no stuttering.
The `VK_GOOGLE_display_timing` extension allows an application to satisfy
these needs.
The presentation engine's display typically refreshes the pixels that are
displayed to the user on a periodic basis.
The period may be fixed or variable.
In many cases, the presentation engine is associated with fixed refresh rate
(FRR) display technology, with a fixed refresh rate (RR, e.g. 60Hz).
In some cases, the presentation engine is associated with variable refresh
rate (VRR) display technology, where each refresh cycle (RC) can vary in
length.
This extension treats VRR displays as if they are FRR.
[open,refpage='vkGetRefreshCycleDurationGOOGLE',desc='Obtain the RC duration of the PE\'s display',type='protos']
--
To query the duration of a refresh cycle (RC) for the presentation engine's
display, call:
include::../../api/protos/vkGetRefreshCycleDurationGOOGLE.txt[]
* pname:device is the device associated with pname:swapchain.
* pname:swapchain is the swapchain to obtain the refresh duration for.
* pname:pDisplayTimingProperties is a pointer to an instance of the
sname:VkRefreshCycleDurationGOOGLE structure.
include::../../validity/protos/vkGetRefreshCycleDurationGOOGLE.txt[]
--
[open,refpage='VkRefreshCycleDurationGOOGLE',desc='Structure containing the RC duration of a display',type='structs']
--
The sname:VkRefreshCycleDurationGOOGLE structure is defined as:
include::../../api/structs/VkRefreshCycleDurationGOOGLE.txt[]
* pname:refreshDuration is the number of nanoseconds from the start of one
refresh cycle to the next.
include::../../validity/structs/VkRefreshCycleDurationGOOGLE.txt[]
--
[NOTE]
.Note
====
The rate at which an application renders and presents new images is known as
the image present rate (IPR, aka frame rate).
The inverse of IPR, or the duration between each image present, is the image
present duration (IPD).
In order to provide a smooth, stutter-free animation, an application will
want its IPD to be a multiple of pname:refreshDuration.
For example, if a display has a 60Hz refresh rate, pname:refreshDuration
will be a value in nanoseconds that is approximately equal to 16.67ms.
In such a case, an application will want an IPD of 16.67ms (1X multiplier of
pname:refreshDuration), or 33.33ms (2X multiplier of pname:refreshDuration),
or 50.0ms (3X multiplier of pname:refreshDuration), etc.
In order to determine a target IPD for a display (i.e. a multiple of
pname:refreshDuration), an application needs to determine when its images
are actually displayed.
Let's say that an application has an initial target IPD of 16.67ms (1X
multiplier of pname:refreshDuration).
It will therefore position the geometry of a new image 16.67ms later than
the previous image.
Let's say that this application is running on slower hardware, so that it
actually takes 20ms to render each new image.
This will create visual anomalies, because the images won't be displayed to
the user every 16.67ms, nor every 20ms.
In this case, it is better for the application to adjust its target IPD to
33.33ms (i.e. a 2X multiplier of pname:refreshDuration), and tell the
presentation engine to not present images any sooner than every 33.33ms.
This will allow the geometry to be correctly positioned for each presentable
image.
Adjustments to an application's IPD may be needed because different views of
an application's geometry can take different amounts of time to render.
For example, looking at the sky may take less time to render than looking at
multiple, complex items in a room.
In general, it is good to not frequently change IPD, as that can cause
visual anomalies.
Adjustments to a larger IPD because of late images should happen quickly,
but adjustments to a smaller IPD should only happen if the
pname:actualPresentTime and pname:earliestPresentTime members of the
slink:VkPastPresentationTimingGOOGLE structure are consistently different,
and if pname:presentMargin is consistently large, over multiple images.
====
[open,refpage='vkGetPastPresentationTimingGOOGLE',desc='Obtain timing of a previously-presented image',type='protos']
--
The implementation will maintain a limited amount of history of timing
information about previous presents.
Because of the asynchronous nature of the presentation engine, the timing
information for a given flink:vkQueuePresentKHR command will become
available some time later.
These time values can be asynchronously queried, and will be returned if
available.
All time values are in nanoseconds, relative to a monotonically-increasing
clock (e.g. `CLOCK_MONOTONIC` (see clock_gettime(2)) on Android and Linux).
To asynchronously query the presentation engine, for newly-available timing
information about one or more previous presents to a given swapchain, call:
include::../../api/protos/vkGetPastPresentationTimingGOOGLE.txt[]
* pname:device is the device associated with pname:swapchain.
* 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 sname:VkPastPresentationTimingGOOGLE structures to query, as
described below.
* pname:pPresentationTimings is either `NULL` or a pointer to an an array
of sname:VkPastPresentationTimingGOOGLE structures.
If pname:pPresentationTimings is `NULL`, then the number of newly-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, at most pname:pPresentationTimingCount
structures will be written.
If pname:pPresentationTimingCount is smaller than the number of
newly-available timing records 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::../../validity/protos/vkGetPastPresentationTimingGOOGLE.txt[]
--
[open,refpage='VkPastPresentationTimingGOOGLE',desc='Structure containing timing information about a previously-presented image',type='structs']
--
The sname:VkPastPresentationTimingGOOGLE structure is defined as:
include::../../api/structs/VkPastPresentationTimingGOOGLE.txt[]
* pname:presentID is an application-provided value that was given to a
previous fname:vkQueuePresentKHR command via
slink:VkPresentTimeGOOGLE::pname:presentID (see below).
It can: be used to uniquely identify a previous present with the
flink:vkQueuePresentKHR command.
* pname:desiredPresentTime is an application-provided value that was given
to a previous flink:vkQueuePresentKHR command via
slink:VkPresentTimeGOOGLE::pname:desiredPresentTime.
If non-zero, it was used by the application to indicate that an image
not be presented any sooner than pname:desiredPresentTime.
* pname:actualPresentTime is the time when the image of the
pname:swapchain was actually displayed.
* pname:earliestPresentTime is the time when the image of the
pname:swapchain could have been displayed.
This may: differ from pname:actualPresentTime if the application
requested that the image be presented no sooner than
slink:VkPresentTimeGOOGLE::pname:desiredPresentTime.
* pname:presentMargin is an indication of how early the
fname:vkQueuePresentKHR command was processed compared to how soon it
needed to be processed, and still be presented at
pname:earliestPresentTime.
The results for a given pname:swapchain and pname:presentID are only
returned once from fname:vkGetPastPresentationTimingGOOGLE.
The application can: use the fname:VkPastPresentationTimingGOOGLE values to
occasionally adjust its timing.
For example, if pname:actualPresentTime is later than expected (e.g. one
pname:refreshDuration late), the application may increase its target IPD to
a higher multiple of pname:refreshDuration (e.g. decrease its frame rate
from 60Hz to 30Hz).
If pname:actualPresentTime and pname:earliestPresentTime are consistently
different, and if pname:presentMargin is consistently large enough, the
application may decrease its target IPD to a smaller multiple of
pname:refreshDuration (e.g. increase its frame rate from 30Hz to 60Hz).
If pname:actualPresentTime and pname:earliestPresentTime are same, and if
pname:presentMargin is consistently high, the application may delay the
start of its input-render-present loop in order to decrease the latency
between user input and the corresponding present (always leaving some margin
in case a new image takes longer to render than the previous image).
An application that desires its target IPD to always be the same as
pname:refreshDuration, can also adjust features until
pname:actualPresentTime is never late and pname:presentMargin is
satisfactory.
--
The full `VK_GOOGLE_display_timing` extension semantics are described for
swapchains created with ename:VK_PRESENT_MODE_FIFO_KHR.
For example, non-zero values of
sname:VkPresentTimeGOOGLE::pname:desiredPresentTime must: be honored, and
fname:vkGetPastPresentationTimingGOOGLE should: return a
sname:VkPastPresentationTimingGOOGLE structure with valid values for all
images presented with fname:vkQueuePresentKHR.
The semantics for other present modes are as follows:
* ename:VK_PRESENT_MODE_IMMEDIATE_KHR.
The presentation engine may: ignore non-zero values of
sname:VkPresentTimeGOOGLE::pname:desiredPresentTime in favor of
presenting immediately.
The value of
sname:VkPastPresentationTimingGOOGLE::pname:earliestPresentTime must: be
the same as
sname:VkPastPresentationTimingGOOGLE::pname:actualPresentTime, which
should: be when the presentation engine displayed the image.
* ename:VK_PRESENT_MODE_MAILBOX_KHR.
The intention of using this present mode with this extension is to
handle cases where an image is presented late, and the next image is
presented soon enough to replace it at the next vertical blanking
period.
For images that are displayed to the user, the value of
sname:VkPastPresentationTimingGOOGLE::pname:actualPresentTime must: be
when the image was displayed.
For images that are not displayed to the user,
fname:vkGetPastPresentationTimingGOOGLE may: not return a
sname:VkPastPresentationTimingGOOGLE structure, or it may: return return
a sname:VkPastPresentationTimingGOOGLE structure with the value of zero
for both sname:VkPastPresentationTimingGOOGLE::pname:actualPresentTime
and sname:VkPastPresentationTimingGOOGLE::pname:earliestPresentTime.
It is possible that an application can: submit images with
sname:VkPresentTimeGOOGLE::pname:desiredPresentTime values such that new
images may: not be displayed.
For example, if sname:VkPresentTimeGOOGLE::pname:desiredPresentTime is
far enough in the future that an image is not presented before
fname:vkQueuePresentKHR is called to present another image, the first
image will not be displayed to the user.
If the application continues to do that, the presentation may: not
display new images.
* 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_RELAXED_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
sname:VkPastPresentationTimingGOOGLE 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.
Reference in New Issue View Git Blame Copy Permalink