1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="weston_touch_calibration"> 3 4 <copyright> 5 Copyright 2017-2018 Collabora, Ltd. 6 Copyright 2017-2018 General Electric Company 7 8 Permission is hereby granted, free of charge, to any person obtaining a 9 copy of this software and associated documentation files (the "Software"), 10 to deal in the Software without restriction, including without limitation 11 the rights to use, copy, modify, merge, publish, distribute, sublicense, 12 and/or sell copies of the Software, and to permit persons to whom the 13 Software is furnished to do so, subject to the following conditions: 14 15 The above copyright notice and this permission notice (including the next 16 paragraph) shall be included in all copies or substantial portions of the 17 Software. 18 19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 DEALINGS IN THE SOFTWARE. 26 </copyright> 27 28 <interface name="weston_touch_calibration" version="1"> 29 <description summary="weston touchscreen calibration interface"> 30 This is the global interface for calibrating a touchscreen input 31 coordinate transformation. It is recommended to make this interface 32 privileged. 33 34 This interface can be used by a client to show a calibration pattern and 35 receive uncalibrated touch coordinates, facilitating the computation of 36 a calibration transformation that will align actual touch positions 37 on screen with their expected coordinates. 38 39 Immediately after being bound by a client, the compositor sends the 40 touch_device events. 41 42 The client chooses a touch device from the touch_device events, creates a 43 wl_surface and then a weston_touch_calibrator for the wl_surface and the 44 chosen touch device. The client waits for the compositor to send a 45 configure event before it starts drawing the first calibration pattern. 46 After receiving the configure event, the client will iterate drawing a 47 pattern, getting touch input via weston_touch_calibrator, and converting 48 pixel coordinates to expected touch coordinates with 49 weston_touch_calibrator.convert until it has enough correspondences to 50 compute the calibration transformation or the compositor cancels the 51 calibration. 52 53 Once the client has successfully computed a new calibration, it can use 54 weston_touch_calibration.save request to load the new calibration into 55 the compositor. The compositor may take this new calibration into use and 56 may write it into persistent storage. 57 </description> 58 59 <enum name="error"> 60 <description summary="global interface errors"/> 61 <entry name="invalid_surface" value="0" 62 summary="the given wl_surface already has a role"/> 63 <entry name="invalid_device" value="1" 64 summary="the given device is not valid"/> 65 <entry name="already_exists" value="2" 66 summary="a calibrator has already been created"/> 67 </enum> 68 69 <request name="destroy" type="destructor"> 70 <description summary="unbind"> 71 Destroy the binding to the global interface, does not affect any 72 objects already created through this interface. 73 </description> 74 </request> 75 76 <request name="create_calibrator"> 77 <description summary="give the calibrator role to a surface"> 78 This gives the calibrator role to the surface and ties it with the 79 given touch input device. 80 81 If the surface already has a role, then invalid_surface error is raised. 82 83 If the device string is not one advertised with touch_device event's 84 device argument, then invalid_device error is raised. 85 86 If a weston_touch_calibrator protocol object exists in the compositor 87 already, then already_exists error is raised. This limitation is 88 compositor-wide and not specific to any particular client. 89 </description> 90 <arg name="surface" type="object" interface="wl_surface" 91 summary="the surface to give the role to"/> 92 <arg name="device" type="string" summary="the touch device to calibrate"/> 93 <arg name="cal" type="new_id" interface="weston_touch_calibrator" 94 summary="a new calibrator object"/> 95 </request> 96 97 <request name="save"> 98 <description summary="save calibration for a touch device"> 99 This request asks the compositor to save the calibration data for the 100 given touch input device. The compositor may ignore this request. 101 102 If the device string is not one advertised with touch_device event's 103 device argument, then invalid_device error is raised. 104 105 The array must contain exactly six 'float' (the 32-bit floating 106 point format used by the C language on the system) numbers. For a 3x3 107 calibration matrix in the form 108 @code 109 ( a b c ) 110 ( d e f ) 111 ( 0 0 1 ) 112 @endcode 113 the array must contain the values { a, b, c, d, e, f }. For the 114 definition of the coordinate spaces, see 115 libinput_device_config_calibration_set_matrix(). 116 </description> 117 <arg name="device" type="string" summary="the target touch device"/> 118 <arg name="matrix" type="array" summary="the new calibration matrix"/> 119 </request> 120 121 <event name="touch_device"> 122 <description summary="advertise a touchscreen input device"> 123 When a client binds to weston_touch_calibration, one touch_device event 124 is sent for each touchscreen that is available to be calibrated. This 125 is the only time the event is sent. Touch devices added in the 126 compositor will not generate events for existing 127 weston_touch_calibration objects. 128 129 An event carries the touch device identification and the associated 130 output or head (display connector) name. 131 132 On platforms using udev, the device identification is the udev sys 133 path. It is an absolute path and starts with the sys mount point. 134 </description> 135 <arg name="device" type="string" 136 summary="the touch device identification"/> 137 <arg name="head" type="string" 138 summary="name of the head or display connector"/> 139 </event> 140 </interface> 141 142 <interface name="weston_touch_calibrator" version="1"> 143 <description summary="calibrator surface for a specific touch device"> 144 On creation, this object is tied to a specific touch device. The 145 compositor sends a configure event which the client must obey with the 146 associated wl_surface. 147 148 Once the client has committed content to the surface, the compositor can 149 grab the touch input device, prevent it from emitting normal touch 150 events, show the surface on the correct output, and relay input events 151 from the touch device via this protocol object. 152 153 Touch events from other touch devices than the one tied to this object 154 must generate wrong_touch events on at least touch-down and must not 155 generate normal or calibration touch events. 156 157 At any time, the compositor can choose to cancel the calibration 158 procedure by sending the cancel_calibration event. This should also be 159 used if the touch device disappears or anything else prevents the 160 calibration from continuing on the compositor side. 161 162 If the wl_surface is destroyed, the compositor must cancel the 163 calibration. 164 165 The touch event coordinates and conversion results are delivered in 166 calibration units. The calibration units cover the device coordinate 167 range exactly. Calibration units are in the closed interval [0.0, 1.0] 168 mapped into 32-bit unsigned integers. An integer can be converted into a 169 real value by dividing by 2^32-1. A calibration matrix must be computed 170 from the [0.0, 1.0] real values, but the matrix elements do not need to 171 fall into that range. 172 </description> 173 174 <enum name="error"> 175 <description summary="calibrator object errors"/> 176 <entry name="bad_size" value="0" 177 summary="surface size does not match"/> 178 <entry name="not_mapped" value="1" 179 summary="requested operation is not possible without mapping the surface"/> 180 <entry name="bad_coordinates" value="2" 181 summary="surface-local coordinates are out of bounds"/> 182 </enum> 183 184 <request name="destroy" type="destructor"> 185 <description summary="destroy the calibrator"> 186 This unmaps the surface if it was mapped. The input device grab 187 is dropped, if it was present. The surface loses its role as a 188 calibrator. 189 </description> 190 </request> 191 192 <request name="convert"> 193 <description summary="convert from surface to raw coordinates"> 194 This request asks the compositor to convert the surface-local 195 coordinates into the expected touch input coordinates appropriate for 196 the associated touch device. The intention is that a client uses this 197 request to convert marker positions that the user is supposed to touch 198 during calibration. 199 200 If the compositor has cancelled the calibration, the conversion result 201 shall be zeroes and no errors will be raised. 202 203 The coordinates given as arguments to this request are relative to 204 the associated wl_surface. 205 206 If a client asks for conversion before it has committed valid 207 content to the wl_surface, the not_mapped error is raised. 208 209 If the coordinates x, y are outside of the wl_surface content, the 210 bad_coordinates error is raised. 211 </description> 212 <arg name="x" type="int" summary="surface-local X coordinate"/> 213 <arg name="y" type="int" summary="surface-local Y coordinate"/> 214 <arg name="reply" type="new_id" interface="weston_touch_coordinate" 215 summary="object delivering the result"/> 216 </request> 217 218 <event name="configure"> 219 <description summary="surface size"> 220 This event tells the client what size to make the surface. The client 221 must obey the size exactly on the next commit with a wl_buffer. 222 223 This event shall be sent once as a response to creating a 224 weston_touch_calibrator object. 225 </description> 226 <arg name="width" type="int" summary="surface width"/> 227 <arg name="height" type="int" summary="surface height"/> 228 </event> 229 230 <event name="cancel_calibration"> 231 <description summary="cancel the calibration procedure"> 232 This is sent when the compositor wants to cancel the calibration and 233 drop the touch device grab. The compositor unmaps the surface, if it 234 was mapped. 235 236 The weston_touch_calibrator object will not send any more events. The 237 client should destroy it. 238 </description> 239 </event> 240 241 <event name="invalid_touch"> 242 <description summary="a user touch that cannot be used for calibration"> 243 For whatever reason, a touch event resulting from a user action cannot 244 be used for calibration. The client should show feedback to the user 245 that the touch was rejected. 246 247 Possible causes for this event include the user touching a wrong 248 touchscreen when there are multiple ones present. This is particularly 249 useful when the touchscreens are cloned and there is no other way to 250 identify which screen the user should be touching. 251 252 Another cause could be a touch device that sends coordinates beyond its 253 declared range. If motion takes a touch point outside the range, the 254 compositor should also send 'cancel' event to undo the touch-down. 255 </description> 256 </event> 257 258 <!-- touch events copied from wl_touch interface --> 259 <event name="down"> 260 <description summary="touch down event and beginning of a touch sequence"> 261 A new touch point has appeared on the surface. This touch point is 262 assigned a unique ID. Future events from this touch point reference 263 this ID. The ID ceases to be valid after a touch up event and may be 264 reused in the future. 265 266 For the coordinate units, see weston_touch_calibrator. 267 </description> 268 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> 269 <arg name="id" type="int" summary="the unique ID of this touch point"/> 270 <arg name="x" type="uint" summary="x coordinate in calibration units"/> 271 <arg name="y" type="uint" summary="y coordinate in calibration units"/> 272 </event> 273 274 <event name="up"> 275 <description summary="end of a touch event sequence"> 276 The touch point has disappeared. No further events will be sent for 277 this touch point and the touch point's ID is released and may be 278 reused in a future touch down event. 279 </description> 280 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> 281 <arg name="id" type="int" summary="the unique ID of this touch point"/> 282 </event> 283 284 <event name="motion"> 285 <description summary="update of touch point coordinates"> 286 A touch point has changed coordinates. 287 288 For the coordinate units, see weston_touch_calibrator. 289 </description> 290 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/> 291 <arg name="id" type="int" summary="the unique ID of this touch point"/> 292 <arg name="x" type="uint" summary="x coordinate in calibration units"/> 293 <arg name="y" type="uint" summary="y coordinate in calibration units"/> 294 </event> 295 296 <event name="frame"> 297 <description summary="end of touch frame event"> 298 Indicates the end of a set of events that logically belong together. 299 A client is expected to accumulate the data in all events within the 300 frame before proceeding. 301 302 A wl_touch.frame terminates at least one event but otherwise no 303 guarantee is provided about the set of events within a frame. A client 304 must assume that any state not updated in a frame is unchanged from the 305 previously known state. 306 </description> 307 </event> 308 309 <event name="cancel"> 310 <description summary="touch session cancelled"> 311 Sent if the compositor decides the touch stream is a global 312 gesture. No further events are sent to the clients from that 313 particular gesture. Touch cancellation applies to all touch points 314 currently active on this client's surface. The client is 315 responsible for finalizing the touch points, future touch points on 316 this surface may reuse the touch point ID. 317 </description> 318 </event> 319 <!-- END of touch events copied from wl_touch interface --> 320 321 </interface> 322 323 <interface name="weston_touch_coordinate" version="1"> 324 <description summary="coordinate conversion reply"/> 325 326 <!-- no destructor request defined, no requests possible --> 327 328 <event name="result"> 329 <description summary="coordinates in raw touch space"> 330 This event returns the conversion result from surface coordinates to 331 the expected touch device coordinates. 332 333 For details, see weston_touch_calibrator.convert. For the coordinate 334 units, see weston_touch_calibrator. 335 336 This event destroys the weston_touch_coordinate object. 337 </description> 338 <arg name="x" type="uint" summary="x coordinate in calibration units"/> 339 <arg name="y" type="uint" summary="y coordinate in calibration units"/> 340 </event> 341 </interface> 342</protocol> 343