wl_tablet draft v2

Sun Jul 13 12:17:05 PDT 2014

 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.