Weston touch calibration

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.

destroy()
Unbind

Destroy the binding to the global interface, does not affect any objects already created through this interface.

create_calibrator(surface: object<wl_surface>, device: string, cal: new_id<weston_touch_calibrator>)
Argument
Type
Description
surfaceobject<wl_surface>
the surface to give the role to
devicestring
the touch device to calibrate
calnew_id<weston_touch_calibrator>
a new calibrator object
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.

save(device: string, matrix: array)
Argument
Type
Description
devicestring
the target touch device
matrixarray
the new calibration matrix
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().

touch_device(device: string, head: string)
Argument
Type
Description
devicestring
the touch device identification
headstring
name of the head or display connector
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.

Argument
Value
Description
invalid_surface0
the given wl_surface already has a role
invalid_device1
the given device is not valid
already_exists2
a calibrator has already been created
Global interface errors

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.

destroy()
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.

convert(x: int, y: int, reply: new_id<weston_touch_coordinate>)
Argument
Type
Description
xint
surface-local X coordinate
yint
surface-local Y coordinate
replynew_id<weston_touch_coordinate>
object delivering the result
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.

configure(width: int, height: int)
Argument
Type
Description
widthint
surface width
heightint
surface height
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.

cancel_calibration()
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.

invalid_touch()
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.

down(time: uint, id: int, x: uint, y: uint)
Argument
Type
Description
timeuint
timestamp with millisecond granularity
idint
the unique ID of this touch point
xuint
x coordinate in calibration units
yuint
y coordinate in calibration units
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.

up(time: uint, id: int)
Argument
Type
Description
timeuint
timestamp with millisecond granularity
idint
the unique ID of this touch point
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.

motion(time: uint, id: int, x: uint, y: uint)
Argument
Type
Description
timeuint
timestamp with millisecond granularity
idint
the unique ID of this touch point
xuint
x coordinate in calibration units
yuint
y coordinate in calibration units
Update of touch point coordinates

A touch point has changed coordinates.

For the coordinate units, see weston_touch_calibrator.

frame()
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.

cancel()
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.

Argument
Value
Description
bad_size0
surface size does not match
not_mapped1
requested operation is not possible without mapping the surface
bad_coordinates2
surface-local coordinates are out of bounds
Calibrator object errors

Coordinate conversion reply
result(x: uint, y: uint)
Argument
Type
Description
xuint
x coordinate in calibration units
yuint
y coordinate in calibration units
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.


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.