On Tue, 19 Aug 2014 10:29:21 +0300 Pekka Paalanen <ppaala...@gmail.com> wrote:
> From: Pekka Paalanen <pekka.paala...@collabora.co.uk> > > Define what a role is, and what restrictions there are. > > A change to existing behaviour is that a role cannot be changed at all > once set. However, this is unlikely to cause problems, as there is no > reason to re-use wl_surfaces in clients. > > v2: give more concrete examples of roles, define losing a role, Jasper > rewrote the paragraph on how a role is set. > > Signed-off-by: Pekka Paalanen <pekka.paala...@collabora.co.uk> > --- > protocol/wayland.xml | 26 ++++++++++++++++++++++++-- > 1 file changed, 24 insertions(+), 2 deletions(-) > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > index 2d57f69..d3fcaec 100644 > --- a/protocol/wayland.xml > +++ b/protocol/wayland.xml > @@ -973,8 +973,30 @@ > local coordinates of the pixel content, in case a buffer_transform > or a buffer_scale is used. > > - Surfaces are also used for some special purposes, e.g. as > - cursor images for pointers, drag icons, etc. > + A surface without a "role" is fairly useless, a compositor does > + not know where, when or how to present it. The role is the > + purpose of a wl_surface. Examples of roles are a cursor for a > + pointer (as set by wl_pointer.set_cursor), a drag icon > + (wl_data_device.start_drag), a sub-surface > + (wl_subcompositor.get_subsurface), and a window as defined by a > + shell protocol (e.g. wl_shell.get_shell_surface). > + > + A surface can have only one role at a time. Initially a > + wl_surface does not have a role. Once a wl_surface is given a > + role, it can never be given a different role again, even if the > + wl_surface loses the role in between. > + > + Surface roles are set by requests in other interfaces such as Bah... forgot to save one tiny change: "Surface roles are given by ..." -------------------^^^^^ Thanks, pq > + wl_pointer.set_cursor. The request should explicitly mention > + that this request gives a role to a wl_surface. Often, this > + request also creates a new protocol object that represents the > + role and adds additional functionality to wl_surface. When a > + client wants to destroy a wl_surface, they must destroy this 'role > + object' before the wl_surface. > + > + A wl_surface may lose its role as specified in the interface > + that gave it the role or in the interface of the role object. > + Losing a role means losing all the role-specific state. > </description> > > <enum name="error"> _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel