<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Aug 18, 2014 at 10:14 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:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">From: Pekka Paalanen <<a href="mailto:pekka.paalanen@collabora.co.uk">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></blockquote><div><br></div><div>Thanks for this. I was going to add it in the Publican docs, but those are significantly out of date and I spent more time laughing at them than writing things in them. We should fix that. :(<br> <br></div><div>Looks good overall. I'm going to be a terrible person and nitpick your grammar. Sorry about that in advance!<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> Signed-off-by: Pekka Paalanen <<a href="mailto:pekka.paalanen@collabora.co.uk">pekka.paalanen@collabora.co.uk</a>><br> ---<br> protocol/wayland.xml | 20 ++++++++++++++++++--<br> 1 file changed, 18 insertions(+), 2 deletions(-)<br> <br> diff --git a/protocol/wayland.xml b/protocol/wayland.xml<br> index 2d57f69..39af61f 100644<br> --- a/protocol/wayland.xml<br> +++ b/protocol/wayland.xml<br> @@ -973,8 +973,24 @@<br> 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 not<br> + know where, when or how to present it. The role is the purpose of a<br> + wl_surface. Examples of roles are a cursor for a pointer, a drag icon,<br> + a sub-surface, and a window as defined by a shell protocol.<br></blockquote><div><br></div><div>I'd give more concrete examples. "Examples of surface roles include the pointer icon (as set by wl_pointer.set_cursor), a drag icon (as set by wl_data_device.start_drag), ..."<br> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> + A surface can have only one role at a time. Initially a wl_surface<br> + does not have a role. Once a role is set, it can never be set to a<br> + different role again.<br></blockquote><div><br></div><div>There is an important clarification here. If I have two surfaces like "pointer cursor", "I-beam cursor", I can call wl_pointer.set_cursor on either of them in succession. I could imagine someone being confused that "the pointer icon" role is a singleton, and when the I-beam cursor gains it, the pointer cursor loses it, and she might think that you would have to create a new wl_surface since it's illegal to set the wl_pointer.set_cursor role on the pointer cursor surface again.<br> <br></div><div>What we're trying to do is prevent surface reuse, so you can't transform something that was once a pointer cursor into a wl_subsurface or anything like that.<br></div><div><br></div><div>I'm not really sure how to describe this, though. I'm not too happy with this, but it's the best I came up with.<br> </div><div><br></div><div>"A surface can only have one role at a time. When you first make a request to set a surface's role, the surface can then only have that role forever, even if it loses the role. For instance, if somebody sets the 'subsurface' role on a wl_surface, then it can only ever be a subsurface, even if you destroy the associated wl_subsurface object"<br> <br>We should probably describe the concept of "losing the role" from e.g. wl_subsurface.destroy, wl_pointer.set_cursor above.<br></div><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> + A role is set by a request in another interface than wl_surface<br> + itself. The protocol specification of the other interface<br> + defines, that the request gives a specific role to a wl_surface.<br> + Often, this request also creates a new protocol object, that<br> + represents the role and extends the interface to the wl_surface.<br> + If such a new protocol object is created, clients are<br> + recommended to destroy it before they destroy the wl_surface.<br> + Whether destroying the wl_surface first is legal, depends on the<br> + protocol interface related to the role.<br></blockquote><div><br></div><div>I know you're a non-native speaker, so I won't bash your grammar in-depth. I'll just offer a replacement paragraph with everything fixed up. I'm also going to strengthen up the wording here a bit.<br> <br></div><div>"Surface roles are set 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 clients want to destroy a surface, they must destroy this 'role object' before the wl_surface, except when specified otherwise."<br> </div><div><br></div><div>We should also change the description of wl_subsurface to say that destroying the wl_surface before the role object is an exception to this rule, and is considered legacy behavior, so clients should try not to do it.<br> </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> </description><br> <br> <enum name="error"><br> <span class=""><font color="#888888">--<br> 1.8.5.5<br> <br> _______________________________________________<br> wayland-devel mailing list<br> <a href="mailto:wayland-devel@lists.freedesktop.org">wayland-devel@lists.freedesktop.org</a><br> <a href="http://lists.freedesktop.org/mailman/listinfo/wayland-devel" target="_blank">http://lists.freedesktop.org/mailman/listinfo/wayland-devel</a><br> </font></span></blockquote></div><br><br clear="all"><br>-- <br> Jasper<br> </div></div>