From 2396aec6842c709a714f3825dbad9fd88478f2e6 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Thu, 25 Apr 2013 13:57:41 +0300 Subject: protocol: add sub-surfaces Add protocol for sub-surfaces, wl_subcompositor as the global interface, and wl_subsurface as the per-surface interface extension. This patch is meant to be reverted, once sub-surfaces are moved into Wayland core. Changes in v2: - Rewrite wl_subcompositor.get_subsurface description, and move mapping and commit details into wl_subsurface description. Check the wording in wl_subsurface.set_position description. - Add wl_subsurface.set_commit_mode request, and document it, with the commit_mode enum. Add bad_value error code for wl_subsurface. - Moved the protocol into Weston repository so we can land it upstream sooner for public exposure. It is to be moved into Wayland core later. - Add destroy requests to both wl_subcompositor and wl_subsurface, and document them. Experience has showed, that interfaces should always have a destructor unless there is a good and future-proof reason to not have it. Changes in v3: - Specify, that wl_subsurface will become inert, if the corresponding wl_surface is destroyed, instead of requiring a certain destruction order. - Replaced wl_subsurface.set_commit_mode with wl_subsurface.set_sync and wl_subsurface.set_desync. Parent-cached commit mode is now called synchronized, and independent mode is desynchronized. Removed commit_mode enum, and bad_value error. - Added support for nested sub-surfaces. Signed-off-by: Pekka Paalanen --- clients/.gitignore | 2 + clients/Makefile.am | 4 + clients/window.h | 1 + protocol/subsurface.xml | 236 ++++++++++++++++++++++++++++++++++++++++++++++++ src/.gitignore | 3 + src/Makefile.am | 4 + src/compositor.h | 1 + tests/.gitignore | 2 + tests/Makefile.am | 4 + 9 files changed, 257 insertions(+) create mode 100644 protocol/subsurface.xml diff --git a/clients/.gitignore b/clients/.gitignore index dcd45641..16088e85 100644 --- a/clients/.gitignore +++ b/clients/.gitignore @@ -20,6 +20,8 @@ simple-egl simple-shm simple-touch smoke +subsurface-client-protocol.h +subsurface-protocol.c tablet-shell-client-protocol.h tablet-shell-protocol.c text-client-protocol.h diff --git a/clients/Makefile.am b/clients/Makefile.am index 8c9bcd4d..5f83acd4 100644 --- a/clients/Makefile.am +++ b/clients/Makefile.am @@ -81,6 +81,8 @@ libtoytoolkit_la_SOURCES = \ window.h \ text-cursor-position-protocol.c \ text-cursor-position-client-protocol.h \ + subsurface-protocol.c \ + subsurface-client-protocol.h \ workspaces-protocol.c \ workspaces-client-protocol.h @@ -185,6 +187,8 @@ BUILT_SOURCES = \ desktop-shell-protocol.c \ tablet-shell-client-protocol.h \ tablet-shell-protocol.c \ + subsurface-client-protocol.h \ + subsurface-protocol.c \ workspaces-client-protocol.h \ workspaces-protocol.c diff --git a/clients/window.h b/clients/window.h index c2946d8c..815b3f1c 100644 --- a/clients/window.h +++ b/clients/window.h @@ -27,6 +27,7 @@ #include #include #include "../shared/config-parser.h" +#include "subsurface-client-protocol.h" #define ARRAY_LENGTH(a) (sizeof (a) / sizeof (a)[0]) diff --git a/protocol/subsurface.xml b/protocol/subsurface.xml new file mode 100644 index 00000000..60b4002c --- /dev/null +++ b/protocol/subsurface.xml @@ -0,0 +1,236 @@ + + + + + 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. + + + + + 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. + + + + + 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. + + + + + + + + + + + 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. + + + + + + + + + + + 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 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 wl_surface state to be applied on the next parent + surface's commit, 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 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 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. + + + + + 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. + + + + + + + + + + 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. + + 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. + + + + + + + + + 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. + + + + + + + + The sub-surface is placed just below of the reference surface. + See wl_subsurface.place_above. + + + + + + + + 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 when + wl_surface.commit is called on the parent surface, after the + parent surface's own 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. + + + + + + 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. + + + + + diff --git a/src/.gitignore b/src/.gitignore index 8c0fea69..ee62b844 100644 --- a/src/.gitignore +++ b/src/.gitignore @@ -18,3 +18,6 @@ workspaces-protocol.c workspaces-server-protocol.h input-method-protocol.c input-method-server-protocol.h +subsurface-server-protocol.h +subsurface-protocol.c + diff --git a/src/Makefile.am b/src/Makefile.am index 0471294d..73c2d0d8 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -36,6 +36,8 @@ weston_SOURCES = \ input-method-server-protocol.h \ workspaces-protocol.c \ workspaces-server-protocol.h \ + subsurface-protocol.c \ + subsurface-server-protocol.h \ bindings.c \ animation.c \ gl-renderer.h \ @@ -280,6 +282,8 @@ BUILT_SOURCES = \ input-method-server-protocol.h \ workspaces-server-protocol.h \ workspaces-protocol.c \ + subsurface-server-protocol.h \ + subsurface-protocol.c \ git-version.h CLEANFILES = $(BUILT_SOURCES) diff --git a/src/compositor.h b/src/compositor.h index 97c91c01..e3584743 100644 --- a/src/compositor.h +++ b/src/compositor.h @@ -35,6 +35,7 @@ extern "C" { #include "version.h" #include "matrix.h" #include "config-parser.h" +#include "subsurface-server-protocol.h" #define ARRAY_LENGTH(a) (sizeof (a) / sizeof (a)[0]) diff --git a/tests/.gitignore b/tests/.gitignore index 05bc024e..fa19888c 100644 --- a/tests/.gitignore +++ b/tests/.gitignore @@ -11,3 +11,5 @@ keyboard-test event-test button-test xwayland-test +subsurface-client-protocol.h +subsurface-protocol.c diff --git a/tests/Makefile.am b/tests/Makefile.am index 27295458..a42a1fcb 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -64,6 +64,8 @@ weston_test_client_src = \ weston-test-client-helper.h \ wayland-test-protocol.c \ wayland-test-client-protocol.h \ + subsurface-protocol.c \ + subsurface-client-protocol.h \ $(weston_test_runner_src) weston_test_client_libs = \ $(SIMPLE_CLIENT_LIBS) \ @@ -113,6 +115,8 @@ endif EXTRA_DIST = weston-tests-env BUILT_SOURCES = \ + subsurface-protocol.c \ + subsurface-client-protocol.h \ wayland-test-protocol.c \ wayland-test-server-protocol.h \ wayland-test-client-protocol.h -- cgit v1.2.3