diff --git a/CMakeLists.txt b/CMakeLists.txt index 60cd7b7..bcb026b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,7 +11,7 @@ include(GNUInstallDirs) add_subdirectory(cmake) set(XML - xml/treeland-capture-unstable-v1.xml + xml/treeland-capture-snap-unstable-v1.xml xml/treeland-output-manager-v1.xml xml/treeland-virtual-output-manager-v1.xml xml/treeland-dde-shell-v1.xml diff --git a/xml/treeland-capture-snap-unstable-v1.xml b/xml/treeland-capture-snap-unstable-v1.xml new file mode 100644 index 0000000..17a98a3 --- /dev/null +++ b/xml/treeland-capture-snap-unstable-v1.xml @@ -0,0 +1,165 @@ + + + + + + This protocol allows a client to request snap region hints from the + compositor. While snapping is active, the compositor tracks the cursor + position and notifies the client of the rectangle the cursor should + "snap" to (e.g., a window boundary or a full output). The client uses + these hints to draw its own snap preview UI. + + Snap targets are computed against the window layout captured when the + snap session starts: the compositor records the position and stacking + order of every window at that moment and keeps them unchanged for the + whole session. Windows that move, are mapped or unmapped, or change + stacking order after start are not reflected in the snap targets. + + A client may identify an overlay surface by setting the xdg-toplevel-tag + "org.deepin.treeland.capture-mask" on that toplevel. When the compositor + detects this tag, it applies the following configuration to the surface: + + 1. Raises the surface above normal windows and their popup panels. + 2. Moves the surface to the top-left corner of the rectangle that + encloses the entire canvas (i.e., the bounding box of all outputs' + geometries). + 3. Removes all decorations (title bar, corner radius, window shadow). + 4. Disables window open/close animations. + 5. Excludes the surface from the multitask view and window switcher. + 6. Disables automatic positioning by the compositor's layout engine. + + Such a surface does not affect the snapping protocol; snapping + behaves the same whether or not the surface exists. Surfaces + carrying the capture-mask tag are excluded from snapping, i.e., they + are never reported as snap targets. + + 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 interface is a global singleton for requesting snap region hints + from the compositor. Each client binds at most one instance of this + global. The compositor tracks the cursor position and notifies the + client of the rectangle the cursor should snap to. + + The snap object is created in an idle state. The client starts + snapping by calling start, which causes the compositor to capture the + current window positions and stacking order and begin tracking the + cursor position, providing snap region hints based on the captured + layout. + + While snapping is active, the compositor sends a snap_region event + each time the snap target changes (i.e., when the cursor moves to a + different window or output). The client can use these events to update + its snap preview UI. + + When the client is done (e.g., the user has clicked or dragged to + confirm a selection in the client's UI), the client calls stop to + stop snap notifications. A stopped snap object may be restarted by + calling start again. + + Only one snap session may be active across all clients at any time. + If another client's snap session is active, start fails with the + snap_busy reason. + + + + + + + + + + Destroy the treeland_capture_snap_v1 object. If snapping is in + progress, the compositor automatically stops it (stops cursor + tracking). No further events are emitted on this object. + + + + + + Request the compositor to capture the current window positions and + stacking order and begin tracking the cursor, sending snap region + hints based on the captured layout. + + This request may be called again after stop to restart snapping; a + fresh capture of the window layout is taken on every start. start + must not be called on an already active snap object; the compositor + ignores such a request. + + A snap_region event is not guaranteed to be sent immediately after + start. The compositor sends snap_region events when the snap target + changes. + + If snapping cannot be started because another client's snap session + is already active, the compositor sends a failed event with the + snap_busy reason instead. + + + + + + Signal that the client is done with snapping. The compositor stops + tracking the cursor and stops sending snap_region events. + + This request is a no-op if snapping is not in progress (e.g., if + failed was already emitted or stop was already called). + + The client should call destroy afterwards to free the snap object. + + + + + + Notifies the client of the current snap target rectangle. Snap + targets are determined from the window layout captured at start and + are not updated while the session is active: windows that move, are + mapped or unmapped, or change stacking order after start are not + reflected. This event is sent each time the snap target changes due + to cursor movement. The compositor may also send this event after + start to report the current target. + + The region is in global logical coordinates (i.e., the + xdg_output logical coordinate space). The client is responsible for + any coordinate transformation needed for its UI. + + If width and height are both zero, there is no current snap target + (e.g., the cursor is over empty desktop space). The client should + hide its snap preview in this case. + + + + + + + + + + Snapping could not be started. The compositor + will not send any more snap_region events. The client should call + destroy to free the snap object. + + This event is sent when another client's snap session is already + active (reason snap_busy). + + + + + diff --git a/xml/treeland-capture-unstable-v1.xml b/xml/treeland-capture-unstable-v1.xml deleted file mode 100644 index ba7ac8a..0000000 --- a/xml/treeland-capture-unstable-v1.xml +++ /dev/null @@ -1,247 +0,0 @@ - - - - - This protocol allows authorized application to capture output contents or window - contents(useful for window streaming). - - 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. - - - - - - - - - - - - - - - - - Unreferences the frame. This request must be called as soon as it's no longer valid. - - - - - - Start session and keeps sending frame. - - - - - - This is the ACK to the current "ready" event. The next "frame" event will be sent only when current - "ready" event is acknowledged. The timestamp should be the same as the one sent in "ready" event. - If the frame has the "transient" flag, all objects sent before become invalid after this event. - - - - - - - - - Main event supplying the client with information about the frame. If the capture didn't fail, this event is always - emitted first before any other events. - When mask is provided, x and y should be offset relative to mask surface origin. Otherwise offset_x and offset_y should always - be zero. - - - - - - - - - - - - - - - - - - - - - - - - - - - This event is sent as soon as the frame is presented, indicating it is available for reading. This event - includes the time at which presentation happened at. - - - - - - - - - If the capture failed or if the frame is no longer valid after the "frame" event has been emitted, this - event will be used to inform the client to scrap the frame. - - - - - - - - - - - - - - - Destroys the context. This request can be sent at any time by the client. - - - - - - Copy capture contents to provided buffer - - - - - - - Inform client to prepare buffer. - - - - - - - - - - Inform client that all buffer formats supported are emitted. - - - - - - Provides flags about the frame. This event is sent once before the - "ready" event. - - - - - - - Inform that buffer is ready for reading - - - - - - Inform that frame copy fails. - - - - - - - - - - - - - - - - - - - - - - - - - Destroys the context. This request can be sent at any time by the client. - - - - - - Selector is provided by compositor. Client can provide source hint to hint compositor - to provide certain kinds of source. - - - - - - - - - - This event can be called just once. A second call might result in a protocol error cause - we just provide transient - - - - - - - Often used by a screen recorder. - - - - - - - This event supplies the client some information about the capture source, including - the capture region relative to mask and source type. - - - - - - - - - - - There could a lot of reasons but the most common one is that selector is busy - - - - - - - - - - - Destroy the treeland_capture_manager_v1 object. - - - - - - - - - - -