capture snap

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

xml/treeland-capture-snap-unstable-v1.xml

@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="treeland_capture_snap_unstable_v1">
+  <copyright><![CDATA[
+  SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd.
+  SPDX-License-Identifier: MIT
+  ]]></copyright>
+
+  <description summary="compositor-side snap region hint for screenshot/recording">
+    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.
+  </description>
+
+  <interface name="treeland_capture_snap_v1" version="1">
+    <description summary="snap region hint session">
+      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.
+    </description>
+
+    <enum name="failure_reason">
+      <description summary="reasons why snapping failed"/>
+      <entry name="snap_busy" value="0"
+             summary="another client has an active snap session"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the snap object">
+        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.
+      </description>
+    </request>
+
+    <request name="start">
+      <description summary="begin snap region hints">
+        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.
+      </description>
+    </request>
+
+    <request name="stop">
+      <description summary="stop snap region hints">
+        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.
+      </description>
+    </request>
+
+    <event name="snap_region">
+      <description summary="current snap target region">
+        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.
+      </description>
+      <arg name="x" type="int"
+           summary="global logical x coordinate of the snap target"/>
+      <arg name="y" type="int"
+           summary="global logical y coordinate of the snap target"/>
+      <arg name="width" type="uint"
+           summary="width of the snap target (0 if no target)"/>
+      <arg name="height" type="uint"
+           summary="height of the snap target (0 if no target)"/>
+    </event>
+
+    <event name="failed">
+      <description summary="snapping failed">
+        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).
+      </description>
+      <arg name="reason" type="uint"
+           enum="treeland_capture_snap_v1.failure_reason"
+           summary="why snapping failed"/>
+    </event>
+  </interface>
+</protocol>