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      Warning! The protocol described in this file is experimental and
40      backward incompatible changes may be made. Backward compatible changes
41      may be added together with the corresponding interface version bump.
42      Backward incompatible changes are done by bumping the version number in
43      the protocol and interface names and resetting the interface version.
44      Once the protocol is to be declared stable, the 'z' prefix and the
45      version number in the protocol and interface names are removed and the
46      interface version number is reset.
47    </description>
48
49    <request name="destroy" type="destructor">
50      <description summary="destroy explicit synchronization factory object">
51        Destroy this explicit synchronization factory object. Other objects,
52        including zwp_linux_surface_synchronization_v1 objects created by this
53        factory, shall not be affected by this request.
54      </description>
55    </request>
56
57    <enum name="error">
58      <entry name="synchronization_exists" value="0"
59             summary="the surface already has a synchronization object associated"/>
60    </enum>
61
62    <request name="get_synchronization">
63      <description summary="extend surface interface for explicit synchronization">
64        Instantiate an interface extension for the given wl_surface to provide
65        explicit synchronization.
66
67        If the given wl_surface already has an explicit synchronization object
68        associated, the synchronization_exists protocol error is raised.
69
70        Graphics APIs, like EGL or Vulkan, that manage the buffer queue and
71        commits of a wl_surface themselves, are likely to be using this
72        extension internally. If a client is using such an API for a
73        wl_surface, it should not directly use this extension on that surface,
74        to avoid raising a synchronization_exists protocol error.
75      </description>
76
77      <arg name="id" type="new_id"
78           interface="zwp_linux_surface_synchronization_v1"
79           summary="the new synchronization interface id"/>
80      <arg name="surface" type="object" interface="wl_surface"
81           summary="the surface"/>
82    </request>
83  </interface>
84
85  <interface name="zwp_linux_surface_synchronization_v1" version="2">
86    <description summary="per-surface explicit synchronization support">
87      This object implements per-surface explicit synchronization.
88
89      Synchronization refers to co-ordination of pipelined operations performed
90      on buffers. Most GPU clients will schedule an asynchronous operation to
91      render to the buffer, then immediately send the buffer to the compositor
92      to be attached to a surface.
93
94      In implicit synchronization, ensuring that the rendering operation is
95      complete before the compositor displays the buffer is an implementation
96      detail handled by either the kernel or userspace graphics driver.
97
98      By contrast, in explicit synchronization, dma_fence objects mark when the
99      asynchronous operations are complete. When submitting a buffer, the
100      client provides an acquire fence which will be waited on before the
101      compositor accesses the buffer. The Wayland server, through a
102      zwp_linux_buffer_release_v1 object, will inform the client with an event
103      which may be accompanied by a release fence, when the compositor will no
104      longer access the buffer contents due to the specific commit that
105      requested the release event.
106
107      Each surface can be associated with only one object of this interface at
108      any time.
109
110      In version 1 of this interface, explicit synchronization is only
111      guaranteed to be supported for buffers created with any version of the
112      wp_linux_dmabuf buffer factory. Version 2 additionally guarantees
113      explicit synchronization support for opaque EGL buffers, which is a type
114      of platform specific buffers described in the EGL_WL_bind_wayland_display
115      extension. Compositors are free to support explicit synchronization for
116      additional buffer types.
117    </description>
118
119    <request name="destroy" type="destructor">
120      <description summary="destroy synchronization object">
121        Destroy this explicit synchronization object.
122
123        Any fence set by this object with set_acquire_fence since the last
124        commit will be discarded by the server. Any fences set by this object
125        before the last commit are not affected.
126
127        zwp_linux_buffer_release_v1 objects created by this object are not
128        affected by this request.
129      </description>
130    </request>
131
132    <enum name="error">
133      <entry name="invalid_fence" value="0"
134             summary="the fence specified by the client could not be imported"/>
135      <entry name="duplicate_fence" value="1"
136             summary="multiple fences added for a single surface commit"/>
137      <entry name="duplicate_release" value="2"
138             summary="multiple releases added for a single surface commit"/>
139      <entry name="no_surface" value="3"
140             summary="the associated wl_surface was destroyed"/>
141      <entry name="unsupported_buffer" value="4"
142             summary="the buffer does not support explicit synchronization"/>
143      <entry name="no_buffer" value="5"
144             summary="no buffer was attached"/>
145    </enum>
146
147    <request name="set_acquire_fence">
148      <description summary="set the acquire fence">
149        Set the acquire fence that must be signaled before the compositor
150        may sample from the buffer attached with wl_surface.attach. The fence
151        is a dma_fence kernel object.
152
153        The acquire fence is double-buffered state, and will be applied on the
154        next wl_surface.commit request for the associated surface. Thus, it
155        applies only to the buffer that is attached to the surface at commit
156        time.
157
158        If the provided fd is not a valid dma_fence fd, then an INVALID_FENCE
159        error is raised.
160
161        If a fence has already been attached during the same commit cycle, a
162        DUPLICATE_FENCE error is raised.
163
164        If the associated wl_surface was destroyed, a NO_SURFACE error is
165        raised.
166
167        If at surface commit time the attached buffer does not support explicit
168        synchronization, an UNSUPPORTED_BUFFER error is raised.
169
170        If at surface commit time there is no buffer attached, a NO_BUFFER
171        error is raised.
172      </description>
173      <arg name="fd" type="fd" summary="acquire fence fd"/>
174    </request>
175
176    <request name="get_release">
177      <description summary="release fence for last-attached buffer">
178        Create a listener for the release of the buffer attached by the
179        client with wl_surface.attach. See zwp_linux_buffer_release_v1
180        documentation for more information.
181
182        The release object is double-buffered state, and will be associated
183        with the buffer that is attached to the surface at wl_surface.commit
184        time.
185
186        If a zwp_linux_buffer_release_v1 object has already been requested for
187        the surface in the same commit cycle, a DUPLICATE_RELEASE error is
188        raised.
189
190        If the associated wl_surface was destroyed, a NO_SURFACE error
191        is raised.
192
193        If at surface commit time there is no buffer attached, a NO_BUFFER
194        error is raised.
195      </description>
196      <arg name="release" type="new_id" interface="zwp_linux_buffer_release_v1"
197           summary="new zwp_linux_buffer_release_v1 object"/>
198    </request>
199  </interface>
200
201  <interface name="zwp_linux_buffer_release_v1" version="1">
202    <description summary="buffer release explicit synchronization">
203      This object is instantiated in response to a
204      zwp_linux_surface_synchronization_v1.get_release request.
205
206      It provides an alternative to wl_buffer.release events, providing a
207      unique release from a single wl_surface.commit request. The release event
208      also supports explicit synchronization, providing a fence FD for the
209      client to synchronize against.
210
211      Exactly one event, either a fenced_release or an immediate_release, will
212      be emitted for the wl_surface.commit request. The compositor can choose
213      release by release which event it uses.
214
215      This event does not replace wl_buffer.release events; servers are still
216      required to send those events.
217
218      Once a buffer release object has delivered a 'fenced_release' or an
219      'immediate_release' event it is automatically destroyed.
220    </description>
221
222    <event name="fenced_release">
223      <description summary="release buffer with fence">
224        Sent when the compositor has finalised its usage of the associated
225        buffer for the relevant commit, providing a dma_fence which will be
226        signaled when all operations by the compositor on that buffer for that
227        commit have finished.
228
229        Once the fence has signaled, and assuming the associated buffer is not
230        pending release from other wl_surface.commit requests, no additional
231        explicit or implicit synchronization is required to safely reuse or
232        destroy the buffer.
233
234        This event destroys the zwp_linux_buffer_release_v1 object.
235      </description>
236      <arg name="fence" type="fd" summary="fence for last operation on buffer"/>
237    </event>
238
239    <event name="immediate_release">
240      <description summary="release buffer immediately">
241        Sent when the compositor has finalised its usage of the associated
242        buffer for the relevant commit, and either performed no operations
243        using it, or has a guarantee that all its operations on that buffer for
244        that commit have finished.
245
246        Once this event is received, and assuming the associated buffer is not
247        pending release from other wl_surface.commit requests, no additional
248        explicit or implicit synchronization is required to safely reuse or
249        destroy the buffer.
250
251        This event destroys the zwp_linux_buffer_release_v1 object.
252      </description>
253    </event>
254  </interface>
255
256</protocol>
257