Input and games.

[Todd Showalter]

On Thu, Apr 25, 2013 at 8:50 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:

> Todd has already listed what features a standard gamepad or controller
> has. Now someone should start designing the protocol. :-)

    Based on the wl_pointer docs, I should think it would look
something like this:

----------------------------------8<----------------------------------

wl_gamepad::connect -- gamepad appears
    The connect event occurs when a gamepad is plugged in, attaches
via wireless, or otherwise becomes available for use.  The message can
also be generated in response to a client "enumerate gamepads" query.

    The name argument may or may not be empty, depending on what
information the server has available, but if present can be used by
the client to determine what to do with wl_gamepad::extended events.

    The pad_index is used to tell messages from different gamepads
apart; a system may have multiple gamepads connected, and messages
from them need to be distinguishable.  The pad_index value may be much
higher than the number of gamepads currently connected if the user has
been connecting and disconnecting gamepads in pathological ways.

    The cookie may or may not contain useful data, and shouldn't be
counted on, but it is a hint to the application using the data whether
a connecting gamepad has been seen before.  If the hardware has a
software-visible serial number, the cookie should be a hash of that
value.  If the hardware is plugging in at a specific USB port, the
cookie should be a hash of the device path.  The cookie exists so that
if the application sees a gamepad disappear and then another gamepad
appears, if the cookie for the old and new controllers match it can
assume it has the same physical gamepad.

Arguments:
    time -- uint -- standard event timestamp
    name -- string -- device name
    pad_index -- uint -- which gamepad this is
    cookie -- uint -- unique device hash; UNRELIABLE, hint only

----------------------------------------------------------------
wl_gamepad::disconnect -- gamepad disappears
    The disconnect event occurs when a gamepad becomes unavailable,
either due to unplugging or signal loss.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is

----------------------------------------------------------------
wl_gamepad::stick -- gamepad stick movement
    A stick event occurs when there is stick movement on a gamepad.
It would be preferable if the protocol could handle float data, but
failing that the axis values can be mapped to a large integer range,
as below.  The precision of the fixed type is sufficient for most
current hardware, but not all; for example, the ps3 controller analog
sticks have a [-128 .. 127] range, but the ps3 dpad is actually
pressure sensitive, and therefore actually has an effective range of
[-255 .. 255].  It's not hard to imagine higher-precision controllers
in the future as prices come down.

    The stick_index indicates which stick the message pertains to; for
hardware with more than the standard number of joysticks/thumbsticks,
higher index values are possible, but 0 is always left stick, 1 is
always right stick and 2 is always the dpad.  Even if the physical
hardware lacks one or more of those axis values, additional axis
values will be mapped above 2.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is
    stick_index -- uint -- 0 for left stick, 1 for right stick, 2 for dpad
    x -- int -- the x axis of the stick mapped to [-2^15 .. 2^15 - 1]
    y -- int -- the y axis of the stick mapped to [-2^15 .. 2^15 - 1]

----------------------------------------------------------------
wl_gamepad::trigger -- gamepad analog trigger movement
    A trigger event occurs when there is analog trigger movement on a
gamepad.  As with stick messages, it would be preferable if the axis
value could be sent as float, but failing that the value can be mapped
to a large integer range.

    The trigger_index is 0 for left stick values and 1 for right stick
values.  Hardware with more triggers can potentially supply higher
values; the pressure-sensitive buttons on the ps3 controller would go
here, for instance.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is
    trigger_index -- uint -- 0 for left trigger, 1 for right trigger
    x -- uint -- the trigger value mapped to [0 .. 2^15 - 1]

----------------------------------------------------------------
wl_gamepad::button -- gamepad button press
    A button event occurs when a button is pressed or released.  The
standard buttons are:

0 - BUTTON_FACE_NORTH -- triangle on ps3, y on xbox
1 - BUTTON_FACE_EAST -- circle on ps3, b on xbox
2 - BUTTON_FACE_SOUTH -- x on ps3, a on xbox
3 - BUTTON_FACE_WEST -- square on ps3, x on xbox
4 - BUTTON_SHOULDER_LEFT -- L1 on ps3, LT on xbox
5 - BUTTON_SHOULDER_RIGHT -- R1 on ps3, RT on xbox
6 - BUTTON_LEFT_STICK -- left stick click
7 - BUTTON_RIGHT_STICK -- right stick click
8 - BUTTON_START -- start button

    Controllers may have other buttons, and if so they must map to
index values higher than those of the standard buttons.  Nonstandard
buttons can only be understood in the context of the information
delivered via the wl_gamepad::connect event.

    There is perhaps a question here about whether to deal with things
like controller keyboards; some game controllers have keyboards that
connect to them for things like in-game messaging.  Arguably they
belong within the gamepad protocol if they're going to be handled,
since they're per-player keyboards.  That said, they're also uncommon.
 If they are going to be handled, it also makes sense to ask whether
this is actually something where we should be bringing in the wl_seat
abstraction, but that might be abusing wl_seat.  The alternative would
be to do something like use keyboard keysyms, but set the high bit.
Regardless, I'm not sold on including them in the protocol at all.
Call it an open question.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is
    button_index -- uint -- index of the button that changed state
    state -- uint -- 0 for released, 1 for pressed

----------------------------------------------------------------
wl_gamepad::accelerometer
    An optional part of the protocol; an orientation event indicates a
change in accelerometer data.  Accelerometer data is assumed to be
generated as a three axis vector; some hardware apparently produces
quaternions, which is interesting, but quaternions (at least,
normalized quaternions) don't give you velocity, just orientation.
Besides, without float values in the protocol the data the quaternion
encoding gets icky fast; quaternions are normalized 4d vectors, which
means they need a lot of precision below the decimal.

    This is a part of the protocol that is being included for
discussion; I'm not sold on it.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is
    accel_index -- uint -- index of the accelerometer that changed state
    x -- uint -- accelerometer x axis, mapped such that 1.0f == 2^15 - 1
    y -- uint -- accelerometer y axis, mapped such that 1.0f == 2^15 - 1
    z -- uint -- accelerometer z axis, mapped such that 1.0f == 2^15 - 1

----------------------------------------------------------------
wl_gamepad::sysbutton -- gamepad system button event
    A sysbutton event occurs when the system button (the ps button on
a ps3 controller, the glowy x button on the xbox 360 controller, the
home button on the wii controller) is pressed.  While this information
might be passed on to the application, it is somewhat expected that
his event will be trapped and acted upon by the window manager.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is

----------------------------------------------------------------
wl_gamepad::extended -- gamepad hardware-specific extended event
    This is an optional extension to the protocol; a method of
handling extra data created by gamepads beyond the standard protocol.
Most extended information would pass through more standard messages;
extra buttons, sticks or trigger values should use those messages with
higher index values.  This message is for handling anything that
doesn't fit the standard model.  I'm not sold on this event either; it
might just be a bad idea.

Arguments:
    time -- uint -- standard event timestamp
    pad_index -- uint -- which gamepad this is
    subtype -- uint -- ordinal identifying the event subtype
    a -- uint -- first parameter
    b -- uint -- second parameter
    c -- uint -- third parameter
    d -- uint -- fourth parameter

----------------------------------------------------------------

                                             Todd.

--
 Todd Showalter, President,
 Electron Jump Games, Inc.