From 64e8db4f02ebe99879e56ac5ef783d2203ef8c8c Mon Sep 17 00:00:00 2001 From: guolin Date: Fri, 18 Sep 2026 09:57:37 +0800 Subject: [PATCH] feat(window-transition): use a live source surface for the transition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Replace set_source_buffer with set_source_surface taking a wl_surface 2. Render the source surface live instead of sampling a one-off buffer 3. Rename the invalid_buffer error to invalid_surface 4. Clarify the closed event and the source surface lifetime contract 1. 将 set_source_buffer 替换为接收 wl_surface 的 set_source_surface 2. 源 surface 在转场中实时渲染，不再一次性采样 buffer 3. 将 invalid_buffer 错误更名为 invalid_surface 4. 澄清 closed 事件语义与源 surface 生命周期约定 PMS: TASK-395857 Log: 转场源改用实时 surface，替代一次性 buffer Influence: 1. 用 wayland-scanner 重建协议头文件并确认无警告 2. 将调用 set_source_buffer 的合成器/客户端改为 set_source_surface 3. 验证源 surface 在打开/关闭转场中实时渲染且不重复显示 --- public/README.md | 2 +- public/README.zh_CN.md | 2 +- ...treeland-window-transition-unstable-v1.xml | 88 ++++++++++--------- 3 files changed, 49 insertions(+), 43 deletions(-) diff --git a/public/README.md b/public/README.md index 7801488..a0d675d 100644 --- a/public/README.md +++ b/public/README.md @@ -4,7 +4,7 @@ For general application developers. Installed via `TREELAND_PROTOCOL_XML_FILES`. | File | Protocol | Interfaces | Purpose | |------|----------|-----------|---------| -| `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | Window open/close transition relative to a rectangle, with optional source image | +| `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | Window open/close transition relative to a rectangle, with an optional live source surface | | `treeland-snap-target-unstable-v1.xml` | `treeland_snap_target_unstable_v1` | `treeland_snap_target_v1` | Compositor-side snap region hints; an optional pidfd event for window targets can be enabled via the `event_type.pidfd` bit of `start` | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | Query and observe user-level appearance settings: cursor theme/size, fonts, icon theme, accent color, window opacity, color scheme, titlebar height, corner radius | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | Per-window server-side decoration (SSD) customization by applications: corner radius, shadow, border, titlebar visibility; requires xdg-decoration SSD | diff --git a/public/README.zh_CN.md b/public/README.zh_CN.md index 2e4c976..dfc7e3f 100644 --- a/public/README.zh_CN.md +++ b/public/README.zh_CN.md @@ -4,7 +4,7 @@ | 文件 | 协议 | 接口 | 用途 | |------|----------|-----------|---------| -| `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | 相对某个矩形的窗口打开/关闭转场，可附带源图像 | +| `treeland-window-transition-unstable-v1.xml` | `treeland_window_transition_unstable_v1` | `treeland_window_transition_manager_v1`, `treeland_window_transition_rect_v1` | 相对某个矩形的窗口打开/关闭转场，可附带实时源 surface | | `treeland-snap-target-unstable-v1.xml` | `treeland_snap_target_unstable_v1` | `treeland_snap_target_v1` | 合成器侧吸附区域提示；窗口目标的 pidfd 事件为可选项，需在 `start` 中置 `event_type.pidfd` 位启用 | | `treeland-appearance-unstable-v1.xml` | `treeland_appearance_unstable_v1` | `treeland_appearance_v1` | 查询与订阅用户级外观设置：光标主题/大小、字体、图标主题、强调色、窗口不透明度、配色方案、标题栏高度、圆角 | | `treeland-decoration-unstable-v1.xml` | `treeland_decoration_unstable_v1` | `treeland_decoration_manager_v1`, `treeland_decoration_context_v1` | 逐窗口服务端装饰（SSD）定制：圆角、阴影、边框、标题栏可见性；需先经 xdg-decoration 申请 SSD | diff --git a/public/treeland-window-transition-unstable-v1.xml b/public/treeland-window-transition-unstable-v1.xml index a6c65f3..6342a74 100644 --- a/public/treeland-window-transition-unstable-v1.xml +++ b/public/treeland-window-transition-unstable-v1.xml @@ -29,10 +29,11 @@ geometry, and the compositor uses the latest set geometry for both the open and the close animation. - Optionally, the client may attach an image (a wl_buffer) to the - rectangle via set_source_buffer. When an image is set, the compositor - uses it as the source image for the transition instead of an empty - rectangle. + Optionally, the client may attach a live source surface to the + rectangle via set_source_surface. When a source surface is set, the + compositor uses its content as the source of the transition instead + of an empty rectangle, and renders it live while the transition is + playing. The client may temporarily disable the rectangle by setting a geometry of 0x0 size (zero width and zero height). While the @@ -50,7 +51,9 @@ 2. A calls get_window_transition_rect on this manager, passing the token. 3. A calls set_geometry on the resulting rect object to define the - transition rectangle (relative to A). + transition rectangle (relative to A), and optionally calls + set_source_surface on the rect object to attach a live source + surface for the transition. 4. A calls commit on the xdg_activation_token_v1 to obtain the token string. 5. A passes the token string to B, the target window. @@ -63,13 +66,12 @@ the latest set geometry when B is closed. 9. When B is closed, the compositor plays the close animation from B's geometry back to the rectangle. - 10. Once the compositor stops using the rectangle (e.g. because B - is destroyed), it sends the closed event on the rect object. - A destroys the rect object after receiving this event. + 10. Once the compositor stops using the rectangle, it sends the + closed event on the rect object. A destroys the rect object + after receiving this event. 11. If A destroys the rect object before B is closed (or if A's client disconnects, or if A is destroyed), the compositor falls - back to its default close animation and does not send the closed - event. + back to its default animation. Timing and responsibilities: @@ -132,8 +134,8 @@ - + @@ -164,40 +166,44 @@ - - - Sets the source image used by the transition for this - rectangle. This request takes effect immediately. - - The compositor samples the buffer content when this request - is applied, then sends wl_buffer.release, after which the - client may reuse or destroy the buffer. The client must keep - the buffer alive and its content valid until that release is - received. - - Passing null clears the source image. The buffer may be - replaced, including with null, by a later call. - - A buffer that cannot be imported by the compositor raises - the invalid_buffer error. + + + Sets the surface whose content the compositor uses as the + source of the transition for this rectangle. The surface is + rendered live while the transition is playing; its content is + scaled into the rectangle set via set_geometry. + + The surface must not already be in use for any other purpose, + and the compositor reserves it for use as a transition source + only: it is not displayed anywhere else, and the client must not + use it for any other purpose. A surface that has previously been + used as a transition source may be used again. + + The client should keep the surface alive, and keep valid + content on it, while it is set as the source. + + Passing null clears the source surface. The client may + replace the source by passing another surface; a previously + set surface is no longer used as a source. Destroying the + rect object or the surface itself also ends its use as a + source. + + A surface that cannot be used as a source, for example one + that is already in use for another purpose, or that belongs to + another client, raises the invalid_surface error. - + - Sent once the compositor no longer references this rectangle, - e.g. because the target window has been destroyed. From this - point the object is useless to the client and should be - destroyed. - - This is a notification only. This event is sent at most once - per rectangle object, and only if the rectangle object was - still alive when the compositor stopped using it. If the client - destroys the rectangle (or disconnects) before then, this event - is not sent. No further events are delivered on this object - after closed. + Sent when the compositor is done with this rectangle. The + client must destroy the rectangle object after receiving this + event. + + This is a notification only. No further events are delivered + on this object after closed.