This reverts commit 2396aec684.
This exact version of the sub-surface protocol has been copied into
Wayland core. Therefore it must be removed from here to avoid build
conflicts and useless duplication.
No other changes to sub-surface protocol consumers are needed, the
identical API is now offered by libwayland-client and libwayland-server.
The commit adding sub-surfaces to Wayland is:
Author: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
protocol: add sub-surfaces to the core
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
dev
Pekka Paalanen
11 years ago
committed by
Kristian Høgsberg
parent
ba44c6bf2e
commit
a662206e71
@ -1,244 +0,0 @@ |
|||||||
<?xml version="1.0" encoding="UTF-8"?> |
|
||||||
<protocol name="subsurface"> |
|
||||||
|
|
||||||
<copyright> |
|
||||||
Copyright © 2012-2013 Collabora, Ltd. |
|
||||||
|
|
||||||
Permission to use, copy, modify, distribute, and sell this |
|
||||||
software and its documentation for any purpose is hereby granted |
|
||||||
without fee, provided that the above copyright notice appear in |
|
||||||
all copies and that both that copyright notice and this permission |
|
||||||
notice appear in supporting documentation, and that the name of |
|
||||||
the copyright holders not be used in advertising or publicity |
|
||||||
pertaining to distribution of the software without specific, |
|
||||||
written prior permission. The copyright holders make no |
|
||||||
representations about the suitability of this software for any |
|
||||||
purpose. It is provided "as is" without express or implied |
|
||||||
warranty. |
|
||||||
|
|
||||||
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS |
|
||||||
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND |
|
||||||
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY |
|
||||||
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
|
||||||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
|
||||||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, |
|
||||||
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF |
|
||||||
THIS SOFTWARE. |
|
||||||
</copyright> |
|
||||||
|
|
||||||
<interface name="wl_subcompositor" version="1"> |
|
||||||
<description summary="sub-surface compositing"> |
|
||||||
The global interface exposing sub-surface compositing capabilities. |
|
||||||
A wl_surface, that has sub-surfaces associated, is called the |
|
||||||
parent surface. Sub-surfaces can be arbitrarily nested and create |
|
||||||
a tree of sub-surfaces. |
|
||||||
|
|
||||||
The root surface in a tree of sub-surfaces is the main |
|
||||||
surface. The main surface cannot be a sub-surface, because |
|
||||||
sub-surfaces must always have a parent. |
|
||||||
|
|
||||||
A main surface with its sub-surfaces forms a (compound) window. |
|
||||||
For window management purposes, this set of wl_surface objects is |
|
||||||
to be considered as a single window, and it should also behave as |
|
||||||
such. |
|
||||||
|
|
||||||
The aim of sub-surfaces is to offload some of the compositing work |
|
||||||
within a window from clients to the compositor. A prime example is |
|
||||||
a video player with decorations and video in separate wl_surface |
|
||||||
objects. This should allow the compositor to pass YUV video buffer |
|
||||||
processing to dedicated overlay hardware when possible. |
|
||||||
</description> |
|
||||||
|
|
||||||
<request name="destroy" type="destructor"> |
|
||||||
<description summary="unbind from the subcompositor interface"> |
|
||||||
Informs the server that the client will not be using this |
|
||||||
protocol object anymore. This does not affect any other |
|
||||||
objects, wl_subsurface objects included. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
<enum name="error"> |
|
||||||
<entry name="bad_surface" value="0" |
|
||||||
summary="the to-be sub-surface is invalid"/> |
|
||||||
</enum> |
|
||||||
|
|
||||||
<request name="get_subsurface"> |
|
||||||
<description summary="give a surface the role sub-surface"> |
|
||||||
Create a sub-surface interface for the given surface, and |
|
||||||
associate it with the given parent surface. This turns a |
|
||||||
plain wl_surface into a sub-surface. |
|
||||||
|
|
||||||
The to-be sub-surface must not already have a dedicated |
|
||||||
purpose, like any shell surface type, cursor image, drag icon, |
|
||||||
or sub-surface. Otherwise a protocol error is raised. |
|
||||||
</description> |
|
||||||
|
|
||||||
<arg name="id" type="new_id" interface="wl_subsurface" |
|
||||||
summary="the new subsurface object id"/> |
|
||||||
<arg name="surface" type="object" interface="wl_surface" |
|
||||||
summary="the surface to be turned into a sub-surface"/> |
|
||||||
<arg name="parent" type="object" interface="wl_surface" |
|
||||||
summary="the parent surface"/> |
|
||||||
</request> |
|
||||||
</interface> |
|
||||||
|
|
||||||
<interface name="wl_subsurface" version="1"> |
|
||||||
<description summary="sub-surface interface to a wl_surface"> |
|
||||||
An additional interface to a wl_surface object, which has been |
|
||||||
made a sub-surface. A sub-surface has one parent surface. A |
|
||||||
sub-surface's size and position are not limited to that of the parent. |
|
||||||
Particularly, a sub-surface is not automatically clipped to its |
|
||||||
parent's area. |
|
||||||
|
|
||||||
A sub-surface becomes mapped, when a non-NULL wl_buffer is applied |
|
||||||
and the parent surface is mapped. The order of which one happens |
|
||||||
first is irrelevant. A sub-surface is hidden if the parent becomes |
|
||||||
hidden, or if a NULL wl_buffer is applied. These rules apply |
|
||||||
recursively through the tree of surfaces. |
|
||||||
|
|
||||||
The behaviour of wl_surface.commit request on a sub-surface |
|
||||||
depends on the sub-surface's mode. The possible modes are |
|
||||||
synchronized and desynchronized, see methods |
|
||||||
wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized |
|
||||||
mode caches the wl_surface state to be applied when the parent's |
|
||||||
state gets applied, and desynchronized mode applies the pending |
|
||||||
wl_surface state directly. A sub-surface is initially in the |
|
||||||
synchronized mode. |
|
||||||
|
|
||||||
Sub-surfaces have also other kind of state, which is managed by |
|
||||||
wl_subsurface requests, as opposed to wl_surface requests. This |
|
||||||
state includes the sub-surface position relative to the parent |
|
||||||
surface (wl_subsurface.set_position), and the stacking order of |
|
||||||
the parent and its sub-surfaces (wl_subsurface.place_above and |
|
||||||
.place_below). This state is applied when the parent surface's |
|
||||||
wl_surface state is applied, regardless of the sub-surface's mode. |
|
||||||
As the exception, set_sync and set_desync are effective immediately. |
|
||||||
|
|
||||||
The main surface can be thought to be always in desynchronized mode, |
|
||||||
since it does not have a parent in the sub-surfaces sense. |
|
||||||
|
|
||||||
Even if a sub-surface is in desynchronized mode, it will behave as |
|
||||||
in synchronized mode, if its parent surface behaves as in |
|
||||||
synchronized mode. This rule is applied recursively throughout the |
|
||||||
tree of surfaces. This means, that one can set a sub-surface into |
|
||||||
synchronized mode, and then assume that all its child and grand-child |
|
||||||
sub-surfaces are synchronized, too, without explicitly setting them. |
|
||||||
|
|
||||||
If the wl_surface associated with the wl_subsurface is destroyed, the |
|
||||||
wl_subsurface object becomes inert. Note, that destroying either object |
|
||||||
takes effect immediately. If you need to synchronize the removal |
|
||||||
of a sub-surface to the parent surface update, unmap the sub-surface |
|
||||||
first by attaching a NULL wl_buffer, update parent, and then destroy |
|
||||||
the sub-surface. |
|
||||||
|
|
||||||
If the parent wl_surface object is destroyed, the sub-surface is |
|
||||||
unmapped. |
|
||||||
</description> |
|
||||||
|
|
||||||
<request name="destroy" type="destructor"> |
|
||||||
<description summary="remove sub-surface interface"> |
|
||||||
The sub-surface interface is removed from the wl_surface object |
|
||||||
that was turned into a sub-surface with |
|
||||||
wl_subcompositor.get_subsurface request. The wl_surface's association |
|
||||||
to the parent is deleted, and the wl_surface loses its role as |
|
||||||
a sub-surface. The wl_surface is unmapped. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
<enum name="error"> |
|
||||||
<entry name="bad_surface" value="0" |
|
||||||
summary="wl_surface is not a sibling or the parent"/> |
|
||||||
</enum> |
|
||||||
|
|
||||||
<request name="set_position"> |
|
||||||
<description summary="reposition the sub-surface"> |
|
||||||
This schedules a sub-surface position change. |
|
||||||
The sub-surface will be moved so, that its origin (top-left |
|
||||||
corner pixel) will be at the location x, y of the parent surface |
|
||||||
coordinate system. The coordinates are not restricted to the parent |
|
||||||
surface area. Negative values are allowed. |
|
||||||
|
|
||||||
The next wl_surface.commit on the parent surface will reset |
|
||||||
the sub-surface's position to the scheduled coordinates. |
|
||||||
|
|
||||||
The initial position is 0, 0. |
|
||||||
</description> |
|
||||||
|
|
||||||
<arg name="x" type="int" summary="coordinate in the parent surface"/> |
|
||||||
<arg name="y" type="int" summary="coordinate in the parent surface"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="place_above"> |
|
||||||
<description summary="restack the sub-surface"> |
|
||||||
This sub-surface is taken from the stack, and put back just |
|
||||||
above the reference surface, changing the z-order of the sub-surfaces. |
|
||||||
The reference surface must be one of the sibling surfaces, or the |
|
||||||
parent surface. Using any other surface, including this sub-surface, |
|
||||||
will cause a protocol error. |
|
||||||
|
|
||||||
The z-order is double-buffered state, and will be applied on the |
|
||||||
next commit of the parent surface. |
|
||||||
See wl_surface.commit and wl_subcompositor.get_subsurface. |
|
||||||
|
|
||||||
A new sub-surface is initially added as the top-most in the stack |
|
||||||
of its siblings and parent. |
|
||||||
</description> |
|
||||||
|
|
||||||
<arg name="sibling" type="object" interface="wl_surface" |
|
||||||
summary="the reference surface"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="place_below"> |
|
||||||
<description summary="restack the sub-surface"> |
|
||||||
The sub-surface is placed just below of the reference surface. |
|
||||||
See wl_subsurface.place_above. |
|
||||||
</description> |
|
||||||
|
|
||||||
<arg name="sibling" type="object" interface="wl_surface" |
|
||||||
summary="the reference surface"/> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="set_sync"> |
|
||||||
<description summary="set sub-surface to synchronized mode"> |
|
||||||
Change the commit behaviour of the sub-surface to synchronized |
|
||||||
mode, also described as the parent dependant mode. |
|
||||||
|
|
||||||
In synchronized mode, wl_surface.commit on a sub-surface will |
|
||||||
accumulate the committed state in a cache, but the state will |
|
||||||
not be applied and hence will not change the compositor output. |
|
||||||
The cached state is applied to the sub-surface immediately after |
|
||||||
the parent surface's state is applied. This ensures atomic |
|
||||||
updates of the parent and all its synchronized sub-surfaces. |
|
||||||
Applying the cached state will invalidate the cache, so further |
|
||||||
parent surface commits do not (re-)apply old state. |
|
||||||
|
|
||||||
See wl_subsurface for the recursive effect of this mode. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
<request name="set_desync"> |
|
||||||
<description summary="set sub-surface to desynchronized mode"> |
|
||||||
Change the commit behaviour of the sub-surface to desynchronized |
|
||||||
mode, also described as independent or freely running mode. |
|
||||||
|
|
||||||
In desynchronized mode, wl_surface.commit on a sub-surface will |
|
||||||
apply the pending state directly, without caching, as happens |
|
||||||
normally with a wl_surface. Calling wl_surface.commit on the |
|
||||||
parent surface has no effect on the sub-surface's wl_surface |
|
||||||
state. This mode allows a sub-surface to be updated on its own. |
|
||||||
|
|
||||||
If cached state exists when wl_surface.commit is called in |
|
||||||
desynchronized mode, the pending state is added to the cached |
|
||||||
state, and applied as whole. This invalidates the cache. |
|
||||||
|
|
||||||
Note: even if a sub-surface is set to desynchronized, a parent |
|
||||||
sub-surface may override it to behave as synchronized. For details, |
|
||||||
see wl_subsurface. |
|
||||||
|
|
||||||
If a surface's parent surface behaves as desynchronized, then |
|
||||||
the cached state is applied on set_desync. |
|
||||||
</description> |
|
||||||
</request> |
|
||||||
|
|
||||||
</interface> |
|
||||||
</protocol> |
|
||||||
Loading…
Reference in new issue