From 28d83ea16250573721eca3b4fb962c8056dd220c Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Mon, 27 Mar 2023 15:36:37 +0200 Subject: [PATCH 01/18] staging: add refresh cycle protocol Signed-off-by: Sebastian Wick --- meson.build | 1 + staging/refresh-cycle/README | 4 + staging/refresh-cycle/refresh-cycle-v1.xml | 206 +++++++++++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 staging/refresh-cycle/README create mode 100644 staging/refresh-cycle/refresh-cycle-v1.xml diff --git a/meson.build b/meson.build index ab55c7f..0937bc3 100644 --- a/meson.build +++ b/meson.build @@ -41,6 +41,7 @@ staging_protocols = { 'ext-idle-notify': ['v1'], 'ext-session-lock': ['v1'], 'fractional-scale': ['v1'], + 'refresh-cycle': ['v1'], 'single-pixel-buffer': ['v1'], 'tearing-control': ['v1'], 'xdg-activation': ['v1'], diff --git a/staging/refresh-cycle/README b/staging/refresh-cycle/README new file mode 100644 index 0000000..c4fa00e --- /dev/null +++ b/staging/refresh-cycle/README @@ -0,0 +1,4 @@ +Refresh Cycle protocol + +Maintainers: +Sebastian Wick diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml new file mode 100644 index 0000000..2452bf1 --- /dev/null +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -0,0 +1,206 @@ + + + + Copyright © 2023 Red Hat, Inc. + + 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 global is a wp_refresh_cycle_v1 factory. + + + + + Destroy the manager object. + + Existing objects created through this interface remain valid. + + + + + + Create a wp_refresh_cycle_v1 object tied to a wl_surface. + + + + + + + + + + + + + + Destroy the refresh cycle object. + + + + + + Describes when and how to expect latching events. + + + + Indicates that the output does not have a concept of vertical retrace + or a refresh cycle, or that the output device is self-refreshing + without a way to query the refresh count. + + No latching events are send in this state. + + + + + Indicates that latching events are send. + + + + + Indicates that latching events are send but might be unreliable or + erratic. + + + + + Indicates that the surface is hidden or otherwise obstructed. + + No latching events are send in this state. + + + + + + + Describes if the refresh rate is fixed or variable and if the variable + refresh rate is driven by this surface or not. + + + + The refresh rate is fixed and latching events occur in regular + intervals. + + + + + The refresh rate is variable and driven by this surface. + + + + + The refresh rate is variable and not driven by this surface. Latching + events can occur in erratic intervals. + + + + + + + + + + + + + + + + + + + + + + + The refresh cycle state. + + frr, vrr_min and vrr_max must be zero if the refresh_state is none. + vrr_min and vrr_max must be zero if refresh_kind is frr. + + + + + + + + + + + + As latching can be synchronized to only one output at a + time, this event tells which output it was. This event is only + sent prior to the latching event. + + As clients may bind to the same global wl_output multiple + times, this event is sent for each bound instance that matches + the synchronized output. If a client has not bound to the + right wl_output global at all, this event is not sent. + + + + + + + The latching event is sent no earlier than the compositor deciding which + commits will be chosen for the next presentation, but as close to it as + possible. + + The exact time of this event is recorded in the timestamp (tv_sec_hi/lo, + tv_nsec). + + The 64-bit value combined from seq_hi and seq_lo is the value of the + output's vertical retrace counter of the following presentation. This + value must be compatible with the seq_hi and seq_lo of the + presentation-time protocol. + + vrr_min and vrr_max describe the possible range in which the latching + event could have happened. For FRR those values are zero. + + + + + + + + + + + + From bd5740dc2a7a876e585fbedd0bfa144ec1fa2600 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Wed, 29 Mar 2023 23:38:47 +0200 Subject: [PATCH 02/18] refresh-cycle: Fix typos, adjust wording Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index 2452bf1..6ad477a 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -70,17 +70,17 @@ or a refresh cycle, or that the output device is self-refreshing without a way to query the refresh count. - No latching events are send in this state. + No latching events are sent in this state. - Indicates that latching events are send. + Indicates that latching events are sent. - Indicates that latching events are send but might be unreliable or + Indicates that latching events are sent but might be unreliable or erratic. @@ -88,7 +88,7 @@ Indicates that the surface is hidden or otherwise obstructed. - No latching events are send in this state. + No latching events are sent in this state. @@ -183,8 +183,8 @@ value must be compatible with the seq_hi and seq_lo of the presentation-time protocol. - vrr_min and vrr_max describe the possible range in which the latching - event could have happened. For FRR those values are zero. + The vrr_min and vrr_max arguments describe the possible range in which + the latching event could have happened. For FRR those values are zero. From bfc551d0e09e12bc7531e63c70c1c9fcc11fa80d Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Wed, 29 Mar 2023 23:44:17 +0200 Subject: [PATCH 03/18] refresh-cycle: Import clock_id event from presentation-time Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 36 +++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index 6ad477a..5be8296 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -47,6 +47,39 @@ + + + + This event tells the client in which clock domain the compositor + interprets the timestamps used by the refresh cycle extension. This + clock is called the refresh cycle clock. + + The compositor sends this event when the client binds to the + wp_refresh_cycle_manager interface. The refresh cycle 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 refresh cycle 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. + + + @@ -176,7 +209,8 @@ possible. The exact time of this event is recorded in the timestamp (tv_sec_hi/lo, - tv_nsec). + tv_nsec). For the interpretation of the timestamp, see + wp_refresh_cycle_manager.clock_id event. The 64-bit value combined from seq_hi and seq_lo is the value of the output's vertical retrace counter of the following presentation. This From 1aab298f20069c1b343fc6d7e2482230ec569fd2 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Wed, 29 Mar 2023 23:48:14 +0200 Subject: [PATCH 04/18] refresh-cycle: Replace sync_output with invalidate The sync_output event is only useful for figuring out when the previous latching events become invalid. Let's be explicit about the invalidation instead and remove the link to outputs. Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index 5be8296..bf006bf 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -187,19 +187,15 @@ summary="the throttle hint"/> - - - As latching can be synchronized to only one output at a - time, this event tells which output it was. This event is only - sent prior to the latching event. + + + The latching events sent prior to this event should not be used to + predict any future events. - As clients may bind to the same global wl_output multiple - times, this event is sent for each bound instance that matches - the synchronized output. If a client has not bound to the - right wl_output global at all, this event is not sent. + This is typically sent when the surface changes the output or the mode + of the current output changes, making the previous latching events + invalid. - From 4b122e7fe335dcf9829d9d198b0543e2750940c9 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Thu, 30 Mar 2023 00:03:18 +0200 Subject: [PATCH 05/18] refresh-cycle: Differentiate between commit and buffer latching Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 29 ++++++++++++++++------ 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index bf006bf..4b49190 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -204,8 +204,15 @@ commits will be chosen for the next presentation, but as close to it as possible. - The exact time of this event is recorded in the timestamp (tv_sec_hi/lo, - tv_nsec). For the interpretation of the timestamp, see + The exact time of this event is recorded in the commit latching + timestamp (commit_tv_sec_hi/lo, commit_tv_nsec). + + The buffer latching timestamp (buffer_tv_sec_hi/lo, buffer_tv_nsec) + describes when all the fences of buffers attached to surfaces of a + commit must be signaled in order to get presented on the refresh cycle + of this latching event. + + For the interpretation of the timestamps, see wp_refresh_cycle_manager.clock_id event. The 64-bit value combined from seq_hi and seq_lo is the value of the @@ -216,12 +223,18 @@ The vrr_min and vrr_max arguments describe the possible range in which the latching event could have happened. For FRR those values are zero. - - - + + + + + + Date: Fri, 31 Mar 2023 20:53:45 +0200 Subject: [PATCH 06/18] refresh-cycle: Remove the throttle hint Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index 4b49190..03985b7 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -150,22 +150,6 @@ - - - - - - - - - - - - - - - - The refresh cycle state. @@ -183,8 +167,6 @@ summary="minimum Variable Refresh Rate cycle in nanoseconds"/> - From cd3322cf20d2f7496010bcd4ffcdc5a3277af2fb Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Fri, 31 Mar 2023 21:10:17 +0200 Subject: [PATCH 07/18] refresh-cycle: Remove explicit VRR parameters Signed-off-by: Sebastian Wick --- staging/refresh-cycle/refresh-cycle-v1.xml | 49 +++++++--------------- 1 file changed, 15 insertions(+), 34 deletions(-) diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml index 03985b7..40f8b0d 100644 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ b/staging/refresh-cycle/refresh-cycle-v1.xml @@ -126,26 +126,23 @@ - + - Describes if the refresh rate is fixed or variable and if the variable - refresh rate is driven by this surface or not. + Describes how to interpret latching events. - - - The refresh rate is fixed and latching events occur in regular - intervals. + + + The latching events occur in relatively regular intervals. If the + frequency or phase changes suddenly an invalidate event will be sent. + The next predicted latching event will not deviate from the actual + next latching event by a lot. - - - The refresh rate is variable and driven by this surface. - - - - - The refresh rate is variable and not driven by this surface. Latching - events can occur in erratic intervals. + + + The latching events occur in erratic intervals. The next predicted + latching event is set to zero. It is not advisable to try and predict + the next latching event. @@ -153,20 +150,11 @@ The refresh cycle state. - - frr, vrr_min and vrr_max must be zero if the refresh_state is none. - vrr_min and vrr_max must be zero if refresh_kind is frr. - - - - + @@ -201,9 +189,6 @@ output's vertical retrace counter of the following presentation. This value must be compatible with the seq_hi and seq_lo of the presentation-time protocol. - - The vrr_min and vrr_max arguments describe the possible range in which - the latching event could have happened. For FRR those values are zero. @@ -221,10 +206,6 @@ summary="high 32 bits of refresh counter"/> - - From 74d9c9c21c1fb7f333e8b3e55fdc0a273fba8117 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Fri, 31 Mar 2023 21:41:21 +0200 Subject: [PATCH 08/18] presentation-time: Move refresh-cycle to presentation-time v2 Signed-off-by: Sebastian Wick --- meson.build | 1 - .../presentation-time/presentation-time.xml | 148 +++++++++++- staging/refresh-cycle/README | 4 - staging/refresh-cycle/refresh-cycle-v1.xml | 212 ------------------ 4 files changed, 147 insertions(+), 218 deletions(-) delete mode 100644 staging/refresh-cycle/README delete mode 100644 staging/refresh-cycle/refresh-cycle-v1.xml diff --git a/meson.build b/meson.build index 0937bc3..ab55c7f 100644 --- a/meson.build +++ b/meson.build @@ -41,7 +41,6 @@ staging_protocols = { 'ext-idle-notify': ['v1'], 'ext-session-lock': ['v1'], 'fractional-scale': ['v1'], - 'refresh-cycle': ['v1'], 'single-pixel-buffer': ['v1'], 'tearing-control': ['v1'], 'xdg-activation': ['v1'], diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 04301ff..43bb9fa 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -4,6 +4,7 @@ Copyright © 2013-2014 Collabora, Ltd. + Copyright © 2023 Red Hat, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), @@ -25,7 +26,7 @@ DEALINGS IN THE SOFTWARE. - + @@ -122,6 +123,23 @@ + + + Request refresh cycle information for the given surface. This + creates a new refresh_cycle object, which will deliver the + refresh cycle information continuously. If multiple refresh + cycle objects are created for the same surface, they will all + deliver the same information. + + For details on what information is returned, see the + refresh_cycle interface. + + " + " + + @@ -263,4 +281,132 @@ + + + + + + + + Destroy the refresh cycle object. + + + + + + Describes when and how to expect latching events. + + + + Indicates that the output does not have a concept of vertical + retrace or a refresh cycle, or that the output device is + self-refreshing without a way to query the refresh count. + + No latching events are sent in this state. + + + + + Indicates that latching events are sent. + + + + + Indicates that latching events are sent but might be + unreliable or erratic. + + + + + Indicates that the surface is hidden or otherwise obstructed. + + No latching events are sent in this state. + + + + + + + Describes how to interpret latching events. + + + + The latching events occur in relatively regular intervals. + If the frequency or phase changes suddenly an invalidate + event will be sent. The next predicted latching event will + not deviate from the actual next latching event by a lot. + + + + + The latching events occur in erratic intervals. The next + predicted latching event is set to zero. It is not advisable + to try and predict the next latching event. + + + + + + + The refresh cycle state. + + + + + + + + The latching events sent prior to this event should not be used + to predict any future events. The last compositor prediction of + the next latching event is likely going to be wrong. + + This is typically sent when the surface changes the output or + the mode of the current output changes, making the previous + latching events invalid. + + + + + + The latching event is sent no earlier than the compositor + deciding which commits will be chosen for the next + presentation, but as close to it as possible. + + The exact time of this event is recorded in the commit latching + timestamp (commit_tv_sec_hi/lo, commit_tv_nsec). + + The buffer latching timestamp (buffer_tv_sec_hi/lo, + buffer_tv_nsec) describes when all the fences of buffers + attached to surfaces of a commit must be signaled in order to + get presented on the refresh cycle of this latching event. + + For the interpretation of the timestamps, see + presentation.clock_id. + + The 64-bit value combined from seq_hi and seq_lo is the value + of the output's vertical retrace counter of the following + presentation. This value is compatible with seq_hi and seq_lo + from presentation_feedback.presented. + + + + + + + + + + + + diff --git a/staging/refresh-cycle/README b/staging/refresh-cycle/README deleted file mode 100644 index c4fa00e..0000000 --- a/staging/refresh-cycle/README +++ /dev/null @@ -1,4 +0,0 @@ -Refresh Cycle protocol - -Maintainers: -Sebastian Wick diff --git a/staging/refresh-cycle/refresh-cycle-v1.xml b/staging/refresh-cycle/refresh-cycle-v1.xml deleted file mode 100644 index 40f8b0d..0000000 --- a/staging/refresh-cycle/refresh-cycle-v1.xml +++ /dev/null @@ -1,212 +0,0 @@ - - - - Copyright © 2023 Red Hat, Inc. - - 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 global is a wp_refresh_cycle_v1 factory. - - - - - Destroy the manager object. - - Existing objects created through this interface remain valid. - - - - - - Create a wp_refresh_cycle_v1 object tied to a wl_surface. - - - - - - - - This event tells the client in which clock domain the compositor - interprets the timestamps used by the refresh cycle extension. This - clock is called the refresh cycle clock. - - The compositor sends this event when the client binds to the - wp_refresh_cycle_manager interface. The refresh cycle 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 refresh cycle 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. - - - - - - - - - - - - - Destroy the refresh cycle object. - - - - - - Describes when and how to expect latching events. - - - - Indicates that the output does not have a concept of vertical retrace - or a refresh cycle, or that the output device is self-refreshing - without a way to query the refresh count. - - No latching events are sent in this state. - - - - - Indicates that latching events are sent. - - - - - Indicates that latching events are sent but might be unreliable or - erratic. - - - - - Indicates that the surface is hidden or otherwise obstructed. - - No latching events are sent in this state. - - - - - - - Describes how to interpret latching events. - - - - The latching events occur in relatively regular intervals. If the - frequency or phase changes suddenly an invalidate event will be sent. - The next predicted latching event will not deviate from the actual - next latching event by a lot. - - - - - The latching events occur in erratic intervals. The next predicted - latching event is set to zero. It is not advisable to try and predict - the next latching event. - - - - - - - The refresh cycle state. - - - - - - - - The latching events sent prior to this event should not be used to - predict any future events. - - This is typically sent when the surface changes the output or the mode - of the current output changes, making the previous latching events - invalid. - - - - - - The latching event is sent no earlier than the compositor deciding which - commits will be chosen for the next presentation, but as close to it as - possible. - - The exact time of this event is recorded in the commit latching - timestamp (commit_tv_sec_hi/lo, commit_tv_nsec). - - The buffer latching timestamp (buffer_tv_sec_hi/lo, buffer_tv_nsec) - describes when all the fences of buffers attached to surfaces of a - commit must be signaled in order to get presented on the refresh cycle - of this latching event. - - For the interpretation of the timestamps, see - wp_refresh_cycle_manager.clock_id event. - - The 64-bit value combined from seq_hi and seq_lo is the value of the - output's vertical retrace counter of the following presentation. This - value must be compatible with the seq_hi and seq_lo of the - presentation-time protocol. - - - - - - - - - - - - - From d0a24eed87f0ef3f6a26943591177feabcd8277a Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Fri, 31 Mar 2023 21:53:36 +0200 Subject: [PATCH 09/18] presentation-time: Add next commit and buffer latching prediction Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 43bb9fa..fdce202 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -406,6 +406,10 @@ summary="high 32 bits of refresh counter"/> + + From 14859d977a74569d5fa7ac95eee92670c6f82789 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Fri, 31 Mar 2023 23:22:57 +0200 Subject: [PATCH 10/18] presentation-time: Remove stray characters Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index fdce202..1077f88 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -135,9 +135,9 @@ refresh_cycle interface. " + summary="target surface"/> " + summary="new refresh cycle object"/> From 8b51322feb8883df26853f409388ea272796b378 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Fri, 31 Mar 2023 23:59:03 +0200 Subject: [PATCH 11/18] presentation-time: Fix interface name Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 1077f88..9568e14 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -136,7 +136,7 @@ - @@ -281,7 +281,7 @@ - + From 89e35ea4fdaf8c67a6e4f2f75d52119a514ab03a Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Mon, 3 Apr 2023 23:34:31 +0200 Subject: [PATCH 12/18] presentation-time: remove next latching time Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 9568e14..8684e8d 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -406,10 +406,6 @@ summary="high 32 bits of refresh counter"/> - - From bbf05572dcaa546307e763b0bbc17f464699b9b1 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 00:43:39 +0200 Subject: [PATCH 13/18] presentation-time: Various changes Signed-off-by: Sebastian Wick --- .../presentation-time/presentation-time.xml | 107 ++++++++++++------ 1 file changed, 73 insertions(+), 34 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 8684e8d..544a819 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -294,7 +294,8 @@ - Describes when and how to expect latching events. + Describes if the surface has a refresh cycle, sends latching + events and processes content updates. @@ -302,71 +303,105 @@ retrace or a refresh cycle, or that the output device is self-refreshing without a way to query the refresh count. - No latching events are sent in this state. + No latching events are sent in this state but content updates + get processed and might get presented. - Indicates that latching events are sent. + Indicates that the surface has an active refresh cycle. + + Latching events are sent and content updates get processed + and might get presented. - - - Indicates that latching events are sent but might be - unreliable or erratic. - - - + Indicates that the surface is hidden or otherwise obstructed. - No latching events are sent in this state. + No latching events are sent in this state and content updates + get ignored. - + - Describes how to interpret latching events. + Describes the refresh cycle kind of a surface. - The latching events occur in relatively regular intervals. - If the frequency or phase changes suddenly an invalidate - event will be sent. The next predicted latching event will - not deviate from the actual next latching event by a lot. + The refresh cycle has a relatively constant duration. The + duration_min and duration_max arguments are equal and + describe refresh cycle duration and can be used to predict + future latching events. - The latching events occur in erratic intervals. The next - predicted latching event is set to zero. It is not advisable - to try and predict the next latching event. + The refresh cycle duration is erratic. The duration_min and + duration_max arguments are set to zero and can not be used to + predict future latching events. + + The refresh cycle is always discontinuous and the + discontinuity flag in refresh_cycle.latching is always set in + latching events. - The refresh cycle state. + This event describes the refresh cycle of the surface. The + information is valid until the next state event and provides + context for the latching events sent in between two state + events. + + The refresh_state argument describes if the surface has a + refresh cycle and expects content updates. + + The latching_kind argument describes the kind of refresh cycle + of the surface. This information together with duration_min + and duration_max can be used to predict the latching events of + future refresh cycles. See the enum description for details of + each kind. + + The duration_min and duration_max arguments contain information + about the refresh cycle duration. See the enum description for + details of each kind. + + This event indicates a discontinuity. See + refresh_cycle.latching_flags for more information. + + The compositor sends this event when the client binds to the + refresh_cycle interface. - - + + + - - - The latching events sent prior to this event should not be used - to predict any future events. The last compositor prediction of - the next latching event is likely going to be wrong. - - This is typically sent when the surface changes the output or - the mode of the current output changes, making the previous - latching events invalid. + + + These flags provide information about the latching event. - + + + A discontinuity indicates that previously observed latching + events will not correlate with future latching events and + should not be used to predict future latching events. + + This is typically sent when the surface changes the output, the + mode of the current output changes or the compositor adjusts + the timing to meet its own deadlines. + + + @@ -406,6 +441,10 @@ summary="high 32 bits of refresh counter"/> + + From 187e9e553fa29a2f64eeaad6f75786d5a5bda6d0 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 00:52:39 +0200 Subject: [PATCH 14/18] presentation-time: Add ramp up and ramp down for refresh cycles Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 544a819..f961365 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -370,6 +370,13 @@ about the refresh cycle duration. See the enum description for details of each kind. + The ramp_up and ramp_down arguments describe how much the + duration of the refresh cycle can increase and decrease per + refresh cycle. The argument is zero if there is no restriction + on the increase or decrease per cycle. The refresh cycle can + never be decreased below duration_min and can never be + increased beyond duration_max. + This event indicates a discontinuity. See refresh_cycle.latching_flags for more information. @@ -381,9 +388,13 @@ + summary="the minimum duration of a refresh cycle in nanoseconds"/> + summary="the maximum duration of a refresh cycle in nanoseconds"/> + + From 1ca5bc8e1f85ef57e763621c30292bceb6bc7170 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 00:53:29 +0200 Subject: [PATCH 15/18] presentation-time: Typo Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index f961365..9f86e4c 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -383,7 +383,7 @@ The compositor sends this event when the client binds to the refresh_cycle interface. - From 2b57c764462a92db420f1e8c9f1c569ee6ec7148 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 00:55:00 +0200 Subject: [PATCH 16/18] presentation-time: Add summary Signed-off-by: Sebastian Wick --- stable/presentation-time/presentation-time.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 9f86e4c..d3a757d 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -293,7 +293,7 @@ - + Describes if the surface has a refresh cycle, sends latching events and processes content updates. @@ -326,11 +326,11 @@ - + Describes the refresh cycle kind of a surface. - + The refresh cycle has a relatively constant duration. The duration_min and duration_max arguments are equal and describe refresh cycle duration and can be used to predict @@ -338,7 +338,7 @@ - + The refresh cycle duration is erratic. The duration_min and duration_max arguments are set to zero and can not be used to predict future latching events. @@ -415,7 +415,7 @@ - + The latching event is sent no earlier than the compositor deciding which commits will be chosen for the next presentation, but as close to it as possible. From 54e66f28c535b0b512b593e64fbc235877b5bb89 Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 01:02:09 +0200 Subject: [PATCH 17/18] presentation-time: Minor changes Signed-off-by: Sebastian Wick --- .../presentation-time/presentation-time.xml | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index d3a757d..826fb3b 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -332,20 +332,19 @@ The refresh cycle has a relatively constant duration. The - duration_min and duration_max arguments are equal and - describe refresh cycle duration and can be used to predict - future latching events. + duration_min and duration_max arguments are equal and can be + used to predict future latching events. ramp_up and ramp_down + are zero. - The refresh cycle duration is erratic. The duration_min and - duration_max arguments are set to zero and can not be used to - predict future latching events. + The refresh cycle duration is erratic. duration_min, + duration_max, ramp_up and down are set to zero and can not be + used to predict future latching events. The refresh cycle is always discontinuous and the - discontinuity flag in refresh_cycle.latching is always set in - latching events. + discontinuity flag in the latching event is always set. @@ -377,8 +376,8 @@ never be decreased below duration_min and can never be increased beyond duration_max. - This event indicates a discontinuity. See - refresh_cycle.latching_flags for more information. + This event indicates a discontinuity and the discontinuity flag + in the latching event is set. The compositor sends this event when the client binds to the refresh_cycle interface. From 2c3fc18fb475751fa9a830c1f3306897764f0cec Mon Sep 17 00:00:00 2001 From: Sebastian Wick Date: Tue, 4 Apr 2023 03:36:01 +0200 Subject: [PATCH 18/18] presentation-time: Describe the refresh cycle events Signed-off-by: Sebastian Wick --- .../presentation-time/presentation-time.xml | 73 +++++++++++++------ 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml index 826fb3b..af18879 100644 --- a/stable/presentation-time/presentation-time.xml +++ b/stable/presentation-time/presentation-time.xml @@ -376,8 +376,16 @@ never be decreased below duration_min and can never be increased beyond duration_max. + The buffer_latching argument describes when the buffer latching + of a refresh cycle happens relative to the commit latching. See + the latching event for more information. + + The presentation argument describes when the presentation of a + refresh cycle happens relative to the commit latching. See the + latching event for more information. + This event indicates a discontinuity and the discontinuity flag - in the latching event is set. + of the next latching event is set. The compositor sends this event when the client binds to the refresh_cycle interface. @@ -394,6 +402,10 @@ summary="the maximum increase of the duration per refresh cycle in nanoseconds"/> + + @@ -415,44 +427,57 @@ - The latching event is sent no earlier than the compositor - deciding which commits will be chosen for the next - presentation, but as close to it as possible. + Each refresh cycle consists of a number of events in order: the + commit latching of the previous refresh cycle, the commit + latching of the current cycle, the buffer latching and the + presentation. - The exact time of this event is recorded in the commit latching - timestamp (commit_tv_sec_hi/lo, commit_tv_nsec). + The commit latching indicates the start of a new refresh cycle. + Two refresh cycles overlap between the commit latching and the + presentation. The buffer latching can be at the same time as + the commit latching. - The buffer latching timestamp (buffer_tv_sec_hi/lo, - buffer_tv_nsec) describes when all the fences of buffers - attached to surfaces of a commit must be signaled in order to - get presented on the refresh cycle of this latching event. + The time between two commit latching events is the duration of + the refresh cycle and describes the update frequency. - For the interpretation of the timestamps, see - presentation.clock_id. + If a content update is supposed to land on a certain refresh + cycle then the content update must be committed before the + commit latching and the buffers of the content update must be + ready before the buffer latching. + + A buffer is considered ready if there are no fences attached to + it or if all the explicit and implicit fences attached to it + are signaled. + + If a content update landed on a refresh cycle then it is + considered for presentation by the compositor on this or any + of the following refresh cycles. + + This latching event is sent no earlier than the commit latching + but as close to it as possible. + + The exact time of the commit latching is recorded in the + timestamp (commit_tv_sec_hi/lo, commit_tv_nsec). For the + interpretation of the timestamp, see presentation.clock_id. The 64-bit value combined from seq_hi and seq_lo is the value - of the output's vertical retrace counter of the following + of the output's vertical retrace counter of the refresh cycle's presentation. This value is compatible with seq_hi and seq_lo from presentation_feedback.presented. + + The time of the buffer latching and presentation relative to the + commit latching is sent in the state event. - - - - - - -