wl_tablet draft v2
Jason Gerecke
killertofu at gmail.com
Mon Jul 28 09:41:12 PDT 2014
On Wed, Jul 16, 2014 at 5:08 PM, Lyude <thatslyude at gmail.com> wrote:
> On Mon, 2014-07-14 at 13:25 -0700, Jason Gerecke wrote:
>> On Sun, Jul 13, 2014 at 12:17 PM, Lyude <thatslyude at gmail.com> wrote:
>> > 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.
>> >
>> Speaking of overflow, what's Wayland's stance on whether the
>> compositor or client is responsible for dealing with it? I remember
>> Google mentioned that while working on Android's input driver, they
>> noticed some input devices could be "turned up to 11" and report
>> values beyond the kernel-indicated minimum/maximum. They decided to
>> punt the problem to app developers and documented that an app may e.g.
>> see 110% pressure if that's what the hardware reported. The question
>> is mostly academic since the Wacom kernel driver shouldn't be an
>> offender, but I might as well ask :)
> If it comes down to handling overflow, it'll probably be up to the
> client. I'm hoping it shouldn't though. The reason I choose 65535 in the
> first place is because it can more then cover any of the axes (other
> then the X and Y axes, but those aren't normalized anyway so I'm not
> worried about that), and it's difficult to accidentally overflow doing
> general arithmetic with a value of 65535. In most situations, addition,
> subtraction, multiplication, etc. shouldn't overflow. In fact you can
> (almost) square it at least once without overflowing. I'm assuming if
> there's a chance they might, then the client's doing something that the
> developers understand the risk of. It's just a number though, so we can
> always turn it down if we need to.
>
>>
>> > 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.
>>
>> How does this compare to the event sequence sent when a mouse leaves a
>> surface? If, for example, I hold down the left mouse button inside a
>> client and drag outside, does the client see a button-up event?
>> Sending the sequence above seems sane enough, but I wonder if there
>> are cases where it would cause an application to run into trouble.
> Currently, dragging with a mouse makes the mouse continue to report a
> button being held down to the surface it was originally on until it
> reaches the surface we're dragging an item too. Tablet's will most
> likely work the same way.
>>
>> > 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.
>>
>> Is resolution information available anywhere for these axes? If I have
>> one tablet that reports +-64 degrees of tilt and another that reports
>> +-90 degrees, how does a client translate a value of
>> WL_TABLET_AXIS_MAX into an appropriate physical value in each case?
> Right now no. The zero point of the data is kept intact because of the
> normalization values, but my understanding was that we'd be fine
> normalizing the tilt. It's entirely possible I misread an e-mail
> somewhere though. If resolution information is needed I can add that in
> rather easily.
Normalizing the data is fine, but the resolution data needs to be
available somewhere as well. The GTK+ API doesn't require anything
more than the former, but Qt requires that there be some way to turn
the normalized value into degrees. For libinput this could be
something as simple as a "get_axis_resolution" function that returns
the number of radians (or mm, or newtons, or some other physical unit)
that the normalized value +1.0 corresponds to. I suppose Wayland would
let make the value available through the wl_tablet_manager somehow.
Jason
---
Now instead of four in the eights place /
you’ve got three, ‘Cause you added one /
(That is to say, eight) to the two, /
But you can’t take seven from three, /
So you look at the sixty-fours....
>>
>> > - 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.
>>
>> It sounds like this would be in addition to the above definitions, correct?
> Correct.
>
> Cheers,
> Lyude
>>
>> Jason
>> ---
>> Now instead of four in the eights place /
>> you’ve got three, ‘Cause you added one /
>> (That is to say, eight) to the two, /
>> But you can’t take seven from three, /
>> So you look at the sixty-fours....
>>
>>
>> > 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.
>> >
>> > _______________________________________________
>> > wayland-devel mailing list
>> > wayland-devel at lists.freedesktop.org
>> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
More information about the wayland-devel
mailing list