1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="fifo_v1">
3 <copyright>
4 Copyright © 2023 Valve Corporation
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice (including the next
14 paragraph) shall be included in all copies or substantial portions of the
15 Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 DEALINGS IN THE SOFTWARE.
24 </copyright>
25
26 <interface name="wp_fifo_manager_v1" version="1">
27 <description summary="protocol for fifo constraints">
28 When a Wayland compositor considers applying a content update,
29 it must ensure all the update's readiness constraints (fences, etc)
30 are met.
31
32 This protocol provides a way to use the completion of a display refresh
33 cycle as an additional readiness constraint.
34
35 Warning! The protocol described in this file is currently in the testing
36 phase. Backward compatible changes may be added together with the
37 corresponding interface version bump. Backward incompatible changes can
38 only be done by creating a new major version of the extension.
39 </description>
40
41 <enum name="error">
42 <description summary="fatal presentation error">
43 These fatal protocol errors may be emitted in response to
44 illegal requests.
45 </description>
46 <entry name="already_exists" value="0"
47 summary="fifo manager already exists for surface"/>
48 </enum>
49
50 <request name="destroy" type="destructor">
51 <description summary="unbind from the manager interface">
52 Informs the server that the client will no longer be using
53 this protocol object. Existing objects created by this object
54 are not affected.
55 </description>
56 </request>
57
58 <request name="get_fifo">
59 <description summary="request fifo interface for surface">
60 Establish a fifo object for a surface that may be used to add
61 display refresh constraints to content updates.
62
63 Only one such object may exist for a surface and attempting
64 to create more than one will result in an already_exists
65 protocol error. If a surface is acted on by multiple software
66 components, general best practice is that only the component
67 performing wl_surface.attach operations should use this protocol.
68 </description>
69 <arg name="id" type="new_id" interface="wp_fifo_v1"/>
70 <arg name="surface" type="object" interface="wl_surface"/>
71 </request>
72 </interface>
73
74 <interface name="wp_fifo_v1" version="1">
75 <description summary="fifo interface">
76 A fifo object for a surface that may be used to add
77 display refresh constraints to content updates.
78 </description>
79
80 <enum name="error">
81 <description summary="fatal error">
82 These fatal protocol errors may be emitted in response to
83 illegal requests.
84 </description>
85 <entry name="surface_destroyed" value="0"
86 summary="the associated surface no longer exists"/>
87 </enum>
88
89 <request name="set_barrier">
90 <description summary="sets the start point for a fifo constraint">
91 When the content update containing the "set_barrier" is applied,
92 it sets a "fifo_barrier" condition on the surface associated with
93 the fifo object. The condition is cleared immediately after the
94 following latching deadline for non-tearing presentation.
95
96 The compositor may clear the condition early if it must do so to
97 ensure client forward progress assumptions.
98
99 To wait for this condition to clear, use the "wait_barrier" request.
100
101 "set_barrier" is double-buffered state, see wl_surface.commit.
102
103 Requesting set_barrier after the fifo object's surface is
104 destroyed will generate a "surface_destroyed" error.
105 </description>
106 </request>
107
108 <request name="wait_barrier">
109 <description summary="adds a fifo constraint to a content update">
110 Indicate that this content update is not ready while a
111 "fifo_barrier" condition is present on the surface.
112
113 This means that when the content update containing "set_barrier"
114 was made active at a latching deadline, it will be active for
115 at least one refresh cycle. A content update which is allowed to
116 tear might become active after a latching deadline if no content
117 update became active at the deadline.
118
119 The constraint must be ignored if the surface is a subsurface in
120 synchronized mode. If the surface is not being updated by the
121 compositor (off-screen, occluded) the compositor may ignore the
122 constraint. Clients must use an additional mechanism such as
123 frame callbacks or timestamps to ensure throttling occurs under
124 all conditions.
125
126 "wait_barrier" is double-buffered state, see wl_surface.commit.
127
128 Requesting "wait_barrier" after the fifo object's surface is
129 destroyed will generate a "surface_destroyed" error.
130 </description>
131 </request>
132
133 <request name="destroy" type="destructor">
134 <description summary="destroy the fifo interface">
135 Informs the server that the client will no longer be using
136 this protocol object.
137
138 Surface state changes previously made by this protocol are
139 unaffected by this object's destruction.
140 </description>
141 </request>
142 </interface>
143</protocol>