That applies to the whole series, BTW
On Thu, Aug 21, 2014 at 9:03 AM, Jason Ekstrand <ja...@jlekstrand.net> wrote: > LGTM > Reviewed-by: Jason Ekstrand <jason.ekstr...@intel.com> > > > On Thu, Aug 21, 2014 at 2:52 AM, 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. >> >> v3: make role permanent, there is no such thing as "losing a role". >> Re-issuing the same role again must be allowed for wl_pointer.set_cursor >> et al. to work. >> >> v4: clarify the semantics of destroying a role object. >> >> Signed-off-by: Pekka Paalanen <pekka.paala...@collabora.co.uk> >> --- >> protocol/wayland.xml | 33 +++++++++++++++++++++++++++++++-- >> 1 file changed, 31 insertions(+), 2 deletions(-) >> >> diff --git a/protocol/wayland.xml b/protocol/wayland.xml >> index bb457bc..621c64d 100644 >> --- a/protocol/wayland.xml >> +++ b/protocol/wayland.xml >> @@ -973,8 +973,37 @@ >> 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 is set permanently for the whole lifetime of the >> + wl_surface object. Giving the current role again is allowed, >> + unless explicitly forbidden by the relevant interface >> + specification. >> + >> + Surface roles are given by requests in other interfaces such as >> + 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. >> + >> + Destroying the role object does not remove the role from the >> + wl_surface, but it may stop the wl_surface from "playing the role". >> + For instance, if a wl_subsurface object is destroyed, the >> wl_surface >> + it was created for will be unmapped and forget its position and >> + z-order. It is allowed to create a wl_subsurface for the same >> + wl_surface again, but it is not allowed to use the wl_surface as >> + a cursor (cursor is a different role than sub-surface, and role >> + switching is not allowed). >> </description> >> >> <enum name="error"> >> -- >> 1.8.5.5 >> >> >
_______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel