mainnika
/
weston
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

protocol: add weston_touch_calibration

Browse Source 
This is a Wayland protocol extension to allow the calibration of
touchscreens in Weston.

See: https://phabricator.freedesktop.org/T7868

v2:
- replace "server" with "compositor"
- rephrase error conditions to be simpler
- reword the matrix description in 'save' request
- rephrase when touch_device events are sent
- change device id to DEVPATH with "/sys" prefix
- qualify calibration units better
- replace wrong_touch event with a more generic invalid_touch
- fix error enum and add bad_coordinates
- convert while cancelled will not raise any errors

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
v1 Tested-by: Matt Hoosier <matt.hoosier@gmail.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
dev
Pekka Paalanen 7 years ago
parent c4689ff1d0
commit 999876a8f9
2 changed files with 346 additions and 1 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 5
      Makefile.am
  2. 342
      protocol/weston-touch-calibration.xml

5
Makefile.am
Unescape View File

@ -168,7 +168,9 @@ nodist_libweston_@LIBWESTON_MAJOR@_la_SOURCES = \
protocol/pointer-constraints-unstable-v1-protocol.c \
protocol/pointer-constraints-unstable-v1-server-protocol.h \
protocol/input-timestamps-unstable-v1-protocol.c \
protocol/input-timestamps-unstable-v1-server-protocol.h
protocol/input-timestamps-unstable-v1-server-protocol.h \
protocol/weston-touch-calibration-protocol.c \
protocol/weston-touch-calibration-server-protocol.h
BUILT_SOURCES += $(nodist_libweston_@LIBWESTON_MAJOR@_la_SOURCES)
@ -1545,6 +1547,7 @@ EXTRA_DIST += \
protocol/weston-screenshooter.xml \
protocol/text-cursor-position.xml \
protocol/weston-test.xml \
protocol/weston-touch-calibration.xml \
protocol/ivi-application.xml \
protocol/ivi-hmi-controller.xml

342
protocol/weston-touch-calibration.xml
Unescape View File

@ -0,0 +1,342 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="weston_touch_calibration">
<copyright>
Copyright 2017-2018 Collabora, Ltd.
Copyright 2017-2018 General Electric Company
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
</copyright>
<interface name="weston_touch_calibration" version="1">
<description summary="weston touchscreen calibration interface">
This is the global interface for calibrating a touchscreen input
coordinate transformation. It is recommended to make this interface
privileged.
This interface can be used by a client to show a calibration pattern and
receive uncalibrated touch coordinates, facilitating the computation of
a calibration transformation that will align actual touch positions
on screen with their expected coordinates.
Immediately after being bound by a client, the compositor sends the
touch_device events.
The client chooses a touch device from the touch_device events, creates a
wl_surface and then a weston_touch_calibrator for the wl_surface and the
chosen touch device. The client waits for the compositor to send a
configure event before it starts drawing the first calibration pattern.
After receiving the configure event, the client will iterate drawing a
pattern, getting touch input via weston_touch_calibrator, and converting
pixel coordinates to expected touch coordinates with
weston_touch_calibrator.convert until it has enough correspondences to
compute the calibration transformation or the compositor cancels the
calibration.
Once the client has successfully computed a new calibration, it can use
weston_touch_calibration.save request to load the new calibration into
the compositor. The compositor may take this new calibration into use and
may write it into persistent storage.
</description>
<enum name="error">
<description summary="global interface errors"/>
<entry name="invalid_surface" value="0"
summary="the given wl_surface already has a role"/>
<entry name="invalid_device" value="1"
summary="the given device is not valid"/>
<entry name="already_exists" value="2"
summary="a calibrator has already been created"/>
</enum>
<request name="destroy" type="destructor">
<description summary="unbind">
Destroy the binding to the global interface, does not affect any
objects already created through this interface.
</description>
</request>
<request name="create_calibrator">
<description summary="give the calibrator role to a surface">
This gives the calibrator role to the surface and ties it with the
given touch input device.
If the surface already has a role, then invalid_surface error is raised.
If the device string is not one advertised with touch_device event's
device argument, then invalid_device error is raised.
If a weston_touch_calibrator protocol object exists in the compositor
already, then already_exists error is raised. This limitation is
compositor-wide and not specific to any particular client.
</description>
<arg name="surface" type="object" interface="wl_surface"
summary="the surface to give the role to"/>
<arg name="device" type="string" summary="the touch device to calibrate"/>
<arg name="cal" type="new_id" interface="weston_touch_calibrator"
summary="a new calibrator object"/>
</request>
<request name="save">
<description summary="save calibration for a touch device">
This request asks the compositor to save the calibration data for the
given touch input device. The compositor may ignore this request.
If the device string is not one advertised with touch_device event's
device argument, then invalid_device error is raised.
The array must contain exactly six 'float' (the 32-bit floating
point format used by the C language on the system) numbers. For a 3x3
calibration matrix in the form
@code
( a b c )
( d e f )
( 0 0 1 )
@endcode
the array must contain the values { a, b, c, d, e, f }. For the
definition of the coordinate spaces, see
libinput_device_config_calibration_set_matrix().
</description>
<arg name="device" type="string" summary="the target touch device"/>
<arg name="matrix" type="array" summary="the new calibration matrix"/>
</request>
<event name="touch_device">
<description summary="advertise a touchscreen input device">
When a client binds to weston_touch_calibration, one touch_device event
is sent for each touchscreen that is available to be calibrated. This
is the only time the event is sent. Touch devices added in the
compositor will not generate events for existing
weston_touch_calibration objects.
An event carries the touch device identification and the associated
output or head (display connector) name.
On platforms using udev, the device identification is the udev sys
path. It is an absolute path and starts with the sys mount point.
</description>
<arg name="device" type="string"
summary="the touch device identification"/>
<arg name="head" type="string"
summary="name of the head or display connector"/>
</event>
</interface>
<interface name="weston_touch_calibrator" version="1">
<description summary="calibrator surface for a specific touch device">
On creation, this object is tied to a specific touch device. The
compositor sends a configure event which the client must obey with the
associated wl_surface.
Once the client has committed content to the surface, the compositor can
grab the touch input device, prevent it from emitting normal touch
events, show the surface on the correct output, and relay input events
from the touch device via this protocol object.
Touch events from other touch devices than the one tied to this object
must generate wrong_touch events on at least touch-down and must not
generate normal or calibration touch events.
At any time, the compositor can choose to cancel the calibration
procedure by sending the cancel_calibration event. This should also be
used if the touch device disappears or anything else prevents the
calibration from continuing on the compositor side.
If the wl_surface is destroyed, the compositor must cancel the
calibration.
The touch event coordinates and conversion results are delivered in
calibration units. The calibration units cover the device coordinate
range exactly. Calibration units are in the closed interval [0.0, 1.0]
mapped into 32-bit unsigned integers. An integer can be converted into a
real value by dividing by 2^32-1. A calibration matrix must be computed
from the [0.0, 1.0] real values, but the matrix elements do not need to
fall into that range.
</description>
<enum name="error">
<description summary="calibrator object errors"/>
<entry name="bad_size" value="0"
summary="surface size does not match"/>
<entry name="not_mapped" value="1"
summary="requested operation is not possible without mapping the surface"/>
<entry name="bad_coordinates" value="2"
summary="surface-local coordinates are out of bounds"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the calibrator">
This unmaps the surface if it was mapped. The input device grab
is dropped, if it was present. The surface loses its role as a
calibrator.
</description>
</request>
<request name="convert">
<description summary="convert from surface to raw coordinates">
This request asks the compositor to convert the surface-local
coordinates into the expected touch input coordinates appropriate for
the associated touch device. The intention is that a client uses this
request to convert marker positions that the user is supposed to touch
during calibration.
If the compositor has cancelled the calibration, the conversion result
shall be zeroes and no errors will be raised.
The coordinates given as arguments to this request are relative to
the associated wl_surface.
If a client asks for conversion before it has committed valid
content to the wl_surface, the not_mapped error is raised.
If the coordinates x, y are outside of the wl_surface content, the
bad_coordinates error is raised.
</description>
<arg name="x" type="int" summary="surface-local X coordinate"/>
<arg name="y" type="int" summary="surface-local Y coordinate"/>
<arg name="reply" type="new_id" interface="weston_touch_coordinate"
summary="object delivering the result"/>
</request>
<event name="configure">
<description summary="surface size">
This event tells the client what size to make the surface. The client
must obey the size exactly on the next commit with a wl_buffer.
This event shall be sent once as a response to creating a
weston_touch_calibrator object.
</description>
<arg name="width" type="int" summary="surface width"/>
<arg name="height" type="int" summary="surface height"/>
</event>
<event name="cancel_calibration">
<description summary="cancel the calibration procedure">
This is sent when the compositor wants to cancel the calibration and
drop the touch device grab. The compositor unmaps the surface, if it
was mapped.
The weston_touch_calibrator object will not send any more events. The
client should destroy it.
</description>
</event>
<event name="invalid_touch">
<description summary="a user touch that cannot be used for calibration">
For whatever reason, a touch event resulting from a user action cannot
be used for calibration. The client should show feedback to the user
that the touch was rejected.
Possible causes for this event include the user touching a wrong
touchscreen when there are multiple ones present. This is particularly
useful when the touchscreens are cloned and there is no other way to
identify which screen the user should be touching.
Another cause could be a touch device that sends coordinates beyond its
declared range. If motion takes a touch point outside the range, the
compositor should also send 'cancel' event to undo the touch-down.
</description>
</event>
<!-- touch events copied from wl_touch interface -->
<event name="down">
<description summary="touch down event and beginning of a touch sequence">
A new touch point has appeared on the surface. This touch point is
assigned a unique ID. Future events from this touch point reference
this ID. The ID ceases to be valid after a touch up event and may be
reused in the future.
For the coordinate units, see weston_touch_calibrator.
</description>
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
<arg name="id" type="int" summary="the unique ID of this touch point"/>
<arg name="x" type="uint" summary="x coordinate in calibration units"/>
<arg name="y" type="uint" summary="y coordinate in calibration units"/>
</event>
<event name="up">
<description summary="end of a touch event sequence">
The touch point has disappeared. No further events will be sent for
this touch point and the touch point's ID is released and may be
reused in a future touch down event.
</description>
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
<arg name="id" type="int" summary="the unique ID of this touch point"/>
</event>
<event name="motion">
<description summary="update of touch point coordinates">
A touch point has changed coordinates.
For the coordinate units, see weston_touch_calibrator.
</description>
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
<arg name="id" type="int" summary="the unique ID of this touch point"/>
<arg name="x" type="uint" summary="x coordinate in calibration units"/>
<arg name="y" type="uint" summary="y coordinate in calibration units"/>
</event>
<event name="frame">
<description summary="end of touch frame event">
Indicates the end of a set of events that logically belong together.
A client is expected to accumulate the data in all events within the
frame before proceeding.
A wl_touch.frame terminates at least one event but otherwise no
guarantee is provided about the set of events within a frame. A client
must assume that any state not updated in a frame is unchanged from the
previously known state.
</description>
</event>
<event name="cancel">
<description summary="touch session cancelled">
Sent if the compositor decides the touch stream is a global
gesture. No further events are sent to the clients from that
particular gesture. Touch cancellation applies to all touch points
currently active on this client's surface. The client is
responsible for finalizing the touch points, future touch points on
this surface may reuse the touch point ID.
</description>
</event>
<!-- END of touch events copied from wl_touch interface -->
</interface>
<interface name="weston_touch_coordinate" version="1">
<description summary="coordinate conversion reply"/>
<!-- no destructor request defined, no requests possible -->
<event name="result">
<description summary="coordinates in raw touch space">
This event returns the conversion result from surface coordinates to
the expected touch device coordinates.
For details, see weston_touch_calibrator.convert. For the coordinate
units, see weston_touch_calibrator.
This event destroys the weston_touch_coordinate object.
</description>
<arg name="x" type="uint" summary="x coordinate in calibration units"/>
<arg name="y" type="uint" summary="y coordinate in calibration units"/>
</event>
</interface>
</protocol>
Write Preview
Loading…
Cancel
Save