Weston touch calibration

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

A touch point has changed coordinates.

For the coordinate units, see weston_touch_calibrator.

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.

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.

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.