Wayland

sync 请求要求服务器在返回的 wl_callback 对象上发出 'done' 事件。由于请求按顺序处理，事件按顺序传递，这可以用作屏障以确保所有先前的请求和由此产生的事件都已被处理。

此请求返回的对象将在回调触发后由 compositor 销毁，因此客户端不得在该时间点之后尝试使用它。

回调中传递的 callback_data 是未定义的，应被忽略。

此请求创建一个 registry 对象，允许客户端列出并绑定 compositor 提供的全局对象。

应注意，响应 get_registry 请求所消耗的服务器端资源只能在客户端断开连接时释放，而不是在客户端侧代理被销毁时释放。因此，客户端应尽可能少地调用 get_registry 以避免浪费内存。

当发生致命（不可恢复）错误时发送 error 事件。object_id 参数是发生错误的对象，通常是对该对象的请求的响应。code 标识错误并由对象接口定义。因此，每个接口定义自己的错误码集合。message 是错误的简要描述，方便调试。

此事件由对象 ID 管理逻辑内部使用。当客户端删除其创建的对象时，服务器将发送此事件以确认已看到删除请求。当客户端收到此事件时，它将知道可以安全地重用该对象 ID。

这些错误是全局的，可以在响应任何服务器请求时发出。

使用指定的名称作为标识符，将新的客户端创建的对象绑定到服务器。

通知客户端全局对象。

此事件通知客户端具有给定名称的全局对象现在可用，并且它实现了给定接口的给定版本。

通知客户端已移除的全局对象。

此事件通知客户端由 name 标识的全局对象不再可用。如果客户端使用 bind 请求绑定了该全局对象，则客户端现在应销毁该对象。

该对象仍然有效，在客户端销毁它之前，对该对象的请求将被忽略，以避免全局对象消失和客户端向其发送请求之间的竞争。

在相关请求完成时通知客户端。

请求 compositor 创建新的 surface。

请求 compositor 创建新的 region。

此请求销毁 wl_compositor。这对任何其他对象没有影响。

从池中创建 wl_buffer 对象。

buffer 在池中 offset 字节处创建，具有指定的 width 和 height。stride 参数指定从一行开头到下一行开头的字节数。format 是 buffer 的像素格式，必须是通过 wl_shm.format 事件公布的格式之一。

buffer 将保持对创建它的池的引用，因此在从中创建 buffer 后立即销毁池是有效的。

销毁共享内存池。

当从此池创建的所有 buffer 消失时，映射的内存将被释放。

此请求将导致服务器从创建池时传递的文件描述符重新映射池的后备内存，但使用新的大小。此请求只能用于使池变大。

此请求仅更改服务器映射的字节数，不会触及创建时传递的文件描述符对应的文件。客户端有责任确保文件至少与新的池大小一样大。

创建一个新的 wl_shm_pool 对象。

该池可用于创建基于共享内存的 buffer 对象。服务器将对传入的文件描述符 mmap size 字节，作为该池的后备内存。

客户端可以使用此请求告知服务器不再使用该 shm 对象。

通过此接口创建的对象不受影响。

通知客户端可用于 buffer 的有效像素格式。已知格式包括 argb8888 和 xrgb8888。

drm_fourcc.h（或 format 枚举）的扩展不需要增加 wl_shm 版本；因此客户端可能会收到在客户端创建时列表中不存在的格式代码。

这些错误可能在响应 wl_shm 请求时被发出。

描述单个像素的内存布局。

所有渲染器都应支持 argb8888 和 xrgb8888，但其他格式是可选的，可能不被当前使用的特定渲染器支持。

drm 格式代码与 drm_fourcc.h 中定义的宏匹配，argb8888 和 xrgb8888 除外。compositor 实际支持的格式将通过 format 事件报告。更详细的格式描述请参见 drm_fourcc.h。

对于所有 wl_shm 格式，除非在其他协议扩展中另有说明，否则像素值使用预乘 alpha。

销毁 buffer。是否以及如何释放后备存储由 buffer 工厂接口定义。

有关对 surface 的可能副作用，请参阅 wl_surface.attach。

当此 wl_buffer 不再被 compositor 使用时发送。

有关何时可能发送或不发送 release 事件及其后果的更多信息，请参阅 wl_surface.attach 的描述。

如果客户端在将此 wl_buffer 附加到 surface 的同一 wl_surface.commit 中请求的帧回调之前收到 release 事件，则客户端可以立即自由重用该 buffer 及其后备存储，并且不需要第二个 buffer 用于下一个 surface 内容更新。通常当 compositor 维护 wl_surface 内容的副本时（例如作为 GL 纹理），这是可能的。这是对使用 wl_shm 客户端的 GL(ES) compositor 的重要优化。

指示客户端可以接受给定的 MIME 类型， 或传入 NULL 表示不接受。

对于版本 2 或更早的对象， 此请求用于客户端反馈是否可以接收给定的 MIME 类型， 或传入 NULL 表示不接受任何类型； 该反馈不会决定拖放操作是否成功。

对于版本 3 或更新的对象， 此请求决定拖放操作的最终结果。 如果最终结果是没有接受任何 MIME 类型， 拖放操作将被取消， 相应的拖放源将收到 wl_data_source.cancelled。 客户端仍可将此事件与 wl_data_source.action 结合使用以提供反馈。

要传输已提供的数据，客户端发出此请求 并指明它想要接收的 MIME 类型。 传输通过传入的文件描述符进行（通常使用 pipe 系统调用创建）。 源客户端以请求的 MIME 类型格式写入数据， 然后关闭文件描述符。

接收客户端从管道的读取端读取数据直到 EOF， 然后关闭其端，此时传输完成。

此请求可以针对不同的 MIME 类型多次发生， 无论是在 wl_data_device.drop 之前还是之后。 拖放目标客户端可以预取数据或更仔细地检查数据 以决定是否接受。

销毁 data offer。

通知 compositor 拖放目标已成功完成拖放操作。

收到此请求后，compositor 将在拖放源客户端上 发出 wl_data_source.dnd_finished。

在此请求之后执行除 wl_data_offer.destroy 以外的其他请求是客户端错误。 在 wl_data_offer.accept 中设置了 NULL MIME 类型之后 或未通过 wl_data_offer.action 收到任何操作后执行此请求也是错误。

如果为非拖放操作收到 wl_data_offer.finish 请求， 将引发 invalid_finish 协议错误。

设置目标端客户端为此操作支持的操作。 如果 compositor 需要更改所选操作， 此请求可能触发发出 wl_data_source.action 和 wl_data_offer.action 事件。

此请求可以在拖放操作过程中多次调用， 通常是在响应 wl_data_device.enter 或 wl_data_device.motion 事件时。

此请求决定拖放操作的最终结果。 如果最终结果是没有接受任何操作， 拖放源将收到 wl_data_source.cancelled。

dnd_actions 参数必须仅包含 wl_data_device_manager.dnd_actions 枚举中表示的值， preferred_action 参数必须仅包含其中一个设置的值， 否则将导致协议错误。

在管理 "ask" 操作时， 目标拖放客户端可以执行进一步的 wl_data_offer.receive 请求， 并且预计在请求 wl_data_offer.finish 之前执行最后一次 wl_data_offer.set_actions 请求，preferred_action 设为 "ask" 以外的操作 （以及可选的 wl_data_offer.accept）， 以传达用户选择的操作。 如果 preferred_action 不在 wl_data_offer.source_actions 掩码中， 将引发错误。

如果 "ask" 操作被取消（例如用户取消）， 客户端应立即执行 wl_data_offer.destroy。

此请求只能在拖放 offer 上执行，否则将引发协议错误。

在创建 wl_data_offer 对象后立即发送。 每个提供的 MIME 类型对应一个事件。

此事件指示数据源提供的操作。 它将在创建 wl_data_offer 对象后立即发送， 或在源端通过 wl_data_source.set_actions 更改其提供的操作时随时发送。

此事件指示 compositor 在匹配源端/目标端操作后选择的操作。 此处只提供一个操作（或没有）。

在拖放操作期间，此事件可以多次发出， 以响应目标端通过 wl_data_offer.set_actions 进行的操作更改。

在拖放目标上发生 wl_data_device.drop 之后， 此事件将不再发出， 客户端必须遵守最后收到的操作， 或在处理 "ask" 操作时遵守通过 wl_data_offer.set_actions 设置的最后一个首选操作。

Compositor 也可能即时更改所选操作， 主要是在拖放操作期间响应键盘修饰键的变化。

收到的最新操作始终是有效的。 在收到 wl_data_device.drop 之前，选择的操作可能会更改 （例如由于按下键盘修饰键）。 在收到 wl_data_device.drop 时， 拖放目标必须遵守最后收到的操作。

操作更改仍可能在 wl_data_device.drop 之后发生， 特别是在 "ask" 操作中， 拖放目标可能会在之后选择另一个操作。 在此阶段发生的操作更改始终是客户端间协商的结果， compositor 将不再能够引发不同的操作。

对于 "ask" 操作， 预计拖放目标可能会选择不同的操作和/或 MIME 类型， 基于 wl_data_offer.source_actions 并最终由用户选择 （例如弹出一个包含可用选项的菜单）。 最终的 wl_data_offer.set_actions 和 wl_data_offer.accept 请求 必须在调用 wl_data_offer.finish 之前发生。

此请求向通告给目标的 MIME 类型集合中添加一个 MIME 类型。 可以多次调用以提供多种类型。

销毁 data source。

设置源端客户端为此操作支持的操作。 如果 compositor 需要更改所选操作， 此请求可能触发 wl_data_source.action 和 wl_data_offer.action 事件。

dnd_actions 参数必须仅包含 wl_data_device_manager.dnd_actions 枚举中表示的值， 否则将导致协议错误。

此请求必须只执行一次， 并且只能在拖放中使用的源上执行， 因此必须在 wl_data_device.start_drag 之前执行。 尝试将源用于拖放以外的用途将引发协议错误。

当目标接受 pointer_focus 或 motion 事件时发送。 如果目标不接受任何提供的类型，type 为 NULL。

用于拖放期间的反馈。

请求客户端发送数据。 以指定的 MIME 类型通过传入的文件描述符发送数据， 然后关闭它。

此 data source 不再有效。可能有几个原因：

• data source 已被另一个 data source 替换。
• 拖放操作已执行，但拖放目标 未通过 wl_data_source.target 接受任何提供的 MIME 类型。
• 拖放操作已执行，但拖放目标 未选择通过 wl_data_source.action 提供的掩码中的任何操作。
• 拖放操作已执行但未发生在 surface 上。
• compositor 取消了拖放操作（例如 compositor 相关的超时以避免过时的拖放传输）。

客户端应清理并销毁此 data source。

对于版本 2 或更早的对象， 仅当 data source 被另一个 data source 替换时 才会发出 wl_data_source.cancelled。

用户执行了放置操作。 此事件不表示接受， 如果拖放目标不接受任何 MIME 类型， 之后仍可能发出 wl_data_source.cancelled。

但是，如果 compositor 在此事件发生之前取消了拖放操作， 则可能不会收到此事件。

请注意，data_source 将来可能仍会被使用， 不应在此处销毁。

拖放目标已完成与此 data source 的交互， 因此客户端现在可以自由销毁此 data source 并释放所有相关数据。

如果执行操作使用的操作是 "move"， 源现在可以删除已传输的数据。

此事件指示 compositor 在匹配源端/目标端操作后选择的操作。 此处只提供一个操作（或没有）。

在拖放操作期间，此事件可以多次发出， 主要是在响应目标端通过 wl_data_offer.set_actions 进行的更改， 以及 data device 进入/离开 surface 时。

仅在 wl_data_source.dnd_drop_performed 之后 才可能收到此事件， 如果拖放操作以 "ask" 操作结束， 则最终的 wl_data_source.action 事件 将在 wl_data_source.dnd_finished 之前立即发生。

Compositor 也可能即时更改所选操作， 主要是在拖放操作期间响应键盘修饰键的变化。

收到的最新操作始终是有效的。 选择的操作可能会随协商而更改 （例如 "ask" 操作可以变为 "move" 操作）， 因此最终操作的效果必须始终在 wl_data_offer.dnd_finished 中应用。

客户端可以从此点开始触发光标 surface 更改， 以反映当前操作。

此请求要求 compositor 代表客户端启动拖放操作。

source 参数是为最终数据传输提供数据的 data source。 如果 source 为 NULL，enter、leave 和 motion 事件 仅发送给启动拖动的客户端， 客户端应内部处理数据传递。 如果 source 被销毁，拖放会话将被取消。

origin surface 是拖动发起的 surface， 客户端必须有一个与序列号匹配的活动隐式抓取。

icon surface 是一个可选的（可以为 NULL）surface， 提供一个随光标移动的图标。 最初，icon surface 的左上角放置在光标热点， 但后续的 wl_surface.offset 请求可以移动相对位置。 Attach 请求必须像往常一样用 wl_surface.commit 确认。 icon surface 被赋予拖放图标的角色。 如果 icon surface 已经有另一个角色， 将引发协议错误。

对于具有拖放图标角色的 wl_surface，输入区域将被忽略。

给定的源不能在任何进一步的 set_selection 或 start_drag 请求中使用。 尝试重用先前使用的源可能会发送 used_source 错误。

此请求要求 compositor 将选择设置为来自源的数据。

要取消选择，将 source 设置为 NULL。

给定的源不能在任何进一步的 set_selection 或 start_drag 请求中使用。 尝试重用先前使用的源可能会发送 used_source 错误。

此请求销毁 data device。

data_offer 事件引入一个新的 wl_data_offer 对象， 该对象随后将用于 data_device.enter 事件（用于拖放） 或 data_device.selection 事件（用于选择）。 紧随 data_device.data_offer 事件之后， 新的 data_offer 对象将发出 data_offer.offer 事件 以描述它提供的 MIME 类型。

