linuxexplicitsynchronization.xml RawHistoryFolder
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="zwp_linux_explicit_synchronization_unstable_v1">
3
4 <copyright>
5 Copyright 2016 The Chromium Authors.
6 Copyright 2017 Intel Corporation
7 Copyright 2018 Collabora, Ltd
8
9 Permission is hereby granted, free of charge, to any person obtaining a
10 copy of this software and associated documentation files (the "Software"),
11 to deal in the Software without restriction, including without limitation
12 the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 and/or sell copies of the Software, and to permit persons to whom the
14 Software is furnished to do so, subject to the following conditions:
15
16 The above copyright notice and this permission notice (including the next
17 paragraph) shall be included in all copies or substantial portions of the
18 Software.
19
20 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26 DEALINGS IN THE SOFTWARE.
27 </copyright>
28
29 <interface name="zwp_linux_explicit_synchronization_v1" version="2">
30 <description summary="protocol for providing explicit synchronization">
31 This global is a factory interface, allowing clients to request
32 explicit synchronization for buffers on a per-surface basis.
33
34 See zwp_linux_surface_synchronization_v1 for more information.
35
36 This interface is derived from Chromium's
37 zcr_linux_explicit_synchronization_v1.
38
39 Note: this protocol is superseded by linux-drm-syncobj.
40
41 Warning! The protocol described in this file is experimental and
42 backward incompatible changes may be made. Backward compatible changes
43 may be added together with the corresponding interface version bump.
44 Backward incompatible changes are done by bumping the version number in
45 the protocol and interface names and resetting the interface version.
46 Once the protocol is to be declared stable, the 'z' prefix and the
47 version number in the protocol and interface names are removed and the
48 interface version number is reset.
49 </description>
50
51 <request name="destroy" type="destructor">
52 <description summary="destroy explicit synchronization factory object">
53 Destroy this explicit synchronization factory object. Other objects,
54 including zwp_linux_surface_synchronization_v1 objects created by this
55 factory, shall not be affected by this request.
56 </description>
57 </request>
58
59 <enum name="error">
60 <entry name="synchronization_exists" value="0"
61 summary="the surface already has a synchronization object associated"/>
62 </enum>
63
64 <request name="get_synchronization">
65 <description summary="extend surface interface for explicit synchronization">
66 Instantiate an interface extension for the given wl_surface to provide
67 explicit synchronization.
68
69 If the given wl_surface already has an explicit synchronization object
70 associated, the synchronization_exists protocol error is raised.
71
72 Graphics APIs, like EGL or Vulkan, that manage the buffer queue and
73 commits of a wl_surface themselves, are likely to be using this
74 extension internally. If a client is using such an API for a
75 wl_surface, it should not directly use this extension on that surface,
76 to avoid raising a synchronization_exists protocol error.
77 </description>
78
79 <arg name="id" type="new_id"
80 interface="zwp_linux_surface_synchronization_v1"
81 summary="the new synchronization interface id"/>
82 <arg name="surface" type="object" interface="wl_surface"
83 summary="the surface"/>
84 </request>
85 </interface>
86
87 <interface name="zwp_linux_surface_synchronization_v1" version="2">
88 <description summary="per-surface explicit synchronization support">
89 This object implements per-surface explicit synchronization.
90
91 Synchronization refers to co-ordination of pipelined operations performed
92 on buffers. Most GPU clients will schedule an asynchronous operation to
93 render to the buffer, then immediately send the buffer to the compositor
94 to be attached to a surface.
95
96 In implicit synchronization, ensuring that the rendering operation is
97 complete before the compositor displays the buffer is an implementation
98 detail handled by either the kernel or userspace graphics driver.
99
100 By contrast, in explicit synchronization, dma_fence objects mark when the
101 asynchronous operations are complete. When submitting a buffer, the
102 client provides an acquire fence which will be waited on before the
103 compositor accesses the buffer. The Wayland server, through a
104 zwp_linux_buffer_release_v1 object, will inform the client with an event
105 which may be accompanied by a release fence, when the compositor will no
106 longer access the buffer contents due to the specific commit that
107 requested the release event.
108
109 Each surface can be associated with only one object of this interface at
110 any time.
111
112 In version 1 of this interface, explicit synchronization is only
113 guaranteed to be supported for buffers created with any version of the
114 wp_linux_dmabuf buffer factory. Version 2 additionally guarantees
115 explicit synchronization support for opaque EGL buffers, which is a type
116 of platform specific buffers described in the EGL_WL_bind_wayland_display
117 extension. Compositors are free to support explicit synchronization for
118 additional buffer types.
119 </description>
120
121 <request name="destroy" type="destructor">
122 <description summary="destroy synchronization object">
123 Destroy this explicit synchronization object.
124
125 Any fence set by this object with set_acquire_fence since the last
126 commit will be discarded by the server. Any fences set by this object
127 before the last commit are not affected.
128
129 zwp_linux_buffer_release_v1 objects created by this object are not
130 affected by this request.
131 </description>
132 </request>
133
134 <enum name="error">
135 <entry name="invalid_fence" value="0"
136 summary="the fence specified by the client could not be imported"/>
137 <entry name="duplicate_fence" value="1"
138 summary="multiple fences added for a single surface commit"/>
139 <entry name="duplicate_release" value="2"
140 summary="multiple releases added for a single surface commit"/>
141 <entry name="no_surface" value="3"
142 summary="the associated wl_surface was destroyed"/>
143 <entry name="unsupported_buffer" value="4"
144 summary="the buffer does not support explicit synchronization"/>
145 <entry name="no_buffer" value="5"
146 summary="no buffer was attached"/>
147 </enum>
148
149 <request name="set_acquire_fence">
150 <description summary="set the acquire fence">
151 Set the acquire fence that must be signaled before the compositor
152 may sample from the buffer attached with wl_surface.attach. The fence
153 is a dma_fence kernel object.
154
155 The acquire fence is double-buffered state, and will be applied on the
156 next wl_surface.commit request for the associated surface. Thus, it
157 applies only to the buffer that is attached to the surface at commit
158 time.
159
160 If the provided fd is not a valid dma_fence fd, then an INVALID_FENCE
161 error is raised.
162
163 If a fence has already been attached during the same commit cycle, a
164 DUPLICATE_FENCE error is raised.
165
166 If the associated wl_surface was destroyed, a NO_SURFACE error is
167 raised.
168
169 If at surface commit time the attached buffer does not support explicit
170 synchronization, an UNSUPPORTED_BUFFER error is raised.
171
172 If at surface commit time there is no buffer attached, a NO_BUFFER
173 error is raised.
174 </description>
175 <arg name="fd" type="fd" summary="acquire fence fd"/>
176 </request>
177
178 <request name="get_release">
179 <description summary="release fence for last-attached buffer">
180 Create a listener for the release of the buffer attached by the
181 client with wl_surface.attach. See zwp_linux_buffer_release_v1
182 documentation for more information.
183
184 The release object is double-buffered state, and will be associated
185 with the buffer that is attached to the surface at wl_surface.commit
186 time.
187
188 If a zwp_linux_buffer_release_v1 object has already been requested for
189 the surface in the same commit cycle, a DUPLICATE_RELEASE error is
190 raised.
191
192 If the associated wl_surface was destroyed, a NO_SURFACE error
193 is raised.
194
195 If at surface commit time there is no buffer attached, a NO_BUFFER
196 error is raised.
197 </description>
198 <arg name="release" type="new_id" interface="zwp_linux_buffer_release_v1"
199 summary="new zwp_linux_buffer_release_v1 object"/>
200 </request>
201 </interface>
202
203 <interface name="zwp_linux_buffer_release_v1" version="1">
204 <description summary="buffer release explicit synchronization">
205 This object is instantiated in response to a
206 zwp_linux_surface_synchronization_v1.get_release request.
207
208 It provides an alternative to wl_buffer.release events, providing a
209 unique release from a single wl_surface.commit request. The release event
210 also supports explicit synchronization, providing a fence FD for the
211 client to synchronize against.
212
213 Exactly one event, either a fenced_release or an immediate_release, will
214 be emitted for the wl_surface.commit request. The compositor can choose
215 release by release which event it uses.
216
217 This event does not replace wl_buffer.release events; servers are still
218 required to send those events.
219
220 Once a buffer release object has delivered a 'fenced_release' or an
221 'immediate_release' event it is automatically destroyed.
222 </description>
223
224 <event name="fenced_release" type="destructor">
225 <description summary="release buffer with fence">
226 Sent when the compositor has finalised its usage of the associated
227 buffer for the relevant commit, providing a dma_fence which will be
228 signaled when all operations by the compositor on that buffer for that
229 commit have finished.
230
231 Once the fence has signaled, and assuming the associated buffer is not
232 pending release from other wl_surface.commit requests, no additional
233 explicit or implicit synchronization is required to safely reuse or
234 destroy the buffer.
235
236 This event destroys the zwp_linux_buffer_release_v1 object.
237 </description>
238 <arg name="fence" type="fd" summary="fence for last operation on buffer"/>
239 </event>
240
241 <event name="immediate_release" type="destructor">
242 <description summary="release buffer immediately">
243 Sent when the compositor has finalised its usage of the associated
244 buffer for the relevant commit, and either performed no operations
245 using it, or has a guarantee that all its operations on that buffer for
246 that commit have finished.
247
248 Once this event is received, and assuming the associated buffer is not
249 pending release from other wl_surface.commit requests, no additional
250 explicit or implicit synchronization is required to safely reuse or
251 destroy the buffer.
252
253 This event destroys the zwp_linux_buffer_release_v1 object.
254 </description>
255 </event>
256 </interface>
257
258</protocol>