[RFC DRAFT] graphics tablet protocol extension

[Peter Hutterer]

On Thu, Oct 03, 2013 at 03:44:51PM +0200, David Herrmann wrote:
[...]
> >> >      <event name="capabilities">
> >> > @@ -1306,6 +1307,19 @@
> >> >        <arg name="name" type="string"/>
> >> >      </event>
> >> >
> >> > +    <!-- Version 4 additions -->
> >> > +    <request name="get_tablet_manager" since="4">
> >> > +      <description summary="return tablet manager object">
> >> > +        The ID provided will be initialized to the wl_tablet_manager
> >> > +        interface for this seat. This can then be used to retrieve the
> >> > +        objects representing the actual tablet devices.
> >> > +
> >> > +        This request only takes effect if the seat has the tablets
> >> > +        capability.
> >> > +      </description>
> >> > +      <arg name="id" type="new_id" interface="wl_tablet_manager"/>
> >> > +    </request>
> >> > +
> >> >    </interface>
> >> >
> >> >    <interface name="wl_pointer" version="3">
> >> > @@ -1617,6 +1631,223 @@
> >> >      </event>
> >> >    </interface>
> >> >
> >> > +  <interface name="wl_tablet_manager" version="1">
> >> > +    <description summary="controller object for graphic tablet devices">
> >> > +      A tablet manager object provides requests to access the graphics
> >> > +      tablets available on this system.
> >> > +    </description>
> >> > +
> >> > +    <enum name="tablet_type">
> >> > +      <description summary="tablet type">
> >> > +        Describes the type of tablet.
> >> > +      </description>
> >> > +      <entry name="external" value="0" summary="The tablet is an external tablet, such as an Intuos" />
> >> > +      <entry name="internal" value="1" summary="The tablet is an built-in tablet, usually in a laptop" />
> >> > +      <entry name="display" value ="2" summary="The tablet is a display tablet, such as a Cintiq" />
> >> > +    </enum>
> >> > +
> >> > +    <event name="device_added">
> >> > +      <description summary="new device notification"/>
> >> > +      <arg name="id" type="new_id" interface="wl_tablet" summary="the newly added graphics tablet " />
> >> > +      <arg name="name" type="string" summary="the device name"/>
> >> > +      <arg name="vid" type="uint" summary="vendor id"/>
> >> > +      <arg name="pid" type="uint" summary="product id"/>
> >> > +      <arg name="type" type="uint" />
> >>
> >> So tablets are server-side created objects? I think we tried to avoid
> >> that. Only wl_display uses this now, afaik. Even for globals we added
> >> the wl_registry interface which just announces unique names which the
> >> client then binds to via wl_registry.bind. So why not turn
> >> wl_tablet_manager into wl_tablet_registry and provide the same
> >> functions as the global registry?
> >
> > two things:
> > having thought about this (and talked to krh and daniels at XDC) the tablet
> > manager shouldn't be necessary anymore. It used to have the device_removed
> > event, but now it's just an intermediate layer that can be removed by moving
> > the device_added event up into the seat and sending it conditional on either
> > get_tablets or on binding to the seat with the correct version.
> 
> That sounds much better. I like the approach with advertising tablets
> on the seat via "tabled_added" events. I don't even think it needs to
> be conditional. Older clients just ignore it which seems fine.
> 
> >
> > as for moving tablets over to a global: my first attempt was to have
> > wl_tablet_manager as a global. the server-side objects stay in that case, if
> > you bind to the manager it sends you events about the tablets. so for three
> > tablets and the client wanting tablet 2 it could look like that:
> >
> >   wl_tablet_manager::bind
> >        event:device added(1)
> >        event:device added(2)
> >        event:device added(3)
> >        request:get_device(some client id, 2)
> >
> > at this point you still need some sort of ID to identify the tablet when the
> > client request comes, so you might as well use server-allocated IDs and let
> > the client discard what it doesn't want:
> >
> >   wl_tablet_manager::bind
> >        event:device added(server id 1)
> >        event:device added(server id 2)
> >        event:device added(server id 3)
> >        request:release (server id 1)
> >        request:release (server id 3)
> >
> > so I don't know how to get rid of server-allocated IDs.
> 
> Ouh, you always need server-allocated IDs, but not server-allocated
> names. What wl_registry does is to provide its own ID namespace for
> globals but they are unrelated to Wayland-protocol IDs and just
> identify the global. So for tablets you could even reuse the
> underlying input-device ID (or event evdev ID) if you wanted. A simple
> counter would be enough, though. A client-side "get_tablet(tablet-id,
> client-id)" call with the given tablet ID would then allow the client
> to create the object itself.

once again that was my first approach but then you have a internal ID
mapping that is IMO unnecessary. if we need to assign an ID to send to the
client so the client assigns another ID to init the device - why not
allocate the final ID in the server. Plus, you then have to handle the race
conditions where the device disappears before the client assigns an ID to
it and you can't handle that through the object directly.

> The advantage of your first example is that the client controls the
> namespace (client side namespace is _much_ bigger than server-side).
> Especially for hotpluggable devices we don't want to risk cluttering
> the server-side ID namespace as we have no control over how many of
> these may exist. (compared to wl_seat objects which are rather static
> and thus could easily be server-side allocated).

is ID allocation for a handful of devices really a problem?

> 
> wl_global used to be a server-allocated API pre 1.0 then krh changed
> it to wl_registry. I don't know his exact reasons but I think it's to
> try to avoid server-side allocated global IDs at all. But obviously we
> should ask him. This is just my understanding of it.
> 
> > as said above, the tablet_manager doesn't really provide that much
> > functionality at this point, so another alternative is to have wl_tablet
> > directly as global, but I don't know how to hook that up with seats
> > then. and you'd still have server-allocated IDs.
> 
> Yepp, if it's a global you get problems binding it to a seat. Don't
> think this is a good idea.
> 
> >
> > yes, it is much like the EVIOCGRAB. once bound the client has a straight
> > connection to the tablet and gets all events (provided the surface is in
> > focus). So you can say that your GIMP canvas maps directly to your tablet,
> > regardless of where the canvas is. this is a corner use-case, as I said I'm
> > not sure this is necessary atm.
> >
> > otoh it's not like an EVIOCGRAB in that the compositor is still controlling
> > the device. if the compositor decides the surface doesn't deserve focus at
> > the moment (e.g. because it's minimised or somesuch), you could still handle
> > the tablet normally in other clients. but from the client's POV the tablet
> > is bound, with the upper left of the tablet corresponding to the upper left
> > of the surface.
> 
> But binding doesn't do scaling, right? So the upper-left is bound, but
> that doesn't mean the lower-right is bound to the lower-right corner,
> does it? Would be weird, I guess.

correct. the client has the axis range and resolution, so the rest is up to
the client.

> Regarding Grab: So does this mean the server _can_ actually allow two
> clients to bind to a tablet if one is minimized? Or does it just mean
> the server is allowed to use the tablet itself if the client is
> minimized? Because your comment clearly states only one client can
> bind at a time.
> 
> Just as a remark, DirectInput on Windows only allows clients with
> input-focus (here: of the respective wl_seat) to bind to devices. Once
> it looses focus, the binding is lost. This allows clients to share
> devices but also to get exclusive access if active/focused.

sounds good, I'll amend accordingly.

Cheers,
   Peter