From 9e11c718ad958783a761c25a8da5f0ffa041e4dd Mon Sep 17 00:00:00 2001 From: Alexandros Frantzis Date: Thu, 30 Apr 2020 15:35:22 +0300 Subject: [PATCH] WIP: RFC: present-timing: Enhanced presentation timing requests and events This a protocol that offers enhanced presentation timing requests and events, in order to help clients minimize visual anomalies. It is modeled after the WIP VK_KHR_present_timing extension. Signed-off-by: Alexandros Frantzis --- unstable/present-timing/README | 4 + .../present-timing-unstable-v1.xml | 313 ++++++++++++++++++ unstable/present-timing/present-timing.rst | 43 +++ 3 files changed, 360 insertions(+) create mode 100644 unstable/present-timing/README create mode 100644 unstable/present-timing/present-timing-unstable-v1.xml create mode 100644 unstable/present-timing/present-timing.rst diff --git a/unstable/present-timing/README b/unstable/present-timing/README new file mode 100644 index 0000000..074c8a3 --- /dev/null +++ b/unstable/present-timing/README @@ -0,0 +1,4 @@ +Present timing protocol + +Maintainers: +Alexandros Frantzis diff --git a/unstable/present-timing/present-timing-unstable-v1.xml b/unstable/present-timing/present-timing-unstable-v1.xml new file mode 100644 index 0000000..caa5f13 --- /dev/null +++ b/unstable/present-timing/present-timing-unstable-v1.xml @@ -0,0 +1,313 @@ + + + + + Copyright © 2020 Collabora, Ltd. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + + + + This protocol extension allows an application to obtain per-surface + presentation properties (e.g. the refresh period), get timing + information about each present, and to schedule a present to happen + no earlier than a desired time. An application can use this to + minimize various visual anomalies (e.g. stuttering). + + This protocol extension is modeled after the VK_EXT_present_timing + extension. + + + + + Informs the server that the client will no longer be using + this protocol object. Existing objects created by this object + are not affected. + + + + + + Requests a new zwp_surface_present_timing_v1 object for the given + surface. + + If the associated wl_surface object becomes invalid, the + zwp_surface_present_timing_v1 becomes inert and the client should + destroy it by calling zwp_surface_present_timing.destroy. + + + + + + + + This event tells the client in which clock domain the + compositor interprets the timestamps used by the presentation + extension. This clock is called the presentation clock. + + The compositor sends this event when the client binds to the + present_timing interface. The presentation clock does not change + during the lifetime of the client connection. + + The clock identifier is platform dependent. On Linux/glibc, + the identifier value is one of the clockid_t values accepted + by clock_gettime(). clock_gettime() is defined by + POSIX.1-2001. + + Timestamps in this clock domain are expressed as tv_sec_hi, + tv_sec_lo, tv_nsec triples, each component being an unsigned + 32-bit value. Whole seconds are in tv_sec which is a 64-bit + value combined from tv_sec_hi and tv_sec_lo, and the + additional fractional part in tv_nsec as nanoseconds. Hence, + for valid timestamps tv_nsec must be in [0, 999999999]. + + Note that clock_id applies only to the presentation clock, + and implies nothing about e.g. the timestamps used in the + Wayland core protocol input events. + + Compositors should prefer a clock which does not jump and is + not slewed e.g. by NTP. The absolute value of the clock is + irrelevant. Precision of one millisecond or better is + recommended. Clients must be able to query the current clock + value directly, not by asking the compositor. + + + + + + + + + An object that allows clients to receive presentation related + properties for a surface, set presentation timing parameters + for a present, and request timing feedback for a present. + + + + + Informs the server that the client will no longer be using + this protocol object. Existing objects created by this object + are not affected. + + + + + + Sets the target present time for the next content submission of + the associated wl_surface. + + The target present time is the earliest time point at which the + compositor should present the submitted contents. For best results + on fixed rate displays this should be set to T + n*R, where T is the + previous content presentation time for this surface, and n*R is an + integer multiple of the refresh period (see + zwp_surface_present_timing_v1.timing_properties). + + Note that if a present_slop value has been set, the compositor + may choose to present earlier than target present time if some + conditions are met (see zwp_surface_present_timing_v1.set_present_slop + for details). + + If the target present time is zero or has not been set, this + extension does not affect the compositor's timings on presenting + the content submission. + + The target present time is interpreted according to the active clock + domain (see zwp_present_timing_v1.clock_id). + + The target present time is double-buffered state, and will be applied + on the next wl_surface.commit request for the associated surface. + + + + + + + + + Sets the ideal present time for the next content submission of + the associated wl_surface. + + The ideal present time provides an indication to the compositor + of what the client desires its presentation duration to become. + An application the ideal present time to the same value as + target present time, indicating that the client desires its + presentation duration to remain steady. A value earlier than + the target present time that the client desires to shorten its + presentation duration. A value later than the target present time + indicates that the application desires to lengthen its presentation + duration. + + The compositor will provide feedback on this value in the data returned + in zwp_present_time_feedback_v1. The client can use this information to + adapt future target present times. + + An unset ideal present time, or a value of zero, indicates no particular + preference about what the clients desires in terms of presentation rate. + + Setting the ideal present time to timepoint zero, indicates to the + compositor that no evaluation is needed. + + The ideal present time is double-buffered state, and will be applied + on the next wl_surface.commit request for the associated surface. + + + + + + + + + Sets the duration of a time period before the target present time, + in which the compositor may choose to present the submitted contents + if it overlaps with the vsync period on fixed refresh rate displays. + + This is used to avoid unintentionally missing a vertical blanking + period on FRR displays due to rounding errors or drift between + clocks. + + The present slop is interpreted according to the active clock + domain (see zwp_present_timing_v1.clock_id). + + The present slop is double-buffered state, and will be applied + on the next wl_surface.commit request for the associated surface. + + + + + + + + + + + + + + + The refresh period is an indication of the duration of a present/refresh + cycle as it applies for the associated surface. The period is interpreted + according to the active clock domain (see zwp_present_timing_v1.clock_id). + + If presentation occurs at a fixed rate, this is the interval from the start + of one refresh cycle to the start of the next refresh cycle. + + If presentation may occur at a variable rate (i.e. refresh cycles may + have variable length), this is the minimum interval from the + start of one refresh cycle to the start of the next refresh cycle. + + The refresh_type argument indicates whether presentation occurs in a + fixed or variable rate. + + This event is emitted once the compositor has enough information to evaluate + the refresh period and refresh type, and whenever these properties change. + + + + + + + + + + Request presentation feedback for the next content submission + on the given surface. This creates a new presentation_feedback + object, which will deliver the feedback information once. If + multiple presentation_feedback objects are created for the same + submission, they will all deliver the same information. + + For details on what information is returned, see the + zwp_present_timing_feedback_v1 interface. + + + + + + + + + Timing information about a present. + + + + + The associated content update was displayed to the user at the + indicated actual time (actual_tv_sec_hi/lo, actual_tv_nsec). + + The actual timestamp corresponds to the time when the content update + turned into light the first time on the surface's main output. + Compositors may approximate this from the framebuffer flip completion + events from the system, and the latency of the physical display path + if known. + + The optimal timestamp indicates the time when the compositor would + have liked the client to set the target present time to. This allows + the compositor to provide feedback to the provided ideal present time. + The compositor may set this to the actual present time, to the ideal + present time (see zwp_surface_present_timing_v1.set_ideal_present_time), + or to some other time based upon how the client is performing, the system + load and/or future clock settings. + + All timestamps are interpreted according to the active clock + domain (see zwp_present_timing_v1.clock_id). + + + + + + + + + + + + + + The content update was never displayed to the user. + + + + + diff --git a/unstable/present-timing/present-timing.rst b/unstable/present-timing/present-timing.rst new file mode 100644 index 0000000..8578b78 --- /dev/null +++ b/unstable/present-timing/present-timing.rst @@ -0,0 +1,43 @@ +.. Copyright 2020 Collabora, Ltd. + +Wayland Present Timing Protocol Design Goals +============================================ + +TODO + +Example of using ideal_present_time to evaluate presentation rates +------------------------------------------------------------------ + +Assume a 60Hz fixed rate display and a client which has currently determined it +can only present smoothly every 66.6ms (i.e., at 15Hz), so it sets +target_present_time to T+66.6ms (T: target_present_time of previous commit). + +At some point the client may want to check if it can present smoothly more +often. The client could check this by setting target_present_time to T+16.67ms +for a few frames, but doing so could lead to stutter if the +16.67ms deadline +couldn't be consistently met (which is what we are trying to evaluate). +Instead, the client keeps target_present_time at T+66.6ms and sets +ideal_present_time to T+16.67ms. + +ideal_present_time tells the compositor to evaluate if it could have presented +at that point (or later), without actually doing so. The compositor informs the +client about the result of this evaluation using the optimal_present_time field +of the feedback event. So, for the case above, the feedback event would contain +an actual_present_time of T+66.6ms (assuming it was indeed still able present +at that point), and an optimal_present_time which is >=ideal_present_time and +