path: root/protocol/weston-touch-calibration.xml

<?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>