Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
SUSE:SLE-12:Update
wayland
add-subsurfaces-to-the-core.patch
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File add-subsurfaces-to-the-core.patch of Package wayland
From 81c57614d11787c00b8859cbaef650e284b4f188 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen <pekka.paalanen@collabora.co.uk> Date: Fri, 15 Nov 2013 16:09:45 +0200 Subject: protocol: add sub-surfaces to the core The sub-surface protocol was originally committed into Weston on May 10th, 2013, in commit 2396aec6842c709a714f3825dbad9fd88478f2e6. The design for the protocol had started in the beginning of December 2012. I think it is high time to move this into the core now. This patch copies the sub-surface protocol as it was in Weston on Nov 15th, 2013, into Wayland. Weston gets a patch to remove the protocol from there. Sub-surface is a wl_surface role. You create a wl_surface as usual, and assign it the sub-surface role and a parent wl_surface. Sub-surfaces are an integral part of the parent surface, and stay glued to the parent. For window management, a window is the union of the top-level wl_surface and all its sub-surfaces. Sub-surfaces are not clipped to the parent, and the union of the surface tree can be larger than the (top-level) wl_surface at its root. The representative use case for sub-surfaces is a video player window. When the video content is given its own wl_surface, there is no need to modify the video frame contents after decoding or copy them into a whole window sized buffer before submitting it to the compositor. This allows efficient, zero-copy video presentation paths, where video decoding hardware produces a (YUV) buffer, which eventually ends up in a (YUV-capable) hardware overlay and is scanned out directly. This can also be used for zero-copy presentation of windowed OpenGL content, where the OpenGL rendering engine does not need to draw or avoid window decorations. Sub-surfaces allow mixing different buffer types into the same window, e.g. software-rendered decorations in wl_shm buffers, and live content in EGL-based buffers. However, the sub-surface extension does not offer clipping or scaling facilities, or accurate presentation timing. Those are topics for additional extensions. Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk> diff --git a/protocol/wayland.xml b/protocol/wayland.xml index a1df007..61fde84 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -4,6 +4,7 @@ <copyright> Copyright © 2008-2011 Kristian Høgsberg Copyright © 2010-2011 Intel Corporation + Copyright © 2012-2013 Collabora, Ltd. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted @@ -1795,4 +1796,220 @@ </interface> + <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> -- cgit v0.10.2
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
