Merge branch 'capture-state' into 'main'

staging: add ext-surface-capture-control protocol

See merge request wayland/wayland-protocols!450

meson.build

@@ -76,6 +76,7 @@ staging_protocols = {
 	'xdg-toplevel-icon': ['v1'],
 	'xdg-toplevel-tag': ['v1'],
 	'xwayland-shell': ['v1'],
+	'ext-surface-capture-control': ['v1'],
 }
 
 experimental_protocols = {

staging/ext-surface-capture-control/README

@@ -0,0 +1,7 @@
+Surface capture control
+
+This protocol allows applications to control and receive notifications about
+screen capture activities affecting their surfaces.
+
+Maintainers:
+YaoBing Xiao <xiaoyaobing@uniontech.com> (@zzxyb)

staging/ext-surface-capture-control/ext-surface-capture-control-v1.xml

@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="ext_surface_capture_control_v1">
+  <copyright>
+    Copyright © 2025 YaoBing Xiao
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="surface capture control and notification">
+    This protocol allows clients to control and receive notifications about
+    screen capture activities affecting their surfaces.
+
+    It provides two main features:
+    1. Capture exclude regions - areas that should not be included in captures
+    2. Capture state notifications - informing clients when their surface is
+       being captured
+
+    This is useful for protecting sensitive content (passwords, private
+    messages, personal information) and allowing applications to adapt their
+    UI when being recorded or shared.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="ext_surface_capture_control_manager_v1" version="1">
+    <description summary="manager for surface capture control">
+      This interface is a factory for ext_surface_capture_control_v1 objects,
+      which provide capture control and notification for individual surfaces.
+    </description>
+
+    <request name="get_surface_capture_control">
+      <description summary="extend surface with capture control">
+        Create a capture control object for a wl_surface. This object provides
+        capture exclusion and state notification capabilities for the surface.
+
+        If a capture control object already exists for the surface, the
+        already_constructed protocol error is raised.
+      </description>
+      <arg name="id" type="new_id" interface="ext_surface_capture_control_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+
+    <enum name="error">
+      <entry name="already_constructed" value="0"
+             summary="surface already has a capture control object"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the manager. This does not affect existing capture control
+        objects.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="ext_surface_capture_control_v1" version="1">
+    <description summary="capture control for a surface">
+      This interface allows clients to control capture behavior and receive
+      notifications about capture activities for a specific surface.
+
+      Capture control state is double-buffered and applied on wl_surface.commit.
+    </description>
+
+    <enum name="capture_state">
+      <description summary="surface capture state">
+        Indicates whether the surface is currently being captured.
+      </description>
+      <entry name="stopped" value="0" summary="no capture activity"/>
+      <entry name="active" value="1" summary="capture is active"/>
+    </enum>
+
+    <request name="set_exclude_region">
+      <description summary="set region to exclude from capture">
+        Set the region of the surface that should be excluded from screen
+        capture and recording. This is useful for protecting sensitive content
+        such as password fields, private messages, or personal information.
+
+        The exclude region is specified in surface-local coordinates.
+
+        The compositor ignores parts of the exclude region that fall outside
+        the surface boundaries.
+
+        This is double-buffered state, see wl_surface.commit.
+
+        Setting a new exclude region replaces the previous one. Setting the
+        region to NULL clears the exclude region (everything can be captured).
+
+        The initial exclude region is empty (nothing is excluded).
+
+        The compositor should respect this region when performing screen
+        capture operations. However, compositors may choose to ignore this
+        request for security, accessibility, or policy reasons (e.g., when
+        screen capture is required by administrators or assistive technologies).
+      </description>
+      <arg name="region" type="object" interface="wl_region" allow-null="true"
+           summary="region to exclude from capture, or null to clear"/>
+    </request>
+
+    <event name="capture_state">
+      <description summary="capture state changed">
+        This event is sent whenever the capture state of the surface changes.
+        It indicates whether the surface is currently being captured (recorded,
+        or shared) by the compositor or client applications.
+
+        This event is sent immediately after the capture control object is
+        created, with the current capture state. Subsequent events are sent
+        whenever the state changes.
+
+        Capturing state is a hint intended to help the client make an informed
+        decision about whether to alert the user.
+
+        Note: This is a best-effort notification. The compositor may not be
+        able to detect all capture activities, especially those performed by
+        external hardware or software outside the compositor's control.
+        Additionally, this event is only sent when the surface is being
+        captured individually (e.g., via ext_image_capture_source_v1). It is
+        not sent when the surface is captured as part of a larger area, such
+        as output or workspace capture.
+      </description>
+      <arg name="state" type="uint" enum="capture_state"
+           summary="current capture state"/>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the capture control object">
+        Destroy the capture control object. Any pending exclude region state
+        is discarded.
+      </description>
+    </request>
+  </interface>
+</protocol>