<div dir="ltr">That applies to the whole series, BTW<br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Aug 21, 2014 at 9:03 AM, Jason Ekstrand <span dir="ltr"><<a href="mailto:jason@jlekstrand.net" target="_blank">jason@jlekstrand.net</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">LGTM<br>Reviewed-by: Jason Ekstrand <<a href="mailto:jason.ekstrand@intel.com" target="_blank">jason.ekstrand@intel.com</a>><br>
</div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Aug 21, 2014 at 2:52 AM, Pekka Paalanen <span dir="ltr"><<a href="mailto:ppaalanen@gmail.com" target="_blank">ppaalanen@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>From: Pekka Paalanen <<a href="mailto:pekka.paalanen@collabora.co.uk" target="_blank">pekka.paalanen@collabora.co.uk</a>><br>
<br>
Define what a role is, and what restrictions there are.<br>
<br>
A change to existing behaviour is that a role cannot be changed at all<br>
once set. However, this is unlikely to cause problems, as there is no<br>
reason to re-use wl_surfaces in clients.<br>
<br>
v2: give more concrete examples of roles, define losing a role, Jasper<br>
rewrote the paragraph on how a role is set.<br>
<br>
v3: make role permanent, there is no such thing as "losing a role".<br>
Re-issuing the same role again must be allowed for wl_pointer.set_cursor<br>
et al. to work.<br>
<br>
</div>v4: clarify the semantics of destroying a role object.<br>
<div><br>
Signed-off-by: Pekka Paalanen <<a href="mailto:pekka.paalanen@collabora.co.uk" target="_blank">pekka.paalanen@collabora.co.uk</a>><br>
---<br>
</div> protocol/wayland.xml | 33 +++++++++++++++++++++++++++++++--<br>
1 file changed, 31 insertions(+), 2 deletions(-)<br>
<br>
diff --git a/protocol/wayland.xml b/protocol/wayland.xml<br>
index bb457bc..621c64d 100644<br>
--- a/protocol/wayland.xml<br>
+++ b/protocol/wayland.xml<br>
@@ -973,8 +973,37 @@<br>
<div><div> local coordinates of the pixel content, in case a buffer_transform<br>
or a buffer_scale is used.<br>
<br>
- Surfaces are also used for some special purposes, e.g. as<br>
- cursor images for pointers, drag icons, etc.<br>
+ A surface without a "role" is fairly useless, a compositor does<br>
+ not know where, when or how to present it. The role is the<br>
+ purpose of a wl_surface. Examples of roles are a cursor for a<br>
+ pointer (as set by wl_pointer.set_cursor), a drag icon<br>
+ (wl_data_device.start_drag), a sub-surface<br>
+ (wl_subcompositor.get_subsurface), and a window as defined by a<br>
+ shell protocol (e.g. wl_shell.get_shell_surface).<br>
+<br>
+ A surface can have only one role at a time. Initially a<br>
+ wl_surface does not have a role. Once a wl_surface is given a<br>
+ role, it is set permanently for the whole lifetime of the<br>
+ wl_surface object. Giving the current role again is allowed,<br>
+ unless explicitly forbidden by the relevant interface<br>
+ specification.<br>
+<br>
+ Surface roles are given by requests in other interfaces such as<br>
+ wl_pointer.set_cursor. The request should explicitly mention<br>
+ that this request gives a role to a wl_surface. Often, this<br>
+ request also creates a new protocol object that represents the<br>
+ role and adds additional functionality to wl_surface. When a<br>
+ client wants to destroy a wl_surface, they must destroy this 'role<br>
+ object' before the wl_surface.<br>
+<br>
+ Destroying the role object does not remove the role from the<br>
+ wl_surface, but it may stop the wl_surface from "playing the role".<br>
</div></div>+ For instance, if a wl_subsurface object is destroyed, the wl_surface<br>
+ it was created for will be unmapped and forget its position and<br>
+ z-order. It is allowed to create a wl_subsurface for the same<br>
+ wl_surface again, but it is not allowed to use the wl_surface as<br>
+ a cursor (cursor is a different role than sub-surface, and role<br>
+ switching is not allowed).<br>
<div><div> </description><br>
<br>
<enum name="error"><br>
--<br>
1.8.5.5<br>
<br>
</div></div></blockquote></div><br></div>
</div></div></blockquote></div><br></div>