[RFC] Sub-surface protocol and implementation v1

[John Kåre Alsaker]

On Fri, Dec 21, 2012 at 12:56 PM, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> Hi all,
>
> we started a discussion about sub-surfaces in Wayland in [1].
> Based on that, and with heavy limiting of scope, I present my first
> sub-surface draft:
>
> http://cgit.collabora.com/git/user/pq/wayland.git/log/?h=subsurface-v1
> http://cgit.collabora.com/git/user/pq/weston.git/log/?h=subsurface-v1
>
> The following changes since commit 812bd4dd0fb20161aaf07029fbd6146d530b9932:
>
>   client: remove two unused function pointer typedefs (2012-12-12 11:04:53 -0500)
>
> are available in the git repository at:
>   git://git.collabora.co.uk/git/user/pq/wayland.git subsurface-v1
>
> Pekka Paalanen (1):
>       protocol: add sub-surfaces
>
>  protocol/wayland.xml |  122 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 122 insertions(+), 0 deletions(-)
>
>
> The following changes since commit e565b405695d2dbcfbf0fd228fe8885ff522ae84:
>
>   tests: Pass --backend so the test suite runs with the right modules (2012-12-14 16:34:00 -0500)
>
> are available in the git repository at:
>   git://git.collabora.co.uk/git/user/pq/weston.git subsurface-v1
>
> Pekka Paalanen (11):
>   misc:
>       tests: make signal other than ABRT a hard failure
>       shell: remove remnants of screensaver surface list
>   surface transform inheritance:
>       compositor: update weston_surface:transform.matrix always
>       compositor: introduce weston_surface_geometry_dirty()
>       compositor: put weston_matrix_pointer into transformation_list
>       compositor: popup inherits surface transformation
>   sub-surface work:
>       compositor: introduce sub-surfaces
>       tests: add sub-surface protocol tests
>       compositor: add sub-surfaces to repaint list
>       shell: keyboard focus with sub-surfaces
>       clients: add a demo for sub-surfaces
>
>  clients/.gitignore            |    1 +
>  clients/Makefile.am           |    4 +
>  clients/subsurfaces.c         |  239 ++++++++++++++++++++
>  src/compositor.c              |  489 ++++++++++++++++++++++++++++++++++++++---
>  src/compositor.h              |   85 ++++++--
>  src/shell.c                   |  121 ++++++-----
>  src/util.c                    |    9 +-
>  src/xwayland/window-manager.c |    4 +-
>  tests/.gitignore              |    2 +
>  tests/Makefile.am             |    4 +
>  tests/subsurface-test.c       |  306 ++++++++++++++++++++++++++
>  tests/weston-test-runner.c    |    6 +-
>  tests/weston-test.c           |    2 +-
>  13 files changed, 1165 insertions(+), 107 deletions(-)
>  create mode 100644 clients/subsurfaces.c
>  create mode 100644 tests/subsurface-test.c
>
>
> I will reply to this email with the sub-surface patches, but leave out
> the preparatory work that I have already posted earlier.
>
> I chose to leave all clipping and scaling outside the scope of this
> work for now, we should discuss those later.
>
> This proposal allows sub-surfaces to form a single window, that may be
> updated in unison, honouring the every frame is perfect -principle. The
> implementation does not yet fully achieve that, though. More details are
> in the commit messages and the protocol definition.
>
> I'll quote my earlier email [2], explaining the base for the design:
>> Conceptually I see it like this: zero or more sub-surfaces with one main
>> surface forms a window. A window is the entity managed at window
>> manager level, and therefore a window is what can be a top-level
>> window, tooltip, menu, etc.
> ...
>>
>> On the protocol level, these concepts are built on the wl_surface
>> object, which can form a part of a window (by being a sub-surface), or
>> the base object of a window (the main surface, or "parent"). The base
>> object can then be associated with meanings like top-level and tooltip
>> in the shell level of the protocol.
>
> Even though the implementation is a little lacking, it is already
> usable. The 'subsurfaces' client just shows a red rectangle [3], but
> could be extended to draw something more interesting. Sub-surfaces are
> drawn and positioned properly, so people could already start
> experimenting with them. Committing is subject to change, but otherwise
> I don't expect changes to be required in clients written against the v1
> proposal.
>
> This would be a nice moment to try and write a video player with
> decorations _and_ YUV video content, or a GL application with software
> rendered decorations. You might even try whether stitching decorations
> from 4 sub-surfaces would work. These should offer us more insight on
> how sub-surfaces should be defined. :-)
>
> There are still many open questions, ranging from implementation
> details I noted in code comments and commit messages, to heavy protocol
> additions like clipping. Some of the open questions are:
> - how should commits work in parent vs. sub-surfaces?
Commit should work the same way. It should commit itself and all it's
children. Furthermore it should commit all reordering of it's
immediate children.

> - do we allow nested sub-surfaces?
Yes, this makes it easier for client code to cooperate. If a library
wants to use subsurfaces it shouldn't need any special handling with
the application to achieve that. It also allows clients to commit a
group of sub-surfaces by using a dummy parent.

> - do we want a completely orthogonal interface for clipping and scaling,
>   or should it be limited to sub-surfaces?
Clipping and/or scaling should work for all kinds of surfaces. I don't
see any reason to limit it to sub-surfaces.

> - should we forbid reparenting?
> - should sub-surface role be revertible, instead of permanent?
I see this as a nice source for race conditions, although it may turn
out to be useful.

> - should a sub-surface be restricted to its parent's area?
It should not, especially since we don't have a good way to define the
parent area. Dummy surfaces whose only purpose is to hold sub-surfaces
depend on them not being restricted to the non-existing parent area.

> Personally, I have to postpone all that till January or later.
>
>
> Happy mid-winter and joyful New Year,
> pq
>
> [1] http://lists.freedesktop.org/archives/wayland-devel/2012-December/006623.html
> [2] http://lists.freedesktop.org/archives/wayland-devel/2012-December/006837.html
> [3] http://people.collabora.com/~pq/subsurface-1.png
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel

Sub-surfaces should also be able to get keyboard focus, no special
case is required for that. We should also make sure that dummy
surfaces without any attached buffers, but only sub-surfaces work
correctly with or without a input region.