Inter-client surface embedding

Pekka Paalanen ppaalanen at
Sun Feb 16 23:21:33 PST 2014

On Mon, 17 Feb 2014 00:04:19 +0000 (GMT)
Mark Thomas <mark-wayland-devel at> wrote:

> As part of my current attempts to get MATE fully working on Wayland, I was 
> planning to take a look at porting mate-panel this weekend.  However, I 
> pretty quickly hit the first snag, which is that Gtk on Wayland doesn't 
> support the GtkSocket/GtkPlug interface, which mate-panel relies heavily 
> upon.
> This is because Wayland doesn't understand the idea of linking different 
> clients' surfaces together, so I've had a first pass at implementing an 
> interface that lets you do that.
> My changes are available in github at
> I'd be interested to hear what people think.
> I've got it working with a couple of toy clients, so I think the theory is 
> sound, but there are a few niggles to work through.
> What works:
>    - Clients can create one or more "hole" objects on a surface.  This 
> gives them a "uid" (32-bit number) which they can pass to other clients of 
> the same wayland server (e.g. via a socket, D-Bus, etc.).  For the toy 
> apps you do this manually.
>    - Other clients with the uid in hand can create a "plug" that attaches 
> to that hole.  This effectively creates a subsurface of the other client's 
> surface.  (In fact, internally a plug is a weston_subsurface with a couple 
> of extra fields in use).
>    - The hole can have a position and size set.  The size is notified 
> to the "plug" client who is expected to conform to it.  Currently there's 
> no policing of this, but I expect a more robust implementation would want 
> to.
>    - Either side can tear down the connection between the two.  If the 
> hole goes away, or the hole's client calls "remove" on the hole, then the 
> plug client receives a "removed" event.
> What needs some work:
>    - The subsurface has to be unsynchronized, otherwise the plug client's 
> updates don't render unless the hole client is also updating.  Not sure 
> how this will work with nested subsurfaces if synchronization is 
> inherited.
>    - The subsurface has separate focus from the main window surface.  For 
> the usual use cases of embedding like this, you'd prefer the parent 
> surface to remain focused (or at least, appear focused) while the embedded 
> surface is being interacted with.   Not sure if this is a general feature 
> of subsurfaces, nor what could be done about it.


set an empty input region, and the input events will fall through the
surface. So you intend that the embedded client never gets input for
the embedded surface directly?

>    - The toy examples are quite rapidly thrown together and so aren't 
> particularly good.  Improvements gladly welcomed.
>    - The interfaces are incomplete (and undocumented, sorry).
>    - There's probably a bunch of other things I've not thought about.

Did you know about the earlier attempts on this? I think you should be
able to find some discussion or a proposal by searching the
wayland-devel@ archives for "foreign surface" protocol, IIRC. At that
time, the conclusion was to use a nested mini-compositor approach
instead, which is demoed in weston clients as weston-nested.

I see your protocol definition lacks all documentation on how it is
supposed to be used and implemented. A verbal description would be nice,
giving an overview.

How do you handle glitch-free resizing? Sub-surfaces handle glitch-free
resizing by temporarily changing the sub-surface into synchronized
mode, assuring the sub-surface has new content in the correct new size,
and then atomically commits the whole tree of sub-surfaces with a
commit to the root wl_surface. Do you have any synchronization
guarantees like that? With separate processes cooperating to create a
single window it will be even more important than with the
existing sub-surfaces case, and you will need more IPC between the two
clients. Using client1<->client2 IPC would be more efficient than

Have you considered if your use case could be better served by
moving some functionality into a special DE-specific client (e.g.
weston-desktop-shell) and having separate protocol (an alternative
"shell" interface) for panel clients to tell their wl_surface needs to
be embeded into the panel, rather than implementing a generic
mechanism where you need to solve all corner-cases in a generic way?
If the protocol extension was designed particularly for panels, you
might have an easy way out by defining special resize behaviour which
would avoid most client<->client negotiation.

You need something special to place the panel itself on the desktop
anyway, so I think it's ok to have the compositor specifically help the
special DE-specific client to do the embedding properly.


More information about the wayland-devel mailing list