wl_tablet draft v2

[Lyude]

                           wl_tablet specifications
				  Version 2

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 arithmetic 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.

Changes since the last version:
- The surface argument is now only included in the proximity-in events
- wl_tablet_manager has been added. Events no longer have a separate id
  argument, and instead rely on wl_tablet objects to differentiate each tablet
  from each other. A lot of it was copied from Peter's initial wl_tablet
  proposal, but a few additions have been made; I've added an argument for
  each of the axis events that a tablet supports to the device_added event.
- Axis changes have been split up into a couple different events
- Added a generic frame event. Because of the different kinds of click
  emulations done with tablets, having each event packed into a frame is
  convenient.
- All of the starting values for each axis are provided as normal events in
  the same frame as a proximity_in event. The same goes for the status of each
  button on the tool. This makes the protocol a lot cleaner

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

Interfaces:
- wl_tablet
	Enumerators:
	- wl_tablet_tool_type:
		- pen
		- eraser
		- brush
		- pencil
		- airbrush
		- finger
		- mouse
		- lens
	- wl_tablet_button
		- stylus_1
		- stylus_2
	- 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.
	  A proximity_in event is immediately followed by the following
	  sequence of events in the same frame:
		- motion
		- down (if the tool is touching the tablet's surface at the
		  same time it comes into proximity)
		- a button press event for each button held down on the tool
		  as it comes into proximity
	  	- pressure (if supported by the tablet)
		- distance (if supported by the tablet)
		- tilt (if supported by the tablet)
	  This allows a client to get the starting values for all of the axes,
	  along with the starting coordinates of the tool, and the state of
	  each button on the tool.

	  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: 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.

	- proximity_out
	  Sent whenever the tool leaves the proximity of the tablet or moves
	  out of the client surface. When the tool goes out of proximity,
	  button release events are sent before the initial proximity_out
	  event for each button that was held down before the tablet tool left
	  proximity. Following that, an up event will be sent if the tool was
	  in contact with the surface of the tablet before it went out of
	  proximity. In addition, axis updates always come before a
	  proximity-out event.
	  Arguments:
		- Name: time
		  Type: uint
		  The time of the event with millisecond granularity.

	- down
	  Sent when the tool makes contact with the surface of the tablet.
	  Arguments:
		- Name: time
		  Type: uint
		  The time of the event with millisecond granularity.

	- up
	  Sent when the tool is no longer making contact with the surface of
	  the tablet.
		- Name: time
		  Type: uint
		  The time of the event with millisecond granularity.

	- motion
	  Sent whenever the tool moves.
	  	- Name: x
		  Type: fixed
		  Surface relative x coordinate

		- Name: y
		  Type: fixed
		  Surface relative y coordinate

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

	- distance
	  Sent whenever the distance of the tool from the tablet changes. The
	  value of the axis is normalized from 0 to WL_TABLET_AXIS_MAX.
	  	- Name: distance
		  Type: fixed
		  The new distance of the tool

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

	- pressure
	  Sent whenever the pressure of the tool tablet changes. The value of
	  the axis is normalized from 0 to WL_TABLET_AXIS_MAX.
	  	- Name: pressure
		  Type: fixed
		  The new pressure value for the tool

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

	- tilt
	  Sent whenever the tilt of the tool changes. Each axis value is
	  normalized from WL_TABLET_AXIS_MIN to WL_TABLET_AXIS_MAX.
	  	- Name: tilt_x
		  Type: fixed
		  The X tilt axis of the tool

		- Name: tilt_y
		  Type: fixed
		  The Y tilt axis of the tool

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

	- button
	  Sent whenever a button on the tool is pressed or released.
	  Arguments:
		- 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.

	- frame
	  Indicates the end of a sequence of device events

	- device_removed
	  Sent when this tablet has been removed from the host

Requests:
	- release
	  Releases the wl_tablet object, resulting in the reference count
	  being decremented by one. When the reference count reaches 0, the
	  wl_tablet object will be destroyed.

- wl_tablet_manager
	Enumerators:
	- tablet_type:
		- external
		  The drawing tablet is external and lacks a display, like the
		  Wacom Intuos series.
		- internal
		  The tablet is part of a display that is built into the
		  computer, like the ones built into the Microsoft Surface.
		- display
		  The tablet is part of a display that is connected to the
		  computer externally, like the Wacom Cintiq series.
	- axis_flag
	  Used along with the supported_axes bitfield to indicate which
	  additional axes a tablet can support
		- tilt
		- pressure
		- distance

	Events:
	- device_added
	  Sent when a new tablet has been connected to the host.
	  Arguments:
	  	- Name: id
		  Type: new_id
		  Interface: wl_tablet
		  The new wl_tablet object for the tablet

		- Name: name
		  Type: string
		  The name of the tablet device

		- Name: vid
		  Type: uint
		  The vendor id of the tablet

		- Name: pid
		  Type: uint
		  The product id of the tablet

		- Name: type
		  Type: uint
		  The type of tablet. Uses values from
		  wl_tablet_manager::tablet_type

		- Name: extra_axes
		  Type: uint
		  A bitfield containing information on which extra axes are
		  supported.

Ideas:
- wl_tablet_tool
  This is something that hasn't really been decided on. Basically, the concept
  of this is a lot similar to the concept of how tablet tools are currently
  handled in libinput, we return a struct with all of the tool information
  inside it, instead of just providing a separate tool type variable and
  serial number we provide an entire object, which may or may not be easier
  for the client to work with.
	Enumerators:
	- wl_tablet_tool_type:
		- pen
		- eraser
		- brush
		- pencil
		- airbrush
		- finger
		- mouse
		- lens
	Events:
		- Name: removed
		  Sent when a tool has been removed from the system.

  Using this would require us changing the proximity_in event to provide the
  object ID of the tool currently in use, instead of the serial number and
  type.
  In addition, we would have to add this event to wl_tablet_manager:
	- Name: tool_added
	  Sent when a new tool is being used with one of the tablets connected
	  to the system
	  Arguments:
	  	- Name: id
		  Type: new_id
		  Interface: wl_tablet_tool
		  The ID of the new tool

	  	- Name: type
		  Type: uint
		  Returns the tool's physical type

		- Name: serial
		  Type: uint
		  Returns the tool's serial numbers. On tablets where this is
		  not supported, this will always be 0.