[RFC Weston 01/10] protocol: add sub-surfaces
Pekka Paalanen
ppaalanen at gmail.com
Fri Feb 22 07:07:45 PST 2013
Add protocol for sub-surfaces, wl_subcompositor as the global interface,
and wl_subsurface as the per-surface interface extension.
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.
Signed-off-by: Pekka Paalanen <ppaalanen at gmail.com>
---
clients/.gitignore | 2 +
clients/Makefile.am | 4 +
clients/window.h | 1 +
protocol/subsurface.xml | 214 ++++++++++++++++++++++++++++++++++++++++++++++++
src/.gitignore | 3 +
src/Makefile.am | 4 +
src/compositor.h | 1 +
tests/.gitignore | 2 +
tests/Makefile.am | 4 +
9 files changed, 235 insertions(+)
create mode 100644 protocol/subsurface.xml
diff --git a/clients/.gitignore b/clients/.gitignore
index dcd4564..16088e8 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 8c9bcd4..5f83acd 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 c2946d8..815b3f1 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 0000000..1d148d9
--- /dev/null
+++ b/protocol/subsurface.xml
@@ -0,0 +1,214 @@
+<?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 cannot be nested.
+
+ A parent 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 parent surface must not be a sub-surface itself.
+ The to-be sub-surface must not already have a dedicated
+ purpose, like any shell surface type, cursor image, drag icon,
+ or sub-surface. It also must not be a parent to further
+ sub-surfaces. 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.
+
+ The behaviour of wl_surface.commit request on a sub-surface depends
+ on the commit mode, set by wl_subsurface.set_commit_mode. The commit
+ mode affects operations with the wl_surface state of sub-surfaces.
+
+ If the commit mode is "parent-cached", 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 sub-surfaces with "parent-cached" commit mode.
+ Applying the cached state will invalidate the cache, so further
+ parent surface commits do not (re-)apply old state.
+
+ If the commit mode is "independent", wl_surface.commit on a
+ sub-surface will apply the pending state without caching.
+ Calling wl_surface.commit on the parent surface has no effect on the
+ sub-surface state. This mode allows a sub-surface to be updated
+ on its own.
+
+ 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 on the parent surface's
+ commit, regardless of commit mode. As the exception, changes to
+ commit mode are applied immediately.
+
+ The wl_subsurface object must be destroyed before the wl_surface object
+ it was create for. 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"/>
+ <entry name="bad_value" value="1"
+ summary="unknown enum parameter value"/>
+ </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>
+
+ <enum name="commit_mode">
+ <entry name="parent_cached" value="1"
+ summary="sub-surface commit only caches state"/>
+ <entry name="independent" value="2"
+ summary="sub-surface commit applies state"/>
+ </enum>
+
+ <request name="set_commit_mode">
+ <description summary="change sub-surface commit behaviour">
+ Change how parent and sub-surface commits apply the pending
+ surface state. This request is effective immediately.
+ See the wl_subsurface description.
+
+ The default commit mode is parent-cached.
+ </description>
+
+ <arg name="mode" type="uint" summary="enum commit_mode"/>
+ </request>
+
+ </interface>
+</protocol>
diff --git a/src/.gitignore b/src/.gitignore
index 3c27953..c1392e1 100644
--- a/src/.gitignore
+++ b/src/.gitignore
@@ -17,3 +17,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 2c93a7b..bcc8795 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -34,6 +34,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 \
@@ -252,6 +254,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 cd21c32..3d197ef 100644
--- a/src/compositor.h
+++ b/src/compositor.h
@@ -31,6 +31,7 @@
#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 05bc024..fa19888 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 0f81458..9b9351a 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -60,6 +60,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) \
@@ -109,6 +111,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
--
1.7.12.4
More information about the wayland-devel
mailing list