protocol/weston-touch-calibration.xml - weston-mtk - Git at Google

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