[PATCH wayland-protocols 3/4] tablet: restrict the cursor surface to one per tool

[Peter Hutterer]

On Wed, May 11, 2016 at 08:04:35AM -0500, Yong Bakos wrote:
> On May 10, 2016, at 9:51 PM, Peter Hutterer <peter.hutterer at who-t.net> wrote:
> > 
> > The initial approach was to allow one surface to be re-used between tools,
> > seats and even used together as wl_pointer cursor surface. This has a few
> > drawbacks, most of which are related to managing the surface correctly in the
> > compositor. For example, the same cursor surface could have two different
> > hotspots. Animated cursors should animate independently rather than update at
> > the same time.
> > 
> > Furthermore: a client cannot know when a surface will cease being used as a
> > cursor surface. The basic assumption of "after focus out" is an implementation
> > detail in the compositor and unless the client unsets the cursor it is not
> > guaranteed that the surface is released. This again makes sharing a surface
> > less obvious - you cannot know if the wl_pointer surface is still in use when
> > you set it for a new wp_tablet_tool.
> > 
> > Avoid these headaches (and push some of them to the clientl) by simply
> > restricting a wl_surface to be assigned to a single tool. For the 99% use case
> > where we have one tablet with two tools (pen + eraser) this means we merely
> > get two extra surfaces, and the two don't usually share the same cursor shape
> > anyway. If sharing is absolutely, a client may still opt to share the
> > underlying wl_buffer.
> > 
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> 
> Do you think that last sentence should be mentioned in the description?
> Noted inline below...
> 
> 
> > ---
> > unstable/tablet/tablet-unstable-v2.xml | 12 +++++-------
> > 1 file changed, 5 insertions(+), 7 deletions(-)
> > 
> > diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> > index e7b8626..d3f57ff 100644
> > --- a/unstable/tablet/tablet-unstable-v2.xml
> > +++ b/unstable/tablet/tablet-unstable-v2.xml
> > @@ -225,13 +225,11 @@
> > 	and pending input regions become undefined, and the wl_surface is
> > 	unmapped.
> > 
> > -	This request gives the surface the role of a cursor. The role
> > -	assigned by this request is the same as assigned by
> > -	wl_pointer.set_cursor meaning the same surface can be
> > -	used both as a wl_pointer cursor and a wp_tablet cursor. If the
> > -	surface already has another role, it raises a protocol error.
> > -	The surface may be used on multiple tablets and across multiple
> > -	seats.
> > +	This request gives the surface the role of a wp_tablet_tool cursor. A
> > +	surface may only ever be used as cursor surface for one
> > +	wp_tablet_tool. If the surface already has another role or has
> > +	previously been used as cursor surface for a different tool, a
> > +	protocol error is raised.
> 
> Is it worth mentioning here that "Clients may still opt to share the underlying
> wl_buffer, if sharing is absolutely necessary." Or perhaps its worth /not/
> mentioning, in order to not encourage the practice?

I don't think it should be documented here, because that's a matter of how a
wl_surface relates to the wl_buffer. Whether the surface is used as cursor
or not should not determine that interaction, otherwise we'd have to specify
that too and that's just opening a can of worms.

Cheers,
   Peter