| 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> |