[PATCH wayland v4 1/5] protocol: define the concept of wl_surface role

[Jason Ekstrand]

That applies to the whole series, BTW


On Thu, Aug 21, 2014 at 9:03 AM, Jason Ekstrand <jason at jlekstrand.net>
wrote:

> LGTM
> Reviewed-by: Jason Ekstrand <jason.ekstrand at intel.com>
>
>
> On Thu, Aug 21, 2014 at 2:52 AM, Pekka Paalanen <ppaalanen at gmail.com>
> wrote:
>
>> From: Pekka Paalanen <pekka.paalanen at 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.paalanen at 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
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140821/87890222/attachment.html>