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 <ppaalanen@gmail.com>

9 files changed, 257 insertions, 0 deletions

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 <wayland-client.h>
 #include <cairo.h>
 #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 @@
+<?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"/>
+      <entry name="bad_parent" value="1"
+             summary="the given parent is a sub-surface"/>
+    </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 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.
+    </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.
+
+	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.
+      </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 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.
+      </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.
+      </description>
+    </request>
+
+  </interface>
+</protocol>
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