wl_tablet specification draft

[Chandler Paul]

Hello! As you all know I've been working on adding drawing tablet
support to the Wayland protocol. Now that we've added support for
tablets to libinput, the next step is writing the actual protocol that
will be implemented by the compositor. Following this blurb is the
current draft of the tablet protocol we have. Feel free to critique it.

Cheers,
	Lyude

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

                           wl_tablet specifications

General notes:
- Many of the axis values in this are normalized to either 0-65535 or
  (-65535)-65535. I would leave the axis values as-is since libinput reports
  them as doubles, but since we only have 8 bits of precision we'd lose way
  too many values. 65535 seemed like the best choice since it's the maximum
  length of a signed short, it's a whole number, it's way higher then the
  range of any of the axes (with the exception of X and Y, but these aren't
  normalized anyway) and we can do just about any basic arithmatic with it
  without having to worry about overflowing. plus, all we have to do is
  multiply the value by 65535 after we get it from libinput.

Definitions:
- WL_TABLET_AXIS_MAX = 65535
- WL_TABLET_AXIS_MIN = (-65535)

Enumerators:
- wl_tablet_axis:
        - WL_TABLET_AXIS_X
        - WL_TABLET_AXIS_Y
	  Represents the X and Y axes respectively. Only used in bitfields to
	  indicate whether or not they've changed since the last event.

        - WL_TABLET_AXIS_DISTANCE
          Represents the distance axis on a tablet. Normalized from 0 to
          WL_TABLET_AXIS_MAX. For tablets that do not support reporting the
          distance, this will always be 0.

        - WL_TABLET_AXIS_PRESSURE
          Represents the pressure axis on a tablet. Normalized from 0 to
          WL_TABLET_AXIS_MAX. For tablets that do not support reporting the
          pressure, this will always be WL_TABLET_AXIS_MAX.

        - WL_TABLET_AXIS_TILT_VERTICAL
        - WL_TABLET_AXIS_TILT_HORIZONTAL
          Each represents the vertical and horizontal tilt axes respectfully.
          Normalized from WL_TABLET_AXIS_MIN to WL_TABLET_AXIS_MAX. For
          tablets that do not support this, this value will always be 0.

        - WL_TABLET_AXIS_CNT
          Represents the number of axes
- wl_tablet_tool_type:
        - pen
        - eraser
        - brush
        - pencil
        - airbrush
        - finger
        - mouse
        - lens
- wl_tablet_button_state
        - pressed
        - released

Events:
- proximity_in
  Sent when the tool comes into proximity above the client surface, either by
  the tool coming into proximity or a tool being in-proximity and moving to
  the client surface. If a tablet tool makes contact with the tablet at the
  same time that the tool comes into proximity, the proximity event comes
  first and the down event comes afterwards.
  Arguments:
        - Name: id
          Type: uint
          the id of the tablet sending this event.

        - Name: type
          Type: uint
          The type of tool that came into proximity, e.g. pen, airbrush, etc.

        - Name: serial
          Type: uint
	  The serial number of the tool that came into proximity. On tablets
	  where this isn't provided, this value will always be 0.

        - Name: x
          Type: fixed
          Surface relative x coordinate

        - Name: y
          Type: fixed
          Surface relative y coordinate

        - Name: surface
          Type: object
          Interface: wl_surface
          The current surface the tablet tool is over

        - Name: time
          Type: uint
          The time of the event with millisecond granularity.

        - Name: axes
          Type: array
	  The current values of each of the tablet axes starting at
	  WL_TABLET_AXIS_DISTANCE. The length of the array is equal to the
	  number of axes that are reported. Any axes >= WL_TABLET_AXIS_CNT
	  must be ignored. The size of the array remains fixed for the
	  lifetime of the tablet.

- proximity_out
  Send whenever the tool leaves the proximity of the tablet or moves out of
  the client surface. When the tool goes out of proximity, a set of button
  release events are sent before the initial proximity_out event for each
  button that was held down before the tablet tool left proximity. In
  addition, axis updates always come before a proximity-out event.
  Arguments:
        - Name: id
          Type: uint
          The id of the tablet sending this event.

        - Name: time
          Type: uint
          The time of the event with millisecond granularity.

- axis
  Sent whenever an axis on the tool changes. This can include movement on the
  X and Y axis.
  Arguments:
        - Name: id
          Type: uint
          The id of the tablet sending this event.

        - Name: x
          Type: fixed
          Surface relative x coordinate

        - Name: y
          Type: fixed
          Surface relative y coordinate

        - Name: surface
          Type: object
          Interface: wl_surface
          The current surface the tablet tool is over

        - Name: time
          Type: uint
          The time of the event with millisecond granularity.

        - Name: changed_axes
          Type: bitfield
          Indicates which axes have changed.

        - Name: axes
          Type: array
	  The current values of each of the tablet axes starting at
	  WL_TABLET_AXIS_DISTANCE. The length of the array is equal to the
	  number of axes that are reported. Any axes >= WL_TABLET_AXIS_CNT
	  must be ignored.

- button
  Sent whenever a button on the tool is pressed or released.
  Arguments:
        - Name: id
          Type: uint
          The id of the tablet sending this event.

        - Name: button
          Type: uint
          The button whose state has changed

        - Name: state
          Type: uint
          Whether the button was pressed or released

        - Name: time
          Type: uint
          The time of the event with millisecond granularity.

- added
  Sent when a tablet device is added.
  Arguments:
        - Name: id
          Type: uint
          The id of the tablet sending this event.

- removed
  Sent when the tablet device has been removed.
  Arguments:
        - Name: id
          Type: uint
          The id of the tablet sending this event.

How tablet IDs are generated:
Tablet IDs are aggressively recycled, e.g. we always try to get the lowest
possible tablet ID. This means that the client can always assume that the ID
number for a new tablet will never be greater then the number of tablets
currently connected.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140624/e8f988bc/attachment.sig>