summaryrefslogtreecommitdiff
path: root/data
diff options
context:
space:
mode:
authorRafael Antognolli <rafael.antognolli@intel.com>2013-08-07 18:05:55 -0300
committerRafael Antognolli <rafael.antognolli@intel.com>2013-10-10 13:21:40 -0300
commitf26f2da5ea55ccdb028065f1ff803cbac08c8863 (patch)
treeb914c509c57e52efecc2ed26a543010b0a6137b3 /data
parent2c1c6b9335e38c6e52b06829a95d9b58d780c99e (diff)
adding wayland subsurfaces protocol file.
Diffstat (limited to 'data')
-rw-r--r--data/ecore/ecore_wayland/protocol/subsurface.xml244
1 files changed, 244 insertions, 0 deletions
diff --git a/data/ecore/ecore_wayland/protocol/subsurface.xml b/data/ecore/ecore_wayland/protocol/subsurface.xml
new file mode 100644
index 0000000..9e4a658
--- /dev/null
+++ b/data/ecore/ecore_wayland/protocol/subsurface.xml
@@ -0,0 +1,244 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="subsurface">
3
4 <copyright>
5 Copyright © 2012-2013 Collabora, Ltd.
6
7 Permission to use, copy, modify, distribute, and sell this
8 software and its documentation for any purpose is hereby granted
9 without fee, provided that the above copyright notice appear in
10 all copies and that both that copyright notice and this permission
11 notice appear in supporting documentation, and that the name of
12 the copyright holders not be used in advertising or publicity
13 pertaining to distribution of the software without specific,
14 written prior permission. The copyright holders make no
15 representations about the suitability of this software for any
16 purpose. It is provided "as is" without express or implied
17 warranty.
18
19 THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
20 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
21 FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
22 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
23 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
24 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
25 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
26 THIS SOFTWARE.
27 </copyright>
28
29 <interface name="wl_subcompositor" version="1">
30 <description summary="sub-surface compositing">
31 The global interface exposing sub-surface compositing capabilities.
32 A wl_surface, that has sub-surfaces associated, is called the
33 parent surface. Sub-surfaces can be arbitrarily nested and create
34 a tree of sub-surfaces.
35
36 The root surface in a tree of sub-surfaces is the main
37 surface. The main surface cannot be a sub-surface, because
38 sub-surfaces must always have a parent.
39
40 A main surface with its sub-surfaces forms a (compound) window.
41 For window management purposes, this set of wl_surface objects is
42 to be considered as a single window, and it should also behave as
43 such.
44
45 The aim of sub-surfaces is to offload some of the compositing work
46 within a window from clients to the compositor. A prime example is
47 a video player with decorations and video in separate wl_surface
48 objects. This should allow the compositor to pass YUV video buffer
49 processing to dedicated overlay hardware when possible.
50 </description>
51
52 <request name="destroy" type="destructor">
53 <description summary="unbind from the subcompositor interface">
54 Informs the server that the client will not be using this
55 protocol object anymore. This does not affect any other
56 objects, wl_subsurface objects included.
57 </description>
58 </request>
59
60 <enum name="error">
61 <entry name="bad_surface" value="0"
62 summary="the to-be sub-surface is invalid"/>
63 </enum>
64
65 <request name="get_subsurface">
66 <description summary="give a surface the role sub-surface">
67 Create a sub-surface interface for the given surface, and
68 associate it with the given parent surface. This turns a
69 plain wl_surface into a sub-surface.
70
71 The to-be sub-surface must not already have a dedicated
72 purpose, like any shell surface type, cursor image, drag icon,
73 or sub-surface. Otherwise a protocol error is raised.
74 </description>
75
76 <arg name="id" type="new_id" interface="wl_subsurface"
77 summary="the new subsurface object id"/>
78 <arg name="surface" type="object" interface="wl_surface"
79 summary="the surface to be turned into a sub-surface"/>
80 <arg name="parent" type="object" interface="wl_surface"
81 summary="the parent surface"/>
82 </request>
83 </interface>
84
85 <interface name="wl_subsurface" version="1">
86 <description summary="sub-surface interface to a wl_surface">
87 An additional interface to a wl_surface object, which has been
88 made a sub-surface. A sub-surface has one parent surface. A
89 sub-surface's size and position are not limited to that of the parent.
90 Particularly, a sub-surface is not automatically clipped to its
91 parent's area.
92
93 A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
94 and the parent surface is mapped. The order of which one happens
95 first is irrelevant. A sub-surface is hidden if the parent becomes
96 hidden, or if a NULL wl_buffer is applied. These rules apply
97 recursively through the tree of surfaces.
98
99 The behaviour of wl_surface.commit request on a sub-surface
100 depends on the sub-surface's mode. The possible modes are
101 synchronized and desynchronized, see methods
102 wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
103 mode caches the wl_surface state to be applied when the parent's
104 state gets applied, and desynchronized mode applies the pending
105 wl_surface state directly. A sub-surface is initially in the
106 synchronized mode.
107
108 Sub-surfaces have also other kind of state, which is managed by
109 wl_subsurface requests, as opposed to wl_surface requests. This
110 state includes the sub-surface position relative to the parent
111 surface (wl_subsurface.set_position), and the stacking order of
112 the parent and its sub-surfaces (wl_subsurface.place_above and
113 .place_below). This state is applied when the parent surface's
114 wl_surface state is applied, regardless of the sub-surface's mode.
115 As the exception, set_sync and set_desync are effective immediately.
116
117 The main surface can be thought to be always in desynchronized mode,
118 since it does not have a parent in the sub-surfaces sense.
119
120 Even if a sub-surface is in desynchronized mode, it will behave as
121 in synchronized mode, if its parent surface behaves as in
122 synchronized mode. This rule is applied recursively throughout the
123 tree of surfaces. This means, that one can set a sub-surface into
124 synchronized mode, and then assume that all its child and grand-child
125 sub-surfaces are synchronized, too, without explicitly setting them.
126
127 If the wl_surface associated with the wl_subsurface is destroyed, the
128 wl_subsurface object becomes inert. Note, that destroying either object
129 takes effect immediately. If you need to synchronize the removal
130 of a sub-surface to the parent surface update, unmap the sub-surface
131 first by attaching a NULL wl_buffer, update parent, and then destroy
132 the sub-surface.
133
134 If the parent wl_surface object is destroyed, the sub-surface is
135 unmapped.
136 </description>
137
138 <request name="destroy" type="destructor">
139 <description summary="remove sub-surface interface">
140 The sub-surface interface is removed from the wl_surface object
141 that was turned into a sub-surface with
142 wl_subcompositor.get_subsurface request. The wl_surface's association
143 to the parent is deleted, and the wl_surface loses its role as
144 a sub-surface. The wl_surface is unmapped.
145 </description>
146 </request>
147
148 <enum name="error">
149 <entry name="bad_surface" value="0"
150 summary="wl_surface is not a sibling or the parent"/>
151 </enum>
152
153 <request name="set_position">
154 <description summary="reposition the sub-surface">
155 This schedules a sub-surface position change.
156 The sub-surface will be moved so, that its origin (top-left
157 corner pixel) will be at the location x, y of the parent surface
158 coordinate system. The coordinates are not restricted to the parent
159 surface area. Negative values are allowed.
160
161 The next wl_surface.commit on the parent surface will reset
162 the sub-surface's position to the scheduled coordinates.
163
164 The initial position is 0, 0.
165 </description>
166
167 <arg name="x" type="int" summary="coordinate in the parent surface"/>
168 <arg name="y" type="int" summary="coordinate in the parent surface"/>
169 </request>
170
171 <request name="place_above">
172 <description summary="restack the sub-surface">
173 This sub-surface is taken from the stack, and put back just
174 above the reference surface, changing the z-order of the sub-surfaces.
175 The reference surface must be one of the sibling surfaces, or the
176 parent surface. Using any other surface, including this sub-surface,
177 will cause a protocol error.
178
179 The z-order is double-buffered state, and will be applied on the
180 next commit of the parent surface.
181 See wl_surface.commit and wl_subcompositor.get_subsurface.
182
183 A new sub-surface is initially added as the top-most in the stack
184 of its siblings and parent.
185 </description>
186
187 <arg name="sibling" type="object" interface="wl_surface"
188 summary="the reference surface"/>
189 </request>
190
191 <request name="place_below">
192 <description summary="restack the sub-surface">
193 The sub-surface is placed just below of the reference surface.
194 See wl_subsurface.place_above.
195 </description>
196
197 <arg name="sibling" type="object" interface="wl_surface"
198 summary="the reference surface"/>
199 </request>
200
201 <request name="set_sync">
202 <description summary="set sub-surface to synchronized mode">
203 Change the commit behaviour of the sub-surface to synchronized
204 mode, also described as the parent dependant mode.
205
206 In synchronized mode, wl_surface.commit on a sub-surface will
207 accumulate the committed state in a cache, but the state will
208 not be applied and hence will not change the compositor output.
209 The cached state is applied to the sub-surface immediately after
210 the parent surface's state is applied. This ensures atomic
211 updates of the parent and all its synchronized sub-surfaces.
212 Applying the cached state will invalidate the cache, so further
213 parent surface commits do not (re-)apply old state.
214
215 See wl_subsurface for the recursive effect of this mode.
216 </description>
217 </request>
218
219 <request name="set_desync">
220 <description summary="set sub-surface to desynchronized mode">
221 Change the commit behaviour of the sub-surface to desynchronized
222 mode, also described as independent or freely running mode.
223
224 In desynchronized mode, wl_surface.commit on a sub-surface will
225 apply the pending state directly, without caching, as happens
226 normally with a wl_surface. Calling wl_surface.commit on the
227 parent surface has no effect on the sub-surface's wl_surface
228 state. This mode allows a sub-surface to be updated on its own.
229
230 If cached state exists when wl_surface.commit is called in
231 desynchronized mode, the pending state is added to the cached
232 state, and applied as whole. This invalidates the cache.
233
234 Note: even if a sub-surface is set to desynchronized, a parent
235 sub-surface may override it to behave as synchronized. For details,
236 see wl_subsurface.
237
238 If a surface's parent surface behaves as desynchronized, then
239 the cached state is applied on set_desync.
240 </description>
241 </request>
242
243 </interface>
244</protocol>