Gamepad focus model (Re: Input and games.)

[Pekka Paalanen]

Hi Todd,

Daniel nicely replied to the most important comments, here are a few
more.

On Mon, 6 May 2013 09:48:47 -0400
Todd Showalter <todd at electronjump.com> wrote:

> On Mon, May 6, 2013 at 8:36 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> 
> > Into wl_seat, we should add a capability bit for gamepad. When the bit
> > is set, a client can send wl_seat::get_gamepad_manager request, which
> > creates a new wl_gamepad_manager object. (Do we actually need a
> > capability bit?)
> 
>     There are options here:
> 
> - have the capability bit, if the bit is set the client can request a
> manager -- has to deal with the case where the client sent the request
> but the caps bit wasn't set, presumably by returning NULL or -1 the
> protocol equivalent
> 
> - leave out the caps bit, client requests the manager if they want it,
> they get NULL equivalent if there are no gamepads
> 
> - leave out the caps bit, gampad manager is always there, but can be
> expected to return 0 if asked to enumerate gamepads when none are
> connected

Yeah, like Daniel said, there is no concept of a "return value".

When a client creates a new object, the server can only either agree,
or disconnect the client with a protocol error. Any other behaviour
requires specialized handling, and causes a roundtrip, where the client
must either wait for a reply before continuing, or risk having further
requests ignored without any obvious way to know what got ignored in
the end. Both cases are unacceptable.

When a client sends a request, that creates a new protocol object, then
from the client's point of view, the object is created on that instant,
before the request has even been submitted to the wire. This allows the
client to immediately send more requests on that new object, without
waiting for a roundtrip in between. The same works also in the reverse
direction, when the server creates protocol objects by sending events.

A major design principle in Wayland is to minimize roundtrips, as it
leads to better performance and lower overhead.

> > A wl_gamepad_manager will send an event for each physical gamepad (as
> > it dynamically appears, if hotplugged later) associated with this
> > particular wl_seat, creating a wl_gamepad object for each.
> >
> > A wl_gamepad object will send an event about the player id as the first
> > thing, and also if it later changes.
> 
>     Some gamepads don't have player id controls, so we can't rely on
> them, but supporting them where we can is useful.  I think it's best
> viewed as a really forceful hint as to the player's ID, where
> otherwise we're stuck doing heuristics with plugging.

It's not about the gamepad capabilities at all. It's just an
assignment, configured in the server: this input device belongs to
player N.

> > If a gamepad is hot-unplugged, a wl_gamepad event will notify about
> > that, and the wl_gamepad object becomes inert (does not send any
> > events, ignores all but the destroy request).
> 
>     Dealing gracefully with things like wireless gamepads running
> their batteries flat or moving out of radio range is important, which
> is what I assume this is to deal with.  I presume the idea here is
> that if the player moves back into range or replaces the batteries,
> the wl_gamepad object revives?

No, that's not what I had in mind. An inert protocol object is
permanently dead by definition, and is only waiting for destruction by
the client. This is just a convenience to avoid races between the
server and the client.

If the gamepad later comes back "online", it is like it was hotplugged
again: a new wl_gamepad object is sent, with the same player id as
before.

> > Gamepad input events are delivered according to the keyboard focus of
> > the related wl_seat. If there is no keyboard to focus, then use the
> > pointer focus, or something. It doesn't really affect the protocol
> > design how the focus is assigned. However, would we need a
> > wl_gamepad::enter,leave events? Probably, along with events for initial
> > state. Or maybe enter/leave should be wl_gamepad_manager events?
> 
>     I think we need enter/leave events.  The client can be responsible
> for cleaning up its own state, though if an initial state is sent on
> focus gain that makes things much easier.

Yeah, the main point of the leave event is to say "you don't get any
more input events from this device, until it comes back", and it also
implies that the client should forget all temporary state of the
gamepad, like which buttons were down.

Immediately following an enter event, or in the enter event, a new set
of current state is sent. Notice, that this should not be done by
sending e.g. fake button-down events. We have a protocol design policy,
that input events from user actions are never manufactured.

>     I don't see anything here that raises any flags for me; at least
> at first reading it seems quite usable.

Cool. There are lots of details to get right, but those are easier to
tune with some XML at hand.


Thanks,
pq