当活动的拖放指针进入客户端拥有的 surface 时发送此事件。 进入时指针的位置由 x 和 y 参数提供， 采用 surface 局部坐标。

当拖放指针离开 surface 且会话结束时发送此事件。 客户端此时必须销毁在 enter 时引入的 wl_data_offer。

当拖放指针在当前聚焦的 surface 内移动时发送此事件。 指针的新位置由 x 和 y 参数提供， 采用 surface 局部坐标。

当拖放操作因隐式抓取被移除而结束时发送此事件。

拖放目标应遵守通过 wl_data_offer.action 收到的最后操作， 如果结果操作是 "copy" 或 "move"， 目标仍可执行 wl_data_offer.receive 请求， 并且预计以 wl_data_offer.finish 请求结束所有传输。

如果结果操作是 "ask"，该操作将不被视为最终操作。 拖放目标应执行最后一次 wl_data_offer.set_actions 请求， 或执行 wl_data_offer.destroy 以取消操作。

selection 事件发出以通知客户端此设备选择的新 wl_data_offer。 data_device.data_offer 和 data_offer.offer 事件 在此事件之前立即发出以引入 data offer 对象。 selection 事件在客户端接收键盘焦点之前 以及客户端拥有键盘焦点时设置新选择时发送给客户端。 data_offer 有效直到收到新的 data_offer 或 NULL 或直到客户端失去键盘焦点。 在同一客户端内切换具有键盘焦点的 surface 不意味着会发送新的选择。 客户端在收到此事件时必须销毁先前的 selection data_offer（如果有）。

创建一个新的 data source。

为给定的 seat 创建一个新的 data device。

此请求销毁 wl_data_device_manager。 这不会影响任何其他对象。

这是拖放操作中可用/首选操作的位掩码。

在 compositor 中，所选操作是匹配源端和目标端提供的操作的结果。 如果没有匹配，将向源端和目标端发送带有 "none" 操作的 "action" 事件。 所有进一步的检查实际上将在（源操作 ∩ 目标操作）上进行。

此外，compositor 也可以根据按下的键修饰符选择不同的操作。 主要工具包中使用的一个常见设计 （以及推荐给 compositor 的行为）是：

• 如果未按下修饰符，将使用第一个匹配（按位顺序）。
• 按住 Shift 选择 "move"（如果在掩码中启用）。
• 按住 Control 选择 "copy"（如果在掩码中启用）。

超出此范围的行为被认为是实现相关的。 Compositor 可以绑定其他修饰符（如 Alt/Meta） 或使用 BTN_LEFT 以外的其他按钮发起的拖动 到特定操作（例如 "ask"）。

为现有 surface 创建 shell surface。这将赋予 wl_surface shell surface 的角色。如果 wl_surface 已有其他角色，则会引发协议错误。

只能将一个 shell surface 与给定 surface 关联。

客户端必须使用 pong 请求响应 ping 事件，否则客户端可能被视为无响应。

开始指针驱动的 surface 移动。

此请求必须在响应按钮按下事件时使用。服务端可能会根据 surface 的状态（例如 fullscreen 或 maximized）忽略移动请求。

开始指针驱动的 surface 调整大小。

此请求必须在响应按钮按下事件时使用。服务端可能会根据 surface 的状态（例如 fullscreen 或 maximized）忽略调整大小请求。

将 surface 映射为 toplevel surface。

toplevel surface 不是 fullscreen、maximized 或 transient 的。

将 surface 映射为相对于已有 surface 的位置。

x 和 y 参数指定 surface 左上角相对于父 surface 左上角的位置，使用 surface 局部坐标。

flags 参数控制 transient 行为的细节。

将 surface 映射为 fullscreen surface。

如果提供了 output 参数，则 surface 将在该 output 上全屏显示。如果客户端未指定 output，compositor 将应用其策略——通常选择 surface 面积最大的 output。

客户端可以指定一种方法来解决 output 大小与 surface 大小之间的冲突——通过 method 参数提供。

framerate 参数仅在 method 设为 "driver" 时使用，用于指示首选帧率。值为 0 表示客户端不关心帧率。帧率以 mHz 为单位指定，即 60000 表示 60Hz。

"scale" 或 "driver" 方法意味着对 surface 进行缩放操作，可以通过直接缩放操作或更改 output 模式来实现。这将覆盖任何类型的 output 缩放，因此将 buffer 大小等于模式大小的 surface 映射时，可以填充整个屏幕而不受 buffer_scale 的影响。

"fill" 方法表示不放大 buffer，但会应用任何 output 缩放。这意味着可能会遇到边界情况：应用程序映射了一个与 output 模式大小相同但 buffer_scale 为 1 的 buffer（从而创建了一个比 output 更大的 surface）。在这种情况下，允许缩小结果以适应屏幕。

compositor 必须使用 configure 事件回复此请求，其中包含 surface 将全屏显示的 output 的尺寸。

将 surface 映射为 popup。

popup surface 是带有附加指针 grab 的 transient surface。

现有的隐式 grab 将被更改为 owner-events 模式，并且 popup grab 将在隐式 grab 结束后继续（即释放鼠标按钮不会导致 popup 被取消映射）。

popup grab 持续到窗口被销毁或在任何其他客户端的窗口中按下鼠标按钮。在客户端自身的任何 surface 中的点击会正常报告，但在其他客户端 surface 中的点击将被丢弃并触发回调。

x 和 y 参数指定 surface 左上角相对于父 surface 左上角的位置，使用 surface 局部坐标。

将 surface 映射为 maximized surface。

如果提供了 output 参数，则 surface 将在该 output 上最大化。如果客户端未指定 output，compositor 将应用其策略——通常选择 surface 面积最大的 output。

compositor 将回复一个 configure 事件，告知预期的新 surface 大小。操作在下一次 buffer 附加到此 surface 时完成。

maximized surface 通常填满其绑定的整个 output，但桌面元素（如面板）除外。这是 maximized shell surface 和 fullscreen shell surface 之间的主要区别。

具体细节取决于 compositor 的实现。

为 surface 设置简短标题。

此字符串可用于在任务栏、窗口列表或 compositor 提供的其他用户界面元素中标识 surface。

字符串必须使用 UTF-8 编码。

为 surface 设置类别。

surface 类别标识该 surface 所属的应用程序的一般类别。一个常见的约定是使用应用程序 .desktop 文件的文件名（如果是非标准位置则使用完整路径）作为类别。

Ping 客户端以检查其是否正在接收事件和发送请求。客户端应以 pong 请求回复。

configure 事件请求客户端调整其 surface 的大小。

大小是一个提示，客户端可以自由忽略它（如果不调整大小）、选择更小的大小（以满足宽高比或以 NxM 像素为步长调整大小）。

edges 参数提供关于 surface 如何被调整大小的提示。客户端可以使用此信息来决定如何将其内容调整为新的大小（例如，滚动区域可能会调整其内容位置以保持可见内容不动）。

客户端可以自由忽略除最后一个 configure 事件之外的所有事件。

width 和 height 参数指定窗口在 surface 局部坐标中的大小。

当 popup grab 被中断时发送 popup_done 事件，即当用户点击了不属于拥有 popup surface 的客户端的 surface 时。

这些值用于指示在调整大小操作中正在拖动 surface 的哪条边缘。服务端可以使用此信息来调整其行为，例如选择适当的光标图像。

这些标志指定 transient surface 预期行为的细节。用于 set_transient 请求。

向 compositor 提示如何处理 surface 尺寸与 output 尺寸之间的冲突。compositor 可以自由忽略此参数。

删除 surface 并使其对象 ID 失效。

设置 buffer 作为此 surface 的内容。

surface 的新大小根据 buffer 大小经过逆 buffer_transform 和逆 buffer_scale 变换后计算得出。这意味着在提交时，提供的 buffer 大小必须是 buffer_scale 的整数倍。如果不是这种情况，将发送 invalid_size 错误。

x 和 y 参数指定新待处理 buffer 左上角相对于当前 buffer 左上角的位置，使用 surface 局部坐标。换句话说，x 和 y 与新的 surface 大小一起定义了 surface 大小变化的方向。不建议将 x 和 y 参数设置为 0 以外的值，应改用单独的 wl_surface.offset 请求。

当绑定的 wl_surface 版本为 5 或更高时，传递任何非零的 x 或 y 值都是协议违规，将导致引发 "invalid_offset" 错误。x 和 y 参数被忽略且不会更改待处理状态。要实现等效语义，请使用 wl_surface.offset。

surface 内容是双缓冲状态，请参见 wl_surface.commit。

初始 surface 内容为空；没有内容。wl_surface.attach 将给定的 wl_buffer 分配为待处理的 wl_buffer。wl_surface.commit 使待处理的 wl_buffer 成为新的 surface 内容，surface 的大小变为从 wl_buffer 计算的大小，如上所述。提交后，在下一次附加之前没有待处理的 buffer。

提交待处理的 wl_buffer 允许 compositor 读取 wl_buffer 中的像素。compositor 可以在 wl_surface.commit 请求之后的任何时间访问像素。当 compositor 不再访问像素时，它将发送 wl_buffer.release 事件。只有在收到 wl_buffer.release 之后，客户端才能重新使用 wl_buffer。已被附加但随后被另一次附加替换而未提交的 wl_buffer 应被视为已提交，且必须在 composit... (line truncated to 2000 chars)

此请求用于描述待处理 buffer 与当前 surface 内容不同的区域，以及 surface 因此需要重新绘制的区域。compositor 会忽略超出 surface 范围的 damage 部分。

Damage 是双缓冲状态，请参见 wl_surface.commit。

damage 矩形以 surface 局部坐标指定，其中 x 和 y 指定 damage 矩形的左上角。

待处理 damage 的初始值为空：无 damage。wl_surface.damage 添加待处理 damage：新的待处理 damage 是旧的待处理 damage 与给定矩形的并集。

wl_surface.commit 将待处理 damage 分配为当前 damage，并清除待处理 damage。服务端将在重新绘制 surface 时清除当前 damage。

注意！新客户端不应使用此请求。相反，可以使用 wl_surface.damage_buffer 发布 damage，它使用 buffer 坐标而不是 surface 坐标。

通过创建 frame 回调，在适合开始绘制新帧时请求通知。这对于限制重绘操作和驱动动画非常有用。

当客户端在 wl_surface 上进行动画时，可以使用 "frame" 请求在适合绘制和提交下一帧动画时获得通知。如果客户端在此之前提交更新，某些更新可能无法显示，客户端因绘制过于频繁而浪费资源。

frame 请求将在下一次 wl_surface.commit 时生效。除非再次请求，否则通知只会为一帧发布。对于 wl_surface，通知按 frame 请求被提交的顺序发布。

服务端必须发送通知，使客户端不会发送过多的更新，同时仍然允许在再次绘制之前等待回复的客户端获得尽可能高的更新速率。服务端应在发送 frame 回调事件后给客户端一些时间来绘制和提交，以使其赶上下一次 output 刷新。

如果 surface 以任何方式不可见（例如 surface 在屏幕外，或完全被其他不透明 surface 遮挡），服务端应避免发出 frame 回调信号。

此请求返回的对象将在回调触发后被 compositor 销毁，因此客户端不得在此之后尝试使用它。

回调中传递的 callback_data 是当前时间（以毫秒为单位），基准未定义。

此请求设置 surface 中包含不透明内容的区域。

不透明区域是 compositor 的优化提示，使其能够优化不透明区域后面内容的重绘。设置不透明区域对于正确行为不是必需的，但将透明内容标记为不透明将导致重绘伪影。

不透明区域以 surface 局部坐标指定。

compositor 会忽略超出 surface 范围的不透明区域部分。

不透明区域是双缓冲状态，请参见 wl_surface.commit。

wl_surface.set_opaque_region 更改待处理的不透明区域。wl_surface.commit 将待处理区域复制到当前区域。除此之外，待处理和当前区域永远不会被更改。

不透明区域的初始值为空。设置待处理不透明区域具有复制语义，wl_region 对象可以立即销毁。NULL wl_region 会导致待处理不透明区域被设为空。

此请求设置 surface 中可以接收指针和触摸事件的区域。

发生在此区域之外的输入事件将尝试服务端 surface 栈中的下一个 surface。compositor 会忽略超出 surface 范围的输入区域部分。

输入区域以 surface 局部坐标指定。

输入区域是双缓冲状态，请参见 wl_surface.commit。

wl_surface.set_input_region 更改待处理的输入区域。wl_surface.commit 将待处理区域复制到当前区域。除此之外，待处理和当前区域永远不会被更改，但光标和图标 surface 是特殊情况，请参见 wl_pointer.set_cursor 和 wl_data_device.start_drag。

输入区域的初始值为无限大。这意味着整个 surface 将接受输入。设置待处理输入区域具有复制语义，wl_region 对象可以立即销毁。NULL wl_region 会导致输入区域被设为无限大。

surface 状态（输入、不透明和 damage 区域、附加的 buffer 等）是双缓冲的。协议请求修改待处理状态，而不是 compositor 正在使用的活动状态。

所有需要提交才能生效的请求都被记录为影响双缓冲状态。

其他接口可以添加更多双缓冲 surface 状态。

commit 请求从待处理状态原子地创建内容更新（CU），即使待处理状态未被修改也是如此。内容更新被放置在每个 surface 队列的末尾，直到变为活动状态。提交后，新的待处理状态如每个相关请求所记录的那样。

CU 要么是非同步内容更新（DCU），要么是同步内容更新（SCU）。如果 surface 在 commit 请求时实际上是同步的，则为 SCU，否则为 DCU。

当 surface 从实际上同步转变为实际上非同步时，其队列中所有不被任何 DCU 可达的 SCU 变为 DCU，并且从队列外部到这些 CU 的依赖边被移除。

有关"实际上同步"和"实际上非同步"的定义，请参见 wl_subsurface。

当 CU 被放入队列时，CU 依赖于其前面的 CU 和每个直接子 surface 队列末尾的 SCU（如果该 SCU 存在且没有其他依赖项）。这可以形成以依赖为边的 CU 有向无环图。

除了 surface 状态外，CU 还可以具有在应用之前必须满足的约束。其他接口可以添加 CU 约束。

所有在其队列前面没有 SCU 的 DCU 都是候选者。如果候选者可达的图没有任何未满足的约束，则整个图必须被原子地应用。

当 CU 被应用时，wl_buffer 在所有其他状态之前应用。这意味着双缓冲状态中的所有坐标都是相对于应用 wl_buffer 的坐标。有关每种状态如何应用的详细信息，请参见每种状态的描述。

如果应用 CU 时有任何约束未满足，则引发约束_not_met 错误。当图中有多个 CU 且至少有一个约束未满足时，引发约束_not_met 错误。

此请求设置客户端已应用于 buffer 内容的变换。transform 参数的可接受值是 wl_output.transform 的值。

compositor 在使用 buffer 内容时应用此变换的逆变换。

Buffer 变换是双缓冲状态，请参见 wl_surface.commit。

新创建的 surface 的 buffer 变换设置为 normal。

wl_surface.set_buffer_transform 更改待处理的 buffer 变换。wl_surface.commit 将待处理的 buffer 变换复制到当前变换。除此之外，待处理和当前值永远不会被更改。

此请求的目的是允许客户端根据 output 变换呈现内容，从而允许 compositor 即使在显示器旋转时也能使用某些优化。使用硬件叠加和为 fullscreen surface 扫描客户端 buffer 是此类优化的示例。这些优化高度依赖于 compositor 的实现，因此应根据具体情况考虑使用此请求。

请注意，如果变换值包括 90 或 270 度旋转，buffer 的宽度将变为 surface 高度，buffer 的高度将变为 surface 宽度。

如果 transform 不是 wl_output.transform 枚举中的值之一，则引发 invalid_transform 协议错误。

此请求设置一个可选的缩放因子，用于 compositor 解释附加到窗口的 buffer 内容。

Buffer 缩放是双缓冲状态，请参见 wl_surface.commit。

新创建的 surface 的 buffer 缩放设置为 1。

wl_surface.set_buffer_scale 更改待处理的 buffer 缩放。wl_surface.commit 将待处理的 buffer 缩放复制到当前缩放。除此之外，待处理和当前值永远不会被更改。

此请求的目的是允许客户端为高分辨率 output 提供更高分辨率的 buffer 数据。建议您选择与 surface 显示所在的 output 缩放相同的 buffer 缩放。这意味着 compositor 在该 output 上渲染 surface 时可以避免缩放。

请注意，如果缩放大于 1，则必须附加一个比所需 surface 大小更大（每个维度大 scale 倍）的 buffer。

如果 scale 不大于 0，则引发 invalid_scale 协议错误。

此请求用于描述待处理 buffer 与当前 surface 内容不同的区域，以及 surface 因此需要重新绘制的区域。compositor 会忽略超出 surface 范围的 damage 部分。

Damage 是双缓冲状态，请参见 wl_surface.commit。

damage 矩形以 buffer 坐标指定，其中 x 和 y 指定 damage 矩形的左上角。

待处理 damage 的初始值为空：无 damage。wl_surface.damage_buffer 添加待处理 damage：新的待处理 damage 是旧的待处理 damage 与给定矩形的并集。

wl_surface.commit 将待处理 damage 分配为当前 damage，并清除待处理 damage。服务端将在重新绘制 surface 时清除当前 damage。

此请求与 wl_surface.damage 只有一个区别——它接受 buffer 坐标中的 damage 而不是 surface 局部坐标。虽然这通常比 surface 坐标更直观，但在使用 wp_viewport 或绘图库（如 EGL）不了解 buffer 缩放和 buffer 变换时尤其可取。

注意：由于 buffer 变换更改和 damage 请求可能在协议流中交错，因此在 wl_surface.commit 之前无法确定 surface 和 buffer damage 之间的实际映射。因此，希望考虑两种 damage 的 compositor 将不得不分别累积来自两个请求的 damage，并且只在收到 wl_surface.commit 后才从一种转换为另一种。

x 和 y 参数指定新待处理 buffer 左上角相对于当前 buffer 左上角的位置，使用 surface 局部坐标。换句话说，x 和 y 与新的 surface 大小一起定义了 surface 大小变化的方向。

wl_surface.offset 的确切语义是特定于角色的。有关更多信息，请参阅特定角色的文档。

surface 位置偏移是双缓冲状态，请参见 wl_surface.commit。

此请求在语义上等同于 wl_surface 版本 5 之前 wl_surface.attach 请求中的 x 和 y 参数，并替代了它们。有关详细信息，请参见 wl_surface.attach。

为客户端通过 wl_surface.attach 附加的 buffer 的释放创建回调。

当 compositor 完成对相关提交的底层存储的使用后，它将释放该 buffer。一旦客户端收到此事件，并且假设关联的 buffer 没有来自其他 wl_surface.commit 请求的待处理释放，客户端就可以安全地重用该 buffer。

释放回调是双缓冲状态，将在 wl_surface.commit 时与待处理 buffer 关联。

wl_callback.done 事件中传递的 callback_data 未使用，始终为零。

在同一内容更新中发送此请求而未附加非空 buffer 是协议错误。compositor 将在这种情况下发送 no_buffer 错误。

当 surface 的创建、移动或调整大小导致其某部分位于 output 的扫描区域内时，会发出此事件。

请注意，surface 可能与零个或多个 output 重叠。

当 surface 的创建、移动或调整大小导致其不再有任何部分位于 output 的扫描区域内时，会发出此事件。

客户端不应使用 surface 所在的 output 数量来进行帧率限制。即使未发送 leave 事件，surface 也可能被隐藏；即使未发送 enter 事件，compositor 也可能期望新的 surface 内容更新。应改用 frame 事件。

此事件指示此 surface 的首选 buffer 缩放。每当 compositor 的偏好发生变化时发送。

在收到此事件之前，此 surface 的首选 buffer 缩放为 1。

支持缩放的客户端应使用此事件来缩放其内容，并使用 wl_surface.set_buffer_scale 来指示它们渲染时使用的缩放。这允许客户端提供更高细节的 buffer。

compositor 应发出大于 0 的缩放值。

此事件指示此 surface 的首选 buffer 变换。每当 compositor 的偏好发生变化时发送。

在收到此事件之前，此 surface 的首选 buffer 变换为 normal。

将此变换应用于 surface buffer 内容并使用 wl_surface.set_buffer_transform 可能使 compositor 更高效地使用 surface buffer。

这些错误可以在响应 wl_surface 请求时发出。

提供的 ID 将被初始化为该 seat 的 wl_pointer 接口。

此请求仅在 seat 具有 pointer 能力或曾经具有 pointer 能力时生效。对从未具有 pointer 能力的 seat 发出此请求属于协议违规。在这种情况下将发送 missing_capability 错误。

提供的 ID 将被初始化为该 seat 的 wl_keyboard 接口。

此请求仅在 seat 具有键盘能力或曾经具有键盘能力时生效。对从未具有键盘能力的 seat 发出此请求属于协议违规。在这种情况下将发送 missing_capability 错误。

提供的 ID 将被初始化为该 seat 的 wl_touch 接口。

此请求仅在 seat 具有 touch 能力或曾经具有 touch 能力时生效。对从未具有 touch 能力的 seat 发出此请求属于协议违规。在这种情况下将发送 missing_capability 错误。

客户端可以使用此请求告知服务器它将不再使用该 seat 对象。

当绑定到 seat global 或当 seat 获得或失去 pointer、keyboard 或 touch 能力时发送此事件。参数是一个能力枚举，包含该 seat 拥有的完整能力集。

当添加 pointer 能力时，客户端可以使用 wl_seat.get_pointer 请求创建 wl_pointer 对象。该对象将持续接收 pointer 事件，直到该能力在未来被移除。

当 pointer 能力被移除时，客户端应使用 wl_pointer.release 请求销毁与该 seat 关联的 wl_pointer 对象。这些对象将不再接收 pointer 事件。

在某些 compositor 中，如果 seat 重新获得 pointer 能力且客户端拥有之前获取的版本 4 或更低版本的 wl_pointer 对象，该对象可能会重新开始发送 pointer 事件。此行为被视为对预期行为的误解，客户端不应依赖此行为。版本 5 及更高版本的 wl_pointer 对象在最近一次通知客户端 pointer 能力已添加的事件之前创建时，不得发送事件。

上述行为同样适用于 wl_keyboard 和 wl_touch 与 keyboard 和 touch 能力的关系。

在多 seat 配置中，seat 名称可用于客户端识别 seat 代表的物理设备。

seat 名称是一个 UTF-8 字符串，其内容没有约定的格式。每个名称在所有 wl_seat global 中是唯一的。名称仅保证在当前 compositor 实例中唯一。

所有客户端使用相同的 seat 名称。因此，名称可以跨进程共享以引用特定的 wl_seat global。

名称事件在绑定到 seat global 之后发送，且应在发布能力之前发送。此事件每个 seat 对象仅发送一次，且名称在 wl_seat global 的生命周期内不会更改。

compositor 可以在 wl_seat global 被销毁并稍后重新创建时重用相同的 seat 名称。

这是该 seat 拥有的能力位掩码；如果设置了某个成员，则表示该 seat 具有此能力。

这些错误可在响应 wl_seat 请求时发出。

设置 pointer surface，即包含 pointer 图像（光标）的 surface。此请求赋予该 surface 光标角色。如果该 surface 已有其他角色，将引发协议错误。

仅当该设备的 pointer 焦点为请求客户端的 surface 或 surface 参数为当前 pointer surface 时，光标才会实际更改。如果之前已通过此请求设置了 surface，则会被替换。如果 surface 为 NULL，pointer 图像将被隐藏。

参数 hotspot_x 和 hotspot_y 定义了 pointer surface 相对于 pointer 位置的位置。其左上角始终位于 (x, y) - (hotspot_x, hotspot_y)，其中 (x, y) 是以 surface 局部坐标表示的 pointer 位置坐标。

对 pointer surface 的 wl_surface.offset 请求会将 hotspot_x 和 hotspot_y 分别减去传递给请求的 x 和 y 参数。偏移量必须照常通过 wl_surface.commit 应用。

热点也可以通过将当前设置的 pointer surface 传递给此请求并使用新的 hotspot_x 和 hotspot_y 值来更新。

对于具有光标角色的 wl_surface，输入区域将被忽略。当用作光标结束时，wl_surface 将被取消映射。

serial 参数必须与发送给客户端的最新 wl_pointer.enter 序列号匹配。否则该请求将被忽略。

客户端可以使用此请求告知服务器它将不再使用该 pointer 对象。

此请求会销毁 pointer 代理对象，因此客户端在使用此请求后不得调用 wl_pointer_destroy()。

通知该 seat 的 pointer 聚焦于某个 surface。

当 seat 的焦点进入 surface 时，pointer 图像未定义，客户端应通过 set_cursor 请求设置适当的 pointer 图像来响应此事件。

通知该 seat 的 pointer 不再聚焦于某个 surface。

离开通知在新焦点的进入通知之前发送。

pointer 位置变更通知。参数 surface_x 和 surface_y 是相对于聚焦 surface 的位置。

鼠标按钮点击和释放通知。

click 的位置由最后的 motion 或 enter 事件给出。time 参数是以毫秒为单位精度的时间戳，基准未定义。

button 是 Linux 内核 linux/input-event-codes.h 头文件中定义的按钮代码，例如 BTN_LEFT。

任何 16 位按钮代码值保留用于内核事件代码列表的未来添加。所有高于 0xFFFF 的其他按钮代码目前未定义，但可能在未来版本的协议中使用。

滚动和其他 axis 通知。

对于滚动事件（垂直和水平滚动 axis），value 参数是指定 axis 上向量的长度，坐标空间与 motion 事件相同，表示沿指定 axis 的相对移动。

对于支持非平行于 axis 移动的设备，将发出多个 axis 事件。

在适用的情况下（例如触控板），服务器可以选择发出滚动事件，其中运动向量等同于 motion 事件向量。

在适用的情况下，客户端可以根据滚动距离变换其内容。

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

所有 wl_pointer.frame 事件之前的 wl_pointer 事件在逻辑上属于同一组。例如，在对角滚动运动中，compositor 将发送可选的 wl_pointer.axis_source 事件、两个 wl_pointer.axis 事件（水平和垂直）以及最后的 wl_pointer.frame 事件。客户端可以使用此信息计算滚动的对角向量。

当同一帧中出现多个 wl_pointer.axis 事件时，运动向量是所有事件的组合运动。当同一帧中出现 wl_pointer.axis 和 wl_pointer.axis_stop 事件时，表示一个 axis 上的运动已停止，但另一个 axis 上的运动仍在继续。当同一帧中出现多个 wl_pointer.axis_stop 事件时，表示这些 axis 在同一时刻停止。

每个逻辑事件组都会发送 wl_pointer.frame 事件，即使该组仅包含单个 wl_pointer 事件。具体来说，客户端可能会收到如下序列：motion、frame、button、frame、axis、frame、axis_stop、frame。

wl_pointer.enter 和 wl_pointer.leave 事件是由 compositor 生成的逻辑事件，而非硬件生成。这些事件也由 wl_pointer.frame 分组。当 pointer 从一个 surface 移动到另一个 surface 时，compositor 应将 wl_pointer.leave 事件分组在同一 wl_pointer.frame 内。但是，客户端不得依赖 wl_pointer.leave 和 wl_pointer.enter 在同一 wl_pointer.frame 内。compositor 特定的策略可能要求将 wl_pointer.leave 和 wl_pointer.enter 事件分散到多个 wl_pointer.frame 组中。

滚动和其他 axis 的源信息。

此事件不会单独出现。它在 wl_pointer.frame 事件之前发送，并携带该帧中所有事件的源信息。

源指定此事件是如何生成的。如果源为 wl_pointer.axis_source.finger，当用户将手指从设备上抬起时将发送 wl_pointer.axis_stop 事件。

如果源为 wl_pointer.axis_source.wheel、wl_pointer.axis_source.wheel_tilt 或 wl_pointer.axis_source.continuous，wl_pointer.axis_stop 事件可能会也可能不会被发送。compositor 是否为这些源发送 axis_stop 事件取决于硬件和具体实现；客户端不得依赖接收这些滚动源的 axis_stop 事件，并应默认将这些滚动源的滚动序列视为未终止。

此事件是可选的。如果特定 axis 事件序列的源未知，则不发送任何事件。每个帧仅允许一个 wl_pointer.axis_source 事件。

wl_pointer.axis_discrete 和 wl_pointer.axis_source 的顺序不保证。

滚动和其他 axis 的停止通知。

对于某些 wl_pointer.axis_source 类型，将发送 wl_pointer.axis_stop 事件以通知客户端 axis 序列已终止。这使客户端能够实现动力滚动。有关何时可能生成此事件的信息，请参阅 wl_pointer.axis_source 文档。

此事件之后具有相同 axis_source 的任何 wl_pointer.axis 事件应被视为新 axis 运动的开始。

时间戳的解释与 wl_pointer.axis 事件中的时间戳相同。时间戳值可能与之前的 wl_pointer.axis 事件相同。

滚动和其他 axis 的离散步进信息。

此事件以离散步进（例如鼠标滚轮的单次拨动）携带 wl_pointer.axis 事件的 axis 值。

此事件自 wl_pointer 版本 8 起已弃用——支持版本 8 或更高版本的客户端不会收到此事件。

此事件不会单独出现，它与 wl_pointer.axis 事件配对，后者在连续尺度上表示此 axis 值。协议保证每个 axis_discrete 事件在同一 wl_pointer.frame 内始终紧随一个具有相同 axis 编号的 axis 事件。请注意，协议允许在 axis_discrete 及其配对的 axis 事件之间发生其他事件，包括其他 axis_discrete 或 axis 事件。每个 wl_pointer.frame 中每个 axis 类型不得超过一个 axis_discrete 事件。

此事件是可选的；连续滚动设备（如触控板上的双指滚动）没有离散步进，不会生成此事件。

离散值携带方向信息。例如，值 -2 表示此 axis 负方向上的两个步进。

axis 编号与关联的 axis 事件中的 axis 编号相同。

wl_pointer.axis_discrete 和 wl_pointer.axis_source 的顺序不保证。

离散高分辨率滚动信息。

此事件携带高分辨率滚轮滚动信息，每 120 的倍数代表一个逻辑滚动步进（一个滚轮卡位）。例如，axis_value120 为 30 表示正方向上逻辑滚动步进的四分之一，value120 为 -240 表示同一硬件事件中负方向上的两个逻辑滚动步进。依赖离散滚动的客户端应在处理事件之前将 value120 累积到 120 的倍数。

value120 不得为零。

此事件在支持 wl_pointer 版本 8 或更高版本的客户端中取代 wl_pointer.axis_discrete 事件。

当同一 wl_pointer.frame 中出现 wl_pointer.axis_source 事件时，axis 源适用于此事件。

wl_pointer.axis_value120 和 wl_pointer.axis_source 的顺序不保证。

导致 axis 运动的实体的相对方向信息。

对于 wl_pointer.axis 事件，wl_pointer.axis_relative_direction 事件指定导致 wl_pointer.axis 事件的实体的运动方向。例如：

• 如果用户在触控板上的手指向下移动并导致 wl_pointer.axis vertical_scroll down 事件，则物理方向为 identical
• 如果用户在触控板上的手指向下移动并导致 wl_pointer.axis vertical_scroll up 滚动事件（自然滚动），则物理方向为 inverted

客户端可以使用此信息调整组件的滚动运动。具体来说，启用自然滚动会导致内容相对于传统滚动改变方向。某些控件（如音量控制滑块）通常应与物理方向匹配，无论自然滚动是否启用。此事件使客户端能够将控件的滚动方向与物理方向匹配。

此事件不会单独出现，它与 wl_pointer.axis 事件配对，后者表示此 axis 值。协议保证每个 axis_relative_direction 事件在同一 wl_pointer.frame 内始终紧随一个具有相同 axis 编号的 axis 事件。请注意，协议允许在 axis_relative_direction 及其配对的 axis 事件之间发生其他事件。

axis 编号与关联的 axis 事件中的 axis 编号相同。

wl_pointer.axis_relative_direction、wl_pointer.axis_discrete 和 wl_pointer.axis_source 的顺序不保证。

描述产生 button 事件的按钮的物理状态。

描述滚动事件的 axis 类型。

描述 axis 事件的源类型。这向客户端指示 axis 事件是如何物理生成的；客户端可以相应地调整用户界面。例如，来自 finger 源的滚动事件可能在具有动力滚动的平滑坐标空间中，而 wheel 源可能以若干行为单位的离散步进。

continuous axis 源是设备在连续坐标空间中生成事件，但使用手指以外的东西。此源的一个示例是基于按钮的滚动，其中设备的垂直运动在按住按钮时转换为滚动事件。

wheel tilt axis 源表示实际设备是滚轮，但滚动事件不是由旋转而是由滚轮的（通常是侧向）倾斜引起的。

这指定了导致 wl_pointer.axis 事件的物理运动方向，相对于 wl_pointer.axis 方向。

此事件向客户端提供一个文件描述符，客户端可以以只读模式进行内存映射以提供键盘映射描述。

从版本 7 开始，fd 必须由接收者以 MAP_PRIVATE 方式映射，因为 MAP_SHARED 可能会失败。

通知该 seat 的键盘焦点位于某个 surface 上。

compositor 必须在此事件之后发送 wl_keyboard.modifiers 事件。

在 wl_keyboard 逻辑状态中，此事件将活动 surface 设置为 surface 参数，并将当前逻辑上按下的键设置为 keys 参数中的键。如果 wl_keyboard 在此事件之前已有活动 surface，compositor 不得发送此事件。

客户端不应使用已按键列表来模拟按键事件。列表中按键的顺序未指定。

通知该 seat 的键盘焦点不再位于某个 surface 上。

离开通知在新焦点的进入通知之前发送。

在 wl_keyboard 逻辑状态中，此事件将所有值重置为默认值。如果 wl_keyboard 的活动 surface 在此事件之前不等于 surface 参数，compositor 不得发送此事件。

按键被按下或释放。time 参数是以毫秒为单位精度的时间戳，基准未定义。

key 是平台相关的键代码，可以通过将其提供给键盘映射（参见 keymap 事件）来解释。

如果此事件导致修饰键更改，则生成的 wl_keyboard.modifiers 事件必须在此事件之后发送。

在 wl_keyboard 逻辑状态中，此事件将 key 添加到当前逻辑上按下的键中（如果 state 参数为 pressed）或从中移除（如果 state 参数为 released）。如果 wl_keyboard 在此事件之前没有活动 surface，compositor 不得发送此事件。如果 state 为 pressed（或 released）且 key 在此事件之前已逻辑上按下（或未逻辑上按下），compositor 不得发送此事件。

自版本 10 起，当接收到 rate 参数为 0 的 wl_keyboard.repeat_info 事件时，compositor 可以发送带有 repeated 键状态的 key 事件。这允许 compositor 承担按键重复的责任。

通知客户端修饰键和/或组状态已更改，应更新其本地状态。

compositor 可以在客户端没有 surface 具有键盘焦点的情况下发送此事件，例如将修饰键信息绑定到 pointer 焦点。如果发送了带有已按下修饰键的修饰键事件而没有先前的 enter 事件，客户端可以假设修饰键状态在收到下一个 wl_keyboard.modifiers 事件之前是有效的。为了重置修饰键状态，compositor 可以发送不带已按下修饰键的 wl_keyboard.modifiers 事件。

在 wl_keyboard 逻辑状态中，此事件更新修饰键和组。

通知客户端键盘的重复速率和延迟。

此事件在 wl_keyboard 对象创建后立即发送，并保证在任何按键事件之前被客户端接收。

rate 或 delay 的负值为非法值。rate 为零将禁用所有重复（无论 delay 的值如何）。

此事件也可以在之后发送新值，因此客户端应在 wl_keyboard 创建后继续监听此事件。

这指定了通过 wl_keyboard.keymap 事件提供给客户端的键盘映射格式。

描述产生 key 事件的按键的物理状态。

自版本 10 起，按键可以处于 repeated 伪状态，其含义与 pressed 相同，但用于在 key 事件中表示重复。

按键只能在进入 pressed 状态之后、进入 released 状态之前进入 repeated 状态。在按键按下期间，此事件可能被多次生成。

一个新的触摸点出现在 surface 上。此触摸点被分配一个唯一 ID。此触摸点的未来事件引用此 ID。该 ID 在 touch up 事件后失效，可以在未来被重用。

触摸点已消失。将不再发送此触摸点的事件，触摸点的 ID 被释放，可以在未来的 touch down 事件中被重用。

触摸点已更改坐标。

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

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

当 compositor 判定触摸流为全局手势时发送。不会再向客户端发送该手势的事件。触摸取消适用于此客户端 surface 上当前活动的所有触摸点。客户端负责终结触摸点，此 surface 上的未来触摸点可以重用触摸点 ID。

cancel 事件之后不需要 frame 事件。

当触摸点更改其形状时发送。

此事件不会单独出现。它在 wl_touch.frame 事件之前发送，并携带该帧中任何先前报告的或新触摸点的新形状信息。

描述触摸点的其他事件（如 wl_touch.down、wl_touch.motion 或 wl_touch.orientation）可能在同一 wl_touch.frame 内发送。客户端应将这些事件视为单个逻辑触摸点更新。wl_touch.shape、wl_touch.orientation 和 wl_touch.motion 的顺序不保证。wl_touch.down 事件保证在该触摸 ID 的第一个 wl_touch.shape 事件之前发生，但两个事件可能在同一 wl_touch.frame 内发生。

触摸点形状通过椭圆的长轴和短轴长度近似。长轴长度描述椭圆的较长直径，短轴长度描述较短直径。长轴和短轴是正交的，均以 surface 局部坐标指定。椭圆的中心始终位于 wl_touch.down 或 wl_touch.move 报告的触摸点位置。

此事件仅在触摸设备支持形状报告时由 compositor 发送。如果客户端未收到此事件，则必须对形状进行合理假设。

当触摸点更改其方向时发送。

此事件不会单独出现。它在 wl_touch.frame 事件之前发送，并携带该帧中任何先前报告的或新触摸点的新形状信息。

描述触摸点的其他事件（如 wl_touch.down、wl_touch.motion 或 wl_touch.shape）可能在同一 wl_touch.frame 内发送。客户端应将这些事件视为单个逻辑触摸点更新。wl_touch.shape、wl_touch.orientation 和 wl_touch.motion 的顺序不保证。wl_touch.down 事件保证在该触摸 ID 的第一个 wl_touch.orientation 事件之前发生，但两个事件可能在同一 wl_touch.frame 内发生。

方向描述触摸点长轴相对于正 surface y 轴的顺时针角度，并归一化到 -180 到 +180 度范围。方向的粒度取决于触摸设备，某些设备仅支持 0 到 90 度之间的二进制旋转值。

此事件仅在触摸设备支持方向报告时由 compositor 发送。

通过此请求，客户端可以告知服务器它将不再使用该 output 对象。

geometry 事件描述 output 的几何属性。该事件在绑定到 output 对象时发送，并在任何属性更改时再次发送。

如果不适用，物理尺寸可以设置为零（例如对于投影仪或虚拟 output）。

从版本 2 开始，geometry 事件之后会跟随 done 事件。

客户端应使用 wl_surface.preferred_buffer_transform 而非此事件提供的 transform 来确定 surface 的首选 buffer transform。

注意：wl_output 仅提供关于 output 位置和标识的部分信息。某些 compositor（例如未实现桌面风格 output 布局或暴露虚拟 output 的 compositor）可能会伪造此信息。客户端应使用 xdg_output.logical_position 而非 x 和 y，使用 name 和 description 而非 make 和 model。

mode 事件描述 output 的可用模式。

该事件在绑定到 output 对象时发送，并且始终会有一个模式，即当前模式。如果 output 更改模式，则会再次发送该事件，表示现在当前的模式。换句话说，当前模式始终是最后收到的带有 current 标志的模式。

非当前模式已被弃用。compositor 可以决定仅公布当前模式而不发送其他模式。客户端不应依赖非当前模式。

模式的大小以 output 设备的物理硬件单位给出。这不一定与全局 compositor 空间中的 output 大小相同。例如，output 可能被缩放（如 wl_output.scale 所述）或被变换（如 wl_output.transform 所述）。希望获取全局 compositor 空间中 output 大小的客户端应改用 xdg_output.logical_size。

如果不适用，垂直刷新率可以设置为零（例如对于虚拟 output）。

从版本 2 开始，mode 事件之后会跟随 done 事件。

客户端不应使用刷新率来调度帧。而应使用 wl_surface.frame 事件或 presentation-time 协议。