Treeland window transition
Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.
This extension allows a client to request that the compositor play a window transition for a new window that opens from a specified rectangular area, and, when the window is closed, transitions back to that same rectangular area.
The rectangle is attached to an xdg-activation-v1 token string after the token is committed, so the compositor can associate the rectangle with the originating surface and use it as the animation source when the target window appears.
The client may call set_geometry multiple times to update the geometry, and the compositor uses the latest set geometry for both the open and the close animation.
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 rectangle is disabled, the compositor does not use it as the animation source or target and behaves as if no rectangle were set, but the rectangle object and its association with the activation token remain alive. The client can re-enable the rectangle later by setting a positive size again; the target window uses the latest set geometry whenever the rectangle is enabled.
The full flow is: 1. A, the originating surface, obtains an xdg_activation_token_v1, calls set_surface to identify itself, and calls commit to obtain the token string. 2. A calls get_window_transition_rect on this manager, passing the token string. 3. A calls set_geometry on the resulting rect object to define the 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 passes the token string to B, the target window. 5. B calls xdg_activation_v1.activate with the token and B's surface. 6. The compositor looks up the rectangle associated with the token, converts it to global coordinates using A's position, and plays the open animation from that rectangle to B's geometry. 7. While B is alive, A may call set_geometry again on the rect object to update the transition rectangle. The compositor uses the latest set geometry when B is closed. 8. When B is closed, the compositor plays the close animation from B's geometry back to the rectangle. 9. 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. 10. 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 animation.
Timing and responsibilities:
The client must call xdg_activation_v1.activate on the target surface before that surface is first mapped (i.e. before the wl_surface.commit that causes the compositor to map it). This ensures the compositor has the transition rectangle available when the surface appears.
The terms "must", "must not", "should", and "may" in this document are to be interpreted as described in RFC 2119.
This interface is a manager for creating window transition rectangle objects. A window transition rectangle is attached to an xdg-activation-v1 token string to request that the compositor play a window transition from that rectangle when the token is used to activate a new window, and back to that rectangle when the window is closed.
get_window_transition_rect(rect: new_id<treeland_window_transition_rect_v1>, token: string)
Argument | Type | Description |
|---|---|---|
| rect | new_id<treeland_window_transition_rect_v1> | new window transition rectangle object |
| token | string | the committed activation token string to attach the rectangle to |
Creates a new window transition rectangle object associated with the given activation token string.
treeland_window_transition_rect_v1
Represents a rectangle that the compositor uses as the reference area for window open and close animations. The rectangle coordinates are relative to the surface that was set on the associated activation token via set_surface. The compositor combines the surface's position with the rectangle offset to determine the global animation area.
The object remains live: the client may call set_geometry again to update the rectangle, and the compositor will use the latest set geometry for the close animation when the target window is closed.
When the client destroys this object (or the client disconnects, or the originating surface is destroyed), the compositor falls back to its default close animation for the target window.
destroy()
Destroying the rectangle object removes the animation association. If the target window is still alive, the compositor will use its default close animation when the window is closed.
Argument | Type | Description |
|---|---|---|
| x | int | x offset relative to the originating surface |
| y | int | y offset relative to the originating surface |
| width | int | rectangle width |
| height | int | rectangle height |
Sets the rectangle geometry, taking effect immediately. The x and y coordinates are relative to the surface set on the associated activation token via set_surface. This request may be called multiple times to update the geometry.
A geometry with a positive width and a positive height is guaranteed to be valid. A width and height of both 0 is also guaranteed to be valid and temporarily disables the rectangle. Otherwise might be rejected with the invalid_geometry error.
set_source_surface(surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| surface | object<wl_surface>allow null | the live source surface, or null to clear it |
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.
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.
error { invalid_geometry, invalid_surface }
Argument | Value | Description |
|---|---|---|
| invalid_geometry | 0 | the geometry cannot be handled by the compositor |
| invalid_surface | 1 | the source surface cannot be used as a transition source |
Compositor Support
Copyright
SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT