Weston touch calibration

销毁与全局接口的绑定，不影响已通过此接口创建的任何对象。

这将校准器角色赋予表面，并将其与给定的触摸输入设备绑定。

如果表面已有角色，则引发 invalid_surface 错误。

如果设备字符串不是 touch_device 事件的 device 参数所通告的设备之一，则引发 invalid_device 错误。

如果合成器中已存在 weston_touch_calibrator 协议对象，则引发 already_exists 错误。此限制是针对整个合成器的，而非特定客户端。

此请求要求合成器保存给定触摸输入设备的校准数据。合成器可以忽略此请求。

如果设备字符串不是 touch_device 事件的 device 参数所通告的设备之一，则引发 invalid_device 错误。

该数组必须恰好包含六个 'float'（系统上 C 语言使用的 32 位浮点格式）数字。对于以下形式的 3x3 校准矩阵： @code ( a b c ) ( d e f ) ( 0 0 1 ) @endcode 数组必须包含值 { a, b, c, d, e, f }。有关坐标空间的定义，请参阅 libinput_device_config_calibration_set_matrix()。

当客户端绑定到 weston_touch_calibration 时，会为每个可校准的触摸屏发送一个 touch_device 事件。这是唯一发送此事件的时间。合成器中添加的触摸设备不会为现有的 weston_touch_calibration 对象生成事件。

事件携带触摸设备标识和关联的输出或显示连接器名称。

在使用 udev 的平台上，设备标识是 udev sys 路径。它是绝对路径，以 sys 挂载点开头。

如果表面已映射，则取消映射。如果存在输入设备抓取，则释放。表面失去其校准器角色。

此请求要求合成器将表面局部坐标转换为适用于关联触摸设备的预期触摸输入坐标。目的是客户端使用此请求转换在校准期间用户应触摸的标记位置。

如果合成器已取消校准，转换结果应为零，不会引发错误。

作为此请求参数给出的坐标相对于关联的 wl_surface。

如果客户端在向 wl_surface 提交有效内容之前请求转换，则引发 not_mapped 错误。

如果坐标 x, y 在 wl_surface 内容之外，则引发 bad_coordinates 错误。

此事件告诉客户端设置表面的大小。客户端必须在下次使用 wl_buffer 提交时严格遵守该大小。

此事件应在创建 weston_touch_calibrator 对象后作为响应发送一次。

当合成器想要取消校准并释放触摸设备抓取时发送此事件。如果表面已映射，合成器会取消映射。

weston_touch_calibrator 对象将不再发送任何事件。客户端应销毁它。

无论何种原因，用户操作导致的触摸事件无法用于校准。客户端应向用户显示触摸被拒绝的反馈。

此事件的可能原因包括用户在有多个触摸屏时触摸了错误的触摸屏。当触摸屏被克隆且无法以其他方式识别用户应触摸哪个屏幕时，这尤其有用。

另一个原因可能是触摸设备发送了超出其声明范围的坐标。如果移动使触摸点超出范围，合成器还应发送 'cancel' 事件以撤消触摸按下。

表面上出现了新的触摸点。此触摸点被分配一个唯一 ID。来自此触摸点的后续事件引用此 ID。该 ID 在触摸抬起事件后失效，并可能在未来被重用。

有关坐标单位，请参阅 weston_touch_calibrator。

触摸点已消失。不会再发送此触摸点的事件，触摸点的 ID 被释放，并可能在未来的触摸按下事件中被重用。

触摸点已更改坐标。

有关坐标单位，请参阅 weston_touch_calibrator。

表示逻辑上属于同一组的一组事件的结束。客户端应在继续之前累积帧内所有事件中的数据。

wl_touch.frame 至少终止一个事件，但不保证帧内的事件集。客户端必须假设帧中未更新的任何状态与先前已知的状态相同。

如果合成器确定触摸流是全局手势，则发送此事件。不会再向客户端发送该特定手势的事件。触摸取消适用于此客户端表面上当前活动的所有触摸点。客户端负责完成触摸点，此表面上的未来触摸点可以重用触摸点 ID。

此事件返回从表面坐标到预期触摸设备坐标的转换结果。

有关详情，请参阅 weston_touch_calibrator.convert。有关坐标单位，请参阅 weston_touch_calibrator。

此事件销毁 weston_touch_coordinate 对象。