On Thu, Apr 25, 2013 at 8:50 AM, Pekka Paalanen <ppaala...@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. _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel